TCI Protocol Reference

Introduction

The TCI (Transceiver Control Interface) protocol is an open WebSocket-based protocol originally developed by Expert Electronics for their ExpertSDR2 software. It has since been adopted and extended by Thetis / OpenHPSDR and a growing number of other SDR platforms. TCI provides a standardised, language-agnostic way for client applications to control a software-defined radio over a local or remote network connection.

This document describes the TCI commands required for full compatibility with TCI Remote — a web-based remote SDR control application — and the TCI Remote Compactor, a companion proxy that adds audio compression and multi-user access on top of the standard TCI protocol.

If your SDR software correctly implements the commands in this document, users will be able to connect to it with TCI Remote either directly over a local network or through the Compactor proxy for remote access, without any modification to your server code.

Transport Layer

TCI uses a plain WebSocket connection (RFC 6455). The server listens on a configurable TCP port; the conventional default is 50001. No WebSocket subprotocol negotiation header is used. Connections are always initiated by the client.

• All commands are exchanged as UTF-8 text frames.
• All IQ and audio sample data is exchanged as binary frames.
• No TLS is required for local connections. Applications may use WSS for remote access independently of the protocol.
• Multiple clients may connect to the same TCI server simultaneously. The server must broadcast state changes to all connected clients.

Server Handshake

Immediately after the WebSocket connection is established, the server must push an initialisation block to the client. The client does not send any commands until it receives the ready message that terminates this block.

// Required server → client init messages, in order:

protocol:2;                             // TCI protocol version
device:ExpertSDR2;                      // radio / software name
receive_only:false;                     // true if TX is not supported
trx_count:1;                            // number of independent TRX channels
channels_count:2;                       // audio channels per TRX
vfo_limits:100000,450000000;            // min and max VFO frequency in Hz
if_limits:-96000,96000;                // min and max IF offset in Hz
modulations_list:AM,SAM,DSB,LSB,USB,CWL,CWU,NFM,DIGL,DIGU,SPEC,DRM;
iq_samplerate:192000;                   // MUST be ≥ 96000
audio_samplerate:48000;                 // must be 48000
tx_profiles_ex:Default,Contest,DX;     // comma-separated TX profile names
ready                                    // no trailing semicolon on this one

tx_profiles_ex populates the TX profile dropdown. The remaining init fields are accepted and ignored — see the note below.

After sending ready, the server should also push the current value of all stateful parameters (frequency, mode, filters, PTT state, etc.) so that the client UI immediately reflects the actual radio state without the client needing to poll. TCI Remote does not rely on this alone: it also sends an explicit query batch.

Bare messages — no colon, no semicolon Receive

Three server → client messages carry no parameters and no trailing semicolon. A parser that splits on : must not throw them away.

Message Format

All TCI text messages follow a consistent format:

command_name:param1,param2,paramN;   // general form
ready                                 // no colon, no semicolon
keepalive;                            // command with no parameters

• Command names are lowercase ASCII, no spaces.
• Parameters are comma-separated with no whitespace.
• Every message ends with a semicolon, except ready.
• Boolean parameters are the literal strings true or false.
• Frequencies are always unsigned integers in Hz.
• The TRX index is zero-based. Single-radio setups always use TRX 0.
• Multiple commands may be delivered in one WebSocket text frame, separated by semicolons. Parsers should handle this.
• Unknown commands should be silently ignored for forward compatibility.

The Query Form

Most commands have a query form: the same command name with the TRX index only and no value. The server answers with the normal, fully populated message. TCI Remote relies on this — it does not assume the init push covered everything.

// set                          // query                 // server answers
rx_nb_enable:0,true;            rx_nb_enable:0;         rx_nb_enable:0,true;
agc_auto_ex:0,false;            agc_auto_ex:0;          agc_auto_ex:0,false;
tx_profile_ex:Contest;          tx_profile_ex;          tx_profile_ex:Contest;

