churn/docs/wireless_connectivity.md

# Extending ButterBox connectivity with WiFi HaLow and LoRa

*This documentation is entirely based upon the original blog post ["Butter Box Connectivity"](https://www.sr2.uk/posts/2026-butter-box-connectivity).*
 
ButterBoxes are designed to operate in areas with limited or no Internet connectivity. In some
deployments, it is useful to extend the range over which boxes can communicate with each other,
or over which client devices can reach a box, beyond what conventional WiFi allows. This document
describes two long-range wireless options that have been evaluated for use with the ButterBox,
 **WiFi HaLow** (IEEE 802.11ah) and **LoRa**, and explains how to set each one up as a bridge in front of a box.

Both approaches let you keep the ButterBox itself unchanged: the long-range radio acts as a
transparent link between the box and the remote client (or another box), so the existing portal,
Delta Chat relay, and update mechanisms continue to work as normal.

## Choosing between HaLow and LoRa

| | WiFi HaLow | LoRa |
| --- | --- | --- |
| Typical range | ~400 m (modeled), usable up to ~500 m | Greater than HaLow |
| Throughput | Up to ~8.9 Mbps (Region 1/3), ~43 Mbps (Region 2); often much lower in practice | ~2680 bits per second |
| Cost per node | ~£155 (Morse Micro evaluation kit) | ~£26 (USR-LG206-P RS232 bridge) |
| Good for | Portal access, multi-box networks, software updates | Very low bandwidth messaging, store-and-forward |

In short: pick **HaLow** if you need clients to reach the ButterBox portal or to push updates
between boxes at reasonable speeds. Pick **LoRa** if you only need to move very small amounts
of data over a longer distance, and you are prepared to use protocols designed for slow,
high-latency links.

> WiFi HaLow operates in sub-1GHz ISM bands. The exact frequency allocation depends on your
> region: 863–870 MHz in ITU Regions 1 and 3, and 902–928 MHz in Region 2. Make sure
> the hardware you buy is approved for use where you intend to deploy it.

## Option 1: WiFi HaLow bridge

This setup uses a pair of Morse Micro HaLow evaluation kits to create a long-range bridge in
front of the ButterBox. Conventional WiFi clients connect to the mobile end of the bridge and
reach the box transparently over HaLow.

### Requirements

- 2 × Morse Micro **MM8108-EKH19** evaluation kits (available from Mouser Electronics,
  approximately £155 each).
- A ButterBox running the standard image, with its portal and Delta Chat relay configured.
- A power source for the mobile end of the bridge - a USB powerbank is sufficient.
- Antennas appropriate for the band allowed in your region.

### Setup

1. Place the first HaLow kit alongside the ButterBox and connect it to the box's LAN port.
   This unit acts as the **stationary bridge** at the box's location.
2. Configure the second HaLow kit as the **mobile bridge**. Power it from a powerbank so it
   can be carried or positioned away from the box.
3. Both kits must be configured to use the same HaLow channel within the band approved for
   your region (863–870 MHz or 902–928 MHz). Refer to the Morse Micro evaluation
   kit documentation for the exact channel selection commands.
4. The mobile bridge exposes a conventional 2.4 GHz WiFi network. Client devices (phones,
   laptops) join this network in the normal way; their traffic is then relayed over HaLow to
   the stationary bridge and on to the ButterBox.
5. Because the bridge is transparent at the IP layer, no changes are needed on the ButterBox
   itself. Clients reach the portal at the usual `butterbox.local` address.

### Notes on performance

- Coverage modelling suggests reliable operation out to roughly 400 metres, and the ButterBox
  portal remained reachable in tests at around 500 metres.
- Link speed is volatile: even within 50 metres, throughput can drop to around 0.3 Mbps before
  recovering. Expect the portal to feel slower than over conventional WiFi.
- HaLow operates in an ISM band and must implement "listen before send". Heavily congested
  environments will reduce effective throughput further.
- For multi-box deployments (for example, several ButterBoxes across a school, refugee camp,
  or evacuation centre) HaLow has enough bandwidth to also push updates between boxes. 
  See [upgrade_pack.md](upgrade_pack.md) for the offline upgrade workflow this complements.

## Option 2: LoRa serial bridge

LoRa offers significantly greater range than HaLow but at a fraction of the throughput. It is
not suitable for portal access, but can be used for very low bandwidth messaging or
store-and-forward style workflows between boxes.

### Requirements

- 2 × **USR-LG206-P** RS232-to-LoRa bridges (available from AliExpress, approximately
  £26 each).
- A USB-to-RS232 adapter for each ButterBox the bridge is attached to, unless the box already
  has a serial port.
- Antennas appropriate for the band approved in your region (typically 868 MHz or 915 MHz; the
  433 MHz band is also available in some regions but overlaps with amateur radio allocations).

### Setup

1. Connect a USR-LG206-P to each ButterBox you want to link, using the USB-to-RS232 adapter.
2. Configure both LoRa bridges with matching frequency, spreading factor, and network ID
   settings. The factory defaults will work for a point-to-point link, but the frequency must
   be set to a band approved in your region.
3. The bridge presents itself as a serial device on the ButterBox (typically `/dev/ttyUSB0`).
   Any application that can speak over a serial link can now exchange data between the two
   boxes.
4. For practical use, layer a protocol designed for slow, high-latency links on top of the
   serial connection. A reasonable starting point is **UUCP**, which is packaged in the Debian
   repositories the ButterBox already uses and is well suited to store-and-forward delivery
   over unreliable links.

### Notes on performance

- The advertised throughput of the USR-LG206-P is **2680 bits per second** ... bits, not
  kilobits. Plan accordingly: this is enough for small text messages and metadata, but not for
  interactive use of the portal.
- LoRa's physical layer is a proprietary Semtech standard. There is currently no fully open
  source implementation of the radio itself, although the application protocols you run over
  it can be open.
- Because the link is so slow, generic IP-over-serial approaches will be unsatisfactory.
  Protocols specifically designed for constrained links (for example tinySSB, which uses
  aggressive compression and small packet sizes) are a better fit if UUCP does not meet your
  needs.

## Testing

Once a bridge is in place, the simplest end-to-end test is the same one used in the
[multi-box Delta Chat setup](multibox.md): create a Delta Chat account on each ButterBox and
exchange a test message. If the message is delivered, the link is working at the application
layer.

For HaLow setups, you can additionally browse to the ButterBox admin portal from a client
device connected to the mobile bridge, and confirm that pages load (slowly is fine).

For LoRa setups, do not expect the portal to be usable. Instead, verify the serial link with
a tool such as `minicom` or `screen` on each box, then test your chosen application protocol
(for example UUCP) by queueing a small file for delivery in one direction and confirming it
arrives at the other end.