From c2c4203b25b83144d886fbd0e99b6f2d340fa58d Mon Sep 17 00:00:00 2001 From: FlowmemoryAI <283694809+FlowmemoryAI@users.noreply.github.com> Date: Wed, 13 May 2026 00:39:06 -0500 Subject: [PATCH] Add FlowRouter V0 POC hardware package --- docs/DECISIONS/0001-flowrouter-v0-scope.md | 35 ++ docs/SECURITY_MODEL.md | 10 + hardware/README.md | 53 +++ hardware/field-tests/README.md | 18 + .../TWO_NODE_MESHTASTIC_FIELD_TEST.md | 85 ++++ .../fixtures/flowrouter_sample_seed42.json | 200 +++++++++ hardware/flowrouter/ASSEMBLY.md | 106 +++++ hardware/flowrouter/BOM.md | 195 +++++++++ hardware/flowrouter/ENCLOSURE_CONCEPT_V0.md | 111 +++++ hardware/flowrouter/FLOWCORE_LIGHT_PIPE.md | 62 +++ hardware/flowrouter/FLOWROUTER_V0_SCOPE.md | 220 ++++++++++ hardware/flowrouter/MEASUREMENT_CHECKLIST.md | 128 ++++++ hardware/flowrouter/PRINTING_GUIDE.md | 98 +++++ hardware/flowrouter/README.md | 61 +++ .../lora-sidecar/CONTROL_MESSAGE_INVENTORY.md | 106 +++++ hardware/lora-sidecar/README.md | 95 +++++ hardware/lora-sidecar/TWO_NODE_DEMO_PLAN.md | 90 +++++ .../memory-cartridges/NFC_CARTRIDGE_V0.md | 89 ++++ hardware/memory-cartridges/README.md | 82 ++++ hardware/simulator/README.md | 33 ++ hardware/simulator/flowrouter_sim.py | 381 ++++++++++++++++++ .../schemas/compact_receipt_relay.schema.json | 22 + .../schemas/dashboard_feed.schema.json | 19 + .../schemas/device_manifest.schema.json | 17 + .../emergency_offline_signal.schema.json | 20 + .../flowpulse_digest_relay.schema.json | 22 + .../schemas/gateway_discovery.schema.json | 20 + .../simulator/schemas/heartbeat.schema.json | 21 + .../schemas/local_cache_status.schema.json | 24 ++ .../nfc_memory_cartridge_metadata.schema.json | 19 + .../schemas/sidecar_status.schema.json | 23 ++ .../verifier_report_digest_relay.schema.json | 20 + .../FLOWNET_BOUNDARIES.md | 106 +++++ research/meshtastic/MESHTASTIC_ROLE.md | 70 ++++ 34 files changed, 2661 insertions(+) create mode 100644 docs/DECISIONS/0001-flowrouter-v0-scope.md create mode 100644 hardware/README.md create mode 100644 hardware/field-tests/README.md create mode 100644 hardware/field-tests/TWO_NODE_MESHTASTIC_FIELD_TEST.md create mode 100644 hardware/fixtures/flowrouter_sample_seed42.json create mode 100644 hardware/flowrouter/ASSEMBLY.md create mode 100644 hardware/flowrouter/BOM.md create mode 100644 hardware/flowrouter/ENCLOSURE_CONCEPT_V0.md create mode 100644 hardware/flowrouter/FLOWCORE_LIGHT_PIPE.md create mode 100644 hardware/flowrouter/FLOWROUTER_V0_SCOPE.md create mode 100644 hardware/flowrouter/MEASUREMENT_CHECKLIST.md create mode 100644 hardware/flowrouter/PRINTING_GUIDE.md create mode 100644 hardware/flowrouter/README.md create mode 100644 hardware/lora-sidecar/CONTROL_MESSAGE_INVENTORY.md create mode 100644 hardware/lora-sidecar/README.md create mode 100644 hardware/lora-sidecar/TWO_NODE_DEMO_PLAN.md create mode 100644 hardware/memory-cartridges/NFC_CARTRIDGE_V0.md create mode 100644 hardware/memory-cartridges/README.md create mode 100644 hardware/simulator/README.md create mode 100644 hardware/simulator/flowrouter_sim.py create mode 100644 hardware/simulator/schemas/compact_receipt_relay.schema.json create mode 100644 hardware/simulator/schemas/dashboard_feed.schema.json create mode 100644 hardware/simulator/schemas/device_manifest.schema.json create mode 100644 hardware/simulator/schemas/emergency_offline_signal.schema.json create mode 100644 hardware/simulator/schemas/flowpulse_digest_relay.schema.json create mode 100644 hardware/simulator/schemas/gateway_discovery.schema.json create mode 100644 hardware/simulator/schemas/heartbeat.schema.json create mode 100644 hardware/simulator/schemas/local_cache_status.schema.json create mode 100644 hardware/simulator/schemas/nfc_memory_cartridge_metadata.schema.json create mode 100644 hardware/simulator/schemas/sidecar_status.schema.json create mode 100644 hardware/simulator/schemas/verifier_report_digest_relay.schema.json create mode 100644 research/decentralized-internet/FLOWNET_BOUNDARIES.md create mode 100644 research/meshtastic/MESHTASTIC_ROLE.md diff --git a/docs/DECISIONS/0001-flowrouter-v0-scope.md b/docs/DECISIONS/0001-flowrouter-v0-scope.md new file mode 100644 index 00000000..c6d35d02 --- /dev/null +++ b/docs/DECISIONS/0001-flowrouter-v0-scope.md @@ -0,0 +1,35 @@ +# Decision 0001: FlowRouter V0 Scope + +Date: 2026-05-13 + +## Status + +Accepted for V0 research package. + +## Context + +FlowRouter needs to be concrete enough for hardware, dashboard, services, and field-test agents to share packet shapes and operational assumptions. It also needs strict boundaries so the project does not overclaim internet replacement, production manufacturing, hardware trustlessness, appchain operation, or LoRa bandwidth. + +## Decision + +FlowRouter V0 is a production-shaped proof-of-concept package built around certified commodity router/radio hardware, Raspberry Pi or mini PC compute, NVMe/local cache, Meshtastic/LoRa control signaling, NFC Memory Cartridge metadata, FlowCore light-pipe status, local dashboard feeds, simulator packets, and controlled field-test plans. + +V0 packet schemas and simulator outputs are advisory interfaces for later consumers. They are not production protocol commitments. + +## Boundaries + +- No ISP replacement claim. +- No broadband over LoRa/Meshtastic. +- No custom RF board or antenna design. +- No production manufacturing commitment. +- No passive income promise. +- No full trustlessness claim. +- No production L1/appchain operation. +- No validator or data availability role for hardware nodes. +- No final CAD until physical measurements are sufficient. + +## Consequences + +- Hardware work can advance through docs, schemas, fixtures, simulator output, and field-test plans before physical CAD. +- Future services and dashboards can consume deterministic sample feeds without depending on hardware availability. +- Hardware security assumptions remain conservative: physical tampering, spoofing, replay, unauthenticated messages, sidecar bandwidth limits, power/thermal risk, storage failure, and operator key exposure are in scope. diff --git a/docs/SECURITY_MODEL.md b/docs/SECURITY_MODEL.md index d6ae24c9..8e88bdad 100644 --- a/docs/SECURITY_MODEL.md +++ b/docs/SECURITY_MODEL.md @@ -71,6 +71,16 @@ Follow-up: - Physical tampering - Unsafe power or enclosure assumptions - Overestimating LoRa or Meshtastic bandwidth +- Treat FlowRouter v0 devices as physically exposed research rigs until a later identity and attestation model exists. +- Keep hardware control surfaces local-only by default, and require explicit authentication before any radio message changes local state. +- Treat local caches as stale or replayable unless entries are checked against commitments, receipts, or other verifiable provenance. +- Avoid custom RF, antenna, amplifier, and production enclosure assumptions in v0; use certified commodity hardware within local radio rules. +- Treat replayed LoRa messages as expected adversarial input until sequence, nonce, freshness, and audit rules exist. +- Treat FCC, regional radio, antenna, duty-cycle, and equipment-authorization mistakes as project risks, not just operator mistakes. +- Treat power, brownout, thermal throttling, fan failure, and sealed-enclosure heat buildup as safety and data-integrity risks. +- Treat NVMe, SD card, and removable cartridge failures as cache-integrity risks; local cache is not a permanent source of truth. +- Treat operator keys, channel keys, dashboard credentials, and cartridge labels as sensitive operational material that must not be exposed on displays, NFC tags, logs, or public MQTT. +- Treat simulator packets, packet schemas, and generated fixtures as unsigned advisory test data until a later identity and authentication design exists. ### Supply Chain diff --git a/hardware/README.md b/hardware/README.md new file mode 100644 index 00000000..8a831518 --- /dev/null +++ b/hardware/README.md @@ -0,0 +1,53 @@ +# FlowMemory Hardware + +Last updated: 2026-05-13 + +This directory contains the FlowRouter V0 proof-of-concept hardware package. It is production-shaped but research-safe: the docs, schemas, simulator, and field-test plans are intended to help later dashboard, services, and hardware work consume consistent data without claiming finished hardware. + +## Package Map + +- `flowrouter/`: FlowRouter V0 scope, BOM, assembly, enclosure, light-pipe, printing, and measurement docs. +- `lora-sidecar/`: Meshtastic/LoRa role, compact control-message inventory, and two-node demo notes. +- `memory-cartridges/`: NFC Memory Cartridge concept and metadata boundaries. +- `simulator/`: deterministic FlowRouter POC packet generator and schema validator. +- `fixtures/`: generated sample packet feeds for tests and future dashboard/service consumers. +- `field-tests/`: field-test plans and logs for controlled hardware experiments. + +## V0 Purpose + +FlowRouter V0 is a local FlowMemory gateway POC. It can model or test: + +- Local node status. +- Artifact cache status. +- Compact receipt relay. +- Heartbeat messages. +- Gateway discovery. +- Local dashboard feed shape. +- Meshtastic/LoRa sidecar status and limits. +- NFC Memory Cartridge metadata. +- FlowCore light-pipe status. +- Enclosure measurement direction. + +## V0 Non-Goals + +FlowRouter V0 does not: + +- Replace ISPs. +- Create global internet from nothing. +- Carry broadband over LoRa or Meshtastic. +- Move model weights, large artifacts, media, or raw memory payloads over LoRa. +- Prove hardware trustlessness. +- Mine tokens or promise passive income. +- Run a production L1 or appchain. +- Define production manufacturing, final CAD, or custom RF boards. + +## Validation Entry Point + +Generate and validate deterministic simulator output: + +```powershell +python hardware/simulator/flowrouter_sim.py --seed 42 --out hardware/fixtures/flowrouter_sample_seed42.json +python hardware/simulator/flowrouter_sim.py --validate-file hardware/fixtures/flowrouter_sample_seed42.json +``` + +The simulator uses only the Python standard library. diff --git a/hardware/field-tests/README.md b/hardware/field-tests/README.md new file mode 100644 index 00000000..4217510d --- /dev/null +++ b/hardware/field-tests/README.md @@ -0,0 +1,18 @@ +# FlowRouter Field Tests + +Last updated: 2026-05-13 + +Field tests must stay controlled, reversible, and honest about limitations. The current package includes a two-node Meshtastic plan and simulator-generated packet fixtures for dry runs before hardware is attached. + +## Rules + +- Use certified router and radio hardware. +- Set the correct LoRa region before transmit. +- Keep public MQTT disabled unless a test explicitly requires and documents a private broker posture. +- Do not send secrets, large artifacts, model data, media, or raw memory over LoRa. +- Do not claim ISP replacement, production mesh, passive income, full trustlessness, or emergency-service reliability. +- Stop on thermal, power, radio-region, interference, or secret-exposure concerns. + +## Plans + +- `TWO_NODE_MESHTASTIC_FIELD_TEST.md`: two-node heartbeat, discovery, digest, dashboard, and offline-mode plan. diff --git a/hardware/field-tests/TWO_NODE_MESHTASTIC_FIELD_TEST.md b/hardware/field-tests/TWO_NODE_MESHTASTIC_FIELD_TEST.md new file mode 100644 index 00000000..23fb53fb --- /dev/null +++ b/hardware/field-tests/TWO_NODE_MESHTASTIC_FIELD_TEST.md @@ -0,0 +1,85 @@ +# Two-Node Meshtastic Field Test + +Last updated: 2026-05-13 + +This plan covers issues #12 and #33 and uses the simulator outputs from `../simulator/` as dry-run packet fixtures before radio transmission. + +## Objective + +Validate that two FlowRouter-like nodes can exchange compact advisory control packets over Meshtastic while normal FlowMemory data remains on WiFi/Ethernet. + +## Hardware + +Node A: + +- Certified OpenWrt router or lab LAN gateway. +- Raspberry Pi 5 or mini PC. +- NVMe/local cache candidate. +- Meshtastic sidecar in the correct regional variant. + +Node B: + +- Laptop, Raspberry Pi, or second FlowRouter-like node. +- Meshtastic sidecar in the same region/channel settings. + +## Dry Run + +Before using radios: + +```powershell +python hardware/simulator/flowrouter_sim.py --seed 42 --out hardware/fixtures/flowrouter_sample_seed42.json +python hardware/simulator/flowrouter_sim.py --validate-file hardware/fixtures/flowrouter_sample_seed42.json +``` + +Review the generated heartbeat, gateway discovery, receipt relay, cache status, sidecar status, dashboard feed, and failure/offline packet. + +## Radio Setup + +- Confirm region and frequency variant. +- Attach antennas before transmit. +- Record firmware version, modem preset, hop limit, channel name, and MQTT settings. +- Prefer private channel settings. +- Keep public MQTT disabled by default. +- Keep operator command warning packets non-executing. + +## Test Sequence + +1. Baseline both nodes on normal LAN/internet. +2. Send node heartbeat from Node A. +3. Send gateway discovery from Node A. +4. Send local cache status digest from Node A. +5. Send compact receipt relay from Node A. +6. Disable upstream internet for Node A. +7. Confirm local dashboard feed still reports LAN-local state. +8. Send emergency/offline signal from Node A. +9. Restore upstream internet. +10. Record reconciliation notes and operator confusion points. + +## Success Criteria + +- Node B receives heartbeat and gateway discovery packets. +- Digest and receipt packets fit the compact schema. +- Offline/failure packet is distinguishable from verified state. +- No heavy payload or secret crosses LoRa. +- Operators can explain local, advisory, and verified status. + +## Metrics + +- Packet count sent/received. +- RSSI/SNR if available. +- Hop count. +- Delay observations. +- Duplicate/lost packets. +- Node A upstream outage detection time. +- Local dashboard availability. +- Cache status before/during/after outage. +- Sidecar temperature and power notes if available. + +## Stop Conditions + +- Wrong region, antenna, or transmit configuration. +- Suspected harmful interference. +- Thermal or power instability. +- Secret, credential, channel key, model data, media, raw memory, or large artifact appears in a payload. +- Operator command warning starts to execute privileged behavior. +- Public MQTT exposure is discovered unexpectedly. diff --git a/hardware/fixtures/flowrouter_sample_seed42.json b/hardware/fixtures/flowrouter_sample_seed42.json new file mode 100644 index 00000000..0e44f216 --- /dev/null +++ b/hardware/fixtures/flowrouter_sample_seed42.json @@ -0,0 +1,200 @@ +{ + "generated_at": "2026-05-13T17:02:00Z", + "packets": { + "compact_receipt_relay": { + "block_hint": 1200012, + "chain": "base-sepolia-sim", + "device_id": "fr-e1e7878a2aa8", + "emitted_at": "2026-05-13T17:00:40Z", + "log_index_hint": 3, + "lora_eligible": true, + "packet_type": "compact_receipt_relay", + "payload_bytes_estimate": 96, + "receipt_digest": "fbe8a762b036d20581160b7e58a3adccf61f53c653713c439f85cc7bee5246fa", + "schema_version": "flowrouter.poc.v0", + "sequence": 1045, + "tx_hash_prefix": "0xea723a0a09aa25b7", + "verification_state": "advisory" + }, + "dashboard_feed": { + "cache": { + "bytes_limit": 268435456, + "bytes_used": 7340032, + "health": "healthy", + "unresolved_count": 7 + }, + "device_id": "fr-e1e7878a2aa8", + "flowcore": { + "pattern": "solid-cobalt", + "state": "online" + }, + "generated_at": "2026-05-13T17:01:40Z", + "latest_receipt_digest": "fbe8a762b036d20581160b7e58a3adccf61f53c653713c439f85cc7bee5246fa", + "network": { + "gateway_id": "gw-82a524067b14", + "lan": "reachable", + "upstream": "reachable" + }, + "packet_type": "dashboard_feed", + "schema_version": "flowrouter.poc.v0", + "sidecar": { + "payload_budget_bytes": 160, + "region": "US", + "state": "ready" + }, + "trust_labels": [ + "local", + "advisory", + "not-chain-verified" + ] + }, + "device_manifest": { + "capabilities": [ + "heartbeat", + "gateway_discovery", + "compact_receipt_relay", + "local_cache_status", + "sidecar_status", + "dashboard_feed" + ], + "device_id": "fr-e1e7878a2aa8", + "device_role": "flowrouter-dev-kit", + "generated_at": "2026-05-13T17:00:00Z", + "hardware": { + "compute": "Raspberry Pi 5 8GB candidate", + "display": "OLED/e-paper status candidate", + "flowcore": "cobalt light-pipe LED candidate", + "nfc": "passive NFC cartridge candidate", + "router": "OpenWrt One candidate", + "sidecar": "Meshtastic USB sidecar candidate", + "storage": "NVMe 256GB cache candidate" + }, + "packet_type": "device_manifest", + "schema_version": "flowrouter.poc.v0", + "security": { + "identity_mode": "simulated-key-fingerprint", + "state_authority": "local-only-unverified", + "trust_level": "advisory" + } + }, + "emergency_offline_signal": { + "code": "UPSTREAM_LOSS", + "device_id": "fr-e1e7878a2aa8", + "emitted_at": "2026-05-13T17:01:30Z", + "last_gateway_id": "gw-82a524067b14", + "operator_action": "check-upstream-and-power", + "packet_type": "emergency_offline_signal", + "priority": "local", + "schema_version": "flowrouter.poc.v0", + "sequence": 1049, + "summary": "Upstream unavailable; LAN dashboard and local cache still reachable.", + "ttl_seconds": 900 + }, + "flowpulse_digest_relay": { + "chain": "base-sepolia-sim", + "device_id": "fr-e1e7878a2aa8", + "digest": "1d5a28ff5af6335dccc9412d01d434aa58bf0870011f781bd614a5266740da3b", + "emitted_at": "2026-05-13T17:00:20Z", + "event_count": 7, + "from_block": 1200000, + "lora_eligible": true, + "packet_type": "flowpulse_digest_relay", + "payload_bytes_estimate": 112, + "schema_version": "flowrouter.poc.v0", + "sequence": 1043, + "to_block": 1200024, + "verification_state": "advisory" + }, + "gateway_discovery": { + "advertised_roles": [ + "local-dashboard", + "cache-status", + "digest-relay" + ], + "dashboard_hint": "http://flowrouter.local/status", + "device_id": "fr-e1e7878a2aa8", + "emitted_at": "2026-05-13T17:01:00Z", + "gateway_id": "gw-82a524067b14", + "lan_reachable": true, + "packet_type": "gateway_discovery", + "schema_version": "flowrouter.poc.v0", + "sequence": 1047, + "sidecar_reachable": true, + "upstream_reachable": true + }, + "heartbeat": { + "cache_state": "healthy", + "device_id": "fr-e1e7878a2aa8", + "emitted_at": "2026-05-13T17:00:10Z", + "flowcore_state": "online", + "network_state": "online", + "packet_type": "heartbeat", + "power_state": "mains", + "schema_version": "flowrouter.poc.v0", + "sequence": 1042, + "sidecar_state": "ready", + "uptime_seconds": 86442, + "warnings": [] + }, + "local_cache_status": { + "artifact_count": 3, + "bytes_limit": 268435456, + "bytes_used": 7340032, + "cache_digest": "2bac34b09472df95c9ba884e903660990e4ed701414693aaf2b8e9ddc19bfc22", + "cache_id": "cache-3a1ab90d4efc", + "device_id": "fr-e1e7878a2aa8", + "emitted_at": "2026-05-13T17:00:50Z", + "health": "healthy", + "mode": "bounded-local", + "packet_type": "local_cache_status", + "receipt_count": 11, + "schema_version": "flowrouter.poc.v0", + "sequence": 1046, + "unresolved_count": 7, + "verified_count": 4 + }, + "nfc_memory_cartridge_metadata": { + "cartridge_id": "cart-0cfd3cfcb210", + "contains_secrets": false, + "created_at": "2026-05-13T17:01:20Z", + "digest": "7bb78aa4de0935712809a8e46e13b832ba5a761416731e51aeb02d753bbca5b0", + "expires_at": "2026-06-13T17:00:00Z", + "label": "field-test-cache-alpha", + "packet_type": "nfc_memory_cartridge_metadata", + "pointer": "flowmemory://cache/4549dba629bc", + "schema_version": "flowrouter.poc.v0", + "trust_level": "untrusted-pointer" + }, + "sidecar_status": { + "device_id": "fr-e1e7878a2aa8", + "emitted_at": "2026-05-13T17:01:10Z", + "modem_preset": "LongFast", + "mqtt_state": "disabled", + "packet_type": "sidecar_status", + "payload_budget_bytes": 160, + "radio": "meshtastic", + "region": "US", + "rssi_dbm": -91, + "schema_version": "flowrouter.poc.v0", + "sequence": 1048, + "snr_db": 7.25, + "tx_enabled": true, + "warnings": [] + }, + "verifier_report_digest_relay": { + "device_id": "fr-e1e7878a2aa8", + "emitted_at": "2026-05-13T17:00:30Z", + "lora_eligible": true, + "packet_type": "verifier_report_digest_relay", + "payload_bytes_estimate": 128, + "report_digest": "b988417bf67c48bab7208ee1fe0531d66fbcb45a1be1b853b70423239c4c8870", + "report_id": "vr-14d051ae590e", + "result": "unresolved", + "schema_version": "flowrouter.poc.v0", + "sequence": 1044, + "subject_digest": "1d5a28ff5af6335dccc9412d01d434aa58bf0870011f781bd614a5266740da3b" + } + }, + "seed": 42, + "simulator": "flowrouter-v0-poc" +} diff --git a/hardware/flowrouter/ASSEMBLY.md b/hardware/flowrouter/ASSEMBLY.md new file mode 100644 index 00000000..eafb3bef --- /dev/null +++ b/hardware/flowrouter/ASSEMBLY.md @@ -0,0 +1,106 @@ +# FlowRouter v0 Assembly Notes + +Last updated: 2026-05-13 + +These notes describe safe prototype assembly order. They are not production assembly instructions. + +## Assembly Principles + +- Keep all parts serviceable. +- Use stock enclosures and open frames until thermal data exists. +- Keep radio, antenna, router, compute, display, LED, and NFC wiring separable. +- Label every cable and power supply. +- Do not transmit on LoRa without correct region, antenna, and test plan. +- Do not expose local dashboard or admin ports to the public internet. + +## Bench Assembly Sequence + +1. Router baseline + - Record router model, firmware source, firmware version, recovery method, MAC addresses, and port map. + - Verify LAN access and upstream WAN behavior. + - Confirm no unsolicited public inbound access is enabled. + +2. Compute baseline + - Assemble Raspberry Pi 5 or mini PC with stock cooling. + - Install NVMe if used. + - Record OS image, storage device, power supply, and idle/load temperature. + - Keep compute on LAN behind the router during early tests. + +3. Local cache baseline + - Create a bounded cache directory. + - Define max size, retention period, and deletion behavior. + - Store only test receipts, digests, and logs. + - Power-cycle and verify recovery behavior. + +4. Display baseline + - Mount display temporarily. + - Show only safe status fields. + - Verify readability, cable strain, and heat exposure. + - Record display dimensions before enclosure work. + +5. FlowCore LED baseline + - Use an off-the-shelf LED module or safe GPIO circuit. + - Map simple states: booting, online, degraded, local-only, cache warning, thermal warning, sidecar warning. + - Verify current limiting and avoid enclosed high-brightness heat buildup. + +6. NFC cartridge baseline + - Start with USB NFC reader or dev module. + - Read passive tags containing only IDs, pointers, labels, and hashes. + - Treat reads as untrusted until checked by local policy. + - Record reader range and orientation before printing any cartridge slot. + +7. Meshtastic sidecar baseline + - Use stock certified device/module. + - Set correct region before transmit. + - Keep antenna attached for transmit. + - Send only low-bandwidth messages from `../lora-sidecar/CONTROL_MESSAGE_INVENTORY.md`. + - Record RSSI/SNR, hop count, loss, retry behavior, and battery/power state if available. + +8. Integration test + - Disconnect upstream internet. + - Verify LAN dashboard remains reachable. + - Verify display and LED show local-only or degraded state. + - Send gateway availability and heartbeat control messages over Meshtastic. + - Restore upstream internet and verify cache reconciliation notes. + +## Cable And Mounting Notes + +- Avoid sharp cable bends near USB-C, HDMI, FPC, antenna, and NFC connections. +- Leave clearance for reset buttons, recovery pins, SD/NVMe access, Ethernet latch movement, and antennas. +- Use strain relief for display, NFC, and sidecar cables. +- Keep antennas away from large metal masses, NVMe heat spreaders, and noisy switching supplies where practical. +- Use removable fasteners or tape for early layout work; do not glue service parts. + +## Power-Up Checklist + +- Correct PSU for each device. +- No exposed conductive debris. +- Antenna attached or LoRa transmit disabled. +- Fan path clear. +- NVMe seated. +- Display cable seated. +- NFC reader connected but not storing secrets. +- Router admin password changed. +- Meshtastic channel keys are test-only and not committed to the repo. + +## Stop Conditions + +Stop the test if: + +- Any component overheats or throttles unexpectedly. +- Power supply voltage/current warnings appear. +- LoRa transmission may be outside local rules. +- The device causes suspected interference. +- The local dashboard exposes secrets or public access. +- Cache content includes private keys, seed phrases, credentials, or sensitive memory artifacts. + +## Assembly Blockers Before Final CAD + +- Exact router dimensions and port clearances. +- Exact compute dimensions, cooler height, and mounting holes. +- NVMe adapter and SSD height. +- Display active area and bezel. +- NFC read range through chosen material. +- LED/light-pipe geometry. +- Antenna location and cable routing. +- Thermal data under sustained load. diff --git a/hardware/flowrouter/BOM.md b/hardware/flowrouter/BOM.md new file mode 100644 index 00000000..63b9bbdb --- /dev/null +++ b/hardware/flowrouter/BOM.md @@ -0,0 +1,195 @@ +# FlowRouter v0 Research BOM + +Last updated: 2026-05-13 + +This is a research BOM, not a procurement list or manufacturing commitment. Every item is a candidate class until measured, sourced, and validated in a field test. + +## BOM Rules + +- Use certified commodity router and radio hardware. +- Prefer parts with documented recovery, replacement, and support paths. +- Prefer modular parts that can be removed without reprinting the enclosure. +- Do not design custom RF boards, amplifiers, antennas, or production PCBs. +- Do not treat this BOM as a sellable SKU definition. + +## Core Gateway Candidates + +| Component | Dev Kit candidate | Pro/Vault candidate | Notes | +| --- | --- | --- | --- | +| Router | OpenWrt One or GL-MT3000 | GL-MT6000 or x86_64 OpenWrt mini PC | Router choice controls enclosure size, thermal behavior, port access, and recovery plan. | +| Compute | Raspberry Pi 5, 8GB | x86_64 mini PC, 8GB+ RAM | Pi 5 is better for visible hardware integration; mini PC is better for cache and sustained services. | +| Storage | 256GB NVMe | 1TB NVMe | NVMe cache is local/offline and pruneable. Use microSD only for boot or non-write-heavy roles. | +| Display | 1.3-2.4 inch OLED or 2.13-2.9 inch e-paper | Larger e-paper or status OLED plus dashboard | Display shows safe status only, never secrets. | +| FlowCore LED | Off-the-shelf blue LED module/light pipe | Serviceable LED module with diffuser/light pipe | Use clear state map and current limiting. | +| NFC | USB NFC reader or GPIO/I2C reader module | Same, plus replaceable cartridge bay | V0 reads tags/pointers; no secret storage on tags. | +| Sidecar radio | Meshtastic-compatible USB/BLE device | Meshtastic-compatible device with external antenna path as certified | Region variant must match test location. | +| Power | Vendor router PSU plus Pi 5 5V/5A USB-C supply | Vendor mini PC PSU plus powered USB hub if needed | Measure total draw before enclosure. | +| Cooling | Pi 5 Active Cooler and router stock cooling | Mini PC stock cooling, NVMe thermal pad, enclosure airflow | No sealed enclosure without thermal data. | + +## Required Parts For A FlowRouter Dev Kit + +Estimated costs are broad United States street-price planning ranges as of 2026-05-13. They are not quotes, procurement instructions, or production commitments. + +| Part class | Example vendor/device | Expected range | Required for v0? | Notes | +| --- | --- | --- | --- | --- | +| OpenWrt router | OpenWrt One, GL.iNet GL-MT3000, GL.iNet GL-MT6000 | USD 90-200 | Yes | Select one. The router handles normal WiFi/Ethernet paths. | +| Local compute | Raspberry Pi 5 8GB or small x86_64 mini PC | USD 80-300 | Yes | Pi 5 is best for visible dev-kit integration; mini PC is better for sustained cache/services. | +| Compute power supply | Raspberry Pi 27W-class USB-C PSU or mini PC vendor PSU | USD 10-40 | Yes | Use vendor-recommended supply; avoid marginal USB power. | +| Compute cooling | Raspberry Pi Active Cooler or mini PC stock cooler | USD 5-35 | Yes | Required before sustained cache/logging tests. | +| NVMe adapter | Raspberry Pi M.2 HAT+ or mini PC internal M.2 slot | USD 12-40 | Yes for NVMe cache tests | Adapter dimensions and SSD height are CAD blockers. | +| NVMe SSD | 256GB NVMe SSD | USD 20-45 | Yes for Dev Kit cache | Use as bounded cache, not permanent source of truth. | +| Meshtastic sidecar | RAK WisBlock, LilyGO, Heltec, or similar Meshtastic-compatible device | USD 25-100 | Yes for issue #12 tests | Must match local region and use supported antenna. | +| Display | Small OLED or e-paper module | USD 5-35 | Yes for product-shaped prototype | Shows safe local status only. | +| Blue FlowCore LED | Off-the-shelf LED module plus diffuser/light-pipe material | USD 2-20 | Yes for product-shaped prototype | No high-brightness sealed heat pocket. | +| NFC reader | USB NFC reader or PN532-style module | USD 10-50 | Yes for cartridge research | Reads pointers/IDs only; no secrets on tags. | +| NFC tags/cards | NTAG-style cards, stickers, or tokens | USD 5-20 | Yes for cartridge research | Test read range through printed material. | +| Prototype fasteners | M2.5/M3 screws, standoffs, inserts, labels | USD 10-35 | Yes | Must remain serviceable. | +| Printed prototype material | PETG filament | USD 20-35 | Yes for enclosure tests | PETG is default; final CAD remains blocked on measurements. | + +Approximate Dev Kit planning range: USD 300-900 depending on router, compute, display, sidecar, and tools already available. + +## Optional Parts And Test Equipment + +| Part class | Example | Expected range | Use | +| --- | --- | --- | --- | +| Larger NVMe SSD | 1TB NVMe | USD 50-120 | Pro/Vault cache and long log tests. | +| Powered USB hub | Known-good USB 3 hub | USD 20-60 | Sidecar, NFC, and storage stability tests. | +| USB Ethernet adapter | Known Linux-compatible adapter | USD 15-45 | Raspberry Pi router experiments. | +| External switch | Small unmanaged/managed switch | USD 20-80 | LAN test topology. | +| E-paper display variant | 2.13-2.9 inch module | USD 15-45 | Persistent status screen tests. | +| Thermal probes | USB thermometer, IR thermometer, or thermocouple logger | USD 15-100 | Thermal validation before enclosure. | +| USB power meter | USB-C PD power meter | USD 15-60 | Pi/sidecar power budget. | +| Kill-A-Watt style meter | AC power meter | USD 20-40 | Router/mini PC draw. | +| ASA filament | Known printer-compatible ASA | USD 25-45 | Higher-temperature enclosure coupons. | +| TPU filament | Shore 95A TPU | USD 20-40 | Feet, bumpers, strain relief. | +| Label printer | Durable labels | USD 30-120 | Field-test labeling. | + +## Missing Dimensions For BOM Lock + +The BOM cannot become procurement-stable until these dimensions are captured for the selected parts: + +- Router exact body, port, vent, antenna, button, and recovery clearances. +- Compute board/chassis, cooler height, connector access, and mounting holes. +- NVMe adapter and SSD height including heatsink or thermal pad. +- Display PCB, active area, connector, and cable path. +- NFC reader antenna center and tag read range through selected material. +- LED module, diffuser, and light-pipe geometry. +- Sidecar radio body, antenna sweep, and cable exit. +- Power connector clearance and safe cable bend radii. +- Printed material shrinkage and insert hole tolerances. + +## Recommended OpenWrt Router Options + +| Device | Why consider it | V0 caution | +| --- | --- | --- | +| OpenWrt One | Clean OpenWrt baseline with recovery-friendly design and M.2 option. | Availability and exact mechanical dimensions must be verified before enclosure work. | +| GL.iNet GL-MT6000 | Strong router with 2.5G ports, WiFi 6, USB 3.x, RAM, and eMMC. | Ships with vendor OpenWrt fork; tests must record OEM vs official OpenWrt. | +| GL.iNet GL-MT3000 | Portable travel-router candidate with USB-C power and USB 3.0. | Fewer ports and less RAM; best for mobile experiments. | +| x86_64 mini PC with OpenWrt | Strongest lab routing/cache platform. | Model-specific thermals, NICs, BIOS behavior, and power draw vary. | + +## Pi 5 Compute Package + +Minimum candidate: + +- Raspberry Pi 5, 8GB. +- Raspberry Pi 27W-class USB-C supply. +- Raspberry Pi Active Cooler. +- M.2 HAT+ or equivalent supported NVMe adapter. +- 256GB NVMe SSD. +- Short, strain-relieved USB cable to sidecar radio if not using BLE/Wi-Fi. +- GPIO-safe LED/display/NFC wiring only after power budget review. + +V0 preference: + +- Pi 5 for FlowRouter Dev Kit and Beacon-style visible prototypes. +- Mini PC for Pro, Vault, Forge, and longer-duration cache tests. + +## Display Package + +Candidate classes: + +- I2C OLED for fast status and compact wiring. +- SPI e-paper for persistent low-power state. +- Router stock LEDs plus web dashboard for the lowest-risk early test. + +Status fields: + +- Power state. +- Upstream internet state. +- LAN-only state. +- Last verified sync time. +- Cache warning. +- Thermal warning. +- LoRa sidecar warning. + +Blocked until measured: + +- Display window size. +- Viewing angle. +- Cable routing. +- Mounting tabs. +- Service access. + +## NFC Cartridge Package + +Candidate classes: + +- USB NFC reader for fastest lab integration. +- PN532-style module for embedded dev kit experiments. +- Passive NTAG-style cards or tokens for cartridge IDs. +- Printed cartridge shell with NFC tag pocket after dimensions are known. + +V0 tag content: + +- Cartridge ID. +- Human-safe label. +- Hash or content pointer. +- Schema version. +- Optional expiration or test batch marker. + +V0 tag non-content: + +- No private keys. +- No seed phrases. +- No raw AI memory. +- No large artifacts. + +## Meshtastic/LoRa Sidecar Package + +Candidate classes: + +- USB-connected Meshtastic device. +- BLE-connected Meshtastic handheld/module. +- RAK WisBlock Meshtastic build using region-appropriate radio module. +- LilyGO or Heltec Meshtastic-compatible boards if regional variant and certification posture are acceptable for the test. + +Required checks: + +- Frequency variant matches region. +- Stock antenna or vendor-supported antenna is used. +- Firmware region is set before transmit. +- Radio can be disabled for bench work. +- Sidecar can be physically separated from noisy compute/storage if needed. + +## Hardware Tier BOM Summary + +| Tier | Candidate BOM shape | +| --- | --- | +| FlowRouter Dev Kit | GL-MT3000 or OpenWrt One, Raspberry Pi 5, 256GB NVMe, OLED/e-paper, blue LED, USB NFC reader, USB/BLE Meshtastic sidecar, PETG open frame. | +| FlowRouter Pro | GL-MT6000 or x86 OpenWrt mini PC, stronger mini PC compute, 1TB NVMe, larger display, serviceable LED/NFC, measured fan path. | +| FlowMemory Beacon | Small Meshtastic node, e-paper/OLED, blue LED, optional NFC tag reader, battery/USB power notes. | +| FlowMemory Vault | Mini PC or Pi 5 with larger NVMe, display, NFC cartridge workflow, LAN-only dashboard, tamper notes. | +| FlowMemory Forge | Lab machine, printer/calibration tools, measurement fixtures, USB sidecars, spare radios, thermal probes. | +| FlowMemory Atlas | Field mapping kit with router, sidecar, GPS-capable Meshtastic device if allowed, dashboard notes, logs. | +| Memory Cartridges | Passive NFC tags, printed shells after measurement, labels, optional removable SSD carrier concept for later review. | + +## Excluded From V0 BOM + +- Custom RF PCB. +- RF power amplifier. +- Unverified antennas. +- Cellular modem SKU commitment. +- Battery/solar product system. +- Production case hardware. +- Tamper-resistant enclosure claim. +- Paid relay/mining/passive-income hardware. diff --git a/hardware/flowrouter/ENCLOSURE_CONCEPT_V0.md b/hardware/flowrouter/ENCLOSURE_CONCEPT_V0.md new file mode 100644 index 00000000..f339f08a --- /dev/null +++ b/hardware/flowrouter/ENCLOSURE_CONCEPT_V0.md @@ -0,0 +1,111 @@ +# FlowRouter Enclosure Concept v0 + +Last updated: 2026-05-13 + +This document supports issue #30. It defines the v0 enclosure concept without creating final CAD or production manufacturing assumptions. + +## Concept Goal + +The enclosure should make FlowRouter feel like a coherent gateway while preserving serviceability, airflow, measurement access, and research safety. + +The v0 enclosure is a prototype shell around certified commodity hardware. It does not modify RF paths, does not replace certified radio/router enclosures where that would affect compliance, and does not claim production readiness. + +## Visual Direction + +- Matte ivory shell. +- Translucent cobalt FlowCore light pipe. +- Small e-paper/OLED status window. +- Front-facing NFC cartridge touch/slot area. +- Scientific-instrument layout with labels, service screws, and visible status hierarchy. + +## Draft Layout Envelope + +These dimensions are draft layout targets for bench planning only. They are not CAD, manufacturing dimensions, or fit guarantees. + +| Envelope | Approximate target | Rationale | +| --- | --- | --- | +| Dev Kit desktop footprint | 220mm x 160mm | Fits common FDM build plates and leaves room for router/compute modules only if selected parts are compact. | +| Dev Kit height | 65mm to 90mm | Allows Pi 5 cooler, small display tilt, cable strain relief, and airflow. | +| NFC cartridge face | 55mm x 35mm | Enough for passive tag/card experiments and visible label area. | +| Display window | 60mm x 35mm | Fits small OLED or 2.13 inch e-paper class modules with bezel tolerance. | +| FlowCore light-pipe window | 8mm to 18mm diameter or width | Large enough to read state without becoming decorative lighting. | +| Sidecar service bay | model-specific | Blocked until chosen Meshtastic device and antenna clearances are measured. | + +Any selected router or mini PC that exceeds the draft envelope should use a split shell, sidecar mount, or open-frame fixture instead of forcing unsafe fit. + +## Enclosure Profiles + +| Profile | Purpose | Boundary | +| --- | --- | --- | +| Open-frame bench rig | Fast measurement, cable access, heat observation. | Primary v0 starting point. Not field rugged. | +| Desktop dev kit shell | Product-shaped arrangement for router, compute, display, LED, NFC, and sidecar. | No sealed thermals; service panels required. | +| Field-test carrier | Cable strain relief, labels, feet, and protected display/NFC surfaces. | Not weatherproof or tamper-resistant. | +| Future production-shaped concept | Visual and ergonomic target for later design. | Not manufacturing CAD or compliance claim. | + +## Functional Zones + +- Router zone: keeps stock router airflow and port access intact. +- Compute zone: supports Pi 5 or mini PC with cooler access and NVMe service path. +- Cache zone: keeps NVMe thermals visible and serviceable. +- Display zone: visible from normal operator angle, no secret display. +- FlowCore LED zone: light pipe visible without glare or heat pocket. +- NFC cartridge zone: front-accessible, non-metallic read path, removable test fixture. +- LoRa sidecar zone: removable mount with antenna exposure and cable strain relief. +- Cable zone: separates power, Ethernet, USB, display, NFC, and radio leads. + +## Airflow Concept + +- Preserve router stock vents. +- Keep Pi 5 active cooler or mini PC fan unobstructed. +- Use vertical chimney-style vents where orientation allows. +- Keep NVMe away from stagnant pockets. +- Keep radio sidecar away from hot exhaust. +- Do not add dust screens until airflow loss is measured. + +## Service Access + +The enclosure must allow access to: + +- Router power, WAN, LAN, USB, reset/recovery, and antenna positions. +- Compute power, USB, Ethernet, SD/NVMe service, and fan cleaning. +- Display connector and mounting screws. +- NFC reader and cartridge slot. +- FlowCore LED/light pipe. +- Meshtastic sidecar, antenna, and transmit-disable workflow. + +## Display, NFC, And LED Placement + +- Display should be visible without opening the enclosure. +- NFC cartridge slot should not require reaching around antennas or power cables. +- FlowCore LED should be visible from across a room but not bright enough to obscure display reading. +- NFC and LED openings should be test coupons before full-panel printing. + +## Antenna And Radio Boundary + +- Do not print custom antennas. +- Do not bury vendor antennas. +- Do not force unsupported antenna orientation. +- Keep sidecar removable so radio certification assumptions are not blurred by enclosure experiments. +- Record every test antenna configuration. + +## Missing Dimensions And Blockers + +Final CAD is blocked by: + +- Selected router body, vents, ports, and antenna sweep. +- Selected compute and cooler dimensions. +- NVMe adapter height and temperature. +- Display active area and connector path. +- NFC reader/tag read-through distance. +- FlowCore LED/light-pipe geometry. +- Sidecar radio and antenna clearance. +- Power connector bend radius. +- Sustained thermal data inside any shell. + +## Success Criteria + +- Operator can read status and access NFC cartridge without moving network cables. +- Router and compute can be serviced without destructive disassembly. +- Airflow remains measurable and unobstructed. +- Radio sidecar stays removable and region-compliant. +- The concept does not imply weatherproofing, tamper resistance, or production readiness. diff --git a/hardware/flowrouter/FLOWCORE_LIGHT_PIPE.md b/hardware/flowrouter/FLOWCORE_LIGHT_PIPE.md new file mode 100644 index 00000000..e2a0b223 --- /dev/null +++ b/hardware/flowrouter/FLOWCORE_LIGHT_PIPE.md @@ -0,0 +1,62 @@ +# FlowCore Light-Pipe Prototype + +Last updated: 2026-05-13 + +This document supports issue #32. It defines a research-safe blue FlowCore LED/light-pipe concept for FlowRouter v0. + +## Role + +The FlowCore light pipe is an at-a-glance local status indicator. It complements the display and local dashboard; it is not a security indicator by itself. + +## Visual Direction + +- Shell direction: matte ivory prototype enclosure. +- Light-pipe direction: translucent cobalt FlowCore window or pipe. +- Overall feel: scientific instrument, bench gateway, labeled test hardware. +- Avoid gamer RGB, decorative status effects, or ambiguous colors. + +## V0 Status Map + +| State | LED behavior | Meaning | +| --- | --- | --- | +| Booting | Slow cobalt pulse | Hardware is starting or local status is not ready. | +| Online | Solid cobalt | LAN dashboard and upstream path appear available. Advisory only. | +| Syncing | Soft double pulse | Local cache or digest state is reconciling over normal network paths. | +| Verified | Solid cobalt with brief confirmation pulse | The displayed item is verified by normal verifier/indexer path. | +| Unresolved | Slow blink | Local/advisory state exists but is not verified. | +| Offline | Two short pulses with long gap | LAN-only or upstream unavailable. | +| Error | Fast blink | Power, thermal, cache, sidecar, or validation error needs operator attention. | + +## Candidate Parts + +- Off-the-shelf 5V or 3.3V blue LED module. +- GPIO-safe LED board with current limiting. +- Short acrylic light pipe. +- Printed PETG diffuser test coupon. +- TPU gasket or bumper around light-pipe opening. + +No custom PCB is required for v0. + +## Electrical Boundaries + +- Use vendor-rated LED current. +- Include current limiting if the module does not provide it. +- Do not drive high-current LED strips from Raspberry Pi GPIO. +- Avoid visible wiring strain near the display and NFC reader. +- Keep LED power budget in the total system power measurement. + +## Thermal And Usability Checks + +- Measure LED pocket temperature after 30 minutes. +- Check glare against OLED/e-paper display. +- Check visibility in room light and dim light. +- Check whether the state pattern is distinguishable without reading docs. +- Confirm light-pipe removal does not require removing router or compute. + +## Non-Goals + +- No production electrical design. +- No custom LED PCB. +- No safety-critical status claim. +- No hidden operator command channel. +- No final light-pipe CAD until geometry and thermals are measured. diff --git a/hardware/flowrouter/FLOWROUTER_V0_SCOPE.md b/hardware/flowrouter/FLOWROUTER_V0_SCOPE.md new file mode 100644 index 00000000..8802c619 --- /dev/null +++ b/hardware/flowrouter/FLOWROUTER_V0_SCOPE.md @@ -0,0 +1,220 @@ +# FlowRouter v0 Scope + +Last updated: 2026-05-13 + +FlowRouter v0 is a production-shaped research foundation for FlowMemory hardware. It defines the smallest credible gateway shape while staying safely inside commodity hardware, measured prototypes, and low-bandwidth control signaling. + +## What FlowRouter v0 Is + +FlowRouter v0 is a local gateway research rig built from: + +- A certified OpenWrt-capable router for WiFi/Ethernet routing. +- Raspberry Pi 5 or x86_64 mini PC compute for local services, telemetry, and cache control. +- NVMe storage for bounded local/offline artifact and receipt cache experiments. +- Meshtastic/LoRa sidecar for compact control messages. +- E-paper or OLED display for local operator state. +- Blue FlowCore LED light pipe for simple hardware state. +- NFC memory cartridge slot for physical identity, pointers, or removable cache workflows. +- LAN-only local dashboard assumptions. + +The v0 question is whether FlowMemory can keep useful local state, compact coordination, and operator clarity during degraded connectivity, then reconcile with normal network paths later. + +## What FlowRouter v0 Is Not + +FlowRouter v0 is not: + +- An ISP replacement. +- A claim that global internet appears without an upstream gateway. +- A production mesh network. +- A passive-income device. +- A full-trustless hardware oracle. +- A production hardware SKU. +- A production firmware distribution. +- A custom RF board, antenna, amplifier, or radio certification project. +- A final CAD package. +- A manufacturing BOM. +- A high-bandwidth LoRa or Meshtastic transport. +- A way to move AI memory, model artifacts, media, or bulk data over LoRa. + +## Required Truths + +- At least one gateway needs upstream internet for external sync. +- WiFi and Ethernet handle normal data paths. +- Meshtastic and LoRa are low-bandwidth control channels. +- V0 must use certified radio/router hardware in authorized configurations. +- Cached local state is not automatically verified state. +- Operator commands over radio are warnings or queued intent only until authentication, authorization, replay protection, and audit semantics are designed. + +## Workstream Boundaries + +Research: + +- Compare commodity hardware classes and document assumptions. +- Define proof-of-concept questions, field metrics, and open risks. +- Produce notes, diagrams, and decision inputs for later issues. + +Field tests: + +- Run controlled local tests with explicit start/stop conditions. +- Record observed connectivity, cache, radio, power, thermal, and tamper data. +- Avoid public deployment, public relay behavior, and coverage claims. + +Firmware and electrical work: + +- Configure supported OpenWrt images, Meshtastic firmware, packages, and local scripts only as needed for measurement. +- Use vendor power supplies and certified off-the-shelf radios. +- Do not design production firmware, custom PCBs, custom RF paths, amplifiers, or antenna systems. + +Enclosure work: + +- Use temporary mounts, dev cases, labels, airflow notes, and field photos. +- Document cooling constraints before any printed enclosure is considered final. +- Do not produce final CAD, tooling files, production materials, or manufacturing assumptions without measurements. + +Operator controls: + +- Define local-only status and control expectations for power, upstream connectivity, cache state, and sidecar state. +- Treat remote commands as out of scope until authentication, authorization, audit logs, and failure modes are defined. +- Keep operator controls distinct from dashboard or hardware-console product work. + +## Recommended Certified OpenWrt Router Options + +Use supported commodity hardware first. Prefer documented OpenWrt support, recovery paths, enough RAM for logging, and USB/M.2/serial access for sidecar and cache experiments. + +| Router | V0 role | Assumptions | +| --- | --- | --- | +| OpenWrt One | Clean baseline router | Official OpenWrt-oriented device with recovery-friendly design, 1GB RAM, 2.5G/1G Ethernet, USB serial, and M.2 SSD option. Best first baseline if available. | +| GL.iNet GL-MT6000 / Flint 2 | Higher-throughput router | Strong router-first candidate with WiFi 6, 1GB RAM, 8GB eMMC, USB 3.x, four 1G LAN ports, and two 2.5G ports. Distinguish OEM OpenWrt fork from official OpenWrt image. | +| GL.iNet GL-MT3000 / Beryl AX | Portable field router | Travel-router candidate with WiFi 6, USB 3.0, USB-C power, 512MB RAM, and two Ethernet ports. Useful for mobile field tests, not final product assumptions. | +| x86_64 OpenWrt mini PC | Lab router/cache/control node | Use when tests need more CPU, RAM, SSD, or multiple Ethernet ports. Prefer common Intel NICs, 4GB+ RAM, SSD storage, and measured thermals. | + +Avoid unsupported bargain routers unless the research question is specifically hardware compatibility risk. + +## Raspberry Pi 5 vs Mini PC Tradeoffs + +| Dimension | Raspberry Pi 5 | x86_64 mini PC | +| --- | --- | --- | +| Best use | Visible dev kit, GPIO/display/LED/NFC integration, low-power local services. | Higher-throughput routing, larger cache, stronger local services, multiple NICs. | +| Networking | Built-in Gigabit Ethernet; router use usually needs USB Ethernet, external switch, or separate access point. | Often includes one or more Ethernet ports; multi-NIC models are better router candidates. | +| Storage | M.2 HAT+ gives PCIe 2.0 x1 NVMe path; microSD should not hold write-heavy cache. | Internal NVMe/SATA is usually stronger for cache and logs. | +| Cooling | Active cooling expected under sustained load. | Depends on chassis; fanless needs thermal proof before field use. | +| Power | Use official-class 5V/5A USB-C supply for Pi 5 with peripherals. | Use vendor PSU; measure idle and load draw. | +| Enclosure fit | Good for printed dev case and GPIO peripherals. | Easier to use as black-box compute; harder to integrate cleanly without exact model dimensions. | + +## NVMe Storage Assumptions + +- NVMe is for bounded local/offline cache, not permanent source of truth. +- 256GB is the recommended v0 default for FlowRouter Dev Kit cache tests. +- 1TB is a reasonable FlowRouter Pro/Vault research target when longer logs or package mirrors are needed. +- Cache entries should prefer hashes, CIDs, compact receipts, state summaries, and provenance metadata. +- Cache retention must be explicit by size and age. +- Cache content that is sensitive must be encrypted at rest or excluded. +- Power-loss recovery and filesystem behavior must be tested before unattended use. + +## Display Options + +| Option | Fit | Notes | +| --- | --- | --- | +| Small OLED | Fast local status | Useful for IP state, cache state, temperature, and sidecar state. Watch burn-in and cable strain. | +| E-paper | Low-power persistent status | Good for device identity, last sync, and warning state. Refresh is slower; protect display from pressure. | +| Router LEDs only | Minimal baseline | Acceptable for early v0, but insufficient for operator clarity without local dashboard. | + +The display should never reveal secrets, private keys, WiFi passwords, channel keys, or sensitive cache labels. + +## FlowCore LED Options + +- Blue LED behind a light pipe is allowed as a visual state indicator. +- V0 states should stay simple: booting, local-only, online, degraded, cache warning, sidecar warning, thermal warning. +- Use off-the-shelf LED boards or GPIO-compatible modules. +- Add current limiting and follow vendor ratings. +- Avoid high-brightness enclosed LEDs without thermal checks. + +## NFC Memory Cartridge Options + +- V0 NFC should use off-the-shelf reader modules and passive tags. +- The cartridge should carry a short cartridge ID, content pointer, hash, or label. +- Do not store private keys, seed phrases, or long sensitive data on passive NFC tags. +- Treat cartridge reads as untrusted input until authenticated and checked against expected commitments. +- Cartridge mechanical fit is blocked on measurements in `MEASUREMENT_CHECKLIST.md`. + +## LoRa/Meshtastic Module Options + +- Use off-the-shelf Meshtastic-compatible devices or certified radio modules for the region. +- Prefer USB/serial/BLE integration before any embedded electrical design. +- Candidate classes: RAK WisBlock Meshtastic builds, LilyGO Meshtastic boards, Heltec Meshtastic boards, or other documented Meshtastic-compatible devices. +- Verify regional frequency variant before purchase or field use. +- Do not design custom RF electronics in v0. +- Do not add amplifiers or unsupported antennas. +- Keep radios connected to suitable antennas before transmit. + +## Power Assumptions + +- Use vendor-recommended router supplies. +- Raspberry Pi 5 assumes a high-quality 5V/5A USB-C supply when peripherals are attached. +- Mini PCs use vendor PSU and measured draw. +- Displays, NFC, LEDs, and radio sidecars need a power budget before enclosure integration. +- Battery, UPS, solar, and vehicle-power tests are field-test notes only, not product power-system design. + +## Cooling Assumptions + +- Raspberry Pi 5 should use active cooling under sustained load. +- Mini PCs need measured idle/load temperature and throttling observations. +- Router thermals must be measured before enclosure changes. +- NVMe drives need airflow or thermal pads if logs/cache writes are sustained. +- No sealed printed enclosure is acceptable without thermal measurements. + +## Enclosure Assumptions + +- V0 can use open test frames, dev cases, bracket prototypes, labels, cable guides, and measured mockups. +- Final CAD is blocked until dimensions, connector clearances, thermal paths, cable bend radii, display windows, NFC field location, antenna placement, and service access are measured. +- Antennas should remain outside or properly exposed by the enclosure according to the device vendor's intended use. +- The enclosure must allow tool access, SD/NVMe service, reset/recovery, and visible warning states. + +## 3D Printer And Material Constraints + +- Model for common FDM printers first; assume 220mm x 220mm x 250mm as the default build-volume target unless larger hardware requires a split enclosure. +- PETG is the default v0 material for toughness and moderate heat resistance. +- ASA is acceptable for higher-temperature or outdoor-adjacent tests only with ventilation, printer capability, and shrinkage testing. +- TPU is useful for feet, bumpers, cable strain relief, and vibration isolation. +- PLA is acceptable for desk mockups only; do not use it for warm routers, vehicles, sun exposure, or enclosed electronics. +- Use threaded inserts or captured nuts for serviceable assemblies. +- Do not rely on printed plastic as an electrical safety barrier. + +## Regulatory Cautions + +This document is not legal advice. Operators are responsible for local radio rules. + +- Use certified off-the-shelf router and radio hardware in authorized configurations. +- Set the correct Meshtastic region before transmit. +- For United States tests, Meshtastic documents the `US` region as 902-928 MHz with 30 dBm power limit. +- Do not override region, frequency, duty-cycle, or power settings to escape local limits. +- Stop or change a test if harmful interference is suspected. +- Amateur-radio operation needs a separate issue because encryption, identification, operator licensing, and band plans change the design. +- Public marketing, sale, lease, or distribution needs a separate regulatory review before product claims. + +## Smallest Useful Proof-of-Concept Questions + +1. Can a commodity router and local compute node keep a LAN dashboard reachable when upstream internet is lost? +2. Can a Meshtastic sidecar exchange compact gateway/status messages with another node under degraded IP connectivity? +3. Can NVMe-backed local cache preserve compact receipts, digests, and logs across power loss? +4. Can operators distinguish local-only state from verified state? +5. Can the enclosure concept keep router, compute, NVMe, display, LED, NFC, and sidecar serviceable and cool? +6. What device identity, tamper evidence, and operator-key handling are required before any remote command path is safe? + +## References Checked + +- OpenWrt Table of Hardware: https://openwrt.org/toh/start +- OpenWrt One: https://openwrt.org/toh/openwrt/one +- OpenWrt GL.iNet GL-MT6000: https://openwrt.org/toh/gl.inet/gl-mt6000 +- OpenWrt GL.iNet GL-MT3000: https://openwrt.org/toh/gl.inet/gl-mt3000 +- OpenWrt x86 guide: https://openwrt.org/docs/guide-user/installation/openwrt_x86 +- OpenWrt extroot guide: https://openwrt.org/docs/guide-user/additional-software/extroot_configuration +- Raspberry Pi 5: https://www.raspberrypi.com/products/raspberry-pi-5/ +- Raspberry Pi Active Cooler: https://www.raspberrypi.com/products/active-cooler/ +- Raspberry Pi M.2 HAT+: https://www.raspberrypi.com/products/m2-hat-plus/ +- Meshtastic LoRa configuration: https://meshtastic.org/docs/configuration/radio/lora/ +- Meshtastic channel configuration: https://meshtastic.org/docs/configuration/radio/channels/ +- Meshtastic MQTT configuration: https://meshtastic.org/docs/configuration/module/mqtt/ +- 47 CFR 15.5: https://www.ecfr.gov/current/title-47/chapter-I/subchapter-A/part-15/subpart-A/section-15.5 +- 47 CFR 15.204: https://www.ecfr.gov/current/title-47/chapter-I/subchapter-A/part-15/subpart-C/section-15.204 +- 47 CFR 2.803: https://www.ecfr.gov/current/title-47/chapter-I/subchapter-A/part-2/subpart-I/section-2.803 diff --git a/hardware/flowrouter/MEASUREMENT_CHECKLIST.md b/hardware/flowrouter/MEASUREMENT_CHECKLIST.md new file mode 100644 index 00000000..f726ce75 --- /dev/null +++ b/hardware/flowrouter/MEASUREMENT_CHECKLIST.md @@ -0,0 +1,128 @@ +# FlowRouter v0 Measurement Checklist + +Last updated: 2026-05-13 + +Final CAD is blocked until these measurements exist for the selected hardware. Record measured values, device revisions, measurement method, and photos where useful. + +## Selected Hardware + +- [ ] Router model, revision, firmware source, and power supply. +- [ ] Compute model, revision, cooler, power supply, and OS image. +- [ ] NVMe adapter, SSD model, heatsink/thermal pad. +- [ ] Display model and interface. +- [ ] NFC reader model and tag type. +- [ ] LED/light-pipe module. +- [ ] Meshtastic/LoRa sidecar model, frequency variant, antenna, firmware version. + +## Router Measurements + +- [ ] Overall width, depth, height. +- [ ] Foot height and location. +- [ ] Ethernet port positions and latch clearance. +- [ ] USB/serial/power connector positions. +- [ ] Button/recovery access. +- [ ] Antenna dimensions and rotation sweep if external. +- [ ] Stock-case vent locations. +- [ ] Idle temperature in open air. +- [ ] Sustained routing temperature in open air. +- [ ] Recovery procedure clearance needs. + +## Compute Measurements + +- [ ] Board or chassis dimensions. +- [ ] Mounting hole locations. +- [ ] Cooler height. +- [ ] GPIO/header clearance. +- [ ] USB/Ethernet/HDMI/power connector clearance. +- [ ] NVMe adapter height and overhang. +- [ ] Idle temperature. +- [ ] Sustained cache/logging temperature. +- [ ] Throttling behavior. + +## Storage Measurements + +- [ ] NVMe form factor. +- [ ] SSD height with label/heatsink. +- [ ] Thermal pad or heatsink clearance. +- [ ] Write-heavy temperature after 15 minutes. +- [ ] Write-heavy temperature after 60 minutes. +- [ ] Power-loss recovery observation. +- [ ] Filesystem check behavior after forced power loss in a disposable test image. + +## Display Measurements + +- [ ] PCB width, height, thickness. +- [ ] Active display area. +- [ ] Bezel/window size. +- [ ] Connector location. +- [ ] Cable bend radius. +- [ ] Readability in expected orientation. +- [ ] Heat exposure from nearby compute/router. + +## NFC Cartridge Measurements + +- [ ] Reader PCB dimensions. +- [ ] Antenna field center. +- [ ] Read range in open air. +- [ ] Read range through 1mm, 2mm, and 3mm PETG. +- [ ] Read range through 1mm, 2mm, and 3mm ASA if ASA is considered. +- [ ] Tag dimensions. +- [ ] Cartridge insertion/removal clearance. +- [ ] Effect of nearby screws, magnets, labels, and cables. + +## FlowCore LED Measurements + +- [ ] LED module dimensions. +- [ ] Operating current. +- [ ] Heat after 30 minutes. +- [ ] Light-pipe diameter/length. +- [ ] Visible states under room light. +- [ ] Display glare impact. + +## Sidecar Radio Measurements + +- [ ] Device dimensions. +- [ ] Antenna orientation and clearance. +- [ ] USB/BLE/serial connection path. +- [ ] Radio-disabled bench mode confirmed. +- [ ] Region setting confirmed before transmit. +- [ ] RSSI/SNR for short field test. +- [ ] Packet loss/retry notes. +- [ ] Heat near compute/storage. + +## Power Measurements + +- [ ] Router idle draw. +- [ ] Router load draw. +- [ ] Compute idle draw. +- [ ] Compute load draw. +- [ ] NVMe write load draw if measurable. +- [ ] Display/LED/NFC/sidecar draw. +- [ ] Total draw with all peripherals. +- [ ] PSU headroom. +- [ ] Brownout or undervoltage warnings. + +## Enclosure And Printing Measurements + +- [ ] Printer build volume. +- [ ] Material used and brand. +- [ ] Dimensional accuracy coupon. +- [ ] Heat-set insert coupon. +- [ ] Vent coupon airflow observation. +- [ ] PETG shrink/fit notes. +- [ ] ASA shrink/fit notes if used. +- [ ] TPU foot/bumper fit notes if used. +- [ ] Minimum service clearance around every removable part. + +## Missing Measurements Summary + +Until measured, assume unknown: + +- Final enclosure dimensions. +- Display window geometry. +- NFC cartridge slot geometry. +- Light-pipe geometry. +- Antenna placement. +- Cable bend radii. +- Thermal margin in any printed enclosure. +- Power budget with all peripherals attached. diff --git a/hardware/flowrouter/PRINTING_GUIDE.md b/hardware/flowrouter/PRINTING_GUIDE.md new file mode 100644 index 00000000..a0247176 --- /dev/null +++ b/hardware/flowrouter/PRINTING_GUIDE.md @@ -0,0 +1,98 @@ +# FlowRouter v0 Printing Guide + +Last updated: 2026-05-13 + +This guide defines enclosure-printing constraints before final CAD. It intentionally does not create final CAD because required dimensions and thermal measurements are missing. + +## Printing Goal + +V0 printed parts should support measurement, serviceability, airflow, display/NFC/light-pipe experiments, and field-test handling. They should not imply production readiness. + +## Printer Constraints + +- Default design target: common FDM printer with about 220mm x 220mm x 250mm build volume. +- Use split panels if router, mini PC, or antenna layout exceeds the build volume. +- Assume 0.4mm nozzle unless a print note says otherwise. +- Design test coupons before full enclosure panels. +- Prefer parts that print without fragile supports around vents, clips, and cable channels. +- Keep wall thickness, standoff geometry, and heat-set insert holes parameterized in CAD later. + +## Material Recommendations + +| Material | Use | Caution | +| --- | --- | --- | +| PETG | Default v0 material for dev frames, brackets, panels, and light-duty field parts. | Can soften near hot electronics; measure internal temperatures. | +| ASA | Higher-temperature and outdoor-adjacent tests. | Requires enclosed/ventilated printer setup and shrinkage calibration. | +| TPU | Feet, bumpers, vibration pads, cable strain relief, gaskets. | Not for structural electronics mounts. | +| PLA | Desk mockups and fit checks only. | Avoid for warm routers, vehicles, sun, sealed electronics, or field use. | + +## Enclosure Features To Prototype + +- Removable top or side panel. +- Router service access. +- Compute service access. +- NVMe access or removable cache bay. +- Display window. +- Blue FlowCore LED light pipe. +- NFC cartridge face/slot. +- LoRa sidecar mount and cable exit. +- Antenna clearance without printed plastic forcing unsupported RF geometry. +- Vent paths for router, compute, NVMe, and power supplies. +- Label recesses for device ID and test batch. + +## Airflow And Thermal Rules + +- Do not enclose a router in printed plastic without measuring stock-case temperature first. +- Do not place Pi 5, mini PC, NVMe, or radios in a sealed enclosure. +- Keep inlet and exhaust paths separate where possible. +- Avoid trapping hot air behind e-paper/OLED modules. +- Measure temperatures with the prototype in its real orientation. +- Add dust screens only after airflow loss is measured. + +## NFC And Light Pipe Rules + +- NFC slot geometry is blocked until reader/tag range is measured through PETG and ASA samples. +- Do not put metal fasteners or foil-backed labels between reader and tag. +- Keep the FlowCore LED light pipe removable. +- Avoid LED brightness that washes out display readability or creates heat in a sealed pocket. + +## Antenna And Radio Rules + +- V0 printed parts must not create a custom antenna system. +- Keep vendor antennas exposed in normal orientation. +- Do not bury antennas near metal fasteners, NVMe heat spreaders, batteries, or dense wire bundles. +- Do not print brackets that require unsupported antenna modifications. +- Record whether a test used stock antenna, vendor-approved antenna, or radio transmit disabled. + +## Fasteners And Serviceability + +- Prefer M2.5/M3 screws, captured nuts, or heat-set inserts after test coupons. +- Avoid plastic threads for parts expected to be opened repeatedly. +- Do not glue radios, storage, displays, or NFC readers. +- Leave room for labels, cable strain relief, and connector latch access. + +## Pre-CAD Test Coupons + +Print and measure: + +- Screw boss and insert samples. +- Vent grille samples. +- PETG and ASA NFC read-through samples. +- Light-pipe samples. +- Cable channel samples for USB-C, Ethernet, display, and antenna pigtails. +- Snap-fit samples only if service life is measured. + +## Final CAD Gate + +Final CAD stays blocked until `MEASUREMENT_CHECKLIST.md` has enough completed measurements for: + +- Selected router. +- Selected compute. +- Selected storage adapter. +- Display. +- NFC reader/tag stack. +- LED/light pipe. +- Sidecar radio. +- Cable exits and bend radii. +- Thermal load. +- Printer calibration and material shrinkage. diff --git a/hardware/flowrouter/README.md b/hardware/flowrouter/README.md new file mode 100644 index 00000000..3b886382 --- /dev/null +++ b/hardware/flowrouter/README.md @@ -0,0 +1,61 @@ +# FlowRouter Hardware Foundation + +Last updated: 2026-05-13 + +FlowRouter is the FlowMemory hardware gateway track. V0 is production-shaped but research-safe: it should look like the beginning of a real device family while remaining built from certified commodity hardware, measured prototypes, and explicit non-goals. + +## Product Thesis + +FlowRouter may combine: + +- Certified OpenWrt router for normal WiFi/Ethernet data paths. +- Raspberry Pi 5 or x86_64 mini PC for local services, telemetry, and cache control. +- NVMe artifact cache for bounded offline storage. +- Meshtastic/LoRa sidecar for low-bandwidth control signaling. +- E-paper or OLED display for local status. +- Blue FlowCore LED light pipe for at-a-glance state. +- NFC memory cartridge slot for physical memory identity, pointers, or removable cache workflows. +- Local dashboard reachable on the LAN. + +FlowRouter does not create global internet by itself. At least one gateway needs upstream internet for external sync. Meshtastic and LoRa are control signaling only; WiFi and Ethernet carry normal data. + +## V0 Boundary + +V0 uses certified router/radio hardware and off-the-shelf compute. It does not include custom RF boards, custom antennas, final CAD, production firmware, production mesh infrastructure, tokenomics, passive-income claims, ISP replacement claims, or full trustlessness claims. + +## Hardware Tiers + +| Tier | V0 meaning | Research boundary | +| --- | --- | --- | +| FlowRouter Dev Kit | Bench and early field gateway using commodity router, Pi/mini PC, sidecar, display, and open enclosure notes. | Primary v0 build target. Not a sellable SKU. | +| FlowRouter Pro | Higher-capacity gateway with stronger compute, better thermal envelope, NVMe, and multi-WAN experiments. | Research profile only; no production commitment. | +| FlowMemory Beacon | Small status node with display, FlowCore LED, and Meshtastic signaling. | Control/status node, not a router or artifact cache. | +| FlowMemory Vault | Local artifact/cache node with larger NVMe and tamper observations. | Cache research only; not a permanent source of truth. | +| FlowMemory Forge | Lab node for printing, measurement, field-test preparation, and device provisioning. | Lab fixture, not field deployment infrastructure. | +| FlowMemory Atlas | Mapping/observability profile for field-test topology and node health. | Documentation and telemetry concept only. | +| Memory Cartridges | Physical NFC-tagged cartridges for memory pointers, labels, and possibly removable cache media. | V0 uses pointers and test fixtures, not secret-bearing production media. | + +## Directory Map + +- `FLOWROUTER_V0_SCOPE.md`: scope, non-goals, hardware assumptions, and tier definitions. +- `BOM.md`: research BOM candidates and tier summaries. +- `ASSEMBLY.md`: safe prototype assembly sequence. +- `PRINTING_GUIDE.md`: enclosure and material constraints before CAD. +- `MEASUREMENT_CHECKLIST.md`: measurements required before final CAD. +- `ENCLOSURE_CONCEPT_V0.md`: enclosure concept boundaries before final CAD. +- `FLOWCORE_LIGHT_PIPE.md`: blue FlowCore LED/light-pipe prototype notes. +- `../lora-sidecar/`: Meshtastic/LoRa sidecar role and message inventory. +- `../memory-cartridges/`: NFC memory cartridge assumptions. +- `../../research/meshtastic/`: Meshtastic role and research assumptions. +- `../../research/decentralized-internet/`: FlowNet boundary notes. +- `../simulator/`: deterministic POC packet simulator and schemas. +- `../fixtures/`: generated sample packet feeds. +- `../field-tests/`: controlled field-test plans. + +## V0 Success Criteria + +- A local operator can tell whether the node has upstream internet, LAN availability, cache health, power/thermal status, and sidecar status. +- A second node can receive compact Meshtastic status or digest messages during degraded IP connectivity. +- Cached state is clearly marked local-only until verified through normal network, indexer, or chain-derived paths. +- The prototype can be measured for thermal, power, serviceability, and enclosure-fit constraints. +- The docs make it difficult to overclaim bandwidth, production readiness, trustlessness, or regulatory status. diff --git a/hardware/lora-sidecar/CONTROL_MESSAGE_INVENTORY.md b/hardware/lora-sidecar/CONTROL_MESSAGE_INVENTORY.md new file mode 100644 index 00000000..26ebf095 --- /dev/null +++ b/hardware/lora-sidecar/CONTROL_MESSAGE_INVENTORY.md @@ -0,0 +1,106 @@ +# Meshtastic/LoRa Control Message Inventory + +Last updated: 2026-05-13 + +This inventory addresses issue #12. It defines candidate control messages for FlowRouter v0 and explicitly rules out high-bandwidth payloads. + +## Message Envelope + +Every candidate should fit in a small binary or compact text payload. Target payloads should stay well below practical Meshtastic limits and should be designed around compact fields rather than JSON verbosity. + +Common fields: + +| Field | Shape | Purpose | +| --- | --- | --- | +| `v` | uint8 | Schema version. | +| `type` | enum/uint8 | Message type. | +| `node` | short node id or hash prefix | Sender identity hint; not sufficient authentication. | +| `seq` | uint32/uint64 | Replay detection and ordering. | +| `ts` | compact timestamp or monotonic tick | Freshness hint when clocks exist. | +| `flags` | bitset | Low-battery, local-only, degraded, test mode. | +| `auth` | truncated MAC/signature field | Required before state-changing use; exact scheme unresolved. | + +## Candidate Messages + +| Message | Purpose group | Approximate payload shape | Why it fits low bandwidth | Risks and requirements | +| --- | --- | --- | --- | --- | +| Node heartbeat | Status ping | `v,type,node,seq,uptime,bat/temp,flags,auth` | Tiny status tuple; no artifact data. | Spoofing and replay risk; needs auth and sequence tracking. | +| Gateway availability | Status ping | `v,type,node,seq,wan,lan,cache,sidecar,flags,auth` | Bitfields describe availability instead of carrying logs. | Overclaiming connectivity; receiver must treat as advisory. | +| FlowPulse digest | Compact digest | `v,type,node,seq,chain,from,to,digest32,count,flags,auth` | Sends a hash over a FlowPulse range, not events. | Digest cannot be trusted until verified by indexer/receipts. | +| Artifact availability digest | Compact digest | `v,type,node,seq,namespace,digest32,count,bytes_class,ttl,auth` | Announces cache hints only; no artifacts. | May leak inventory metadata; needs privacy review. | +| Compact receipt reference | Compact receipt reference | `v,type,node,seq,chain,block_hint,tx_hash_prefix/log_hint,receipt_hash,auth` | Carries short pointer and hash, not receipt body. | Prefix collisions and stale hints; full verification requires normal network path. | +| Field diagnostic | Field diagnostic | `v,type,node,seq,temp,power_class,rssi,snr,loss,flags,auth` | Numeric summary only. | Sensor accuracy, spoofing, and replay risk. | +| Emergency/local signal | Emergency signal | `v,type,node,seq,code,priority,ttl,location_hint?,auth` | Short code and optional coarse hint. | Abuse risk; no public emergency-service claim. | +| Operator command warning | Operator command | `v,type,node,seq,command_id,intent,ttl,auth` | Intent marker only; no scripts or payloads. | Must not execute privileged action in v0; needs strong auth, authorization, replay protection, and audit before any future action. | + +## Message Type Notes + +### Node Heartbeat + +Use for "this node is alive" and coarse device state. Keep it periodic but infrequent to avoid channel congestion. + +### Gateway Availability + +Use for advisory state about upstream internet, LAN reachability, local cache, and sidecar status. It does not prove connectivity to the global internet. + +### FlowPulse Digest + +Use only as a compact checkpoint over a known event range. It should never carry event bodies, logs, memory artifacts, or model data. + +### Artifact Availability Digest + +Use to say "this cache may have content matching this digest or namespace." It must not expose sensitive labels or bulk metadata. + +### Compact Receipt Reference + +Use as a breadcrumb for later reconciliation. It can include a chain id, block hint, short transaction/log hint, and receipt hash. It is not final proof by itself. + +### Field Diagnostic + +Use for temperature, power class, RSSI/SNR, message loss, and degraded-state flags. It helps correlate field notes after the test. + +### Emergency/Local Signal + +Use for local operator attention in degraded connectivity. It is not a public safety system and should not claim emergency-service reliability. + +### Operator Command Warning + +Use only to warn or mark intent. V0 must not execute remote commands over LoRa. Future state-changing commands require a separate threat model. + +## Authentication And Replay Needs + +V0 must assume LoRa control channels are adversarial: + +- Node IDs can be spoofed. +- Packets can be replayed. +- Messages can be lost, delayed, duplicated, or reordered. +- Channel keys can leak. +- Routing metadata remains visible even when payloads are encrypted. + +Before state-changing use, every message needs: + +- Message authentication bound to device identity. +- Sequence, nonce, or receipt-based replay protection. +- Expiration/freshness policy that handles offline operation. +- Domain separation by network, test, channel, and message type. +- Audit log on the receiving node. +- Operator-visible warning when auth fails or freshness is uncertain. + +## Retry And Loss Policy + +- Heartbeats can be lossy. +- Availability messages can be repeated at low frequency. +- Digests and receipt references may be resent with the same sequence until acknowledged by a normal network path. +- Emergency/local signals may repeat with TTL and priority limits. +- Operator command warnings must not be retried into execution semantics. + +## Explicit Non-Goals + +- No high-bandwidth payloads. +- No artifact transfer. +- No AI memory transfer. +- No app traffic. +- No ISP replacement. +- No production mesh deployment. +- No firmware implementation in this issue. +- No app UI implementation in this issue. diff --git a/hardware/lora-sidecar/README.md b/hardware/lora-sidecar/README.md new file mode 100644 index 00000000..cc315271 --- /dev/null +++ b/hardware/lora-sidecar/README.md @@ -0,0 +1,95 @@ +# LoRa Sidecar + +Last updated: 2026-05-13 + +The LoRa sidecar is FlowRouter v0's low-bandwidth control-signaling path. It is not normal internet bandwidth, not a payload network, and not a production mesh deployment. + +## Role + +The sidecar may send and receive: + +- Node heartbeat. +- Gateway availability. +- FlowPulse digest. +- Artifact availability digest. +- Compact receipt reference. +- Field diagnostic. +- Emergency/local signal. +- Operator command warning. + +The sidecar must not send: + +- AI memory artifacts. +- Model data. +- Media. +- Bulk files. +- Normal app traffic. +- Secrets, private keys, seed phrases, WiFi passwords, or channel keys. + +## Hardware Assumptions + +- Use off-the-shelf Meshtastic-compatible devices or certified radio modules for the test region. +- Prefer USB, BLE, serial, or Wi-Fi/MQTT integration over embedded electrical design. +- Keep the radio removable from the FlowRouter enclosure. +- Use stock or vendor-supported antennas. +- Do not add amplifiers. +- Do not create custom RF boards. +- Confirm the hardware frequency variant before field use. + +## Integration Modes + +| Mode | Fit | Boundary | +| --- | --- | --- | +| USB serial | Best early lab path. | Requires cable strain relief and serial permissions. | +| BLE | Useful for handheld sidecars. | Pairing and reliability must be measured. | +| Wi-Fi/MQTT | Useful for lab gateway experiments. | Prefer private broker; downlink is risky and must be explicit. | +| Embedded UART/I2C/SPI | Later prototype path. | Not v0 default; requires electrical review. | + +## Radio Configuration Assumptions + +- Set Meshtastic region before transmit. +- Use conservative hop limits. +- Use short messages and low frequency. +- Record modem preset, hop limit, channel name, PSK posture, and MQTT settings in field notes. +- Treat OK-to-MQTT as policy metadata, not cryptographic enforcement. +- Disable transmit during bench work that lacks antenna, region, or test plan. + +## Payload Budget + +FlowRouter V0 should treat LoRa/Meshtastic as a scarce control channel: + +- Target compact payloads of 160 bytes or less before transport overhead where practical. +- Treat about 200 bytes as a practical upper bound for application-level message design. +- Prefer binary-inspired fields, short enums, hashes, prefixes, counters, and bitsets. +- Send digests, references, and state summaries instead of full logs or artifacts. +- Rate-limit repeated messages and avoid chatty telemetry loops. + +Never send over LoRa: + +- Model weights. +- Large artifacts. +- Media. +- Raw AI memory payloads. +- Full verifier reports. +- Full receipt bodies. +- Secrets, private keys, seed phrases, credentials, WiFi passwords, or channel keys. + +## Security Requirements Before Control + +Before a radio message can change local FlowRouter state, the design needs: + +- Device identity model. +- Message authentication. +- Replay protection. +- Monotonic sequence or nonce handling. +- Time or freshness model that works offline. +- Operator authorization. +- Audit log. +- Failsafe behavior. + +V0 operator command messages are warnings or test intents only; they do not execute privileged actions. + +## Related Docs + +- `CONTROL_MESSAGE_INVENTORY.md`: candidate compact control messages. +- `TWO_NODE_DEMO_PLAN.md`: controlled two-node demo plan for advisory control signaling. diff --git a/hardware/lora-sidecar/TWO_NODE_DEMO_PLAN.md b/hardware/lora-sidecar/TWO_NODE_DEMO_PLAN.md new file mode 100644 index 00000000..018759eb --- /dev/null +++ b/hardware/lora-sidecar/TWO_NODE_DEMO_PLAN.md @@ -0,0 +1,90 @@ +# Two-Node FlowRouter Meshtastic Demo Plan + +Last updated: 2026-05-13 + +This document supports issue #33. It defines a controlled two-node demo for compact control signaling without implementing firmware, app UI, production deployment, or public mesh infrastructure. + +## Demo Objective + +Show that two FlowRouter-like nodes can exchange compact advisory status over Meshtastic/LoRa when normal IP connectivity is degraded. + +The demo must not claim ISP replacement, production mesh, emergency reliability, passive income, or high-bandwidth LoRa transport. + +## Topology + +| Node | Hardware shape | Role | +| --- | --- | --- | +| Node A | Router plus local compute plus Meshtastic sidecar | Simulated gateway with upstream internet toggled on/off. | +| Node B | Router or laptop plus Meshtastic sidecar | Observer node that receives advisory control messages. | + +At least one node needs upstream internet for external sync tests. During outage simulation, local dashboard and cache behavior should remain LAN-local. + +## Allowed Message Candidates + +Use only messages from `CONTROL_MESSAGE_INVENTORY.md`: + +- Node heartbeat. +- Gateway availability. +- FlowPulse digest. +- Artifact availability digest. +- Compact receipt reference. +- Field diagnostic. +- Emergency/local signal. +- Operator command warning as non-executing intent only. + +## Setup Checklist + +- Confirm test region and set Meshtastic LoRa region before transmit. +- Confirm antennas are attached. +- Record firmware version, modem preset, hop limit, channel name, and MQTT state. +- Prefer a private channel for the test. +- Keep public MQTT disabled unless the test explicitly documents a private broker and uplink/downlink posture. +- Keep operator command warnings disabled or non-executing. +- Prepare local logs for router, compute, cache, and sidecar observations. + +## Demo Steps + +1. Baseline both nodes with upstream internet available. +2. Send heartbeat and gateway availability messages. +3. Record RSSI, SNR, hop count, loss, and delay observations. +4. Disable upstream internet on Node A. +5. Confirm Node A local dashboard remains reachable on LAN. +6. Send local-only gateway availability and field diagnostic messages. +7. Send one compact digest or receipt reference using test data only. +8. Restore upstream internet. +9. Record reconciliation notes and whether advisory state was clearly distinguishable from verified state. + +## Success Metrics + +- Node B receives at least one heartbeat and one gateway availability update from Node A. +- Node A display or local log distinguishes online, local-only, and degraded state. +- No message exceeds the compact inventory shape. +- No artifact, AI memory, media, credential, or secret is transmitted over LoRa. +- Operators can explain which state is local, advisory, or verified. + +## Stop Conditions + +- Suspected regulatory or interference issue. +- Wrong region or antenna configuration. +- Device overheats or power becomes unstable. +- Public MQTT exposure is discovered unexpectedly. +- Any secret or sensitive payload appears in a control message. +- Operator command warning starts to behave like an executable command. + +## Risks To Record + +- Device identity spoofing. +- Replayed LoRa messages. +- Packet loss and duplicate delivery. +- Channel-key leakage. +- MQTT exposure. +- Bandwidth overclaim. +- Regulatory mistakes. +- Operator confusion. +- Cache state being mistaken for verified state. + +## Outputs + +- Field notes under `hardware/lora-sidecar/` or `hardware/flowrouter/`. +- Updated message inventory if a payload shape is too large or ambiguous. +- Updated security assumptions if authentication, replay, or operator-key risks change. diff --git a/hardware/memory-cartridges/NFC_CARTRIDGE_V0.md b/hardware/memory-cartridges/NFC_CARTRIDGE_V0.md new file mode 100644 index 00000000..2c0fb39e --- /dev/null +++ b/hardware/memory-cartridges/NFC_CARTRIDGE_V0.md @@ -0,0 +1,89 @@ +# NFC Memory Cartridge v0 + +Last updated: 2026-05-13 + +This document supports issue #31. It defines the first Memory Cartridge prototype as a passive NFC tag workflow, not a secure hardware token. + +## Objective + +Use a physical cartridge to make memory/cache identity visible to an operator while keeping all security claims conservative. + +## V0 Cartridge Payload + +Recommended compact fields: + +| Field | Example | Notes | +| --- | --- | --- | +| `schema` | `fmcart:v0` | Identifies the cartridge format. | +| `cart_id` | short random ID | Human workflows only; not proof of authenticity. | +| `label` | test namespace | Avoid sensitive names. | +| `pointer` | CID, URL, or local namespace | Must be verified through normal paths. | +| `digest` | hash prefix or full hash if space allows | Helps detect obvious mismatch. | +| `batch` | field-test batch | Optional. | +| `expires` | date or epoch | Optional stale-use warning. | + +## Tag Content Limits + +Do not write: + +- Private keys. +- Seed phrases. +- RPC credentials. +- WiFi passwords. +- Meshtastic channel keys. +- Raw AI memory. +- Personal or sensitive labels. +- Large artifact payloads. + +## Prototype Hardware + +- Passive NTAG-style cards, stickers, or tokens. +- USB NFC reader for first lab tests. +- PN532-style module only after power and mounting are reviewed. +- Printed shell or sleeve only after read-through measurements exist. + +## Read Path + +1. Operator inserts or taps cartridge. +2. Reader captures small tag payload. +3. Local software treats payload as untrusted. +4. Display shows safe label and local/advisory/verified status. +5. Verification path checks pointer/digest through normal FlowMemory mechanisms when network or cache state allows. + +## Measurement Plan + +- Measure read range in open air. +- Measure read range through 1mm, 2mm, and 3mm PETG. +- Measure read range through ASA if used. +- Test orientation sensitivity. +- Test effect of nearby screws, labels, cables, display, and LED module. +- Record false read, failed read, and duplicate tag behavior. + +## Risks + +- Tag cloning. +- Stale pointer reuse. +- Label spoofing. +- Sensitive label leakage. +- Operator confusion between cartridge presence and verified content. +- NFC reader placement failure after enclosure changes. + +## Future Threat Model Topics + +Before Memory Cartridges can move beyond passive metadata pointers, a separate threat model must define: + +- Whether cartridges ever hold encrypted removable media. +- Whether a secure element is needed. +- How cartridge identity is authenticated. +- How cloned tags are detected or tolerated. +- How stale pointers expire. +- How operators distinguish inserted, read, trusted, and verified states. +- How malware, autorun, or unsafe mount behavior is prevented if removable storage is introduced. + +## Non-Goals + +- No secure element. +- No production cartridge. +- No removable storage commitment. +- No proof-of-memory claim. +- No final cartridge CAD until read range and slot geometry are measured. diff --git a/hardware/memory-cartridges/README.md b/hardware/memory-cartridges/README.md new file mode 100644 index 00000000..31930dc5 --- /dev/null +++ b/hardware/memory-cartridges/README.md @@ -0,0 +1,82 @@ +# Memory Cartridges + +Last updated: 2026-05-13 + +Memory Cartridges are the FlowMemory hardware concept for physical memory identity, cache pointers, and operator-visible artifact workflows. V0 keeps this research-safe by using NFC tags and optional removable-media notes, not secret-bearing production cartridges. + +## V0 Role + +A Memory Cartridge may represent: + +- A physical label for a memory namespace. +- A pointer to an off-chain artifact set. +- A content hash or compact digest. +- A test batch identifier. +- A cache import/export workflow marker. + +It is not: + +- A seed phrase holder. +- A private-key token. +- A trusted proof device. +- A production secure element. +- A guarantee that referenced artifacts are available or verified. + +## NFC Assumptions + +- Use passive NFC tags for v0. +- Store short NDEF-style records only. +- Treat tag content as untrusted input. +- Verify any hash or pointer through normal FlowMemory verification paths. +- Do not store secrets, credentials, or raw memory content. +- Record tag type, capacity, read range, and material stack in `../flowrouter/MEASUREMENT_CHECKLIST.md`. + +## Candidate Tag Payload + +Fields should stay small: + +- `fmcart:v0` +- Cartridge ID. +- Namespace or label. +- Content pointer or hash. +- Optional test batch. +- Optional expiration. + +## Physical Cartridge Concept + +The physical shell can include: + +- Printed label area. +- NFC tag pocket. +- Direction marker. +- Write-protect visual marker if removable storage is explored later. +- Color or texture distinction for field sorting. + +Final cartridge CAD is blocked until NFC read range, material thickness, reader position, insertion clearance, and labeling behavior are measured. + +## Optional Removable Storage Concept + +Later research may evaluate a cartridge carrier that holds a removable SSD or USB storage device. That is not a v0 commitment. + +Before removable storage is allowed: + +- Define malware and autorun assumptions. +- Define encryption and key handling. +- Define mount policy. +- Define write protection. +- Define safe eject. +- Define provenance and cache verification. + +## Risks + +- Tag cloning. +- Stale pointer reuse. +- Label spoofing. +- Sensitive label leakage. +- Reader placement failures. +- Operator confusion between local cache and verified state. + +## Related Docs + +- `NFC_CARTRIDGE_V0.md`: first passive NFC cartridge prototype plan. +- `../flowrouter/MEASUREMENT_CHECKLIST.md`: NFC read-through and slot measurements required before CAD. diff --git a/hardware/simulator/README.md b/hardware/simulator/README.md new file mode 100644 index 00000000..0e75a304 --- /dev/null +++ b/hardware/simulator/README.md @@ -0,0 +1,33 @@ +# FlowRouter Simulator + +Last updated: 2026-05-13 + +The simulator emits deterministic FlowRouter V0 proof-of-concept packets for dashboard, services, hardware, and field-test planning. It uses only the Python standard library. + +## Generate Sample Output + +```powershell +python hardware/simulator/flowrouter_sim.py --seed 42 --out hardware/fixtures/flowrouter_sample_seed42.json +``` + +## Validate Existing Fixture + +```powershell +python hardware/simulator/flowrouter_sim.py --validate-file hardware/fixtures/flowrouter_sample_seed42.json +``` + +## Packet Types + +- Device manifest +- Heartbeat +- FlowPulse digest relay +- Verifier report digest relay +- Compact receipt relay +- Local cache status +- Gateway discovery +- Sidecar status +- NFC Memory Cartridge metadata +- Emergency/offline signal +- Dashboard feed + +The packets are JSON versions of compact, binary-inspired fields. They are not production protocol commitments and should remain small enough to reason about LoRa constraints. diff --git a/hardware/simulator/flowrouter_sim.py b/hardware/simulator/flowrouter_sim.py new file mode 100644 index 00000000..bb242a57 --- /dev/null +++ b/hardware/simulator/flowrouter_sim.py @@ -0,0 +1,381 @@ +#!/usr/bin/env python3 +"""Deterministic FlowRouter V0 POC packet generator and validator.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import sys +from pathlib import Path +from typing import Any + + +SCHEMA_FILES = { + "device_manifest": "device_manifest.schema.json", + "heartbeat": "heartbeat.schema.json", + "flowpulse_digest_relay": "flowpulse_digest_relay.schema.json", + "verifier_report_digest_relay": "verifier_report_digest_relay.schema.json", + "compact_receipt_relay": "compact_receipt_relay.schema.json", + "local_cache_status": "local_cache_status.schema.json", + "gateway_discovery": "gateway_discovery.schema.json", + "sidecar_status": "sidecar_status.schema.json", + "nfc_memory_cartridge_metadata": "nfc_memory_cartridge_metadata.schema.json", + "emergency_offline_signal": "emergency_offline_signal.schema.json", + "dashboard_feed": "dashboard_feed.schema.json", +} + + +def digest(seed: int, label: str, length: int = 64) -> str: + return hashlib.sha256(f"flowrouter-v0:{seed}:{label}".encode("utf-8")).hexdigest()[:length] + + +def short_id(seed: int, label: str) -> str: + return digest(seed, label, 12) + + +def iso_tick(offset_seconds: int) -> str: + # Fixed clock keeps fixtures deterministic. + base_hour = 17 + minute = offset_seconds // 60 + second = offset_seconds % 60 + return f"2026-05-13T{base_hour:02d}:{minute:02d}:{second:02d}Z" + + +def build_packets(seed: int) -> dict[str, Any]: + device_id = f"fr-{short_id(seed, 'device')}" + gateway_id = f"gw-{short_id(seed, 'gateway')}" + cartridge_id = f"cart-{short_id(seed, 'cartridge')}" + receipt_digest = digest(seed, "receipt") + flowpulse_digest = digest(seed, "flowpulse") + verifier_digest = digest(seed, "verifier") + cache_digest = digest(seed, "cache") + + manifest = { + "packet_type": "device_manifest", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "device_role": "flowrouter-dev-kit", + "generated_at": iso_tick(0), + "hardware": { + "router": "OpenWrt One candidate", + "compute": "Raspberry Pi 5 8GB candidate", + "storage": "NVMe 256GB cache candidate", + "sidecar": "Meshtastic USB sidecar candidate", + "display": "OLED/e-paper status candidate", + "nfc": "passive NFC cartridge candidate", + "flowcore": "cobalt light-pipe LED candidate", + }, + "capabilities": [ + "heartbeat", + "gateway_discovery", + "compact_receipt_relay", + "local_cache_status", + "sidecar_status", + "dashboard_feed", + ], + "security": { + "identity_mode": "simulated-key-fingerprint", + "trust_level": "advisory", + "state_authority": "local-only-unverified", + }, + } + + heartbeat = { + "packet_type": "heartbeat", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "sequence": 1000 + seed, + "emitted_at": iso_tick(10), + "uptime_seconds": 86400 + seed, + "power_state": "mains", + "network_state": "online", + "cache_state": "healthy", + "sidecar_state": "ready", + "flowcore_state": "online", + "warnings": [], + } + + flowpulse_relay = { + "packet_type": "flowpulse_digest_relay", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "sequence": 1001 + seed, + "emitted_at": iso_tick(20), + "chain": "base-sepolia-sim", + "from_block": 1200000, + "to_block": 1200024, + "event_count": 7, + "digest": flowpulse_digest, + "payload_bytes_estimate": 112, + "lora_eligible": True, + "verification_state": "advisory", + } + + verifier_report = { + "packet_type": "verifier_report_digest_relay", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "sequence": 1002 + seed, + "emitted_at": iso_tick(30), + "report_id": f"vr-{short_id(seed, 'verifier-report')}", + "subject_digest": flowpulse_digest, + "result": "unresolved", + "report_digest": verifier_digest, + "payload_bytes_estimate": 128, + "lora_eligible": True, + } + + receipt_relay = { + "packet_type": "compact_receipt_relay", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "sequence": 1003 + seed, + "emitted_at": iso_tick(40), + "chain": "base-sepolia-sim", + "block_hint": 1200012, + "tx_hash_prefix": f"0x{digest(seed, 'tx', 16)}", + "log_index_hint": 3, + "receipt_digest": receipt_digest, + "payload_bytes_estimate": 96, + "lora_eligible": True, + "verification_state": "advisory", + } + + cache_status = { + "packet_type": "local_cache_status", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "sequence": 1004 + seed, + "emitted_at": iso_tick(50), + "cache_id": f"cache-{short_id(seed, 'cache-id')}", + "mode": "bounded-local", + "bytes_used": 7340032, + "bytes_limit": 268435456, + "artifact_count": 3, + "receipt_count": 11, + "verified_count": 4, + "unresolved_count": 7, + "cache_digest": cache_digest, + "health": "healthy", + } + + gateway_discovery = { + "packet_type": "gateway_discovery", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "gateway_id": gateway_id, + "sequence": 1005 + seed, + "emitted_at": iso_tick(60), + "lan_reachable": True, + "upstream_reachable": True, + "sidecar_reachable": True, + "dashboard_hint": "http://flowrouter.local/status", + "advertised_roles": ["local-dashboard", "cache-status", "digest-relay"], + } + + sidecar_status = { + "packet_type": "sidecar_status", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "sequence": 1006 + seed, + "emitted_at": iso_tick(70), + "radio": "meshtastic", + "region": "US", + "modem_preset": "LongFast", + "payload_budget_bytes": 160, + "mqtt_state": "disabled", + "tx_enabled": True, + "rssi_dbm": -91, + "snr_db": 7.25, + "warnings": [], + } + + cartridge = { + "packet_type": "nfc_memory_cartridge_metadata", + "schema_version": "flowrouter.poc.v0", + "cartridge_id": cartridge_id, + "label": "field-test-cache-alpha", + "pointer": f"flowmemory://cache/{short_id(seed, 'pointer')}", + "digest": digest(seed, "cartridge-digest"), + "created_at": iso_tick(80), + "expires_at": "2026-06-13T17:00:00Z", + "contains_secrets": False, + "trust_level": "untrusted-pointer", + } + + emergency = { + "packet_type": "emergency_offline_signal", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "sequence": 1007 + seed, + "emitted_at": iso_tick(90), + "code": "UPSTREAM_LOSS", + "priority": "local", + "ttl_seconds": 900, + "summary": "Upstream unavailable; LAN dashboard and local cache still reachable.", + "last_gateway_id": gateway_id, + "operator_action": "check-upstream-and-power", + } + + dashboard_feed = { + "packet_type": "dashboard_feed", + "schema_version": "flowrouter.poc.v0", + "device_id": device_id, + "generated_at": iso_tick(100), + "network": { + "lan": "reachable", + "upstream": "reachable", + "gateway_id": gateway_id, + }, + "cache": { + "health": cache_status["health"], + "bytes_used": cache_status["bytes_used"], + "bytes_limit": cache_status["bytes_limit"], + "unresolved_count": cache_status["unresolved_count"], + }, + "sidecar": { + "state": "ready", + "region": sidecar_status["region"], + "payload_budget_bytes": sidecar_status["payload_budget_bytes"], + }, + "flowcore": { + "state": "online", + "pattern": "solid-cobalt", + }, + "latest_receipt_digest": receipt_digest, + "trust_labels": ["local", "advisory", "not-chain-verified"], + } + + return { + "device_manifest": manifest, + "heartbeat": heartbeat, + "flowpulse_digest_relay": flowpulse_relay, + "verifier_report_digest_relay": verifier_report, + "compact_receipt_relay": receipt_relay, + "local_cache_status": cache_status, + "gateway_discovery": gateway_discovery, + "sidecar_status": sidecar_status, + "nfc_memory_cartridge_metadata": cartridge, + "emergency_offline_signal": emergency, + "dashboard_feed": dashboard_feed, + } + + +class ValidationError(Exception): + pass + + +def check_type(value: Any, expected: str) -> bool: + if expected == "object": + return isinstance(value, dict) + if expected == "array": + return isinstance(value, list) + if expected == "string": + return isinstance(value, str) + if expected == "integer": + return isinstance(value, int) and not isinstance(value, bool) + if expected == "number": + return (isinstance(value, int) or isinstance(value, float)) and not isinstance(value, bool) + if expected == "boolean": + return isinstance(value, bool) + return True + + +def validate_value(schema: dict[str, Any], value: Any, path: str) -> None: + expected = schema.get("type") + if expected and not check_type(value, expected): + raise ValidationError(f"{path}: expected {expected}, got {type(value).__name__}") + + if "enum" in schema and value not in schema["enum"]: + raise ValidationError(f"{path}: value {value!r} not in enum {schema['enum']!r}") + + if isinstance(value, str) and "maxLength" in schema and len(value) > schema["maxLength"]: + raise ValidationError(f"{path}: string longer than {schema['maxLength']}") + + if isinstance(value, (int, float)) and not isinstance(value, bool): + if "minimum" in schema and value < schema["minimum"]: + raise ValidationError(f"{path}: value below minimum {schema['minimum']}") + if "maximum" in schema and value > schema["maximum"]: + raise ValidationError(f"{path}: value above maximum {schema['maximum']}") + + if isinstance(value, dict): + required = schema.get("required", []) + for key in required: + if key not in value: + raise ValidationError(f"{path}: missing required key {key}") + + properties = schema.get("properties", {}) + if schema.get("additionalProperties") is False: + extra = sorted(set(value) - set(properties)) + if extra: + raise ValidationError(f"{path}: unexpected keys {extra}") + for key, child in properties.items(): + if key in value: + validate_value(child, value[key], f"{path}.{key}") + + if isinstance(value, list) and "items" in schema: + for index, item in enumerate(value): + validate_value(schema["items"], item, f"{path}[{index}]") + + +def load_schema(schema_dir: Path, packet_type: str) -> dict[str, Any]: + schema_file = SCHEMA_FILES.get(packet_type) + if not schema_file: + raise ValidationError(f"no schema registered for packet type {packet_type}") + return json.loads((schema_dir / schema_file).read_text(encoding="utf-8")) + + +def validate_packets(packets: dict[str, Any], schema_dir: Path) -> None: + for name, packet in packets.items(): + if not isinstance(packet, dict): + raise ValidationError(f"{name}: packet must be an object") + packet_type = packet.get("packet_type") + if packet_type != name: + raise ValidationError(f"{name}: packet_type {packet_type!r} does not match key") + schema = load_schema(schema_dir, packet_type) + validate_value(schema, packet, name) + + +def output_document(seed: int) -> dict[str, Any]: + return { + "simulator": "flowrouter-v0-poc", + "seed": seed, + "generated_at": iso_tick(120), + "packets": build_packets(seed), + } + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--seed", type=int, default=42, help="deterministic seed") + parser.add_argument("--out", type=Path, help="write generated JSON to this path") + parser.add_argument("--validate-file", type=Path, help="validate an existing simulator JSON file") + args = parser.parse_args() + + schema_dir = Path(__file__).resolve().parent / "schemas" + + try: + if args.validate_file: + doc = json.loads(args.validate_file.read_text(encoding="utf-8")) + validate_packets(doc["packets"], schema_dir) + print(f"valid: {args.validate_file}") + return 0 + + doc = output_document(args.seed) + validate_packets(doc["packets"], schema_dir) + encoded = json.dumps(doc, indent=2, sort_keys=True) + "\n" + if args.out: + args.out.parent.mkdir(parents=True, exist_ok=True) + args.out.write_text(encoded, encoding="utf-8") + print(f"wrote: {args.out}") + else: + sys.stdout.write(encoded) + return 0 + except (KeyError, json.JSONDecodeError, OSError, ValidationError) as exc: + print(f"error: {exc}", file=sys.stderr) + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/hardware/simulator/schemas/compact_receipt_relay.schema.json b/hardware/simulator/schemas/compact_receipt_relay.schema.json new file mode 100644 index 00000000..3a8f0c8b --- /dev/null +++ b/hardware/simulator/schemas/compact_receipt_relay.schema.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Compact Receipt Relay", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "sequence", "emitted_at", "chain", "block_hint", "tx_hash_prefix", "log_index_hint", "receipt_digest", "payload_bytes_estimate", "lora_eligible", "verification_state"], + "properties": { + "packet_type": { "type": "string", "enum": ["compact_receipt_relay"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "chain": { "type": "string" }, + "block_hint": { "type": "integer", "minimum": 0 }, + "tx_hash_prefix": { "type": "string", "maxLength": 18 }, + "log_index_hint": { "type": "integer", "minimum": 0 }, + "receipt_digest": { "type": "string", "maxLength": 64 }, + "payload_bytes_estimate": { "type": "integer", "minimum": 0, "maximum": 200 }, + "lora_eligible": { "type": "boolean" }, + "verification_state": { "type": "string", "enum": ["local", "advisory", "verified", "unresolved"] } + } +} diff --git a/hardware/simulator/schemas/dashboard_feed.schema.json b/hardware/simulator/schemas/dashboard_feed.schema.json new file mode 100644 index 00000000..30fea2df --- /dev/null +++ b/hardware/simulator/schemas/dashboard_feed.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Dashboard Feed", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "generated_at", "network", "cache", "sidecar", "flowcore", "latest_receipt_digest", "trust_labels"], + "properties": { + "packet_type": { "type": "string", "enum": ["dashboard_feed"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "generated_at": { "type": "string" }, + "network": { "type": "object" }, + "cache": { "type": "object" }, + "sidecar": { "type": "object" }, + "flowcore": { "type": "object" }, + "latest_receipt_digest": { "type": "string", "maxLength": 64 }, + "trust_labels": { "type": "array", "items": { "type": "string" } } + } +} diff --git a/hardware/simulator/schemas/device_manifest.schema.json b/hardware/simulator/schemas/device_manifest.schema.json new file mode 100644 index 00000000..bb07072d --- /dev/null +++ b/hardware/simulator/schemas/device_manifest.schema.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "FlowRouter V0 Device Manifest", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "device_role", "generated_at", "hardware", "capabilities", "security"], + "properties": { + "packet_type": { "type": "string", "enum": ["device_manifest"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "device_role": { "type": "string" }, + "generated_at": { "type": "string" }, + "hardware": { "type": "object" }, + "capabilities": { "type": "array", "items": { "type": "string" } }, + "security": { "type": "object" } + } +} diff --git a/hardware/simulator/schemas/emergency_offline_signal.schema.json b/hardware/simulator/schemas/emergency_offline_signal.schema.json new file mode 100644 index 00000000..4eefc4cc --- /dev/null +++ b/hardware/simulator/schemas/emergency_offline_signal.schema.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Emergency Offline Signal", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "sequence", "emitted_at", "code", "priority", "ttl_seconds", "summary", "last_gateway_id", "operator_action"], + "properties": { + "packet_type": { "type": "string", "enum": ["emergency_offline_signal"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "code": { "type": "string", "enum": ["UPSTREAM_LOSS", "POWER_WARNING", "THERMAL_WARNING", "SIDECAR_OFFLINE", "LOCAL_ONLY"] }, + "priority": { "type": "string", "enum": ["local", "operator", "test"] }, + "ttl_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, + "summary": { "type": "string", "maxLength": 160 }, + "last_gateway_id": { "type": "string", "maxLength": 32 }, + "operator_action": { "type": "string", "maxLength": 64 } + } +} diff --git a/hardware/simulator/schemas/flowpulse_digest_relay.schema.json b/hardware/simulator/schemas/flowpulse_digest_relay.schema.json new file mode 100644 index 00000000..a5a3af9b --- /dev/null +++ b/hardware/simulator/schemas/flowpulse_digest_relay.schema.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "FlowPulse Digest Relay", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "sequence", "emitted_at", "chain", "from_block", "to_block", "event_count", "digest", "payload_bytes_estimate", "lora_eligible", "verification_state"], + "properties": { + "packet_type": { "type": "string", "enum": ["flowpulse_digest_relay"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "chain": { "type": "string" }, + "from_block": { "type": "integer", "minimum": 0 }, + "to_block": { "type": "integer", "minimum": 0 }, + "event_count": { "type": "integer", "minimum": 0 }, + "digest": { "type": "string", "maxLength": 64 }, + "payload_bytes_estimate": { "type": "integer", "minimum": 0, "maximum": 200 }, + "lora_eligible": { "type": "boolean" }, + "verification_state": { "type": "string", "enum": ["local", "advisory", "verified", "unresolved"] } + } +} diff --git a/hardware/simulator/schemas/gateway_discovery.schema.json b/hardware/simulator/schemas/gateway_discovery.schema.json new file mode 100644 index 00000000..22adc782 --- /dev/null +++ b/hardware/simulator/schemas/gateway_discovery.schema.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Gateway Discovery", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "gateway_id", "sequence", "emitted_at", "lan_reachable", "upstream_reachable", "sidecar_reachable", "dashboard_hint", "advertised_roles"], + "properties": { + "packet_type": { "type": "string", "enum": ["gateway_discovery"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "gateway_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "lan_reachable": { "type": "boolean" }, + "upstream_reachable": { "type": "boolean" }, + "sidecar_reachable": { "type": "boolean" }, + "dashboard_hint": { "type": "string", "maxLength": 128 }, + "advertised_roles": { "type": "array", "items": { "type": "string" } } + } +} diff --git a/hardware/simulator/schemas/heartbeat.schema.json b/hardware/simulator/schemas/heartbeat.schema.json new file mode 100644 index 00000000..c1c97c87 --- /dev/null +++ b/hardware/simulator/schemas/heartbeat.schema.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "FlowRouter V0 Heartbeat", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "sequence", "emitted_at", "uptime_seconds", "power_state", "network_state", "cache_state", "sidecar_state", "flowcore_state", "warnings"], + "properties": { + "packet_type": { "type": "string", "enum": ["heartbeat"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "uptime_seconds": { "type": "integer", "minimum": 0 }, + "power_state": { "type": "string", "enum": ["mains", "battery", "unknown"] }, + "network_state": { "type": "string", "enum": ["online", "local-only", "offline", "degraded"] }, + "cache_state": { "type": "string", "enum": ["healthy", "warning", "offline", "unknown"] }, + "sidecar_state": { "type": "string", "enum": ["ready", "degraded", "offline", "unknown"] }, + "flowcore_state": { "type": "string" }, + "warnings": { "type": "array", "items": { "type": "string" } } + } +} diff --git a/hardware/simulator/schemas/local_cache_status.schema.json b/hardware/simulator/schemas/local_cache_status.schema.json new file mode 100644 index 00000000..37881434 --- /dev/null +++ b/hardware/simulator/schemas/local_cache_status.schema.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Local Cache Status", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "sequence", "emitted_at", "cache_id", "mode", "bytes_used", "bytes_limit", "artifact_count", "receipt_count", "verified_count", "unresolved_count", "cache_digest", "health"], + "properties": { + "packet_type": { "type": "string", "enum": ["local_cache_status"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "cache_id": { "type": "string", "maxLength": 48 }, + "mode": { "type": "string", "enum": ["bounded-local", "read-only", "offline", "unknown"] }, + "bytes_used": { "type": "integer", "minimum": 0 }, + "bytes_limit": { "type": "integer", "minimum": 0 }, + "artifact_count": { "type": "integer", "minimum": 0 }, + "receipt_count": { "type": "integer", "minimum": 0 }, + "verified_count": { "type": "integer", "minimum": 0 }, + "unresolved_count": { "type": "integer", "minimum": 0 }, + "cache_digest": { "type": "string", "maxLength": 64 }, + "health": { "type": "string", "enum": ["healthy", "warning", "error", "unknown"] } + } +} diff --git a/hardware/simulator/schemas/nfc_memory_cartridge_metadata.schema.json b/hardware/simulator/schemas/nfc_memory_cartridge_metadata.schema.json new file mode 100644 index 00000000..c462ab2c --- /dev/null +++ b/hardware/simulator/schemas/nfc_memory_cartridge_metadata.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "NFC Memory Cartridge Metadata", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "cartridge_id", "label", "pointer", "digest", "created_at", "expires_at", "contains_secrets", "trust_level"], + "properties": { + "packet_type": { "type": "string", "enum": ["nfc_memory_cartridge_metadata"] }, + "schema_version": { "type": "string" }, + "cartridge_id": { "type": "string", "maxLength": 48 }, + "label": { "type": "string", "maxLength": 64 }, + "pointer": { "type": "string", "maxLength": 128 }, + "digest": { "type": "string", "maxLength": 64 }, + "created_at": { "type": "string" }, + "expires_at": { "type": "string" }, + "contains_secrets": { "type": "boolean", "enum": [false] }, + "trust_level": { "type": "string", "enum": ["untrusted-pointer", "local-only", "advisory"] } + } +} diff --git a/hardware/simulator/schemas/sidecar_status.schema.json b/hardware/simulator/schemas/sidecar_status.schema.json new file mode 100644 index 00000000..d2e66451 --- /dev/null +++ b/hardware/simulator/schemas/sidecar_status.schema.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Sidecar Status", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "sequence", "emitted_at", "radio", "region", "modem_preset", "payload_budget_bytes", "mqtt_state", "tx_enabled", "rssi_dbm", "snr_db", "warnings"], + "properties": { + "packet_type": { "type": "string", "enum": ["sidecar_status"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "radio": { "type": "string", "enum": ["meshtastic", "lora", "disabled"] }, + "region": { "type": "string", "maxLength": 16 }, + "modem_preset": { "type": "string", "maxLength": 32 }, + "payload_budget_bytes": { "type": "integer", "minimum": 0, "maximum": 200 }, + "mqtt_state": { "type": "string", "enum": ["disabled", "private", "public", "unknown"] }, + "tx_enabled": { "type": "boolean" }, + "rssi_dbm": { "type": "integer", "minimum": -200, "maximum": 0 }, + "snr_db": { "type": "number", "minimum": -50, "maximum": 50 }, + "warnings": { "type": "array", "items": { "type": "string" } } + } +} diff --git a/hardware/simulator/schemas/verifier_report_digest_relay.schema.json b/hardware/simulator/schemas/verifier_report_digest_relay.schema.json new file mode 100644 index 00000000..3f02baea --- /dev/null +++ b/hardware/simulator/schemas/verifier_report_digest_relay.schema.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Verifier Report Digest Relay", + "type": "object", + "additionalProperties": false, + "required": ["packet_type", "schema_version", "device_id", "sequence", "emitted_at", "report_id", "subject_digest", "result", "report_digest", "payload_bytes_estimate", "lora_eligible"], + "properties": { + "packet_type": { "type": "string", "enum": ["verifier_report_digest_relay"] }, + "schema_version": { "type": "string" }, + "device_id": { "type": "string", "maxLength": 32 }, + "sequence": { "type": "integer", "minimum": 0 }, + "emitted_at": { "type": "string" }, + "report_id": { "type": "string", "maxLength": 48 }, + "subject_digest": { "type": "string", "maxLength": 64 }, + "result": { "type": "string", "enum": ["valid", "invalid", "unresolved", "stale"] }, + "report_digest": { "type": "string", "maxLength": 64 }, + "payload_bytes_estimate": { "type": "integer", "minimum": 0, "maximum": 200 }, + "lora_eligible": { "type": "boolean" } + } +} diff --git a/research/decentralized-internet/FLOWNET_BOUNDARIES.md b/research/decentralized-internet/FLOWNET_BOUNDARIES.md new file mode 100644 index 00000000..19093293 --- /dev/null +++ b/research/decentralized-internet/FLOWNET_BOUNDARIES.md @@ -0,0 +1,106 @@ +# FlowNet Boundaries + +Last updated: 2026-05-13 + +FlowNet is the working research name for FlowMemory's local resilience and decentralized-connectivity experiments around FlowRouter. This note defines what can be claimed in v0. + +## Boundary Statement + +FlowNet v0 is a local-first resilience experiment. It does not create global internet by itself. At least one gateway needs upstream internet for external sync, and normal data paths use WiFi, Ethernet, cellular, or existing ISP infrastructure. + +Meshtastic and LoRa are low-bandwidth side channels for compact control messages. They do not carry normal app traffic, AI memory, model artifacts, media, or bulk files. + +## In Scope + +- Local LAN availability during upstream outages. +- LAN-only dashboard access. +- Bounded local/offline cache. +- Gateway availability beacons. +- Compact FlowPulse or receipt digests. +- Field diagnostics. +- Device identity and tamper-risk research. +- Enclosure, power, and thermal field notes. + +## Out Of Scope + +- ISP replacement. +- Global internet without upstream gateways. +- Production public mesh infrastructure. +- Passive-income relay/mining claims. +- Tokenomics. +- Full trustlessness claims. +- Custom RF boards. +- Production manufacturing. +- Final CAD without measurements. +- Emergency-service reliability claims. + +## V0 Topologies + +| Topology | What it can show | What it cannot claim | +| --- | --- | --- | +| Single FlowRouter on LAN | Local dashboard and cache behavior during upstream loss. | Mesh resilience or offsite sync. | +| Two FlowRouters with Meshtastic sidecars | Compact control signaling under degraded IP. | Broadband, full receipt sync, or production mesh. | +| FlowRouter plus upstream gateway | Reconnect and cache reconciliation behavior. | Independent global internet. | +| Lab mini PC plus travel router | Measurement, test automation, and routing experiments. | Final hardware product shape. | + +## Trust Boundaries + +- Local cache is local evidence, not final truth. +- Chain-derived receipts and indexer/verifier outputs remain the verification path. +- Radio messages are advisory unless authenticated and replay-protected. +- Physical devices are tamperable. +- Operator dashboards can mislead if they blur local, advisory, and verified state. + +## Appchain Hardware Observer Boundary + +For issue #37, FlowRouter-class devices may later observe appchain or L1-like activity as cache, diagnostic, and operator-visibility nodes. They are not validators, data availability providers, consensus participants, or mandatory protocol infrastructure in V0. + +Allowed observer roles: + +- Cache compact appchain or protocol digests. +- Relay short receipt or verifier-report references over low-bandwidth side channels. +- Show local/advisory/verified state to operators. +- Record field diagnostics that help reconcile state after normal network paths return. + +Not allowed in V0: + +- Validator hardware requirements. +- Validator rewards or hardware economics. +- Data availability duties. +- Consensus duties. +- Production L1 or appchain operation. + +## Claims Allowed In V0 + +- "Keeps a local dashboard reachable on LAN during upstream outage" if measured. +- "Sends compact advisory status over Meshtastic" if measured. +- "Caches selected compact receipts/digests locally" if measured. +- "Uses certified commodity router/radio hardware" when true for the chosen parts. + +## Claims Not Allowed In V0 + +- "Decentralized internet replacement." +- "No ISP needed." +- "Earn passive income." +- "Trustless hardware proof." +- "Production mesh." +- "Unlimited offline AI memory." +- "LoRa carries FlowMemory data." + +## Metrics To Collect + +- Upstream outage detection time. +- LAN dashboard availability. +- Cache write/read and power-loss behavior. +- Reconnect reconciliation notes. +- Meshtastic delivery count, RSSI, SNR, hop count, and retry behavior. +- Device temperature and power draw. +- Operator confusion points. +- Tamper observations. + +## Follow-Up Decision Needs + +- Whether FlowRouter needs a formal device identity scheme. +- Whether FlowNet should define public gateway rules. +- Whether local dashboard state needs a strict local/advisory/verified taxonomy. +- Whether Memory Cartridges are NFC-only in v0 or include removable storage later. diff --git a/research/meshtastic/MESHTASTIC_ROLE.md b/research/meshtastic/MESHTASTIC_ROLE.md new file mode 100644 index 00000000..00b9896a --- /dev/null +++ b/research/meshtastic/MESHTASTIC_ROLE.md @@ -0,0 +1,70 @@ +# Meshtastic Role In FlowRouter v0 + +Last updated: 2026-05-13 + +Meshtastic is a FlowRouter v0 sidecar for low-bandwidth control signaling. It is not a replacement for WiFi, Ethernet, cellular, ISP service, or normal internet access. + +## Role Summary + +Meshtastic may support: + +- Node heartbeat. +- Gateway availability status. +- Compact FlowPulse digest announcements. +- Artifact availability digests. +- Compact receipt references. +- Field diagnostics. +- Emergency/local operator attention signals. + +Meshtastic must not carry: + +- Heavy AI memory. +- Model artifacts. +- Media. +- Bulk app data. +- Full receipts or logs. +- Secrets. +- Production command traffic. + +## Network Model + +- WiFi/Ethernet carries normal FlowMemory data. +- At least one gateway needs upstream internet for external sync. +- Meshtastic may keep nearby operators informed when IP paths are degraded. +- Meshtastic may help correlate local logs after reconnect. +- Meshtastic messages are advisory until verified by authenticated local policy and normal verification paths. + +## Configuration Assumptions + +- Set the correct LoRa region before transmit. +- Devices in the same mesh need compatible region and modem settings. +- Keep hop count conservative. +- Keep messages small and infrequent. +- Use private channels for field tests when possible. +- Treat channel keys as test secrets that must not be committed. +- Avoid public MQTT by default. +- If MQTT is used, prefer a private broker and explicitly document uplink/downlink settings. + +## Privacy And Security + +Meshtastic payload encryption does not hide all metadata. V0 should assume: + +- Node IDs and routing metadata may be visible. +- Channel keys can leak. +- Packets can be replayed. +- Sender identity can be spoofed without additional authentication. +- Messages can be delayed, lost, duplicated, or reordered. +- Public MQTT can expand the exposure of packets and metadata. + +## Research Questions + +1. What is the minimum useful status interval before channel congestion becomes a problem? +2. Which control messages remain useful when only one or two messages are delivered? +3. How should FlowRouter present "radio advisory" state versus verified state? +4. What authentication scheme fits the payload budget without creating dangerous false confidence? +5. What field metrics are needed to compare RSSI/SNR, distance, antenna placement, and enclosure effects? +6. How should public MQTT be avoided or safely isolated in lab tests? + +## Link To Hardware Inventory + +The candidate message inventory lives in `../../hardware/lora-sidecar/CONTROL_MESSAGE_INVENTORY.md`.