Immediately after ready, TCI Remote sends this batch. If your server ignores the query form, every one of these controls will show a stale value until the user touches it.

C→S  sql_enable:0;          // squelch on/off
C→S  sql_level:0;           // squelch threshold
C→S  run_cat_ex:ZZSO;       // squelch source — sql_enable cannot express it
C→S  rx_anf_enable:0;
C→S  lock:0;
C→S  split_enable:0;
C→S  mute:0;
C→S  mon_enable:0,false;    // this one is a set, not a query: monitor off
C→S  rx_volume:0,0;         // trx 0, channel 0
C→S  drive:0;
C→S  tune_drive:0;
C→S  modulation:0;          // query only — the app never pushes the mode at connect,
C→S  modulation:1;          //   so an externally set mode is not overridden
C→S  rx_filter_band:0;      // or a set, if the user has a saved passband
C→S  rx_filter_band:1;
C→S  rx_nb_enable:0;
C→S  rx_nb2_enable:0;
C→S  rx_bin_enable:0;
C→S  agc_auto_ex:0;
C→S  tx_profiles_ex;        // no index at all
C→S  tx_profile_ex;

Stream Setup

After receiving ready, the client sends these commands to configure and start the IQ and audio streams.

Client → Server Send

Server → Client Receive

Frequency & VFO

Bidirectional Both

Client → Server only Send

Modulation

Bidirectional Both

Filters & Passband

Bidirectional Both

RIT / XIT

RIT (Receiver Incremental Tuning) shifts the receive frequency without moving the transmit frequency. XIT does the reverse.

Bidirectional Both

DSP Features

Bidirectional Both

AGC & Squelch

Bidirectional Both

PTT & Transmit Control

Bidirectional Both

Client → Server only Send

Audio Control

Bidirectional Both

Server → Client Receive

TX Profiles

TX profiles store transmit settings (equaliser, compressor, microphone gain, etc.) under named presets. TCI Remote displays the profile list in a dropdown and allows remote switching.

Server → Client on init Receive

Bidirectional Both

Sensors & Meters

Sensor data is pushed by the server at a regular interval once enabled. Typical update rates: S-meter at 10–20 Hz, TX telemetry at 4–10 Hz while transmitting.

Server → Client Receive

CAT Pass-through

TCI provides a pass-through mechanism for CAT (Computer Aided Transceiver) strings, allowing clients to use radio-specific features not covered by the native TCI command set.

Client → Server Send

CAT Commands Used

Everything below travels inside run_cat_ex:. These are the only CAT strings TCI Remote sends on its own initiative. They are all Kenwood-style / Thetis ZZ dialect, because that is what Thetis exposes.

Sent by TCI Remote Send

Sent by the Compactor

None. The Compactor never originates a CAT command. It only decides whether a client's run_cat_ex: is allowed through — see Compactor Extensions.

Keepalive

Client → Server Send

IQ Binary Frames

IQ sample data is transmitted as WebSocket binary frames. The frame format used by Thetis / OpenHPSDR (and followed by TCI Remote) is a 64-byte header followed by interleaved float32 I/Q sample pairs.

Audio Binary Frames

RX audio (server → client) and TX audio (client → server) use the same 64-byte header structure as IQ frames, with a different frame_type value and 48,000 Hz sample rate.

The audio payload (starting at byte offset 64) contains interleaved stereo float32 samples:

// Stereo interleaved layout:
L₀, R₀, L₁, R₁, L₂, R₂, ...   // float32 LE each

// Total payload size:
sample_count × 2 × 4   // × 2 channels × 4 bytes per float32

Compactor Extensions

Text messages

Binary frames

Between app and Compactor the standard 64-byte TCI binary frames are replaced by compressed frames with a four-byte ASCII magic. Between Compactor and your TCI server, ordinary uncompressed TCI frames are used.

Command gating

When a client connects as a Radio Network visitor rather than as the owner, the Compactor filters what it forwards. This is the one place where a command may be silently dropped before it reaches your server.

