### boardsmith-fw Quick Start Guide

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/README.md

A step-by-step guide to using boardsmith-fw, from importing a schematic to building the firmware.

```APIDOC
## Quick Start

Follow these steps to get started with `boardsmith-fw`:

1.  **Import a schematic**:
    ```bash
    boardsmith-fw import fixtures/esp32_bme280_i2c/esp32_bme280.sch --out output
    ```

2.  **Analyze hardware**:
    This step generates a hardware graph and an analysis report.
    ```bash
    boardsmith-fw analyze --out output
    ```

3.  **Generate firmware**:
    Navigate to the output directory and generate the firmware project.
    ```bash
    cd output
    boardsmith-fw generate --description "Read BME280 sensor data every second" --lang c
    ```

4.  **Build the firmware**:
    Compile the generated project using the appropriate toolchain.
    ```bash
    boardsmith-fw build --project generated_firmware
    ```
    *(Note: Requires ESP-IDF, STM32 toolchain, or Pico SDK to be installed.)*
```

--------------------------------

### Boardsmith Development Environment Setup (Bash)

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

Provides the basic bash commands required to set up the development environment for the Boardsmith project. This includes forking the repository, cloning it, navigating into the directory, and installing the project with development dependencies.

```bash
# 1. Fork and clone
git clone https://github.com/ForestHubAI/boardsmith
cd VibeHard
pip install -e ".[dev]"

```

--------------------------------

### boardsmith-fw Quick Start Workflow

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/README.md

Demonstrates the basic workflow for using boardsmith-fw to import a schematic, analyze hardware, generate firmware, and build the project. This involves several sequential commands.

```bash
# 1. Import a schematic
boardsmith-fw import fixtures/esp32_bme280_i2c/esp32_bme280.sch --out output

# 2. Analyze hardware (generates hardware_graph.json + analysis.md)
boardsmith-fw analyze --out output

# 3. Generate firmware
cd output
boardsmith-fw generate --description "Read BME280 sensor data every second" --lang c

# 4. Build (requires ESP-IDF / STM32 toolchain / Pico SDK)
boardsmith-fw build --project generated_firmware
```

--------------------------------

### Cloning Boardsmith and Setting Up Development Environment

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

This section details the initial steps for setting up a local development environment for Boardsmith. It includes cloning the repository, navigating into the project directory, and installing the project with development dependencies.

```bash
git clone https://github.com/ForestHubAI/boardsmith
cd VibeHard
pip install -e ".[dev]"
```

--------------------------------

### Minimal Sensor Component Entry Example (Python)

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

Provides a minimal, yet complete, example of a component entry for a temperature and humidity sensor (SHT31) using Python's TypedDict. It includes essential fields like MPN, manufacturer, name, category, interface, electrical ratings, and capabilities.

```python
# shared/knowledge/seed/sensor.py

ComponentEntry(
    mpn="SHT31-DIS",
    manufacturer="Sensirion",
    name="SHT31 Temperature and Humidity Sensor",
    category="sensor",
    sub_type="temp_humidity",
    description="High-accuracy I2C temperature and humidity sensor",
    interface_types=["I2C"],
    package="DFN-8",
    mounting="smd",
    electrical_ratings=ElectricalRatings(
        vdd_min=2.4,
        vdd_max=5.5,
        current_draw_typical_ma=0.3,
    ),
    timing_caps=TimingCaps(
        i2c_max_clock_hz=1_000_000,
        i2c_modes=["standard", "fast", "fast-plus"],
    ),
    known_i2c_addresses=["0x44", "0x45"],
    i2c_address_selectable=True,
    unit_cost_usd=2.50,
    tags=["temperature", "humidity", "i2c", "sensirion"],
    datasheet_url="https://sensirion.com/media/documents/213E6A3B/63A5A569/Datasheet_SHT3x_DIS.pdf",
    status="active",
    capabilities={
        "measures": ["temperature", "humidity"],
        "temp_range_c": [-40, 125],
        "temp_accuracy_c": 0.3,
        "humidity_range_pct": [0, 100],
        "humidity_accuracy_pct": 2.0,
    },
    library_support=["arduino", "micropython", "esp-idf", "zephyr"],
),
```

--------------------------------

### boardsmith-fw Installation

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/README.md

Instructions for installing the boardsmith-fw CLI tool using pip.

