Architecture & Data Flow

Technical documentation for developers and contributors.

Dual-Core Architecture

SpojBoard uses both cores of the ESP32-S3 with FreeRTOS tasks for optimal performance:

┌─────────────────────────────────────────────────────────┐
│ CORE 0 (WiFi Network Stack)                             │
├─────────────────────────────────────────────────────────┤
│ WiFi interrupt handlers (sub-ms response)               │
│ LwIP TCP/IP stack                                       │
│ NO application tasks                                    │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ CORE 1 (Application Tasks)                              │
├─────────────────────────────────────────────────────────┤
│ displayRenderTask()  [Priority 2]                       │
│   Waits for notification, copies data via mutex,        │
│   renders to HUB75 (~100ms)                             │
│                                                         │
│ apiFetchTask()       [Priority 1]                       │
│   Handles blocking HTTP calls (200-2000ms)              │
│   Updates departures via mutex, sleeps 100ms            │
│                                                         │
│ Arduino loop()       [Priority 1]                       │
│   Web server, ETA recalculation, state management       │
└─────────────────────────────────────────────────────────┘

Thread Safety

Two mutexes protect shared data with short lock durations (~1ms):

• displayMutex — Protects display update requests (display task ↔ loop)
• apiDataMutex — Protects departures array and weather data (API task ↔ loop)

Data is copied under mutex, then processed without locks. Rendering and HTTP calls never hold a mutex.

Configuration Constants

Complete Data Pipeline

State Machine

The device operates in multiple modes with priority-based evaluation:

Operating Modes

Display Priority (highest to lowest)

1. Demo mode — custom sample departures
2. Rest mode — display off
3. Ticker mode — candlestick price chart (easter egg)
4. AP mode — WiFi setup credentials
5. WiFi connecting — connection status
6. Setup required — web UI address
7. API error — error message
8. No departures — info message
9. Normal operation — real departures

Memory Allocation

The firmware favors static allocation in the main loop for stability. Departures are collected into a temporary buffer, sorted, and cached for display, while per-API JSON buffers live on the heap only for the duration of a fetch.

Typical: ~200KB free heap. Firmware fits within the 2MB app partition (dual OTA partitions of 2MB each).

For the exact per-structure budget and current buffer sizes, see the architecture reference on GitHub.

Module Architecture

Layered design with zero circular dependencies:

Layer 6: Application
  main.cpp (orchestrates all modules, runtime API selection)

Layer 5: Business Logic
  TransitAPI (abstract), GolemioAPI, BvgAPI, MqttAPI,
  WeatherAPI, TickerAPI, GitHubOTA

Layer 4: Network Services
  WiFiManager, CaptivePortal, ConfigWebServer, OTAUpdateManager

Layer 3: Hardware Abstraction
  DisplayController, DisplayManager, DisplayColors,
  TimeUtils, RestMode

Layer 2: Data Layer
  AppConfig, DepartureData

Layer 1: Foundation
  Logger, UTF-8 utilities (gfxlatin2, decodeutf8)

Key Patterns

• Zero Circular Dependencies: Lower layers never depend on higher layers
• Callback Pattern: Modules communicate upward via callbacks
• Pure Data Structures: Config passed as parameter, not stored in modules
• Static Allocation: No dynamic allocation in main loop for stability

Multi-Stop Behavior

When multiple stop IDs are configured (comma-separated, max 12 stops):

1. Query each stop individually (Golemio 12, BVG 10 departures per stop)
2. Apply 1-second delay between API calls (rate limiting)
3. Merge into a running accumulator — a failed stop keeps its last-known rows
4. Sort by ETA across all stops
5. Publish top 24 soonest departures (partial board shown during initial fill)
6. Display configured rows on LED matrix

This ensures you always see the soonest departures across all stops, while a transient failure of one stop never blanks it.

Performance

Debugging

When config.debugMode = true:

• Detailed logging on the serial console — everything goes to serial and nowhere else. The telnet mirror on port 23 existed until r9 and was removed with its dependency
• Memory logging at key checkpoints (api_start, api_complete, display_update)
• API response logging with timestamps

Serial output always available at 115200 baud for boot sequence, WiFi status, and errors.