• Never forwarded from a visitor: trx and tune when the parameters contain true, plus cw_message, cw_macro, cw_macros, run_cat, run_cat_ex, drive, tx_filter_band_ex, tx_antenna, tx_profile_ex, mon_enable, mon_volume and split_enable. run_cat_ex:PS0; and run_cat_ex:PS1; are the two exceptions that are let through.
• Additionally blocked for listeners (a visitor who does not hold the control slot): everything that changes the radio for all listeners at once — vfo, dds, modulation, rx_filter_band, vfo_swap_ex, vfo_lock, lock, rx_enable, rx_antenna, the DSP toggles, agc_auto_ex, agc_gain, sql_enable, sql_level, RIT/XIT, and rx_volume / rx_mute / mute / volume. Listeners get a private volume control inside the app instead.
• Batches are evaluated per command: one blocked command in a semicolon-separated batch blocks the batch.

What the Compactor sends on its own

One thing only: mox:0;tune:0; on its monitoring connection, to force the radio out of TX when a session ends or a watchdog fires. Everything else it puts on the wire towards your server is a client command it decided to forward.

Complete Initialisation Sequence

The annotated exchange below shows the full message flow at connection time.

═══ WebSocket connection established ════════════════════════════

── Server → Client: init block ──────────────────────────────────
S→C  protocol:2;
S→C  device:MySDR;
S→C  receive_only:false;
S→C  trx_count:1;
S→C  channels_count:2;
S→C  vfo_limits:100000,450000000;
S→C  if_limits:-96000,96000;
S→C  modulations_list:AM,SAM,DSB,LSB,USB,CWL,CWU,NFM,DIGL,DIGU;
S→C  iq_samplerate:192000;
S→C  audio_samplerate:48000;
S→C  tx_profiles_ex:Default,Contest,DX;
S→C  ready

── Client → Server: stream setup ────────────────────────────────
C→S  audio_stream_sample_type:float32;
C→S  audio_stream_channels:2;
C→S  audio_stream_samples:2400;
C→S  audio_samplerate:48000;
C→S  audio_start:0;
C→S  iq_start:0;
C→S  rx_sensors_enable:0,true;
C→S  tx_sensors_enable:true;

── Server → Client: stream confirmation + current state push ────
S→C  audio_start:0;
S→C  vfo:0,0,14225000;
S→C  dds:0,14225000;
S→C  modulation:0,USB;
S→C  rx_filter_band:0,0,2800;
S→C  tx_profile_ex:Default;
S→C  trx:0,false;
S→C  split_enable:false;
S→C  agc_auto_ex:0,true;
S→C  agc_gain:0,60;
S→C  rx_nb_enable:0,false;
S→C  rx_anf_enable:0,false;
S→C  rx_nr_enable_ex:0,false,0;
S→C  sql_enable:0,false;
S→C  rit_enable:0,false;
S→C  xit_enable:0,false;
S→C  mute:false;

═══ Steady state — IQ and audio binary frames flowing ════════════

S→C  rx_smeter:0,-85;         // ~S5, repeated at 10–20 Hz

── User changes frequency ───────────────────────────────────────
C→S  vfo:0,0,14195000;
S→C  vfo:0,0,14195000;        // echo confirmed value to all clients
S→C  dds:0,14195000;          // center frequency may shift too

── User presses PTT ─────────────────────────────────────────────
C→S  trx:0,true;
S→C  trx:0,true;              // echoed to ALL connected clients
      … TX audio binary frames (frame_type=2) client → server …
      … tx_sensors frames server → client while TX active …
C→S  trx:0,false;
S→C  trx:0,false;             // echoed to all clients

State Echo Rules

A TCI server is a stateful broker. These rules ensure that all connected clients stay in sync regardless of which client triggered a change.

