> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded development workflows

> Take a firmware change from project setup through build, flash, and hardware verification.

Start with a selected project and the commands recorded in `EMBEDDER.md`. Treat implementation, build, programming, and runtime behavior as separate checks.

## Set up the project

Run `/project` to select or create a project. Choose the target platform, review fitted peripherals with `/peripheral`, and add schematics when you need board connections.

Run `/init` and confirm the detected commands and hardware. See [Quickstart](/quickstart) for the full setup flow.

## Plan an uncertain change

Run `/plan`, then describe the behavior and constraints:

```text theme={"system"}
Plan a DMA-based UART receiver. Trace the existing parser and buffer ownership,
check the MCU constraints, and propose tests for overflow and partial frames.
```

Review affected files, assumptions, error handling, and verification. Approve the plan to start implementation in Act mode.

For a focused fix, use Act directly:

```text theme={"system"}
In @drivers/uart.c, return UART_TIMEOUT when the receive deadline expires.
Keep the public header unchanged, add the missing test case, and run UART tests.
```

## Build and test

```text theme={"system"}
Run the recorded host tests, then build the debug image for the selected board.
Stop on failure. On success, report the build configuration and artifact path.
```

Check that the output belongs to the current build. Resolve the first useful error before continuing to hardware.

## Flash and observe

Identify the board, probe or bridge, power setup, and serial connection. Then ask:

```text theme={"system"}
Flash the verified debug image to the selected development board. Capture boot
output and wait up to 15 seconds for "self-test: pass". Report programming
verification and the observed boot result separately.
```

Use history when the message may already be captured. Use live monitoring when you need to wait for it. An open Monitor tab alone does not establish that the expected message appeared.

## Investigate a failure

Use `/debug` for GDB state inspection or bounded instruction and coverage captures. Begin with existing output and preserve the target when its current state matters.

```text theme={"system"}
The board reset during the first SPI transfer. Read UART history and inspect
the reset reason. Do not reflash or reset it before collecting the current state.
```

For electrical or timing questions, request a bounded instrument capture with channel assignments and an expected result. Use [hardware scripts](/debug-mode/hardware-scripts) to repeat the check.

## Review the outcome

Ask for the changed behavior, files, checks run, and any unresolved limits. A build proves compilation; a flash verifies programming; the runtime test establishes the requested board behavior.

Keep reusable commands in [EMBEDDER.md](/core-concepts/embedder-md) and confirmed constraints in [project memory](/core-concepts/memory).

## Continue or change direction

Send a follow-up in the same conversation for related work. During a run it steers the active turn at the next step boundary. Messages not yet absorbed wait in the queue; review or remove obsolete queued messages before switching tasks.

Use `/btw` for a side question and `/new` in VS Code for unrelated work. See [Sessions and context](/core-concepts/sessions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.