feat(shell): add interactive shell and console testing framework

.github/copilot-instructions.md

@@ -33,7 +33,7 @@ firmware/                  # Single unified PlatformIO project
 │   ├── receiver/          # Static HTML/CSS/JS for receiver web UI
 │   └── transmitter/       # Static HTML/CSS/JS for transmitter web UI
 ├── include/               # lv_conf.h, User_Setup.h (TFT_eSPI pin config)
-├── sim/                   # Simulation shim headers + sources for sim_rx / sim_tx
+├── sim/                   # Simulation shim headers + sources for sim_rx / sim_tx / sim_tx_gui
 │   ├── include/           #   Arduino.h, Wire.h, esp_now.h, Preferences.h, etc.
 │   ├── src/               #   sim_arduino.cpp, sim_espnow.cpp, sim_freertos.cpp, etc.
 │   └── sim_build.py       #   PlatformIO extra_script
@@ -51,7 +51,8 @@ hardware/                  # Hardware design docs (transmitter, receiver, module
 | `transmitter`  | `espressif32`  | ESP32 transmitter firmware       | `ODH_TRANSMITTER`                  |
 | `native`       | `native`       | Host unit tests (Unity)          | `NATIVE_TEST`                      |
 | `sim_rx`       | `native`       | Receiver simulation (terminal)   | `NATIVE_SIM`, `ODH_RECEIVER`, `SIM_RX`  |
-| `sim_tx`       | `native`       | Transmitter simulation (SDL2)    | `NATIVE_SIM`, `ODH_TRANSMITTER`, `SIM_TX` |
+| `sim_tx`       | `native`       | Transmitter simulation (headless terminal) | `NATIVE_SIM`, `ODH_TRANSMITTER`, `SIM_TX`, `ODH_HEADLESS` |
+| `sim_tx_gui`   | `native`       | Transmitter simulation (SDL2)    | `NATIVE_SIM`, `ODH_TRANSMITTER`, `SIM_TX` |
 
 ### Build Commands
 
@@ -61,7 +62,8 @@ pio run -e receiver              # Build receiver
 pio run -e transmitter           # Build transmitter
 pio test -e native               # Run 90 unit tests
 pio run -e sim_rx -t exec        # Run receiver simulation
