Skip to content

Best Practices

The single biggest performance lever in AI-assisted firmware development is session focus. Hydron's accuracy degrades as a conversation accumulates too many file reads, tool outputs, and aborted attempts.

1. Help Hydron verify its work

Pair every implementation prompt with a concrete check Hydron can run.

When success criteria are vague, Hydron produces code that compiles and looks plausible but silently misses behavior. With a command it can run, it iterates against the compiler instead of waiting for your review.

Before: "Add SPI register read support to the DRV8316 driver"

After: "In src/drivers/drv8316/drv8316.cpp, add a readRegister(addr) that returns the 16-bit SPI frame. Verify against the DRV8316 datasource: writing 0x03 (Control_1) with REG_LOCK=0x3 then reading back should yield REG_LOCK=0x3. Add a sketch under examples/drivers/drv8316/ that prints all status registers and exits. Build with arduino-cli compile --fqbn arduino:samd:nano_33_iot."

Always name the target board. Without it, Hydron may pick a default architecture and you will miss platform-specific breakage like ARM vs AVR differences.

2. Explore, plan, then code

For anything spanning more than one file, ask Hydron to plan before it writes. Letting it jump straight to code on a multi-file change often produces a partial implementation in one file and a stub in the next.

Use this three-step sequence:

  1. Ask mode — Explore: "Read src/drivers/drv8316/{drv8316.cpp,drv8316.h}. How is the SPI bus owned? How are register reads/writes framed? No code yet."
  2. Plan mode: "I want to add a DRV8323 driver following the same pattern. List every file to create, the public API surface, and the registers to expose for v1. No code yet."
  3. Code mode — Implement: "Implement the plan. Match the DRV8316 init/config/read style exactly. Build all DRV8316 example sketches after to confirm nothing in shared code broke."

Skip the plan step for trivial work like renaming fields or fixing typos. Planning short tasks adds latency without changing the outcome.

3. Prompt like a code review comment

The more your prompt resembles a strict code review comment, the better. Hydron infers intent well, but inference compounds error.

Patterns that work:

  • Scope by file: "In src/drivers/drv8316/drv8316.cpp..."
  • Trigger datasource lookup: Use keywords like "query documents" or "reference the H2Loop project" to pull from your attached datasources. Hydron does not always route to them unless the prompt explicitly triggers it.
  • Reference existing patterns: "Look at src/drivers/tmc6200/ for layout. Scaffold src/drivers/tmc6300/ matching that file split. No new abstractions."
  • Describe the symptom: "On STM32G4, drv8316.readStatus() returns 0xFFFF after ~30s of operation. Likely SPI clock or CS timing. Reproduce with the standalone example, instrument the CS pin, fix root cause."

4. Attach your datasheets

Datasheets are the single biggest accuracy multiplier on firmware projects. Attach the datasheet for every chip your project drives via the Project Dashboard.

When you prompt Hydron to cross-reference a driver against its datasheet, it can produce a complete register coverage table in one shot.

  • Attach errata sheets separately. They often contradict the main datasheet on edge cases.
  • Re-attach when the vendor publishes a new revision. Old datasources do not auto-update.
  • Make sure your Hydron project is selected in the CLI or VS Code before prompting. Datasources are scoped to the active project.
  • Use trigger keywords in your prompts. Hydron routes to datasource lookup when it sees words like query, refer to, look up, or H2Loop project. Without them, Hydron may answer from training data instead of your attached docs.

5. Use mentions to anchor context

Hydron auto-discovers files with built-in search tools, but explicit @-mentions give you tight control over what the AI sees.

  • Feed it reality. Don't manually copy-paste crash logs. Use @terminal to pass failed build output directly to the chat.
  • Trust the discovery tools. For sweeping architectural tasks ("Find everywhere we use blocking delays in ISRs"), just ask. Let Hydron use its internal grep instead of manually tagging every header file.
  • Keep relevant files open. In VS Code, Hydron passes your active editor tabs as passive context. Keep your working files open to silently steer the agent's focus.

For the full mention reference, see Context & Mentions in the VS Code extension docs.

6. Manage your session

Course-correct early. Pressing Esc interrupts generation but preserves context. Stop early and redirect. The cost of letting Hydron finish a wrong path is that its flawed reasoning stays in the context window and influences the next attempt.

Start fresh when stuck. If you have corrected Hydron more than twice on the same point, use /new. A clean session with a sharper prompt beats a long session full of corrections.

One session, one scope. Do not continue a session across unrelated tasks.

Use Ask mode for exploration. "Read all encoder drivers and tell me which implement SimpleFOCRegisters" should run in Ask mode. Otherwise you burn half your context window on file reads before writing a single line of code. Ask mode returns a summary; your main session stays clean.