npr::rf::SlaveMacEngine class final
#include <npr/mac/slave_mac_engine.hpp>

Main slave-side NPR MAC engine.

Owns NPR protocol state machines, TX frame planning policy, and IPv4 segmentation/reassembly queues.

Core idea:

Runtime remains orchestration-only and asks this engine for decisions.
This engine converts current radio/network state into deterministic TX plans and consumes TX feedback to update policy.
Uplink demand advertised to master is intentionally smoothed (fast attack + slow decay) to keep slot allocation stable for bursty traffic patterns (for example MQTT or sporadic ICMP bursts).

Runtime drives it in loop order: process RX -> tick policy -> ask for TX plans -> feed TX results back.

Base classes

class IMacEngine: Thin role-neutral MAC boundary used by NprRuntime.

Public functions

auto allocation_age_us(uint64_t now_us) const -> uint64_t override: Delegated allocation age from TdmaSyncState.
auto allocation_valid(uint64_t now_us) const -> bool: Delegated allocation validity from TdmaSyncState.
auto client_id() const -> uint8_t override: Returns currently assigned local client id.
auto connected() const -> bool override: Returns current connection state.
auto consume_ipv4_downlink_packet() -> bool override: Releases one downlink IPv4 packet after successful runtime handoff.
auto downlink_queue_size() const -> size_t: Number of packets currently queued for downlink handoff to host.
auto enqueue_ipv4_uplink_packet(const uint8_t* packet, size_t packet_size) -> bool override: Enqueues host IPv4 packet for uplink segmentation.
auto init(const MacInitParams& params) -> bool override: Initializes engine from role-neutral runtime context.
auto init(const RadioProfile& profile, NprDiagnostics& diagnostics, NprFrameCodec& codec, const uint8_t callsign_prefix[2], const char* callsign_suffix, uint32_t requested_ip_size, uint32_t min_requested_ip_size, uint64_t who_cadence_us, uint64_t reassembly_timeout_us, uint64_t unslotted_wake_interval_us, uint8_t unslotted_wake_burst_count) -> bool: Initializes engine with profile, codecs, identity and policy parameters.
void log_signaling_stats_periodic(uint64_t now_us) override: Emits periodic signaling/neighbor stats logs.
auto network_config_snapshot(NprNetworkConfig* out) const -> bool override: Copies current network config snapshot.
auto next_slot_start_us(uint64_t now_us, uint64_t* out_slot_start_us) const -> bool: Computes next slot start according to current sync/allocation state.
auto on_slot_burst_plan_result(const SlaveMacSlotBurstPlanResult& plan) -> SlaveMacSlotBurstPlanAction override: Classifies one burst plan output into runtime action and applies MAC failure accounting.
auto on_slot_burst_tx_result(const SlaveMacSlotBurstTxFeedback& feedback) -> bool override: Applies PHY TX result to MAC state and returns true when burst should continue.
void on_tx_failure() override: Notifies MAC about failed frame TX attempt.
void on_tx_success(SlotTxFrameKind kind, uint64_t now_us) override: Notifies MAC about successful frame TX.
void on_unslotted_connect_tx_result(SlaveMacUnslottedConnectAction action, bool sent, uint64_t now_us): Feeds result of unslotted connect/wake transmission back to MAC state.
void on_unslotted_tx_result(MacUnslottedAction action, bool sent, uint64_t now_us) override: Role-neutral runtime-facing alias for unslotted TX feedback.
auto peek_ipv4_downlink_packet(uint8_t* out, size_t out_capacity, size_t* out_size) const -> bool override: Copies the current front downlink IPv4 packet without consuming it.
void periodic(uint64_t now_us, uint32_t* out_reassembly_timeout_drops): Runs periodic maintenance (timeouts, keepalives, WHO cadence).
auto plan_slot_burst_frame(const SlaveMacSlotBurstPlanInput& in, SlaveMacSlotBurstPlanResult* out) -> bool: Plans one frame for ongoing slot burst utilization.
auto plan_slot_burst_tx(const MacSlotBurstPlanInput& in, MacSlotBurstPlanResult* out) -> bool override: Role-neutral runtime-facing alias for slotted burst planning.
auto plan_slot_frame(const SlaveMacSlotPlanInput& in, SlaveMacSlotPlanResult* out) -> bool: Plans one frame for one allocated slot.
auto plan_unslotted_connect_frame(uint64_t now_us, SlaveMacUnslottedConnectAction action, SlaveMacUnslottedConnectTxPlan* out) -> bool: Builds full unslotted connect/wake transmit plan for runtime.
auto plan_unslotted_connect_request(uint8_t uplink_buffer_state, bool top_flag, uint8_t* out_frame, size_t out_capacity, size_t* out_size) -> bool: Builds CONNECT_REQ frame directly (helper for unslotted paths).
auto plan_unslotted_disconnect_request(uint8_t uplink_buffer_state, bool top_flag, uint8_t* out_frame, size_t out_capacity, size_t* out_size) -> bool: Builds DISCONNECT_REQ frame directly (helper for explicit disconnect path).
auto plan_unslotted_tx(uint64_t now_us, MacUnslottedAction action, MacUnslottedTxPlan* out) -> bool override: Role-neutral runtime-facing alias for unslotted frame planning.
auto process_received_packet(const uint8_t* packet, size_t packet_size, uint64_t packet_time_us, bool local_rssi_valid, uint8_t local_rssi, SlaveMacRxProcessResult* out) -> bool override: Processes one PHY RX packet and updates MAC state.
auto queued_ipv4_pending_frames() const -> uint8_t: Returns estimated pending frame count to advertise in TDMA low-5 demand.
void request_disconnect(uint64_t now_us): Starts explicit disconnect handshake from connected state.
void reset(uint64_t now_us) override: Resets dynamic MAC state while keeping static configuration.
auto should_continue_slot_burst(uint32_t sent_in_slot, uint64_t now_us, const SlotTxTimeBudget& slot_budget) const -> bool override: Returns true when MAC policy allows planning another frame in current slot burst.
auto should_send_connect_req(uint64_t now_us) const -> bool: Returns whether CONNECT_REQ should be sent now.
auto should_send_disconnect_req(uint64_t now_us) const -> bool: Returns whether explicit disconnect request should be sent now.
auto should_transmit_in_allocated_slot(uint64_t now_us) const -> bool: Returns whether this node should transmit in allocated slots at current time.
auto slot_budget_us() const -> uint32_t override: Returns currently available slot budget in microseconds.
auto sync_age_us(uint64_t now_us) const -> uint64_t override: Delegated sync age from TdmaSyncState.
auto sync_valid(uint64_t now_us) const -> bool: Delegated TDMA sync validity from TdmaSyncState.
void tick(const SlaveMacTickInput& input, SlaveMacTickPlan* out_plan) override: Computes one-step MAC execution plan for runtime.
auto who_cache_snapshot(SignalingWhoEntry* out_entries, size_t max_entries) const -> size_t override: Copies active WHO cache entries for external observability consumers.
auto who_pending() const -> bool: Returns whether WHO frame is currently pending.

