> ## 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. # Rapid prototyping > Move from hardware context to working firmware with project setup, documentation-grounded implementation, and on-target verification. Use this workflow to turn a board, schematic, or part selection into a small firmware milestone that you can build and observe on the intended target. Embedder combines project hardware context, repository instructions, agent modes, and bench tools; you still choose the architecture and define what proves the prototype works. ## Define the first observable milestone Choose one behavior that exercises the smallest useful path through the hardware. A good milestone identifies: * the intended board and populated peripherals; * the interface, pins, and operating conditions; * the firmware behavior to implement; * the exact build configuration; * an observable pass condition, such as a UART line, GPIO waveform, sensor value, or current range. ```text theme={"system"} Bring up the BME280 on I2C1 using the pins routed in the active schematic. Read the chip ID, temperature, and pressure once per second. Build the debug image and verify "bme280: ready" plus three valid samples over UART. ``` Avoid starting with a broad request such as "bring up the board." A bounded milestone gives Embedder a finish line and makes failures easier to localize. ## Establish the hardware context Run: ```text theme={"system"} /project ``` Select the project associated with the workspace, or create one from a catalog platform, a custom platform, or a complete schematic source set. Choose the exact board or MCU from the project setup picker. The catalog available to your team is the source of truth. If the platform is not in the catalog, choose **Add a platform** when your account permits custom components, or create the project from [schematics](/core-concepts/schematics). Run `/peripheral` and attach the exact catalog parts fitted to the board. For an off-catalog part, add its PDF documentation as a custom peripheral when that feature is available. Adding a peripheral supplies identity and indexed documentation. It does not generate a driver, assign pins, or prove that the part is populated. When schematics are available, compare the active project components with the parsed design. Use references such as `@sch:component:U4`, `@sch:net:I2C1_SDA`, and `@sch:power_domain:VDD_IO` to attach the relevant connectivity to a prompt. Catalog recommendations and schematic part matches are useful starting evidence, not a verified bill of materials. Check the board revision, package, fitted option, power domain, and connector routing before implementation. ## Initialize the repository workflow Run `/init` after selecting the project: ```text theme={"system"} /init ``` Embedder inspects the repository, selected hardware, build files, tests, debugger configuration, connected equipment, and project rules. It asks you to verify target hardware, build and test commands, deployment, bench setup, and quality requirements before it creates or refreshes the managed section in `EMBEDDER.md`. The resulting guide should record: * the exact target, toolchain, build configuration, and artifact path; * test, flash, debug, and observation commands; * connected probes, serial settings, and bench constraints; * generated or vendored code boundaries; * the expected result and evidence status for each workflow. Discovery alone does not verify a command. A workflow is verified only when it ran successfully or when existing evidence was explicitly confirmed. `/init` does not flash hardware or install dependencies unless you approve that optional validation. ## Ground the implementation in the design Ask Embedder to inspect source, indexed component documents, and parsed schematics before it chooses registers or pins: ```text theme={"system"} Trace the current I2C initialization from @src/board.c through @drivers/i2c.c. Compare it with @sch:component:U4 and the selected MCU documentation. Report the required clock, pin alternate functions, bus speed limits, and unresolved assumptions. Do not edit code yet. ``` Use the evidence sources for different questions: | Question | Source | | ------------------------------------------------- | --------------------------------------------------- | | Which part and documentation apply? | Active project platform and peripherals | | How is the board wired? | Parsed schematic entities and board-specific skills | | Which registers, timing limits, and errata apply? | Indexed datasheets and reference manuals | | How does the current firmware work? | Repository source, build files, and tests | | Which commands and safety rules apply here? | Root `EMBEDDER.md` | If a required fact remains ambiguous, resolve it before implementation. Do not substitute documentation from a nearby MCU, board revision, or peripheral variant. ## Choose Plan or Act Use Plan mode when the prototype changes architecture, spans several modules, introduces a new driver boundary, or depends on unresolved hardware choices: ```text theme={"system"} /plan ``` ```text theme={"system"} Plan the smallest implementation that initializes the IMU, reads WHO_AM_I, and streams one acceleration sample per second. Compare the existing driver interfaces, selected part documentation, and schematic pins. Include targeted host tests, the build artifact, flash steps, and the on-board pass condition. ``` Plan mode can research code, documentation, schematics, diagnostics, and saved hardware output. It can modify only the session plan. Review the proposed files, hardware assumptions, failure handling, and verification sequence before approving it. Approval starts implementation in Act mode. For a small, fully specified change, start directly in Act mode: ```text theme={"system"} /act ``` ```text theme={"system"} Add the missing chip-ID read to @drivers/bme280.c using the existing I2C wrapper. Keep the public API unchanged, add the host test, run that test, and build the recorded debug target. Stop if the target or command is ambiguous. ``` ## Implement and verify in layers Treat each layer as separate evidence. A later success does not repair a missing earlier result. Add or run the focused unit test, simulator check, or static diagnostic that covers the changed code. Fix the first useful failure before broadening the test scope. Run the exact command recorded for the project. Confirm the configuration and identify the resulting ELF, HEX, or BIN artifact. ```text theme={"system"} Run the recorded BME280 unit test, then build the debug image. Report the commands, results, and artifact path. Do not flash if either command fails. ``` Check the board, MCU, probe or bridge, serial transport, and power state. Require an explicit choice when more than one target is connected. Use the dedicated flash workflow so target arbitration, programming verification, reset handling, and early serial capture apply. ```text theme={"system"} Flash the verified debug artifact to the selected board. Monitor UART and stop when "bme280: ready" appears. Report programming verification and the matching runtime line separately. ``` Verify the behavior at the layer that matters. Read serial or RTT output for a software-visible result. Use a logic analyzer, oscilloscope, power analyzer, or debugger when the pass condition depends on pins, timing, current, or target state. | Evidence | What it proves | | ----------------------------------------------- | --------------------------------------------------------- | | Targeted test passes | The covered software behavior matches the test | | Firmware build succeeds | The selected source and configuration produce an artifact | | Flasher verifies programming | That artifact was programmed to the intended target | | Post-flash UART or RTT marker appears | The programmed image reached the reported runtime state | | Logic, scope, power, or debugger result matches | The target exhibited the measured hardware behavior | ## Escalate a hardware failure to Debug Switch to Debug mode when source inspection, host tests, and ordinary serial output cannot explain the target: ```text theme={"system"} /debug ``` Debug mode adds managed GDB, hardware scripts, coverage, instruction trace, and instrument providers. Start with the least invasive observation and state what the investigation must preserve: ```text theme={"system"} The first SPI transfer times out after reset. Read buffered UART output, then attach without programming. Inspect the active frame and SPI status registers. Do not reset or reflash until the installed image has been identified. ``` Use `hardware_status` to confirm which probes and instruments are ready. A custom platform entry provides context; it does not create a new flasher, debugger backend, or instrument provider. ## Keep the prototype reproducible Before calling the milestone complete: 1. Record the exact build, test, flash, and observation workflows in `EMBEDDER.md`. 2. Keep the pin choice, board revision, and required jumpers with the project instructions. 3. Save reusable hardware checks under `.embedder/hardware/`. 4. Report which evidence was observed and which assumptions remain inferred. 5. Rerun the narrow pass condition from a clean build or known target state. Follow the project, plan, build, flash, and debug sequence in detail. Upload complete designs and reference parsed components, nets, and pins. Record verified commands, artifacts, equipment, and safety rules. Check catalog platforms, probes, transports, and instrument boundaries.