AlphaNet Data Protocol
From Zenitel Wiki
Introduction
The AlphaCom/AlphaNet Data Protocol (ACDP protocol) is used for:
- Data communication between AlphaCom Exchanges in AlphaNet, including other types of exchanges such as TouchLine MPC
- Data communication between AlphaCom Exchanges and External Devices such as RIOs and PC based Control Handlers
- Advanced internal control of the AlphaCom. Event Handler can use DP messages as general Action Commands.
The Data Protocol is made generally available from software version AMC 06.00. Previous AMC softwares are NOT compatible with this protocol descriptions.
Protocol properties
- Binary format for speed. Readable ASCII hex format can be used as an alternative for easier debugging
- The physical layer of the protocol is RS485, RS422 or RS232
- Data link layers with message checksum for reliability, and with acknowledgment and re-transmission of erroneous messages
- Network layer for routability when several exchanges are connected
- Variable length fields and optional fields so that the protocol can be used also in future systems with different requirements regarding number of digits in addresses, station numbers etc.
- A systematic way of addressing exchange resources both as directory numbers and physical addresses
- Addressed messages. Commands are addressed to a specific device, and response is returned to the device issuing the command only. In addition, there is a few status broadcast messages
- Addressed messages can be routed in a network. The input and output messages have identical frame format, and thus can be sent via transit exchanges. The same protocol is used both to control a single exchange, and as the AlphaNet protocol
Message example
Here is a HEX coded example of a message with network layer header and application data. This is basically what you send to the exchange in the “simple link layer” format. We assume that you use exchange node 01, the PC is device 01, and that there is a station 107 and 102. The message DIAL_DIGITS looks like this, with spaces between fields for clarity only:
Network Application Application Message layer header header parameters 0101 0141 01 41 1234 0050 3201107F 20102F Src Dest Hop Cl Ref Msg P1 P2 dev dev cnt ss id Station Digits to dial
Important terms of the data protocol
Access to AlphaCom resources
Directory numbers vs. features
Directory numbers, users and stations
Message Formats - Grouped by Function
- Explanation of table format, explanations are in italic font:
See also:
Common notes
- Over time, more parameters will be added to existing messages. These parameters are often marked “(optional)”, and the AMC version which introduced them is shown to the right in the explanation of each parameter.
- - Note that it’s the exchange that processes the DP message that adds default values when it creates an internal representation of the message. If you send a “short” message to a remote node in AlphaNet, all default fields will be filled in in that exchange. Example: SEND_MAIL without A station name will get the name from the same dir.no in the remote exchange (if existing). See comment under Simple Link Layer, page 70.
- In general, NULL is not allowed as NET_OBJ_REF parameter.
- It’s described explicitly when it can be used, e.g. to switch call forwarding OFF. Hint: Some DP messages works correctly only if you leave the NET_OBJ_REF parameter out, rather than supplying an explicit NULL field.
- Note that all messages may cause the response message ILLEGAL_PARAM, indicating that the exchange has problems recognizing either the message number, or a parameter value of a message. In these cases the documented response message will NOT be returned.
- - ILLEGAL_PARAM refers to the problem parameter using a number from 1 and up. This is the number you will find in to the left of each parameter in the table.
- - In AlphaNet, if you get an ILLEGAL_PARAM from a remote node indicating that an optional parameter is required, remember that the AMC versions indicated for optional parameters refers to the receiving node, not the local node generating the message.
- Some messages may seem to have too few parameters. Keep in mind that:
- - the network layer header contains node and device address for both a source and a destination
- - the reference field is always identical in a “command” and the returned “response”.
- AlphaNet: To control a station in a network you must address the DP message to that station’s node. Messages are in general ONLY routed according to the network layer header. If you send a message to an exchange, and use a node number as part of the (A) Subscriber field which is different from the addressed node, the command will be ignored or cause an error response. The messages which deviates from this rule is documented explicitly!
Station Connect Operations
| Message | Description |
|---|---|
| CALL_SETUP | Sets up a coversation between two users |
| CONN_REQUEST | Sets up a coversation between two users |
| CONN_REFERENCE | Positive response from the exchange to CONN_REQUEST |
| CONN_REF_ACK | The external application acknowledges the CONN_REFERENCE |
| STATION_BUSY | Negative response to CONN_REQUEST |
| RESOURCE_BUSY | Negative response to CONN_REQUEST |
| NO_ACCESS | Negative response to CONN_REQUEST |
| STATION_DOWN | Negative response to CONN_REQUEST |
| DISCON_ST | Disconnect station from ongoing feature |
| DISC_REQ | Conversation established with CONN_REQUEST: The external application disconnects a conversation. |
| DISC_REQ_ACK | Conversation established with CONN_REQUEST: The AlphaCom acknowledges the DISC_REQ message |
| DISCONNECTED | Conversation established with CONN_REQUEST: Conversation was disconnected, e.g. the user pressed C-key |
| DISCONNECTED_ACK | Conversation established with CONN_REQUEST: Acknowledge of the DISCONNECTED message |
| CALL_STATUS_BC | Broadcast message telling the status of a call |
| CONN_STATUS_BC | Broadcast message telling that a connection is established |
| DISCON_STATUS_BC | Broadcast message telling that a connection is disconnected |
| PARK_INQ_BROKER | Park station from conversation, enter Inquiry call state |
| UNPARK | Unpark station from Inquiry call state station, return to conversation |
| REQ_TRANSF_CALL | Transfer call in an Inquiry Call situation. |
Station Keyboard & Display emulation
Note that the exchange remembers the M-key state and the handset state forever (it’s not “cleared” e.g. by conversation cancel).
| Message | Description |
|---|---|
| DIAL_DIGITS | Simulate digit dialing from a station |
| DIAL_DAK | Dial DAK on a station |
| SINGLE_DIGIT | Dial one digit on a station |
| DIGIT_RELEASE | The station has released a digit press |
| M_KEY | Order station to press M-key |
| M_KEY_RELEASE | Order station to release M-key |
| HANDSET_OFF | Order station to lift handset |
| HANDSET_ON | Order station to replace handset |
| C_KEY | Order station to press C-key |
| DISPLAY_TEXT | Send text and control characters to a station |
| ST_BUSY_BC | Broadcast message: Intercom station is busy |
| ST_FREE_BC | Broadcast message: Intercom station is free |
Station Features and Status
| Message | Description |
|---|---|
| PROGRAM | Set audio program for single station or a predefined group of stations |
| PROGRAM_ACK | Positive response to PROGRAM |
| PROGRAM_NAK | Negative response to PROGRAM |
| PROG_CONF | Set Simplex conference for predefined group of stations or a single station |
| PROG_CONF_ACK | Positive response to PROG_CONF |
| PROG_CONF_NAK | Negative response to PROG_CONF |
| CONF_TALK | Set Simplex conference speaker |
| CONF_TALK_STOP | Stop station form feeding Simplex conference |
| AUDIO_DETECT | Triggers the event Simplex_Conference_Audio |
| O_DUPL_CONF | Include/exclude a station or a group into/from an Open Duplex Conference |
| OD_CONF_ENTERED | The participant has entered an Open Duplex Conference |
| OD_CONF_LEAVE | The participant has left the Open Duplex Conference |
| ALARM_MSG | Set up (or disconnect) an ASVP Alarm message to a single station or a predefined group of stations |
| ALARM_MSG_ACK | Positive response to ALARM_MSG |
| ST_GROUP_DISCON | Switch off Group Call audio at a station that receives Group Call audio at the moment |
| SET_CALL_REQ_MODE | Turn on/off message “your call is registered, please wait”, then ringing/flashing at a station |
| CALL_TRANSFER | Set or remove call transfer for a station |
| CALL_TRANSFER_OK | Positive response to CALL_TRANSFER |
| CALL_TRANSFER_NOK | Negative response to CALL_TRANSFER |
| SET_REQ_TRANSF | Set transfer of Call Request for an intercom station |
| GET_REQ_TRANSF | Get the Call Request Transfer status for an intercom station |
| REQ_TRANSF | Response to the SET_REQ_TRANSF and GET_REQ_TRANSF messages |
| SET_ABSENCE | Set absence status for an intercom station |
| GET_ABSENCE | Get absence status for an intercom station |
| ABSENCE_STATUS | Response to SET_ABSENCE and GET_ABSENCE messages |
| WAKE_UP | Register or remove wakeup request |
| WAKE_UP_ACK | Positive response to WAKE_UP |
| WAKE_UP_NAK | Negative response to WAKE_UP |
| SET_GRP_FILT | Set group call filter for a station |
| GROUP_MEMBERSHIP | Set group membership in NVRAM for a station |
| EXT_FEATURE_BC | Broadcast message when a directory number (feature 50) is dialed on a station |
| SET_STATION_COS | Set COS membership in NVRAM for a station |
| MODIFY_COS_CONTENTS | Modify feature membership in COS in NVRAM |
Station Mail Operations
| Message | Description |
|---|---|
| SEND_MAIL | Send a mail message to an intercom station |
| SEND_TXT_MAIL | Send a mail message with free text to an intercom station |
| SEND_MAIL_ACK | Response to the SEND_MAIL and SEND_TEXT_MAIL messages |
| CANCEL_MAIL | Delete one or more mail/call request/alarm messages queued at a station |
| SET_MAIL_TIMEOUT | Set the timer of a mail queue entry |
| COPY_MAIL | Send a copy of a mail in own queue to a new destination (station or group) |
| MAILQ_NAVIG | Do operation on mail queue, or step current mail in mail queue |
| DELETE_MAIL | Delete a mail entry in the queue for an intercom station |
| DELETE_MAIL_ACK | Response to the DELETE_MAIL message |
| GET_FIRST_MAIL | Get the first mail entry in the queue for an intercom station |
| GET_LAST_MAIL | Get the last mail entry in the queue for an intercom station |
| GET_NEXT_MAIL | Get the next mail entry in the queue for an intercom station |
| GET_PREV_MAIL | Get the previous mail entry in the queue for an intercom station |
| GET_THIS_MAIL | Get the identified mail entry in the queue for an intercom station |
| EXT_MAIL | Response to the GET_x_MAIL messages |
| Q_ELEM_ADDED | Broadcast message. Reports that a mail message has been added to a station’s mail queue |
| Q_ELEM_REMOVED | Broadcast message. Reports that a mail message has been removed from a station’s mail queue |
General Exchange Control
| Message | Description |
|---|---|
| SET_SYSTEM_TIME | Set the internal clock to the given date and time |
| GET_SYSTEM_TIME | Ask a device (AlphaCom) for date and time |
| SYSTEM_TIME | Response to the GET_SYSTEM_TIME and SET_SYSTEM_TIME message |
| PUT_STRING | Output String to Exchange serial port after adding appropriate framing depending on selected port |
| LOG_STRING | Output String to System Log |
| EXECUTE_COMMAND | Send a command string to the exchange to be executed there |
| EVENT_REPORT | Report an event to the event/action system |
| SET_TIMER | Start or stop a timer |
| WRITE_USER_DEF_DATA | Write User Defined Data (UDD) |
| SET_DIRNO_TXT | Change the display text of a directory number (station or feature) |
| NAME_EXTENSION | Special exchange mode using two line names: Send the second line through AlphaNet |
| SNV | Update specific system settings (NVRAM) values |
| STATUS_REPORT | Report equipment Presence and Error/OK status |
| COMMAND_RESPONSE | General response message to messages |
| ILLEGAL_PARAM | Negative response |
| DPMT_INVALID | Reserved value for internal use |
| DUMMY | Test message: Should be routed, accepted and ignored |
Device Control and Status
A device shall not respond to any message before it’s operative except RESET_DEVICE and GET_DEVICE.
| Message | Description |
|---|---|
| RESET_TAKEN | A device reports that it has done an internal reset |
| RESET_DEVICE | Reset a device |
| GET_DEVICE | Get information from an external device |
| DEVICE_INFO | Response to the GET_DEVICE message |
| PING | Test device: “Are you there?” |
| PONG | Response to the PING message. “Yes, I’m here.” |
Remote Control
| Message | Description |
|---|---|
| SET_LOGICAL_RCO | Set or clear a logical RCO |
| RCO_CHANGED | New RCO state reported from the exchange |
| RCI_CHANGED | New RCI state reported from the exchange |
RIO Protocol
There are a number of messages for RIO control. The message sequences, timing and error procedures are described in a separate document. Note that all inputs or outputs “owned” by the exchange can NOT be controlled in parallel by an external computer. Responses are always returned to the device that controls a pin.
| Message | Description |
|---|---|
| GET_PIN_COUNTS | Query a RIO about number of output and input pins and support for non mandatory features |
| PIN_COUNTS | Response to the GET_PIN_COUNTS message |
| SET_RCO | Turn the given remote control output on |
| SET_RCO_OK | Positive response to the SET_RCO message |
| SET_RCO_FAILED | Negative response to the SET_RCO message |
| CLEAR_RCO | Turn the given remote control output off |
| CLEAR_RCO_OK | Positive response to the CLEAR_RCO message |
| CLEAR_RCO_FAILED | Negative response to the CLEAR_RCO message |
| PULSE_RCO | Generate a pulse with the defined length |
| PULSE_RCO_OK | Positive response to the PULSE_RCO message |
| PULSE_RCO_FAILED | Negative response to the PULSE_RCO message |
| POLL_RCI | Poll the given remote control input once |
| SCAN_RCI_ONCE | Scan input until defined condition is met, then report to exchange |
| SCAN_RCI_ACK | Positive response to the SCAN_RCI_ONCE message |
| RCI_IS_ON | Response to the POLL_RCI and SCAN_RCI_ONCE messages, input pin is on |
| RCI_IS_OFF | Response to the POLL_RCI and SCAN_RCI_ONCE messages, input pin is off |
| SCAN_END_ACK | Acknowledgment to the RCI_IS_OFF and RCI_IS_ON messages |
AlphaNet
This is messages related to audio control between exchanges. <br\>AlphaNet also uses other messages like station emulation, mails, and system maintenance.
| Message | Description |
|---|---|
| AUDIO_PATH_SETUP | Set up audio path between a source node and a destination node (possibly via transit nodes) |
| AUDIO_CODEC | Message sent in the direction of start node, from end node or trans-coding nodes along the path |
| AUDIO_PATH_OK | End to end message: Audio path is ready |
| AUDIO_LINK_OK | Response to AUDIO_PATH_SETUP. Channel number is OK |
| AUDIO_PATH_STATE | SIP Response to AUDIO_PATH_SETUP |
| STATION_INFO | SIP update of number and display text |
| AUDIO_LINK_NOT_AVAILABLE | Response to AUDIO_PATH_SETUP from next node: Channel not granted |
| AUDIO_PATH_DISCONNECT | Release the endtoend audio path. Normal disconnect from source or destination |
| AUDIO_LINK_RELEASE | Used to release audio path backwards stepwise from node to node when setup meets busy or faulty link |
| STATION_LISTEN | Message from remote exchange. Set station in listen mode. Shut mic |
| STATION_CONVERSATION | Message from remote exchange. Set station in conversation mode. Stop tone and open mic. |
| STATION_TRANSFER | Message from remote exchange: Transfer of B subscriber. |
| CHECK_AUDIO_PATH | Check of established audio path at regular intervals |
| AUDIO_PATH_CHECK_OK | Positive response to CHECK_AUDIO_PATH |
| AUDIO_CH_LOOPBACK_REQ | Request for loopback audio connection. Used by the Audio Channel Testing process |
| AUDIO_CH_LOOPBACK_ACK | Positive acknowledge of AUDIO_CH_LOOPBACK_REQ |
| AUDIO_CH_FAULTY | Response to AUDIO_CH_LOOPBACK_REQ: Requested channel was faulty |
| LOOPBACK_IMPOSSIBLE | Response to AUDIO_CH_LOOPBACK_REQ |
| AUDIO_CH_DISCON | Disconnect a audio channel after loopback test |
| AUDIO_CH_TONE_REQ | Request a peer exchange to put a 500Hz tone on a audio channel |
| AUDIO_M_PATH_SETUP | Communication in a multi-node network |
| AUDIO_M_PATH_OK | Contains statuses for an AUDIO_M_PATH_SETUP from one or more destination exchanges |
| AUDIO_M_LINK_OK | Per hop positive response to AUDIO_M_PATH_SETUP |
| AUDIO_M_PATH_BACKTRACK | AUDIO_M_PATH_SETUP failed |
| VCP_MEET_REQ | Request answer to global group call |
| BUILD_GLOB_GRP | Broadcast message to all exchanges to make them rebuild global group indexes |
| GLOB_GRP_MEMB | A exchange tells which global groups this exchange is member of by broadcasting this to all exchanges |
| RESET_AUDIO_LINK | Reset audio link between nodes. Message not used in current AlphaCom version |
| CONF_JOIN | Exchange wants to join conference, asks root-exchange to setup connection back to sender |
| CONF_MEMB_CHK | Ask whether any neighbor exchange has any ordinary member left in conference |
| CONF_ORD_MEMB | An exchange tells its neighbors that it has ordinary member left in conference |
| CONF_IS_ROOT | Broadcast message. Sender informs that it is root of conference |
| CONF_NOT_ROOT | Broadcast message. Sender informs that it is no longer root of conference |
| AUDIO_M_FEED_REQ | Global Simplex Conference: Some station is pressing the M-key when participating in a conference |
| AUDIO_M_FEED_STOP | Global Simplex Conference: The station is releasing the M-key |
| AUDIO_PATH_DELAY | Set Duplex switch delay |
System Maintenance
| Message | Description |
|---|---|
| SET_NODE_NUMBER | Change the node number of an exchange |
| ROUTE_ALPHAPRO_MSG | Send AlphaPro message via AlphaNet to/from a remote node |
| CONSOLE_REQ | Log on to system debug console (TST) |
| CONSOLE_DISC | Log off from system debug console (TST) |