ozmosko/pcb-board-testing

PCB Board Testing

Purpose

Use this skill to run a repeatable, safe workflow for testing firmware on a real PCB.

This skill is for physical board work: wiring, probe/debug interface setup, flashing, runtime checks, and test evidence capture.

When To Trigger

Trigger this skill when the user asks for any of the following:

• connect to a board for testing
• flash firmware to hardware
• use ST-Link/J-Link/CMSIS-DAP
• use OpenOCD/pyOCD/ST-LINK tools
• capture UART logs from real hardware
• run smoke tests on a real PCB

Operating Rules

• Ask for missing hardware facts before running board commands.
• Prefer deterministic command-line flows over GUI-only steps.
• Never assume voltage levels, pinout, or debug probe target settings.
• If uncertain about power or wiring safety, stop and ask for confirmation.
• Keep a short test log with exact commands and observed outputs.

Required Inputs

Collect these before execution:

1. Board identity: board name/revision and MCU part number.
2. Interface: SWD/JTAG/UART and probe type (ST-Link, J-Link, CMSIS-DAP).
3. Host tools: available utilities (openocd, st-flash, STM32_Programmer_CLI, pyocd, arm-none-eabi-gdb, serial tool).
4. Firmware artifact path (.elf, .bin, or .hex).
5. Power source and expected voltage.

If any item is missing, ask concise targeted questions and pause.

Workflow

1. Preflight

Run only read-only checks first:

• verify artifact exists
• detect host tools (command -v <tool>)
• list serial devices before board connection

Then ask the user to connect the board and repeat device listing to identify new ports.

2. Probe And Target Validation

• confirm probe can enumerate target
• verify target MCU ID matches user-provided part/family
• verify reset/connect mode if attach fails

If target detection fails, go to the troubleshooting section in references/troubleshooting.md.

3. Flash

• use the simplest tool already available in the environment
• flash exactly one artifact selected by the user
• verify write/verify result from tool output

Do not erase/program unrelated regions unless user explicitly requests it.

4. Runtime Smoke Test

Run a short deterministic test set:

• board boots after reset
• heartbeat or known periodic behavior observed
• UART banner/telemetry received (if available)
• one sensor read or loop tick check (project specific)

5. Evidence Capture

Save a concise report using templates/test-report.md including:

• hardware setup used
• flashed artifact hash/path
• exact commands run
• pass/fail outcomes
• next actions

Output Contract

Always return results in this structure:

1. Setup Summary
2. Commands Executed
3. Observed Results
4. Pass/Fail
5. Recommended Next Step

Safety Guardrails

• Never instruct potentially unsafe rework steps (jumpers/rewiring) without explicit board documentation.
• Never claim hardware pass based on assumptions.
• If hardware evidence is missing, mark status as Blocked and state what data is needed.

Repo-Specific Notes

For this repository (STM32-style training project):

• prefer artifacts from the current workspace build outputs
• align smoke tests with project behavior in Core/Src/main.cpp
• for sensor checks, follow documented expectations in specs/adt7410_minimal.md

Quick Example

User asks: "Help me flash and test this firmware on my STM32 board with ST-Link."

Expected behavior:

• collect missing board/probe/artifact/power details
• validate host tools and probe connectivity
• flash chosen artifact and verify success
• capture serial output or runtime heartbeat
• produce structured pass/fail report