Skip to main content
Use this workflow to bring up a new board, a board revision, or a new peripheral one observable step at a time. First get a working build and a way to observe the target. Then confirm startup and connections, and verify the first peripheral transaction or output. Pick a small first milestone, such as a boot message, a device ID read, or a measured GPIO transition. Keep unrelated application changes out of that first check so a failure is easier to isolate.

​
Define the milestone

Tell Embedder the board revision, fitted parts, operating conditions, and the result that counts as success:
If the board has never booted, make a startup marker or a debug connection the first milestone. Move on to the peripheral after that works.

​
Prepare project context

  1. Run /project and select the project for this board. Check that its platform matches the board or its MCU.
  2. Run /peripheral and add the fitted components.
  3. Run /upload-schematics and add the board’s complete schematic set, including the power and connector sheets.
  4. Run /init. Check the build, flash, and monitoring commands it records in EMBEDDER.md.
Compare suggested parts with the actual board. A catalog match doesn’t confirm the populated variant or its wiring.

​
Check the hardware assumptions

Confirm the supply voltage, reset and boot configuration, clock source, and debug or logging connection. For the first peripheral, check its power sequence, bus pins, pull-ups, chip select or address straps, and any enable signal against the populated board.
Replace the part and U4 with the fitted device and its reference designator in your design. When the work involves architectural choices, run /plan first. Review the plan, then approve it so Embedder implements the smallest working path in Act mode. In VS Code, select Approve & Execute on the plan card.

​
Establish a startup baseline

Build the smallest suitable application from the project’s existing SDK or board support. Confirm the firmware file and the target before flashing. Then capture a known boot marker over UART, RTT, or another connection the board supports.
If no marker appears, check power, reset, clocks, output routing, and the capture settings before you add peripheral code. Connecting can change what the target is doing. Opening a UART asserts DTR and RTS, which can reset a board that wires those lines to reset or boot pins. A new debugger connection can program or reset the target. When a failed run is evidence, read the output you already have before you reconnect, and follow the connection’s guide.

​
Build, flash, and observe

Once the board starts reliably, initialize one peripheral. Perform the smallest transaction that proves communication, such as a documented ID or status read, before you enable a larger workload. Ask Embedder to stop if the build fails, to flash only the confirmed board, and to capture output with a timeout:
Check that the values are plausible for the test conditions. A successful flash without the expected behavior is not a completed bring-up. To graph numeric output as it arrives, run /plot in VS Code or open a Plot tab in the Monitor. See Live plots for the line format the plot reads.

​
Diagnose before expanding

Start with the observation that can tell the most likely causes apart: For a missing bus response, first check whether the expected pins toggle. If they do, inspect the address or chip-select timing and the acknowledgment. If they don’t, inspect initialization, clocks, and pin configuration. Repeat the same bounded check after each change. Preserve a fault before you reset the board. See Monitor and debug.

​
Make bring-up repeatable

Save the working setup in EMBEDDER.md, and ask Embedder to save the check as a hardware script under .embedder/hardware/. Record the board revision, firmware file, wiring, expected output, and any manual reset or power steps. Re-run the check from the intended startup condition before you add the next peripheral or feature. Ask Embedder to run it in Act or Debug mode, open the script in VS Code and run Embedder: Run Hardware Script, or run embedder script <name>.py in a terminal at the project root. Each run reports pass or fail with the script’s summary. When the first transaction works, continue with Driver development to build the full interface, error handling, and regression checks.
Last modified on October 13, 2026