Skip to content

TCPIP spot

Eric edited this page Jan 20, 2023 · 4 revisions

ADD

Add a spot to the radio. Added in SmartSDR v2.3.

C[D]<seq_number>|spot add rx_freq=<MHz> callsign=<callsign> [tx_freq=<MHz>] [mode=<mode>] [color=<color>] [source=<source>] [spotter_callsign=<spotter_callsign>] [timestamp=<timestamp>]
[lifetime_seconds=<seconds>] [priority=<priority>] [comment=<comment>] [trigger_action=<action>]

Note: Any spaces in any one of these individual fields must be encoded as 0x7F.

<rx_freq>          = Required. The receive frequency for the spot in MHz, up to 15 significant digits.
<callsign>         = Required. The callsign of the Spot (primary field shown in the Panadapter).  Note that duplicate detection is not done in this API.
<tx_freq>          = Optional. The transmit frequency for the spot in MHz, up to 15 significant digits assuming a split spot.  If not present, simplex is assumed and the rx_freq is
assumed to be the tx_freq.
<mode>             = Optional. The reported mode of the spot.  This may or may not match the accepted DSPModes defined for a Slice (ideally lsb, usb, cw, am, fm, rtty, psk, ft8, etc) .
<color>            = Optional. The color to use for the text of the spot in hex ARGB format (e.g. "#AARRGGBB").
<source>           = Optional. A description of where the spot data originated.
<spotter_callsign> = Optional. The reported callsign of the spotter.
<timestamp>        = Optional. The reported timestamp of the spot in Unix time (seconds since midnight Jan 1, 1970 UTC).
<lifetime_seconds> = Optional. The lifetime in seconds to keep the spot.  After this period, the spot will automatically be removed.  The default 0 says not to automatically remove it.
<priority>         = Optional. The priority of a spot in the range 1-5 where 1 is the most important and 5 is the least.  This helps to promote more important spots for greater
visibility when many spots are shown on the Panadapter.
<comment>          = Optional. Any additional reported comments for the spot. These are shown in tooltips when hovering over the spot (or right-clicking in Maestro or M models).  See note
above about encoding spaces.
<trigger_action>   = Optional. Determines what to do when the spot is triggered (clicked on).  Set to Tune (default, radio tunes active or closest Slice in the Panadapter, or creates one
if necessary, to the spot rx_freq) or None (no effect by the radio, client may implement custom behavior).

Adding a new spot with the same RX Frequency and Callsign will simply update the existing Spot's fields with the information provided.

Example:

C179|spot add rx_freq=14.178 callsign=KE5DTO mode=USB color=#FF0000FF source=N1MM spotter_callsign=N5AC timestamp=1533196800 lifetime_seconds=3600 priority=4 comment=thanks

See Response Format for details on the format of the response messages from the radio

Hex Response Message Debug Output / Meaning
00000000 <spot_index> OK spot <spot_index> created
5000002C   Incorrect number of parameters

Responses

   <spot_index> = the index assigned to the spot upon creation        

Response Example:

R179|0|37

SET

Modify an existing spot using the spot index.

C[D]<seq_number>|spot set <spot_index> [rx_freq=<MHz>] [callsign=<callsign>] [tx_freq=<MHz>] [mode=<mode>] [color=<color>] [source=<source>] [spotter_callsign=<spotter_callsign>]
[timestamp=<timestamp>] [lifetime_seconds=<seconds>] [priority=<priority>] [comment=<comment>] [trigger_action=<action>]

While none of these fields are required, there of course must be at least one present to make a good spot set command.

<spot_index>       = Required. A reference to the index assigned to the spot upon creation.
<rx_freq>          = Optional. The receive frequency for the spot in MHz, up to 15 significant digits.
<callsign>         = Optional. The callsign of the Spot (primary field shown in the Panadapter).  Note that duplicate detection is not done in this API.
<tx_freq>          = Optional. The transmit frequency for the spot in MHz, up to 15 significant digits assuming a split spot.  If not present, simplex is assumed and the rx_freq
is assumed to be the tx_freq.
<mode>             = Optional. The reported mode of the spot.  This may or may not match the accepted DSPModes defined for a Slice (ideally lsb, usb, cw, am, fm, rtty, psk, ft8, etc) .
<color>            = Optional. The color to use for the text of the spot in hex ARGB format (e.g. "#AARRGGBB").
<source>           = Optional. A description of where the spot data originated.
<spotter_callsign> = Optional. The reported callsign of the spotter.
<timestamp>        = Optional. The reported timestamp of the spot in Unix time (seconds since midnight Jan 1, 1970 UTC).
<lifetime_seconds> = Optional. The lifetime in seconds to keep the spot.  After this period, the spot will automatically be removed.  The default 0 says not to automatically remove it.  Note that the lifetime is in seconds since the spot originated, not from when this value is set.
<priority>         = Optional. The priority of a spot in the range 1-5 where 1 is the most important and 5 is the least.  This helps to promote more important spots for greater
visibility when many spots are shown on the Panadapter.
<comment>          = Optional. Any additional reported comments for the spot. These are shown in tooltips when hovering over the spot (or right-clicking in Maestro or M models).
See note above about encoding spaces.
<trigger_action>   = Optional. Determines what to do when the spot is triggered (clicked on).  Set to Tune (default, radio tunes active or closest Slice in the Panadapter, or creates
one if necessary, to the spot rx_freq) or None (no effect by the radio, client may implement custom behavior).

Example:

C180|spot set 37 rx_freq=14.185

See Response Format for details on the format of the response messages from the radio

Hex Response Message Debug Output / Meaning
00000000 spot set successful
5000002C   Incorrect number of parameters
500000BC   Invalid spot index

Responses

Response Example:

R180|0

REMOVE

Remove (delete) an existing spot using the spot index.

C[D]<seq_number>|spot remove <spot_index>

<spot_index>       = Required. A reference to the index assigned to the spot upon creation.

Example:

C181|spot remove 37

See Response Format for details on the format of the response messages from the radio

Hex Response Message Debug Output / Meaning
00000000 Successfully removed spot
500000BC   Invalid spot index
5000002C   Incorrect number of parameters

Responses

Response Example:

R181|0||

TRIGGER

Trigger an existing spot using the spot index.

C[D]<seq_number>|spot trigger <spot_index> [pan_stream_id]

<spot_index>       = Required. A reference to the index assigned to the spot upon creation.
<pan_stream_id>    = Optional. A reference to the associated Panadapter, for purposes of tuning/creating Slices.  If the trigger_action is set to none, this field is not used and can be left off.

Example:

C182|spot trigger 37

See Response Format for details on the format of the response messages from the radio

Hex Response Message Debug Output / Meaning
00000000 Successfully triggered spot
500000BC   Invalid spot index
5000002C   Incorrect number of parameters

Responses

Response Example:

R182|0||