diff --git a/CLAUDE.md b/CLAUDE.md index 262884dce4..06461a8e98 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -93,6 +93,8 @@ All 5 ruvector crates integrated in workspace: **Not supported:** ESP32 (original), ESP32-C3 — single-core, can't run CSI DSP pipeline. +**⚠️ Compact boards (SuperMini, ESP32-S3-Zero, other coin-sized clones) run hot:** the firmware keeps the WiFi radio on continuously (`WIFI_PS_NONE`) and runs a full DSP pipeline (`edge_tier=2`), which is sustained high current draw. Full-size dev boards handle this fine; coin-sized clones with minimal PCB copper and budget regulators can run uncomfortably hot and, per at least one field report, have failed to power on again after a hot session. Give them airflow and check by touch during the first few minutes. See `firmware/esp32-csi-node/README.md` for details. + ### Build & Test Commands (this repo) ```bash # Rust — full workspace tests (1,031+ tests, ~2 min) diff --git a/firmware/esp32-csi-node/README.md b/firmware/esp32-csi-node/README.md index f75d053c29..23b9efa602 100644 --- a/firmware/esp32-csi-node/README.md +++ b/firmware/esp32-csi-node/README.md @@ -105,6 +105,8 @@ curl http://:8032/wasm/list > **Tip:** A single node provides presence and vital signs along its line of sight. Multiple nodes (3-6) create a multistatic mesh that resolves 3D pose with <30 mm jitter and zero identity swaps. +> **⚠️ Thermal warning — compact boards (ESP32-S3-Zero, SuperMini, other coin-sized clones):** This firmware runs the WiFi radio with modem sleep disabled (`WIFI_PS_NONE`, required for continuous CSI capture) plus a full edge-processing DSP pipeline on Core 1 (`edge_tier=2`) plus, on ADR-183 builds, a continuous 40 Hz onboard LED driver. That's sustained high current draw with no duty-cycling. Full-size dev boards (DevKitC-1, XIAO) have more copper pour and thermal mass around the regulator and tolerate this fine. Coin-sized clones with minimal PCB area and budget regulators may run hot to the touch during normal operation, and in at least one field report, boards that ran hot during a session failed to power on afterward (regulator damage suspected — see issue tracker). Give these boards airflow, don't stack or enclose them, and check them by touch during the first several minutes of a new deployment. If a board is uncomfortably hot (not just warm), power it down and let it cool before continuing. + --- ## Firmware Architecture diff --git a/firmware/esp32-csi-node/main/main.c b/firmware/esp32-csi-node/main/main.c index 67973ceebe..6627bbbbc6 100644 --- a/firmware/esp32-csi-node/main/main.c +++ b/firmware/esp32-csi-node/main/main.c @@ -67,6 +67,8 @@ static void event_handler(void *arg, esp_event_base_t event_base, if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) { esp_wifi_connect(); } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) { + wifi_event_sta_disconnected_t *disc = (wifi_event_sta_disconnected_t *)event_data; + ESP_LOGW(TAG, "WiFi disconnected, reason=%d rssi=%d", disc->reason, disc->rssi); if (s_retry_num < MAX_RETRY) { esp_wifi_connect(); s_retry_num++; @@ -102,7 +104,10 @@ static void wifi_init_sta(void) wifi_config_t wifi_config = { .sta = { - .threshold.authmode = WIFI_AUTH_WPA2_PSK, + /* WPA_PSK (not WPA2_PSK) so routers running WPA/WPA2-mixed + * compatibility mode aren't rejected with + * WIFI_REASON_NO_AP_FOUND_IN_AUTHMODE_THRESHOLD (#1050). */ + .threshold.authmode = WIFI_AUTH_WPA_PSK, }, }; diff --git a/plugins/ruview/skills/ruview-hardware-setup/SKILL.md b/plugins/ruview/skills/ruview-hardware-setup/SKILL.md index dd5bf319e8..8bf134f217 100644 --- a/plugins/ruview/skills/ruview-hardware-setup/SKILL.md +++ b/plugins/ruview/skills/ruview-hardware-setup/SKILL.md @@ -18,6 +18,8 @@ Bring a RuView sensing node online: build firmware → flash → provision WiFi **Not supported:** original ESP32, ESP32-C3 (single-core). +**⚠️ Ask about board form factor before flashing.** If the user's board is a coin-sized clone (ESP32-S3-Zero, SuperMini, or similar — not a full DevKitC/XIAO-style board with a real USB connector and visible regulator), warn them before they walk away from it: this firmware runs the WiFi radio continuously (`WIFI_PS_NONE`) plus a full DSP pipeline (`edge_tier=2`), which is sustained high current draw that full-size dev boards handle fine but tiny clones with minimal copper/budget regulators may not. At least one field report: boards ran hot during a normal session and failed to power on again afterward (regulator damage suspected). Tell them to give the board airflow (don't stack/enclose it) and check it by touch during the first several minutes of any new deployment. + ## 1. Build firmware (Windows — Python subprocess, NOT bash directly) ESP-IDF v5.4 does not support MSYS2/Git Bash. Use the Espressif Python venv as a subprocess with `MSYSTEM*` env vars stripped. The proven command lives in `CLAUDE.local.md` — reproduce it: