XMOS xSCOPE

Use xSCOPE to watch output from an XMOS .xe application running on an xTAG or in the xsim simulator. Choose the application and target, then connect a Serial Monitor tab or ask Embedder to capture the output.

Prepare the target

Install XMOS XTC Tools on the computer running Embedder. Launch Embedder from the XTC tools environment, or set EMBEDDER_XTC_PATH to the XTC installation.
Build the .xe with xSCOPE support.
For hardware, connect and power the board and its xTAG. For a simulated run, you don’t need to connect anything.

Set the application and target in .embedder/xmos.json. Merge these fields into the file if it already exists:

.embedder/xmos.json

{
  "xe": "build/my_app.xe",
  "target": "hardware"
}

Field	Value
`xe`	The `.xe` path, relative to the project root. Without it, Embedder uses the newest `.xe` it finds.
`target`	`hardware` or `simulator`. Leave it out to use the single attached xTAG.
`adapterId`	The xTAG’s adapter ID. Needed only when several xTAGs are attached.
`xscope`	`true` turns on realtime xSCOPE, which host input and shared Trace recordings need. Leave it out for output-only monitoring.

Embedder ignores older XMOS settings in EMBEDDER.md, such as xmos_xe. If any remain, the Monitor shows a notice asking you to move them to .embedder/xmos.json.

Start a monitored run

Open a Serial Monitor tab. See Open a Serial Monitor tab.
Select the Port for your target:
- XMOS xTAG followed by an adapter ID, for that xTAG.
- XMOS xSCOPE, when Embedder detects XMOS hardware but can’t list its adapters.
- XMOS xsim (simulator), for a simulated run. It appears for XMOS projects when xsim is available.
In App (.xe), keep Auto-detect or choose a build. The Monitor saves your choice as xe in .embedder/xmos.json.
Select Connect.

A fresh xSCOPE connection loads the selected .xe on the chosen xTAG or simulator and runs it, replacing the running program. If an XMOS debugger session already holds the xTAG, the Monitor attaches to that session’s console instead and shows Attached to xgdbserver console. To preserve a running target or fault, read the captured history before you start a new connection.

You can also ask Embedder to load and monitor a build:

Load build/my_app.xe on the selected xTAG and monitor its xSCOPE output
until the startup test finishes. Report any errors.

Embedder’s result names the .xe that ran and whether it loaded that image or joined a session that was already running. On hardware, the image runs from RAM and doesn’t survive a power cycle or reset. To keep it, program it to boot flash; see XMOS debugging. Confirm the selected application, the hardware or simulator target, and the expected startup output before you interpret the result. Simulator output is evidence about the simulated run, not the connected board.

Reconnect after agent commands

Before Embedder runs a shell command, including a build, it disconnects the Monitor’s xSCOPE connections. It does the same before it flashes, starts a debugger server, or runs a hardware script. The Monitor tab shows xSCOPE monitoring stopped. Reconnect explicitly after the command finishes.

Output already captured stays in the Monitor history.
On hardware, the program keeps running without being observed. A simulated run stops.
You can’t reconnect until the command and its cleanup finish. That includes background shell commands and any processes they leave running. An early attempt shows xSCOPE Monitor is suspended while shell commands or hardware cleanup are running. Reconnect after they finish.
Embedder doesn’t reconnect the Monitor for you. The exception is xSCOPE output that Embedder captures itself, such as boot output after a flash. The Monitor joins that session once any hardware commands finish.
Trace recordings that share the xSCOPE connection stay connected during these commands.

Reconnecting starts a new session that loads the last image Embedder ran on that target. If you rebuilt the .xe at the same path, the new session runs the new build. If you changed xe in .embedder/xmos.json since that load, the new session runs the configured .xe instead.

Rebuild build/my_app.xe, then load it on the selected xTAG and monitor
its xSCOPE output until the startup test finishes.

See XMOS debugging for debugger setup and .xe execution controls.

Record probes and prints in Trace

An xSCOPE event recording captures values from the firmware’s registered probes and its xSCOPE prints. Use the matching .xe and select hardware or the simulator explicitly. To share a Monitor connection with the recording, set "xscope": true before you connect it.

Record xSCOPE probes and prints from build/my_app.xe on the selected xTAG.
Reuse the matching active realtime session if available. Stop after I
reproduce the issue, open the recording in Trace, and show the probe values
and prints around the event.

A recording can share a compatible active Monitor or debugger session. A fresh recording launches the application, like a fresh Monitor connection. An output-only session must be restarted in realtime mode before it can supply these events, so preserve any fault evidence first. After you reproduce the issue, ask Embedder to stop the recording. In Trace, registered numeric probes appear as counters and prints appear as events. Check the expected probe names and any dropped-record warnings before you interpret the timeline. You can query the saved recording without launching the application again. For instruction execution rather than application probes, see XMOS xsim and Coverage and trace.

Send supported input

Host input needs all of the following:

"xscope": true in .embedder/xmos.json.
A connection started in realtime xSCOPE mode.
Firmware built with xSCOPE that receives input through xscope_data_from_host.

xSCOPE tabs in the Monitor have no send box. Ask Embedder to send a command the firmware recognizes, then check the firmware’s response in the tab. On an output-only connection, Embedder reports that host input isn’t available and names these requirements. Switching an existing output-only session to realtime can require disconnecting and starting a new connection, which loads the selected application again. Baud rate, DTR and RTS resets, and the RTT and ITM settings, such as probe frequency, CPU frequency, device, and interface, don’t apply to xSCOPE. To restart the program, ask Embedder to load the .xe again, or give it a reset command.

Read an existing run

Read the last 50 lines already captured on the active xSCOPE connection.
Do not launch another application or reset the target.

Use history for output that’s already captured, and a live request with a duration or stop string for future output.

Troubleshoot

xrun was not found: install XTC Tools, launch Embedder from the XTC tools environment, or set EMBEDDER_XTC_PATH to the XTC installation.
XMOS xSCOPE requires an .xe artifact or XMOS .xe not found: rebuild, check xe in .embedder/xmos.json, and confirm the App (.xe) selection.
Several xTAGs found: select the port for the intended xTAG, or set adapterId in .embedder/xmos.json.
xTAG port shows (in use), (no target), or (invalid firmware): XTC Tools reports that state for the xTAG. Close the program that’s using it, connect and power the target, or check the xTAG with the XTC Tools.
No xTAG found: plug in the xTAG, or set "target": "simulator" for a simulated run.
A debugger session holds the xTAG: stop the debugger server before loading a different .xe, or load the image through the debugger.
Monitor shows xSCOPE monitoring stopped: an agent command suspended the connection. Wait for the command and its cleanup to finish, then reconnect.
Input unavailable: check "xscope": true, the realtime connection, and the firmware’s xscope_data_from_host receiver.
No output: confirm that the selected build enables xSCOPE and reaches its logging code.
Settings in .embedder/xmos.json are ignored: check that the file is valid JSON and uses only supported fields. Embedder ignores the whole file if it can’t read it.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

Prepare the target

Start a monitored run

Reconnect after agent commands

Record probes and prints in Trace

Send supported input

Read an existing run

Troubleshoot

​Prepare the target

​Start a monitored run

​Reconnect after agent commands

​Record probes and prints in Trace

​Send supported input

​Read an existing run

​Troubleshoot

Prepare the target

Start a monitored run

Reconnect after agent commands

Record probes and prints in Trace

Send supported input

Read an existing run

Troubleshoot