Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/firmware-qemu.yml
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,10 @@ jobs:
working-directory: firmware/esp32-csi-node/test
run: make all CC="$CC"

- name: Run radar parser, routing and NVS regressions
working-directory: firmware/esp32-csi-node/test
run: make run_mmwave_freshness run_radar_fused_route run_radar_nvs CC="$CC"

- name: Run serialize fuzzer (60s)
working-directory: firmware/esp32-csi-node/test
run: make run_serialize CC="$CC" FUZZ_DURATION=60 || echo "FUZZER_CRASH=serialize" >> "$GITHUB_ENV"
Expand Down
23 changes: 23 additions & 0 deletions firmware/esp32-csi-node/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,27 @@ The boot log must identify `MR60BHA2` and the server must receive fresh
`edge_fused_vitals` packets before the radar is considered connected. Radar
reported heart and breathing values remain unvalidated, nonmedical evidence.

##### Optional split destination for MR60 fused radar

The default remains one target for every stream. An explicit `csi_cfg`
NVS `u16` key `radar_port` opts the fresh MR60 fused-vitals branch into another
UDP port on the **same configured `target_ip`**. Absent/zero means legacy;
nonzero must be at least1024 and differ from `target_port`. For example, keep
raw CSI and ordinary edge/sync/feature packets on a private receiver port and
route only the existing48-byte `0xC5110004` MR60 packet to a radar-aware server.
The configured node ID, MR60 type, finite/range bounds and presence/count
consistency are checked, and the split path is capped at two packets/second.
Invalid explicit configuration, invalid packets or a split send failure never
fall back to the bulk destination. A wrong-type/unreadable NVS key blocks the
split rather than silently resuming legacy routing.

Provision this opt-in using an existing private NVS workflow which preserves
network settings and the other namespace entries; it is not a new HTTP or
serial configuration field. Confirm the receiving server handles fused radar
without inserting it into RF learner ingress. Keep CSI acquisition enabled:
the current edge processing cadence drives fused delivery. Firmware routing
changes neither server output/privacy gates nor sensing qualification.

### 3. Provision WiFi credentials (no reflash needed)

