Skip to content

adding-a-board.md

Latest commit

 

History

History
111 lines (89 loc) · 5.13 KB

adding-a-board.md

File metadata and controls

111 lines (89 loc) · 5.13 KB
Raw

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).