The protocol is based on XML. Each and every message should be a genuine XML node. UTF-8 encoding is used to encode any non-ASCII strings. All values inside the XML nodes should be properly encoded (eg < > and & replaced with < > and & respectively). It is recommended to use a real XML parser to parse the commands because the arguments/child nodes may be out of order. This document describes four different kinds of commands: * Initialization sequence, roughly in order * Server to client commands * Commands that are accepted in both directions * Client to server commands === INITIALIZATION === The protocol version to use is determined by the first command received. There are 3 different options for the client to establish the connection (client -> server): Protocol version 1 (obsolete, backward compatibility): SESSION:[sid] Protocol version 2: [sid] Future protocol versions (also allow for v1 and v2): [sid][version] [version] is the protocol version number, currently only 1 and 2 are supported In all cases, [sid] represents the session key. ERROR / SETNAK commands (server -> client) These commands can be sent during the initialization if an error occurs - see below for their meaning. SESSION command (server -> client, protocol version 1 only) 10000 This command is obsolete and should be ignored, older clients may prefix [command] in the command format with the SESSION value (10000 in this case). VERSION command (server -> client, protocol version 2 only) [version] [version] is the version number of the server software MODES command (server -> client, protocol version 2) This command is used to report the possible reception modes/modulations supported by the receiver [mode_id][mode_name]... The node contains any number of nodes, which each represent a mode/modulation [mode_id] is the ID number (1-255) that will be used in all further transactions Recommended values are - 1: AM, 2: WFM, 3: NFM, 4: LSB, 5: USB, 6: CW [mode_name] is the associated name FILTERS command (server -> client, protocol version 2) This command is used to report the possible bandpass filters supported by the receiver [filter_id][filter_name]... The node contains any number of nodes, which each represent a bandpass filter [filter_id] is the ID number (1-255) that will be used in all further transactions (usually close or equal to the filter width in kHz) [filter_name] is the associated name OPTIONS command (server -> client, protocol version 2) This command is used to report capabilities, other options and their current value (see the list of OPTION ID codes) [option_id][name][value]... The node contains any number of nodes, which each represent a capability/setting [option_id] is the ID number to be used in all further transactions - it's meaning is fixed [name] is the name that described the option [value] is the current value (if applicable) STREAMS command (server -> client, protocol version 2) This command is used to report available audio streams [name]... The node contains any number of nodes, which each represent an audio stream [name] is the name of the audio stream which should be used when requesting the actual audio stream (see AUDIO command) === NORMAL OPERATION, SERVER -> CLIENT === ERROR/SETNAK command (server -> client) This command usually indicates that a fatal error has occured and the connection will be closed. Note: these commands may also be used during initialization! Protocol version 1: - The session key is not valid or some other error has occured during initialization - The user was kicked by an administrator Protocol version 2: [reason] Where [reason] is one of: * EXPIRED - Invalid session key * USERLIMIT - Maximum number of simultaneous sessions for this user has been reached * IPLIMIT - Maximum number of simultaneous sessions for this IP address has been reached * RECEIVER - Some internal error has occured and the receiver is not located on this server * KICK - The user was kicked by an administrator * possibly others GETBND command (server -> client) Informs the client about the available bandguides/frequency lists, one GETBND command is sent for each available list [text] [text] is a name that describes the list GETLST/ADDLIST command (server -> client) Used to send a bandguide/frequency list to the client, one GETLST command is sent for each entry in the list [text] or [text] [text] is a the line that describes the entry - it is taken directly from the bandguides file so it may be in any format. The recommended format is outside of the scope of this document. PLAY command (version 2) Informs the client of an audio stream HTTP url (often, but not necessarily, after a call to the STREAMS command) [audio_url] [audio_url] may be a full HTTP url including the http:// prefix, a hostname and a port, or it may be a relative url on the server's ip address/hostname / port. A relative url will always start with a / character. GETALL (version 1, obsolete) Used to inform the client of the current receiver status K0[ffffffffff][mm][bb]0000[ss]000[a]000[t]00[ii] All values are zero padded to the specified length (eg [bb] has length 2) The meaning of the fixed zeros in this command is unknown, old server software may report different values. The format of this command is very similar to the format used to control the PCR1000 receiver. [ffffffffff] is the frequency in Hz [mm] is the reception mode (0: LSB, 1: USB, 2: AM, 3: CW, 5: NFM, 6: WFM) [bb] is the bandpass filter (0: 3k, 1: 6k, 2: 15k, 3: 50k, 4: 230k) [ss] is the squelch option (ranging from 00 to 99) [a] is the AGC option (either 0 or 1) [t] is the Attenuator option (either 0 or 1) [ii] is the current signal strength (2 digit hexadecimal, ranging from 00 to FF) AVAIL command (protocol version 2) Informs the client about the currently acceptable reception modes and bandpass filters [mode_id][mode_id]...[filter_id][filter_id]... The AVAIL node may contain any number of child nodes Each M child node represents an acceptable reception mode with ID number [mode_id] - see MODES command Each F child node represents an acceptable bandpass filter with ID number [filter_id] - see FILTERS command SIGNAL command (protocol version 2) Updates the signal strength/S-meter [value] [value] ranges from 0 to 255 TEXT command (protocol version 2) Updates the radio text display [text] GETUSR command (protocol version 1) Adds an user to the user list, in reply to the GETUSR/USERS command [prefix][username] or [prefix][username] \[[Location]\] [prefix] is a prefix that indicates the user's access level [T]=trial user, +=paid user (unused), %=site operator, @=administrator [username] is the user's login name (or other identifier) \[ and \] represent the actual [ and ] characters [location] is the user's location as specified on the GT website (format: City, CountryCode-2) USERS command (protocol version 2) Informs the client of the currently connected users [uid][level][pfx][name][location]... [uid] is the GlobalTuners user ID (or 0 if not applicable) [level] is the GlobalTuners user level [Prefix] is a character that can be used to prefix the user name to indicate it's access level: [T]=trial user, +=paid user (unused), %=site operator, @=administrator [Name] is the GlobalTuners user name or another identifier [Location] is optional and indicates the location (format: City, COuntry-code-2) as registered in the GlobalTuners database The node is optional and indicates that this entry represents *this* client. It may be used to determine the user id, level or name of the user currently logged in. === NORMAL OPERATION, BOTH DIRECTIONS === TUNE command (protocol version 2) This command is used client -> server to tune the receiver or server -> client to report the current frequency. [frequency][mode_id][filter_id] [frequency][mode_id][filter_id][rel_frequency] [frequency] is the frequency in Hz [mode_id] is the ID number of the current reception mode/modulation (see MODES command) [filter_id] is the ID number if the current bandpass filter (often equal to it's width in kHz, see FILTERS command) [rel_frequency] may be used client->server to set the frequency relative to the current one, a value of 100 means +100 Hz. In client -> server communication, any of the fields may be 0, indicating no change is requested. OPTION command (version 2) Requests to set a receiver option to the specified value (client -> server) or reports a changed option (server -> client) [option_id] is the ID number as specified in the OPTIONS command and defined in the OPTIONS ID list [value] is the new value (see OPTIONS ID list for it's exact meaning) [relative_value] may be used client->server for relative changes, a value of 1 means +1 or toggle depending on the option SETCHT/GETCHT/CHAT command (version 1/2) Used to send a chat message (client -> server) or inform the client about a chat message (server -> client) Client-server only (obsolete): SETCHT:[message] or [message] Server-client only (V1): [message] Both directions (V2): [message] The SETCHT and CHAT commands are accepted by the server. Currently only the GETCHT command is used for server->client (even for protocol version 2), but the CHAT command should be accepted by the client as well. PING & PONG commands (protocol version 2) The command is used to confirm that the connection is alive. On reception, the other side shall reply with === NORMAL OPERATION, CLIENT -> SERVER === Some client -> server commands have either one or none arguments, in this case there are two possible formats: For backward compatibility: With an argument: [command]:[value] Without argument: [command]: Without argument (shorter): [command] Here, [command] represents the actual command, [value] is the value and may be left blank if not applicable. Prefered format: With an argument: <[command]>[value] Without argument: <[command] /> * Note: some commands are associated with a specific protocol version, however, the server will accept all commands with any protocol version in use. The protocol version only affects server -> client commands. SETUSR command (version 1, obsolete) SETUSR:[username] Obsolete and can/will be ignored GETUSR/GETUSERS command (version 1/2) GETUSR: or or Request to send the user list SETQRG command (version 1, obsolete) Requests to tune the receiver to [frequency] in Hz SETQRG:[frequency] SETMOD command (version 1, obsolete) Requests to change the receiver mode and bandpass filter SETMOD:[xx][yy] [xx] is the modulation type (2 digits, padded with a zero) 0: LSB, 1: USB, 2: AM, 3: CW, 5: NFM, 6: WFM [yy] is the bandpass filter (2 digits, zero padded) 0: 3kHz, 1: 6kHz, 2: 15kHz, 3: 50kHz, 4: 230kHz SETSTM command (version 1, obsolete) - Stereo/mono option SETAGC command (version 1, obsolete) - AGC option SETATT command (version 1, obsolete) - ATT option SETSQL command (version 1, obsolete) - Squelch option SQUELCH command (version 2, obsolete) - Squelch option Requests to change the receiver to change an option, See the OPTION ID list for more info on the StereoMono option SETSTM:[value] or [value] DISP command (version 2) Requests the receiver to change it's radio text display (usually in a circular way) GETLIST command (version 2) Retrieve a band guide list [list_id] [list_id] can be 0 to retrieve the user loggings or a value ranging from 1 to the number of entries specified by the GETBND commands, where 1 will retrieve the list specified by the first GETBND command. The reply will use the ADDLIST command GETLST command (version 1/2) Retrieve a band guide list GETLST:[list_id] or [list_id] [list_id] can be any text starting with u (eg user or just u) to retrieve the user loggings, 0 to retrieve the NodeInfo.txt file or a value ranging from 1 to the number of entries specified by the GETBND commands, where 1 will retrieve the list specified by the first GETBND command. The reply will use the GETLST command SETLOG command (version 1) Add a user logging entry to the bandguides SETLOG:[entry] or [entry] [entry] is the bandguide entry in the appropriate format AUDIO command (version 2) Request to start an audio stream [name] is the stream name as defined in the STREAMS command In most cases, the PLAY command will be used to inform the client of the HTTP url of the audio stream SETSCN (version 1, obsolete) Request scanning, not supported CLOSE (version 2) Request to close the connection (not needed, but may be used if the client is somehow not able to close the connection by itself) === Suggestions for extension === EXT command (version 2) Support for the EXT command is optional, it allows arbitrary commands to be sent around [command] [context] [source] [arbitrary nodes] [command] is the extended command. Somme commands will be officially accepted and supported by GlobalTuners and the URadioServer software. Developers may introduce additional EXT commands, as long as these additional commands are prefixed with an underscore (_). - Predefined commands (redundant, not distributed to any objects that may receive the message on some other channel): CHAT - fields SENDER_ID, SENDER_NAME, TEXT; a normal receiver chat message OPTION - fields ID, VALUE; set option ID to VALUE TUNE - fields F, M, B; set tuning - Receiver context commands, interesting for user controllers only TUNE_REQ - request permission to tune TUNE_ACK - allow all users awaiting permission to tune TUNE_LCK - lock tuning completely ANT_ROT - fields VALUE; set antenna rotator ANT_SEL - fields VALUE; select antenna [context] indicates the context in which the message should be distributed: USER:[id] - One single user by user id [id] USER - All controllers on the current receiver RECV - All controllers and plugins on the current receiver DRV - All plugins and drivers on the current receiver SERV - The radioserver core and associated plugins and drivers (future) GLOB - The entire GlobalTuners system (through Global Chat?) [source] is optional and indicates the source of the message (verified): USER:[id] - User with user ID [id] RECV:[id] - Receiver manager with ID [id] DRV - Receiver or audio driver PLUG:[key] - Plugin with short name [key] SERV - Server core HUB - GlobalTuners hub [arbitrary nodes] may contain any number of XML nodes (or otherwise valid XML values) as long as it does not conflict with the predefined node names (CMD, CTX). EXT commands may be dropped without any notice, for example because of connection losses or policies. WARNING: EXT commands may be generated by any connected client or plugin. The commands are not checked for validity so be very careful when trusting them. EXT messages may be mangles by an XML parser and encoder before they are passed on. EXT messages may be passed using other encoding exhemes, therefore it is recommended to only use one level of child nodes inside the EXT node, use only plain textual values inside and not to use duplicate node names.