WaveSight

ESP32 Wi‑Fi CSI radar for human presence & movement detection. Privacy‑first — no cameras, no sensors, just Wi-Fi signal jitter. Real‑time WEB UI dashboard with live RSSI/jitter charts, auto‑calibration, GPIO/LED outputs.

Table of Contents

• Features
• Prerequisites
• Getting Started
  • 1. Clone the Repository
  • 2. Configure the Project
  • 3. Build and Flash Firmware
  • 4. First Boot
• Web Dashboard Overview
• Configuration
• Button Functions
• RGB LED indicator
• Auto Calibration
• Troubleshooting
• Misc

Features

✨ Full Feature List

🧠 Core Radar & Sensing

• Wi‑Fi CSI‑based human detection – uses channel state information jitter, no cameras or additional sensors.
• Presence detection – determines if someone is in the room (configurable timeout).
• Movement detection – real‑time motion sensing with moving‑window filtering.
• Auto‑calibration – learns the empty‑room threshold automatically; takes ~60s.
• GPIO output – dedicated pins for someone and move status to trigger external devices.

🖥️ Web Dashboard

• WEB UI – modern WEB UI interface.
• Live charts – rolling RSSI and Jitter graphs with live numeric values.
• Status tiles – someone presence, movement, RSSI, calibration state.
• Full settings control – Wi‑Fi connection, radar parameters, pin config, LED toggle.
• Responsive design – works on desktop, tablet, and mobile.

🔐 Security & Authentication

• Session‑based login – secure with password (default admin/admin).
• All endpoints protected – denying unauthorised access.

📶 Wi‑Fi Management

• STA mode – connect to your home router with stored credentials.
• Wi‑Fi scan – scan and select networks from the dashboard.
• Auto‑reconnect – background reconnection loop with configurable interval.
• SoftAP fallback – automatically starts a configuration hotspot when no credentials are saved.
• Button‑triggered SoftAP – short button press toggles config mode.

💡 LED & Physical Feedback

• WS2812 RGB LED – visual feedback for different states:
  • Breathing blue – SoftAP/config mode.
  • Breathing purple – no config.
  • Breathing red – disconnected / trying to reconnect.
  • Yellow blink – calibration in progress.
  • Green – movement detected.
  • White – someone present.
• LED on/off control – enable/disable LED.

⚙️ Device Management

• Reboot – from web UI.
• Factory reset – clears all settings (also accessible via long button press).
• Wi‑Fi reset – clears stored credentials only (medium‑long button press).
• Pin configuration – change WS2812, someone, and move GPIOs via UI.

Prerequisites

🪄 Prerequisites Hardware & Software

Hardware

• ESP32 or ESP32‑S2 or ESP32‑S3 or ESP32‑C3 board (tested on ESP32‑S3‑DevKitC‑1)

• Wi‑Fi router (2.4 GHz) – the radar monitors the connection to your access point

• WS2812 (NeoPixel) RGB LED (optional, for status feedback)

  ❗ Notice: Many ESP32 dev boards have a built‑in WS2812 RGB LED.
  you can configure WS2812 on ESP-IDF with idf.py menuconfig command, Component config -> WS2812 RGB LED.

  or edit sdkconfig file with notepad and change WS2812 LED pin CONFIG_WS2812_LED_GPIO=

• Two jumper wire for GPIO outputs (optional, for someone / move external triggers)

Software & Tools

• ESP‑IDF v5.4.4 (recommended) or later
• Python 3.8+ (used by ESP‑IDF build system)

Getting Started

⚙️ Getting Started, Build and Flash

• Install python 3.8+ and ESP‑IDF v5.4.4
• Open ESP‑IDF PowerShell or Command Prompt

1. Clone the Repository

git clone https://github.com/ErfanDL/WaveSight.git

• CD to cloned git

cd WaveSight

2. Configure the Project

Set the chip target – pick the command that matches your board:

Your Board	Command
ESP32	idf.py set-target esp32
ESP32‑S3	idf.py set-target esp32s3
ESP32‑C3	idf.py set-target esp32c3
ESP32‑S2	idf.py set-target esp32s2

3. Build and Flash Firmware

• Connect the ESP32 board to the PC using the USB cable then enter the below command:

idf.py build flash

4. First Boot

the device will start a SoftAP hotspot:

• SSID: WaveSight
• Password: configureme

