Skip to content

API.md

Latest commit

 

History

History
751 lines (527 loc) · 20.1 KB

API.md

File metadata and controls

751 lines (527 loc) · 20.1 KB
Raw

JS8Call API Documentation v3.0.0

This document provides documention of the API to control JS8Call.

Methods

The API is normally located on localhost port 2242, but can be changed at Settings -> Reporting Tab -> API If you have access to telnet you can connect to the API with

telnet 127.0.0.1 2242

If you do nothing, the API will print information as it has it available, or you can submit one of the End Points below.

API Format

All API calls are via JSON. JS8Call spits out a JSON packet of the form (for a heartbeat in this case):

{"params":{"PTT":true,"UTC":1768760160665,"_ID":-1},"type":"RIG.PTT","value":"on"}
{"params":{"TONES":[4,2,5,6,1,3,0,7,1,5,7,6,0,2,2,3,7,4,2,7,6,4,5,1,7,1,7,3,6,6,4,1,0,4,1,7,4,2,5,6,1,3,0,0,2,4,2,1,1,4,1,6,3,4,4,4,6,2,0,7,0,5,6,2,3,1,0,3,7,4,6,4,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"TONES":[4,2,5,6,1,3,0,7,1,5,7,6,0,2,2,3,7,4,2,7,6,4,5,1,7,1,7,3,6,6,4,1,0,4,1,7,4,2,5,6,1,3,0,0,2,4,2,1,1,4,1,6,3,4,4,4,6,2,0,7,0,5,6,2,3,1,0,3,7,4,6,4,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"PTT":false,"UTC":1768760173403,"_ID":-1},"type":"RIG.PTT","value":"off"}

The steps above are

  1. PTT on
  2. Send HB MSG as TONES (2 transmission frames)
  3. PTT off

{"params":xxx} is required in both directions and forms the overall packet

Note

In the table below, most of the API calls listed as version 2.3 also existed in earlier versions of JS8Call.

Commands Version
PING 2.3
RIG.GET_FREQ 2.3
RIG.SET_FREQ 2.3
RIG.GET_PTT 3.0
RIG.SET_TUNE 3.0
RIG.TX_HALT 3.0
STATION.GET_CALLSIGN 2.3
STATION.GET_GRID 2.3
STATION.SET_GRID 2.3
STATION.GET_INFO 2.3
STATION.SET_INFO 2.3
STATION.GET_STATUS 2.3
STATION.SET_STATUS 2.3
STATION.VERSION 3.0
STATION.GET_OS 3.0
STATION.SET_STATUS 2.3
STATION.GET_SPOT 3.0
STATION.SET_SPOT 3.0
RX.GET_CALL_ACTIVITY 2.3
RX.GET_CALL_SELECTED 2.3
RX.GET_BAND_ACTIVITY 2.3
RX.GET_TEXT 2.3
RX.GET_FREE_OFFSETS 3.0
TX.GET_TEXT 2.3
TX.SET_TEXT 2.3
TX.SEND_MESSAGE 2.3
TX.GET_QUEUE_DEPTH 3.0
MODE.GET_SPEED 2.3
MODE.SET_SPEED 2.3
INBOX.GET_MESSAGES 2.3
INBOX.STORE_MESSAGE 2.3
WINDOW.RAISE 2.3

_ID Number

The ID number is the epoch time of 1499299200000 (July 6, 2017) plus current epoch time.

Error messages

Response
{"params":{"_ID":"269558031750"},"type":"API.ERROR","value":"unterminated object: json parsing error"}

value contains the error

STATION Message

API >= 3.0

The following message is generated by JS8Call when it is closing down.

Response
{"params":{"REASON":"User closed application","_ID":-1},"type":"STATION.CLOSING","value":""}

RX Messages

The following messages are generated by JS8Call and emitted out from the API as they come in.

RX.ACTIVITY

Response
{"params":{"DIAL":7078000,"FREQ":7080420,"OFFSET":2420,"SNR":-22,"SPEED":1,"TDRIFT":0.26499998569488525,"UTC":1769740328005,"_ID":-1},"type":"RX.ACTIVITY","value":"HC5PH: "}
{"params":{"CMD":" MSG","DIAL":7078000,"EXTRA":"","FREQ":7080420,"FROM":"HC5PH","GRID":" FI06","OFFSET":2420,"SNR":-24,"SPEED":1,"TDRIFT":0.23999999463558197,"TEXT":"F!104 2EE ST[EC] GR[FI06JS] #AUVO","TO":"@SITREP","UTC":1769740328005,"_ID":-1},"type":"RX.DIRECTED","value":"HC5PH: @SITREP MSG F!104 2EE ST[EC] GR[FI06JS] #AUVO ♢ "}

RX.DIRECTED

Response
{"params":{"CMD":" HEARTBEAT","DIAL":7078000,"EXTRA":"","FREQ":7078816,"FROM":"KE2DMC","GRID":"FN32","OFFSET":816,"SNR":1,"SPEED":0,"TDRIFT":0.5399999618530273,"TEXT":"","TO":"@HB","UTC":1769740226361,"_ID":-1},"type":"RX.DIRECTED","value":"KE2DMC: @HB HEARTBEAT ♢ "}

RX.SPOT

Response
{"params":{"CALL":"KF7MIX","DIAL":7078000,"FREQ":7078870,"GRID":"EM48","OFFSET":870,"SNR":-5,"_ID":-1},"type":"RX.SPOT","value":""}

PING

API >= 2.3

Wakes up the API if need be.

End Point
{"params":{},"type":"PING","value":""}
Requirements
value empty string
Response
None

RIG.GET_FREQ

API >= 2.3

Gets radio dial and offset frequencies

End Point
{"params":{},"type":"RIG.GET_FREQ","value":""}
Requirements
value empty string
Response
{"params":{"DIAL":7078000,"FREQ":7079950,"OFFSET":1950,"_ID":269554125481},"type":"RIG.FREQ","value":""}
FREQ is the DIAL frequency plus OFFSET

RIG.SET_FREQ

API >= 2.3

Sets radio dial and offset frequencies

End Point
{"params":{"DIAL":dial,"OFFSET":offset},"type":"RIG.SET_FREQ","value":""}
Requirements
dial Frequency in Hz
offset Offset in Hz
value empty string
Response
{"params":{"DIAL":7078000,"FREQ":7079950,"OFFSET":1950,"SELECTED":"","SPEED":0,"_ID":"269554221645"},"type":"STATION.STATUS","value":""}

FREQ is the DIAL frequency plus OFFSET SPEED is one of the MODE speeds

RIG.GET_PTT

API >= 3.0

Gets rig PTT status

End Point
{"params":{},"type":"RIG.GET_PTT","value":""}
Requirements
value empty string
Response
{"params":{"MESSAGE":"","PTT":false,"_ID":269908447335},"type":"RIG.PTT_STATUS","value":""}
{"params":{"MESSAGE":"SLbuEVAt7YC0","PTT":true,"_ID":269908640060},"type":"RIG.PTT_STATUS","value":""}

MESSAGE will be empty string or a message if more is being transmitted.

PTT will be true if transmitting.

RIG.SET_TUNE

API >= 3.0

Sets TUNE setting on or off

End Point
{"params":{},"type":"RIG.SET_TUNE","value":"false"}
Requirements
value true/false
Response
{"params":{"_ID":270422213693,"value":true},"type":"RIG.SET_TUNE","value":""}
{"params":{"PTT":true,"UTC":1769721024401,"_ID":-1},"type":"RIG.PTT","value":"on"}
{"params":{"_ID":270421833952,"value":false},"type":"RIG.SET_TUNE","value":""}
{"params":{"PTT":false,"UTC":1769721034501,"_ID":-1},"type":"RIG.PTT","value":"off"}

NOTE: Both the SET_TUNE and PTT response messages are triggered. As there is a built-in max time on the tuning, no GET call exists.

RIG.TX_HALT

API >= 3.0

Halts the transmitter immediately

End Point
{"params":{},"type":"RIG.TX_HALT","value":""}
Requirements
value empty string
Response
{"params":{"_ID":270426906894,"value":true},"type":"RIG.TX_HALT","value":""}

STATION.GET_CALLSIGN

API >= 2.3

Gets station callsign

End Point
{"params":{},"type":"STATION.GET_CALLSIGN","value":""}
Requirements
value empty string
Response
{"params":{"_ID":269553944755},"type":"STATION.CALLSIGN","value":"callsign"}
Callsign is returned in value

STATION.GET_GRID

API >= 3.0

Gets station grid square

End Point
{"params":{},"type":"STATION.GET_GRID","value":""}
Requirements
value empty string
Response
{"params":{"_ID":269558175403},"type":"STATION.GRID","value":"EM85"}
Grid square is returned in value

STATION.SET_GRID

API >= 2.3

Sets station grid square

End Point
{"params":{},"type":"STATION.SET_GRID","value":grid}
Requirements
grid 4 or 6 character grid square enclosed in ""
Response
{"params":{"_ID":269558371794},"type":"STATION.GRID","value":"EM85"}

Grid square is returned in value

STATION.GET_INFO

API >= 2.3

Gets station info

End Point
{"params":{},"type":"STATION.GET_INFO","value":""}
Requirements
value empty string
Response
{"params":{"_ID":269559398161},"type":"STATION.INFO","value":"JS8-IMPROVED VER "}

Station info is returned in value

STATION.SET_INFO

API >= 2.3

Sets station info

End Point
{"params":{},"type":"STATION.SET_INFO","value":info}
Requirements
value Station info enclosed in ""
Response
{"params":{"_ID":269559620289},"type":"STATION.INFO","value":"JS8-IMPROVED VER "}

Station info is returned in value

STATION.GET_STATUS

API >= 2.3

Gets station status message

End Point
{"params":{},"type":"STATION.GET_STATUS","value":""}
Requirements
value empty string
Response
{"params":{"_ID":269559773383},"type":"STATION.STATUS","value":"IDLE JS8CALL-IMPORVED VERSION "}

Station status is returned in value

STATION.SET_STATUS

API >= 2.3

Sets station status message

End Point
{"params":{},"type":"STATION.SET_STATUS","value":""}
Requirements
value Station status enclosed in ""
Response
{"params":{"_ID":269559773383},"type":"STATION.STATUS","value":"IDLE JS8CALL-IMPORVED VERSION "}

Station status is returned in value

STATION.VERSION

API >= 3.0

Gets JS8Call version. Use to check for API changes or compatiblity.

End Point
{"params":{},"type":"STATION.VERSION","value":""}
Requirements
value empty string
Response
{"params":{"VERSION":"2.6.0-NOT_FOR_RELEASE","_ID":269908381596},"type":"STATION.VERSION","value":""}

STATION.GET_OS

API >= 3.0

Gets OS info including name, kernel version, and type

End Point
{"params":{},"type":"STATION.GET_OS","value":""}
Requirements
value empty string
Response
{"params":{"OS_KERNEL":"linux","OS_KERNEL_VERSION":"6.14.0-37-generic","OS_NAME":"Ubuntu 24.04.3 LTS","_ID":269977840701},"type":"STATION.GET_OS","value":""}

STATION.GET_SPOT

API >= 3.0

Gets status of SPOT setting

End Point
{"params":{},"type":"STATION.GET_SPOT","value":""}
Requirements
value empty string
Response
{"params":{"_ID":270409823907,"value":true},"type":"STATION.SPOT","value":""}

STATION.SET_SPOT

API >= 3.0

Sets status of SPOT setting

End Point
{"params":{},"type":"STATION.SET_SPOT","value":"true"}
Requirements
value true/false
Response
{"params":{"_ID":270409737648,"value":true},"type":"STATION.SPOT","value":""}

RX.GET_CALL_ACTIVITY

API >= 2.3

Returns the recent call activity

End Point
{"params":{},"type":"RX.GET_CALL_ACTIVITY","value":""}
Requirements
value empty string
Response
{"params":{"":{"GRID":"","SNR":0,"UTC":0},"AB4WV":{"GRID":"","SNR":-18,"UTC":1768858992167},"K4EXA":{"GRID":"EM63","SNR":-18,"UTC":1768858242147},"type":"RX.CALL_ACTIVITY","value":""}

RX.GET_CALL_SELECTED

API >= 2.3

Returns the callsign of a station that has been selected in the UI.

End Point
{"params":{},"type":"RX.GET_CALL_SELECTED","value":""}
Requirements
value empty string
Response
{"params":{"_ID":269560590229},"type":"RX.CALL_SELECTED","value":""}
{"params":{"_ID":269560649847},"type":"RX.CALL_SELECTED","value":"KM4PVB"}

  1. First form is if no callsign is currently selected in the UI.

  2. Second form is the selected callsign in the UI.

RX.GET_BAND_ACTIVITY

API >= 2.3

Gets current band activity

End Point
{"params":{},"type":"RX.GET_BAND_ACTIVITY","value":""}
Requirements
value empty string
Response
{"params":{"1067":{"DIAL":7078000,"FREQ":7079067,"OFFSET":1067,"SNR":-7,"TEXT":"W6OEM: VE3SOY HEARTBEAT SNR -20 ","UTC":1768860611907},"616":{"DIAL":7078000,"FREQ":7078616,"OFFSET":616,"SNR":-18,"TEXT":"KM4BOF: VE3SOY HEARTBEAT SNR -09 ","UTC":1768860611918},"type":"RX.BAND_ACTIVITY","value":""}

RX.GET_TEXT

API >= 2.3

Gets the contents of the directed message window

End Point
{"params":{},"type":"RX.GET_TEXT","value":""}
Requirements
value empty string
Response
{"params":{"_ID":269562514193},"type":"RX.TEXT","value":"\n22:06:10 - (1950) - KJ4CTD: W4CAT SNR? ♢ \n\n22:06:52 - (1950) - KJ4CTD: KB4DSF SNR? ♢ \n\n22:14:29 - (800) - KJ4CTD: N0AAS HEARTBEAT SNR -18 ♢ \n\n22:25:31 - (1950) - KJ4CTD: @SITREP MSG F!104 100 ST[SC] GR[EM85] #ASRM KWC ♢ "}

RX.GET_FREE_OFFSETS

API >= 3.0

Returns contiguous free offset segments in the passband not occupied by recently heard stations. Accounts for the bandwidth of each active signal's submode so the returned segments are guaranteed wide enough for your intended transmission without overlapping other stations.

Entries older than 30 seconds are considered stale and treated as clear.

End Point
{"params":{},"type":"RX.GET_FREE_OFFSETS","value":""}
{"params":{"SPEED":2,"LOW":500,"HIGH":2500},"type":"RX.GET_FREE_OFFSETS","value":""}
Optional params
SPEED Submode int (0=Normal, 1=Fast, 2=Turbo, 4=Slow, 8=Ultra). Defaults to current mode.
LOW Low passband bound in Hz. Default: 500
HIGH High passband bound in Hz. Default: 2500
Response
{"params":{"FREE":[{"HIGH":860,"LOW":500,"WIDTH":360},{"HIGH":2500,"LOW":1120,"WIDTH":1380}],"BANDWIDTH":160,"HIGH":2500,"LOW":500,"SPEED":2,"_ID":269562514193},"type":"RX.FREE_OFFSETS","value":""}

FREE is a list of free segments, each with LOW, HIGH, and WIDTH in Hz. BANDWIDTH is the signal bandwidth (Hz) for the requested SPEED. Segments narrower than BANDWIDTH are omitted — they cannot fit the intended transmission.

TX.GET_TEXT

API >= 2.3

Gets the text to be transmitted

End Point
{"params":{},"type":"TX.GET_TEXT","value":""}
Requirements
value empty string
Response
{"params":{"_ID":269562593590},"type":"TX.TEXT","value":""}
{"params":{"_ID":269562644567},"type":"TX.TEXT","value":"KJ4CTD: KJ4YQK SOME RANDOM TEXT"}
  1. If text box is empty
  2. If text box has something in it

TX.SET_TEXT

API >= 2.3

Sets the text to be transmitted

End Point
{"params":{},"type":"TX.SET_TEXT","value":""}
Requirements
value text to be transmitted
Response
{"params":{"_ID":269563119535},"type":"TX.TEXT","value":"TEST"}

TX.SEND_MESSAGE

API >= 2.3

Sends the value in the next transmit cycle

Note

If the message window already has text displayed, this will NOT transmit your new message!

End Point
{"params":{},"type":"TX.SEND_MESSAGE","value":""}
Requirements
value text to be transmitted
Response
{"params":{"PTT":true,"UTC":1768862879801,"_ID":-1},"type":"RIG.PTT","value":"on"}
{"params":{"TONES":[4,2,5,6,1,3,0,1,0,2,6,6,3,1,6,6,4,0,1,7,0,7,2,6,2,6,0,4,3,4,5,2,3,5,2,0,4,2,5,6,1,3,0,3,4,2,5,4,5,7,0,1,6,3,6,7,0,2,3,5,6,4,5,7,4,0,0,1,7,3,6,4,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"PTT":false,"UTC":1768862893402,"_ID":-1},"type":"RIG.PTT","value":"off"}
{"params":{"PTT":true,"UTC":1768862894801,"_ID":-1},"type":"RIG.PTT","value":"on"}
{"params":{"TONES":[4,2,5,6,1,3,0,2,3,7,1,3,7,7,5,2,2,4,1,1,2,2,1,1,5,3,5,4,0,7,0,5,2,1,6,5,4,2,5,6,1,3,0,7,1,6,4,4,3,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,7,2,6,7,1,2,4,2,5,6,1,3,0],"_ID":-1},"type":"TX.FRAME","value":""}
{"params":{"PTT":false,"UTC":1768862908402,"_ID":-1},"type":"RIG.PTT","value":"off"}
  1. Trigger PTT on
  2. Send the message tones
  3. Trigger PTT off
  4. Trigger PTT on
  5. Send the message tones
  6. Trigger PTT off

TX.GET_QUEUE_DEPTH

API >= 3.0

Gets the number of messages left in the transmit queue.

End Point
{"params":{},"type":"TX.GET_QUEUE_DEPTH","value":""}
Requirements
value empty string
Response
{"params":{"DEPTH":2,"_ID":270440267253},"type":"TX.QUEUE_DEPTH","value":""}

MODE.GET_SPEED

API >= 2.3

Gets the currently set transmit mode speed

End Point
{"params":{},"type":"MODE.GET_SPEED","value":""}
Requirements
value empty string
Response
{"params":{"SPEED":0,"_ID":269564224294},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":1,"_ID":269564372867},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":2,"_ID":269564383363},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":4,"_ID":269564510080},"type":"MODE.SPEED","value":""}
{"params":{"SPEED":8,"_ID":269564511182},"type":"MODE.SPEED","value":""}

MODE.SET_SPEED

API >= 2.3

Sets the currently set transmit mode speed

End Point
{"params":{"SPEED":speed},"type":"MODE.SET_SPEED","value":""}
Requirements
speed mode speed number
value empty string
Response
{"params":{"DIAL":7078000,"FREQ":7079950,"OFFSET":1950,"SELECTED":"","SPEED":0,"_ID":"269564663038"},"type":"STATION.STATUS","value":""}
{"params":{"SPEED":0,"_ID":270412242558},"type":"MODE.SET_SPEED","value":""}
  • Sometimes it comes back with the first form.

MODE Speeds

Mode Number
Normal 0
Fast 1
JS8 40 2
Slow 4
JS8 60 8
Please note, JS8 60 is an experimental and unreliable mode.

INBOX.GET_MESSAGES

API >= 2.3

Fetches all Inbox messages, warning, this could be very large

End Point
{"params":{},"type":"INBOX.GET_MESSAGES","value":""}
Requirements
value empty string
Response
{"params":{"MESSAGES":[{"params":{"CMD":" MSG ","DIAL":7078000,"FREQ":7080318,"FROM":"KJ5MIW","GRID":" EM15","OFFSET":2318,"PATH":"KJ5MIW","SNR":-15,"SUBMODE":0,"TDRIFT":0.13999998569488525,"TEXT":"F!104 100 ST[OK] GR[EM15] #ATTV","TO":"@SITREP","UTC":"2026-01-21 01:44:26","_ID":"269660742003"},"type":"READ","value":""}],"_ID":269699597005},"type":"INBOX.MESSAGES","value":""}

MESSAGES is a comma seperated list of message records, each record is contained within brackets.

INBOX.STORE_MESSAGE

API >= 2.3

Stores a message in YOUR Inbox

End Point
{"params":{"CALLSIGN":callsign,"TEXT":text},"type":"INBOX.STORE_MESSAGE","value":""}}
Requirements
callsign "TO" callsign in ""
text Text to store in ""
value empty string
Response
{"params":{"ID":228,"_ID":269569847892},"type":"INBOX.MESSAGE","value":""}

WINDOW.RAISE

API >= 2.3

If allowed by OS. brings the program to the front

End Point
{"params":{},"type":"WINDOW.RAISE","value":""}
Requirements
value empty string
Response
None