Command-Line Protocol

Version 1.4

November 25, 2002

Abbreviations

Substitutions

Commands

Configuration queries, intercom responses

Status queries

Miscellaneous commands

Miscellaneous responses

Checksums

Notes

Examples

Abbreviations

Substitutions

Commands

Configuration Queries, Intercom Responses

Alphas

Party lines

Special lists

Dim tables

IFBs

Relays

ISOs

Digital inputs

Block inhibits

Priorities

Tone

Keypanel assignments

Key status

Keypanel setup pages

Restrictions

Force/Inhibit

TIF status

Volumes

Jam statement

Alphas

Aliases

Matrix names

Remote alphas

Party lines

Special lists

Special list relays

Dim tables

Dim label

IFBs

Relays

ISOs

Digital inputs

Block inhibits

IFB priority

Trunked IFB priority

Trunk priority

Tone

Keypanels - Key assignments

Keypanels - Key status

Keypanels - Software setups

Local scroll restrictions

ADAMedit restrictions

Remote (trunked) scroll restrictions

Key restrictions

Setup page restrictions

Force/Inhibit - by input

Force/Inhibit - by output

TIF status

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.

Status Queries

Miscellaneous Commands

Miscellaneous Responses

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

Checksums

When the command-line editor is first started, after a master reset or after exit from CSedit, 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.

· The "?" character generates a reply which includes all items in the specified range. The "%" character generates a reply which suppresses null entries; for example, "IF?*" generates a reply containing definitions for all IFBs, while "IF%*" suppresses those IFBs with no input, output, or tone override input defined. Otherwise, the "%" and "?" characters can be used interchangeably.

· Spaces are never used. They are used above only to delimit braces, for greater legibility.

· Anything above enclosed in <angle brackets> must be substituted with other text to make a valid command/query; the section entitled "Substitutions" defines what is acceptable for the various <entries>.

· 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

·Auxiliary component numbers include the following:

The currently supported AUX lists would be:

9500:1-4,11-14(4 PAPs or X-Y panels)

9600:1-4,31(4 PAPs, 1 routing switcher interface)

9700:1-4,21-24,41(4 PAPs, 4 relay controllers, 1 aux ctlr)

· In general, any response to a query may be resent to the intercom literally (immediately or at a later time), as a command. Exceptions include the responses from the "SZ" (size), "NAMX" (matrix names), "SR" (search), "ST" (communications status), "ER" (error counters), and "VER" (software version) requests. A "+" in an input/output (force/inhibit) command (i.e. crosspoint closed) is treated as "~" (no force/inhibit).

· 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.

· When specifying the relays associated with a special list, all associated relays must be included; if, for example, one relay is specified, all other relays are cleared.

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,22RGI0RGO0SU4X3IFP1-3PG1IFTN~

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; no routing switcher inputs or outputs; 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