Getting started

Spangap works for Linux, Mac and probably also Windows (untested as of now). All the host needs is Docker, git and Python 3 — everything else lives inside the build container and the workspace directory you create.

The quickest way to see what the platform does is to build something real on it, so this walks through building Reticulous, the Reticulum mesh firmware that was co-developed with Spangap.

Install the launcher

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

That fetches the single spangap launcher, checks the host prerequisites and drops it somewhere 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.

The launcher is just one file, so the manual install is equally supported:

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

Everything else Spangap needs — the build container, the flash/monitor venv, the straddle checkouts — is pulled in on demand by spangap init and spangap build. A workspace keeps the launcher current on its own, so installing it is a one-time convenience rather than a moving part.

If your shell doesn’t seem to know about spangap right after installing, enter rehash and/or try again from 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 spangap monitor running. It shows you the device log output, and once we’re done it will let you switch to CLI mode by typing a command.

Build and flash

Now open another terminal window and do:

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

After downloading and building, it tells the monitor window to flash the firmware. When that’s done the device resets, comes alive and presents a smartphone-like UI on the LCD as well as a full-featured web interface on a built-in access point whose SSID starts with reticulous_.

Meet it on your own network

If you’d rather have the device join your own WiFi, go to the serial window and type net add <ssid> <password> — use quotes if your password 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 in the overview.

To try Reticulous using only TCP connections to other nodes on any ESP32-S3 that has PSRAM, replace --with ... with --flash-size <n>, where <n> is the number of megabytes of flash your ESP32-S3 comes with. Use spangap probe [<serial port>] to find out whether your ESP32 has PSRAM and how much flash it has.