Command-Line Protocol

Version 2.0
2015-03-27

Abbreviations
Substitutions
Configuration Requests

Configuration queries and responses
Configuration commands

Miscellaneous requests
Status queries
Miscellaneous commands

Overview
Commands
Simple queries

Abbreviations

Substitutions

Configuration Requests

Configuration queries and responses

The following section documents queries and commands that deal with the intercom configuration (i.e. items which are saved in AZedit setup files). Any response to a query documented in this section can be resent to the intercom literally (immediately or at a later time), as a command.

Alphas

Party lines

Special lists

Dim tables

IFBs

Relays

ISOs

Digital inputs

Priorities

Tone

Keypanel assignments

Keypanel setup pages

Restrictions

Force/Inhibit

Volumes

Jam statement

Alphas

Aliases

Party lines

Special lists

Special list relays

When specifying the relays associated with a special list, all associated relays must be included. For example, if a single relay is specified, all other relays are cleared.

Dim tables

Dim label

IFBs

Relays

ISOs

Digital inputs

IFB priority

Trunked IFB priority

Trunk priority

Tone

Keypanels - Key assignments

Keypanels - Software setups

Local scroll restrictions

AZedit restrictions

Remote (trunked) scroll restrictions

Key restrictions

Setup page restrictions

Forces and Inhibits

The first of these commands provides access for a given input to various outputs; the second provides access for various inputs to a given output.

The force/inhibit query returns an indication of whether a crosspoint is forced or inhibited; if it is netiher forced nor inhibited, but is closed for another reason (e.g. an IFB program input), the status returned is "+". When a force/inhibit command is sent to the intercom, a "+" is treated like a "~": any existing force or inhibit is cleared, and the intercom determines whether or not to close the crosspoint based on the status of other requests.

Volumes - Dim tables

Volumes - Crosspoint

Volumes - Party line

Volumes - Analog input trim

Volumes - Analog output trim

Jam statement

Jam statements are a client-specific feature. They simulate radio jamming: periodically, a specific crosspoint (the signal being jammed) is dimmed by the specified amount, and a second crosspoint (the jamming signal) is closed. Jamming is implemented by converting each Jam statement into 3 UPL statements. Note that, with the exception of the special case of Jam statements, UPL statements are not accessible via command-line protocol.

Configuration commands

The following section documents various commands that can be used to modify the intercom's configuration, but do not have a corresponding query.

Other Requests

Miscellaneous Requests

The following section documents queries and commands that deal with miscellaneous functions which are not stored as part of an AZedit setup file. Each response documented in this section can by resent to the intercom literally as a command.

The reponses to the following queries are not valid commands.

Status Queries

Miscellaneous Commands

Command Responses

The last three responses occur only when using command line protocol via the trunk master's general purpose interface.

Stored Queries

Overview

Command-Line Protocol messages can be divided into two groups: commands and queries. A command sent to the intercom receives a simple response of "OK" (if no errors were encountered). A query sent to the intercom receives a response containing the requested information. Normally, the protocol is half-duplex: a message is sent to the intercom; the intercom processes the message and generates a response; and another message can then be sent to the intercom.

A stored query consists of a simple query of the status of a single item (e.g. the query for the status of one talk key), prefixed by a number and a colon.

A stored query is treated as a command. The immediate response is either "OK" or an error response. However, once a query has been stored, the intercom automatically monitors the given item, and generates a response whenever it changes. These responses are generated asynchronously, i.e. without waiting for a message to be received. However, if CLP is active on a given port, any asynchronous response is guaranteed not to be interleaved with any CLP response on that port.

Stored queries are actually converted to UPL statements. Hence, if the intercom is configured for 256 UPL statements, then it can handle up to 256 stored queries. When a stored query is sent to the intercom, the number at the start of the command specifies the UPL statement number which will be used to store and evaluate the query.

(If a UPL statement is created to handle a stored query, the output action for that statement is Inform Command Line Protocol.)

Commands

Simple queries

Checksums

When the command-line editor is first started, after a master reset or after exit from AZedit, checksums are disabled.

When checksums are disabled, the format of a message is:

<message> <return>

where:

<message> is as defined above

<return> is the carriage return character, value 0d hex ('\r' in C).

When checksums are enabled, the format of a message is:

<message> <checksum> <newline>

where:

<message> is as defined above

<checksum> consists of exactly 2 hex digits, calculated by summing the ASCII values of the characters in <message>, taking the 2's complement of the sum, and converting the low-order 8 bits to 2 hex digits (0-9, A-F).

<newline> is the linefeed character, value 0a hex ('\n' in C)

For example, consider the 'dump setup' and 'query all IFBs' messages. The bytes sent for these messages, with checksums disabled, would be:

To calculate checksums:

44+4D+50 = E1

low order 8 bits of the 2's complement = 1F

49+46+3F+2A = F8

low order 8 bits of 2's complement = 08

So, with checksums enabled, these messages would be:

So that a computer driving the command editor does not need to know whether checksums are enabled or disabled, the checksum command (CSM+ or CSM~) must always be terminated with a checksum; it may be followed with either a carriage return or a newline. Hence, the checksum enable command may be one of:

The checksum disable command may be one of:

Notes

