ElixirForge/firmware
1
0
Fork 0
mirror of https://github.com/alexhopeoconnor/firmware.git synced 2026-10-22 03:02:08 +10:00
Code Releases Activity

Implement Hardware Support Agent Specification and Workflow

Browse Source
This commit is contained in:
Ben Meadors
2026-03-26 08:55:11 -05:00
parent b9bdc87367
commit ad03f6f6d8
50 changed files with 7625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bin/generate_hardware_support_context.py
+592
View File
@@ -0,0 +1,592 @@
#!/usr/bin/env python3
"""Generate a markdown inventory of board-support metadata and common target-definition macros."""
from __future__ import annotations
import argparse
import re
from collections import Counter, defaultdict
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
VARIANTS_DIR = ROOT / "variants"
OUTPUT_PATH = ROOT / "docs" / "hardware-support-context.md"
PLATFORMIO_METADATA_KEYS = [
"custom_meshtastic_hw_model",
"custom_meshtastic_hw_model_slug",
"custom_meshtastic_architecture",
"custom_meshtastic_actively_supported",
"custom_meshtastic_support_level",
"custom_meshtastic_display_name",
"custom_meshtastic_images",
"custom_meshtastic_tags",
"custom_meshtastic_requires_dfu",
"custom_meshtastic_partition_scheme",
]
MACRO_PATTERNS = {
"Input": [
"BUTTON_PIN",
"BUTTON_PIN_TOUCH",
"ALT_BUTTON_PIN",
"CANCEL_BUTTON_PIN",
"ROTARY_",
"KB_",
"INPUTDRIVER_",
],
"Radio": [
"USE_RF95",
"USE_SX126",
"USE_SX128",
"USE_LLCC68",
"USE_LR11",
"LORA_",
"SX126X_",
"SX128X_",
"LR1121_",
"RF95_",
],
"GPS": [
"HAS_GPS",
"GPS_",
"PIN_GPS_",
"GPS_DEFAULT_NOT_PRESENT",
],
"Display": [
"HAS_SCREEN",
"USE_TFTDISPLAY",
"USE_TFT",
"USE_SSD",
"USE_SH",
"USE_ST",
"TFT_",
"OLED_",
"SCREEN_",
"PIN_EINK_",
"EINK_",
"DISPLAY_",
"LGFX_",
"HAS_TFT",
],
"I2C/SPI": [
"I2C_",
"SPI_",
"PIN_SPI",
"WIRE_",
],
"Power": [
"BATTERY_",
"ADC_",
"PIN_POWER",
"USE_POWERSAVE",
"SLEEP_TIME",
"XPOWERS_",
"HAS_AXP",
"HAS_PPM",
"HAS_BQ",
"EXT_NOTIFY_OUT",
"FAN_CTRL_PIN",
"RF95_FAN_EN",
],
"Connectivity/Other": [
"HAS_WIFI",
"HAS_BLUETOOTH",
"HAS_ETHERNET",
"HAS_NEOPIXEL",
"HAS_I2S",
"HAS_TOUCH",
"HAS_TOUCHSCREEN",
"HAS_NFC",
"NFC_",
"USE_XL9555",
"EXPANDS_",
"PCF",
"RTC",
],
}
def classify_macro(name: str) -> str:
for category, prefixes in MACRO_PATTERNS.items():
for prefix in prefixes:
if name.startswith(prefix):
return category
return "Other"
def parse_platformio_envs(path: Path) -> list[dict[str, object]]:
envs: list[dict[str, object]] = []
current: dict[str, object] | None = None
for raw_line in path.read_text(encoding="utf-8").splitlines():
line = raw_line.strip()
if not line or line.startswith(";"):
continue
if line.startswith("[") and line.endswith("]"):
if current:
envs.append(current)
current = {"section": line[1:-1], "metadata": {}}
continue
if current is None or "=" not in line:
continue
key, value = [part.strip() for part in line.split("=", 1)]
if key in PLATFORMIO_METADATA_KEYS:
current["metadata"][key] = value
if current:
envs.append(current)
return envs
def parse_variant_macros(path: Path) -> tuple[dict[str, str], Counter[str]]:
defines: dict[str, str] = {}
category_counts: Counter[str] = Counter()
pattern = re.compile(r"^#define\s+([A-Za-z0-9_]+)(?:\s+(.*?))?\s*(?://.*)?$")
for raw_line in path.read_text(encoding="utf-8").splitlines():
match = pattern.match(raw_line.strip())
if not match:
continue
name = match.group(1)
value = (match.group(2) or "1").strip()
defines[name] = value
category_counts[classify_macro(name)] += 1
return defines, category_counts
MACRO_DESCRIPTIONS: dict[str, str] = {
# ---------- Input ----------
"BUTTON_PIN": "Primary user button GPIO pin number.",
"ALT_BUTTON_PIN": "Secondary / alternate button pin, used on boards with two buttons.",
"CANCEL_BUTTON_PIN": "Button wired to cancel/back actions (e.g., T-Deck cancel key).",
"BUTTON_NEED_PULLUP": "Set to 1 when the button GPIO requires the internal pull-up to be enabled.",
"BUTTON_PIN_ALT": "Alternative spelling used by some older board families for a second button.",
"KB_BL_PIN": "Keyboard backlight control pin (e.g., T-LoRa Pager keyboard).",
"KB_INT": "Keyboard interrupt input pin; signals a keypress to the MCU.",
"KB_POWERON": "Pin used to power-on or enable the keyboard peripheral.",
"KB_SLAVE_ADDRESS": "I2C address of the keyboard controller IC.",
"INPUTDRIVER_ENCODER_TYPE": "Selects the rotary encoder driver variant (0 = none, 1+ = specific type).",
"INPUTDRIVER_TWO_WAY_ROCKER": "Enables the two-way rocker input driver.",
"INPUTDRIVER_TWO_WAY_ROCKER_RIGHT": "GPIO pin for the rightward rocker direction.",
"INPUTDRIVER_TWO_WAY_ROCKER_LEFT": "GPIO pin for the leftward rocker direction.",
"INPUTDRIVER_TWO_WAY_ROCKER_BTN": "GPIO pin for the rocker click/press direction.",
"ROTARY_A": "First encoder channel pin (clock / A signal).",
"ROTARY_B": "Second encoder channel pin (data / B signal).",
# ---------- Radio ----------
"USE_SX1262": "Select the SX1262 sub-GHz LoRa chip driver.",
"USE_SX1268": "Select the SX1268 sub-GHz LoRa chip driver (higher power variant of SX1262).",
"USE_SX1280": "Select the SX1280 2.4 GHz LoRa chip driver.",
"USE_RF95": "Select the RFM95/SX1276 legacy LoRa chip driver.",
"USE_LLCC68": "Select the LLCC68 low-cost LoRa chip driver.",
"USE_LR1110": "Select the LR1110 wideband radio driver.",
"USE_LR1120": "Select the LR1120 wideband radio driver.",
"USE_LR1121": "Select the LR1121 wideband radio driver.",
"LORA_CS": "LoRa radio SPI chip-select GPIO pin.",
"LORA_RESET": "LoRa radio hardware-reset GPIO pin (active low).",
"LORA_DIO0": "LoRa radio DIO0 interrupt pin (RF95/SX1276 done/RxDone).",
"LORA_DIO1": "LoRa radio DIO1 interrupt pin; on SX126x this is the primary IRQ line.",
"LORA_DIO2": "LoRa radio DIO2 pin; on RF95 used for FSK interrupt; on SX126x tx/rx control.",
"LORA_SCK": "LoRa radio SPI clock pin.",
"LORA_MISO": "LoRa radio SPI MISO pin.",
"LORA_MOSI": "LoRa radio SPI MOSI pin.",
"SX126X_CS": "SX126x chip-select pin (often same as LORA_CS).",
"SX126X_RESET": "SX126x reset pin (often same as LORA_RESET).",
"SX126X_BUSY": "SX126x BUSY pin; must be polled low before issuing SPI commands.",
"SX126X_DIO1": "SX126x DIO1 interrupt output used for all IRQ events.",
"SX126X_DIO3_TCXO_VOLTAGE": "Drives the TCXO regulator via DIO3; set to the supply voltage (e.g., 1.8).",
"SX126X_DIO2_AS_RF_SWITCH": "Set to 1 so the driver controls the TX/RX RF switch via DIO2.",
"LR1121_IRQ_PIN": "LR1121 interrupt request pin.",
"RF95_FAN_EN": "Enables a cooling fan for high-power RF95 installations.",
# ---------- GPS ----------
"HAS_GPS": "Set to 1 if the board has an on-board GPS receiver; 0 to disable GPS entirely.",
"GPS_RX_PIN": "UART RX pin connected to the GPS module TX output.",
"GPS_TX_PIN": "UART TX pin connected to the GPS module RX input.",
"PIN_GPS_EN": "GPIO to power-enable or power-gate the GPS module.",
"PIN_GPS_PPS": "GPS pulse-per-second input pin for timing synchronisation.",
"PIN_GPS_STANDBY": "Places the GPS into standby/low-power mode when driven.",
"PIN_GPS_RESET": "Hardware-reset line to the GPS module.",
"PIN_GPS_REINIT": "Pin used to trigger GPS re-initialisation sequences.",
"GPS_THREAD_INTERVAL": "Millisecond poll interval for the GPS background thread.",
"GPS_BAUDRATE": "UART baud rate for GPS serial communication.",
"GPS_L76K": "Selects the Quectel L76K GPS driver and protocol.",
"GPS_UBLOX": "Selects the u-blox GPS driver and UBX protocol.",
"GPS_EN_ACTIVE": "Logic level (HIGH or LOW) that enables the GPS power pin.",
"GPS_RESET_MODE": "Defines the reset signal polarity or protocol for the GPS chip.",
"GPS_DEFAULT_NOT_PRESENT": "Compiled-in default assuming no GPS; overridden at runtime if detected.",
# ---------- Display ----------
"HAS_SCREEN": "Set to 1 if the board has any display hardware.",
"USE_TFTDISPLAY": "Selects the TFT LCD driver path.",
"USE_SSD1306": "Selects the SSD1306 128×64 OLED driver over I2C.",
"USE_SH1106": "Selects the SH1106 128×64 OLED driver.",
"USE_ST7735": "Selects the ST7735 TFT SPI driver.",
"USE_ST7789": "Selects the ST7789 TFT SPI driver.",
"TFT_WIDTH": "Horizontal pixel resolution of the TFT display.",
"TFT_HEIGHT": "Vertical pixel resolution of the TFT display.",
"TFT_OFFSET_X": "Horizontal pixel offset for display alignment correction.",
"TFT_OFFSET_Y": "Vertical pixel offset for display alignment correction.",
"TFT_BL": "Backlight control PWM or GPIO pin for the TFT panel.",
"SCREEN_ROTATE": "Non-zero value rotates the display 180° for mounted-upside-down screens.",
"SCREEN_TRANSITION_FRAMERATE": "Target framerate for UI animations and transitions.",
"PIN_EINK_CS": "E-ink display SPI chip-select pin.",
"PIN_EINK_BUSY": "E-ink display BUSY output; high when a page update is in progress.",
"PIN_EINK_DC": "E-ink display data/command select pin.",
"PIN_EINK_RES": "E-ink display hardware-reset pin.",
"PIN_EINK_SCLK": "E-ink display SPI clock pin.",
"PIN_EINK_MOSI": "E-ink display SPI MOSI pin.",
# ---------- I2C/SPI ----------
"I2C_SDA": "Primary I2C data line GPIO pin.",
"I2C_SCL": "Primary I2C clock line GPIO pin.",
"PIN_SPI_MISO": "Primary SPI MISO (data from peripheral) GPIO pin.",
"PIN_SPI_MOSI": "Primary SPI MOSI (data to peripheral) GPIO pin.",
"PIN_SPI_SCK": "Primary SPI clock GPIO pin.",
"SPI_INTERFACES_COUNT": "Number of hardware SPI buses available on this board.",
"WIRE_INTERFACES_COUNT": "Number of hardware I2C buses available on this board.",
"PIN_SPI1_MISO": "Secondary SPI bus MISO pin.",
"PIN_SPI1_MOSI": "Secondary SPI bus MOSI pin.",
"PIN_SPI1_SCK": "Secondary SPI bus clock pin.",
"SPI_FREQUENCY": "Default SPI clock frequency in Hz for this board.",
"SPI_READ_FREQUENCY": "Reduced SPI clock rate used for read transactions.",
"SPI_SCK": "SPI clock pin alias used in older board files.",
"SPI_MOSI": "SPI MOSI pin alias used in older board files.",
"SPI_MISO": "SPI MISO pin alias used in older board files.",
# ---------- Power ----------
"BATTERY_PIN": "ADC input GPIO connected to the battery voltage divider.",
"ADC_MULTIPLIER": "Floating-point scale factor to convert raw ADC reading to battery voltage.",
"ADC_CHANNEL": "ADC channel enum or number for the battery sense input.",
"BATTERY_SENSE_RESOLUTION_BITS": "ADC resolution in bits used for battery voltage sampling.",
"ADC_RESOLUTION": "Board-level ADC resolution definition, referenced by other power macros.",
"BATTERY_SENSE_RESOLUTION": "Alias for the effective ADC resolution for battery sense.",
"ADC_CTRL": "GPIO that enables or gates the ADC voltage-divider circuit.",
"ADC_CTRL_ENABLED": "Logic level (HIGH or LOW) that turns on the ADC control switch.",
"ADC_ATTENUATION": "ESP32 ADC input attenuation setting; controls measurable voltage range.",
"BATTERY_SENSE_SAMPLES": "Number of ADC samples to average for a stable battery reading.",
"EXT_NOTIFY_OUT": "GPIO output used to signal an external LED or buzzer for notifications.",
"USE_POWERSAVE": "Enables aggressive power-save mode (deep sleep, reduced poll intervals).",
"SLEEP_TIME": "Default light-sleep duration in milliseconds between wakeups.",
"PIN_POWER_EN": "GPIO to assert to enable a board power rail or load switch.",
"HAS_PPM": "Set to 1 if the board has an IP5306 or similar PPM power path IC.",
# ---------- Connectivity/Other ----------
"HAS_TOUCHSCREEN": "Set to 1 for boards with a capacitive or resistive touch panel.",
"HAS_NEOPIXEL": "Set to 1 if the board has addressable RGB LEDs (WS2812 / NeoPixel).",
"PCF8563_RTC": "I2C address of the PCF8563 real-time clock IC.",
"PCF85063_RTC": "I2C address of the PCF85063 real-time clock IC.",
"HAS_ETHERNET": "Set to 1 for boards with a wired Ethernet interface.",
"HAS_I2S": "Set to 1 if I2S audio output is present.",
"NFC_INT": "Interrupt pin from the NFC controller IC.",
"NFC_CS": "SPI chip-select for the NFC controller.",
"USE_XL9555": "Enables the XL9555 16-bit I2C GPIO expander driver.",
"EXPANDS_DRV_EN": "GPIO expander pin used to enable the haptic driver.",
"EXPANDS_AMP_EN": "GPIO expander pin used to power-on the audio amplifier.",
"EXPANDS_KB_RST": "GPIO expander pin used to reset the keyboard controller.",
"EXPANDS_LORA_EN": "GPIO expander pin used to power-gate the LoRa radio.",
"EXPANDS_GPS_EN": "GPIO expander pin used to power-gate the GPS module.",
"EXPANDS_NFC_EN": "GPIO expander pin used to power-gate the NFC controller.",
# ---------- Other ----------
"LED_POWER": "GPIO for the status LED, defines the LED pin number.",
"LED_STATE_ON": "Logic level (HIGH or LOW) that turns the status LED on.",
"PIN_SERIAL1_RX": "Secondary UART RX pin (used for accessories, GPS on some boards).",
"PIN_SERIAL1_TX": "Secondary UART TX pin.",
"PIN_WIRE_SDA": "Arduino-framework I2C SDA pin alias (nRF52 / RP2040 style).",
"PIN_WIRE_SCL": "Arduino-framework I2C SCL pin alias.",
"PIN_LED1": "First LED GPIO pin in the nRF52 Arduino BSP pin table.",
"VARIANT_MCK": "Crystal oscillator frequency in Hz for nRF52 variant clock configuration.",
"PINS_COUNT": "Total number of GPIO pins defined in the Arduino BSP variant table.",
"NUM_DIGITAL_PINS": "Count of digital-capable pins in the BSP variant table.",
"NUM_ANALOG_INPUTS": "Count of analog-input pins in the BSP variant table.",
"NUM_ANALOG_OUTPUTS": "Count of analog-output (DAC) pins in the BSP variant table.",
"LED_BLUE": "GPIO number of the blue status LED (typical on nRF52 and RP2040 boards).",
"USE_LFXO": "Instructs the nRF52 BSP to use the low-frequency crystal oscillator.",
"BUTTON_NEED_PULLUP": "Enables internal pull-up on the button GPIO (duplicate entry for clarity).",
}
def shorten(value: str, limit: int = 60) -> str:
compact = " ".join(value.split())
return compact if len(compact) <= limit else compact[: limit - 3] + "..."
# Architecture families known to rely heavily on BSP or base-environment defaults rather
# than declaring every field locally. Used in the Inherited Defaults Note section.
_BSP_DEFAULT_FAMILIES: dict[str, list[str]] = {
"nrf52840": [
"VARIANT_MCK — nRF52 BSP clock constant (e.g., 64000000ul); always inherited from BSP unless overridden.",
"USE_LFXO — low-frequency crystal oscillator selection; declared locally only when the board uses LFXO rather than the RC oscillator.",
"PIN_SPI_* / PIN_SPI1_* — SPI bus pin numbers come from the BSP variant table; boards override only when the LoRa radio or display uses non-default SPI routing.",
"WIRE_INTERFACES_COUNT / SPI_INTERFACES_COUNT — bus count comes from BSP; explicitly set only when the board deviates.",
"LED_BLUE / PIN_LED1 / PINS_COUNT / NUM_DIGITAL_PINS — standard BSP pin-table entries inherited from the nRF52 Arduino core.",
],
"rp2040": [
"PIN_SPI_* — primary SPI pins come from the RP2040 Arduino BSP; most boards declare them explicitly, but the defaults align with the Pico pin assignments.",
"NUM_DIGITAL_PINS / NUM_ANALOG_INPUTS — Arduino BSP counts; rarely overridden locally.",
],
"stm32": [
"Radio and pin assignments for STM32WL targets are largely internal to the WL SoC and declared via STM32 HAL/BSP headers; variant.h files are minimal.",
"USE_STM32WLx is typically the only explicit define; all other radio config comes from the BSP.",
],
"native": [
"The native/Portduino target uses runtime configuration rather than compile-time pin defines; variant.h only sets display and GPS stubs.",
],
}
def collect_inventory() -> dict[str, object]:
architectures: defaultdict[str, list[dict[str, object]]] = defaultdict(list)
category_frequency: defaultdict[str, Counter[str]] = defaultdict(Counter)
total_variant_dirs = 0
total_envs = 0
no_variant_h: defaultdict[str, int] = defaultdict(int) # arch -> count of dirs with no variant.h
has_metadata: int = 0 # env count that has at least one custom_meshtastic_* key
for platformio_path in sorted(VARIANTS_DIR.glob("**/platformio.ini")):
variant_dir = platformio_path.parent
total_variant_dirs += 1
variant_path = variant_dir / "variant.h"
board_level_arch_raw = variant_dir.parts[-2] if len(variant_dir.parts) >= 2 else "unknown"
if not variant_path.exists():
no_variant_h[board_level_arch_raw] += 1
continue
envs = parse_platformio_envs(platformio_path)
defines, category_counts = parse_variant_macros(variant_path)
total_envs += len(envs)
board_level_arch = board_level_arch_raw
for env in envs:
section = str(env["section"])
if not section.startswith("env:"):
continue
metadata = dict(env["metadata"])
if metadata:
has_metadata += 1
architecture = str(metadata.get("custom_meshtastic_architecture") or board_level_arch)
if architecture == "esp32s3":
architecture = "esp32-s3"
if architecture == "esp32c3":
architecture = "esp32-c3"
if architecture == "esp32c6":
architecture = "esp32-c6"
entry = {
"environment": section.split(":", 1)[1],
"variant_dir": str(variant_dir.relative_to(ROOT)),
"metadata": metadata,
"defines": defines,
"category_counts": category_counts,
}
architectures[architecture].append(entry)
for name in defines:
category = classify_macro(name)
category_frequency[category][name] += 1
return {
"architectures": architectures,
"category_frequency": category_frequency,
"total_variant_dirs": total_variant_dirs,
"total_envs": total_envs,
"no_variant_h": dict(no_variant_h),
"has_metadata": has_metadata,
}
def render_markdown(inventory: dict[str, object]) -> str:
architectures = inventory["architectures"]
category_frequency = inventory["category_frequency"]
lines: list[str] = []
lines.append("# Hardware Support Context")
lines.append("")
lines.append("This document inventories the board-support inputs and common target-definition fields")
lines.append("currently used in the Meshtastic firmware repository. It is intended as reusable context")
lines.append("for adding new hardware support without re-discovering naming patterns, metadata keys, and")
lines.append("frequently used pin or capability macros from scratch.")
lines.append("")
lines.append("## Scope")
lines.append("")
lines.append(f"- Variant directories scanned: {inventory['total_variant_dirs']}")
lines.append(f"- PlatformIO environments summarized: {inventory['total_envs']}")
lines.append("- Sources: `variants/**/platformio.ini` and `variants/**/variant.h`")
lines.append("- Notes: This inventory reflects explicit per-variant declarations. Some boards also inherit")
lines.append(" defaults from architecture headers or shared base environments, which must still be checked")
lines.append(" before creating new hardware support.")
lines.append("")
lines.append("## Repository Metadata Inputs")
lines.append("")
lines.append("The following `custom_meshtastic_*` metadata keys are already used across board environments:")
lines.append("")
for key in PLATFORMIO_METADATA_KEYS:
lines.append(f"- `{key}`")
lines.append("")
lines.append("## Common Target-Definition Categories")
lines.append("")
for category in ["Input", "Radio", "GPS", "Display", "I2C/SPI", "Power", "Connectivity/Other", "Other"]:
counter = category_frequency.get(category, Counter())
if not counter:
continue
lines.append(f"### {category}")
lines.append("")
lines.append("| Macro | Used in | Description |")
lines.append("| --- | --- | --- |")
for name, count in counter.most_common(15):
description = MACRO_DESCRIPTIONS.get(name, "")
lines.append(f"| `{name}` | {count} variants | {description} |")
lines.append("")
lines.append("## Architecture and Environment Inventory")
lines.append("")
for architecture in sorted(architectures):
entries = sorted(architectures[architecture], key=lambda item: item["environment"])
lines.append(f"### {architecture}")
lines.append("")
lines.append("| Environment | Display Name | HW Model | HW Slug | Variant Dir | Common Categories |")
lines.append("| --- | --- | --- | --- | --- | --- |")
for entry in entries:
metadata = entry["metadata"]
category_counts = entry["category_counts"]
categories = []
for category in ["Display", "Radio", "Input", "GPS", "Power", "Connectivity/Other"]:
count = category_counts.get(category, 0)
if count:
categories.append(f"{category}:{count}")
category_summary = ", ".join(categories) if categories else "none"
lines.append(
"| {environment} | {display_name} | {hw_model} | {hw_slug} | {variant_dir} | {categories} |".format(
environment=entry["environment"],
display_name=metadata.get("custom_meshtastic_display_name", ""),
hw_model=metadata.get("custom_meshtastic_hw_model", ""),
hw_slug=metadata.get("custom_meshtastic_hw_model_slug", ""),
variant_dir=entry["variant_dir"],
categories=category_summary,
)
)
lines.append("")
lines.append("## Representative Board Examples")
lines.append("")
for architecture in sorted(architectures):
entries = sorted(architectures[architecture], key=lambda item: item["environment"])
if not entries:
continue
sample = entries[0]
lines.append(f"### {architecture}: `{sample['environment']}`")
lines.append("")
lines.append(f"- Variant directory: `{sample['variant_dir']}`")
metadata = sample["metadata"]
for key in PLATFORMIO_METADATA_KEYS:
value = metadata.get(key)
if value:
lines.append(f"- `{key}`: `{value}`")
defines = sample["defines"]
for category in ["Input", "Radio", "GPS", "Display", "I2C/SPI", "Power", "Connectivity/Other"]:
selected = [name for name in defines if classify_macro(name) == category][:8]
if not selected:
continue
lines.append(f"- {category} examples:")
for name in selected:
lines.append(f" - `{name}` = `{shorten(defines[name])}`")
lines.append("")
lines.append("## Intake Guidance For New Hardware")
lines.append("")
lines.append("When using this context to add a new board, collect these inputs before generating files:")
lines.append("")
lines.append("- PlatformIO environment name")
lines.append("- `custom_meshtastic_hw_model` and `custom_meshtastic_hw_model_slug`")
lines.append("- Display name and architecture")
lines.append("- Whether the board is actively supported and its support level")
lines.append("- Partition scheme, DFU requirement, and image/tag metadata if applicable")
lines.append("- Radio chip family and complete radio pin group")
lines.append("- Input/button/rotary/keyboard pins")
lines.append("- Display interface pins and driver-related macros")
lines.append("- GPS, power-management, I2C, SPI, storage, and auxiliary peripheral definitions")
lines.append("- Any board-specific initialization that requires `variant.cpp` or extra variant hooks")
lines.append("")
lines.append("## Inherited Defaults Note")
lines.append("")
lines.append(
"Some architecture families rely on BSP (Board Support Package) or base-environment defaults "
"rather than declaring every pin or capability macro explicitly in `variant.h`. "
"When adding a new board for one of these families, check the relevant BSP headers before "
"assuming a missing define means a feature is absent."
)
lines.append("")
no_variant_h = inventory.get("no_variant_h", {})
if no_variant_h:
lines.append(
f"Directories scanned that had no `variant.h` "
f"(relying entirely on BSP/base-environment): "
+ ", ".join(f"{arch}: {count}" for arch, count in sorted(no_variant_h.items()))
)
lines.append("")
for family, notes in _BSP_DEFAULT_FAMILIES.items():
lines.append(f"### {family}")
lines.append("")
for note in notes:
lines.append(f"- {note}")
lines.append("")
lines.append("## Cautions")
lines.append("")
lines.append("- Some boards rely on architecture defaults rather than declaring every field locally.")
lines.append("- Some board families expose multiple environments or display variants that share one hardware model.")
lines.append("- Source materials such as schematics still need human verification before new pin mappings are trusted.")
lines.append("- This document is a starting context artifact, not proof that a new board definition is safe to merge.")
lines.append("")
return "\n".join(lines)
def print_validate_summary(inventory: dict[str, object]) -> None:
"""Print a validation summary to stdout without writing the output file."""
total_dirs = inventory["total_variant_dirs"]
total_envs = inventory["total_envs"]
has_metadata = inventory["has_metadata"]
no_variant_h = inventory.get("no_variant_h", {})
no_variant_h_total = sum(no_variant_h.values())
architectures = inventory["architectures"]
arch_count = len(architectures)
print("Hardware Support Context — Validation Summary")
print("=" * 48)
print(f"Variant directories scanned : {total_dirs}")
print(f"Directories with no variant.h (BSP-only) : {no_variant_h_total}")
if no_variant_h:
for arch, count in sorted(no_variant_h.items()):
print(f" {arch}: {count}")
print(f"PlatformIO environments found : {total_envs}")
print(f"Environments with custom_meshtastic_* metadata : {has_metadata}")
print(f"Architecture families represented : {arch_count}")
print("")
print("Architecture families:")
for arch in sorted(architectures):
entries = architectures[arch]
print(f" {arch}: {len(entries)} environment(s)")
print("")
print("BSP-default families with special notes:")
for family in _BSP_DEFAULT_FAMILIES:
marker = "YES" if family in {a.split("-")[0] for a in architectures} else "not in scan"
print(f" {family}: {marker}")
def main() -> None:
parser = argparse.ArgumentParser(description="Generate hardware support context markdown")
parser.add_argument("--output", default=str(OUTPUT_PATH), help="Output markdown path")
parser.add_argument(
"--validate",
action="store_true",
help="Print a validation summary (variant counts, BSP-only dirs, metadata coverage) without writing output",
)
args = parser.parse_args()
inventory = collect_inventory()
if args.validate:
print_validate_summary(inventory)
return
markdown = render_markdown(inventory)
output_path = Path(args.output)
output_path.parent.mkdir(parents=True, exist_ok=True)
output_path.write_text(markdown + "\n", encoding="utf-8")
if __name__ == "__main__":
main()