mirror of
https://github.com/alexhopeoconnor/firmware.git
synced 2026-10-17 09:01:30 +10:00
docs: move the firmware design docs to the documentation site (#11488)
The five documents under docs/ were written in this repo while their features
were developed. Four of them describe shipped, upstream behaviour and belong on
meshtastic.org, where users and client authors will look for them:
traffic_management_module.md -> configuration/module/traffic-management
+ development/reference/traffic-management-internals
node_info_stores.md -> development/reference/node-info-stores
mesh_beacon_module.md -> configuration/module/mesh-beacon
+ development/reference/mesh-beacon-internals
+ development/device/mesh-beacon-client-interface
lora_region_preset_compatibility_client_spec.md
-> development/device/region-preset-compatibility
Each is split by audience: settings pages carry the config surface in user
terms, reference pages carry firmware mechanism, and the device pages carry the
protocol a client app speaks. The region-preset spec always said it should
graduate out of this repo once its protobuf landed upstream, which it has
(FromRadio.region_presets, field 19).
nexthop-routing-reliability.md is not documentation - it is a working document
with a mitigation plan, a "files to modify" list and commit sequencing. Its
mitigations shipped in #10745, so the plan is history and the analysis is
superseded; it is dropped rather than published.
Comments that cited the deleted files now point at the published pages, and the
NextHop test header cites #10745 instead of the deleted plan.
This commit is contained in:
@@ -586,7 +586,8 @@ void TrafficManagementModule::reconcileNodeInfoFromNodeDBLocked()
|
||||
|
||||
// Membership refresh (this hourly pass owns it): clear every isMember bit, then re-mark from
|
||||
// both NodeDB tiers. Runs AFTER seeding so the upsert still sees last pass's bits (spareMembers).
|
||||
// Cost/lag rationale in docs/node_info_stores.md "Consistency with NodeDB (anti-entropy)".
|
||||
// Cost/lag rationale in https://meshtastic.org/docs/development/reference/node-info-stores "Consistency with NodeDB
|
||||
// (anti-entropy)".
|
||||
for (uint16_t i = 0; i < nodeInfoTargetEntries(); i++)
|
||||
nodeInfoPayload[i].isMember = false;
|
||||
for (size_t i = 0; i < nodeDB->getNumMeshNodes(); i++) {
|
||||
@@ -729,7 +730,8 @@ bool TrafficManagementModule::copyPublicKey(NodeNum node, uint8_t out[32], bool
|
||||
{
|
||||
// Same enable gate as the write-through hooks and maintenance: a disabled module stops
|
||||
// updating and sweeping the cache, so its frozen contents must not keep feeding PKI key
|
||||
// resolution either. Enforces the "superset only while enabled" corollary (node_info_stores.md).
|
||||
// resolution either. Enforces the "superset only while enabled" corollary
|
||||
// (https://meshtastic.org/docs/development/reference/node-info-stores).
|
||||
if (!moduleConfig.has_traffic_management)
|
||||
return false;
|
||||
if (!nodeInfoPayload || node == 0 || !out)
|
||||
@@ -1514,7 +1516,8 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
|
||||
|
||||
// Throttle the spoofed reply (per requester + per target + 1 s global floor; checked here so a
|
||||
// request declined above never spends the budget). false forwards the request instead of consuming
|
||||
// it. Rationale in docs/traffic_management_module.md "Throttling direct responses".
|
||||
// it. Rationale in https://meshtastic.org/docs/development/reference/traffic-management-internals "Throttling direct
|
||||
// responses".
|
||||
if (!directResponseAllowed(getFrom(p), p->to, clockMs())) {
|
||||
TM_LOG_DEBUG("NodeInfo direct response throttled for 0x%08x; forwarding request", getFrom(p));
|
||||
return false;
|
||||
|
||||
@@ -33,7 +33,8 @@
|
||||
|
||||
/// Packet inspection and traffic shaping: position dedup, per-node rate limiting, unknown-packet
|
||||
/// filtering, NodeInfo direct response, and the next-hop/role overflow caches. One flat 10-byte
|
||||
/// unified cache backs all per-node features; see docs/node_info_stores.md for the store overview.
|
||||
/// unified cache backs all per-node features; see https://meshtastic.org/docs/development/reference/node-info-stores for the
|
||||
/// store overview.
|
||||
class TrafficManagementModule : public MeshModule, private concurrency::OSThread
|
||||
{
|
||||
public:
|
||||
@@ -144,7 +145,8 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
|
||||
private:
|
||||
// 10-byte packed entry, all platforms. Tick stamps are free-running modular counters with
|
||||
// non-zero presence sentinels; the 4-bit cached role rides the top bits of the two count
|
||||
// bytes (tier-3 role fallback). Full layout and rationale: docs/node_info_stores.md.
|
||||
// bytes (tier-3 role fallback). Full layout and rationale:
|
||||
// https://meshtastic.org/docs/development/reference/node-info-stores.
|
||||
#if _meshtastic_Config_DeviceConfig_Role_MAX > 15
|
||||
#warning "Device role enum max exceeds 15 - TMM 4-bit role cache (rate_count[7:6]/unknown_count[7:6]) will truncate new values"
|
||||
#endif
|
||||
@@ -347,12 +349,14 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
|
||||
|
||||
/// 60 s NodeInfo-cache maintenance under cacheLock: saturate the expired obsTick stamp (wrap-safety
|
||||
/// for the modular clock) and run the boot/hourly reconcile. Guarded by TMM_HAS_NODEINFO_CACHE alone
|
||||
/// (never the unified cache size); see docs/node_info_stores.md "Tick clocks and wrap safety".
|
||||
/// (never the unified cache size); see https://meshtastic.org/docs/development/reference/node-info-stores "Tick clocks and
|
||||
/// wrap safety".
|
||||
void maintainNodeInfoCacheLocked();
|
||||
|
||||
/// Anti-entropy under cacheLock: upsert hot-store + warm-tier records this cache lacks (never sets
|
||||
/// hasObserved - seeding is knowledge, not observation), and refresh isMember from both NodeDB
|
||||
/// tiers. Cost/lag: docs/node_info_stores.md "Consistency with NodeDB (anti-entropy)".
|
||||
/// tiers. Cost/lag: https://meshtastic.org/docs/development/reference/node-info-stores "Consistency with NodeDB
|
||||
/// (anti-entropy)".
|
||||
void reconcileNodeInfoFromNodeDBLocked();
|
||||
/// Learn an observed NODEINFO frame into the cache (key hygiene + provenance rules apply).
|
||||
void cacheNodeInfoPacket(const meshtastic_MeshPacket &mp);
|
||||
@@ -368,7 +372,8 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
|
||||
|
||||
// Direct-response throttles bounding the reflector risk of spoofed replies: three fixed bounds
|
||||
// (per requester, per target, 1 s global airtime floor) via 8-slot LRU RAM tables, wrap-safe and
|
||||
// PSRAM-agnostic. Design & rationale: docs/traffic_management_module.md "Throttling direct responses".
|
||||
// PSRAM-agnostic. Design & rationale: https://meshtastic.org/docs/development/reference/traffic-management-internals
|
||||
// "Throttling direct responses".
|
||||
static constexpr uint32_t kDirectResponsePerRequesterMs = 60'000UL;
|
||||
static constexpr uint32_t kDirectResponsePerTargetMs = 60'000UL;
|
||||
static constexpr uint32_t kDirectResponseGlobalMs = 1'000UL;
|
||||
|
||||
Reference in New Issue
Block a user