Project overview

Spangap is made of straddles: modules that each hold a firmware component, a browser app where there is one, and some metadata. The build stitches the ones you pick into one firmware image and one web app. This page says which straddle owns what.

The build system

spangap — the build tool: a single-file launcher that sets up the Docker container, works out which straddles a build needs, generates the boot code, builds, flashes and monitors.

The base runtime

spangap-core — the runtime every device gets. Its parts:

  • init — boots the straddles in the right order; there is no hand-written app_main.
  • storage — the settings store, kept in sync between device and browser: set net.wifi.enable=1 in the CLI moves the toggle in the web UI and on the LCD.
  • its — Inter-Task Streaming: how tasks send each other streams and messages without polling. Everything else is built on it.
  • fs — the filesystem on flash and SD card, run as a service so other tasks can keep their stacks in PSRAM.
  • cli — the unix-like command line, reachable over serial, web and SSH.
  • auth — passwords and sessions, shared by the command line, the web interface and SSH.
  • cron — the scheduled/periodic job runner.
  • logging — the device log.
  • power-management — lets the chip sleep while every task is blocked.
  • memory — the central allocator and heap tooling.
  • ota — signed firmware updates.

Networking and the browser

spangap-net — WiFi and IP: net (WiFi client and access point, wget), tls (certificates), ntp (time) and mdns (<host>.local). It also pulls in the remote-access services below.

spangap-web — the web server (HTTPS, files, WebDAV, login), the WebRTC channel the browser talks to the device over, and the browser shell: the dock, the generated settings panels, login and setup. At build time every other straddle’s browser app is folded into it.

spangap-lcd — the phone-style UI on the screen (LVGL): status bar, launcher, recent apps, and built-in Settings, Log and CLI apps with a terminal. Straddles register their own apps and settings panes; the board straddle supplies the input devices.

Board support

hw-* — one straddle per board: power-up, pins, input devices, battery monitor, SD card. A board straddle makes the hardware usable and says nothing about what the device does; you build an application with it. The supported boards are listed on the Reticulous site.

Peripheral straddles

Each drives one part and talks to the rest only through the settings store. A board straddle lists the ones it has and their pins.

  • gps — a GNSS receiver (u-blox M10 or Quectel L76K): position, receiver power saving, and setting the clock.
  • rtc — a PCF8563 battery-backed clock: read at boot, kept up to date from GPS or NTP, and the source of time when neither is available.
  • imu — a QMI8658 accelerometer, used to tell whether the device is moving, so gps can stop tracking when it is not.

Remote-access services

Pulled in by spangap-net; each can be left out.

  • acme — fetches and renews a real TLS certificate from Let’s Encrypt.
  • duckdns — keeps a DuckDNS hostname pointing at the device.
  • upnp — opens the ports on your router so the device is reachable from outside.
  • wg — a WireGuard tunnel, for when your provider’s NAT makes the three above useless.
  • sshd — an SSH server (and client) into the command line and the log.

Other platform straddles

viewer — shows HTML and Markdown documents (help, READMEs) on the LCD and in the browser.

audio — I2S audio in and out: live microphone to the browser, mixing, WAV playback.

tinylcd — for small monochrome OLEDs: pages of status, one per straddle, stepped through with a button.

And the mesh stack

The mesh-networking straddles — the Reticulum stack (rns), the LoRa, TCP, ESP-NOW and Auto interfaces, LXMF messaging, Nomad browsing and more — live in the sibling Reticulous project, the reference application built on this platform.