Firmware Notes

Firmware notes turn a saved design and cited device documents into a handoff for the person or coding tool that will implement the firmware. They record requirements, pin maps, interface setup, boot/reset assumptions, and expected bring-up observations.

Before You Start

Open the intended saved project. Identify the programmable target, exact part/package, board, and variant. Provide the real product requirements and relevant datasheet, reference manual, module guide, and errata. A sensor with an I2C interface is not itself a target that runs your firmware.

For a multi-board unit, identify each board and confirm which connectors mate. Equal net names on separate boards do not establish an interconnect.

Request a Handoff

1. In Agent, ask for notes for the intended target and scope.
2. Let Trace inspect the schematic hierarchy, target pins, and actual connections. Where a PCB exists, compare its pads and nets with the schematic.
3. Answer material questions about the intended software behavior, module operating mode, chosen interfaces, or missing document sources.
4. Review the written notes and the final Firmware notes review summary: changed files, corrections made during review, likely hardware errors, and remaining open questions.
5. Resolve or explicitly carry those questions into the handoff; do not treat the notes as verified firmware.

Prepare firmware handoff notes for this saved controller board.
Use my confirmed requirements and the exact MCU package.
Check the pin map, SPI device connections, boot/reset, and ADC inputs.
Cite the device documents and keep unknowns as open questions.
Do not implement or flash firmware, or rewire CAD to match the notes.

To maintain notes during later design work, turn Firmware handoff notes On in AI Workflows. Off still permits an explicit request. In Ask, request explanation or review without writing notes.

Find and Edit the Notes

Notes are plain Markdown under .trace/firmware/ in the project folder. Typical files are:

• README.md: scope, boards/targets, last update, and open-question count.
• requirements.md: confirmed software-facing requirements.
• hardware.md: pin map, buses, power/reset/boot, programming access, and unresolved facts.
• bring-up.md: ordered checks and expected observations, not measured results.
• interconnect.md: confirmed links in a multi-board unit, when needed.
• devices/ and examples/: detailed setup notes and short illustrative snippets when useful.

Only files with relevant content need to exist. The top-level design notebook, .trace/context.md, remains the source for overall product intent.

In the chat's Workflows panel, use the firmware row's Editor selection and Open. Available choices can include VS Code, Cursor, Windsurf, and the system file manager. Opening can create the folder and a starter README; it does not generate a complete handoff.

You can edit the notes yourself. Ask later updates to preserve your decisions and unrelated sections.

Review Before Implementation

Check the handoff against the saved design and original documents:

• Keep library pin names/numbers, package pins or balls, GPIO names, alternate functions, nets, and PCB pads distinct.
• Check bus functions end to end, including transmit/receive direction, chip selects, pull-ups, addresses, and voltage domains.
• Cite register values, timing, reset polarity, boot straps, and programming pinouts to the exact document revision and section/page.
• Separate user requirements from proposals. Mark unknown SDK calls or device settings rather than inventing them.
• For analog inputs, state the topology, units, nominal equations, tolerances, loading, reference, and validity limits.
• Keep ERC errors, ambiguous rails, and conflicting pins visible as open questions. Without a PCB check, identify the map as schematic-only.

A bring-up checklist predicts what should be observed. It does not establish safe physical access, actual wiring, or permission to carry out an action.

Export or Share a Reviewed Copy

Under the firmware row, choose Export…, then select a destination outside the notes folder. Use Compress to ZIP for an archive or leave it unchecked for a folder.

Include cited datasheets copies available local files cited from the project's artifact folders. A URL alone does not ensure a document is included. The export also includes the existing design notebook when available. Wait for the reported export result, then inspect the folder or ZIP for the expected notes and references before handing it over.

In the notes, mark a project-relative file for inclusion with local: artifacts/device.pdf (using its actual filename). Ordinary Markdown links alone are not collected by this option. Keep the source revision and page/section citation alongside that local reference, and confirm the file exists before export.

Native Workspaces can include .trace/firmware/ as shared project content, subject to the project's inclusion rules. The automatic workflow preference itself stays local. Review Changes, then Commit and Push deliberately; exporting a copy does not publish it. Trace Plugin notes remain project files—share them through your project's normal reviewed file workflow.

If Notes or Export Are Incomplete

Save/open the correct project if the controls are unavailable. If an editor cannot launch, select the system file manager. For missing citations, save the intended reference locally and update its citation; do not claim the export contains a remote-only document.

If notes disagree with CAD, report both versions and the next check. Do not silently alter the circuit to make the notes true. After an uncertain export, check the destination before retrying, and keep the original project notes.