fastled Board Support Lookup & Diagnosis
You are diagnosing a board definition issue in fbuild. fbuild maintains its own board database (1609+ boards as JSON files) derived primarily from PlatformIO, but boards also exist in Arduino, Zephyr, and other ecosystems that we may need to ingest.
fbuild Board Database
- Board JSONs:
crates/fbuild-config/assets/boards/json/{board_id}.json - Manifest:
crates/fbuild-config/assets/boards/manifest.json - Board config code:
crates/fbuild-config/src/board.rs - Enrichment tool:
crates/fbuild-config/src/bin/enrich_boards.rs - Validation tool:
ci/validate_boards.py - External source comparison:
ci/board_sources.py
Step 1: Check if the board exists in fbuild
ls crates/fbuild-config/assets/boards/json/{BOARD_ID}.json
If it exists, read it and check for missing/wrong fields (build.core, build.variant, build.mcu, build.extra_flags, upload.protocol, upload.speed, etc.)
Step 2: Check PlatformIO source (local)
ls ~/.platformio/platforms/*/boards/{BOARD_ID}.json
Compare against our copy. Run validation:
uv run python ci/validate_boards.py --platforms {PLATFORM}
Step 3: Search external board registries
Use ci/board_sources.py to fetch and search external board lists:
# List all boards from Arduino package indices
uv run python ci/board_sources.py --list-arduino
# List all boards from Zephyr
uv run python ci/board_sources.py --list-zephyr
# Search for a specific board across all sources
uv run python ci/board_sources.py --search {BOARD_NAME}
# Full comparison: find boards in external sources missing from fbuild
uv run python ci/board_sources.py --compare
Step 4: External source URLs (for manual lookup)
Arduino Package Index Files
These are JSON files listing board support packages. Fetch and inspect them:
| Source | URL |
|---|---|
| Arduino Official | https://downloads.arduino.cc/packages/package_index.json |
| ESP32 (Espressif) | https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json |
| ESP8266 | https://arduino.esp8266.com/stable/package_esp8266com_index.json |
| Adafruit | https://adafruit.github.io/arduino-board-index/package_adafruit_index.json |
| SparkFun | https://raw.githubusercontent.com/sparkfun/Arduino_Boards/main/IDE_Board_Manager/package_sparkfun_index.json |
| Teensy | https://www.pjrc.com/teensy/package_teensy_index.json |
CH32V (WCH RISC-V) Platform
The CH32V family (CH32V003, V103, V203, V208, V303, V307, CH32X035) uses the community PlatformIO platform:
| Resource | URL |
|---|---|
| PlatformIO platform | https://github.com/Community-PIO-CH32V/platform-ch32v |
| Board definitions | https://github.com/Community-PIO-CH32V/platform-ch32v/tree/develop/boards |
| WCH Arduino core | https://github.com/openwch/arduino_core_ch32 |
| WCH product pages | http://www.wch-ic.com/products/CH32V003.html (replace series in URL) |
All CH32V boards use platform = ch32v in platformio.ini. Arduino framework is available for V003, V203, and V307 series. Other series use noneos-sdk or ch32v003fun frameworks.
Arduino package index JSON structure:
packages[].platforms[].boards[].name — board display name
packages[].platforms[].architecture — e.g. "esp32", "avr", "samd"
packages[].name — vendor/packager name
Zephyr Board Definitions
Zephyr boards are defined as YAML + Devicetree in the Zephyr repo:
| Resource | URL |
|---|---|
| Board index | https://raw.githubusercontent.com/zephyrproject-rtos/zephyr/main/boards/index.rst |
| Board directories | https://api.github.com/repos/zephyrproject-rtos/zephyr/contents/boards |
Zephyr board.yml structure:
board:
name: <board_name>
vendor: <vendor>
socs:
- name: <soc_name>
Other Sources (for deep investigation)
| Source | Format | URL / Repo |
|---|---|---|
| PlatformIO Registry API | JSON | https://api.registry.platformio.org/v3/packages |
| CMSIS-Pack Index | XML | https://www.keil.com/pack/index.pidx |
| Mbed OS targets | JSON | https://raw.githubusercontent.com/ARMmbed/mbed-os/master/targets/targets.json |
| probe-rs targets | YAML | https://github.com/probe-rs/probe-rs/tree/master/probe-rs/targets |
| STM32CubeMX DB | XML | https://github.com/STMicroelectronics/STM32_open_pin_data |
| CircuitPython | Mixed | https://github.com/adafruit/circuitpython/tree/main/ports |
Step 5: Fix the board
If the board is missing entirely:
- Find its definition in PlatformIO or Arduino sources
- Create
crates/fbuild-config/assets/boards/json/{board_id}.jsonwith the standard fields - Update
manifest.json(sorted alphabetically) - Run enrichment:
uv run cargo run -p fbuild-config --bin enrich_boards
If the board has wrong fields:
- Compare against PlatformIO source:
uv run python ci/validate_boards.py - Fix the JSON directly or re-run enrichment
- Run tests:
uv run test -p fbuild-config
If the board is in Arduino/Zephyr but not PlatformIO:
- Note this in the issue — it may need manual creation
- Extract fields from the Arduino boards.txt or Zephyr board.yml
- Map to fbuild's JSON schema (see esp32dev.json as a reference)