Documentation

The EngineHall engine checks a design where its files are: on your machine or in CI. This page covers what it reads, the rules across schematic, CubeMX and firmware, and how to read a result. The KiCad schematic, part and board rules have their own page.

KiCad checks MCP server

What a review reads

Altium .SchDoc sheets. The pin's electrical end is computed from the pin record. Wires, not the text of a label, decide what is connected.
A KiCad 9 or 10 project: the .kicad_pro, the .kicad_sch hierarchy and the .kicad_pcb. The pin rules below run on its MCU too.
A CubeMX .ioc file, read as CubeMX wrote it.
Hand-written firmware references such as GPIOD, GPIO_PIN_8. Generated defines in main.h are skipped, and vendor trees under Drivers/ and Middlewares/ are not indexed.
For several boards, a pcba-studio.toml at the project root names each target. Paths must stay inside the project, and each firmware root must contain Core/Src.

Rules

cross_domain.pin.mismatch: The same peripheral signal is routed to different pins in the schematic and in the .ioc.
cross_domain.pin.signal_conflict: A pad carries a net that names one peripheral signal while the .ioc gives that pin to a different one.
cross_domain.mcu.part_mismatch: The schematic and CubeMX file name different MCU parts. Pin comparisons are skipped until the inputs match.
cross_domain.firmware.hardcoded_pin_drift: Hand-written firmware writes or configures a pin that the .ioc assigns to a peripheral. Reads do not count.
cross_domain.pin.unconfigured: A peripheral signal on the schematic is absent from the .ioc.
cross_domain.mcu_config.incomplete: The .ioc covers almost none of the schematic. One finding is reported instead of a list of individually true and collectively useless pin findings.
cross_domain.peripheral.unconnected: A peripheral configured in the .ioc has no matching schematic connection.
schematic.net.mislabelled: A net label's pin prefix disagrees with the geometric connection.
schematic.net.open_circuit: A part nearly touches an MCU pin and stops short. This rule is heuristic.
stm32.pin.alternate_function_impossible: The selected pin cannot carry that peripheral signal, according to the MCU database installed with CubeMX. A review on this website skips this rule and says so, because that database is not included with EngineHall.

What a finding contains

Every finding names the artifact, a project-relative location, quoted evidence, the rule id, the severity, the detector, the consequence, and a recommendation. The detector is one of deterministic, heuristic, ai_inferred, external, or manual. The checker does not invent a finding with a language model.

The JSON report follows the schema at finding.schema.json. and a baseline follows baseline.schema.json.

A clean result

Exit status 0 means the selected severity threshold was clean. It does not mean every rule ran or every configured signal was compared. Read coverage.skipped, the compared-signal count, and coverage.statistics.uncompared_signals for each excluded CubeMX assignment.

enginehall inspect .
enginehall review . --require-rule cross_domain.pin.mismatch

More than one board

Put pcba-studio.toml at the project root. Select a target with enginehall review . --target interface.

pcba-studio.toml

version = 1
default_target = "controller"

[targets.controller]
part = "YOUR_ORDERABLE_STM32_PART"
schematic_component = "U1"
ioc = "config/controller.ioc"
schematic_dir = "hardware/controller"
firmware_roots = ["firmware/controller"]

[targets.interface]
ioc = "config/interface.ioc"
schematic_dir = "hardware/interface"
firmware_roots = ["firmware/interface"]

Known findings

enginehall baseline . --reason "Reviewed during initial adoption" writes .pcba-baseline.json. Every suppression has an id and a reason. A review reports how many findings were suppressed and which stored ids no longer match a finding. Commit the file. It is a record of a decision, not a way to hide a new defect.

enginehall baseline . --reason "Reviewed during initial adoption"
enginehall review . --baseline .pcba-baseline.json

Changed files

enginehall review . --changed-only origin/main limits the report to findings whose location or evidence touches a file changed since that git ref.

enginehall review . --changed-only origin/main

Report formats

enginehall review . --format text writes the default report. json, markdown, and sarif are the other formats. Redirect stdout to keep a file.

enginehall review . --format json > review.json

Continuous integration

Install the checked wheel from enginehall.com in the job, then run the review. The private Newmatik GitHub Action is unavailable to public repositories. Switch the install line to the versioned PyPI package when that listing is published.

GitHub Actions

permissions:
  contents: read

steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 0
  - uses: actions/setup-python@v7
    with:
      python-version: "3.12"
  - run: python -m pip install https://enginehall.com/engine/enginehall-2.0.0-py3-none-any.whl
  - run: enginehall review . --require-rule cross_domain.pin.mismatch