mirror of
https://github.com/ruvnet/RuView
synced 2026-07-31 18:51:42 +00:00
Claude
9648a47fdc
Introduces a 5-layer firmware kernel that reframes the existing ESP32
modules as components of a chipset-agnostic architecture and authorizes
adaptive control + a compact feature-state stream as the default upstream.
Layers:
L1 Radio Abstraction Layer — rv_radio_ops_t vtable + ESP32 binding
L2 Adaptive Controller — fast/medium/slow loops (200ms/1s/30s)
L3 Mesh Sensing Plane — anchor/observer/relay/coordinator (spec)
L4 On-device Feature Extr. — rv_feature_state_t (magic 0xC5110006)
L5 Rust handoff — feature_state default; debug raw gated
Files:
docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md (new)
firmware/esp32-csi-node/main/rv_radio_ops.h (new)
firmware/esp32-csi-node/main/rv_radio_ops_esp32.c (new)
firmware/esp32-csi-node/main/rv_feature_state.{h,c} (new)
firmware/esp32-csi-node/main/adaptive_controller.{h,c} (new)
firmware/esp32-csi-node/main/main.c (wire L1+L2)
firmware/esp32-csi-node/main/CMakeLists.txt (add 4 sources)
firmware/esp32-csi-node/main/Kconfig.projbuild (controller knobs)
CHANGELOG.md (Unreleased)
Default policy is conservative: enable_channel_switch and
enable_role_change are off, so behavior matches today's firmware
unless an operator opts in via menuconfig. The pure
adaptive_controller_decide() is exposed for offline unit tests.
Reuses (does not rewrite): csi_collector, edge_processing (ADR-039),
swarm_bridge (ADR-066), secure_tdm (ADR-032), wasm_runtime (ADR-040).
111 lines
4.2 KiB
C
111 lines
4.2 KiB
C
/**
|
|
* @file rv_feature_state.h
|
|
* @brief ADR-081 Layer 4 — Compact on-wire feature state packet.
|
|
*
|
|
* The default upstream payload from a node. Replaces raw ADR-018 CSI as the
|
|
* primary stream; ADR-018 raw frames remain available as a debug stream
|
|
* gated by the controller / channel plan.
|
|
*
|
|
* Magic numbers in use across the firmware:
|
|
* 0xC5110001 — ADR-018 raw CSI frame (csi_collector.h)
|
|
* 0xC5110002 — ADR-039 vitals packet (edge_processing.h)
|
|
* 0xC5110003 — ADR-069 feature vector (edge_processing.h)
|
|
* 0xC5110004 — ADR-063 fused vitals (edge_processing.h)
|
|
* 0xC5110005 — ADR-039 compressed CSI (edge_processing.h)
|
|
* 0xC5110006 — ADR-081 feature state (this file) ← new
|
|
*/
|
|
|
|
#ifndef RV_FEATURE_STATE_H
|
|
#define RV_FEATURE_STATE_H
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** Magic number for ADR-081 rv_feature_state_t. */
|
|
#define RV_FEATURE_STATE_MAGIC 0xC5110006u
|
|
|
|
/** Quality flag bits. */
|
|
#define RV_QFLAG_PRESENCE_VALID (1u << 0)
|
|
#define RV_QFLAG_RESPIRATION_VALID (1u << 1)
|
|
#define RV_QFLAG_HEARTBEAT_VALID (1u << 2)
|
|
#define RV_QFLAG_ANOMALY_TRIGGERED (1u << 3)
|
|
#define RV_QFLAG_ENV_SHIFT_DETECTED (1u << 4)
|
|
#define RV_QFLAG_DEGRADED_MODE (1u << 5)
|
|
#define RV_QFLAG_CALIBRATING (1u << 6)
|
|
#define RV_QFLAG_RECOMMEND_RECAL (1u << 7)
|
|
|
|
/**
|
|
* Compact per-node sensing state. Sent at 1-10 Hz by default, replacing the
|
|
* raw ADR-018 stream as the primary upstream payload.
|
|
*
|
|
* Mode field carries the rv_capture_profile_t value of the dominant window
|
|
* — receivers can use it to weight features (a sample emitted under
|
|
* RV_PROFILE_FAST_MOTION will have a stale respiration_bpm, etc.).
|
|
*
|
|
* CRC32 is the IEEE polynomial computed over bytes [0 .. sizeof - 4].
|
|
*/
|
|
typedef struct __attribute__((packed)) {
|
|
uint32_t magic; /**< RV_FEATURE_STATE_MAGIC. */
|
|
uint8_t node_id; /**< Source node id. */
|
|
uint8_t mode; /**< rv_capture_profile_t at emit time. */
|
|
uint16_t seq; /**< Monotonic per-node sequence. */
|
|
uint64_t ts_us; /**< Node-local microseconds. */
|
|
float motion_score; /**< 0..1, 100 ms window. */
|
|
float presence_score; /**< 0..1, 1 s window. */
|
|
float respiration_bpm; /**< Breaths per minute. */
|
|
float respiration_conf; /**< 0..1. */
|
|
float heartbeat_bpm; /**< Beats per minute. */
|
|
float heartbeat_conf; /**< 0..1. */
|
|
float anomaly_score; /**< 0..1, z-score-derived. */
|
|
float env_shift_score; /**< 0..1, baseline drift. */
|
|
float node_coherence; /**< 0..1, multi-link agreement. */
|
|
uint16_t quality_flags; /**< RV_QFLAG_* bitmap. */
|
|
uint16_t reserved;
|
|
uint32_t crc32; /**< IEEE CRC32 over bytes [0..end-4]. */
|
|
} rv_feature_state_t;
|
|
|
|
_Static_assert(sizeof(rv_feature_state_t) == 80,
|
|
"rv_feature_state_t must be 80 bytes on the wire");
|
|
|
|
/**
|
|
* Compute IEEE CRC32 over a byte buffer.
|
|
*
|
|
* Provided here (not in a separate util) because the firmware does not yet
|
|
* have a shared CRC32 helper — only zlib's via lwIP, which is not always
|
|
* exposed. This implementation is bit-by-bit; ~80 bytes/packet at low
|
|
* cadence has negligible CPU cost.
|
|
*
|
|
* @param data Input buffer.
|
|
* @param len Input length in bytes.
|
|
* @return IEEE CRC32 of the input.
|
|
*/
|
|
uint32_t rv_feature_state_crc32(const uint8_t *data, size_t len);
|
|
|
|
/**
|
|
* Finalize an rv_feature_state_t by populating magic, seq, ts_us, and crc32.
|
|
* Caller fills the remaining fields in-place before calling this. After
|
|
* finalize() the packet is ready to send on the wire.
|
|
*
|
|
* @param pkt Packet to finalize (caller-owned).
|
|
* @param node_id Source node id (typically csi_collector_get_node_id()).
|
|
* @param seq Monotonic sequence (caller-managed).
|
|
* @param ts_us Node-local microseconds (typically esp_timer_get_time()).
|
|
* @param mode Active rv_capture_profile_t.
|
|
*/
|
|
void rv_feature_state_finalize(rv_feature_state_t *pkt,
|
|
uint8_t node_id,
|
|
uint16_t seq,
|
|
uint64_t ts_us,
|
|
uint8_t mode);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* RV_FEATURE_STATE_H */
|