1. Connect your phone or PC to this Wi‑Fi network.
2. Open a browser and go to http://192.168.4.1.
3. Log in with:
   • Username: admin
   • Password: admin

📶 Connect to Your Home Router

• Still in Settings, click on Scan and select your Wi-Fi router and enter Password.
• Click Connect to Wi‑Fi.
• The device will save the credentials, reboot, and connect to your router.
• After the reboot, find the device’s new IP (from the serial monitor or your router’s client list), open it in a browser, and log in again – you’re all set 🎉

Web Dashboard Overview

📷 Screenshots

   

📱 Mobile UI

   

Configuration

🛜 Wi‑Fi Setup

• Use the Scan button to see nearby networks.
• select your Wi-Fi Network, enter its password, and click Connect to Wi‑Fi.
• The device reboots and joins the selected network.

📡 Radar Settings

• Someone Timeout (seconds) – how long after the last movement the system considers the room empty.
• Move Threshold – jitter value above which movement is detected.
• Filter Window & Filter Count – moving‑window parameters for noise reduction.
• Click Save Radar Settings to apply immediately.

📈 Auto‑Calibration

• The room must be empty.
• Click Start Calibration – the system samples for the set duration (default 60 s) and learns the background threshold.
• The LED blinks yellow during calibration.

📍Pin Configuration

• Change the GPIO pins for the WS2812 LED, someone output, and movement output.
• Click Save Pins – changes take effect after a reboot.

Button Functions

🔘 Button Functions

The physical button (GPIO 0 on most boards, GPIO 8 on ESP32‑C3) works as follows:

Press duration Action

• Short press (< 3 s) Toggle SoftAP configuration mode
• Long press (3‑5 s) Clear Wi‑Fi credentials and reboot
• Very long press (> 5 s) Factory reset (erase all settings) and reboot

RGB LED indicator

💡 LED & Physical Feedback

• WS2812 RGB LED – visual feedback for different states:
  • Breathing blue – SoftAP/config mode.
  • Breathing purple – no config.
  • Breathing red – disconnected / trying to reconnect.
  • Yellow blink – calibration in progress.
  • Green – movement detected.
  • White – someone present.

Auto Calibration

📈 Correct calibration

1. Make sure the room is completely empty – no people or large moving objects.
2. Go to the Dashboard (or Settings → Calibration).
3. Click “Start Calibration”.
   • The LED will start blinking yellow.
   • A countdown timer appears showing the remaining time (60 seconds).
4. Wait until the timer reaches zero. The device automatically:
   • Stops sampling,
   • Calculates the optimal Someone threshold and Move threshold from the background noise,
   • Saves the new values permanently.
5. Once finished, the LED stops blinking and the status returns to “Idle”.

⚠️ Important:

• During calibration, no one should move in the direct line‑of‑sight between the router and the ESP32. Even walking nearby can skew the background measurement.
• For the most accurate results, place the router and the ESP32 at roughly the same height (e.g., on the same desk or shelf). Large height differences may reduce detection sensitivity after calibration.

🔄 Always run calibration after the device has been placed in its final location and connected to the same Wi‑Fi network it will monitor. Moving the router or the ESP32 may require recalibration.

Troubleshooting

⁉️ Troubleshooting

Radar charts show no data?

• Ensure the ESP32 is connected to your Wi‑Fi router (not just the SoftAP). The radar analyses the connection to the access point.

RGB LED not working?

• Verify the WS2812 pin in Settings → Pin Configuration matches your hardware. For the ESP32‑S3‑DevKitC‑1, it should be 48.

  ❗ Notice: Many ESP32 dev boards have a built‑in WS2812 RGB LED.
  you can configure WS2812 on ESP-IDF with idf.py menuconfig command, Component config -> WS2812 RGB LED.

  or edit sdkconfig file with notepad and change WS2812 LED pin CONFIG_WS2812_LED_GPIO=

Can’t access the dashboard after connecting to home Wi‑Fi?

• Check the serial monitor for the assigned IP address, or look at your router’s client list.

Stuck in SoftAP mode?

• A short button press toggles SoftAP on/off. If the device was in SoftAP, pressing the button will exit it and reboot into station mode.

Misc

💲 Donation

If you like my work and want to support me, you can send me a donation via crypto:

Ethereum: 0x283D333C14500dDB93aEE219D2AC1ab3a95ADd5E

Tether USDT (TRC20): TPTeQGyVVjK7yk3jXCqXeDZto38jWVU4v8