HARDWARIO Real Time Transfer Terminal Console

Overview

HARDWARIO Real Time Transfer Terminal Console (rttt) is a Python package that provides an interface for real-time data transfer using SEGGER J-Link RTT (Real-Time Transfer) technology. It enables efficient data communication between an embedded system and a host computer via RTT channels.

This package is particularly useful for debugging, logging, and real-time data visualization in embedded applications.

Features

• Real-time communication with embedded devices via RTT.
• Support for multiple RTT buffers (console and logger).
• Adjustable latency for optimized readout.
• J-Link support with configurable serial numbers, device types, and speeds.
• Command-line interface (CLI) for quick and easy access.
• Easy installation via PyPI.

Installation

To install the package, use:

pip install rttt

To verify the installation, run:

rttt --help

Usage

Basic Command

To start the RTT console:

rttt --device <DEVICE_NAME>

Available Options

Usage: rttt [OPTIONS]

  HARDWARIO Real Time Transfer Terminal Console.

Options:
  --version                  Show the version and exit.
  --serial SERIAL_NUMBER     J-Link serial number.
  --device DEVICE            J-Link Device name.
  --speed SPEED              J-Link clock speed in kHz. [default: 2000]
  --reset                    Reset application firmware.
  --flash-cmd COMMAND        External command used by the flash operation
                             instead of the built-in J-Link programming.
                             Must contain the {file} placeholder.
  --address ADDRESS          RTT block address.
  --terminal-buffer INTEGER  RTT Terminal buffer index. [default: 0]
  --logger-buffer INTEGER    RTT Logger buffer index. [default: 1]
  --latency INTEGER          Latency for RTT readout in ms. [default: 50]
  --history-file PATH        Path to history file. [default: ~/.rttt_history]
  --console-file PATH        Path to console file. [default: ~/.rttt_console]
  --mcp / --no-mcp           Enable MCP server. [default: no-mcp]
  --mcp-listen TEXT          MCP server listen address [host:]port. [default: 127.0.0.1:8090]
  --mcp-token TOKEN          Require "Authorization: Bearer TOKEN" on the MCP
                             server and upload endpoint.
  --substitutions / --no-substitutions
                             Enable template substitutions in terminal input.
                             [default: substitutions]
  --trust-shells             Trust shell substitutions in config without
                             interactive prompt (for CI/scripts).
  --headless                 Run without the interactive console, MCP server
                             only (requires --mcp).
  --help                     Show this message and exit.

Examples

Connect to a device (replace NRF52840_xxAA with your actual device name):

rttt --device NRF52840_xxAA

Use a specific J-Link serial number:

rttt --device NRF52840_xxAA --serial 123456789

Configuration File

RTTT supports configuration via .rttt.yaml files. All existing files are loaded and deep-merged, so you can keep user-wide defaults in your home directory and override specific keys per project. The load order, from lowest to highest priority, is:

1. ~/.config/rttt.yaml — user defaults
2. ~/.rttt.yaml — user defaults (alternative location)
3. ./.rttt.yaml — project-specific overrides
4. RTTT_* environment variables
5. Command-line flags

Nested mappings (like substitutions:) merge per-key — a project config can add new substitutions without losing the ones defined in your home config, or override specific ones by name.

Example Configuration:

device: NRF9151_XXCA
console_file: "test.log"
substitutions:
  RTC_SET: "rtc set {{UTC_NOW}}"

With this configuration, simply running:

rttt

Input Substitutions

RTTT can expand {{NAME}} placeholders in commands you type in the terminal before they are sent to the device. This is handy for things like setting the current time on the device without typing it manually:

rtc set {{UTC_NOW}}

gets expanded to (example):

rtc set 2026/04/20 10:08:00

Built-in Substitutions

Placeholder names must be upper-case letters, digits, and underscores, and start with a letter or underscore.

Custom Substitutions

Define your own values in .rttt.yaml under the substitutions key. Values are strings and may reference other substitutions (built-in or custom):

substitutions:
  RTC_SET: "rtc set {{UTC_NOW}}"
  PROJECT: "nrf9151-demo"
  HEADER: "DEV={{PROJECT}} T={{UTC_NOW}}"

Then typing {{RTC_SET}} in the terminal sends e.g. rtc set 2026/04/20 10:08:00 to the device.

Custom names take precedence over built-ins, so you can override UTC_NOW with a fixed value if needed.

Multi-Line Substitutions

A substitution value may contain newlines. When the expanded text spans multiple lines, each line is sent as a separate input event to the device. This is useful for grouping a batch of commands under a single placeholder:

substitutions:
  CONFIG: |
    app config interval-sample 60
    app config interval-aggreg 300
    app config interval-report 1800
    {{RTC_SET}}

Typing {{CONFIG}} sends all five commands in order. Nested placeholders (like {{RTC_SET}} above) are expanded recursively before the fan-out.

Shell Substitutions

A substitution value can also be a shell command, evaluated lazily each time the placeholder is expanded:

