TharMesh

TharMesh — Offline Mesh Communication System A delay-tolerant, multi-hop offline communication system designed for low-connectivity environments.

TharMesh lets Android phones exchange messages without any internet, cellular data, or central server. Devices talk directly over Bluetooth and Wi-Fi using Google Nearby Connections, relay each other's messages through a multi-hop mesh, and store-and-forward bundles until they reach their destination — even hours later, when a peer comes back into range.

Key Features The features listed below are implemented in the current build and covered by unit or integration tests:

Multi-hop relay messaging. Bundles are forwarded through intermediate peers until they reach the destination. Loop prevention via a seen-set; duplicate floods bounded by a bundle-id LRU cache. Store-carry-forward delivery. Bundles are persisted in Room and re-broadcast on every retry tick, so a message sent while a peer is out of range is delivered as soon as the peer (or any relay) reconnects. Truthful message status pipeline. QUEUED → SENDING → SENT → DELIVERED → READ, with rank-protected status transitions that prevent regression on concurrent acks. A FAILED state is surfaced for transport-level rejections and supports manual retry. Exponential retry with jittered backoff. Per-bundle policy: 5s → 10s → 20s → 40s → 60s with ±20 % jitter and a 60s ceiling. No fixed cap on attempts — DTN principle: a peer may legitimately return after hours. Aggressive SOS path. Priority bundles use a compressed retry curve (1s → 2s → 4s → 8s, no jitter) and bypass per-peer pacing, so an SOS broadcast fans out at full rate. TTL and hop-count enforcement. A per-bundle TTL (default 24 h) and hop counter are checked at every receive, forward, and retry path. Expired or hop-exhausted bundles are dropped at the source. Cryptographic identity. Each device generates an ECDSA P-256 keypair on first launch. Bundles are signed (SHA256withECDSA); peers exchange public keys via QR invite codes and verify signatures before accepting bundles. Per-peer send pacing. A 40 ms minimum gap between sends to the same peer prevents the Nearby send buffer from being overwhelmed under burst conditions. Peer-churn debounce. Rapid PeerConnected events for the same peer are coalesced into a single trailing retry-flush (1.5 s window) to avoid retry storms on flaky links. Permission and connection visibility. A status banner surfaces missing permissions, Bluetooth-off, and Location-off states, plus searching / connected / no-devices indicators when the mesh is healthy. Diagnostics and Field Test Mode. An on-device diagnostics screen exposes counters (peers seen, retries, paced sends, TTL drops, stuck-sending recoveries) and exports a JSON snapshot via the share intent. Field-test toggles re-shape the retry curve to make behaviour visible in seconds rather than minutes. Loopback transport for tests. A purely in-process transport implementation drives 129 unit tests covering routing, retries, pacing, and crash recovery without requiring a real radio.

Known Limitations Android only. TharMesh depends on Google Nearby Connections, which is Android-specific. There is no iOS or desktop client. Nearby radio range. Bundles only propagate when peers are physically within Bluetooth or Wi-Fi-Direct range (typically 30–100 m line-of-sight). TharMesh does not use the internet as a fallback. Bundles are signed AND end-to-end encrypted once both sides have seen each other. Every bundle is authenticated with ECDSA P-256 signatures so a peer cannot forge a message from someone else. Body encryption uses AES-256 / GCM with a per-pair key derived via static ECDH over the same P-256 keypair (HKDF-SHA256 binds both user IDs into the KDF). The first time we send to a peer whose public key we have not yet pinned (TOFU has not fired), the body falls back to plaintext so the bootstrap path stays open — once their signed bundle pins their key in the TOFU store, subsequent sends are sealed automatically. Receivers transparently unseal TME1:-framed bodies and fall back to plaintext for legacy bundles. Battery cost. Continuous Nearby advertising and discovery is non-trivial — expect a measurable battery hit when the mesh is left running for hours. Power-aware duty cycling is on the roadmap. SOS priority and retry-curve state persist across restarts. The v5→v6 migration adds a retry_state table that mirrors the in-memory RetryPolicy per-bundle attemptCount / nextRetryAt plus the priority bit. After a forced app kill, the next MessageRepository seeding reads those rows back so SOS bundles stay on the aggressive 1s→2s→4s→8s curve and normal bundles resume their curve position instead of restarting from base delay. Writes are best-effort (fire-and-forget on the IO dispatcher); a lost write falls back to the pre-persistence behaviour for that bundle only. Per-peer relayed-bytes accounting is surfaced in Diagnostics but not used as a fairness signal. The Diagnostics screen shows, per destination peer, the total bytes we have forwarded on their behalf plus the number of relay frames sent. This gives a field-test fairness view; it does not yet feed back into routing or pacing decisions. Field-test toggles take effect on next sign-in. They are not hot-swappable while the engine is running. CI runs assembleDebug + testDebugUnitTest on every PR (GitHub Actions, .github/workflows/android.yml). On-device field tests are still manual — the CI job covers unit tests only, not instrumented or multi-radio scenarios. No file or media transfer. TharMesh today is a small-text-payload messaging substrate.