rl-docs-hub

Home · Apps · rl-bank-mvp

Terminal firmware architecture

Status: Draft, C++/Pico SDK oriented.

Firmware goals

The firmware should stay deliberately small and modular.

Responsibilities:

Non-goals for phase 1:

firmware/
  src/
    main.cpp
    app/
      app_controller.cpp
      app_controller.h
      session_state.h
    drivers/
      display_st7789.cpp
      display_st7789.h
      keypad.cpp
      keypad.h
      nfc_reader.cpp
      nfc_reader.h
      buzzer.cpp
      buzzer.h
    network/
      wifi_manager.cpp
      wifi_manager.h
      http_client.cpp
      http_client.h
      terminal_api.cpp
      terminal_api.h
    domain/
      payment_session.cpp
      payment_session.h
      models.h
    ui/
      screen_renderer.cpp
      screen_renderer.h
      screens.h
    config/
      pins.h
      build_config.h

State machine recommendation

Primary terminal states:

This matters more than fancy graphics. A clean state machine will save the project.

Runtime flow

  1. boot hardware and show splash
  2. connect Wi-Fi
  3. fetch bootstrap config if enabled
  4. wait for amount entry
  5. open payment session with generated requestId
  6. poll NFC until token detected or session cancelled/timed out
  7. call authorization endpoint
  8. render result screen
  9. return to ready state

Networking approach

For first pass:

UI architecture

Keep rendering primitive and deterministic:

Avoid building a generic widget framework too early.

Debugging and observability

During development, support:

Security posture for prototype

Good enough for prototype:

Integration recommendation

Do not create a separate large firmware repo yet unless implementation starts immediately.

If/when coding begins, I would create a dedicated repo only once these are agreed:

Until then, docs-first is the correct move.