Documentation

PCBA Studio is a local checker for one kind of mistake: the schematic, the STM32CubeMX configuration, and the firmware do not name the same pin.

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 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.firmware.hardcoded_pin_drift	Hand-written firmware names a pin that the .ioc now assigns elsewhere.
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 PCBA Studio.

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 /schemas/finding.schema.json. and a baseline follows /schemas/baseline.schema.json.

A clean result

Exit status 0 means the selected severity threshold was clean. It does not mean every rule ran. coverage.skipped lists the rules that could not run. Read that list.

More than one board

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

version = 1
default_target = "controller"

[targets.controller]
part = "YOUR_ORDERABLE_STM32_PART"
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

pcba 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.

Changed files

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

Report formats

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

pcba review . --format json > review.json

Continuous integration

Install the published package in the job and run the review. The GitHub Action inside the private repository is for Newmatik projects. A public repository cannot use it while that repository stays private.

permissions:
  contents: read

steps:
  - uses: actions/setup-python@v5
    with:
      python-version: "3.12"
  - run: pip install pcba
  - run: pcba review . --format sarif > pcba.sarif