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:
Tom
2026-08-13 16:25:03 +02:00
committed by GitHub
parent c5d3321a41
commit 6745995442
8 changed files with 17 additions and 1755 deletions
+6 -3
View File
@@ -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;
+10 -5
View File
@@ -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;