-pio run -e sim_tx -t exec        # Run transmitter simulation (SDL2 window)
+pio run -e sim_tx -t exec        # Run transmitter simulation (headless terminal)
+pio run -e sim_tx_gui -t exec    # Run transmitter simulation (SDL2 window)
 ```
 
 Always run builds from the `firmware/` directory – `platformio.ini` is there.
@@ -177,7 +179,7 @@ copyright block.
 - FreeRTOS → pthreads
 - I²C (Wire) → in-memory stubs
 - Preferences → in-memory key-value store
-- LCD+LVGL → SDL2 (sim_tx only)
+- LCD+LVGL → SDL2 (sim_tx_gui only)
 - `sim_build.py` adds shim includes and sources automatically
 
 ### Configuration (`odh-config`)
@@ -197,7 +199,8 @@ The CI workflow (`.github/workflows/ci.yml`) runs on push/PR to main/master:
 | `build-transmitter`| `pio run -e transmitter`                    |
 | `build-receiver`   | `pio run -e receiver`                       |
 | `build-sim-rx`     | `pio run -e sim_rx`                         |
-| `build-sim-tx`     | `pio run -e sim_tx` (needs `libsdl2-dev`)   |
+| `build-sim-tx`     | `pio run -e sim_tx`                         |
+| `build-sim-tx-gui` | `pio run -e sim_tx_gui` (needs `libsdl2-dev`)|
 | `clang-format`     | Formatting check (clang-format-19)          |
 | `cppcheck`         | Static analysis                             |
 | `license-headers`  | Copyright header check (SPDX identifier)    |

.github/workflows/ci.yml

@@ -123,11 +123,39 @@ jobs:
         working-directory: firmware
         run: pio run -e sim_rx
 
-  # ── Transmitter simulation build ───────────────────────────────────────
+  # ── Transmitter simulation build (headless) ───────────────────────────
   build-sim-tx:
     name: Build transmitter simulation
     runs-on: ubuntu-latest
 
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install PlatformIO
+        run: pip install platformio
+
+      - name: Cache PlatformIO packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.platformio
+          key: ${{ runner.os }}-pio-sim-${{ hashFiles('firmware/platformio.ini') }}
+          restore-keys: |
+            ${{ runner.os }}-pio-sim-
+
+      - name: Build transmitter simulation
+        working-directory: firmware
+        run: pio run -e sim_tx
+
+  # ── Transmitter simulation build (SDL2 GUI) ─────────────────────────
+  build-sim-tx-gui:
+    name: Build transmitter simulation (GUI)
+    runs-on: ubuntu-latest
+
     steps:
       - uses: actions/checkout@v4
 
@@ -150,9 +178,45 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pio-sim-
 
-      - name: Build transmitter simulation
+      - name: Build transmitter simulation (GUI)
         working-directory: firmware
-        run: pio run -e sim_tx
+        run: pio run -e sim_tx_gui
+
+  # ── Console integration tests (simulation) ──────────────────────────────
+  console-tests:
+    name: Console tests (${{ matrix.target }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [sim_rx, sim_tx]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install PlatformIO
+        run: pip install platformio
+
+      - name: Install test dependencies
+        run: pip install -r firmware/test/test_console/requirements.txt
+
+      - name: Cache PlatformIO packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.platformio
+          key: ${{ runner.os }}-pio-sim-${{ hashFiles('firmware/platformio.ini') }}
+          restore-keys: |
+            ${{ runner.os }}-pio-sim-
+
+      - name: Run console tests (${{ matrix.target }})
+        working-directory: firmware/test/test_console
+        run: pytest --target=${{ matrix.target }} -v
 
   # ── clang-format style check ───────────────────────────────────────────
   clang-format:

README.md

@@ -92,7 +92,7 @@ cd firmware
 # Terminal 1 – receiver
 pio run -e sim_rx -t exec
 
-# Terminal 2 – transmitter (opens SDL2 window)
+# Terminal 2 – transmitter (headless terminal simulation)
 pio run -e sim_tx -t exec
 ```
 

docs/architecture.md

@@ -54,7 +54,7 @@ firmware is built from a single PlatformIO project located in `firmware/`.
 
 ```
 firmware/
-├── platformio.ini         # Unified build: receiver, transmitter, native, sim_rx, sim_tx
+├── platformio.ini         # Unified build: receiver, transmitter, native, sim_rx, sim_tx, sim_tx_gui
 ├── lib/                   # Shared libraries (used by both targets)
 │   ├── odh-protocol/      #   Protocol.h, FunctionMap.h
 │   ├── odh-config/        #   Config.h, NvsStore.h (compile-time + NVS)
@@ -79,7 +79,7 @@ firmware/
 │   ├── receiver/          # Static web UI (HTML/CSS/JS) for receiver
 │   └── transmitter/       # Static web UI for transmitter
 ├── include/               # Board-level overrides (lv_conf.h, User_Setup.h)
-├── sim/                   # Simulation shim headers for sim_rx / sim_tx
+├── sim/                   # Simulation shim headers for sim_rx / sim_tx / sim_tx_gui
 └── test/
     └── test_native/       # Unity tests (90 cases)
 ```
@@ -216,23 +216,24 @@ bus that connects input modules to the transmitter.
 
 ## Simulation
 
-Two simulation environments (`sim_rx`, `sim_tx`) build the full firmware as
-a Linux executable.  Hardware peripherals are replaced by software shims:
+Three simulation environments (`sim_rx`, `sim_tx`, `sim_tx_gui`) build the full
+firmware as a Linux executable.  Hardware peripherals are replaced by software shims:
 
 | Hardware | Simulation Shim |
 |----------|----------------|
 | ESP-NOW | UDP multicast on 127.0.0.1 |
 | FreeRTOS | pthreads / BSD timers |
 | I²C (Wire) | In-memory virtual bus |
 | Preferences (NVS) | In-memory key-value store |
