From cb5970ea4331babc06f60e02502a75970fa6305d Mon Sep 17 00:00:00 2001 From: n8fr8 Date: Mon, 13 Apr 2026 22:35:32 -0400 Subject: [PATCH] add new "advanced wireless documentation" based on the post: https://www.sr2.uk/posts/2026-butter-box-connectivity --- README.md | 1 + docs/wireless_connectivity.md | 127 ++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 docs/wireless_connectivity.md diff --git a/README.md b/README.md index 9357115..5f9374d 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ vmdb2 --rootfs-tarball=my_image.tar.gz --output my_image.img --log my_image.log * [Creating an upgrade content pack for the Butter Box](./docs/upgrade_pack.md) * [Set up DeltaChat messaging between multiple boxes](./docs/multibox.md) +* [Extending Butter Box connectivity with WiFi HaLow and LoRa](./docs/wireless_connectivity.md) ## Copyright and Licence diff --git a/docs/wireless_connectivity.md b/docs/wireless_connectivity.md new file mode 100644 index 0000000..9804941 --- /dev/null +++ b/docs/wireless_connectivity.md @@ -0,0 +1,127 @@ +# Extending ButterBox connectivity with WiFi HaLow and LoRa + +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.