WebSocket API - nricciar/sparksdr-websocket-demo GitHub Wiki

Commands

All commands are sent as json encoded strings. The primary key cmd represents the requested command being sent to the server. All other paramaters are specific to the command being executed.

getReceivers

Example Request

{ "cmd": "getReceivers" }

Example Response

Parameter Description
Receivers List of receivers connected to this server
Receivers.ID Receiver ID
Receivers.Mode Mode of the receiver e.g. USB
Receivers.Frequency Tuned frequency of the receiver
Receivers.FilterLow Receiver filter low value
Receivers.FilterHigh Receiver filter high value 
{"cmd":"getReceiversResponse","Receivers":[{"cmd":"ReceiverResponse","ID":0,"Mode":"LSB","Frequency":7141000.0,"FilterLow":-3000.0,"FilterHigh":-150.0},...]}

Notes

  1. Currently the receivers array contains the "cmd": "ReceiverResponse" in each receiver item. I assume this is because the receiver response shares the same underlying type. This does not hurt anything but is also just wasted bytes.
  2. Frequency is returned as a float this may also be due to the underlying type? returning this as an int would probably be preferred as currently it might as well be one.

getRadios

Example Request

{ "cmd": "getRadios" }

Example Response

Parameter Description
Radios List of radios connected to this server
Radios.ID Radio ID
Radios.Name Name of the radio
Radios.Running State of the current radio (powered on/off) 
{"cmd":"getRadiosResponse","Radios":[{"ID":0,"Name":"Hermes Lite 2 hpsdr_0-28-192-162-19-221","Running":true}]}

Notes

  1. Name currently includes a lot of information but in a way thats not easily usable. maybe breaking this into multiple fields?
  2. A separate IP Address/Mac Address field is the response would be nice
  3. Maybe a field here to itemize (websocket) features/commands supported by the radio e.g. {"features":["addReceiver","setRunning","subscribeToSpots","subscribeToAudio","subscribeToSpectrum"...]}. Perhaps maybe another command for this instead {"cmd":"getFeatures","ID":0}

addReceiver

Add a new receiver to a radio by id.

Example Request

Parameter Description
ID Radio ID for request 
{"cmd":"addReceiver","ID":0}

Example Response

This response is the same as the getReceivers command.

removeReceiver

Remove a receiver by receiver id

Example Request

Parameter Description
ID Radio ID for request 
{"cmd":"removeReceiver","ID":0}

Example Response

This response is the same as the getReceivers command.

setRunning

Turn on/off the radio by id.

Example Request

Parameter Description
ID Radio ID for request
Running Enable/Disable radio 
{"cmd":"setRunning","ID":0,"Running":true}

Example Response

This response is the same as the getRadios command.

setFrequency

Sets the frequency of a receiver by id.

Example Request

Parameter Description
ID Receiver ID for request
Frequency Frequency to tune the receiver 
{"cmd":"setFrequency","ID":0,"Frequency":7141000}

Example Response

Parameter Description
ID Receiver ID
Frequency New frequency of the receiver
Mode New mode of the receiver
FilterLow Receiver filter low value
FilterHigh Receiver filter high value 
{"cmd":"ReceiverResponse","ID":0,"Mode":"LSB","Frequency":7141001.0,"FilterLow":-3000.0,"FilterHigh":-150.0}

Notes

  1. cmd casing is different from other commands
  2. Frequency is returned as a float this may also be due to the underlying type? returning this as an int would probably be preferred as currently it might as well be one.

setMode

Sets the mode of a receiver by id.

Example Request

Parameter Description
ID Receiver ID for request
Mode Mode to set the receiver e.g. `LSB 
{"cmd":"setFrequency","ID":0,"Frequency":7141000}

Example Response

This response is the same as the setFrequency command.

getVersion

Gets version information from server.

Example Request

{"cmd":"getVersion"}

Example Response

Parameter Description
ProtocolVersion WebSocket API version
Host Application Name
HostVersion Application Version 
{"cmd":"getVersionResponse","ProtocolVersion":"0.1.2","Host":"SparkSDR","HostVersion":"2.0.4.5"}

subscribeToSpots

Request spot data from the server.

Example Request

Parameter Description
Enable Subscribe/Unsubscribe to spots 
{"cmd":"subscribeToSpots","Enable":true}

Example Response

Once subscribed to spot data you will continue to receive spot data from the server until you unsubscribe.

Parameter Description
spots List of spots 
{"cmd":"spotResponse","spots":[{"time":"2020-11-30T23:12:00Z","frequency":3576404.0,"tunedfrequency":3575000.0,"power":0,"drift":0,"snr":-7,"dt":-0.0,"msg":"CQ KD0XD EN12","mode":"FT4","distance":1490.7643834497214,"call":"KD0XD","color":1,"locator":"EN12","valid":true,"offsetFrequency":1404.0}]}

subscribeToSpectrum

Request spectrum data from a receiver by id.

Example Request

Parameter Description
RxID Receiver ID for request
Enable Subscribe/Unsubscribe to spectrum 
{"cmd":"subscribeToSpectrum","RxID":0}

Example Response

Once subscribed to a spectrum channel you will continue to receive spectrum data from the server in the form of binary encoded websocket messages until you unsubscribe.

For more information see Binary Messages#Spectrum

Notes

  1. This command as well as subscribeToSpectrum use RxID while other commands currently just use a generic ID. Perhaps other commands should be using RxID/RadioID as well?

subscribeToAudio

Request audio from a receiver by id.

Example Request

Parameter Description
RxID Receiver ID for request
Enable Subscribe/Unsubscribe to audio 
{"cmd":"subscribeToAudio","RxID":0}

Example Response

Once subscribed to an audio channel you will continue to receive chunked audio data from the server in the form of binary encoded websocket messages until you unsubscribe.

For more information see Binary Messages#Audio

Notes

  1. This command as well as subscribeToSpectrum use RxID while other commands currently just use a generic ID. Perhaps other commands should be using RxID/RadioID as well?