---
title: "Trace"
---

# Trace

Record up to 32 TwinCAT symbols by ADS notifications with the controller's own timestamps, trigger on a level or edge, read the plot with cursors and export the samples as CSV.

**State:** TwinCAT kit shipped. A native trace sampled by ADS notifications, tested over real loopback TCP against a model of a TwinCAT router and PLC runtime, Linux only. The comparison with XAE ScopeView on a real PLC waits for its report.

The trace only samples. It adds and deletes ADS notifications, never writes a value, never changes the ADS or PLC state and requests no symbol handle, so starting and stopping is not confirmed. The **Trace** editor tab says so above the plot.

## Commands

**Open Trace**, **Start Trace...**, **Stop Trace** and **Export Trace as CSV...** (Command Palette, category Neural Inverse PLC). The Trace tab has Start Trace..., Stop Trace and Export CSV... buttons, the session's state, a legend table and the plot. The tab is restored after a restart, empty until a trace runs.

## Start a trace

1. Connect a TwinCAT target (see [Connect to controllers](https://neuralinverse.com/docs/modules/plc/targets/)) and run **Start Trace...**.
2. Pick up to 32 symbols from the uploaded symbol table: BOOL, integers, REAL/LREAL, enumerations, TIME types. Structs and arrays are refused; trace their members one by one.
3. Pick the sampling: **Cyclic** (a sample every cycle time) or **On Change** (a sample when the value changed, checked every cycle time).
4. Set the cycle time and the maximum delay in milliseconds (steps of 100 ns, as the ADS request carries them). The last choices are offered again per workspace.
5. Optionally set a trigger: a channel crossing a level rising, falling or either way (for a BOOL, an edge), with a number of samples kept before the trigger and recorded after it. The trace then stops by itself. Pre and post samples must fit the buffer, or the start is refused.

Every sample carries the timestamp the controller stamped it with (100 ns resolution), also when the maximum delay makes the controller send several samples in one frame. 64-bit integers keep their exact value beside the plotted number.

## Memory

Each trace keeps at most 64 MiB for all its channels. Every channel gets the same number of samples, the most that fit (about 2.8 million for one channel, 87,000 each for 32). When a buffer is full, the oldest samples are dropped and counted in the status.

## Read the plot

A lane per channel (BOOL as two levels, numbers on their own axis), step drawing between samples, a min/max span per pixel column when a window holds more samples than columns, the trigger marked with a T and the time axis counting from it (else from the first sample). While recording, the window follows the newest samples.

| Input | Action |
|---|---|
| Wheel, plus and minus | Zoom |
| Drag, arrows (Shift for half a window) | Pan |
| Up, Down | Select a channel |
| Double-click, F | Fit |
| Home, End | Go to the start; back to following |
| Click, 1 and 2 | Select and place a cursor |
| Ctrl+Left, Ctrl+Right | Move the cursor to the previous or next sample of the selected channel |
| Delete | Remove the cursor |

The legend lists each channel's type, its value at cursor 1 and 2 as the device sent it, the delta and the samples held. The cursor times and their delta are shown below it and announced to screen readers.

## Stop and export

**Stop Trace** ends the trace; the samples stay for reading and export until the next trace starts. A trace also ends when the symbol version changes, and its samples stay.

**Export Trace as CSV...** writes one row per sample in time order (RFC 4180): the channel, its type, the timestamp as ISO 8601 UTC with seven decimal places, the raw timestamp, the seconds from the trigger (or the first sample) with seven decimals, and the value exactly as the device sent it.

The trace's notifications are deleted when it stops, when a trigger capture completes, when the target is disconnected or removed, when another target is connected and when the PLC environment is turned off. Every start, end and failure is in the **PLC** log.

## Not verified

- Any TwinCAT runtime; the comparison with ScopeView.
- Whether the controller samples below its task cycle time, how TwinCAT bundles samples within the maximum delay, and how many notifications a runtime accepts per connection.
- Whether TwinCAT removes the notifications of a client whose connection drops without deleting them, as when the window is killed.
- Timing and memory with 32 channels at 1 ms over a long recording.