List Taps

synapsectl -u $DEVICE taps list

This command runs a kListTaps Query and displays each Tap's name, message type, and endpoint.

Monitor a Tap

synapsectl -u $DEVICE taps stream broadband_source_1

taps stream connects to one Tap and displays live message count, rate, bandwidth, message size, and runtime. It does not print or save raw payloads. For a synapse.LogEntry Tap, it also decodes and displays the latest log entry. Stop with Ctrl+C.

Record a Broadband Tap

synapsectl -u $DEVICE read device-config.json \
  --tap-name broadband_source_1 \
  --output ./recordings \
  --duration 60

read loads the configuration, configures and starts the device if it is not already running, and connects to one Tap whose message type is synapse.BroadbandFrame. If --tap-name is omitted, it selects the first compatible Tap.

Option	Purpose
`--output DIRECTORY`	Save compressed HDF5 to `DIRECTORY/broadband_data_YYYYMMDD_HHMMSS.h5`.
`--plot`	Display a real-time broadband plot.
`--tap-name NAME`	Select a particular BroadbandFrame Tap.
`--list-taps`	List available Taps and exit. A configuration argument is still required.
`--duration SECONDS`	Stop after the specified duration. Without it, stream until `Ctrl+C`.

When read exits, it stops the entire device. If the device was already running when read started, its existing configuration is used instead of the file supplied on the command line.

For high-rate streaming, increase the host UDP receive and send buffers:

# Linux
sudo sysctl -w net.core.rmem_max=10485760
sudo sysctl -w net.core.wmem_max=10485760

# macOS
sudo sysctl -w kern.ipc.maxsockbuf=10485760

Plot Recorded Data

Calling plot opens a graphical plotter and plots an HDF5 recording that was produced by read or a Disk Writer node. It is a local operation and does not require a device.

synapsectl plot --data recordings/broadband_data_20260728_120000.h5

Option	Purpose
`--data FILE`	Recording to plot. HDF5 (`.h5`) is the current format.
`--time END` or `--time START:END`	Restrict the displayed time range in seconds.
`--channels ID,ID,...`	Restrict the display to selected channel IDs.
`--config FILE`	Configuration used to interpret a legacy `.bin`, `.dat`, or `.jsonl` recording.
`--dir DIRECTORY`	Locate a legacy data file and configuration JSON in one directory.

Run Queries

synapsectl -u $DEVICE query query.json
synapsectl -u $DEVICE query query.json --stream

Calling query parses a protobuf JSON QueryRequest. Without --stream, it calls Query and prints one response. With -s or --stream, it calls StreamQuery and displays results as they arrive.

Query type	CLI behavior
`kImpedance`	Supported by unary and streaming queries. Results are also written to `impedance_measurements_YYYYMMDD-HHMMSS.csv`.
`kSelfTest`	Supported by unary and streaming queries. Streaming output summarizes each test and its pass/fail result.
`kListTaps`	Supported as a unary query. `taps list` provides a formatted alternative.
`kGetSettings`	Supported as a unary query. The `settings` commands provide a formatted alternative.

Use -v or --verbose after query for verbose query output. In streaming mode, verbose output also follows device logs.

Impedance Query

Use the below example to measure electrodes 0–3 from a supported physical broadband peripheral.

{
  "queryType": "kImpedance",
  "impedanceQuery": {
    "peripheralId": 100,
    "electrodeIds": [0, 1, 2, 3]
  }
}

synapsectl -u $DEVICE query impedance.json
synapsectl -u $DEVICE query impedance.json --stream

Self-Test Query

Use the below example to run a self-test on your peripheral. Self-test is unavailable for virtual or simulated peripherals. Depending on the device, you may also need to stop active recording before running it.

{
  "queryType": "kSelfTest",
  "selfTestQuery": {
    "peripheralId": 100
  }
}

Record Data