clawdmeter/docs/porting/adding-a-board.md

Porting Clawdmeter to a new board

A board port is a folder under firmware/src/boards/ plus a new [env:...] block in firmware/platformio.ini. You should never need to edit firmware/src/main.cpp, firmware/src/ui.cpp, or anything under firmware/src/hal/. If you find yourself wanting to, that's a gap in the HAL — open an issue.

Hardware you need

At minimum:

• An ESP32-S3 (other ESP32 family members may work; this is what the upstream firmware is tested on). OPI PSRAM is required — partial flush buffers and the splash canvas are allocated from PSRAM.
• A QSPI AMOLED panel with a driver supported by GFX Library for Arduino (CO5300, SH8601, NV3041A, etc.). Other interfaces aren't supported yet.
• A touch controller over I2C. The HAL just needs init + read; you can use any driver you can compile.
• A primary button (typically the BOOT/GPIO 0 push button).

Optional:

• A second physical button (e.g. for HID Shift+Tab mode toggle).
• An AXP2101 PMU for battery monitoring + a power button.
• A QMI8658 (or compatible) IMU for automatic rotation.
• An XCA9554 / PCA9554 IO expander if reset / enable lines are routed through one (the AMOLED-1.8 board does this).

Step-by-step

1. Copy the template folder.

   cp -r firmware/src/boards/template firmware/src/boards/my_board
   

2. Fill in boards/my_board/board.h. Replace every TODO with your board's pins, I2C addresses, dimensions, and capability flags. The capability flags drive both compile-time dead-stripping in the HAL implementations and runtime UI decisions via BoardCaps.

3. Implement the per-board sources. Each one corresponds to a HAL header in firmware/src/hal/. Look at one of the reference ports for a worked example:

   File	Reference port (start here)
   display.cpp	boards/waveshare_amoled_216/display.cpp (with CPU rotation) or _18/display.cpp (no rotation)
   touch.cpp	_216/touch.cpp (library-based) or _18/touch.cpp (vendored I2C reader)
   input.cpp	_216/input.cpp (two buttons) or _18/input.cpp (one button)
   power.cpp	_216/power.cpp (PMU IRQ) or _18/power.cpp (PMU + IO expander button)
   imu.cpp	_216/imu.cpp (full rotation) or _18/imu.cpp (init-only stub)
   caps.cpp	either reference — just edit the struct literal
   board_init.cpp	_216/board_init.cpp (no expander) or _18/board_init.cpp (with expander)

4. Add a PlatformIO env. In firmware/platformio.ini, copy one of the existing [env:waveshare_amoled_*] blocks and adjust:

   [env:my_board]
   ; ... platform / board / framework as before ...
   
   build_src_filter =
       +<*>
       -<boards/>
       +<boards/my_board/>          ; the only line you change here
   
   build_flags =
       -DBOARD_MY_BOARD             ; identity-only — the shared code never
                                     ; branches on this; per-board code may
   

   If your panel needs flash > 4 MB (extra animations, larger fonts), copy the board_upload.* block from the AMOLED-1.8 env.

5. Build. pio run -d firmware -e my_board. The link step is the real verification — any missing HAL symbol or duplicated definition shows up here.

6. Flash + smoke test. The first boot should land on the splash screen. If it doesn't, check pio device monitor for HAL init messages — every reference port logs OK / failure for display, touch, PMU, IMU during setup().

7. Visual QA. ./screenshot.sh out.png over USB serial captures the live framebuffer at the active resolution. The UI is responsive (see hal-contract.md for breakpoint details); most ports will look acceptable out of the box. If your screen size doesn't match an existing breakpoint, you may want to add one to compute_layout() in firmware/src/ui.cpp.

Common pitfalls

• Display stays black, no panic. Usually one of: OPI PSRAM not enabled in platformio.ini (check board_build.arduino.memory_type = qio_opi); IO expander not released before gfx->begin() (run io_expander_init() from board_init()); GFX library version too old to know about your panel chip.
• Touch reads zeros / wrong coordinates. The HAL hands LVGL whatever the controller reports — apply any axis swap / mirror inside your touch.cpp. CST9220 needs setSwapXY(true) + setMirrorXY(true, false) on the AMOLED-2.16 board; your controller will likely differ.
• GPL warning when picking a touch driver. The project intentionally avoids copyleft dependencies. If the only available library is GPL, vendor a minimal I2C reader instead (see _18/touch.cpp).
• Both boards built fine but one runs and the other doesn't. The build_src_filter is per-env — re-check you copied the existing env blocks correctly and the -<boards/> then +<boards/your_one/> ordering is right (filters apply in declaration order).