The protocol consists strictly of upper-case characters, digits, the special characters "?", "!", "=", "-", "+", "~", "*", ":", ",", and the double quote ("). Double quote is used only in response to the VER inquiry.

The protocol will be extended in the future by adding new commands to reflect additional intercom capabilities.

Spaces are never used. They are used above only for greater legibility.

Anything above enclosed in <angle brackets> must be substituted with other text to make a valid command/query, as defined in the Substitutions section.

The construct { .... }* is used to indicate what part of a command can be specified multiple times. For example, the tone query for panels 1 through 10 (<list> becomes "1-10")

TN?1-10

might generate a response of:

TN1+2+3+4~5~6~7~8~9+10~

indicating that tone generation is enabled for panels 1, 2, 3, and 9.

Restriction information is denoted by prefixing the letter "R" to the appropriate information. For example, port access restrict is denoted by RKP, whereas individual key restriction is denoted by RKY.

Special function numbers include the following:

Special function names do not have aliases

There is a maximum length for any reply, query, command or reply of 500 bytes. If a query would result in a longer reply, the reply is abbreviated (fewer items are returned), and the line is terminated with a "&". The successive line(s) are returned in response to NXT requests.

Examples

Note: checksum and line termination characters are not shown.

Query matrix size and capabilities

Define IFBs

Define relays

Define alphas

Force crosspoints

Make key assignments

Change setup pages

Set IFB priorities

Restrict key assignments

Force talk and listen key states

Assign party line memberships

Query matrix size and capabilities

SZ?

Typical response for 9500: (reply is all on one line)

SZ:KP50PL60IF24SL6RY8IS16SF1,11-14,21,22SU4X3IFP1-3PG1

i.e.50 point-to-points; 60 party lines; 24 IFBs; 6 special lists; 8 relays; 16 isolates; special functions: null, AL, AF, AM, AR, all-call, panel party lines; 4 software setups; 3 expansion panels supported; 3 levels of IFB priority; 1 program input;

Define IFBs

Set up IFB 10 to use output (bus) 49, with program input as its default input; set up IFB 11 to use output 50, with input 50 as its default input.

IF10INPG1OU49

IF11IN50OU50

Equivalently,

IF10OU49INPG1

IF11OU50IN50

Define relays

Assign relay 1 to output 49/program input; assign relay 2 to output 50, any input.

RY1INPG1OU49RY2IN*OU50

Equivalently,

RY1INPG1OU49

RY2IN*OU50

Or

RY2OU50IN*RY1OU49INPG1

Define alphas

Assign the names:

KP1NADIR1KP2NAPRD1KP3NAVTDRKP4NABILL

IF10NACAMSIF11NANEWS

Force crosspoints

Force the following crosspoints:

input 1 --> outputs 43, 44, 45

input 3 --> output 43

program input 1 --> output 45

Also inhibit the following crosspoints:

program input 1 --> output 1

IN1FI43F44F45F1I

IN3FI43F

INPG1FI45F

Or, specifying outputs instead of inputs,

OU1FIPG1I

OU43FI1F3F

OU44FI1F

OU45FI1FPG1F

Make key assignments

Assign the following keys:

Port 1: Main panel:

Key	Talk level 1	Level 2	Listen
1	IF11	null	N048
2	PL06	null	AL
3	N004	null	AL

Port 2: First expansion panel:

Key	Talk level 1	Level 2	Listen
1	N001	null	AF
2	IS01	null	null

KP1MNKY1T1IF11T2SF1LSKP48KY2T1PL6T2SF1LSSF11KY3T1KP4T2SF1LSSF11

KP2X1KY1T1KP1T2SF1LSSF12KY2T1IS1T2SF1LSSF1

Notes:

·SF11 is auto-listen

·SF12 is auto-follow.

To change the assignments in specific setups, without determining whether those setups are in use and to which panels they may be assigned, change the "KP1MN" to "KP1SU#" and "KP2X1" to "KP2SU#", where # is the corresponding setup number (1-4).

Change setup pages

Change the setups on keypanel 17 to: main = 1, expansion 1 = 3, expansion 2 = no setup, expansion 3 = no setup.

KP17MNSU1X1SU3X2~X3~

Set IFB priorities

Set the IFB priority for panels 1, 2, 3, and 8 to be 2, set the IFB priority for panels 4-7 and 9-20 to be 1.

IFP2KP1-3,8

IFP1KP4-7,9-20

Equivalently,

KP1IFP2KP2IFP2KP3IFP2KP4IFP1KP5IFP1...

Restrict key assignments

Restrict ISO 1-16, IFB 1-12

RIS1+2+3+4+5+6+7+8+9+10+11+12+13+14+15+16+

RIF1+2+3+4+5+6+7+8+9+10+11+12+

Force talk and listen key states

Force first 3 talk and listen keys of the main panel of panel (port) 20 to be on. Force the 4th talk and listen keys off.

KP20MNKS1T+LS+2T+LS+3T+LS+4T~LS~

Assign party-line memberships

Assign the following panels to party-line 10: panel 5: permanent talker/listener; panels 9,10,11,12: permanent listeners

PL10KP5P9L10L11L12L

Assign panel 19 to be a permanent talker/listener on party-line 14; a permanent listener on party-lines 19 and 20; and a permanent talker on party line 3

KP19PL14P19L20L3T