```APIDOC
## Installation

To install the `boardsmith-fw` CLI command, use pip:

```bash
pip install -e ".[dev]"
```

This command installs the package in editable mode and includes development dependencies.
```

--------------------------------

### Install boardsmith-fw CLI

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/README.md

Installs the boardsmith-fw command-line interface tool and its development dependencies using pip.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Boardsmith Diagnostics Contract JSON Example

Source: https://github.com/foresthubai/boardsmith/blob/main/synthesizer/docs/boardsmith_hw_spec.md

An example of the JSON structure emitted by the `boardsmith-fw validate-hir` command. This format includes tool information, validation summary, and detailed diagnostics for each issue found, including severity, message, and suggested fixes.

```json
{
  "tool": "boardsmith-fw",
  "version": "0.6.0",
  "hir_version": "1.1.0",
  "valid": false,
  "summary": {
    "total": 12,
    "errors": 2,
    "warnings": 3,
    "info": 7,
    "unknown": 1
  },
  "diagnostics": [
    {
      "id": "i2c_addr.i2c0.conflict",
      "category": "protocol",
      "severity": "error",
      "status": "fail",
      "message": "Address conflict on bus i2c0: 0x76 used by U2 and U3",
      "path": "$.bus_contracts[0].slave_addresses",
      "affected_components": ["U2", "U3"],
      "suggested_fixes": [
        "Pick alternate address for one part if selectable",
        "Insert I2C mux (e.g., TCA9548A)",
        "Move one part to separate I2C bus"
      ],
      "provenance": {
        "source_type": "inference",
        "confidence": 1.0
      }
    }
  ]
}
```

--------------------------------

### Adding and Testing a Component with Boardsmith CLI

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

This snippet demonstrates the command-line interface (CLI) commands for adding a new component to the Boardsmith project, verifying its loading, and performing a quick build test. It also includes running the project's test suite.

```bash
# shared/knowledge/seed/sensor.py  (or display.py, comms.py, etc.)

boardsmith list-components | grep SHT31

boardsmith build -p "ESP32 with SHT31 humidity sensor" --no-llm --no-pcb

pytest
```

--------------------------------

### Build Firmware using boardsmith-fw CLI

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/fixtures/esp32_bme280_i2c/README.md

This sequence of commands demonstrates the workflow for importing a schematic, analyzing the design, generating C firmware code for the BME280 sensor, and building the final project.

```bash
boardsmith-fw import fixtures/esp32_bme280_i2c/esp32_bme280.sch
boardsmith-fw analyze
boardsmith-fw research
boardsmith-fw generate --description "Read temperature, humidity, and pressure from BME280 every second" --lang c
boardsmith-fw build
```

--------------------------------

### Test Firmware with Boardsmith CLI

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Tests firmware through hardware simulation using QEMU or Renode. Supports specifying the simulator, custom ELF paths, and timeouts for the simulation environment.

```bash
boardsmith test-firmware --out ./output --simulate
```

```bash
boardsmith test-firmware --out ./output --simulate --simulator renode
```

```bash
boardsmith test-firmware --out ./output --simulate --elf build/firmware.elf --timeout 30
```

--------------------------------

### Execute Agentic Build Loop

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Demonstrates how to run the orchestrator to synthesize hardware designs from natural language prompts. It handles configuration parameters, iteration limits, and result auditing.

```python
result: BuildResult = asyncio.run(orchestrator.build(
    prompt="ESP32 with BME280 over I2C",
    target="esp32",
    out_dir=Path("./output"),
    quality="balanced",
    max_iterations=5,
    max_erc_iterations=5,
    with_pcb=True,
    generate_firmware=True,
    progress_callback=on_iteration,
    seed=42,
    clarification_mode="single",
))

print(f"Success: {result.success}")
print(f"Confidence: {result.confidence:.0%}")
print(f"Final state: {result.final_state.value}")
print(f"HITL required: {result.hitl_required}")
```

--------------------------------

### SPI Configuration Schema

Source: https://github.com/foresthubai/boardsmith/blob/main/synthesizer/docs/boardsmith_hw_spec.md

Defines the configuration parameters for an SPI interface, including maximum clock frequency, operating mode, bit order, and chip select behavior. It also includes timing parameters for chip select setup and hold.

