The .aft Format — An Open Trace Format for Embedded Firmware and AI

Written By Tim Harvey

The .aft Format — An Open Trace Format for Embedded Firmware and AI

Record firmware behavior once, analyze it with Claude, ChatGPT, or any AI assistant. No drivers, no setup — just copy and paste.

The .aft format (Active Firmware Trace) is an open, human-readable trace format for embedded firmware. An .aft file records what a running firmware was actually doing: named variables, state machine transitions, events, and log messages, all with precise timing from the underlying hardware capture. The format is designed to be portable across tools and to be read directly by AI assistants like Claude and ChatGPT with no setup, no drivers, and no API keys. Engineers can copy an .aft trace to the clipboard, paste it into any LLM, and ask questions about system behavior in plain English. For workflows that benefit from direct tool access, the same format is also available through an MCP server.

The specification below defines the file structure, including the AI Context Block that carries firmware semantics alongside the recorded data, and the [META], [CHANNELS], and [EVENTS] sections that hold the trace itself.

Active Firmware Trace (.aft) Format Specification

Format Name: Active Firmware Trace File Extension: .aft Version: 1.5 Author: Active Firmware Tools Status: Finalized

1. Overview

The .aft format is a plain-text export produced by the Active-Pro Application. It is designed for use with AI tools, scripts, and programmatic analysis. It is optimized for readability by both humans and language models — no binary parsing, no repeated metadata per row.

.aft is not a replacement for the .active binary archive (full-fidelity capture) or the .csv export (Excel-based inspection). It is the interpreted, semantically meaningful layer of the capture data.

Delivery: Clipboard only. No file is written to disk. The user right-click drags a range on the waveform view to select a time window, then selects "Copy AI Snapshot" from the context menu (or presses Ctrl+C while a range is selected). The assembled .aft content is copied to the clipboard. The user pastes directly into any AI chat interface.

2. Export Scope

Only data that is visible in the UI within the selected time range is exported:

  • Only wavelines that are visible (not collapsed or hidden) are included.
  • Only events that fall within the right-drag selection window are included.
  • Sections with no visible channels are omitted entirely from the output.

3. File Structure

An .aft file has two parts separated by a delimiter:

[Part 1 — Header Block]
  [file header line]
  [descriptor line]
  [ANALYSIS CONTEXT] (omit if field is empty)
  [DEVICE SOURCES]
  [DEVICE A CHANNELS] (omit if no Device A channels are visible)
  [DEVICE B CHANNELS] (omit if no Device B channels are visible)
  [DEVICE C CHANNELS] (omit if no Device C channels are visible)
  [DEVICE D CHANNELS] (omit if no Device D channels are visible)
  [LOGIC CHANNELS]    (omit if no Logic channels are visible)
  [ANALOG CHANNELS]   (omit if no Analog channels are visible)

---DATA---

[Part 2 — Event Data]
  timestamp, source, channel, data
  (event rows)

All section headers are enclosed in square brackets on their own line. Sections with no content are omitted entirely. The delimiter ---DATA--- separates the header block from the event data and must appear on its own line.

4. Comment Syntax

Lines beginning with # are comments and must be ignored by parsers. Comments are permitted anywhere in the file.

5. Part 1 — Header Block

5.1 File Header

The first two lines of every .aft export are fixed:

Active-Pro Firmware Trace (.aft)
Timestamped firmware debug capture. Sources: embedded devices, logic, analog — interleaved chronologically. Analyze as a firmware engineer.

These lines are not wrapped in section brackets. No timestamp or generated date is included. The second line is a fixed descriptor that orients any AI reader to the nature and purpose of the data.

5.2 [ANALYSIS CONTEXT]

Contains the plain text from the "AI Snapshot Instructions" field on the Notes tab in the Active-Pro Application. This is a freeform briefing field — the engineer fills it out intentionally to prime the AI before it reads the capture data. Typical content includes: project context, known issues under investigation, board revision, test conditions, signal descriptions, or anything else relevant to the analysis.

This section appears first in the header block — before the channel legend — so the AI has full context before reading the data. Omit this section entirely if the field is empty.

5.3 [DEVICE SOURCES]

The legend table. Lists every source code that appears in the data section, paired with its label. Only sources that have at least one visible channel are listed.

Format:

[DEVICE SOURCES]
A, Device A Custom Label
B, Device B Custom Label
C, Device C Custom Label
D, Device D Custom Label
AN, ANALOG
L, LOGIC
  • A, B, C, D — the four possible capture devices. Each maps to its user-assigned label. A device is either an ACTIVE DEBUG PORT (ADP) device emitting firmware debug output, or a bus decoder emitting decoded protocol traffic (I2C, SPI, UART, CAN, etc.). The device label identifies which it is.
  • AN — Analog channels.
  • L — Logic channels.
  • Omit any source that has no visible channels in this export.

