CAT manual
Mesh networking and Wi-Fi
How CAT's mesh network works, the MESH settings, and Wi-Fi.
Reticulum#
CAT's networking runs on Reticulum, a networking stack for building networks without central infrastructure. Its design principles are described in The Zen of Reticulum.
- Uncentralizable. There is no central server or account system. Any device can carry traffic for any other, over radio, Wi-Fi, the internet or a serial cable.
- Encrypted. Every message is end-to-end encrypted. Addresses are public keys, so no registration is needed.
- Trustless. Relays carry packets they can't read.
Each CAT is a first-class node, and every CAT that switches on grows the network. A node does four jobs.
Messaging#
CAT sends and receives encrypted messages and doodles, with other CATs and with LXMF apps on phones and computers. See Chat.
Routing#
CAT is a Reticulum transport node. It forwards all Reticulum traffic for the network, so traffic between any two devices can travel through your CAT.
Bridging LoRa and IP#
When CAT is on Wi-Fi, it connects the LoRa radios around it to the Reticulum network on the internet. Anyone nearby with a LoRa radio, such as an RNode used with Sideband, can reach people anywhere through your CAT.
Store and forward#
CAT is an LXMF propagation node. It stores LXMF messages for anyone who is offline, syncs them with other propagation nodes, and delivers them when the recipient reappears. As you carry it around, it picks up mail from the radio neighbours it meets, and passes it on when it connects to other mail nodes, such as its home hub.
NTN (satellite) and BLE messaging are in development.
How the mesh works#
| Term | Meaning |
|---|---|
| LoRa | The long-range, low-power radio built into CAT. CATs within radio range talk to each other directly, with no phone network, Wi-Fi or internet needed. |
| Reticulum | The networking system CAT uses. It finds paths between devices and encrypts everything end to end. |
| LXMF | The message format on top of Reticulum, shared with apps like Sideband and NomadNet. |
| Transport node | A node that forwards all Reticulum traffic for the whole network: packets, announces, path requests and links. Every CAT is a transport node by default. |
| Propagation node | A node that propagates all LXMF messages: it stores messages for anyone who is offline, syncs them with other propagation nodes, and delivers them when the recipient reconnects. Every CAT is a propagation node by default, and uses one (its mail node) for its own messages that can't be delivered directly. |
| TCP bridge and hubs | Over Wi-Fi, CAT connects to a public Reticulum hub on the internet. That links the CATs around you to the rest of the network, and lets you reach friends far away. |
| Sanctuary | The project's home hub. CATs connect to it first and also use it as their default mail node. |
The radio's frequency and other settings are fixed when CAT is set up. CATs hear each other when they use the same radio settings.
The MESH page#
Settings → SETTINGS → MESH. The top of the window is a live status report; the rows below change your CAT's roles. Changes apply at once and are saved when you leave Settings.
- Transport: ON, 7 paths
- CAT is a Reticulum transport node: it forwards all Reticulum traffic it receives (packets, announces, path requests and links) for every device on the network, and currently knows 7 paths. Transport: off (leaf) means CAT carries only its own traffic.
- Propagation node: SERVING, 2 held
- CAT is an LXMF propagation node: it accepts, stores and passes on LXMF messages for every LXMF user, and syncs them with other propagation nodes. It is holding 2 messages now.
- Mail via: d4737137 (home)
- The propagation node that takes your own outgoing mail when a friend can't be reached directly. (home) is Sanctuary. fallback means CAT picked another node because home is out of reach. direct only means MAIL NODE is off. no node reachable means CAT found none.
- TCP bridge: auto UP :4965
- The state of the internet link: UP, connecting, retrying, waiting for WiFi, WiFi is off, no host set or off.
- Bridging LoRa/TCP: yes
- CAT is joining the LoRa mesh and the internet: transport is on, the TCP bridge is up and the radio is online.
| Row | Default | What it does |
|---|---|---|
| TRANSPORT NODE | On | Forward all Reticulum traffic for the network. |
| PROPAGATION NODE | On | Store and propagate all LXMF messages. |
| MAIL NODE: HOME | Home | Choose where your undeliverable mail goes. Press A to cycle HOME → AUTO → OFF → HOME. |
| TCP BRIDGE | – | The internet link window (below). |
| RESET TO DEFAULTS | – | Asks Restore default mesh settings?. This also resets your device name, the Wi-Fi switch and the hub choice. |
Mail node: HOME, AUTO or OFF#
- HOME (default): use Sanctuary's mailbox whenever your CAT has a working internet route to it. Without one, CAT picks the best nearby node instead and switches back when the route returns. Home is never looked for over LoRa.
- AUTO: always pick the best node CAT can find, over radio or internet.
- OFF: deliver directly only. Messages to unreachable friends fail instead of waiting in a mailbox.
Switching mail node doesn't move messages already waiting on the old one. A custom node can be set from the USB shell; the menu then shows MAIL NODE: CUSTOM.
TCP BRIDGE and hubs#
The TCP bridge needs Wi-Fi. By default it uses a built-in list of 32 public hubs, starting with Europe - Sanctuary (home). If a hub stops answering, CAT moves to another one and later tries home again.
| Row | What it does |
|---|---|
| ENABLED | Turn the internet link on or off (on by default). |
| CHOOSE HUB FROM LIST | Start from a different hub in the list. CAT still moves on if it fails. |
| CUSTOM HOST / CUSTOM PORT | Type your own hub's host name or IPv4 address, and port (default 4965). |
| USE CUSTOM HOST | Switch to your custom hub. Rejected with Host must be a host name or IPv4 address, port 1-65535 if it isn't valid. |
| USE AUTOMATIC LIST | Shown only on a custom hub: go back to the built-in list. |
Wi-Fi#
Settings → SETTINGS → WIFI. Wi-Fi is used for the TCP bridge and for Crypto uploads. Your networks and passwords are stored on CAT's board controller and survive resets and game updates. Up to 8 networks are remembered, most recent first.
Joining a network#
- Choose SCAN NETWORKS. After SCANNING Please wait..., nearby networks are listed.
- Pick yours. The keyboard opens for the password (leave it empty for an open network) and press DONE.
- Check the password shown on CONNECT TO and choose CONFIRM.
- Wait for SUCCESS Connected, and press A. A network you connect to is saved automatically.
If it fails you see FAILURE with Connection failed, No response, No networks found or Scan failed.
Saved networks and adding by hand#
- SAVED NETWORKS lists remembered networks and has the AUTOCONNECT switch. With it on, CAT reconnects by itself when it is offline and idle. Pick a network to see its security type and CONNECT or FORGET it. FORGET acts immediately.
- ADD NETWORK is for hidden networks: type the name, optionally a password, and SAVE. With a password it is saved as WPA2, without as open.
- Untick WIFI ON to turn the Wi-Fi radio off. LoRa keeps working; the TCP bridge waits.
CAT joins open, WEP, WPA and WPA2 networks.
What happens to a message#
- If your friend is one radio hop away or reachable over the internet link, CAT sends it straight there and waits for a delivery receipt (two green ticks).
- If they are farther, CAT tries directly once, then gives the message to its mail node (one tick and a dot), retrying after 1, 2 and 4 minutes.
- If CAT has never heard of the recipient, it asks the network and waits up to 3 minutes.
- When your friend's CAT comes online, it collects its mail from the propagation node.