```json
{
            "type": "object",
            "properties": {
              "max_clock_hz": { "type": "integer", "minimum": 1000 },
              "mode": { "type": "integer", "enum": [0, 1, 2, 3] },
              "bit_order": { "type": "string", "enum": ["MSB", "LSB"] },
              "cs_active": { "type": "string", "enum": ["low", "high"] },
              "cs_setup_ns": { "type": "integer" },
              "cs_hold_ns": { "type": "integer" }
            }
          }
```

--------------------------------

### boardsmith-fw CLI for Firmware Compilation and Management (Bash)

Source: https://context7.com/foresthubai/boardsmith/llms.txt

This set of bash commands demonstrates the usage of the boardsmith-fw CLI for various firmware development tasks. It covers importing schematics, analyzing hardware, generating firmware for different targets and RTOS, building, flashing, monitoring, and extracting component knowledge from datasheets.

```bash
# Import schematic
boardsmith-fw import fixtures/esp32_bme280_i2c/esp32_bme280.sch --out output

# Analyze hardware graph
boardsmith-fw analyze --out output

# Generate firmware with FreeRTOS and PlatformIO
boardsmith-fw generate \
  --description "Read BME280 sensor data every second" \
  --lang c \
  --target auto \
  --rtos \
  --platformio \
  --ci \
  --out firmware

# Build firmware
boardsmith-fw build --project generated_firmware

# Flash to device
boardsmith-fw flash --project generated_firmware --port /dev/ttyUSB0

# Monitor serial output
boardsmith-fw monitor --port /dev/ttyUSB0 --baud 115200

# Extract component knowledge from datasheet
boardsmith-fw extract datasheet.pdf --model gpt-4o --save

# Browse built-in knowledge
boardsmith-fw knowledge BME280
```

--------------------------------

### Create Manufacturing Packages with Boardsmith CLI

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Creates production-ready manufacturing packages for PCB fabrication services. Supports multiple services and explicit HIR path specification. The output is a zip file suitable for direct upload to fabrication platforms.

```bash
boardsmith manufacture --out ./output --service jlcpcb
```

```bash
boardsmith manufacture --out ./output -s jlcpcb -s seeed -s pcbway
```

```bash
boardsmith manufacture --out ./output -s jlcpcb --hir ./output/hir.json
```

--------------------------------

### Configure CMake for ESP-IDF Firmware

Source: https://github.com/foresthubai/boardsmith/blob/main/examples/output/01_temp_sensor/firmware/CMakeLists.txt

This CMake script initializes the project, sets the C++ standard to 17, and defines the source files and include directories. It concludes by including the necessary ESP-IDF project tools to enable the build process.

```cmake
cmake_minimum_required(VERSION 3.16)
project(firmware)
set(CMAKE_CXX_STANDARD 17)

# ESP-IDF / Arduino component list
set(COMPONENT_SRCS "main.cpp" "init.cpp")
set(COMPONENT_ADD_INCLUDEDIRS ".")

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
```

--------------------------------

### Execute PCB Generation Pipeline

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Shows how to initialize the PcbPipeline to convert HIR data into physical PCB layouts. It supports deterministic routing and manufacturing export for services like JLCPCB.

```python
hir_dict = json.loads(Path("./output/hir.json").read_text())
pipeline = PcbPipeline(use_llm=False)
result: PcbResult = pipeline.run(
    hir_dict=hir_dict,
    out_dir=Path("./output"),
    project_base="my_board",
    export_manufacturing=["jlcpcb"],
)

if result.pcb_path:
    print(f"PCB: {result.pcb_path}")
    print(f"Gerbers: {result.gerber_dir}")
```

--------------------------------

### Manual PCB Routing Workflow with Docker

Source: https://github.com/foresthubai/boardsmith/blob/main/docker/freerouting/README.md

A sequence of commands to manually process a PCB file: exporting a DSN file, running the FreeRouting autorouter, importing the session file, and generating Gerber files. These commands mount the current working directory to /work inside the container.

```bash
# Export DSN from .kicad_pcb
docker run --rm -v $(pwd)/output:/work boardsmith/freerouting:latest \
  kicad-cli pcb export dsn --output /work/board.dsn /work/pcb.kicad_pcb

# Route with FreeRouting
docker run --rm -v $(pwd)/output:/work boardsmith/freerouting:latest \
  freerouting -de /work/board.dsn -do /work/board.ses -mp 1

# Import routing results back
docker run --rm -v $(pwd)/output:/work boardsmith/freerouting:latest \
  kicad-cli pcb import ses --input /work/board.ses /work/pcb.kicad_pcb

# Export Gerbers
docker run --rm -v $(pwd)/output:/work boardsmith/freerouting:latest \
  kicad-cli pcb export gerbers --output /work/gerbers /work/pcb.kicad_pcb
```

