📡 How a Loomwave message finds its way

How a message travels from one pocket radio to another, through the towers.

The neighborhood: cells and the backbone

Every Loomwave radio (a client — the little box that talks to your phone) belongs to a cell: a small group of radios that all listen to one coordinator. The coordinator is the referee — usually up on a tower or a roof so everyone can hear it. Coordinators that can hear each other form the backbone: a radio highway between neighborhoods.

Cell A Cell B backbone Coordinator A 🗼 Coordinator B 🗼 You Friend

The classroom picture: it's like two classrooms with a teacher in each, and the teachers have walkie-talkies to each other. Kids don't shout across the school — they tell their teacher, and the teachers pass it along.

Every radio has a name it can prove

Each radio makes itself a secret key, and its address is squeezed out of that key — a six-character tag like A1B2C3 or D4E5F6 (illustrative examples). That's called self-certifying: you can't pretend to be A1B2C3 unless you hold its secret, because messages are signed with it. Messages are also encrypted — sealed envelopes only the destination radio can open. The coordinators carry them but can't read them.

The heartbeat: nobody talks over anybody

LoRa radios are slow — one long message can take half a second of airtime — so if everyone transmitted whenever they felt like it, they'd trample each other. Instead the coordinator runs a steady heartbeat called a frame (a few seconds long, repeating forever):

BEACON slot 1 ⬆ slot 2 ⬆ slot 3 ⬆ downlink window ⬇ "I'm here — sync your clocks to me" members take turns sending UP coordinator sends DOWN, everyone listens — one frame, ~5 seconds, repeats forever —

The frame starts with a beacon: the coordinator saying "I'm here, here's the exact time, here's who talks when." Each member gets a slot — a private turn to transmit up. Then comes the downlink window, when every member is guaranteed to be listening and the coordinator delivers whatever it's carrying. Radios can nap the rest of the time to save battery — they know exactly when they matter next.

The classroom picture: the teacher calls roll, each kid gets a turn to speak, and then the teacher reads the announcements while everyone's quiet. Then it all repeats.

A message's journey, hop by hop

You 📱 Coord A Coord B Friend 📱 ① your slot ⬆ ③ backbone hop ④ downlink ⬇ ② "Is the destination one of MY members? … no → forward" ✓ "got it, sending" ✓✓ "your friend's radio has it" (delivery receipt, hops all the way back) ⑤ ack
1
Up to your coordinator. Your phone hands the message to your radio over Bluetooth; your radio waits for its slot in the frame and transmits it up, addressed to Friend's tag. If the coordinator doesn't hear it (radio noise happens), your radio simply tries again next frame — that's ARQ, "automatic repeat request." You see the first ✓ when the coordinator confirms it.
2
The routing decision. The coordinator keeps a roster of its own members. Destination in the roster? Then it's easy: hold the message a moment and deliver it in the next downlink window. Not in the roster? Then it goes on the forward queue for the backbone.
3
Across the backbone. Coordinators share the highway by taking alternate half-frames (the A/B stagger — see below), so relays never collide with their own cells. The message hops coordinator-to-coordinator until it reaches the one whose roster contains your friend.
4
Down to the friend. Coordinator B waits for its downlink window — the moment all its members are guaranteed listening — and transmits the still-sealed envelope. Only your friend's radio can decrypt it.
5
Proof, all the way back. The friend's radio acknowledges; a tiny delivery receipt retraces the whole path back to you. That's the second ✓✓ in the app: not "I sent it" but "their radio has it."

The A/B stagger: how two referees share one whistle

The backbone and the cells share the same radio channel, so backbone coordinators split time: one runs its cell in the first half of the frame and relays in the second; its neighbor does the opposite. Each one beacons offset by half a frame from its peer — like two Ferris wheels timed so their cars never pass the platform together.

Coord A serve my cell relay on backbone Coord B relay on backbone serve my cell half-frame boundary — the "stagger"

For this to work every coordinator must agree what time it is. They derive the frame count ("epoch") from real clock time, and a coordinator only trusts a peer's timing if it comes from an equal-or-better time source — that's the stratum rule. It also stops a nasty trick: a recorded beacon replayed later carries a stale epoch, and everyone ignores it.

Many coordinators, many paths: who decides?

When lots of coordinators can hear each other, there may be several ways to reach a destination. Loomwave's answer is sneaky-simple: don't pick paths — follow ownership. Every coordinator's LSA ("link-state advertisement", sent every few frames) says "here are the members I'm currently hearing, and here's how loudly I hear my neighbor coordinators." A message for F goes to whichever peer claims F as a member right now.

Coord A (has the message) Coord B Coord C — LSA says: "F is MINE" chosen: straight to the owner F 📱 strong, fresh A can *barely* hear F directly (−103 dBm)… and deliberately does NOT use this
1
Peer-owns-it wins. A coordinator only advertises members it's actively hearing, so "C claims F" already proves C has a fresh, working last hop. No path math needed — the best last mile picks itself.
2
Weak shortcuts lose on purpose. A real field bug shaped this: a tower could hear a distant client at −103 dBm — technically alive, practically doomed — and kept trying the direct delivery. Now a peer's solid claim outranks the marginal direct link.
3
Moving radios hand off cleanly. If a client roams and a peer starts claiming it, the old coordinator forwards there and drops its stale roster row — make-before-break, like your phone switching cell towers.
4
No infinite loops. Every forward carries a hop budget that counts down, and nothing is ever sent back toward whoever sent it. On the group/channel path a coordinator also remembers what it has already relayed, so a second copy of the same channel message is dropped instead of forwarded. The budgets are preset by frame type: relayable unicast frames start at 3 hops (the wire field allows up to 15), frames that must never be relayed — beacons, direct downlinks — are deliberately minted with a budget of 0 so a relay refuses them by design, and group floods are clamped to 2 backbone rings no matter what the sender asked for.
5
Group chats flood — with brakes. Channel messages go to every peer whose summary says "I have subscribers for that channel," rate-limited per peer, hop-budgeted, deduped. Broadcast where wanted, silence where not.

The classroom picture: nobody has a map of the whole school. Each teacher just keeps shouting "here's who's in MY class today!" — so when a note needs to reach Frankie, you hand it to the teacher who most recently called Frankie's name. Even if you can faintly hear Frankie yelling from three rooms away, you still give the note to his own teacher.

Fine print for grown-ups: the LSAs also carry per-link signal strength between coordinators, so the network already collects everything a classic shortest-path algorithm would need — the decision function is deliberately a small, swappable, unit-tested pure function (route::downlink) for the day the mesh outgrows ownership-greedy routing.

Why it's built this way

No shouting matches: slots and windows mean the slow LoRa channel never wastes airtime on collisions. Battery: a client knows the exact moments it must listen and sleeps otherwise. Privacy: the network carries sealed envelopes; even the towers can't peek. Honesty: the double-check ✓✓ is a real end-to-end receipt, not a guess. And when a tower goes away, another radio can stand up as coordinator, mint its own proof-carrying address, and the neighborhood re-forms around it.