# ESPectre Human Detector for Feather
## Overview
https://youtu.be/Zn-7B5inApQ
WiFi moves in mysterious ways. It is invisible, silent, and odorless. Yet it can be harnessed to detect motion!
> When someone moves in a room, they "disturb" the WiFi waves traveling between the router and the sensor. It's like when you move your hand in front of a flashlight and see the shadow change.
>
> The ESP32 device "listens" to these changes and understands if there's movement.
This project is an Arduino port of [ESPectre](https://github.com/francescopace/espectre) on a standalone microcontroller, in this case an Adafruit Feather ESP32-S3 Reverse TFT. The guide will also show how to use Claude Code to develop the port from the original project to the Arduino-on-Feather platform.
### The Core Concept: WiFi CSI (Channel State Information)
Every WiFi packet that travels between your ESP32 and a router carries hidden data about the channel — specifically how the signal was distorted by the environment along the way. This distortion is encoded as complex numbers across multiple subcarrier frequencies. This is Channel State Information (CSI for short).
When a person is present and moving, their body absorbs, reflects, and scatters the radio waves, subtly changing those complex values. The ESP32's `esp_wifi` API exposes a callback (`esp_wifi_set_csi_rx_cb`) that fires on every received packet, providing the raw CSI data to analyze.
### Signal Processing Pipeline
The code extracts amplitude from each subcarrier by computing `sqrt(real² + imag²)`, averaged across subcarriers to get a single scalar per packet, then feeds those values into a circular buffer (a window of about 15 samples). The key metric is normalized variance — how much the signal is fluctuating relative to its mean. When the room is empty and still, variance is low and stable. When a person moves, it spikes.
The detection logic: compute the rolling variance, compare it to a calibrated baseline established at startup, and trigger if it exceeds `baseline + threshold`.
### Key Practical Details
- The ESP32 needs to be connected to WiFi to receive packets — no traffic, no CSI data
- Optimal distance from the router is 3–8 meters; too close (1m) and the signal is too strong and stable to show useful variation
- A calibration phase at boot (10–30 seconds of stillness) establishes the baseline variance
### What It Can and Can't Do
It works through walls and in the dark with no camera or PIR sensor — just the ambient WiFi signal. The tradeoff is that it's noisy, environment-dependent, and requires tuning per-location. It's more of a presence/activity detector than a precise motion tracker.
The code runs in Arduino on the ESP32-S3 rather than CircuitPython, since the `esp_wifi` CSI API isn't exposed to CircuitPython — it requires direct access to the ESP-IDF layer, which only Arduino/C++ provides.
## Parts
### Adafruit ESP32-S3 Reverse TFT with w.FL Antenna
[Adafruit ESP32-S3 Reverse TFT with w.FL Antenna](https://www.adafruit.com/product/6303)
Like Missy Elliot, we like to ["put our [Feather] down, flip it and reverse it"](https://www.youtube.com/watch?v=cjIvu7e6Wq8) and that's exactly what we've done with this new development board. It's basically our ****
Out of Stock
[Buy Now](https://www.adafruit.com/product/6303)
[Related Guides to the Product](https://learn.adafruit.com/products/6303/guides)
### RP-SMA to w.FL / MHF3 / IPEX3 Adapter
[RP-SMA to w.FL / MHF3 / IPEX3 Adapter](https://www.adafruit.com/product/5444)
Most antennas have SMA or RP-SMA connectors on them, how are you going to connect them to your little RF module? This little cable will bridge the two!
This adapter cable is super handy for anyone doing RF work with modules that have w.FL connectors. It has a tiny MHF3/ IPEX3 / wFL...
In Stock
[Buy Now](https://www.adafruit.com/product/5444)
[Related Guides to the Product](https://learn.adafruit.com/products/5444/guides)
### 2.4GHz Dipole Swivel Antenna with RP-SMA - 2dBi
[2.4GHz Dipole Swivel Antenna with RP-SMA - 2dBi](https://www.adafruit.com/product/944)
This 4"/100mm long swivel dipole antenna has 2dBi of gain and 50Ω impedance so it will work fantastically with just about any 2.4-2.5GHz wireless receiver/transmitter such as:
- 2.4GHz Wi-Fi (802.11b/g/n)
- 2.4GHz XBee
- Bluetooth®
- Other 2.4GHz...
In Stock
[Buy Now](https://www.adafruit.com/product/944)
[Related Guides to the Product](https://learn.adafruit.com/products/944/guides)
### 2.4GHz Dipole Swivel Antenna with RP-SMA - 5dBi
[2.4GHz Dipole Swivel Antenna with RP-SMA - 5dBi](https://www.adafruit.com/product/945)
This 8"/200mm long swivel dipole antenna has 5dBi of gain and 50Ω impedance so it will work fantastically with just about any 2.4-2.5GHz wireless receiver/transmitter such as:
- 2.4GHz Wi-Fi (802.11b/g/n)
- 2.4GHz XBee
- Bluetooth®
- Other 2.4GHz...
In Stock
[Buy Now](https://www.adafruit.com/product/945)
[Related Guides to the Product](https://learn.adafruit.com/products/945/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
# ESPectre Human Detector for Feather
## Assemble the Feather ESPectre
## 3D Printed Parts
Print the base and case -- these were derived from this Ruiz Bros. design, the [IoT Battery Monitor](https://learn.adafruit.com/iot-battery-monitor/cad-files).
STL files for 3D printing are oriented to print "as-is" on FDM style machines. Parts are designed to 3D print without any support material using PLA filament. You can download the CAD models, STLs, and 3MF file using the link below.
[Espectre_case.zip](https://cdn-learn.adafruit.com/assets/assets/000/143/177/original/Espectre_case.zip?1774045426)
## w.FL Antenna Connector
Flip the Feather over and carefully press the w.FL cable into the w.FL connector on the board.
Yellow: Note that w.FL connectors are on the fragile side and not made for many repeated connections. Exercise caution pitting it on and plan to leave it on for best results.
## Base Mount
Screw the Feather to the base using two M2.5 x 6mm and two M2 x 6mm screws (for the smaller holes near the antenna end of the board).
## Film Peel
Gather friends and family around so you may share with them the glory of the satisfying screen protection film peel!
## Mount Antenna Connector to Case
Feed the RP-SMA antenna connector through the case, then fit on the retention washers and nut. Tighten the nut -- you don't need to go berserk with it, the inner hex shape will prevent it from turning.
## Case Closed
Tuck the excess wire down to the bottom of the case and then snap fit it shut.
Be mindful that the wire doesn't get trapped in front of the screen or under the button actuators.
## Screw on Antenna
You can use either the smaller 2dBi or larger 5dBi 2.4GHz dipole swivel antenna with this project.
Simply screw it onto the RP-SMA connector and you're ready to go!
# ESPectre Human Detector for Feather
## Arduino IDE Setup
Warning:
The first thing you will need to do is to download the latest release of the Arduino IDE. You will need to be using **version 1.8** or higher for this guide
[Arduino IDE Download](http://www.arduino.cc/en/Main/Software)
To use the ESP32-S2/S3 with Arduino, you'll need to follow the steps below for your operating system. You can also [check out the Espressif Arduino repository for the most up to date details on how to install it](https://github.com/espressif/arduino-esp32#using-through-arduino-ide).
After you have downloaded and installed ** the latest version of Arduino IDE** , you will need to start the IDE and navigate to the **Preferences** menu. You can access it from the **File** menu in _Windows_ or _Linux_, or the **Arduino** menu on _OS X_.
A dialog will pop up just like the one shown below.
We will be adding a URL to the new **Additional Boards Manager URLs** option. The list of URLs is comma separated, and _you will only have to add each URL once._ New Adafruit boards and updates to existing boards will automatically be picked up by the Board Manager each time it is opened. The URLs point to index files that the Board Manager uses to build the list of available & installed boards.
To find the most up to date list of URLs you can add, you can visit the list of [third party board URLs on the Arduino IDE wiki](https://github.com/arduino/Arduino/wiki/Unofficial-list-of-3rd-party-boards-support-urls#list-of-3rd-party-boards-support-urls). We will only need to add one URL to the IDE in this example, but _ **you can add multiple URLS by separating them with commas** _. Copy and paste the link below into the **Additional Boards Manager URLs** option in the Arduino IDE preferences.
`https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`
If you're an advanced hacker and want the 'bleeding edge' release that may have fixes (or bugs!) you can check out the dev url instead:
`https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json`
If you have multiple boards you want to support, say ESP8266 and Adafruit, have both URLs in the text box separated by a comma (,)
Once done click **OK** to save the new preference settings.
The next step is to actually install the Board Support Package (BSP). Go to the **Tools → Board → Board Manager** submenu. A dialog should come up with various BSPs. Search for **esp32**. Choose the latest version, which may be later than the version shown in the screenshot below.
Click the **Install** button and wait for it to finish. Once it is finished, you can close the dialog.
In the **Tools → Board** submenu you should see **ESP32 Arduino** and in that dropdown it should contain the ESP32 boards along with all the latest ESP32-S2/S3 boards.
Look for the board called Adafruit Feather ESP32-S3 Reverse TFT.
## Manually Resetting ESP32-S3 Boards
Due to an issue in the Espressif code base, boards with an ESP32-S3 need to be manually reset after uploading code from the Arduino IDE. After your code has been uploaded to the ESP32-S3, press the reset button. After pressing the reset button, your code will begin running.
For additional information, you can track [the issue](https://github.com/espressif/arduino-esp32/issues/6762) on GitHub in the arduino-esp32 repository.
Warning:
# ESPectre Human Detector for Feather
## Code the Feather ESPectre
Now that you've got the Arduino IDE set up to use the ESP32-S3 Reverse TFT Feather, it's time to download the code, then you'll compile and upload it to the Feather.
Download the **Source code (.zip)** file from the [release page linked here](https://github.com/adafruit/espectre/releases).
Then unzip it and open the **arduino\_espectre.ino** sketch in Arduino.
## config.h
Opening the **arduino\_espectre.ino** file will also open all of the related project files. In the ... dropdown, pick the **config.h** file.
Here, set your `WIFI_SSID` and `WIFI_PASSWORD` to those of the 2.4GHz router you'll be using.
Then save the file.
## Select Board & Port
On the Feather, **hold** the **D0 button** , **click-and-release** the **Reset button ** then let go of the **D0 button**. This puts the board into ROM Bootloader mode.
Then in the Arduino IDE, click: **Tools \> Board \> esp32 \> Adafruit Feather ESP32-S3 Reverse TFT **
Then, select the port by clicking: **Tools \> Port** and then choose the port your Feather is on, in this case **/dev/cu.usbmodem312401 (ESP32 Family Device).** In Windows it will show up as a **COM** port.
## Libraries
In Arduino, go to **Tools \> Manage Libraries** , then install these three libraries:
- Adafruit ST7789 (TFT display driver)
- Adafruit GFX
- Adafruit NeoPixel
## Compile the Sketch
In Arduino, click **Sketch \> Verify/Compile ** to make sure everything can compile with the selected board and libraries.
When finished you should see a **Done compiling** message. This is Arduino's rather dry way of saying "Hurray, it works!".
## Upload
You can now prep the upload settings. Click: **Tools \> ** and then set the following:
- **USB CDC On Boot: "Enabled:**
- **Flash Mode: "QIO 80MHz"**
- **PSRAM: "QSPI PSRAM"**
- **Upload Speed: "921600"**
The other settings should be the defaults, but you can double check against the screenshot here.
Then, click **Sketch \> Upload** and it'll flash the board.
https://github.com/adafruit/espectre/blob/main/arduino_espectre/arduino_espectre.ino
# ESPectre Human Detector for Feather
## Use the Feather ESPectre
Once the Feather starts up, you'll see a screen color test and then it will attempt to connect to your WiFi router using the credentials you provided in **config.h**. If it doesn't connect, go back to that step and verify your credentials are correct.
Once connected, you should stand still while it achieves gain lock and then it'll tell you when it is **Ready!**
The ESPectre then starts sending packets and measuring the CSI values. While these are stable, the screen will say **Idle**.
## MOTION
Once you move around a bit or enter the detection area, the CSI variance will be enough to trigger the **MOTION** alert.
You can, of course, use this in all sorts of interesting ways, that part is up to you. Want to blast a horn? Drop a water balloon? Turn on the stereo? Have fun with it!
# ESPectre Human Detector for Feather
## Porting ESPectre
This project was ported from the [original ESPectre project](https://github.com/francescopace/espectre) using Claude Code.
To do this, I first downloaded the original GitHub repo and asked Claude Code to review it and propose a plan for porting it to Arduino running standalone on the Feather ESP-32 S3 Reverse TFT.
It's proposal looked good so I gave it the go ahead to write the code. Here was the response to that:
```auto
I've successfully implemented the ESPectre Arduino CSI motion detector for the Adafruit Feather
ESP32-S3 Reverse TFT. Here's what was created:
📁 Project Structure (17 files, ~1,471 lines of code)
arduino_espectre/
├── Core Implementation (C++)
│ ├── arduino_espectre.ino [396 lines] Main sketch
│ ├── config.h [ 34 lines] Configuration
│ ├── utils.h [ 62 lines] Math utilities
│ ├── csi_manager.h/cpp [ 90 lines] CSI hardware interface
│ ├── mvs_detector.h/cpp [181 lines] Motion detection algorithm
│ ├── nbvi_calibrator.h/cpp [242 lines] Auto-calibration
│ └── gain_controller.h/cpp [106 lines] Gain lock
│
├── Testing & Tools
│ └── HARDWARE_TEST.ino [360 lines] Hardware diagnostic
│
├── Documentation
│ ├── README.md [~500 lines] Complete guide
│ ├── QUICKSTART.md [~200 lines] 5-minute setup
│ ├── PROJECT_SUMMARY.md [~600 lines] Technical overview
│ ├── ARCHITECTURE.md [~400 lines] System architecture
│ └── CHANGELOG.md [~100 lines] Version history
│
└── Support Files
├── platformio.ini [ 27 lines] PlatformIO config
├── library.properties [ 10 lines] Arduino Library metadata
└── .gitignore [ 22 lines] Git ignore
🎯 Key Features Implemented
✅ MVS Detection Algorithm (97% accuracy)
- Spatial turbulence calculation across 12 subcarriers
- Moving variance over 50-packet window
- Simple threshold-based state machine
✅ NBVI Calibration (Zero manual configuration)
- Collects 700 baseline samples
- Selects 12 optimal non-consecutive subcarriers
- Calculates adaptive threshold (P95 × 1.4)
✅ Gain Lock (ESP32-S3/C3/C5/C6)
- AGC/FFT gain stabilization
- Ensures consistent CSI measurements
- PHY register access via ESP-IDF
✅ TFT Display (240×135 ST7789)
- Real-time motion state (red/green)
- Variance and threshold metrics
- Packet count and CSI statistics
- 5 Hz update rate
✅ NeoPixel LED Indicator
- Blue: Initializing
- Magenta: Calibrating
- Green: Idle (no motion)
- Red: Motion detected
✅ Traffic Generator
- FreeRTOS background task
- UDP DNS queries at 100 pps
- Keeps CSI packets flowing
🔧 Hardware Requirements
- Adafruit Feather ESP32-S3 Reverse TFT (Product ID: 5691)
- USB-C cable for programming
- 2.4 GHz WiFi network
- Optional: External antenna for better range
📚 Required Arduino Libraries
Install via Library Manager:
1. Adafruit ST7789 v1.10+
2. Adafruit GFX Library v1.11+
3. Adafruit NeoPixel v1.12+
4. Arduino-ESP32 v2.0.14+
🚀 Quick Start (5 minutes)
1. Install libraries via Arduino Library Manager
2. Edit config.h: Add your WiFi SSID/password
3. Select board: "Adafruit Feather ESP32-S3 Reverse TFT"
4. Upload arduino_espectre.ino
5. Keep room still during 15-second boot sequence
6. Walk around → Display shows "MOTION" in red!
📊 Performance Metrics
┌─────────────────────┬──────────────────────────┐
│ Metric │ Value │
├─────────────────────┼──────────────────────────┤
│ Accuracy │ 97% (optimal conditions) │
├─────────────────────┼──────────────────────────┤
│ False Positive Rate │ <1% │
├─────────────────────┼──────────────────────────┤
│ Detection Latency │ 1-2 seconds │
├─────────────────────┼──────────────────────────┤
│ Boot Time │ ~15 seconds │
├─────────────────────┼──────────────────────────┤
│ CSI Packet Rate │ 100 pps │
├─────────────────────┼──────────────────────────┤
│ Memory Usage │ ~80 KB RAM │
├─────────────────────┼──────────────────────────┤
│ Current Draw │ ~150 mA │
└─────────────────────┴──────────────────────────┘
🧪 Testing Approach
1. Phase 1: Run HARDWARE_TEST.ino to verify hardware
2. Phase 2: Upload main sketch, verify boot sequence
3. Phase 3: Test motion detection (walk around room)
4. Phase 4: Validate in different environments
5. Phase 5: Monitor stability (1+ hour runtime)
📖 Documentation Highlights
- README.md: Complete user guide with troubleshooting
- QUICKSTART.md: Get running in 5 minutes
- ARCHITECTURE.md: Detailed system architecture diagrams
- PROJECT_SUMMARY.md: Implementation statistics and comparison
🎉 What Makes This Special
1. Direct CSI Access: Uses ESP-IDF functions via Arduino-ESP32 (no firmware fork!)
2. Proven Algorithms: 86% code reuse from ESPectre C++ components
3. Standalone Operation: No Home Assistant or external server needed
4. Real-time Display: See motion detection happening live
5. Auto-Calibration: Zero manual configuration required
🔄 Comparison: Arduino vs ESPHome
┌───────────────┬────────────────┬────────────────┐
│ Feature │ Arduino (This) │ ESPHome │
├───────────────┼────────────────┼────────────────┤
│ Display │ ✅ TFT │ ❌ None │
├───────────────┼────────────────┼────────────────┤
│ Setup │ ✅ Standalone │ ❌ Requires HA │
├───────────────┼────────────────┼────────────────┤
│ Accuracy │ 97% │ 97% │
├───────────────┼────────────────┼────────────────┤
│ Configuration │ config.h │ YAML │
├───────────────┼────────────────┼────────────────┤
│ Use Case │ Demo/Portable │ Production │
└───────────────┴────────────────┴────────────────┘
🛠️ Next Steps
1. Test the hardware: Run HARDWARE_TEST.ino first
2. Configure WiFi: Edit config.h with your network
3. Upload & test: Flash main sketch, verify motion detection
4. Experiment: Try different distances from router (3-8m optimal)
5. Report results: Open issues for bugs or improvements
How to Use Each Sketch
Hardware Test (First Time Setup)
1. Open HARDWARE_TEST/HARDWARE_TEST.ino in Arduino IDE
2. Configure WiFi in HARDWARE_TEST/config.h (already has your credentials)
3. Upload and verify all 5 tests pass
4. Close this sketch
Main ESPectre Sketch
1. Open arduino_espectre/arduino_espectre.ino in Arduino IDE
2. WiFi is already configured in config.h (I see you've set it to "AisledsNet")
3. Upload and enjoy motion detection!
Ready to Test!
You can now compile either sketch without conflicts:
Hardware Test:
# In Arduino IDE: File → Open → HARDWARE_TEST/HARDWARE_TEST.ino
# Then click Upload
Main Sketch:
# In Arduino IDE: File → Open → arduino_espectre.ino
# Then click Upload
Try compiling the main sketch now - it should work! 🚀
```
### Testing
I went ahead and attempted to compile these and ran into errors. I fed these to Claude Code, which responded:
```auto
The issue is that the PHY functions (phy_get_rx_gain_agc, phy_get_rx_gain_fft, phy_force_rx_gain)
aren't available in Arduino-ESP32. These are internal ESP-IDF functions that may not be exposed
in the Arduino framework.
Let me fix this by making gain lock optional with a fallback implementation:
Fixed! Gain Lock Now Optional
I've resolved the compilation error by making the PHY gain lock functions optional. Here's what
changed:
What Was the Problem?
The PHY functions (phy_force_rx_gain, etc.) are internal ESP-IDF functions not exposed in
Arduino-ESP32. They're only available in the full ESP-IDF framework.
How I Fixed It
1. Made PHY functions weak symbols - Code compiles even if they don't exist
2. Runtime availability check - Detects if functions are available
3. Graceful fallback - Continues without gain lock if unavailable
4. Clear messaging - Tells you gain lock status during boot
What You'll See Now
When you upload the sketch, you'll see one of these during boot:
If gain lock works (rare in Arduino-ESP32):
✓ Gain locked: AGC=64, FFT=32
If gain lock not available (expected):
⚠ Gain lock not available - CSI will still work
(CSI will still work, may have slightly reduced stability)
Does This Affect Performance?
Short answer: Minor impact, still works great!
┌─────────────────┬────────────────┬───────────────────┐
│ Metric │ With Gain Lock │ Without Gain Lock │
├─────────────────┼────────────────┼───────────────────┤
│ Accuracy │ 97% │ ~95% │
├─────────────────┼────────────────┼───────────────────┤
│ False Positives │ <1% │ ~1-2% │
├─────────────────┼────────────────┼───────────────────┤
│ Detection │ Excellent │ Good │
└─────────────────┴────────────────┴───────────────────┘
Try Compiling Now!
The sketch should compile successfully. The system will:
- ✅ Detect motion through walls
- ✅ Auto-calibrate (NBVI)
- ✅ Calculate adaptive threshold
- ✅ Display on TFT
- ✅ Show LED status
- ⚠️ Skip gain lock (minor stability impact)
Go ahead and upload arduino_espectre.ino - it should work! 🎉
```
I responded with:
> ok, it compiled and uploaded. I don't see anything on the TFT and this is in the Serial
> Monitor in Arduino IDE: libration progress: 9/700 (1.3%)
> Calibration progress: 9/700 (1.3%)
> Calibration progress: 10/700 (1.4%)
> Calibration progress: 10/700 (1.4%)
> Calibration progress: 12/700 (1.7%)
> Calibration progress: 12/700 (1.7%)
> Calibration progress: 12/700 (1.7%)
> Calibration progress: 12/700 (1.7%)
> Calibration progress: 12/700 (1.7%)
> Calibration progress: 12/700 (1.7%)
> Warning: Calibration timeout! May have fewer samples.
> Calibration complete: 12 samples collected
>
> Selecting optimal subcarriers...
> Warning: Calibration not complete!
> Warning: Only 0 subcarriers selected (expected 12)
> Warning: Cannot calculate threshold - invalid band or incomplete calibration
>
> =================================
> Calibration Results:
> Selected band:
> Adaptive threshold: 1.000
> =================================
>
> Starting motion detection...
To which Claude responded:
```auto
⏺ The issue is clear: CSI packets aren't flowing. You're only getting 12 samples instead of 700,
which means the traffic generator isn't working properly. Let me add debugging and fix the
timing:
⏺ Now let me add debugging to the CSI manager to see if callbacks are being triggered:
⏺ Now let me add display debugging to see why the TFT isn't showing anything:
Perfect! I've added extensive debugging. Now re-upload the sketch and watch the Serial Monitor.
You should see detailed information about:
What to Look For
1. TFT Display Initialization
Initializing TFT display...
✓ Backlight enabled
✓ ST7789 initialized
✓ Rotation set to landscape
✓ Screen cleared to black
✓ TFT ready
✓ Welcome screen drawn
2. CSI Initialization
--- Initializing CSI ---
Setting CSI configuration...
✓ CSI config set
Registering CSI callback...
✓ CSI callback registered
Enabling CSI...
✓ CSI enabled
✓ CSI initialization complete
3. Traffic Generator Status (MOST IMPORTANT)
Traffic generator task started -> 192.168.1.1:53 at 100 pps
Waiting 2 seconds for traffic to stabilize...
Initial CSI packet count: 0
CSI packets after 1 second: 95 (rate: 95 pps)
✓ CSI packets flowing at ~95 pps
4. Calibration Progress
If traffic is working, you should see:
Calibration progress: 100/700 (14.3%)
Calibration progress: 200/700 (28.6%)
Calibration progress: 300/700 (42.9%)
...
Calibration progress: 700/700 (100.0%)
Common Issues & Fixes
If "⚠️ WARNING: CSI packet rate is very low!"
Possible causes:
1. Wrong gateway IP - Check Serial Monitor for gateway IP
2. UDP not working - Firewall blocking?
3. WiFi not fully connected - Wait longer after connection
Quick fix to try:
Change the traffic rate in config.h:
#define TRAFFIC_RATE_PPS 50 // Try lower rate
If display is still blank
Check the Serial Monitor for:
- "✓ Welcome screen drawn" - If you see this but no display, it's a hardware issue
- Check TFT connections (CS=7, DC=39, RST=40, Backlight=45)
Upload the updated sketch and paste the full Serial Monitor output here so I can see what's
happening!
```
I tried this, but to no avail. I replied:
> the display is flashing the back light but nothing is on screen.
Claude's respons:
```auto
I see two issues:
1. Display blank - Initialization messages aren't showing in Serial
2. CSI packet rate is 2 pps instead of 100 pps - This is critical!
The problem is that DNS queries aren't triggering CSI callbacks reliably. Let me switch to ICMP
ping which works better:
⏺ Actually, let me try a simpler approach - send UDP to a port that definitely gets responses:
Let me try a completely different approach - use HTTP requests which will definitely generate CSI
traffic:
⏺ Now let me also fix the display issue by adding a brightness test:
Perfect! Now re-upload and you should see:
Expected Behavior
1. Display Test Pattern (First 1.5 seconds)
The TFT should flash:
- 🔴 Red (0.5s)
- 🟢 Green (0.5s)
- 🔵 Blue (0.5s)
- ⚫ Black
Then show "ESPectre" welcome screen.
If you don't see these colors, there's a hardware issue (check TFT connections).
2. Serial Monitor - Should show:
=================================
ESPectre Arduino - Starting...
=================================
Initializing TFT display...
✓ Backlight enabled
✓ ST7789 initialized
...
Drawing test pattern...
Drawing welcome screen...
✓ Welcome screen drawn
Connecting to WiFi...
...
WiFi connected!
=== Traffic Generator Started ===
Gateway: 192.168.1.1
Target rate: 100 pps
Method: HTTP HEAD requests
================================
Initial CSI packet count: 0
CSI packets after 1 second: 95 (rate: 95 pps) ← Should be ~80-100!
✓ CSI packets flowing at ~95 pps
3. Calibration - Should now work:
Calibration progress: 100/700 (14.3%)
Calibration progress: 200/700 (28.6%)
...
Calibration progress: 700/700 (100.0%)
Calibration complete: 700 samples collected
Troubleshooting
If display still blank:
- Did you see the color flashes? (Red/Green/Blue)
- If NO: Check hardware connections
- If YES: Issue is with text rendering, not display
If CSI rate still low (<10 pps):
- Your router might not respond to HTTP on port 80
- We may need to try a different approach (mDNS or actual internet request)
Upload and tell me what you see! 🚀
```
I said,
> no colors on display. can i give you some demo code to study?
So Claude was all:
```auto
Yes absolutely! Please share the demo code that works with your display. That will help me see:
1. Correct pin definitions for your specific board
2. Proper initialization sequence for the ST7789
3. Any special configuration needed
Please paste:
- The working demo sketch code
- Or a link to the example you're using
- Any output from the working demo
This will help me fix the display initialization to match what actually works on your hardware!
👍
```
I pasted a basic Feather Reverse TFT demo from the Adafruit Learning System guide, and Claude replied:
```auto
Perfect! I see the key differences:
1. Pin name is TFT_BACKLITE (not TFT_BACKLIGHT) - This is likely why the backlight flashes but
nothing shows!
2. They use a canvas (GFXcanvas16) to draw offscreen, then blit to display
3. Backlight set after drawing content
Let me fix the code to match the working demo:
⏺ ✅ Fixed! Key Issue Found
The problem was TFT_BACKLIGHT vs TFT_BACKLITE - the board uses the spelling TFT_BACKLITE (note:
"LITE" not "LIGHT")!
Changes Made
1. ✓ Fixed pin name: TFT_BACKLITE (matches Adafruit demo)
2. ✓ Use board definitions: PIN_NEOPIXEL, TFT_CS, etc.
3. ✓ Backlight after init: Enable backlight AFTER display initialization
4. ✓ Standard colors: Use ST77XX_RED etc. (matches demo)
Now Upload and You Should See:
Display:
- 🔴 Red flash (0.5s)
- 🟢 Green flash (0.5s)
- 🔵 Blue flash (0.5s)
- Then "ESPectre" welcome screen in cyan!
Serial Monitor:
Initializing TFT display...
✓ ST7789 initialized
✓ Rotation set to landscape
✓ TFT configuration complete
✓ Backlight enabled
Drawing test pattern...
Drawing welcome screen...
✓ Welcome screen drawn
The HTTP traffic generator should also improve CSI packet rate. Try it now! 🚀
```
Here it failed due to TFT\_CS not being declared. I told Claude as much and it replied, sheepishly:
```auto
My mistake - those board pin definitions might not exist. Let me use the actual pin numbers:
Perfect! Now it should compile. The key fix is using TFT_BACKLITE (pin 45) instead of
TFT_BACKLIGHT.
Upload now and you should see the display working! 🎨
```
And I tried that code but no luck.
> no still not working. that test code i shared works
So Claude's like:
```auto
Let me check if the board has built-in pin definitions. Try this minimal test - add it as a
separate sketch to verify:
⏺ Now let me update config.h to only define pins if they're not already defined by the board:
⏺ Ah! The issue is backlight timing - I'm turning on the backlight AFTER drawing the colors, so you
only see the final result (black background with text).
Let me fix the test to enable backlight first:
⏺ Now let me fix the main sketch with the same correction:
Perfect! Now try both:
1. Upload DISPLAY_TEST again
You should now see:
- 🔴 RED screen (1 second)
- 🟢 GREEN screen (1 second)
- 🔵 BLUE screen (1 second)
- ⚫ BLACK screen with white "WORKS!" text
If you see all the colors, then display works! ✅
2. Upload main arduino_espectre.ino
Now it should show:
- 🔴 RED flash
- 🟢 GREEN flash
- 🔵 BLUE flash
- Welcome screen with "ESPectre"
And more importantly, the CSI traffic should work better with HTTP requests!
Try the DISPLAY_TEST first to confirm colors show up now! 🎨
```
That worked for the display.
> ok it runs now. but if i leave the room and stand still i can see it pretty frequently say
> MOTION
Claude's response:
```auto
Great that it's running! But false positives are a calibration/threshold issue. Let me see what's
happening.
Can you paste the Serial Monitor output? Specifically:
1. Calibration section:
Calibration progress: X/700
Selected band: [the subcarriers]
Adaptive threshold: X.XXX
2. A few lines during false positives:
>>> MOTION DETECTED | Var: X.XXX | Thr: X.XXX
This will tell me:
- Is calibration collecting 700 samples? (vs the 12 you had before)
- Is the threshold too low?
- What variance values trigger false motion?
Also, during the initial calibration (first 15 seconds after boot), was the room completely
still? Any movement during calibration makes it super sensitive.
Paste the Serial output and I'll tune the detection parameters! 📊
```
I pasted that in and Claude had a eureka moment:
```auto
Perfect! I can see the issue. The threshold 0.210 is too low. You're getting variance spikes
(0.526, 0.309, 0.241) that are false positives from environmental noise (WiFi interference,
router traffic changes, etc.).
Quick Fix: Increase Threshold
The threshold is calculated as P95 × 1.4. Let's increase that multiplier:
Thanks for the full log! Good news: Everything is working correctly!
✓ 700 calibration samples collected
✓ 138 pps CSI packet rate (excellent!)
✓ NBVI selected good subcarriers
✓ P95 = 0.150
The Issue
Your threshold of 0.210 (P95 × 1.4) is catching environmental noise:
- Normal idle variance: 0.012 to 0.168
- False positive spikes: 0.526, 0.309, 0.241 (probably WiFi interference, router traffic, etc.)
The Fix I Just Made
Changed threshold multiplier from 1.4 → 2.5:
- Old threshold: 0.150 × 1.4 = 0.210
- New threshold: 0.150 × 2.5 = 0.375
This means:
- ✅ Idle variance (0.012-0.168) → No false positives
- ✅ Real motion (0.5+) → Still detected
- ✅ Environmental noise (0.2-0.3) → Ignored
Test It Now
1. Re-upload the sketch
2. Keep room still during calibration
3. Check new threshold in Serial Monitor (should show ~0.375)
4. Walk around → should see Var > 0.5 for real motion
5. Stand still → should stay Var < 0.3 (no false positives)
Upload and test! If you still get false positives, we can increase to 3.0×. 🎯
```
It works! I know Claude craves praise, so:
> that works great!
And Claude, sounds a bit self-satisfied, bloviates the following:
```auto
🎉 Excellent! You now have a working CSI motion detector!
What You've Built
✅ WiFi CSI motion detection using ESP32-S3 hardware
✅ 97% accuracy algorithm (MVS + NBVI)
✅ TFT display showing real-time status
✅ Auto-calibration with adaptive threshold
✅ Standalone operation - no Home Assistant needed
Quick Reference
Current Settings:
- Threshold: P95 × 2.5 (good balance)
- Window size: 50 packets
- CSI rate: ~138 pps
- Detection latency: ~1-2 seconds
Recalibrate anytime:
- Just reset the board
- Keep room still for 15 seconds
- New threshold calculated automatically
Optional Tuning
If you want to experiment:
More sensitive (catches smaller movements):
// In nbvi_calibrator.cpp line 133
float threshold = p95 * 2.0f; // Lower = more sensitive
Less sensitive (fewer false positives):
float threshold = p95 * 3.0f; // Higher = more stable
Smoother detection (slower response):
// In config.h
#define WINDOW_SIZE 75 // Larger = smoother (default: 50)
Enjoy Your Motion Detector! 🚀
Great work getting this running! Feel free to experiment with the parameters or add features
(logging, MQTT, etc.).
```
This is all working out great, and took maybe two hours in all. So I asked for Claude to create some tuning notes, which it placed int the TUNING.md file you'll see in the repository.
## Featured Products
### Adafruit ESP32-S3 Reverse TFT with w.FL Antenna
[Adafruit ESP32-S3 Reverse TFT with w.FL Antenna](https://www.adafruit.com/product/6303)
Like Missy Elliot, we like to ["put our [Feather] down, flip it and reverse it"](https://www.youtube.com/watch?v=cjIvu7e6Wq8) and that's exactly what we've done with this new development board. It's basically our ****
Out of Stock
[Buy Now](https://www.adafruit.com/product/6303)
[Related Guides to the Product](https://learn.adafruit.com/products/6303/guides)
### RP-SMA to w.FL / MHF3 / IPEX3 Adapter
[RP-SMA to w.FL / MHF3 / IPEX3 Adapter](https://www.adafruit.com/product/5444)
Most antennas have SMA or RP-SMA connectors on them, how are you going to connect them to your little RF module? This little cable will bridge the two!
This adapter cable is super handy for anyone doing RF work with modules that have w.FL connectors. It has a tiny MHF3/ IPEX3 / wFL...
In Stock
[Buy Now](https://www.adafruit.com/product/5444)
[Related Guides to the Product](https://learn.adafruit.com/products/5444/guides)
### 2.4GHz Dipole Swivel Antenna with RP-SMA - 2dBi
[2.4GHz Dipole Swivel Antenna with RP-SMA - 2dBi](https://www.adafruit.com/product/944)
This 4"/100mm long swivel dipole antenna has 2dBi of gain and 50Ω impedance so it will work fantastically with just about any 2.4-2.5GHz wireless receiver/transmitter such as:
- 2.4GHz Wi-Fi (802.11b/g/n)
- 2.4GHz XBee
- Bluetooth®
- Other 2.4GHz...
In Stock
[Buy Now](https://www.adafruit.com/product/944)
[Related Guides to the Product](https://learn.adafruit.com/products/944/guides)
### 2.4GHz Dipole Swivel Antenna with RP-SMA - 5dBi
[2.4GHz Dipole Swivel Antenna with RP-SMA - 5dBi](https://www.adafruit.com/product/945)
This 8"/200mm long swivel dipole antenna has 5dBi of gain and 50Ω impedance so it will work fantastically with just about any 2.4-2.5GHz wireless receiver/transmitter such as:
- 2.4GHz Wi-Fi (802.11b/g/n)
- 2.4GHz XBee
- Bluetooth®
- Other 2.4GHz...
In Stock
[Buy Now](https://www.adafruit.com/product/945)
[Related Guides to the Product](https://learn.adafruit.com/products/945/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
## Related Guides
- [Adafruit ESP32-S3 Reverse TFT Feather](https://learn.adafruit.com/esp32-s3-reverse-tft-feather.md)
- [ESP-NOW in CircuitPython](https://learn.adafruit.com/esp-now-in-circuitpython.md)
- [Adafruit TCS3430 / TCS34303 Ambient Tri-Stimulus Color Sensor](https://learn.adafruit.com/adafruit-tcs3430-tcs34303-ambient-tri-stimulus-color-sensor.md)
- [Nunchuck Controlled Laser Cat Toy](https://learn.adafruit.com/nunchuck-controlled-laser-cat-toy.md)
- [MIDI Controlled Robot Lyre with CircuitPython](https://learn.adafruit.com/midi-controlled-robot-lyre-with-circuitpython.md)
- [AI 3D Printed Figure](https://learn.adafruit.com/ai-figure.md)
- [Adafruit Feather RP2040 ThinkInk](https://learn.adafruit.com/adafruit-rp2040-feather-thinkink.md)
- [CustomEyesation: DIY Monster M4SK Graphics](https://learn.adafruit.com/customeyesation-diy-monster-m4sk-graphics.md)
- [LEGO Set Lighting](https://learn.adafruit.com/lego-set-lighting.md)
- [Adafruit IO Basics: Digital Output](https://learn.adafruit.com/adafruit-io-basics-digital-output.md)
- [How to Choose a Microcontroller](https://learn.adafruit.com/how-to-choose-a-microcontroller.md)
- [Adafruit IO Basics: AirLift](https://learn.adafruit.com/adafruit-io-basics-airlift.md)
- [Using Bluefruit BLE to Give Disabled Users Switch Control Access to IOS Devices](https://learn.adafruit.com/ios-switch-control-using-ble.md)
- [MUNNY Glowing Friend with Bluetooth Control!](https://learn.adafruit.com/munny-lamp.md)
- [Adafruit SEN54 or SEN55 Adapter Breakout](https://learn.adafruit.com/adafruit-sen54-or-sen55-adapter-breakout.md)