View source for SmartSDR TCP/IP API

== SmartSDR TCP/IP API ==
The SmartSDR TCP/IP API performs the following functions:
#Issuing [[#Command Format|commands]] to the radio
#Querying the radio for status
#Receiving streaming [[#Status Format|status information]] from the radio
#Locating radios via the discovery protocol
The command API is accessed using a TCP/IP socket connection to port 4992 of the radio.  To locate radios on the local network, use the [[#Discovery Protocol|discovery protocol]]

== SmartSDR TCP/IP Command Protocol ==
=== Command Prologue ===
Upon connecting to the client port, SmartSDR will provide the version number of the interface and the client handle identifier.  Both of these are provided each time the client connects to the radio.
==== VERSION ====
Protocol version is sent from the radio to the client to notify the client of the protocol version to be used.
<pre>
V<d.e.a.b>

V          = indicates version information
<d.e.a.b>  = major version number in decimal '.' minor version number in decimal '.' a '.' b
</pre>	
Example: <pre>V1.0.0.0</pre>

The 'a' and 'b' numbers are developers discretion and are subject to change without notice.  Generally, no decisions should be made on these numbers.

==== HANDLE ====
The handle provided by the radio is a 32-bit hexadecimal number that uniquely identifies this client connection.  It will subsequently be sent to the the client, along with handles of other clients, to denote which clients executed actions that triggered [[#Status Format|status responses]].
Handle Information (from radio to client):
<pre>
H<handle>

H         = indicates that the handle follows
<handle>  = 32-bit hexadecimal handle
</pre>	
Example:  <pre>H6F4EC23D</pre>
=== Command Format ===
Once the connection is established, the client may begin sending commands to the radio.  Commands follow a general ASCII format.
Command format (from client to radio):
<pre>
C[D]<seq_number>|command<terminator>

C             = indicates a command
D             = optional D after the C requests verbose debug output for this command execution which is returned in the response
<seq_number>  = numeric, up to 32-bits
<terminator>  = 0x0D, 0x0A, or 0x0D 0x0A
</pre>
=== Response Format ===
All commands receive responses from the radio.  One and only one response will be sent for each command received by the radio.  The response is tied to the command by the sequence number supplied by the client.  This sequence number will be echoed back to the client in the response.  The client should check the hex response to determine if the command issued was successful.  A zero (0) value indicates success.  Any other value represents a failure of the command to execute.  The response value is unique and provides insight into the failure mode.  It is recommended that any decisions that are made in the client based on a response should use the hexadecimal response to make the decisions.
Response Format (from radio to client):
<pre>
R<seq_number>|<hex_response>|Message[|Debug output]

<seq_number>   = numeric, up to 32-bits -- echoed from the command sent from the client
<hex response> = ASCII hexadecimal number (32-bit) return value (see table below for possibilities)
<message>      = response value for parsing
<debug output> = optional debug free-format text to assist in application development.  
</pre>
It is generally not recommended that the debug output be parsed by computer to extract information since the debug output could change at any time.

A list of responses can be found on the  [[Known API Responses|known_responses]] page.

=== Status Format ===
Objects in the radio will send out status when they are changed.  To find out about objects, the client must have either subscribed to status for the object ot controlled the object first (in which case an automatic subscription is entered on the client's behalf).  Status messages are asynchronous and can be sent to the client at any time.  
Status Format (from radio to client):
<pre>
S<handle>|<message>

<handle>    = the handle of the client that triggered the update (or 0 for a command line/system change)
<message>   = status value for parsing
</pre>
The period character is used as a decimal separator independent of locale.
A detailed list of status responses can be found in [[SmartSDR Status Responses]]

=== Message Format ===
Messages from the radio can be emitted to the client to let the client know about various status changes, alarms, etc. inside the radio.  Messages are generally free format and also have a 32-bit message number so that they may be trapped by the client and displayed differently if appropriate.
Message Format (from radio to client):
<pre>
M<message_num>|<message_text>

<message_num>    = 32-bit hexadecimal number where bits 24-25 contain the severity of the message (0=Informational, 1=Warning, 2=Error, 3=Fatal Error)
<message_text>   = text to show operator if this message should be displayed
</pre>

If command A is executed before command B, all status reported by command A will be sent before the first status reported by command B.

A detailed list of messages can be found in [[SmartSDR Messages]]

== SmartSDR TCP/IP Commands ==
* [[TCP/IP_amplifier|amplifier]] &rarr; register and control amplifier clients
* [[TCP/IP_antenna_list|antenna_list]] &rarr; retrieve a list of available antennas
* [[TCP/IP_atu|atu]] &rarr; antenna tuner commands
* [[TCP/IP_audio client|audio client]] &rarr; Add/Remove/Set Gain/Pan of Slices for each client
* [[TCP/IP_client|client]] &rarr; identify, register or make changes to client settings
* [[TCP/IP_cw|cw]] &rarr; make changes to the CW keyer or CW mode parameters
* [[TCP/IP_cwx|cwx]] &rarr; send CW with ASCII characters and update/play the CW macros
* [[TCP/IP_dax|dax]] &rarr; control DAX subsystem, subscribe to audio or I/Q samples
* [[TCP/IP_display_pan|display pan]] &rarr; creation and control of panadapter displays
* [[TCP/IP_display_panf|display panf]] &rarr; creation and control of panafall displays
* [[TCP/IP_eq|eq]] &rarr; adjust RX or TX equalizer
* [[TCP/IP_file|file]] &rarr; file upload interface for updating the radio, importing settings and loading waveforms
* [[TCP/IP_filt|filt]] &rarr; adjust slice receiver filter settings
* [[TCP/IP_info|info]] &rarr; get radio information such as model and serial number
* [[TCP/IP_interlock|interlock]] &rarr; adjust transmitter interlock settings, TX1/2/3 outputs, timeouts, etc.
* [[TCP/IP_keepalive|keepalive]] &rarr; enable or disable the TCP/IP channel keepalive system
* [[TCP/IP_memory|memory]] &rarr; update and display memories
* [[TCP/IP_message|message]] &rarr; display an important message on client systems
* [[TCP/IP_meter|meter]] &rarr; control or list meters in radio
* [[TCP/IP_mic|mic]] &rarr; adjust mic settings or change mic source
* [[TCP/IP_mixer|mixer]] &rarr; adjust audio mixer settings
* [[TCP/IP_name|name]] &rarr; identify the name of the current client program
* [[TCP/IP_ping|ping]] &rarr; inform the keep-alive mechanism that the client remains active
* [[TCP/IP_profile|profile]] &rarr; save, load or get info on transmit or global profiles
* [[TCP/IP_preamp|preamp]] &rarr; adjust preamplifier settings on an SCU
* [[TCP/IP_radio|radio]] &rarr; adjust radio name or callsign or change GPS parameters
* [[TCP/IP_read_mclpower|read_mclpower]] &rarr; read power in dBm from attached Mini-Circuits USB Power Meter
* [[TCP/IP_remote_audio|remote_audio]] &rarr; control audio to a remote client
* [[TCP/IP_slice|slice]] &rarr; creation or manipulation of slice receivers
* [[TCP/IP_spot|spot]] &rarr; create, modify, remove spots that show up on the Panadapter
* [[TCP/IP_stream|stream]] &rarr; create or remove radio data streams (for use in DAX, for exmaple)
* [[TCP/IP_sub|sub]] &rarr; creation of status subscriptions to objects
* [[TCP/IP_scu|scu]] &rarr; manipulation of Spectrum Capture Units (SCUs) including preamplifiers, etc.
* [[TCP/IP_tnf|tnf]] &rarr; create/save/adjust tracking notch filter (TNF) settings
* [[TCP/IP_trace|trace]] &rarr; return results of a command trace
* [[TCP/IP_transmit|transmit]] &rarr; adjust transmitter settings including mic levels, monitor levels, vox settings, power and tune settings
* [[TCP/IP_unsub|unsub]] &rarr; removal of status subscriptions to objects
* [[TCP/IP_version|version]] &rarr; report versions of radio firmware that are currently running
* [[TCP/IP_waveform|waveform]] &rarr; register and control waveforms
* [[TCP/IP_xmit|xmit]] &rarr; place or remove the radio from transmit
* [[TCP/IP_xvtr|xvtr]] &rarr; create, remove or adjust transverter settings