-| ILI9341 LCD + LVGL | SDL2 window (sim_tx only) |
+| ILI9341 LCD + LVGL | SDL2 window (sim_tx_gui only) |
 | PCA9685 / ADS1115 | Console logging |
 | WiFi / WebServer | Localhost HTTP |
 
 ```bash
 cd firmware
-pio run -e sim_rx -t exec   # receiver simulation
-pio run -e sim_tx -t exec   # transmitter simulation (opens SDL2 window)
+pio run -e sim_rx -t exec       # receiver simulation
+pio run -e sim_tx -t exec       # transmitter simulation (headless terminal)
+pio run -e sim_tx_gui -t exec   # transmitter simulation (SDL2 window)
 ```
 
 See `firmware/sim/README.md` for keyboard shortcuts and known limitations.
@@ -241,7 +242,7 @@ See `firmware/sim/README.md` for keyboard shortcuts and known limitations.
 
 ## Build Environments
 
-The unified `firmwave/platformio.ini` defines five environments:
+The unified `firmware/platformio.ini` defines six environments:
 
 | Environment | Target | Board | Framework |
 |-------------|--------|-------|-----------|
@@ -250,16 +251,18 @@ The unified `firmwave/platformio.ini` defines five environments:
 | `native` | Host | native | — |
 | `sim_rx` | Host (Linux) | native | — |
 | `sim_tx` | Host (Linux) | native | — |
+| `sim_tx_gui` | Host (Linux) | native | — |
 
 Build commands:
 
 ```bash
 cd firmware
-pio run -e receiver          # build receiver
-pio run -e transmitter       # build transmitter
-pio test -e native           # run 90 unit tests
-pio run -e sim_rx -t exec    # run receiver sim
-pio run -e sim_tx -t exec    # run transmitter sim
+pio run -e receiver              # build receiver
+pio run -e transmitter           # build transmitter
+pio test -e native               # run 90 unit tests
+pio run -e sim_rx -t exec        # run receiver sim
+pio run -e sim_tx -t exec        # run transmitter sim (headless)
+pio run -e sim_tx_gui -t exec    # run transmitter sim (SDL2 window)
 ```
 
 ---

docs/getting-started.md

@@ -165,13 +165,17 @@ cd firmware
 # Terminal 1 – receiver
 pio run -e sim_rx -t exec
 
-# Terminal 2 – transmitter (opens SDL2 window)
+# Terminal 2 – transmitter (headless terminal simulation)
 pio run -e sim_tx -t exec
+
+# Optional: transmitter with SDL2 GUI (requires libsdl2-dev)
+pio run -e sim_tx_gui -t exec
 ```
 
-The receiver starts announcing immediately.  The transmitter opens an SDL2
-window showing the scan screen.  After a few seconds the vehicle appears as a
-button – click it to connect.
+The receiver starts announcing immediately.  The headless transmitter simulation
+runs in the terminal.  For a graphical display, use `sim_tx_gui` which opens an
+SDL2 window showing the scan screen.  After a few seconds the vehicle appears as
+a button – click it to connect.
 
 The web config UI is also available in simulation:
 - Transmitter: `http://localhost:8080`

docs/index.md

@@ -136,7 +136,7 @@ cd firmware
 # Terminal 1 – receiver
 pio run -e sim_rx -t exec
 
-# Terminal 2 – transmitter (opens SDL2 window)
+# Terminal 2 – transmitter (headless terminal simulation)
 pio run -e sim_tx -t exec
 ```
 

firmware/lib/odh-config/Config.h

@@ -65,6 +65,16 @@ inline constexpr float kBatteryDividerRatio = 4.03f;
 inline constexpr uint16_t kAdcVrefMv        = 3300;
 inline constexpr uint8_t kAdcResolutionBits = 12;
 
+// ── Shell console ───────────────────────────────────────────────────────
+
+/// Shell poll interval (ms) – how often the shell task checks for input.
+inline constexpr uint32_t kShellPollIntervalMs = 50;
+
+/// FreeRTOS task config for the shell task.
+inline constexpr uint32_t kShellTaskStackWords = 4096;
+inline constexpr uint8_t kShellTaskPriority    = 1;
+inline constexpr uint8_t kShellTaskCore        = 0;
+
 // ── Receiver-specific settings ──────────────────────────────────────────
 
 namespace rx {