```bash
Expand Down Expand Up @@ -649,6 +670,8 @@ python config_push.py --fleet nodes.txt --set edge_tier=1 --no-reboot
Config is read only at boot, so a change does nothing until the node restarts.
`config_push.py` therefore restarts it by default; `--no-reboot` stages instead.



#### Why some parameters reboot-and-prove

Most settings are recoverable: a wrong `target_ip` sends CSI nowhere, but the
Expand Down
2 changes: 1 addition & 1 deletion firmware/esp32-csi-node/main/edge_processing.c
Original file line number Diff line number Diff line change
Expand Up @@ -984,7 +984,7 @@ static void send_vitals_packet(void)
fpkt.mmwave_targets = mw.target_count;
fpkt.mmwave_confidence = (mw.frame_count > 10) ? 80 : 40;

stream_sender_send((const uint8_t *)&fpkt, sizeof(fpkt));
stream_sender_send_radar_fused((const uint8_t *)&fpkt, sizeof(fpkt));
} else {
/* No mmWave — send standard 32-byte packet. */
stream_sender_send((const uint8_t *)&pkt, sizeof(pkt));
Expand Down
4 changes: 4 additions & 0 deletions firmware/esp32-csi-node/main/main.c
Original file line number Diff line number Diff line change
Expand Up @@ -481,6 +481,10 @@ void app_main(void)
ESP_LOGE(TAG, "Failed to initialize UDP sender");
return;
}
if (stream_sender_configure_radar(g_nvs_config.radar_fused_port, g_nvs_config.node_id) != 0) {
ESP_LOGW(TAG, "Split radar destination unavailable; check explicit radar_port configuration");
}

#endif

/* Initialize CSI collection */
Expand Down
133 changes: 86 additions & 47 deletions firmware/esp32-csi-node/main/mmwave_sensor.c
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,18 @@ static const char *TAG = "mmwave";
/* ---- Shared state ---- */
static mmwave_state_t s_state;
static volatile bool s_running;
static portMUX_TYPE s_state_lock = portMUX_INITIALIZER_UNLOCKED;
/* Transport expiry only; this is not a clinical or occupancy qualification. */
#define MMWAVE_DATA_MAX_AGE_US INT64_C(5000000)
typedef struct {
int64_t presence_us, heart_us, breathing_us, distance_us;
} mmwave_field_times_t;
static mmwave_field_times_t s_field_times;

static bool mmwave_time_fresh(int64_t observed, int64_t now)
{
return observed > 0 && now >= observed && now - observed <= MMWAVE_DATA_MAX_AGE_US;
}

/* ======================================================================
* MR60BHA2 Parser (corrected protocol from Seeed Arduino library)
Expand Down Expand Up @@ -106,63 +118,59 @@ static mr60_parser_t s_mr60;

static void mr60_process_frame(uint16_t type, const uint8_t *data, uint16_t len)
{
const int64_t now = esp_timer_get_time();
bool accepted = false;
portENTER_CRITICAL(&s_state_lock);
s_state.frame_count++;
s_state.last_update_us = esp_timer_get_time();

switch (type) {
case MR60_TYPE_BREATHING:
if (len >= sizeof(float)) {
/* Breathing rate as float32 (little-endian in payload). */
float br;
memcpy(&br, data, sizeof(float));
if (br >= 0.0f && br <= 60.0f) {
s_state.breathing_rate = br;
}
}
case MR60_TYPE_BREATHING: {
float value = NAN;
if (len >= sizeof(value)) memcpy(&value, data, sizeof(value));
const bool valid = isfinite(value) && value >= 0.0f && value <= 60.0f;
s_state.breathing_rate = valid ? value : 0.0f;
s_field_times.breathing_us = valid ? now : 0;
accepted = valid;
break;

case MR60_TYPE_HEARTRATE:
if (len >= sizeof(float)) {
float hr;
memcpy(&hr, data, sizeof(float));
if (hr >= 0.0f && hr <= 250.0f) {
s_state.heart_rate_bpm = hr;
}
}
}
case MR60_TYPE_HEARTRATE: {
float value = NAN;
if (len >= sizeof(value)) memcpy(&value, data, sizeof(value));
const bool valid = isfinite(value) && value >= 0.0f && value <= 250.0f;
s_state.heart_rate_bpm = valid ? value : 0.0f;
s_field_times.heart_us = valid ? now : 0;
accepted = valid;
break;

case MR60_TYPE_DISTANCE:
if (len >= sizeof(uint32_t) + sizeof(float)) {
/* Bytes 0-3: range flag (uint32 LE). 0 = no valid distance. */
uint32_t range_flag;
memcpy(&range_flag, data, sizeof(uint32_t));
if (range_flag != 0) {
float dist;
memcpy(&dist, &data[sizeof(uint32_t)], sizeof(float));
s_state.distance_cm = dist;
}
}
case MR60_TYPE_DISTANCE: {
uint32_t range_flag = 0;
float value = NAN;
if (len >= sizeof(range_flag) + sizeof(value)) {
memcpy(&range_flag, data, sizeof(range_flag));
memcpy(&value, data + sizeof(range_flag), sizeof(value));
}
const bool valid = range_flag != 0 && isfinite(value) && value >= 0.0f;
s_state.distance_cm = valid ? value : 0.0f;
s_field_times.distance_us = valid ? now : 0;
accepted = valid;
break;

}
case MR60_TYPE_PRESENCE:
if (len >= 1) {
s_state.person_present = (data[0] != 0);
/* MR60BHA2 exposes a single-target vital-sign presence flag rather
* than a reliable people-count frame. Keep the public count in
* lockstep with that authoritative flag so downstream clients do
* not report zero targets while fresh radar vitals are arriving. */
s_state.person_present = data[0] != 0;
s_state.target_count = mmwave_mr60_target_count(s_state.person_present);
s_field_times.presence_us = now;
accepted = true;
if (!s_state.person_present) {
s_state.heart_rate_bpm = 0.0f;
s_state.breathing_rate = 0.0f;
s_state.distance_cm = 0.0f;
s_state.heart_rate_bpm = s_state.breathing_rate = s_state.distance_cm = 0.0f;
s_field_times.heart_us = s_field_times.breathing_us = s_field_times.distance_us = 0;
}
}
break;

default:
break;
}
if (accepted) s_state.last_update_us = now;
portEXIT_CRITICAL(&s_state_lock);
}

static void mr60_feed_byte(uint8_t b)
Expand Down Expand Up @@ -249,15 +257,12 @@ static ld2410_parser_t s_ld;

static void ld2410_process_frame(const uint8_t *data, uint16_t len)
{
s_state.frame_count++;
s_state.last_update_us = esp_timer_get_time();

if (len < 12) return;

uint8_t data_type = data[0]; /* 0x02 = normal, 0x01 = engineering */
uint8_t head_marker = data[1]; /* Must be 0xAA */

if (head_marker != LD2410_REPORT_HEAD) return;
if (head_marker != LD2410_REPORT_HEAD || (data_type != 1 && data_type != 2) || data[2] > 3) return;

/* Normal mode target report (data_type 0x02 or 0x01) */
uint8_t target_state = data[2];
Expand All @@ -271,6 +276,11 @@ static void ld2410_process_frame(const uint8_t *data, uint16_t len)
(void)static_energy;
(void)detect_dist;

const int64_t now = esp_timer_get_time();
portENTER_CRITICAL(&s_state_lock);
s_state.frame_count++;
s_state.last_update_us = now;
s_field_times.presence_us = s_field_times.distance_us = now;
s_state.person_present = (target_state != 0);
s_state.target_count = (target_state != 0) ? 1 : 0;

Expand All @@ -281,6 +291,7 @@ static void ld2410_process_frame(const uint8_t *data, uint16_t len)
} else {
s_state.distance_cm = 0.0f;
}
portEXIT_CRITICAL(&s_state_lock);
}

static void ld2410_feed_byte(uint8_t b)
Expand Down Expand Up @@ -346,13 +357,16 @@ static void mock_mmwave_task(void *arg)
float hr_noise = 2.0f * sinf((float)tick * 0.1f) + 0.5f * sinf((float)tick * 0.37f);
float br_noise = 1.0f * sinf((float)tick * 0.07f) + 0.3f * sinf((float)tick * 0.23f);

portENTER_CRITICAL(&s_state_lock);
s_state.heart_rate_bpm = hr_base + hr_noise;
s_state.breathing_rate = br_base + br_noise;
s_state.person_present = true;
s_state.distance_cm = 150.0f + 20.0f * sinf((float)tick * 0.05f);
s_state.target_count = 1;
s_state.frame_count++;
s_state.last_update_us = esp_timer_get_time();
s_field_times = (mmwave_field_times_t){s_state.last_update_us, s_state.last_update_us,
s_state.last_update_us, s_state.last_update_us};

/* Simulate person leaving at tick 200-250 (for scenario testing). */
if (tick >= 200 && tick <= 250) {
Expand All @@ -363,6 +377,7 @@ static void mock_mmwave_task(void *arg)
s_state.target_count = 0;
}

portEXIT_CRITICAL(&s_state_lock);
/* ~1 Hz update rate (matches real MR60BHA2). */
vTaskDelay(pdMS_TO_TICKS(1000));
}
Expand Down Expand Up @@ -496,6 +511,7 @@ const char *mmwave_type_name(mmwave_type_t type)
esp_err_t mmwave_sensor_init(int uart_tx_pin, int uart_rx_pin)
{
memset(&s_state, 0, sizeof(s_state));
memset(&s_field_times, 0, sizeof(s_field_times));
memset(&s_mr60, 0, sizeof(s_mr60));
memset(&s_ld, 0, sizeof(s_ld));
s_running = true;
Expand Down Expand Up @@ -641,7 +657,30 @@ esp_err_t mmwave_sensor_init(int uart_tx_pin, int uart_rx_pin)

bool mmwave_sensor_get_state(mmwave_state_t *state)
{
if (!s_state.detected || state == NULL) return false;
memcpy(state, &s_state, sizeof(mmwave_state_t));
if (state == NULL) return false;
mmwave_field_times_t times;
portENTER_CRITICAL(&s_state_lock);
memcpy(state, &s_state, sizeof(*state));
times = s_field_times;
portEXIT_CRITICAL(&s_state_lock);
const int64_t now = esp_timer_get_time();
/* Missing presence is unavailable, never a new empty-room observation.
* The existing wire format cannot represent unknown range while present:
* mobile treats zero as a measured distance. Withhold that whole snapshot. */
if (!state->detected || !mmwave_time_fresh(times.presence_us, now) ||
(state->person_present && !mmwave_time_fresh(times.distance_us, now))) {
state->detected = false;
state->person_present = false;
state->target_count = 0;
state->heart_rate_bpm = state->breathing_rate = state->distance_cm = 0.0f;
return false;
}
if (!state->person_present) {
state->heart_rate_bpm = state->breathing_rate = state->distance_cm = 0.0f;
} else {
/* Zero is the existing unavailable encoding for numeric vital rates. */
if (!mmwave_time_fresh(times.heart_us, now)) state->heart_rate_bpm = 0.0f;
if (!mmwave_time_fresh(times.breathing_us, now)) state->breathing_rate = 0.0f;
}
return true;
}
5 changes: 4 additions & 1 deletion firmware/esp32-csi-node/main/mmwave_sensor.h
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,10 @@ esp_err_t mmwave_sensor_init(int uart_tx_pin, int uart_rx_pin);
* Get a snapshot of the current mmWave state (thread-safe copy).
*
* @param state Output state struct.
* @return true if valid data is available (sensor detected and running).
* Expired/unseen presence and present-without-fresh-range withhold the snapshot.
* Optional expired vital rates use zero (unavailable). False means unavailable,
* not an observed empty room; sensor identity is retained for fresh recovery.
* @return true if a representable, fresh radar observation is available.
*/
bool mmwave_sensor_get_state(mmwave_state_t *state);

Expand Down
22 changes: 21 additions & 1 deletion firmware/esp32-csi-node/main/nvs_config.c
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ void nvs_config_load(nvs_config_t *cfg)
strlcpy(cfg->target_ip, CONFIG_CSI_TARGET_IP, sizeof(cfg->target_ip));

cfg->target_port = (uint16_t)CONFIG_CSI_TARGET_PORT;
cfg->radar_fused_port = 0; /* Only absent NVS or explicit zero selects legacy routing. */
cfg->node_id = (uint8_t)CONFIG_CSI_NODE_ID;

/* ADR-029: Defaults for channel hopping and TDM.
Expand Down Expand Up @@ -109,7 +110,12 @@ void nvs_config_load(nvs_config_t *cfg)
nvs_handle_t handle;
esp_err_t err = nvs_open("csi_cfg", NVS_READONLY, &handle);
if (err != ESP_OK) {
ESP_LOGI(TAG, "No NVS config found, using compiled defaults");
if (err == ESP_ERR_NVS_NOT_FOUND) {
ESP_LOGI(TAG, "No NVS config found, using compiled defaults");
} else {
cfg->radar_fused_port = 1; /* Unknown opt-in state must not select bulk. */
ESP_LOGW(TAG, "NVS config unreadable; split radar routing blocked");
}
return;
}

Expand Down Expand Up @@ -144,6 +150,20 @@ void nvs_config_load(nvs_config_t *cfg)
ESP_LOGI(TAG, "NVS override: target_port=%u", cfg->target_port);
}

/* Explicit opt-in split route. Preserve invalid intent as a blocked port
* so a bad nonzero/wrong-type value cannot silently resume legacy routing. */
uint16_t radar_port;
const esp_err_t radar_result = nvs_get_u16(handle, "radar_port", &radar_port);
if (radar_result == ESP_OK) {
cfg->radar_fused_port = radar_port;
if (radar_port != 0 && (radar_port < 1024 || radar_port == cfg->target_port)) {
ESP_LOGW(TAG, "Refusing invalid split radar port");
}
} else if (radar_result != ESP_ERR_NVS_NOT_FOUND) {
cfg->radar_fused_port = 1; /* Invalid reserved sentinel: fail closed. */
ESP_LOGW(TAG, "Refusing unreadable split radar port");
}

/* Node ID */
uint8_t node_val;
if (nvs_get_u8(handle, "node_id", &node_val) == ESP_OK) {
Expand Down
1 change: 1 addition & 0 deletions firmware/esp32-csi-node/main/nvs_config.h
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ typedef struct {
char wifi_password[NVS_CFG_PASS_MAX];
char target_ip[NVS_CFG_IP_MAX];
uint16_t target_port;
uint16_t radar_fused_port; /**< Optional same-IP MR60 fused-only port; 0 = legacy routing. */
uint8_t node_id;

/* ADR-029: Channel hopping and TDM configuration */
Expand Down
26 changes: 26 additions & 0 deletions firmware/esp32-csi-node/main/radar_fused_route.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
#ifndef RUVIEW_RADAR_FUSED_ROUTE_H
#define RUVIEW_RADAR_FUSED_ROUTE_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <math.h>

/* Existing ADR-063 little-endian 48-byte MR60 fused packet; never raw CSI. */
static inline bool ruview_mr60_fused_packet(const uint8_t *data, size_t len, uint8_t node_id)
{
if (data == NULL || len != 48 || data[0] != 4 || data[1] != 0 ||
data[2] != 0x11 || data[3] != 0xC5 || data[4] != node_id || data[14] != 1)
return false;
float motion, score, hr, br, range;
memcpy(&motion, data + 16, 4); memcpy(&score, data + 20, 4);
memcpy(&hr, data + 28, 4); memcpy(&br, data + 32, 4); memcpy(&range, data + 36, 4);
return isfinite(motion) && motion >= 0 && motion <= 1e6f &&
isfinite(score) && score >= 0 && score <= 1e6f &&
isfinite(hr) && hr >= 0 && hr <= 250 &&
isfinite(br) && br >= 0 && br <= 60 &&
isfinite(range) && range >= 0 && range <= 3000 &&
data[15] <= 100 && data[41] <= 100 && data[40] <= 1 &&
((data[5] & 8) != 0) == (data[40] == 1);
}
#endif
Loading
Loading