add new "advanced wireless documentation" based on the post: https://www.sr2.uk/posts/2026-butter-box-connectivity

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
 

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.