--------------------------------

### Boardsmith Research Command for Component Lookup

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Searches the knowledge base or dynamically researches components using the knowledge agent. Supports specific component lookups, description searches, and database-only queries.

```bash
boardsmith research BME280
boardsmith research "CO2 sensor I2C 3.3V"
boardsmith research SCD41 --no-agent
boardsmith research MAX17043 --cache-dir ~/.boardsmith/knowledge/
```

--------------------------------

### Run Agentic Build Loop

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Initiates an agentic build loop to design and generate hardware, including firmware.

```APIDOC
## Run Agentic Build Loop

### Description
This endpoint initiates an agentic build loop to design and generate hardware, including firmware, based on a given prompt and target.

### Method
Asynchronous Function Call (Conceptual)

### Endpoint
N/A (Python function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from pathlib import Path
from boardsmith.orchestrator import BuildResult

# Assume orchestrator and on_iteration are defined elsewhere
# result: BuildResult = asyncio.run(orchestrator.build(
#     prompt="ESP32 with BME280 over I2C",
#     target="esp32",
#     out_dir=Path("./output"),
#     quality="balanced",              # fast (0.75), balanced (0.85), high (0.90)
#     max_iterations=5,
#     max_erc_iterations=5,
#     with_pcb=True,
#     generate_firmware=True,
#     progress_callback=on_iteration,
#     seed=42,
#     clarification_mode="single",     # none, single, auto
# ))
```

### Response
#### Success Response (BuildResult)
- **success** (boolean) - Indicates if the build was successful.
- **confidence** (float) - The confidence score of the build result.
- **final_state** (string) - The final state of the build process.
- **hitl_required** (boolean) - Whether Human-In-The-Loop is required.
- **gate_matrix** (object | null) - Contains pass/fail criteria for release.
  - **release_ready** (boolean)
  - **erc_clean** (boolean)
  - **boot_pins_valid** (boolean)
  - **power_budget_ok** (boolean)
  - **bom_complete** (boolean)
- **audit_trail** (object)
  - **accept_reason** (string)
  - **iterations** (array of objects)
    - **iteration** (integer)
    - **confidence** (float)

#### Response Example
```json
{
  "success": true,
  "confidence": 0.85,
  "final_state": "completed",
  "hitl_required": false,
  "gate_matrix": {
    "release_ready": true,
    "erc_clean": true,
    "boot_pins_valid": true,
    "power_budget_ok": true,
    "bom_complete": true
  },
  "audit_trail": {
    "accept_reason": "All gates passed.",
    "iterations": [
      {"iteration": 1, "confidence": 0.70},
      {"iteration": 2, "confidence": 0.85}
    ]
  }
}
```
```

--------------------------------

### boardsmith-fw Generate Firmware Options

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/README.md

Illustrates advanced generation options for boardsmith-fw, including specifying the description, language, target, RTOS integration, PlatformIO support, CI workflow generation, and output directory.

```bash
boardsmith-fw generate \
  --description "Read temperature and humidity" \
  --lang c \
  --target auto \
  --rtos \
  --platformio \
  --ci \
  --out firmware
```

--------------------------------

### Running Boardsmith Tests and Builds

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

This snippet shows how to execute the full test suite for the Boardsmith project, run specific test modules, and perform a build using the Boardsmith CLI. It highlights options like disabling LLM and PCB generation, and using a specific seed for reproducibility.

```bash
# Run all tests (~10 seconds, no API key needed)
pytest

# Run a single module
pytest tests/synthesizer/ -v

