Getting started

Spangap runs on Linux and Mac. Windows with WSL is untested. All the host needs is Docker, git and Python 3 — everything else lives inside the build container and the workspace directory you create.

This page builds something real: Reticulous, the Reticulum mesh firmware developed alongside Spangap. If you just want to see it run, flash a ready-made image first.

Install the launcher

curl -fsSL https://spangap.org/install.sh | sh

This downloads the spangap launcher, a single file, checks that Docker, git and Python are there, and puts it on your PATH, asking where if it isn’t sure. Pass --bin-dir DIR to choose the directory outright, or -y to accept the defaults without prompting.

Or do it by hand:

curl -o ~/bin/spangap https://raw.githubusercontent.com/spangap/spangap/refs/heads/main/spangap
chmod +x ~/bin/spangap

Everything else (the build container, the Python tools for flashing, the source checkouts) is fetched the first time you run spangap init and spangap build. The launcher keeps itself up to date afterwards.

If your shell can’t find spangap right after installing, open a new terminal window.

Create a workspace and watch the device

Say you are in your home directory on a Mac, you want the workspace directory to be called tdeck, and your LilyGo T-Deck Plus is on /dev/cu.usbmodem1101.

spangap init tdeck && \
cd tdeck && \
spangap monitor /dev/cu.usbmodem1101

Leave it running: it shows the device log, and later you can type commands into it.

Build and flash

Now open another terminal window and do:

cd tdeck && \
spangap build reticulous/reticulous --with spangap/hw-lilygo-tdeck && \
spangap flash

This downloads the sources, builds, and hands the image to the monitor window, which flashes it. The device then reboots with a phone-style UI on the LCD and a WiFi access point named reticulous_…. Connect to that and open https://reticulous.local.

Put it on your WiFi

In the monitor window, type net add <ssid> <password> (quote the password if it has spaces).

You can, and should, set a password for the web interface using your browser at https://reticulous.local, or by typing passwd in the serial monitor. Setting a password also allows you to log in to the device command line interface with ssh admin@reticulous.local.

Other hardware

To do the same — minus the LCD UI — on a Heltec V4 LoRa board, replace --with spangap/hw-lilygo-tdeck with --with spangap/hw-heltecv4. The other board straddles are listed on the Reticulous site.

On any other ESP32-S3 with PSRAM, replace --with ... with --flash-size <n>, <n> being the megabytes of flash the board has. That build has no LoRa, but does Reticulum over WiFi. Use spangap probe [<serial port>] to find out whether your ESP32 has PSRAM and how much flash it has.

To build the bare platform instead of Reticulous, use spangap/spangap-demo in place of reticulous/reticulous. To write a straddle of your own, start from the build system’s README, which says what a straddle is made of and how the build puts them together.