From 0b7f0bc9623c0c5da7b7917ecc613d081a42cce8 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 15 Mar 2026 11:48:53 -0400 Subject: [PATCH] docs: update README, CHANGELOG, user guide for v0.4.3-esp32 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: add v0.4.3 to release table, 4MB flash instructions, fix fall-thresh example (5000→15000) - CHANGELOG: v0.4.3-esp32 entry with all fixes and additions - User guide: 4MB flash section with esptool commands Co-Authored-By: claude-flow --- CHANGELOG.md | 12 ++++++++++++ README.md | 15 +++++++++++---- docs/user-guide.md | 11 ++++++++++- 3 files changed, 33 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e2c89a1c..bd7cda85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [v0.4.3-esp32] — 2026-03-15 + +### Fixed +- **Fall detection false positives (#263)** — Default threshold raised from 2.0 to 15.0 rad/s²; normal walking (2-5 rad/s²) no longer triggers alerts. Added 3-consecutive-frame debounce and 5-second cooldown between alerts. Verified on real ESP32-S3 hardware: 0 false alerts in 60s / 1,300+ live WiFi CSI frames. +- **Kconfig default mismatch** — `CONFIG_EDGE_FALL_THRESH` Kconfig default was still 2000 (=2.0) while `nvs_config.c` fallback was updated to 15.0. Fixed Kconfig to 15000. Caught by real hardware testing — mock data did not reproduce. +- **provision.py NVS generator API change** — `esp_idf_nvs_partition_gen` package changed its `generate()` signature; switched to subprocess-first invocation for cross-version compatibility. +- **QEMU CI pipeline (11 jobs)** — Fixed all failures: fuzz test `esp_timer` stubs, QEMU `libgcrypt` dependency, NVS matrix generator, IDF container `pip` path, flash image padding, validation WARN handling, swarm `ip`/`cargo` missing. + +### Added +- **4MB flash support (#265)** — `partitions_4mb.csv` and `sdkconfig.defaults.4mb` for ESP32-S3 boards with 4MB flash (e.g. SuperMini). Dual OTA slots, 1.856 MB each. Thanks to @sebbu for the community workaround that confirmed feasibility. +- **`--strict` flag** for `validate_qemu_output.py` — WARNs now pass by default in CI (no real WiFi in QEMU); use `--strict` to fail on warnings. + ## [Unreleased] ### Added diff --git a/README.md b/README.md index bd964e78..26bbdb3c 100644 --- a/README.md +++ b/README.md @@ -1047,17 +1047,24 @@ Download a pre-built binary — no build toolchain needed: | Release | What's included | Tag | |---------|-----------------|-----| -| [v0.4.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.1-esp32) | **Stable** — CSI build fix, compile guard, AMOLED display, edge intelligence ([ADR-057](docs/adr/ADR-057-firmware-csi-build-guard.md)) | `v0.4.1-esp32` | +| [v0.4.3](https://github.com/ruvnet/RuView/releases/tag/v0.4.3-esp32) | **Stable** — Fall detection fix ([#263](https://github.com/ruvnet/RuView/issues/263)), 4MB flash support ([#265](https://github.com/ruvnet/RuView/issues/265)), QEMU CI green | `v0.4.3-esp32` | +| [v0.4.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.1-esp32) | CSI build fix, compile guard, AMOLED display, edge intelligence ([ADR-057](docs/adr/ADR-057-firmware-csi-build-guard.md)) | `v0.4.1-esp32` | | [v0.3.0-alpha](https://github.com/ruvnet/RuView/releases/tag/v0.3.0-alpha-esp32) | Alpha — adds on-device edge intelligence and WASM modules ([ADR-039](docs/adr/ADR-039-esp32-edge-intelligence.md), [ADR-040](docs/adr/ADR-040-wasm-programmable-sensing.md)) | `v0.3.0-alpha-esp32` | | [v0.2.0](https://github.com/ruvnet/RuView/releases/tag/v0.2.0-esp32) | Raw CSI streaming, multi-node TDM, channel hopping | `v0.2.0-esp32` | ```bash -# 1. Flash the firmware to your ESP32-S3 +# 1. Flash the firmware to your ESP32-S3 (8MB flash — most boards) python -m esptool --chip esp32s3 --port COM7 --baud 460800 \ write_flash --flash-mode dio --flash-size 8MB --flash-freq 80m \ 0x0 bootloader.bin 0x8000 partition-table.bin \ 0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin +# 1b. For 4MB flash boards (e.g. ESP32-S3 SuperMini 4MB) — use the 4MB binaries: +python -m esptool --chip esp32s3 --port COM7 --baud 460800 \ + write_flash --flash-mode dio --flash-size 4MB --flash-freq 80m \ + 0x0 bootloader.bin 0x8000 partition-table-4mb.bin \ + 0xF000 ota_data_initial.bin 0x20000 esp32-csi-node-4mb.bin + # 2. Set WiFi credentials and server address (stored in flash, survives reboots) python firmware/esp32-csi-node/provision.py --port COM7 \ --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 @@ -1104,9 +1111,9 @@ python firmware/esp32-csi-node/provision.py --port COM7 \ --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 \ --edge-tier 2 -# Fine-tune detection thresholds +# Fine-tune detection thresholds (fall-thresh in milli-units: 15000 = 15.0 rad/s²) python firmware/esp32-csi-node/provision.py --port COM7 \ - --edge-tier 2 --vital-int 500 --fall-thresh 5000 --subk-count 16 + --edge-tier 2 --vital-int 500 --fall-thresh 15000 --subk-count 16 ``` When Tier 2 is active, the node sends a 32-byte vitals packet once per second containing: presence, motion level, breathing BPM, heart rate BPM, confidence scores, fall alert flag, and occupancy count. diff --git a/docs/user-guide.md b/docs/user-guide.md index f2e82195..99a0eb56 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -826,13 +826,22 @@ Pre-built binaries are available at [Releases](https://github.com/ruvnet/RuView/ > **Important:** Firmware versions prior to v0.4.1 had CSI **disabled** in the build config, causing a runtime error (`E wifi:CSI not enabled in menuconfig!`). Always use v0.4.1 or later. ```bash -# Flash an ESP32-S3 (requires esptool: pip install esptool) +# Flash an ESP32-S3 with 8MB flash (most boards) python -m esptool --chip esp32s3 --port COM7 --baud 460800 \ write-flash --flash-mode dio --flash-size 8MB --flash-freq 80m \ 0x0 bootloader.bin 0x8000 partition-table.bin \ 0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin ``` +**4MB flash boards** (e.g. ESP32-S3 SuperMini 4MB): download the 4MB binaries from the [v0.4.3 release](https://github.com/ruvnet/RuView/releases/tag/v0.4.3-esp32) and use `--flash-size 4MB`: + +```bash +python -m esptool --chip esp32s3 --port COM7 --baud 460800 \ + write-flash --flash-mode dio --flash-size 4MB --flash-freq 80m \ + 0x0 bootloader.bin 0x8000 partition-table-4mb.bin \ + 0xF000 ota_data_initial.bin 0x20000 esp32-csi-node-4mb.bin +``` + **Provisioning:** ```bash