• Echo all state changes to all clients. When any client sends a command that changes radio state (frequency, mode, PTT, etc.), the server must send the updated state back to every currently connected client, including the one that made the change.
• Push current state to new clients. When a new client connects (after ready), the server should push the current value of all stateful parameters so the client UI is immediately accurate.
• Echo hardware-triggered changes. State changes caused by the hardware itself (e.g. physical PTT button, front-panel tuning) must also be sent as unsolicited server messages to all connected clients.
• Sensor data is push-only. rx_smeter and tx_sensors are not request/response — they are pushed continuously at a fixed rate once enabled. There is no query command for them.

Command Usage Matrix

Every TCI command that TCI Remote v3.5 or Compactor v1.3.4.1 actually puts on the wire or acts upon. Extracted from the source of both, not from this document — if a command is not in this table, it is not used.

• C→S — TCI Remote sends it.
• S→C — TCI Remote acts on it when the server sends it. Blank means the message is accepted and discarded, which is harmless.
• Compactor — relay means it is passed through unchanged; gated means it may be dropped for Radio Network visitors (see Compactor Extensions).

Compatibility Checklist

A server that satisfies all items below will be fully compatible with TCI Remote, both for direct connections and when used through the TCI Remote Compactor proxy.

Transport & Handshake

• WebSocket server on a configurable TCP port (default 50001)
• No subprotocol negotiation required
• Sends full init block before ready (protocol, device, trx_count, modulations_list, vfo_limits, if_limits, iq_samplerate, audio_samplerate, tx_profiles_ex)
• Reports iq_samplerate ≥ 96,000 Hz (192,000 Hz recommended)
• Pushes current radio state to new clients immediately after ready
• Silently ignores unknown commands (forward compatibility)
• Does not close the connection on receipt of keepalive;

Frequency & Mode

• Handles vfo: — sets frequency, echoes to all clients
• Handles dds: — sets panadapter center, echoes to all clients
• Handles modulation: — sets mode, echoes to all clients
• Handles vfo_swap_ex:
• Handles vfo_lock: / lock: and echoes lock state
• Handles split_enable: and echoes split state
• Handles rit_enable:, rit_offset:, xit_enable:, xit_offset:

Filters & DSP

• Handles rx_filter_band: — applies passband, echoes to all clients
• Handles tx_filter_band_ex:
• Handles rx_nb_enable:, rx_nb2_enable:, rx_bin_enable:
• Handles rx_anf_enable:, rx_nr_enable:, rx_nr_enable_ex:
• Handles agc_auto_ex:, agc_gain:
• Handles sql_enable:, sql_level:

PTT & Audio Streams

• Handles trx: — controls PTT, echoes actual hardware state to all clients
• Handles tune:
• Handles drive:
• Implements server-side TX watchdog to prevent stuck TX on client disconnect
• Handles audio_start: / audio_stop: — sends RX audio binary frames (float32 stereo, 48 kHz, frame_type = 1)
• Handles iq_start: / iq_stop: — sends IQ binary frames (float32 interleaved I/Q, sample_rate ≥ 96000, frame_type = 0)
• Accepts TX audio binary frames from the client (frame_type = 2)

TX Profiles & Sensors

• Sends tx_profiles_ex: list during init
• Handles tx_profile_ex: — switches profile, echoes active profile name to all clients
• Sends rx_smeter:0,<dbm>; at regular intervals after rx_sensors_enable:0,true; (values in dBm)
• Sends tx_sensors: during TX after tx_sensors_enable:true;

Query Form and Power State

• Answers the query form — command plus TRX index, no value — for every stateful command
• Answers tx_profiles_ex; and tx_profile_ex; sent with no index at all
• Accepts the fixed mode spellings LSB, USB, DSB, CWL, CWU, NFM, AM, SAM, DIGL, DIGU and echoes them back unchanged
• Optional: sends bare start / stop when the radio hardware is powered on or in standby
• Optional: implements run_cat_ex: pass-through — see CAT Commands Used for what is actually sent