Getting Started

Getting Started

This page walks you from "I bought the parts" to "lights are following me through the hallway" in about 30 minutes.

What you need

Part	Notes
ESP32-C3 SuperMini	The v6.x reference board. ~$3 on AliExpress / Amazon.
HiLink LD2450	24 GHz mmWave radar with 3-target tracking and x/y/speed output. ~$15.
WS2812 / NeoPixel LED strip	60 LEDs/m or 30 LEDs/m, 5 V. Length depends on your install.
5 V DC power supply	Sized for the LED strip — 60 mA per LED at full white. A 5 V / 5 A PSU runs ~80 LEDs at full brightness comfortably.
Wires + JST connector	For LED-strip data + power injection.
(Optional) Pushbutton	Momentary, for factory-reset (reserved for v6.1).

Why this combo? The C3 is single-core but with v6.x's single-sensor architecture (no peer broadcast, no second sensor to fuse) it has plenty of headroom. The LD2450 is the only radar v6.x ships — its (x, y, speed) target stream covers L-shape and U-shape geometries from one sensor at the geometric vantage point. See FAQ for the full reasoning.

Step 1 — Flash the firmware

Option A: pre-built binaries (easiest)

1. Download all 4 .bin files from the v6.1.0-alpha.1 release page.
2. Install esptool: pip install esptool
3. Connect your C3 to your computer via USB.
4. Find the port:
   • macOS: ls /dev/cu.usbmodem*
   • Linux: ls /dev/ttyUSB* /dev/ttyACM*
   • Windows: check Device Manager → Ports
5. Flash:

python -m esptool --chip esp32c3 -p <PORT> -b 460800 \
    --before default_reset --after hard_reset write_flash \
    --flash_mode dio --flash_size 4MB --flash_freq 80m \
    0x0     bootloader-c3-v6.1.0-alpha.1.bin \
    0x8000  partition-table-c3-v6.1.0-alpha.1.bin \
    0xd000  ota-data-initial-c3-v6.1.0-alpha.1.bin \
    0x10000 ambisense-c3-v6.1.0-alpha.1.bin

If esptool errors with Failed to connect to ESP32-C3: No serial data received, do the BOOT-mode dance: hold BOOT, tap RST while still holding, release BOOT after ~1 s, retry. See Troubleshooting for the full ladder.

Option B: build from source

You need ESP-IDF v5.5.2 installed (recommended path: ~/esp/esp-idf-v5.5.2/):

git clone https://github.com/Techposts/AmbiSense.git
cd AmbiSense
git checkout v6-idf-rewrite          # development branch with v6.x

cd firmware
. ~/esp/esp-idf-v5.5.2/export.sh
idf.py set-target esp32c3
idf.py -p <PORT> build flash monitor

The monitor command shows the serial log — useful first time to confirm the device is booting, picking up the C3 SuperMini board profile, and starting Wi-Fi.

Step 2 — Wire the radar and one LED to test

Bare-minimum bench wiring before you commit to a final install:

ESP32-C3 SuperMini      LD2450
------------------      ------
GPIO 20 (radar_rx) ←──── TX
GPIO 21 (radar_tx) ────→ RX
5V                ────→ VCC
GND               ──── GND

ESP32-C3                 WS2812 strip (5V data)
--------                 ----------------------
GPIO 10                ─→ DIN
                  + 5 V → VCC (from the LED PSU, NOT the C3)
                    GND ─ GND (common ground with C3 + radar)

Why these pin defaults: they match the C3 SuperMini board profile shipped in the firmware. If you change pins later via the web UI, the unsafe-pin guard will refuse strapping / USB-JTAG / flash GPIOs (9, 11–19) so you can't accidentally brick boot.

See Hardware Setup for the full wiring diagram including power injection on long strips and the PCB-rev power-rail recommendation.

Step 3 — First boot and web UI

1. Power on the device (USB or external 5 V).
2. The onboard LED blinks slowly (1 Hz) — that's STATUS_LED_AP_MODE, meaning the device is hosting a Wi-Fi access point and waiting for you to configure home Wi-Fi.
3. On your phone, connect to the Wi-Fi network AmbiSense-XXXX (last 4 digits of the device's MAC).
4. The captive portal should pop the setup page automatically. If not, open http://192.168.4.1/ in your browser.
5. Go to Network → Wi-Fi, enter your home SSID + password, click Save & Connect.
6. The device joins your home Wi-Fi. The onboard LED switches to a heartbeat pattern (two short pulses + pause).
7. Reconnect your phone to home Wi-Fi. The device is now reachable as http://ambisense-XXXX.local/ (mDNS).

If .local resolution doesn't work on your network (some routers block mDNS), check your router's DHCP table for the assigned IP and use that directly.

Step 4 — Try it out

Open the web UI in your browser. You should land on the Live screen:

• Distance number updates in real time as you walk around in front of the radar
• Sparkline shows the last 16 s of distance values
• System active toggle on top — tap to mute LED output without rebooting

Walk back and forth in front of the radar. The LED preview at the bottom of the Live screen should track your position, and (if you've wired the strip) the physical strip lights up the segment closest to you.

If the distance reads 0 or stays flat:

1. Go to Hardware tab → check the radar card. If "last frame age" climbs past 1 s, the radar isn't talking. Verify TX↔RX cross-wiring (the radar's TX goes to MCU's RX).
2. Check Hardware → Radar → Diagnostic for the raw byte dump. If bytes are flowing but frames don't parse, double-check baud (default 256000) and that you have an LD2450 (not an older LD2410).

Next steps

• Tune the LED experience: visit LED Modes to pick a mode and color, and Web UI Tour for every control explained.
• Tune motion: Motion Smoothing covers Kalman vs PI and which knobs to touch.
• Plan your install: LD2450 Mounting Guide is critical reading before you commit to a final mounting position — single-sensor architecture has specific geometric requirements.
• Set an admin password: visit System → Admin password to enable PBKDF2-SHA256 auth so neighbours on your home Wi-Fi can't reconfigure your strip.