vrr/Ruview
2
0
Fork 0
mirror of https://github.com/ruvnet/RuView.git synced 2026-05-03 16:30:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

ADR-081: Layer 3 mesh plane + Rust mirror trait — all 5 layers landed

Browse source 
Fully implements the remaining deferred pieces of the adaptive CSI mesh
firmware kernel. All 5 layers (Radio Abstraction, Adaptive Controller,
Mesh Sensing Plane, On-device Feature Extraction, Rust handoff) are
now implemented and host-tested end-to-end.

Layer 3 — Mesh Sensing Plane (firmware/esp32-csi-node/main/rv_mesh.{h,c}):
  * 4 node roles: Unassigned / Anchor / Observer / FusionRelay / Coordinator
  * 7 message types: TIME_SYNC, ROLE_ASSIGN, CHANNEL_PLAN,
    CALIBRATION_START, FEATURE_DELTA, HEALTH, ANOMALY_ALERT
  * 3 auth classes: None / HMAC-SHA256-session / Ed25519-batch
  * Payload types: rv_node_status_t (28 B), rv_anomaly_alert_t (28 B),
    rv_time_sync_t (16 B), rv_role_assign_t (16 B),
    rv_channel_plan_t (24 B), rv_calibration_start_t (20 B)
  * 16-byte envelope + payload + IEEE CRC32 trailer
  * Pure rv_mesh_encode()/rv_mesh_decode() plus typed convenience encoders
  * rv_mesh_send_health() + rv_mesh_send_anomaly() helpers

Controller wiring (adaptive_controller.c):
  * Slow loop (30 s default) now emits HEALTH
  * apply_decision() emits ANOMALY_ALERT on transitions to ALERT /
    DEGRADED
  * Role + mesh epoch tracked in module state; epoch bumps on role
    change

Layer 5 — Rust mirror (crates/wifi-densepose-hardware/src/radio_ops.rs):
  * RadioOps trait mirrors rv_radio_ops_t vtable
  * MockRadio backend for offline tests
  * MeshHeader / NodeStatus / AnomalyAlert types mirror rv_mesh.h
  * Byte-identical IEEE CRC32 (poly 0xEDB88320) verified against
    firmware test vectors (0xCBF43926 for "123456789")
  * decode_mesh / decode_node_status / decode_anomaly_alert / encode_health
  * 8 unit tests, including mesh_constants_match_firmware which asserts
    MESH_MAGIC/VERSION/HEADER_SIZE/MAX_PAYLOAD match rv_mesh.h
    byte-for-byte
  * Exported from lib.rs
  * signal/ruvector/train/mat crates untouched — satisfies ADR-081
    portability acceptance test

Tests (all passing):
  test_adaptive_controller:   18/18   (C, decide() 3.2 ns/call)
  test_rv_feature_state:      15/15   (C, CRC32 87 MB/s)
  test_rv_mesh:               27/27   (C, roundtrip 1.0 µs)
  radio_ops::tests (Rust):     8/8
  --- total:                 68/68 assertions green ---

Docs:
  * ADR-081 status flipped to Accepted
  * Implementation-status matrix updated; L3 + Rust mirror both
    marked Implemented
  * Benchmarks table extended with rv_mesh encode+decode roundtrip
  * Verification section updated with cargo test invocation
  * CHANGELOG: two new entries for L3 mesh plane + Rust mirror

Remaining follow-ups (Phase 3.5 polish, not blocking):
  * Mesh RX path (UDP listener + dispatch) on the firmware
  * Ed25519 signing for CHANNEL_PLAN / CALIBRATION_START
  * Hardware validation on COM7
This commit is contained in:
Claude 2026-04-19 03:57:18 +00:00
parent d53e29506e
commit 8dfb031cb3
No known key found for this signature in database
12 changed files with 1633 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

1
firmware/esp32-csi-node/main/CMakeLists.txt
View file

@ -7,6 +7,7 @@ set(SRCS
# ADR-081 — adaptive CSI mesh firmware kernel
"rv_radio_ops_esp32.c"
"rv_feature_state.c"
"rv_mesh.c"
"adaptive_controller.c"
)

