EngineHall
Where hardware gets built, checked and released, together. A Newmatik product, formerly PCBA Studio.
EngineHall is the shared workspace of a hardware development project on enginehall.com:
open points, meetings, decisions, documentation, design reviews and releases, for a team and its development
partners. Its engine, described below, runs on your machine. It installs as the enginehall package; the commands
are enginehall and hall (pcba still works for one major version and says it is deprecated).
EngineHall's engine finds contradictions between an Altium or KiCad schematic, an STM32CubeMX configuration, and firmware. A board can route one pin, CubeMX can configure another, and the code can still compile; EngineHall checks those boundaries before they become bench failures. On a KiCad project it also verifies the schematic, the parts and the board: KiCad's own ERC and DRC, rails, decoupling, pull-ups, supply ranges and derating against component data, connector pinouts, the Newmatik house DFM values, and declared SPICE testbenches.
The Python engine is the product. It runs locally, uploads nothing, and produces evidence-backed
findings in text, Markdown, JSON, or SARIF. The VS Code extension is an optional UI for running the
engine, viewing .SchDoc files, and keeping a Markdown project tracker. The public site lives in
site/ and is published at enginehall.com.
Quickstart
Requirements: Python 3.11–3.14. Developing this repo also needs Node: 20, 22, or 24 for the extension and the pre-commit hook, and Node 24.18 or a later 24.x with pnpm for the site. From this source checkout:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
For a public install without a source checkout, use the checked wheel served by the site:
python -m pip install https://enginehall.com/engine/enginehall-2.0.0-py3-none-any.whl
The PyPI listing is pending. The install page will switch to enginehall==2.0.0 after
that listing is verified.
Confirm what EngineHall can see, then run a review:
enginehall inspect .
enginehall review .
Try the synthetic reference board with Try the reference board at
enginehall.com/review. It intentionally reports six injected
errors. Exit status 0 means the selected
failure threshold was clean, 1 means findings met it, and 2 means a required check could not
run or the review could not run.
Always read coverage.skipped, the compared-signal count, and
coverage.statistics.uncompared_signals; zero findings only describes the checks and signal
pairs the review could evaluate. Each unpaired CubeMX placement now names its pin and reason.
Project setup
For a single target, discovery finds the directory with the most .SchDoc files, the first .ioc,
firmware roots containing Core/Src, and the MCU part. Use explicit flags if discovery is ambiguous:
enginehall review . --schematic-dir hardware --ioc config/board.ioc --part YOUR_STM32_PART
--ioc and --schematic-dir are read relative to the project root (here .), then the working
directory. A path that exists in neither stops the review with exit 2 instead of quietly
falling back to discovery. When discovery finds several firmware trees, it keeps the ones beside
the .ioc and says so in project.notes; name others with firmware_roots in
pcba-studio.toml.
The alternate-function rule reads STM32CubeMX's MCU database (db/mcu) from the usual install
locations. Set the PCBA_CUBEMX_DB environment variable to use another copy, for example the same
one on every machine; without a database the rule is listed in coverage.skipped.
If the sheets hold more than one instance of the MCU, the pin map is not extracted until you name
one; an unannotated designator such as U? never selects an instance:
enginehall review . --schematic-component U2
For several boards or firmware targets, add pcba-studio.toml at the project root:
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"]
Paths must exist and remain inside the project. Select a non-default target with --target:
enginehall inspect . --target interface
enginehall review . --target interface
KiCad projects
enginehall review finds a .kicad_pro like it finds .SchDoc sheets; --kicad-project (or
kicad_project on a target) chooses one. kicad-cli and ngspice are optional: without them,
ERC, DRC, the netlist cross-check and the testbenches are listed as not checked. An optional
pcba-requirements.toml declares rail voltages, derating limits, single-sided assembly, edge
clearance, connector pinouts and SPICE testbenches. Every rule ends as passed, failed, info, not
checked (with the reason) or not applicable in coverage.rules. Details:
docs/kicad-review.md.
enginehall doctor --no-ping # kicad-cli and ngspice found?
enginehall review boards/main --format markdown
enginehall kicad netlist boards/main # the nets the engine built from the wires
Requiring coverage
"No findings" from a check that never ran is not a pass. Name the checks that must have usable
input; if one could not run, or compared no signal at all, the review exits 2:
enginehall review . --require-rule cross_domain.pin.mismatch --require-rule cross_domain.firmware.hardcoded_pin_drift
A signal on several pins of one side is not compared first-wins; the report lists it as not compared.
Placements are compared by pad as well as by name, so a board whose nets carry functional names
(RMII_TXD0, WIFI_SPI_SCK) is still compared pin by pin.
The browser review accepts the same pcba-studio.toml, target, MCU overrides, baseline, and
required-rule inputs. Select a project folder to keep configured paths intact. Local Git
--changed-only and the installed CubeMX alternate-function database remain CLI-only.
Existing findings
Create an auditable baseline when adopting the checker in an established project:
enginehall baseline . --reason "Reviewed during initial adoption"
enginehall review . --baseline .pcba-baseline.json
The baseline stores stable finding IDs and a required reason for every suppression. Reviews report both the number suppressed and stale IDs that no longer match a finding. Review and commit the file; do not use it to hide new defects.
A cross_domain.firmware.hardcoded_pin_drift ID is derived from the .ioc, the pin, and the pin's
.ioc key, not from the first source file that names the pin, so adding another source file no
longer changes it. Baselines written by earlier versions suppress this rule under the old
file-based ID: regenerate the baseline once, or the old entry is reported as stale and the finding
reappears.
Changed files and pull requests
Limit local output to findings whose location or evidence touches a changed file:
enginehall review . --changed-only origin/main
The source repository is private, so public repositories install the checked wheel from
enginehall.com in CI, exactly as the documentation shows. Switch
the install line to enginehall==2.0.0 once the PyPI listing is published. Keep full Git history when
using --changed-only:
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
The composite action in this private repository remains available to Newmatik projects. It runs a changed-only review, can upload SARIF, and preserves findings even when required coverage is incomplete. Add the firmware rule to public CI when the repository has firmware.
Publishing to a development project
--publish sends the report (findings, their locations and evidence, and coverage) to the check
runs of a development project on the site. No design file or source file is sent, and local paths
are made project-relative. A lead creates the project token under Members, Tokens; pass it in an
environment variable, never on the command line:
PCBA_WORKSPACE_TOKEN=... enginehall review . --publish --project DEMO --url https://enginehall.com
The run carries its commit and repository, so a release drafted from it records the commit:
--commit defaults to GITHUB_SHA, else git rev-parse HEAD in the reviewed folder, and
--repository (a repository id, or its URL) defaults to the origin remote, sent as
https://host/path without credentials. The site matches the URL against the project's connected
repositories; one it does not know is noted, not an error, and a folder without git publishes
without either. --token-env NAME reads another variable. The exit codes
stay the same, except that a failed publish exits 2. The action's publish, project and
workspace-url inputs do the same, with PCBA_WORKSPACE_TOKEN set from a secret in the step's
env.
What it checks
| Rule | Detects |
|---|---|
cross_domain.mcu.part_mismatch |
The schematic and CubeMX file identify different MCU parts; pin comparisons are skipped until the inputs match. |
cross_domain.pin.mismatch |
A peripheral signal routed to different pins in the schematic and .ioc. |
cross_domain.pin.signal_conflict |
A pad whose schematic net names a different peripheral than the .ioc assigns to it (SPI2_MOSI on a pin configured as I2C1_SDA). |
cross_domain.firmware.hardcoded_pin_drift |
Hand-written code that writes, configures, or otherwise names a pin now assigned to a peripheral in the .ioc. Reads (HAL_GPIO_ReadPin) do not count. |
cross_domain.pin.unconfigured |
A schematic peripheral signal absent from the .ioc. |
cross_domain.mcu_config.incomplete |
A placeholder or wrong .ioc covering almost none of the schematic. |
cross_domain.peripheral.unconnected |
A configured peripheral with no matching schematic connection. |
schematic.net.mislabelled |
A label whose pin prefix disagrees with geometric connectivity. |
schematic.net.open_circuit |
A part that nearly touches an MCU pin but stops short. This rule is heuristic. |
stm32.pin.alternate_function_impossible |
A peripheral signal the selected pin cannot carry according to ST's MCU database. |
On KiCad projects (see docs/kicad-review.md for what each needs):
| Rule | Detects |
|---|---|
kicad.erc.violation |
A violation KiCad's ERC reports (kicad-cli). |
kicad.netlist.parity |
The engine's geometric connectivity disagrees with KiCad's netlist export (kicad-cli). |
kicad.power.rail_without_source |
A net with power inputs but no power output or PWR_FLAG. |
kicad.power.pin_without_dc_path |
An IC power pin that reaches no rail through a DC path (only through a capacitor, or not at all). |
kicad.power.decoupling_missing |
An IC supply net with no capacitor to ground. |
kicad.part.shorted |
A two-pin part with both pins on one net. |
kicad.pin.input_floating |
An input pin connected to nothing and not marked no-connect. |
kicad.net.pull_up_missing |
An I2C or open-drain net without a pull-up. |
kicad.label.global_single_sheet |
A global label used on one sheet only (info). |
kicad.label.single_connection |
A label whose net reaches at most one pin. |
kicad.net.name_hygiene |
VBUS without USB, a rail without a voltage in its name (info). |
kicad.component.supply_range |
A supply pin's rail outside the part's operating range or absolute maximum. |
kicad.component.capacitor_derating |
A capacitor above its derated voltage rating. |
kicad.component.resistor_power |
A resistor between two rails above its derated power rating. |
kicad.component.logic_level |
Driver levels a receiver does not recognise, or an input driven past its rating. |
kicad.component.required_connection |
A pin without the connection its component data requires (NRST capacitor, enable not floating, pull-ups). |
kicad.connector.pin_assignment |
A connector pin that does not carry the signal its interface spec names. |
kicad.drc.violation |
A violation or unconnected item KiCad's DRC reports (kicad-cli). |
kicad.drc.schematic_parity |
Board and schematic out of step (kicad-cli). |
kicad.dfm.fiducials |
House fiducials missing or wrong (NM-FID-001..006). |
kicad.dfm.track_angle |
A track not at 0, 45 or 90 degrees (NM-ROUTE-001). |
kicad.dfm.via_in_pad |
A via in or touching a pad (NM-VIA-001). |
kicad.dfm.via_spacing |
Two same-net vias closer than the house distance (NM-VIA-002). |
kicad.dfm.model_missing |
A footprint without a STEP model on disk (NM-3D-001). |
kicad.dfm.silkscreen_outside |
Silkscreen beyond the board outline (NM-SILK-001). |
kicad.dfm.barcode_field |
No or too small barcode field (NM-BC-001). |
kicad.dfm.bottom_side_smd |
An SMD part on the bottom of a board declared single-sided. |
kicad.dfm.smd_edge_clearance |
SMD copper closer to the edge than the declared clearance. |
kicad.dfm.test_point_coverage |
Nets without a test point. |
kicad.dfm.courtyard_overlap |
Overlapping courtyards. |
simulation.spice.testbench |
A declared ngspice testbench outside its pass range. |
Every finding has a project-relative location, quoted evidence, consequence, recommendation, rule ID, severity, and detector classification. JSON output follows the public finding schema.
Architecture
artifact discovery / target config
|
v
.SchDoc + .ioc + firmware -> normalized project model
| |
v v
parsers --------------------> rules
|
baseline / changed-file filter
|
v
text / Markdown / JSON / SARIF
pcba/review.pyis the shared orchestration layer used by the CLI and engine MCP server.pcba/parsers/reads Altium OLE2 streams, CubeMX.iocfiles, ST MCU metadata, and hand-written firmware references.pcba/rules/compares the normalized model. Schematic connectivity comes from geometry; labels only name nets.pcba/report/renders stable machine and human formats.extension/contains the optional VS Code UI, its heuristic viewer parser, the Markdown tracker, and a separate single-artifact/tracker MCP server.
The engine parser is authoritative for review findings. The TypeScript parser serves interactive viewing; both parsers run the same conformance corpora (record streams, placed-pin selection) to prevent format drift.
Common commands
enginehall inspect . # artifacts, selected target, and rule coverage
enginehall review . # all applicable checks
enginehall review . --format json # text, markdown, json, or sarif
enginehall review . --fail-on warning # choose the failing severity threshold
enginehall baseline . --reason "Reviewed" # write .pcba-baseline.json atomically
enginehall altium pinmap --dir hardware # geometric MCU pin-to-net map
enginehall kicad netlist boards/main # KiCad nets built from wire geometry
enginehall kicad pinmap boards/main # KiCad MCU pin-to-net map
enginehall altium project-sheets --project Synthetic.PrjPcb --format json # structural sheet inventory only
enginehall cubemx pins board.ioc # CubeMX pin assignments
enginehall cubemx af board.ioc PA2 # allowed alternate functions
enginehall cubemx diff old.ioc new.ioc # compare generated configurations
enginehall cubemx validate board.ioc manifest.json
enginehall mcp # engine MCP server over stdio
Extension development is separate and optional:
cd extension
npm ci
npm test
npm run package
Open extension/ in VS Code and press F5. The viewer and tracker work without the Python package;
the EngineHall: Run Hardware/Firmware Review command requires pcba on the extension host's
PATH. Findings appear in the Problems panel.
To register the engine with an MCP client, activate the virtualenv and use:
{
"mcpServers": {
"enginehall": { "command": "enginehall", "args": ["mcp"] }
}
}
The local servers (enginehall mcp, enginehall altium mcp, and the extension's) review design files on your
computer. A hosted server at https://enginehall.com/mcp lets an assistant read your account and
the saved projects of your workspaces, and read and draft items in your development projects
(every write is previewed and needs your approval); it never receives design files:
claude mcp add --transport http pcbastudio https://enginehall.com/mcp
Setup for other clients, the tool list, and the safety model: https://enginehall.com/docs/mcp.
Claude Code plugin
The repository is also a Claude Code plugin marketplace (.claude-plugin/). For anyone with
access to the repository:
/plugin marketplace add newmatik/pcbastudio
/plugin install enginehall@newmatik
The plugin brings the seven skills and three MCP servers: pcba (review), pcba-altium (Altium
drive, Windows with Altium running) and fusion (Autodesk Fusion's local server on port 27182, or
FUSION_MCP_PORT). The Python servers run with uvx from the plugin itself, so
uv is the only requirement: no virtualenv, nothing on PATH. The
plugin has no version number, so every commit on main is an update
(claude plugin update enginehall@newmatik). Try a working tree with claude --plugin-dir ..
Claude Code hides a plugin server that duplicates one you registered yourself, so remove an
earlier fusion or pcba entry (claude mcp remove fusion -s user) to use the plugin's.
The extension's schematic and tracker server ships with the extension: run EngineHall: Set up
MCP server for AI chat in VS Code or Cursor.
Contributing
Codex and Claude Code skills
From this source checkout, install the six maintained skills for both clients:
python3 tools/install-skills.py
# Or select just one client:
python3 tools/install-skills.py --clients codex
The installer links into each client's user skill directory.
With the Claude Code plugin installed, link for Codex only (--clients codex); Claude Code
would otherwise list every skill twice.
It repairs links after moving the checkout and leaves real directories untouched. Skills stay
in this repository, so later edits are picked up without copying them again. On Windows,
creating directory symlinks requires Developer Mode or an elevated terminal.
Codex MCP configuration uses TOML; .mcp.json is the Claude Code configuration. Register
the review engine with an absolute virtualenv executable so GUI launches work:
codex mcp add pcba -- /absolute/venv/bin/python -m pcba.cli mcp
codex mcp add enginehall-extension -- /absolute/node /absolute/extension/dist/mcp-server.js
codex mcp add fusion --url http://127.0.0.1:27182/mcp
The extension bundle provides schematic viewing and tracker tools. Build it with
cd extension && npm run build first. The engine and extension have separate tool sets.
On Windows, register Altium's separate drive server with the virtualenv's Python:
codex mcp add pcba-altium -- C:\absolute\venv\Scripts\python.exe -m pcba.cli altium mcp
Start a new client session after registering servers or skills. Altium editing requires the
MCP process to run in the logged-in Windows desktop session with Altium running. A Mac can
load its tool catalogue, but cannot drive Altium locally; an SSH service session also lacks
the interactive desktop. enginehall doctor reports the local prerequisites and connection fixes.
Read AGENTS.md in the source checkout before changing code. In particular:
- Never commit customer schematics,
.iocvalues, net labels, part numbers, pin maps, or project names. Extendfixtures/synthetic/instead. - Treat
.iocfiles as CubeMX-owned. Any write must use the adapter's inspect, plan, preview, approve, apply, reinspect, verify, and record workflow. - Add deterministic parsing and rules before explanation. Give every finding navigable evidence.
- Add a synthetic defect and exact golden assertion for a new rule. Run
tools/precommit.shbefore every commit, and keep one logical change per English commit.
The site (site/) runs locally on port 3090, its Worker preview on 8790, and its local Supabase
stack on 60321–60324; AGENTS.md lists the commands.
The supported product path is STM32 firmware with Altium or KiCad schematics. EngineHall assists review; it
does not provide certification or engineering sign-off. See docs/roadmap.md in the source for
scope and non-goals.
Proprietary software, © 2026 Newmatik GmbH. See the license.
Metadata
Release files for enginehall 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| enginehall-2.0.0.tar.gz | 261.9 kB | With provenance | Details for enginehall-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| enginehall-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for enginehall-2.0.0-py3-none-any.whl |
Total release size: 561.8 kB
Release files / enginehall-2.0.0.tar.gz
| Download URL | enginehall-2.0.0.tar.gz |
|---|---|
| Size | 261.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8855f1fcc164be59d2579bc46ba2506575e7335443b0714b6650444d0f38def6
|
|
BLAKE2b-256 checksum How to use checksums |
b20e245c6fe16f8d0e13c79f0e810dc856b0b1a8c5525766e81752b9604c439d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logRelease files / enginehall-2.0.0-py3-none-any.whl
| Download URL | enginehall-2.0.0-py3-none-any.whl |
|---|---|
| Size | 299.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d285e7064cfa1bf12b0e44e26051c7e5054b1b0b4c730b0c45afb74aa9b84e0a
|
|
BLAKE2b-256 checksum How to use checksums |
3df485e2ddbf5b455a796a104a5292d8204100357512606272097384609b47e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logSecurity for enginehall 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for enginehall-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.