# Try a build (no API key)
boardsmith build -p "ESP32 with MPU6050 IMU" --no-llm --no-pcb --seed 42
```

--------------------------------

### List Components with boardsmith-fw CLI

Source: https://github.com/foresthubai/boardsmith/blob/main/synthesizer/docs/boardsmith_hw_spec.md

Exposes the knowledge inventory for Boardsmith component selection. This command can filter components by various criteria and output the inventory in JSON format, including cached data.

```bash
boardsmith-fw list-components --format json --include-cache --category sensor
```

--------------------------------

### Boardsmith List-Components Command for Browsing Knowledge Base

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Lists all components in the built-in knowledge database. Supports filtering by component role such as sensor, MCU, or display.

```bash
boardsmith list-components
boardsmith list-components --role sensor
boardsmith list-components --role mcu
boardsmith list-components --role display
```

--------------------------------

### Boardsmith Build-Project Command for Single-Pass Synthesis

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Performs a single-pass pipeline for direct prompt-to-hardware conversion without iterative improvement. Can generate full projects, PCBs, and firmware.

```bash
boardsmith build-project   --prompt "ESP32 with BME280 temperature sensor and SSD1306 OLED over I2C"   --target esp32   --out ./my-project
boardsmith build-project   --prompt "RP2040 with NeoPixel LED strip"   --target rp2040   --generate-pcb   --out ./led-controller
boardsmith build-project   --prompt "ESP32 weather station"   --no-interactive   --confidence-threshold 0.75   --out ./batch-output
```

--------------------------------

### boardsmith-fw CLI Commands

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/README.md

Overview of the available commands for the boardsmith-fw CLI tool, covering schematic import, analysis, firmware generation, building, and more.

```APIDOC
## boardsmith-fw CLI Commands

This section details the various commands available in the `boardsmith-fw` CLI tool for compiling hardware schematics into firmware projects.

### Commands Overview

| Command | Description |
|---|---|
| `boardsmith-fw import <path>` | Parse schematic/netlist into internal model |
| `boardsmith-fw analyze` | Build hardware graph + analysis report |
| `boardsmith-fw research` | Search datasheets, extract component knowledge |
| `boardsmith-fw generate` | Generate firmware from graph + knowledge + HIR |
| `boardsmith-fw build` | Compile with target toolchain |
| `boardsmith-fw flash` | Flash firmware to MCU |
| `boardsmith-fw monitor` | Serial monitor (miniterm) |
| `boardsmith-fw verify` | Compile-check via Docker or local toolchain |
| `boardsmith-fw extract <pdf>` | Extract component knowledge from datasheet PDF |
| `boardsmith-fw knowledge [mpn]` | Browse the built-in component knowledge DB |
| `boardsmith-fw init` | Generate default `.boardsmith-fw.yaml` config |
```

--------------------------------

### Initialization Contracts Schema

Source: https://github.com/foresthubai/boardsmith/blob/main/synthesizer/docs/boardsmith_hw_spec.md

Defines the initialization sequences for components, specifying operations (reads and writes) for different phases like reset, configure, and calibrate. It includes timing delays and preconditions/postconditions.

```json
{
      "type": "array",
      "items": {
        "type": "object",
        "required": ["component_id", "phases"],
        "properties": {
          "component_id": { "type": "string" },
          "component_name": { "type": "string" },
          "phases": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["phase", "order"],
              "properties": {
                "phase": { "type": "string", "enum": ["reset", "configure", "calibrate", "enable", "verify"] },
                "order": { "type": "integer", "minimum": 0 },
                "writes": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["reg_addr", "value"],
                    "properties": {
                      "reg_addr": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" },
                      "value": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" },
                      "description": { "type": "string" },
                      "purpose": { "type": "string" }
                    }
                  }
                },
                "reads": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["reg_addr"],
                    "properties": {
                      "reg_addr": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" },
                      "expected_value": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" },
                      "mask": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" },
                      "description": { "type": "string" },
                      "purpose": { "type": "string" }
                    }
                  }
                },
                "delay_after_ms": { "type": "integer", "minimum": 0 },
                "precondition": { "type": "string" },
                "postcondition": { "type": "string" },
                "provenance": { "$ref": "#/$defs/provenance" }
              }
            }
          }
        }
      }
    }
```

--------------------------------

### Compile Firmware with Boardsmith CLI

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Compiles generated firmware using various build systems like PlatformIO, ESP-IDF, or CMake. Allows for auto-detection of the build system or explicit specification of the runner and target.

```bash
boardsmith compile --out ./output
```

```bash
boardsmith compile --out ./output --runner platformio
```

```bash
boardsmith compile --out ./output --runner idf --target esp32
```

--------------------------------

### Access Component Knowledge Database

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Provides methods to query the built-in component database by MPN to retrieve electrical ratings, timing capabilities, and interface information.

```python
from shared.knowledge.components import COMPONENTS, find_by_mpn