5.4 [DEVICE x CHANNELS]

One section per device that has visible channels. Section headers are [DEVICE A CHANNELS], [DEVICE B CHANNELS], [DEVICE C CHANNELS], [DEVICE D CHANNELS].

Each row lists the channel number and its label:

[DEVICE A CHANNELS]
0, Channel 0 Label
3, Channel 3 Label
10, Channel 10 Label
  • Channel numbers are 0..63, independent per device. Device A ch 3 and Device B ch 3 are different channels — disambiguated in the data by the source column (A vs B).
  • Labels are user-assigned in the Active-Pro Application.
  • Mixed-mode ADP channels (channels that emit both ACTIVEText and ACTIVEValue output) appear once in this table. Their data rows contain either text or numeric values — the AI infers from data field content.
  • Omit this section entirely if no channels from this device are visible.

5.5 [LOGIC CHANNELS]

Lists visible logic channels by bit index and label. Logic channels are individual digital signal lines, numbered 0..7.

[LOGIC CHANNELS]
0, Signal A Label
1, Signal B Label
5, Signal C Label

Omit this section entirely if no logic channels are visible.

5.6 [ANALOG CHANNELS]

Lists visible analog channels by index and label.

[ANALOG CHANNELS]
1, Analog 1 Label
3, Analog 3 Label

Omit this section entirely if no analog channels are visible.

6. Part 2 — Event Data

6.1 Column Header

The first line after ---DATA--- is always the column header:

timestamp, source, channel, data

6.2 Event Row Format

Each event is one row with four fields:

Field Description
timestamp Time of the event in seconds, relative to the start of the capture. 9 decimal places (nanosecond precision).
source Source code: A, B, C, D (device), AN (analog), or L (logic).
channel Channel number within the source. For devices: channel number (0..63). For logic: bit index (0..7). For analog: analog channel index.
data The event payload. See Section 6.3 for quoting rules and format by source type.

All rows across all sources are sorted by timestamp ascending, interleaved in a single chronological stream.

6.3 Data Field Quoting Rule

The data field is conditionally quoted:

  • No commas in data — written as-is, no quotes:

    0.000234000, A, 1, 0
0.000301000, A, 2, cmd=FORWARD speed=128
0.000400000, AN, 0, 3.29V

  • Commas present in data — wrapped in double quotes:

    18.076412300, A, 4, "state=STALL, code=4"

  • Double quote character within a quoted field — escaped as "" (standard CSV escaping):

    18.076412300, A, 4, "error=""timeout"", retries=3"

Parser rule: Split on the first three commas. Take everything after the third comma as the data field. If it starts with ", it is a quoted field — strip the outer quotes and unescape "" to ". Otherwise take the remainder as-is.

6.4 Data Field Content by Source Type

Device channels (A / B / C / D):

Text output — human-readable string:

12.345678901, A, 2, state=IDLE
13.345678901, B, 0, START addr=0x48 W ACK

Numeric value output:

14.345678901, A, 5, 24567

Mixed-mode ADP channels emit both text and numeric rows on the same channel number. The AI distinguishes by data field content:

18.076100000, A, 4, 142
18.076412300, A, 4, state=STALL_DETECTED
18.076534700, A, 4, 903
18.076701100, A, 4, state=RECOVERY

Analog channels (AN):

The data field contains the sampled value with its engineering unit appended. The unit string comes from the unit assigned to that analog channel in the Active-Pro Application:

24.345678901, AN, 1, 1.24V
24.345678901, AN, 2, 142mA
24.345678901, AN, 3, 3.30V

Logic channels (L):

Per-bit, change-only rows. Each row reports the new state of one logic channel at the moment it transitions. Value is 0 or 1. Only transitions are recorded — stable signals produce no rows:

25.345678901, L, 0, 0
26.345678901, L, 0, 1
35.345678901, L, 1, 0
36.345678901, L, 1, 1

Multiple logic channels changing at the same timestamp each get their own row.

7. Complete Example

Active-Pro Firmware Trace (.aft)
Timestamped firmware debug capture. Sources: embedded devices, logic, analog — interleaved chronologically. Analyze as a firmware engineer.

[ANALYSIS CONTEXT]
Investigating intermittent I2C NACK failures on sensor board. Failure rate roughly
1 in 50 transactions, appears correlated with motor activity. Board is rev D.

