Provides tools for interacting with NVIDIA Jetson target boards via hardware-in-the-loop automation, including hardware reset and power sequencing, entering NVIDIA Force Recovery mode, rebooting to bootloader, automated Linux shell login, and retrieving network and system telemetry.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ae-hw-bridge reboot the target board and wait for the login prompt"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hardware-in-the-Loop (HIL) automation gateway and FastMCP server for the Agents Engine (ae) ecosystem.
ae-hw-bridge provides AI agents (Agents Engine, Claude, Gemini, Cursor) with a safe, programmable, tool-based interface to interact with physical development boards (DUTs) via the Model Context Protocol (MCP).
It pairs with the hw-puppet Dual-CDC USB bridge. Precompiled firmware binaries are available on the hw-puppet Releases page.
[ AI Agent / Claude / Cursor ] [ Human Developer (Terminal) ]
│ │
│ stdio / SSE (MCP JSON-RPC) │ Virtual PTY (/tmp/ae-hw-bridge-uart)
▼ ▼
[ FastMCP Server ] [ tio / picocom / ae-hw-bridge console ]
│ │
│ Scoped Unix Domain Sockets │
└───────────────────┬────────────────────┘
▼
[ ae-hw-bridge Daemon ]
├─ Bounded Circular Log Buffer (collections.deque)
├─ Virtual Pseudoterminal Mirror (Master/Slave PTY)
├─ Target Domain Logic (.ae-hw-bridge/targets/)
│
├─── CDC 0: MicroPython Raw REPL (/dev/ttyACM* or sysfs-paired) ──┐
└─── CDC 1: Target UART Console (/dev/ttyACM* or sysfs-paired) ──┐│
││ (USB Full-Speed)
▼▼
[ hw-puppet (ESP32-S3) ]
(Firmware & HIL Adapter)
│ │
(Control lines) (TX/RX UART)
▼ ▼
[ Target Dev Board ]
(NVIDIA Jetson, Pi, STM32)Separation of Concerns: Low-level hardware drivers and USB descriptors live in hw-puppet, while high-level orchestration, IPC multiplexing, and MCP tools live in ae-hw-bridge.
Zero Host Contention & Virtual PTY: An auto-spawning, target-scoped daemon (ae-hw-bridge-daemon) manages exclusive access to physical serial devices and exposes a virtual pseudoterminal symlink (/tmp/ae-hw-bridge-uart). Developers can watch UART logs live (via tio, minicom, or ae-hw-bridge console) concurrently with AI agents running tasks without port collision (Device or resource busy).
Multi-Target & Multi-Puppet: Safely binds multiple physical boards via hardware badges (stored in ESP32-S3 NVS) and Linux sysfs USB pairing without serial port number guessing or symlink collisions.
Agent Safety: Internal @repl methods are filtered out from MCP exposure; agents interact strictly through vetted, high-level business tools (full_reboot, login, send_target_command, wait_for_console_pattern, etc.).
Dynamic Target Loading: Target behavior (pin definitions, boot sequences, login credentials) is defined modularly under .ae-hw-bridge/targets/<target_name>/target.py or .ae-hw-bridge/config.yml.
Related MCP server: mcp-micropython-bridge
Tools exposed to AI agents adhere to a strict and predictable prefix convention:
When target modules are configured (e.g. jetson, stm32), all tools are strictly prefixed with <target>_:
jetson_read_target_console
jetson_send_target_command
jetson_full_reboot, jetson_enter_recovery
stm32_read_target_console, stm32_flash_firmware
This guarantees consistent agent tool contracts regardless of whether a project has 1 or N targets.
In clean bench mode (no targets defined, single BaseTarget), tools carry no prefix:
read_target_console
send_target_command
clear_target_console
MCP Tool | Description |
| Software version, connected ESP32-S3 |
| Read lines from circular console buffer (passive UART reception). |
| Send interactive shell command to target UART and capture delta response. |
| Wait for regex pattern on console stream (e.g. login prompt, bootloader). |
| Clear the background circular console buffer. |
| Execute custom MicroPython script in ESP32-S3 RAM via raw REPL (zero flash wear). |
Custom Target Tools | Any public method declared in |
.ae-hw-bridge/config.yml)You can configure hardware mappings in .ae-hw-bridge/config.yml:
# Match connected board by persistent hardware badge:
puppet: jetson
# Or bind directly by port:
# port: /dev/ttyACM1targets:
jetson:
puppet: jetson-desk # Matches HW-Puppet with badge "jetson-desk"
stm32:
puppet: stm32-bench # Matches HW-Puppet with badge "stm32-bench"
port: /dev/ttyACM5 # Or explicit portFail-Safe Ambiguity Protection:
If multiple HW-Puppet boards are plugged into your machine and no configuration or explicit port is provided, ae-hw-bridge safely halts with an informative error rather than guessing a port randomly.
ae-hw-bridge provides built-in CLI commands for managing hardware test benches and viewing UART logs without serial port contention:
# Connect to live target UART console (interactive terminal session via tio / picocom / built-in)
ae-hw-bridge console
# Inspect recent UART console logs (non-interactive, exit immediately)
ae-hw-bridge console -n 50
# Continuously follow live console logs
ae-hw-bridge console -f
# Filter and pipe live output into standard Unix tools
ae-hw-bridge console | grep "ERROR"
ae-hw-bridge console -n 100 --grep "kernel"
# External terminal access (works simultaneously with AI agents!):
# Use your favorite terminal tool directly via the virtual PTY symlink:
tio /tmp/ae-hw-bridge-uart
picocom -b 115200 /tmp/ae-hw-bridge-uart
# View daemon status, connected MCP clients, physical ports, and virtual PTY
ae-hw-bridge status
# Stop background daemons and release serial ports
ae-hw-bridge stop
ae-hw-bridge stop --all
# List all connected HW-Puppet devices, serial numbers, badges, and configured targets
ae-hw-bridge list
# Set a persistent hardware badge in ESP32-S3 NVS
ae-hw-bridge label jetson-bench
ae-hw-bridge label stm32-bench --port /dev/ttyACM1
# Explore and execute target actions directly from Bash
ae-hw-bridge actions [-t <target>]
ae-hw-bridge call reset [-t <target>]
ae-hw-bridge send "uname -a" [-t <target>]
ae-hw-bridge exec "print('MicroPython alive')" [-t <target>]
# Run the FastMCP server
ae-hw-bridgeFor a quick reference of all commands, see the Cheat Sheet.
For full command-line usage and daemon management, see the CLI Reference Guide.
For in-depth architectural details, virtual PTY sharing, and external terminal setup (tio, minicom), see the Virtual UART Console Guide.
Linux (with udev support)
Python 3.10+
A connected hw-puppet (ESP32-S3) device
Install automatically to your preferred AI assistant using the Smithery CLI:
# Claude Desktop / Claude Code
npx -y @smithery/cli install ae-hw-bridge --client claude
# Cursor
npx -y @smithery/cli install ae-hw-bridge --client cursorRun the MCP server directly using uvx without installing into your local Python environment:
uvx ae-hw-bridgepip install ae-hw-bridge
# Or editable mode for development:
pip install -e .Install the provided udev rules to enable non-root access for all HW-Puppet CDC devices:
sudo cp udev/99-hw-puppet.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm triggerclaude mcp add ae-hw-bridge uvx ae-hw-bridgeclaude_desktop_config.json) / Cursor (~/.cursor/mcp.json){
"mcpServers": {
"ae-hw-bridge": {
"command": "uvx",
"args": ["ae-hw-bridge"]
}
}
}Target dev boards (DUTs) are configured modularly in .ae-hw-bridge/targets/<target_name>/.
Complete Target Guide & Examples:
See the in-depth Target Development Guide (docs/target_development.md) for architecture details, @repl execution rules, and ready-to-use recipes for ESP32, STM32, and Linux SBCs.
See the NVIDIA Jetson Reference Target (examples/targets/jetson/README.md) and its implementation (target.py).
For AI assistants and agents, see llms.txt.
# .ae-hw-bridge/targets/jetson/target.py
from typing import Any
from ae_hw_bridge.targets.base import BaseTarget, repl
class JetsonTarget(BaseTarget):
PIN_RST: int = 12
@repl
def reset_pulse(self, pin: int = 12):
"""MicroPython code executed directly in HW-Puppet RAM (hidden from MCP)."""
import time
from machine import Pin # MicroPython imports MUST be inside @repl!
rst = Pin(pin, Pin.OUT, value=1)
rst.value(0)
time.sleep(0.2)
rst.value(1)
def full_reboot(self, timeout: float = 30.0) -> dict[str, Any]:
"""High-level target operation automatically registered as an MCP tool."""
self.clear_target_console()
self.reset_pulse(pin=self.PIN_RST)
res = self.wait_for_console_pattern(r"login:", timeout=timeout)
return {"booted": res.get("matched", False), "line": res.get("line")}pytest55 unit and integration tests covering the console reader, raw REPL client, IPC protocol, daemon server/client, target loader, sysfs discovery, YAML/JSON configuration, and MCP tool registration.
Clear the target UART console circular buffer.
Recommended before triggering a reset or running a test scenario to isolate fresh output.
Inputs: no named parameters. Returns: object
Get bridge software version, connected hardware puppet firmware info, and active ports.
Returns metadata including ae-hw-bridge package version, ESP32-S3 hw-puppet firmware build details (version, platform, git hash), and serial port paths.
Inputs: no named parameters. Returns: object
Read lines from the target board UART console buffer (CDC1).
NOTE: This reads the passive UART reception ring buffer (e.g. bootloader or kernel output).
To read system logs from an already running Linux target, use send_target_command.
Args: tail_lines: Number of most recent lines from the end of the buffer (default: 50 if head_lines not specified). head_lines: Number of earliest lines from the start of the buffer (e.g. first N lines of bootloader after reset). grep: Optional case-insensitive regex pattern to filter lines (e.g. 'panic|error|SafeRTOS').
Inputs: grep, head_lines, tail_lines. Returns: result
Execute arbitrary MicroPython code directly in ESP32 RAM via CDC0 Raw REPL.
Args: code: MicroPython source code string to execute. timeout: Maximum execution time in seconds before aborting (default: 10.0s).
Inputs: code (required), timeout. Returns: object
Send an interactive command string to the target console and collect ONLY new response lines.
Args: command: Shell command string to transmit to target UART (e.g. 'uname -a' or 'nvidia'). wait_timeout: Maximum seconds to wait before returning response (default: 5.0s hard ceiling). idle_threshold: Seconds of UART silence before considering output complete (default: 0.3s).
Inputs: command (required), wait_timeout, idle_threshold. Returns: result
Wait for a line matching regex pattern in target UART console stream.
First checks recent buffer history (unless check_history=False). If not found, blocks until matching line appears or timeout expires. Ideal for waiting for bootloader, kernel messages, login prompts or errors after reset.
Args: pattern: Regular expression to match (e.g. 'login:', r'(?:[$#]\s*$|\w+@\w+:.[$#]\s)', or 'kernel panic'). timeout: Maximum seconds to wait (default: 30.0s). check_history: If True, inspect recent buffered lines first before waiting for new lines (default: True).
Inputs: pattern (required), timeout, check_history. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Tools mostly target distinct actions: clearing buffer, reading buffer, sending commands, waiting for patterns, executing MicroPython, and fetching bridge info. The three console-related tools (read, send, wait) have some inherent overlap but descriptions clarify when to use each, preventing most misselection.
All tool names use consistent snake_case with a verb_object pattern (clear_target_console, get_bridge_info, read_target_console, run_custom_code, send_target_command, wait_for_console_pattern). No deviations in style.
Six tools is well-scoped for a hardware bridge server; each tool covers a necessary operation (buffer management, info retrieval, console I/O, code execution, pattern waiting) without redundancy.
The surface covers core interactions: buffer clear/read, command send, pattern wait, code execution, and bridge info. An explicit reset tool is absent despite being mentioned in clear_target_console's description, but resets may be achievable via send_target_command or run_custom_code, leaving only a minor gap.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