substitutions:
  GIT_SHA:
    shell: "git rev-parse --short HEAD"
  BUILD_HEADER: "build={{GIT_SHA}} at {{UTC_NOW}}"

Options for a shell: entry:

Commands have a 5 second timeout. On failure (non-zero exit, timeout, or missing binary), the placeholder is left in the text and a warning is logged.

Trust prompt. Because a .rttt.yaml in a project you didn't write could run commands on your machine, rttt asks for confirmation the first time it sees a new set of shell substitutions. The approval is cached in ~/.hardwario/rttt_allowed_shells as a hash of the command list plus the absolute config path — you only get asked again if the commands actually change. For non-interactive use (CI, scripts), pass --trust-shells to skip the prompt.

Enabling / Disabling

Substitutions are enabled by default, so built-ins like {{UTC_NOW}} work out of the box. Use --no-substitutions on the command line to disable them for a single session (for example if you actually need to send the literal text {{UTC_NOW}} to the device).

Errors

If a placeholder name is unknown, references itself (cycle), or the format string fails, the placeholder is left in the text as-is and a warning is written to ~/.hardwario/rttt.log. The command is still sent to the device so you don't lose keystrokes.

MCP Server (AI Integration)

RTTT includes a built-in Model Context Protocol (MCP) server that allows AI tools (Claude, Cursor, etc.) to interact with your embedded device via RTT.

MCP server is enabled by default. Start RTTT as usual:

rttt --device NRF52840_xxAA --mcp

Claude Code Configuration

Add to your .mcp.json:

{
    "mcpServers": {
        "rttt": {
            "type": "http",
            "url": "http://127.0.0.1:8090/mcp"
        }
    }
}

When the server runs with --mcp-token, add the matching header:

{
    "mcpServers": {
        "rttt": {
            "type": "http",
            "url": "http://127.0.0.1:8090/mcp",
            "headers": {
                "Authorization": "Bearer <TOKEN>"
            }
        }
    }
}

Authentication

By default the MCP server has no authentication and binds to 127.0.0.1, which is fine for local use. When exposing it to a network (e.g. --mcp-listen 0.0.0.0:8090 on a shared debug box), set a token:

rttt --device NRF9151_XXCA --mcp --mcp-token "$(openssl rand -hex 16)"

Every HTTP request — both the /mcp endpoint and /upload — must then carry Authorization: Bearer <TOKEN>; anything else gets 401 Unauthorized. The token can also come from the RTTT_MCP_TOKEN environment variable or the mcp_token key in .rttt.yaml. Note the transport is plain HTTP, so on an untrusted network the token (and everything else) is visible on the wire — use an SSH tunnel or a TLS reverse proxy for anything beyond a lab LAN.

Available MCP Tools

The server also exposes a debug_device MCP prompt describing typical debugging workflows and RTT troubleshooting for agent clients.

External Flash Command

By default the flash operation programs the device through the J-Link DLL. When a different tool works better for your target (e.g. nrfjprog for nRF91, hardwario CLI, west flash), override it with --flash-cmd or the flash_cmd key in .rttt.yaml:

rttt --device NRF9151_XXCA --mcp \
     --flash-cmd 'nrfjprog --family NRF91 --program {file} --sectorerase --verify --reset'

flash_cmd: "nrfjprog --family NRF91 --program {file} --sectorerase --verify --reset"

The command runs through the shell with these placeholders (values are shell-quoted automatically):

The J-Link connection is released for the duration of the command so the external tool can claim the debug probe, and RTT re-attaches afterwards. The tool's output is streamed to the console and log. With an external command the .zip extension is also accepted (nrfjprog modem firmware packages).

Because flash_cmd from a config file is an arbitrary shell command, it goes through the same trust prompt as shell substitutions — you approve it once per config file (or pass --trust-shells in CI).

Headless Mode

For CI boxes, remote debug servers or fully agent-driven sessions, run the MCP server without the interactive console:

rttt --device NRF9151_XXCA --mcp --headless

Uploading Firmware from a Remote Client

The flash tool resolves paths on the machine rttt runs on. When the MCP client runs elsewhere, upload the firmware first via the HTTP endpoint served on the same port:

curl --data-binary @fw.hex 'http://<host>:8090/upload?filename=fw.hex'
# → {"status": "ok", "path": "/tmp/rttt-uploads-8090/fw.hex", "size": 123456}

Then pass the returned path to the flash tool. Allowed extensions are .hex, .bin, .elf and .srec; the body is limited to 64 MiB.

With --mcp-token set, include the header:

curl -H 'Authorization: Bearer <TOKEN>' \
     --data-binary @fw.hex 'http://<host>:8090/upload?filename=fw.hex'

Note: without --mcp-token the MCP server and the upload endpoint have no authentication. The default bind is 127.0.0.1; set a token before exposing them with --mcp-listen 0.0.0.0:8090 outside a trusted network (see Authentication).

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤  by HARDWARIO a.s. in the heart of Europe.