[DEVICE SOURCES]
A, ADP
B, I2C Decoder
AN, ANALOG
L, LOGIC

[DEVICE A CHANNELS]
0, fw_state
1, i2c_retry_count
2, motor_cmd
5, error_flags

[DEVICE B CHANNELS]
0, I2C Bus

[LOGIC CHANNELS]
0, MOTOR_EN

[ANALOG CHANNELS]
0, VCC_3V3
1, MOTOR_CURRENT_mA

---DATA---
timestamp, source, channel, data
0.000100000, A, 0, state=INIT
0.000102340, AN, 0, 3.31V
0.000102340, AN, 1, 0mA
0.000105000, L, 0, 0
0.000200000, A, 0, state=SENSOR_POLL
0.000201000, B, 0, START addr=0x48 W ACK
0.000209000, B, 0, DATA 0x01 ACK
0.000217000, B, 0, RESTART addr=0x48 R ACK
0.000225000, B, 0, DATA 0xFF ACK
0.000233000, B, 0, STOP
0.000234000, A, 1, 0
0.000300000, A, 0, state=MOTOR_START
0.000301000, A, 2, cmd=FORWARD speed=128
0.000302000, L, 0, 1
0.000400000, AN, 0, 3.29V
0.000400000, AN, 1, 203mA
0.000800000, A, 0, state=SENSOR_POLL
0.000801000, B, 0, START addr=0x48 W ACK
0.000809000, B, 0, DATA 0x01 ACK
0.000817000, B, 0, RESTART addr=0x48 R NACK
0.000818000, A, 0, state=I2C_ERROR
0.000818500, A, 5, "err=I2C_NACK, retry=1"
0.000819000, A, 1, 1
0.000820000, B, 0, STOP
0.000900000, AN, 0, 3.28V
0.000900000, AN, 1, 211mA
0.001400000, A, 2, cmd=STOP
0.001401000, L, 0, 0
0.001550000, AN, 0, 3.31V
0.001600000, A, 0, state=SENSOR_POLL
0.001601000, B, 0, START addr=0x48 W ACK
0.001609000, B, 0, DATA 0x01 ACK
0.001617000, B, 0, RESTART addr=0x48 R ACK
0.001625000, B, 0, DATA 0xFF ACK
0.001633000, B, 0, STOP
0.001634000, A, 1, 0

8. Format Rules Summary

  • Plain text, UTF-8.
  • Sections with no visible channels are omitted entirely.
  • All timestamps are 9 decimal places (nanosecond precision).
  • All event rows are sorted chronologically, all sources interleaved.
  • Logic is change-only, per-bit rows. Value is 0 or 1.
  • Analog value includes the engineering unit string appended in the data field.
  • Data field is unquoted if it contains no commas. Wrapped in double quotes if it contains a comma. Literal double quotes within a quoted field are escaped as "".
  • The delimiter ---DATA--- must appear on its own line.

Active Firmware Tools — AFT Format Specification v1.5 — 2026-04-17

How is the .aft format different from a CSV or logic analyzer capture?

A CSV or logic analyzer capture records signals: voltage transitions, decoded bus bytes, analog waveforms. An .aft file records firmware semantics: the actual named variables, state machine labels, and log strings from the running application, with timing preserved. The difference matters when handing the trace to an AI assistant. Signal-level data requires the AI to reconstruct meaning from bytes. An .aft file already carries the meaning.

How do I open an .aft file?

An .aft file is plain text and can be opened in any text editor. It can also be loaded into the Active-Pro debugger application for graphical analysis, or pasted directly into an AI assistant like Claude or ChatGPT for natural language analysis.

Which AI assistants can read .aft files?

Any modern large language model can read an .aft file. The format has been tested with Claude, ChatGPT, and other major AI assistants. The AI Context Block at the top of every .aft file gives the model enough information to interpret the trace without additional prompting.

Do I need an MCP server or API key to use .aft with AI?

No. The primary workflow is clipboard-based: copy the .aft contents from the Active-Pro application, paste into any AI assistant, and ask questions. An MCP server is available for power users who want the AI assistant to load and query .aft files directly, but it is not required.

Is the .aft format open?

Yes. The specification is published openly and is not tied to a single vendor or tool. Any capture tool, analyzer, or script can produce or consume .aft files.

What hardware produces .aft files?

The Active-Pro Debugger and Active-Pro Ultra produce .aft files directly from their capture output. Other tools can generate .aft files by following the specification below.

Tim Harvey
Previous

AI Snapshot
Next

Export and File Operations