bme280 = find_by_mpn("BME280")
if bme280:
    print(f"Name: {bme280['name']}")
    ratings = bme280['electrical_ratings']
    print(f"VDD: {ratings['vdd_min']}V - {ratings['vdd_max']}V")
```

--------------------------------

### Boardsmith Knowledge Base Component Categories (Python)

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

Illustrates the directory structure and file organization for component definitions within the Boardsmith knowledge base. Each file categorizes specific types of hardware components.

```python
shared/knowledge/seed/
├── sensor.py       <- BME280, MPU6050, SCD41, ...
├── display.py      <- SSD1306, ST7789, ...
├── mcu.py          <- ESP32, RP2040, STM32F4, ...
├── comms.py        <- SX1276 LoRa, nRF24L01, ...
├── power.py        <- LDOs, DC-DC converters
├── memory.py       <- Flash, EEPROM, FRAM
├── actuator.py     <- Motors, servos, relays
└── other.py        <- Everything else
```

--------------------------------

### Filter Components by Category and Electrical Ratings (Python)

Source: https://context7.com/foresthubai/boardsmith/llms.txt

This Python code filters a list of components to categorize them by type (sensor, mcu, display) and identify specific characteristics like 5V tolerance in MCUs. It demonstrates list comprehension for efficient data filtering and extraction.

```python
sensors = [c for c in COMPONENTS if c['category'] == 'sensor']
mcus = [c for c in COMPONENTS if c['category'] == 'mcu']
displays = [c for c in COMPONENTS if c['category'] == 'display']

print(f"Sensors: {len(sensors)}")
print(f"MCUs: {len(mcus)}")
print(f"Displays: {len(displays)}")

tolerant_mcus = [
    c for c in mcus
    if c.get('electrical_ratings', {}).get('is_5v_tolerant', False)
]
for mcu in tolerant_mcus:
    print(f"  {mcu['mpn']}: {mcu['name']}")
```

--------------------------------

### boardsmith-fw Generate Command Options

Source: https://github.com/foresthubai/boardsmith/blob/main/compiler/README.md

Detailed options for the `boardsmith-fw generate` command, allowing customization of firmware generation, including language, target, RTOS, and CI integration.

```APIDOC
## boardsmith-fw generate Command Options

The `generate` command compiles the analyzed hardware graph and component knowledge into a compilable firmware project. The following options allow for customization:

### Command Example

```bash
boardsmith-fw generate \
  --description "Read temperature and humidity" \
  --lang c \
  --target auto \
  --rtos \
  --platformio \
  --ci \
  --out firmware
```

### Options

- `--description` (string): A brief description of the firmware's functionality.
- `--lang` (string): The programming language for the generated code (e.g., `c`).
- `--target` (string): The target MCU or framework (e.g., `auto`, `esp32`, `stm32`, `rp2040`). `auto` attempts to detect from the schematic.
- `--rtos` (flag): Enable FreeRTOS task-per-bus architecture.
- `--platformio` (flag): Generate a `platformio.ini` configuration file.
- `--ci` (flag): Generate a GitHub Actions workflow for CI/CD.
- `--out` (string): The output directory for the generated firmware project.
```

--------------------------------

### Minimal Agent Structure in Boardsmith

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

This Python snippet presents the basic structure for an agent within the Boardsmith project. It includes initialization with an optional LLM gateway, the `run` method utilizing a ReAct loop, and a mandatory deterministic fallback mechanism that must function without an LLM.

```python
from shared.agents.react_loop import run_react_loop, ReActResult
from shared.llm.gateway import LLMGateway

class MyAgent:
    def __init__(self, gateway: LLMGateway | None = None) -> None:
        self._gateway = gateway

    async def run(self, context: dict) -> MyResult:
        if self._gateway is None:
            return self._deterministic_fallback(context)
        result = await run_react_loop(
            gateway=self._gateway,
            system_prompt=SYSTEM_PROMPT,
            tools=MY_TOOLS,
            initial_message=...,
        )
        return self._parse(result)

    def _deterministic_fallback(self, context: dict) -> MyResult:
        # Must always work without LLM
        ...

