Hardware scripts

Use a hardware script for a repeatable check, a sequence of instrument actions, or a long measurement. Ask Embedder to create the Python script under .embedder/hardware/ and define what counts as success.

Create a boot check that reads UART at 115200 baud for up to 10 seconds and
passes only if it sees READY. Do not reset or flash the target.

Run a script

You can run a saved script in three ways:

Ask Embedder in Act or Debug mode.
Open it in VS Code and choose Embedder: Run Hardware Script.
Use the terminal command from the project directory:

embedder script boot_check.py --json

The path is relative to .embedder/hardware/. Use Embedder: Stop Hardware Script, the chat task controls, or Ctrl+C in the terminal to stop a run. Use Embedder’s runner for scripts that rely on its instrument helpers. Running those files with plain python does not supply the same helpers and setup.

Run a script from the editor

In VS Code, a run button (▷) appears in the editor title bar and right-click menu for any Python file in the workspace. Choose it to start the script without writing a chat message. A run row appears at the bottom of the chat with three choices:

Run executes the script and keeps the result out of the conversation. A Hand to agent button on the finished row sends the result later if you change your mind.
Run and hand to agent executes the script and delivers the result to the agent when the run finishes.
Cancel removes the row without touching hardware.

Output streams to the run row and to the Debug tab of the Embedder Monitor. While a script runs, the title-bar button becomes a stop control, and only one editor-started script can run at a time. Editor-started runs never install Python packages. When runtime preparation needs one, the run fails and tells you to approve the install from chat or from embedder script in a terminal.

A simple UART check

Replace the port with the intended target’s port:

.embedder/hardware/boot_check.py

import asyncio
import json

async def main():
    lines = await serial_read(
        "/dev/ttyUSB0",
        timeout_seconds=10,
        baud_rate=115200,
        stop_string="READY",
    )
    ready = any("READY" in line for line in lines)
    print(json.dumps({
        "success": ready,
        "summary": "READY observed" if ready else "READY not observed",
        "data": {"lines": lines},
    }))

asyncio.run(main())

The final JSON result should state success and a short summary, with useful observations alongside it. Keep captures and test results tied to the script and firmware revision that produced them.

Supply a capture profile

For settings that change between runs, use capture_profile in the script and a companion file such as boot_check.profile.json. The CLI and editor use the companion profile automatically. An agent-started run uses the profile supplied with that run instead. Without a profile, capture_profile is an empty dict; use defaults for optional settings. You can override it at launch:

embedder script boot_check.py --profile @profiles/bench.json --timeout 120000

The profile must contain a JSON object, and the script must read the fields you supply. The timeout is in milliseconds. Complete first-use dependency setup in an interactive terminal before relying on unattended runs. See CLI reference for all options.

Use instrument helpers

Choose the tool first, then use its guide for dependencies, channel numbering, and supported operations:

Debuggers: J-Link, OpenOCD, TI CCS, XMOS xgdb, and AURIX/TriCore over TCF.
Serial: UART, RTT, ITM/SWO, and xSCOPE.
Instruments: Saleae, Digilent, PicoScope, Siglent, PPK2, and Joulescope.
Other hardware workflows: Bluetooth LE, J-Trace, and XMOS xsim.

Several instruments share la_* or scope_* helper names. Available triggers, decoders, capture modes, and output controls still depend on the selected tool. A script written for one instrument may need changes for another. Use run_tool(["probe-rs", "list"]) in a script when a command must run on the selected hardware host, including a bridge. Name the target explicitly before any programming or control action. For generated waveforms, supplies, BLE connections, and similar resources, include cleanup even when a test fails.

Watch a live capture preview

Instrument captures show a live preview in the Monitor’s Power, Logic, or Oscilloscope tab while the script runs. A script chip and a Live or Ended pill replace the tab’s setup and transport controls. The preview observes the script’s acquisition; it does not open a second USB connection or take another hardware lease. Closing the preview does not stop the script; use the script’s stop control to end acquisition. Previews are built in for joulescope_measure, ppk2_measure and manual PPK2 start/read/stop captures, and Saleae timed or manual logic captures. Power previews update five times per second, and the view retains the most recent 4,000 preview points. A stopped preview stays visible until you dismiss it with New capture. Other providers can publish preview points while acquiring:

embedder_publish_capture_preview(
    capture_id="spi-test-1",  # Use a new ID for every acquisition.
    name="SPI capture",
    kind="logic",  # power, logic, or oscilloscope
    points=[
        {"channel": "CLK", "timestamp": 0, "value": 0},
        {"channel": "CLK", "timestamp": 1, "value": 1},
    ],
    sample_count=2,
    elapsed_sec=0.001,
)

Timestamps are milliseconds from acquisition start. Send bounded batches and pass state="stopped" with the final update. A preview never saves a capture; use the provider’s normal capture publication helper for that.

Keep a hardware case

For an investigation with several probes, keep related files together:

.embedder/hardware/cases/i2c-nack/
  CASE.md
  capture_bus.py
  inspect_pins.py

Ask Embedder to record the symptom, board revision, hypotheses, findings, next check, and paths to evidence in CASE.md. Update existing scripts when the test changes so it remains clear which version produced a result.

Run longer checks

Ask for a background run when you need a soak test or long capture. Follow its status in the task view and stop it when the test is complete. An active hardware workflow can make another session wait. Check /hardware-queue before starting a conflicting operation, and release the equipment when the run finishes.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

Run a script

Run a script from the editor

A simple UART check

Supply a capture profile

Use instrument helpers

Watch a live capture preview

Keep a hardware case

Run longer checks

​Run a script

​Run a script from the editor

​A simple UART check

​Supply a capture profile

​Use instrument helpers

​Watch a live capture preview

​Keep a hardware case

​Run longer checks

Run a script

Run a script from the editor

A simple UART check

Supply a capture profile

Use instrument helpers

Watch a live capture preview

Keep a hardware case

Run longer checks