Function documentation

bool npr::rf::SlaveMacEngine::init(const RadioProfile& profile, NprDiagnostics& diagnostics, NprFrameCodec& codec, const uint8_t callsign_prefix[2], const char* callsign_suffix, uint32_t requested_ip_size, uint32_t min_requested_ip_size, uint64_t who_cadence_us, uint64_t reassembly_timeout_us, uint64_t unslotted_wake_interval_us, uint8_t unslotted_wake_burst_count)

Initializes engine with profile, codecs, identity and policy parameters.

Returns	`true` on success.

bool npr::rf::SlaveMacEngine::on_slot_burst_tx_result(const SlaveMacSlotBurstTxFeedback& feedback) override

Applies PHY TX result to MAC state and returns true when burst should continue.

This centralizes TX success/failure accounting and slot-overrun stop policy.

bool npr::rf::SlaveMacEngine::plan_slot_burst_frame(const SlaveMacSlotBurstPlanInput& in, SlaveMacSlotBurstPlanResult* out)

Plans one frame for ongoing slot burst utilization.

Uses current MAC policy (signaling vs IPv4 vs NULL) and slot budget hints.

bool npr::rf::SlaveMacEngine::process_received_packet(const uint8_t* packet, size_t packet_size, uint64_t packet_time_us, bool local_rssi_valid, uint8_t local_rssi, SlaveMacRxProcessResult* out) override

Processes one PHY RX packet and updates MAC state.

Parameters
packet	Raw on-air packet bytes.
packet_size	Packet size in bytes.
packet_time_us	Packet timestamp from PHY capture.
local_rssi_valid	Whether local RSSI sample is valid.
local_rssi	Local RSSI sample.
out	Optional derived effects for runtime/PHY feedback.
Returns	`true` when packet was syntactically processed.

bool npr::rf::SlaveMacEngine::should_continue_slot_burst(uint32_t sent_in_slot, uint64_t now_us, const SlotTxTimeBudget& slot_budget) const override

Returns true when MAC policy allows planning another frame in current slot burst.

Applies only policy gates (max frames per burst, absolute slot budget end).

npr::rf::SlaveMacEngine class final #include <npr/mac/slave_mac_engine.hpp>