```

--------------------------------

### Implementing a Pipeline Stage in Boardsmith

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

This Python code defines the structure for a pipeline stage within the synthesizer component. It shows the `run` method signature, emphasizing the use of Pydantic models for return types and the requirement for a deterministic fallback when LLM is disabled.

```python
class B3ComponentSelector:
    def run(self, spec: RequirementsSpec, use_llm: bool = True) -> ComponentSelection:
        ...

```

--------------------------------

### Boardsmith Component Capabilities by Category (Python)

Source: https://github.com/foresthubai/boardsmith/blob/main/CONTRIBUTING.md

Demonstrates the structure of the 'capabilities' field for different hardware component categories within the Boardsmith knowledge base. This field specifies unique technical attributes for each component type.

```python
# sensor
capabilities={
    "measures": ["temperature", "pressure", "humidity"],
    "temp_range_c": [-40, 85],
    "resolution_bits": 16,
}

# display
capabilities={
    "resolution": [128, 64],
    "color": False,
    "protocol": "I2C",
    "driver_ic": "SSD1306",
}

# comms
capabilities={
    "frequency_band_mhz": 868,
    "protocol": "LoRa",
    "max_output_dbm": 20,
    "spreading_factors": [7, 8, 9, 10, 11, 12],
}

# mcu
capabilities={
    "cores": 2,
    "max_freq_mhz": 240,
    "flash_kb": 0,
    "ram_kb": 520,
    "gpio_count": 34,
    "wifi": True,
    "bluetooth": True,
}
```

--------------------------------

### Generate PCB Layout with Boardsmith CLI

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Generates a PCB layout from High-Level Intermediate Representation (HIR) data. Supports optional auto-routing and Gerber export. Can be run in a deterministic mode, bypassing LLM placement hints for reproducible results.

```bash
boardsmith pcb --hir ./output/hir.json --out ./output
```

```bash
boardsmith pcb --hir ./output/hir.json --out ./output --no-llm
```

--------------------------------

### Orchestrate Iterative Design with Python API

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Implements a full iterative orchestration loop for hardware design, incorporating design review and automatic improvement capabilities. This Python API allows for real-time progress updates via a callback function and supports different agent modes for design exploration.

```python
import asyncio
from pathlib import Path
from agents.iterative_orchestrator import (
    IterativeOrchestrator,
    BuildResult,
    IterationRecord,
    ACCEPT_THRESHOLDS,
)

# Progress callback for real-time updates
def on_iteration(record: IterationRecord) -> None:
    print(f"Iteration {record.iteration}: {record.confidence:.0%}")
    print(f"  Stages: {record.stages_rerun}")
    print(f"  Issues: {len(record.issues_found)}")
    print(f"  Fixes: {record.fixes_applied}")
    if record.agent_scores:
        for agent, score in record.agent_scores.items():
            print(f"  {agent}: {score:.0%}")

# Initialize orchestrator
orchestrator = IterativeOrchestrator(
    use_llm=True,
    agent_mode="standard",  # or "experimental" for auto-clarification
)


```

--------------------------------

### Perform Design Review with Boardsmith CLI

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Conducts agentic design reviews focusing on electrical, power, and component quality. Supports auto-improvement mode, providing an original prompt for context, and deterministic checks only.

```bash
boardsmith design-review --hir ./output/hir.json
```

```bash
boardsmith design-review --hir ./output/hir.json --auto-improve
```

```bash
boardsmith design-review --hir ./output/hir.json --prompt "ESP32 CO2 monitor"
```

```bash
boardsmith design-review --hir ./output/hir.json --no-llm
```

--------------------------------

### Boardsmith Build Command for Agentic Design

Source: https://context7.com/foresthubai/boardsmith/llms.txt

Executes the primary command for iterative hardware synthesis with automatic quality improvement and ERC repair. Supports various targets, quality settings, and offline modes.

```bash
boardsmith build -p "ESP32 with BME280 temperature sensor" --quality balanced
boardsmith build -p "ESP32 with BME280 temperature sensor" --no-llm
boardsmith build -p "RP2040 CO2 monitor with SCD41 sensor and ST7789 TFT"   --target rp2040   --quality high   --max-iterations 5
boardsmith build -p "ESP32 with 5V HC-SR04 ultrasonic" --agent experimental
boardsmith build -p "STM32 motor controller" --no-llm --no-pcb --no-firmware --seed 42
```