Difference between revisions of "PowerGenius Ethernet API"
(starter PGXL page)
Latest revision as of 14:02, 27 July 2018
PowerGenius TCP/IP API
The PowerGenius TCP/IP API performs the following functions:
- Issuing commands to the amplifier
- Querying the amplifier for status
- Receiving streaming status information from the amplifier
- Locating amplifiers via the discovery protocol
The command API is accessed using a TCP/IP socket connection to port ???? of the amplifier. To locate amplifier on the local network, use the ????
PowerGenius TCP/IP Command Protocol
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.
Protocol version is sent from the radio to the client to notify the client of the protocol version to be used.
V<d.e.a.b> V = indicates version information <d.e.a.b> = major version number in decimal '.' minor version number in decimal '.' a '.' bExample:
The 'a' and 'b' numbers are developers discretion and are subject to change without notice. Generally, no decisions should be made on these numbers.
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 responses. Handle Information (from radio to client):
H<handle> H = indicates that the handle follows <handle> = 32-bit hexadecimal handleExample:
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):
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
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):
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.
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_responses page.
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):
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
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
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):
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
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 ???