58
firmware/esp32-csi-node/main/adaptive_controller.c
View file

@ -15,6 +15,7 @@
#include "adaptive_controller.h"
#include "rv_radio_ops.h"
#include "rv_feature_state.h"
#include "rv_mesh.h"
#include "edge_processing.h"
#include "stream_sender.h"
#include "csi_collector.h"
@ -131,14 +132,57 @@ static void collect_observation(adapt_observation_t *out)
/* ---- Decision application ---- */
/* ADR-081 L3: epoch monotonically advances per mesh session. Seeded at
* init; every major state transition or role change bumps it so
* receivers can order events. */
static uint32_t s_mesh_epoch = 1;
/* ADR-081 L3: current node role. Updated by ROLE_ASSIGN receipt (future
* mesh-plane RX path) or forced by tests. Default Observer. */
static uint8_t s_role = RV_ROLE_OBSERVER;
/* 8-byte node id. Upper 7 bytes are zero by default; byte 0 is the
* legacy CSI node id for compatibility with the ADR-018 header. */
static void node_id_bytes(uint8_t out[8])
{
memset(out, 0, 8);
out[0] = csi_collector_get_node_id();
}
static void apply_decision(const adapt_decision_t *dec)
{
const rv_radio_ops_t *ops = rv_radio_ops_get();
adapt_state_t prev = s_state;
if (dec->change_state) {
ESP_LOGI(TAG, "state %u → %u",
(unsigned)s_state, (unsigned)dec->new_state);
s_state = (adapt_state_t)dec->new_state;
/* ADR-081 L3: on transition to ALERT, emit ANOMALY_ALERT on the
* mesh plane. On any role-relevant transition, bump the epoch. */
if (s_state == ADAPT_STATE_ALERT && prev != ADAPT_STATE_ALERT) {
uint8_t nid[8];
node_id_bytes(nid);
adapt_observation_t obs;
float motion = 0.0f, anomaly = 0.0f;
portENTER_CRITICAL(&s_obs_lock);
if (s_obs_valid) { obs = s_last_obs; motion = obs.motion_score;
anomaly = obs.anomaly_score; }
portEXIT_CRITICAL(&s_obs_lock);
uint8_t severity = (uint8_t)(anomaly * 255.0f);
rv_mesh_send_anomaly(s_role, s_mesh_epoch, nid,
RV_ANOMALY_COHERENCE_LOSS, severity,
anomaly, motion);
}
if (s_state == ADAPT_STATE_DEGRADED && prev != ADAPT_STATE_DEGRADED) {
uint8_t nid[8];
node_id_bytes(nid);
rv_mesh_send_anomaly(s_role, s_mesh_epoch, nid,
RV_ANOMALY_PKT_YIELD_COLLAPSE,
200, 1.0f, 0.0f);
}
s_mesh_epoch++;
}
if (dec->change_profile && ops != NULL && ops->set_capture_profile != NULL) {
@ -272,10 +316,16 @@ static void emit_feature_state(void)
static void slow_loop_cb(TimerHandle_t t)
{
(void)t;
/* Slow loop: log a heartbeat and (future Phase 3) publish HEALTH
* messages + request CALIBRATION_START on sustained drift. */
ESP_LOGI(TAG, "slow tick (state=%u, feature_state_seq=%u)",
(unsigned)s_state, (unsigned)s_feature_state_seq);
/* ADR-081 L3: publish a HEALTH mesh message every slow tick
* (default 30 s). The coordinator uses these to track liveness and
* detect sync-error drift. */
uint8_t nid[8];
node_id_bytes(nid);
rv_mesh_send_health(s_role, s_mesh_epoch, nid);
ESP_LOGI(TAG, "slow tick (state=%u, feature_state_seq=%u, role=%u, epoch=%u) HEALTH sent",
(unsigned)s_state, (unsigned)s_feature_state_seq,
(unsigned)s_role, (unsigned)s_mesh_epoch);
}
/* ---- Public API ---- */

251
firmware/esp32-csi-node/main/rv_mesh.c Normal file
View file

@ -0,0 +1,251 @@
/**
* @file rv_mesh.c
* @brief ADR-081 Layer 3 — Mesh Sensing Plane implementation.
*
* Encoder/decoder are pure functions (no ESP-IDF deps) and therefore
* host-unit-testable. The send helpers wrap stream_sender so the
* firmware can use a single upstream socket for all payload types.
*/
#include "rv_mesh.h"
#include "rv_feature_state.h"
#include "rv_radio_ops.h"
#include <string.h>
#ifndef RV_MESH_HOST_TEST
#include "esp_log.h"
#include "esp_timer.h"
#include "stream_sender.h"
#include "csi_collector.h"
#include "adaptive_controller.h"
static const char *TAG = "rv_mesh";
#endif
/* ---- Encoder ---- */
size_t rv_mesh_encode(uint8_t type,
uint8_t sender_role,
uint8_t auth_class,
uint32_t epoch,
const void *payload,
uint16_t payload_len,
uint8_t *buf,
size_t buf_cap)
{
if (buf == NULL) return 0;
if (payload == NULL && payload_len != 0) return 0;
if (payload_len > RV_MESH_MAX_PAYLOAD) return 0;
size_t total = sizeof(rv_mesh_header_t) + (size_t)payload_len + 4u;
if (buf_cap < total) return 0;
rv_mesh_header_t hdr;
hdr.magic = RV_MESH_MAGIC;
hdr.version = (uint8_t)RV_MESH_VERSION;
hdr.type = type;
hdr.sender_role = sender_role;
hdr.auth_class = auth_class;
hdr.epoch = epoch;
hdr.payload_len = payload_len;
hdr.reserved = 0;
memcpy(buf, &hdr, sizeof(hdr));
if (payload_len > 0) {
memcpy(buf + sizeof(hdr), payload, payload_len);
}
/* IEEE CRC32 over header + payload. Reuses the CRC32 from
* rv_feature_state.c so there is exactly one implementation. */
uint32_t crc = rv_feature_state_crc32(buf, sizeof(hdr) + payload_len);
memcpy(buf + sizeof(hdr) + payload_len, &crc, 4);
return total;
}
esp_err_t rv_mesh_decode(const uint8_t *buf, size_t buf_len,
rv_mesh_header_t *out_hdr,
const uint8_t **out_payload,
uint16_t *out_payload_len)
{
if (buf == NULL || out_hdr == NULL ||
out_payload == NULL || out_payload_len == NULL) {
return ESP_ERR_INVALID_ARG;
}
if (buf_len < sizeof(rv_mesh_header_t) + 4u) {
return ESP_ERR_INVALID_SIZE;
}
rv_mesh_header_t hdr;
memcpy(&hdr, buf, sizeof(hdr));
if (hdr.magic != RV_MESH_MAGIC) {
return ESP_ERR_INVALID_VERSION; /* repurpose: wrong magic */
}
if (hdr.version != RV_MESH_VERSION) {
return ESP_ERR_INVALID_VERSION;
}
if (hdr.payload_len > RV_MESH_MAX_PAYLOAD) {
return ESP_ERR_INVALID_SIZE;
}
size_t needed = sizeof(hdr) + (size_t)hdr.payload_len + 4u;
if (buf_len < needed) {
return ESP_ERR_INVALID_SIZE;
}
uint32_t got_crc;
memcpy(&got_crc, buf + sizeof(hdr) + hdr.payload_len, 4);
uint32_t want_crc = rv_feature_state_crc32(buf,
sizeof(hdr) + hdr.payload_len);
if (got_crc != want_crc) {
return ESP_ERR_INVALID_CRC;
}
*out_hdr = hdr;
*out_payload = (hdr.payload_len > 0) ? buf + sizeof(hdr) : NULL;
*out_payload_len = hdr.payload_len;
return ESP_OK;
}
/* ---- Typed convenience encoders ---- */
size_t rv_mesh_encode_health(uint8_t sender_role,
uint32_t epoch,
const rv_node_status_t *status,
uint8_t *buf, size_t buf_cap)
{
if (status == NULL) return 0;
return rv_mesh_encode(RV_MSG_HEALTH, sender_role, RV_AUTH_NONE,
epoch, status, sizeof(*status), buf, buf_cap);
}
size_t rv_mesh_encode_anomaly_alert(uint8_t sender_role,
uint32_t epoch,
const rv_anomaly_alert_t *alert,
uint8_t *buf, size_t buf_cap)
{
if (alert == NULL) return 0;
return rv_mesh_encode(RV_MSG_ANOMALY_ALERT, sender_role, RV_AUTH_NONE,
epoch, alert, sizeof(*alert), buf, buf_cap);
}
size_t rv_mesh_encode_feature_delta(uint8_t sender_role,
uint32_t epoch,
const rv_feature_state_t *fs,
uint8_t *buf, size_t buf_cap)
{
if (fs == NULL) return 0;
return rv_mesh_encode(RV_MSG_FEATURE_DELTA, sender_role, RV_AUTH_NONE,
epoch, fs, sizeof(*fs), buf, buf_cap);
}
size_t rv_mesh_encode_time_sync(uint8_t sender_role,
uint32_t epoch,
const rv_time_sync_t *ts,
uint8_t *buf, size_t buf_cap)
{
if (ts == NULL) return 0;
return rv_mesh_encode(RV_MSG_TIME_SYNC, sender_role, RV_AUTH_HMAC_SESSION,
epoch, ts, sizeof(*ts), buf, buf_cap);
}
size_t rv_mesh_encode_role_assign(uint8_t sender_role,
uint32_t epoch,
const rv_role_assign_t *ra,
uint8_t *buf, size_t buf_cap)
{
if (ra == NULL) return 0;
return rv_mesh_encode(RV_MSG_ROLE_ASSIGN, sender_role, RV_AUTH_HMAC_SESSION,
epoch, ra, sizeof(*ra), buf, buf_cap);
}
size_t rv_mesh_encode_channel_plan(uint8_t sender_role,
uint32_t epoch,
const rv_channel_plan_t *cp,
uint8_t *buf, size_t buf_cap)
{
if (cp == NULL) return 0;
return rv_mesh_encode(RV_MSG_CHANNEL_PLAN, sender_role, RV_AUTH_ED25519_BATCH,
epoch, cp, sizeof(*cp), buf, buf_cap);
}
size_t rv_mesh_encode_calibration_start(uint8_t sender_role,
uint32_t epoch,
const rv_calibration_start_t *cs,
uint8_t *buf, size_t buf_cap)
{
if (cs == NULL) return 0;
return rv_mesh_encode(RV_MSG_CALIBRATION_START, sender_role,
RV_AUTH_ED25519_BATCH, epoch, cs, sizeof(*cs),
buf, buf_cap);
}
/* ---- Send helpers (firmware-only; hidden from host tests) ---- */
#ifndef RV_MESH_HOST_TEST
esp_err_t rv_mesh_send(const uint8_t *frame, size_t len)
{
if (frame == NULL || len == 0) return ESP_ERR_INVALID_ARG;
int sent = stream_sender_send(frame, len);
if (sent < 0) {
ESP_LOGW(TAG, "rv_mesh_send: stream_sender failed (len=%u)",
(unsigned)len);
return ESP_FAIL;
}
return ESP_OK;
}
esp_err_t rv_mesh_send_health(uint8_t role, uint32_t epoch,
const uint8_t node_id[8])
{
if (node_id == NULL) return ESP_ERR_INVALID_ARG;
rv_node_status_t st;
memset(&st, 0, sizeof(st));
memcpy(st.node_id, node_id, 8);
st.local_time_us = (uint64_t)esp_timer_get_time();
st.role = role;
const rv_radio_ops_t *ops = rv_radio_ops_get();
if (ops != NULL && ops->get_health != NULL) {
rv_radio_health_t h;
if (ops->get_health(&h) == ESP_OK) {
st.current_channel = h.current_channel;
st.current_bw = h.current_bw_mhz;
st.noise_floor_dbm = h.noise_floor_dbm;
st.pkt_yield = h.pkt_yield_per_sec;
}
}
uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
size_t n = rv_mesh_encode_health(role, epoch, &st, buf, sizeof(buf));
if (n == 0) return ESP_FAIL;
return rv_mesh_send(buf, n);
}
esp_err_t rv_mesh_send_anomaly(uint8_t role, uint32_t epoch,
const uint8_t node_id[8],
uint8_t reason,
uint8_t severity,
float anomaly_score,
float motion_score)
{
if (node_id == NULL) return ESP_ERR_INVALID_ARG;
rv_anomaly_alert_t a;
memset(&a, 0, sizeof(a));
memcpy(a.node_id, node_id, 8);
a.ts_us = (uint64_t)esp_timer_get_time();
a.reason = reason;
a.severity = severity;
a.anomaly_score = anomaly_score;
a.motion_score = motion_score;
uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
size_t n = rv_mesh_encode_anomaly_alert(role, epoch, &a, buf, sizeof(buf));
if (n == 0) return ESP_FAIL;
return rv_mesh_send(buf, n);
}
#endif /* !RV_MESH_HOST_TEST */

296
firmware/esp32-csi-node/main/rv_mesh.h Normal file
View file

@ -0,0 +1,296 @@
/**
* @file rv_mesh.h
* @brief ADR-081 Layer 3 — Mesh Sensing Plane.
*
* Defines node roles, the 7 on-wire message types, and the
* rv_node_status_t health payload that nodes exchange to behave as a
* distributed sensor rather than a collection of independent radios.
*
* Framing: every mesh message starts with rv_mesh_header_t (magic,
* version, type, sender_role, epoch, length) so a receiver can dispatch
* without reading the whole body. The trailing 4 bytes of every message
* are an IEEE CRC32 over the preceding bytes. Authentication
* (HMAC-SHA256 + replay window) is layered on top by
* wifi-densepose-hardware/src/esp32/secure_tdm.rs (ADR-032) for control
* messages that cross the swarm; FEATURE_DELTA uses the integrity
* protection already present in rv_feature_state_t (CRC + monotonic seq).
*/
#ifndef RV_MESH_H
#define RV_MESH_H
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "esp_err.h"
#include "rv_feature_state.h"
#ifdef __cplusplus
extern "C" {
#endif
/* ---- Magic + version ---- */
/** ADR-081 mesh envelope magic. Distinct from the ADR-018 CSI magic. */
#define RV_MESH_MAGIC 0xC5118100u
/** Protocol version. Bumped on any wire-format change. */
#define RV_MESH_VERSION 1u
/** Maximum mesh payload size (excluding header + CRC). */
#define RV_MESH_MAX_PAYLOAD 256u
/* ---- Node roles (ADR-081 Layer 3) ---- */
typedef enum {
RV_ROLE_UNASSIGNED = 0,
RV_ROLE_ANCHOR = 1, /**< Emits timed probes + global time beacons. */
RV_ROLE_OBSERVER = 2, /**< Captures CSI + local metadata. */
RV_ROLE_FUSION_RELAY = 3, /**< Aggregates summaries, forwards deltas. */
RV_ROLE_COORDINATOR = 4, /**< Elects channels, assigns roles. */
RV_ROLE_COUNT
} rv_mesh_role_t;
/* ---- Authorization classes for control messages ---- */
typedef enum {
RV_AUTH_NONE = 0, /**< Telemetry; integrity via CRC only. */
RV_AUTH_HMAC_SESSION = 1, /**< HMAC-SHA256 with session key (ADR-032). */
RV_AUTH_ED25519_BATCH = 2, /**< Ed25519 signature at batch/session. */
} rv_mesh_auth_class_t;
/* ---- Message types ---- */
typedef enum {
RV_MSG_TIME_SYNC = 0x01,
RV_MSG_ROLE_ASSIGN = 0x02,
RV_MSG_CHANNEL_PLAN = 0x03,
RV_MSG_CALIBRATION_START = 0x04,
RV_MSG_FEATURE_DELTA = 0x05, /**< Carries rv_feature_state_t. */
RV_MSG_HEALTH = 0x06,
RV_MSG_ANOMALY_ALERT = 0x07,
} rv_mesh_msg_type_t;
/* ---- Common envelope header (16 bytes) ---- */
typedef struct __attribute__((packed)) {
uint32_t magic; /**< RV_MESH_MAGIC. */
uint8_t version; /**< RV_MESH_VERSION. */
uint8_t type; /**< rv_mesh_msg_type_t. */
uint8_t sender_role; /**< rv_mesh_role_t of the sender at send time. */
uint8_t auth_class; /**< rv_mesh_auth_class_t. */
uint32_t epoch; /**< Monotonic epoch or session counter. */
uint16_t payload_len; /**< Body length excluding header + trailing CRC. */
uint16_t reserved;
} rv_mesh_header_t;
_Static_assert(sizeof(rv_mesh_header_t) == 16,
"rv_mesh_header_t must be 16 bytes");
/* ---- Node health payload (RV_MSG_HEALTH) ---- */
typedef struct __attribute__((packed)) {
uint8_t node_id[8]; /**< 8-byte node identity. */
uint64_t local_time_us; /**< Sender-local microseconds. */
uint8_t role; /**< rv_mesh_role_t. */
uint8_t current_channel;
uint8_t current_bw; /**< MHz (20, 40). */
int8_t noise_floor_dbm;
uint16_t pkt_yield; /**< CSI callbacks/sec over the last window. */
uint16_t sync_error_us; /**< Absolute drift vs. anchor. */
uint16_t health_flags;
uint16_t reserved;
} rv_node_status_t;
_Static_assert(sizeof(rv_node_status_t) == 28,
"rv_node_status_t must be 28 bytes");
/* ---- TIME_SYNC payload ---- */
typedef struct __attribute__((packed)) {
uint64_t anchor_time_us; /**< Anchor's local µs at emit. */
uint32_t cycle_id;
uint32_t cycle_period_us;
} rv_time_sync_t;
_Static_assert(sizeof(rv_time_sync_t) == 16,
"rv_time_sync_t must be 16 bytes");
/* ---- ROLE_ASSIGN payload ---- */
typedef struct __attribute__((packed)) {
uint8_t target_node_id[8];
uint8_t new_role; /**< rv_mesh_role_t. */
uint8_t reserved[3];
uint32_t effective_epoch;
} rv_role_assign_t;
_Static_assert(sizeof(rv_role_assign_t) == 16,
"rv_role_assign_t must be 16 bytes");
/* ---- CHANNEL_PLAN payload ---- */
#define RV_CHANNEL_PLAN_MAX 8
typedef struct __attribute__((packed)) {
uint8_t target_node_id[8];
uint8_t channel_count;
uint8_t dwell_ms_hi; /**< dwell_ms, big-endian to fit u16 in two bytes */
uint8_t dwell_ms_lo;
uint8_t debug_raw_csi; /**< 1 = enable raw ADR-018 stream; 0 = feature_state only. */
uint8_t channels[RV_CHANNEL_PLAN_MAX];
uint32_t effective_epoch;
} rv_channel_plan_t;
_Static_assert(sizeof(rv_channel_plan_t) == 24,
"rv_channel_plan_t must be 24 bytes");
/* ---- CALIBRATION_START payload ---- */
typedef struct __attribute__((packed)) {
uint64_t t0_anchor_us; /**< Start time on anchor clock. */
uint32_t duration_ms;
uint32_t effective_epoch;
uint8_t calibration_profile; /**< rv_capture_profile_t (usually CALIBRATION). */
uint8_t reserved[3];
} rv_calibration_start_t;
_Static_assert(sizeof(rv_calibration_start_t) == 20,
"rv_calibration_start_t must be 20 bytes");
/* ---- ANOMALY_ALERT payload ---- */
typedef struct __attribute__((packed)) {
uint8_t node_id[8];
uint64_t ts_us;
uint8_t severity; /**< 0..255 scaled anomaly. */
uint8_t reason; /**< rv_anomaly_reason_t. */
uint16_t reserved;
float anomaly_score;
float motion_score;
} rv_anomaly_alert_t;
_Static_assert(sizeof(rv_anomaly_alert_t) == 28,
"rv_anomaly_alert_t must be 28 bytes");
typedef enum {
RV_ANOMALY_NONE = 0,
RV_ANOMALY_PHYSICS_VIOLATION = 1,
RV_ANOMALY_MULTI_LINK_MISMATCH = 2,
RV_ANOMALY_PKT_YIELD_COLLAPSE = 3,
RV_ANOMALY_FALL = 4,
RV_ANOMALY_COHERENCE_LOSS = 5,
} rv_anomaly_reason_t;
/* ---- Encoder / decoder API ---- */
/** Maximum on-wire mesh frame: header + max payload + crc. */
#define RV_MESH_MAX_FRAME_BYTES (sizeof(rv_mesh_header_t) + RV_MESH_MAX_PAYLOAD + 4u)
/**
* Encode a typed mesh message into a contiguous buffer.
*
* Writes header(16) + payload(payload_len) + crc32(4). The caller owns
* the buffer; buf_cap must be at least sizeof(rv_mesh_header_t) +
* payload_len + 4. The payload pointer may be NULL iff payload_len == 0.
*
* @return bytes written on success, or 0 on error (bad args / overflow).
*/
size_t rv_mesh_encode(uint8_t type,
uint8_t sender_role,
uint8_t auth_class,
uint32_t epoch,
const void *payload,
uint16_t payload_len,
uint8_t *buf,
size_t buf_cap);
/**
* Validate + parse a mesh frame received from the wire.
*
* Checks magic, version, sizeof(rv_mesh_header_t) bounds, payload_len
* bounds, and CRC32. On success, fills *out_hdr with the header and sets
* *out_payload to point at the payload inside buf (aliasing, not copied)
* plus *out_payload_len to the payload byte count.
*
* @return ESP_OK on success, or an ESP_ERR_* code on failure.
*/
esp_err_t rv_mesh_decode(const uint8_t *buf, size_t buf_len,
rv_mesh_header_t *out_hdr,
const uint8_t **out_payload,
uint16_t *out_payload_len);
/**
* Convenience helpers — encode a specific message type into buf.
* Each returns the number of bytes written, 0 on error.
*/
size_t rv_mesh_encode_health(uint8_t sender_role,
uint32_t epoch,
const rv_node_status_t *status,
uint8_t *buf, size_t buf_cap);
size_t rv_mesh_encode_anomaly_alert(uint8_t sender_role,
uint32_t epoch,
const rv_anomaly_alert_t *alert,
uint8_t *buf, size_t buf_cap);
size_t rv_mesh_encode_feature_delta(uint8_t sender_role,
uint32_t epoch,
const rv_feature_state_t *fs,
uint8_t *buf, size_t buf_cap);
size_t rv_mesh_encode_time_sync(uint8_t sender_role,
uint32_t epoch,
const rv_time_sync_t *ts,
uint8_t *buf, size_t buf_cap);
size_t rv_mesh_encode_role_assign(uint8_t sender_role,
uint32_t epoch,
const rv_role_assign_t *ra,
uint8_t *buf, size_t buf_cap);
size_t rv_mesh_encode_channel_plan(uint8_t sender_role,
uint32_t epoch,
const rv_channel_plan_t *cp,
uint8_t *buf, size_t buf_cap);
size_t rv_mesh_encode_calibration_start(uint8_t sender_role,
uint32_t epoch,
const rv_calibration_start_t *cs,
uint8_t *buf, size_t buf_cap);
/* ---- Send API ---- */
/**
* Send a pre-encoded mesh frame over the primary upstream UDP socket
* (the same one stream_sender uses for ADR-018 and rv_feature_state_t).
*
* @return ESP_OK on success.
*/
esp_err_t rv_mesh_send(const uint8_t *frame, size_t len);
/**
* Convenience: build + send a HEALTH message for this node.
*
* Fills the rv_node_status_t from the live radio ops + controller
* observation, then encodes and sends in one call. Safe to call from a
* FreeRTOS timer.
*/
esp_err_t rv_mesh_send_health(uint8_t role, uint32_t epoch,
const uint8_t node_id[8]);
/**
* Convenience: build + send an ANOMALY_ALERT.
*/
esp_err_t rv_mesh_send_anomaly(uint8_t role, uint32_t epoch,
const uint8_t node_id[8],
uint8_t reason,
uint8_t severity,
float anomaly_score,
float motion_score);
#ifdef __cplusplus
}
#endif
#endif /* RV_MESH_H */