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. AP mode — WiFi setup credentials
4. WiFi connecting — connection status
5. Setup required — web UI address
6. API error — error message
7. No departures — info message
8. Normal operation — real departures

Memory Allocation

Typical: ~200KB free heap, 21.4% RAM used (70KB of 327KB), 94.7% flash used (1.24MB of 1.31MB)

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,
  GitHubOTA, WeatherAPI

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 (12 departures per stop)
2. Apply 1-second delay between API calls (rate limiting)
3. Collect in temp buffer (capacity: 144)
4. Sort by ETA across all stops
5. Cache top 12 soonest departures
6. Display configured rows on LED matrix

This ensures you always see the soonest departures across all stops.

Performance

Debugging

When config.debugMode = true:

• Telnet server on port 23 — mirrors all debug logs over WiFi
• 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.