disaster.radio, a sun powered mesh network for the day the towers are down

The project says it is paused, and that is the first fact

The first line of the README is the one to read before anything else. disaster.radio is currently not actively developed and seeks a new maintainer, with a link to the issue where that is being discussed.

After that, the project describes itself as a work-in-progress long-range, low-bandwidth wireless disaster recovery mesh network powered by the sun. Those three adjectives, work-in-progress, low-bandwidth and long-range, are the whole design brief.

The low-bandwidth constraint is what shapes everything else. The data that flows over the network is text chat, not voice and not data, because a text message is something a LoRa radio can carry across kilometres on a small solar budget and a voice call is not. The README describes the use cases as a demo chat app served by the disaster-radio, an Android chatbox, and a separate mapping web application.

The repository layout shows how complete the system is, which is the reason to look at it even if you never build one. There is a firmware/ directory with the main example code for ESP32 dev boards, a src/ directory with the disaster radio library code used by both the firmware and a simulator, a web/ directory with the demo chat app, a hardware/ directory holding the KiCad board layout and schematic, an enclosure/ directory with 3D models of the enclosures, a research/ directory, and a diagram.dot and diagram.png describing the architecture. There are also separate repositories for the Android app and for the mapping web application.

On the state of the code, the release tags tell their own story. The most recent is 1.0.0-rc.1, an esp32 release candidate from 2020-04-14, before that 0.2.0 and 0.1.1, both esp32_ttgo pre-releases from early 2020. The last push to the repository was on 2026-05-22, so the tree has been touched since the last release, but the released artefacts are from 2020.

The layered model, and why server and client are not what you think

The firmware is made up of a single server and a number of clients, plus middleware that sits between the clients and the server. The README immediately adds the caveat that these are a server and clients in the logical, software sense, not a literal, networking sense.

That caveat is the design. In a real LoRa deployment, every node can hear its neighbours and there is no server in the radio sense, but the software still needs one component that owns the message history and fans messages out to the right destinations. The DisasterServer module contains the DisasterRadio class, described as the main server that takes messages from clients and sends them to other clients.

The clients are the interesting list, because each one is a way in or a way out. LoRaClient interfaces with LoRaLayer2, the radio link. WebSocketClient handles WebSocket connections from the web app. StreamClient is for an Arduino Stream and is currently used for the serial console. TCPClient provides a telnet-like server. HistoryRecord records messages to an SD card or to a bounded queue in memory. OLEDClient displays messages on the screen, mostly for debugging purposes, though the author says he would eventually like to use it for a mobile Disaster Radio terminal of some kind. And GPSClient is a proof of concept that interfaces with a serial GPS module to beacon your current location periodically.

The middleware does the things that make it usable rather than merely connected. WelcomeMessage is a very simple welcome shown to clients when they connect. HistoryReplay shows history to clients when they connect, which is the feature that makes a text network survivable, because a node that was offline for an hour can catch up. And Console implements a simple console with chat, similar to the web app, plus some slash commands, with the author noting he went with a more IRC-like syntax but that you could easily implement a getopt version.

The history subsystem has two implementations, HistorySD which records to an SD card and HistoryMemory which records to a bounded queue in memory with a default limit of 10 messages.

The protocol is described in one paragraph. The server and clients communicate using datagrams that include a destination address, a message type and a message, and the README points to a wiki page on the disaster radio networking stack, the Layered Model page, for the detail.

Hardware, pinouts and the LoRa interrupt

The hardware section is short and points at three places. There is a Devices and Hardware wiki page for supported development boards, the pinouts for supported boards are in firmware/esp32/config.h, and the hardware/ directory holds the KiCad board layout and schematic.

The wiring notes cover the details that a LoRa plus SD card plus display board creates. DIO0 sends an interrupt from the LoRa transceiver upon transmit or receive ready. Chip selects can be used to explicitly switch between the LoRa transceiver and the SD card, though the SD card should be enabled by default, since the LoRa interrupt appears to handle enabling the transceiver. The author flags the open question himself in the same sentence, noting that this still needs to be thoroughly tested, and asking what happens if you receive an interrupt while loading from the SD.

That is the kind of caveat that tells you the design is still in motion rather than finished, and it is worth flagging to anyone planning to build from it.

The build is PlatformIO based, and the setup is one command:

pip install -U platformio

Then you edit platformio.ini to suit your needs. For an ESP32 LILY TTGO board you probably will not have to edit anything, but you must make sure upload_port is set to the correct device, which may vary depending on your operating system and which other devices you have connected.

To check the firmware compiles without flashing, pio run builds all the libraries and main firmware files, and the resulting binary is stored as .pio/build/ttgo-lora32-v1/firmware.bin.

Flashing to a dev board is a USB connection and one more command, with upload_port and upload_speed set correctly in platformio.ini:

pio run -t upload

By default PlatformIO builds and flashes for the LILY's ESP32 TTGO V2 dev board. For another board you select the corresponding build environment, and to build and flash the firmware and file system for the ESP32 TTGO V1 board the command is:

pio run -e ttgo-lora32-v1 -t upload -t uploadfs

There is also advice for developers, including the tip that it may be a good idea to delete the libdeps folder prior to rebuilding, as old, out-dated libraries could cause conflicts, with the command rm -rf .pio/libdeps, and the way to override a specific library such as LoRaLayer2 by cloning it into the firmware/lib folder that is created after running pio run and then commenting it out or removing it from the lib_deps list in platformio.ini.

Why the design is worth studying even while it is paused

The honest reason to spend time on this repository is that it is a complete example of an embedded system designed around a constraint rather than around a feature list.

The constraint is that a disaster destroys the infrastructure people normally depend on, including cellular towers, and that in the first hours after that there is no power and no reliable place to charge a phone. A solar powered node with a LoRa radio that can sit for days and relay text messages over kilometres addresses exactly that, and the design consequences ripple through the whole repository. The chat interface rather than voice is the bandwidth decision. The SD card history rather than a database is the durability decision. The history replay on connect is the assumption that a node might have been down. The GPS beacon is the awareness feature. The 12-bit and 9-bit palette limits in the sibling project are the display decision.

The protocol design is the part most people would want to read. A datagram with a destination address, a message type and a message, delivered by a server component that fans messages out, is a small and legible design that someone could implement in an afternoon for a different radio. The Layered Model wiki page exists precisely so that it can be understood without reading the firmware.

The web/ directory is the demo chat app, built with npm and documented in web/README.md, and the README notes you can download a pre-built version if the npm build gives you trouble. There is also a step for building and uploading the SPIFFS image, which is how the web app and its assets get onto the device's flash.

So the realistic assessment is this. The project is paused and it is looking for a maintainer, which means the code is available for adoption and the design is documented enough to be picked up. What it is not is a product you can deploy today without expecting to finish the job. The LoRa interrupt and SD card interaction is still marked as needing thorough testing, the emulator files situation and the versioning of the protocol are the kind of thing a new maintainer would want to settle, and the released artefacts are six years old relative to the last commit.

Editorial conclusion

disaster-radio suits an engineer who wants to study a complete embedded disaster-communication system, because the firmware, the protocol design, the circuit board, the enclosures and the chat front end are all in one repository, and it suits a community network operator who can pick up the hardware design and the protocol. It is the wrong choice if you need a maintained product, because the README states that the project is currently not actively developed and seeks a new maintainer, and it is the wrong choice for anything beyond text, since the whole design is low-bandwidth by intent. Before building, read the layered model wiki page, because the server and client terminology in the code is logical rather than literal, and check the ESP32 configuration header for the pinouts of the board you intend to use.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. sudomesh/disaster-radio on GitHub