Actions

Difference between revisions of "AlphaNet Data Protocol"

From Zenitel Wiki

(Station Mail Operations)
(Device Control and Status)
Line 330: Line 330:
 
| [[PING]] || ||align=center|0x003C|| Test device:  “Are you there?”
 
| [[PING]] || ||align=center|0x003C|| Test device:  “Are you there?”
 
|-
 
|-
| [[PONG]] ||  ||align=center|0x003C||Response to the PING message. “Yes, I’m here.”
+
| [[PONG]] ||  ||align=center|0x003D||Response to the PING message. “Yes, I’m here.”
 
|-
 
|-
 
|}
 
|}

Revision as of 14:27, 13 November 2007

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. In AlphaCom E the protocol can also be encapsulated in TCP/IP.
  • 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

Message Formats - Grouped by Function

See also


Station Connect Operations

Message Short name Message no, Hex Description
CALL_SETUP CALL 0x0008 Sets up a coversation between two users
CONN_REQUEST CONN 0x000A Sets up a coversation between two users
CONN_REFERENCE   0x000B Positive response from the exchange to CONN_REQUEST
CONN_REF_ACK   0x000E The external application acknowledges the CONN_REFERENCE
STATION_BUSY   0x000D Negative response to CONN_REQUEST
RESOURCE_BUSY   0x003E Negative response to CONN_REQUEST
NO_ACCESS   0x003F Negative response to CONN_REQUEST
STATION_DOWN   0x000C Negative response to CONN_REQUEST
DISCON_ST   0x008E Disconnect station from ongoing feature
DISC_REQ   0x0011 Conversation established with CONN_REQUEST: The external application disconnects a conversation.
DISC_REQ_ACK   0x0012 Conversation established with CONN_REQUEST: The AlphaCom acknowledges the DISC_REQ message
DISCONNECTED   0x000F Conversation established with CONN_REQUEST: Conversation was disconnected, e.g. the user pressed C-key
DISCONNECTED_ACK   0x0010 Conversation established with CONN_REQUEST: Acknowledge of the DISCONNECTED message
CALL_STATUS_BC   0x0040 Broadcast message telling the status of a call
CONN_STATUS_BC   0x0041 Broadcast message telling that a connection is established
DISCON_STATUS_BC   0x0042 Broadcast message telling that a connection is disconnected
PARK_INQ_BROKER INQ 0x0086 Park station from conversation, enter Inquiry call state
UNPARK   0x0087 Unpark station from Inquiry call state station, return to conversation
REQ_TRANSF_CALL TRFC 0x0088 Transfer call in an Inquiry Call situation.
PAR_RING 0x0098 Add a Parallel Ringer station to a call in ringing state



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 Short name Message no, Hex Description
DIAL_DIGITS DD 0x0050 Simulate digit dialing from a station
DIAL_DAK   0x0094 Dial DAK on a station
SINGLE_DIGIT DIG 0x0051 Dial one digit on a station
DIGIT_RELEASE DREL 0x0052 The station has released a digit press
M_KEY M 0x0054 Order station to press M-key
M_KEY_RELEASE MREL 0x0055 Order station to release M-key
HANDSET_OFF HOFF 0x0056 Order station to lift handset
HANDSET_ON HON 0x0057 Order station to replace handset
C_KEY C 0x0058 Order station to press C-key
DISPLAY_TEXT DSPL 0x005A Send text and control characters to a station
ST_BUSY_BC   0x0036 Broadcast message: Intercom station is busy
ST_FREE_BC   0x0037 Broadcast message: Intercom station is free



Station Features and Status

Message Short name Message no, Hex Description
PROGRAM PROG 0x0001 Set audio program for single station or a predefined group of stations
PROGRAM_ACK   0x0003 Positive response to PROGRAM
PROGRAM_NAK   0x004D Negative response to PROGRAM
PROG_CONF CONF 0x0004 Set Simplex conference for predefined group of stations or a single station
PROG_CONF_ACK   0x0006 Positive response to PROG_CONF
PROG_CONF_NAK   0x004E Negative response to PROG_CONF
CONF_TALK   0x008B Set Simplex conference speaker
CONF_TALK_STOP   0x008C Stop station form feeding Simplex conference
AUDIO_DETECT VOX 0x0053 Triggers the event Simplex_Conference_Audio
O_DUPL_CONF ODC 0x006F Include/exclude a station or a group into/from an Open Duplex Conference
OD_CONF_ENTERED   0x0076 The participant has entered an Open Duplex Conference
OD_CONF_LEAVE   0x0071 The participant has left the Open Duplex Conference
ALARM_MSG ALRM 0x0007 Set up (or disconnect) an ASVP Alarm message to a single station or a predefined group of stations
ALARM_MSG_ACK   0x0009 Positive response to ALARM_MSG
ST_GROUP_DISCON SGD 0x0074 Switch off Group Call audio at a station that receives Group Call audio at the moment
SET_CALL_REQ_MODE SCRM 0x006C Turn on/off message “your call is registered, please wait”, then ringing/flashing at a station
CALL_TRANSFER TRF 0x0044 Set or remove call transfer for a station
CALL_TRANSFER_OK   0x0045 Positive response to CALL_TRANSFER
CALL_TRANSFER_NOK   0x0046 Negative response to CALL_TRANSFER
SET_REQ_TRANSF SCRT 0x002B Set transfer of Call Request for an intercom station
GET_REQ_TRANSF   0x002C Get the Call Request Transfer status for an intercom station
REQ_TRANSF   0x002D Response to the SET_REQ_TRANSF and GET_REQ_TRANSF messages
SET_ABSENCE SABS 0x0028 Set absence status for an intercom station
GET_ABSENCE GABS 0x0029 Get absence status for an intercom station
ABSENCE_STATUS   0x002A Response to SET_ABSENCE and GET_ABSENCE messages
WAKE_UP   0x0047 Register or remove wake­up request
WAKE_UP_ACK   0x0048 Positive response to WAKE_UP
WAKE_UP_NAK   0x0049 Negative response to WAKE_UP
SET_GRP_FILT GFLT 0x007D Set group call filter for a station
GROUP_MEMBERSHIP GRM 0x0081 Set group membership in NVRAM for a station
EXT_FEATURE_BC   0x0043 Broadcast message when a directory number (feature 50) is dialed on a station
SET_STATION_COS SSC 0x0090 Set COS membership in NVRAM for a station
MODIFY_COS_CONTENTS MCC 0x0091 Modify feature membership in COS in NVRAM
DTMF_CONN   0x0097 Generate DTMF tone during conversation (Only during conversation with RingMaster)
TEMP_PROG TPROG 0x0096 Temporarily "mute" program distribution to a station



Station Mail Operations

Message Short name Message no, Hex Description
SEND_MAIL SM 0x0031 Send a mail message to an intercom station
SEND_TXT_MAIL STM 0x0032 Send a mail message with free text to an intercom station
SEND_MAIL_ACK   0x0033 Response to the SEND_MAIL and SEND_TEXT_MAIL messages
CANCEL_MAIL CANM 0x0065 Delete one or more mail/call request/alarm messages queued at a station
SET_MAIL_TIMEOUT SMT 0x0082 Set the timer of a mail queue entry
COPY_MAIL CPYM 0x0083 Send a copy of a mail in own queue to a new destination (station or group)
MAILQ_NAVIG   0x008D Do operation on mail queue, or step current mail in mail queue
DELETE_MAIL DELM 0x0034 Delete a mail entry in the queue for an intercom station
DELETE_MAIL_ACK   0x0035 Response to the DELETE_MAIL message
GET_FIRST_MAIL   0x002E Get the first mail entry in the queue for an intercom station
GET_LAST_MAIL   0x0064 Get the last mail entry in the queue for an intercom station
GET_NEXT_MAIL   0x002F Get the next mail entry in the queue for an intercom station
GET_PREV_MAIL   0x0063 Get the previous mail entry in the queue for an intercom station
GET_THIS_MAIL   0x004A Get the identified mail entry in the queue for an intercom station
EXT_MAIL   0x0030 Response to the GET_x_MAIL messages
Q_ELEM_ADDED   0x004B Broadcast message. Reports that a mail message has been added to a station’s mail queue
Q_ELEM_REMOVED   0x004C Broadcast message. Reports that a mail message has been removed from a station’s mail queue



General Exchange Control

Message Short name Message no, Hex Description
SET_SYSTEM_TIME SST 0x0027 Set the internal clock to the given date and time
GET_SYSTEM_TIME GTS 0x0025 Ask a device (AlphaCom) for date and time
SYSTEM_TIME   0x0026 Response to the GET_SYSTEM_TIME and SET_SYSTEM_TIME message
PUT_STRING   0x0073 Output String to Exchange serial port after adding appropriate framing depending on selected port
LOG_STRING LOG 0x0075 Output String to System Log
EXECUTE_COMMAND X 0x004F Send a command string to the exchange to be executed there
EVENT_REPORT ER 0x0067 Report an event to the event/action system
SET_TIMER ST 0x008F Start or stop a timer
WRITE_USER_DEF_DATA WUDD 0x008A Write User Defined Data (UDD)
SET_DIRNO_TXT   0x0077 Change the display text of a directory number (station or feature)
NAME_EXTENSION   0x0080 Special exchange mode using two line names: Send the second line through AlphaNet
SNV SNV 0x0095 Update specific system settings (NVRAM) values
STATUS_REPORT   0x0072 Report equipment Presence and Error/OK status
COMMAND_RESPONSE   0x0066 General response message to messages
ILLEGAL_PARAM   0x023 Negative response
DPMT_INVALID   0x0000 Reserved value for internal use
DUMMY   0xFFFE 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 Short name Message no, Hex Description
RESET_TAKEN RSTT 0x0038 A device reports that it has done an internal reset
RESET_DEVICE RESET 0x0039 Reset a device
GET_DEVICE GDEV 0x003A Get information from an external device
DEVICE_INFO   0x003B Response to the GET_DEVICE message
PING   0x003C Test device: “Are you there?”
PONG   0x003D Response to the PING message. “Yes, I’m here.”



Remote Control

Message Short name Message no, Hex Description
SET_LOGICAL_RCO SLRC 0x006B Set or clear a logical RCO
RCO_CHANGED RCOC 0x0085 New RCO state reported from the exchange
RCI_CHANGED $RCIC 0x0084 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 Short name Message no, Hex Description
GET_PIN_COUNTS GPC 0x0013 Query a RIO about number of output and input pins and support for non mandatory features
PIN_COUNTS   0x0014 Response to the GET_PIN_COUNTS message
SET_RCO SET 0x0014 Turn the given remote control output on
SET_RCO_OK   0x0019 Positive response to the SET_RCO message
SET_RCO_FAILED   0x001A Negative response to the SET_RCO message
CLEAR_RCO CLR 0x0015 Turn the given remote control output off
CLEAR_RCO_OK   0x0016 Positive response to the CLEAR_RCO message
CLEAR_RCO_FAILED   0x0017 Negative response to the CLEAR_RCO message
PULSE_RCO PULS 0x001B Generate a pulse with the defined length
PULSE_RCO_OK   0x001C Positive response to the PULSE_RCO message
PULSE_RCO_FAILED   0x0022 Negative response to the PULSE_RCO message
POLL_RCI POLL 0x001D Poll the given remote control input once
SCAN_RCI_ONCE SCAN 0x0020 Scan input until defined condition is met, then report to exchange
SCAN_RCI_ACK   0x0021 Positive response to the SCAN_RCI_ONCE message
RCI_IS_ON   0x001F Response to the POLL_RCI and SCAN_RCI_ONCE messages, input pin is on
RCI_IS_OFF   0x001E Response to the POLL_RCI and SCAN_RCI_ONCE messages, input pin is off
SCAN_END_ACK   0x0024 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 Short name Message no, Hex Description
AUDIO_PATH_SETUP   0x8001 Set up audio path between a source node and a destination node (possibly via transit nodes)
AUDIO_CODEC   0x801D Message sent in the direction of start node, from end node or trans-coding nodes along the path
AUDIO_PATH_OK   0x8002 End to end message: Audio path is ready
AUDIO_LINK_OK   0x8003 Response to AUDIO_PATH_SETUP. Channel number is OK
AUDIO_PATH_STATE   0x801E SIP Response to AUDIO_PATH_SETUP
STATION_INFO   0x801F SIP update of number and display text
AUDIO_LINK_NOT_AVAILABLE   0x8006 Response to AUDIO_PATH_SETUP from next node: Channel not granted
AUDIO_PATH_DISCONNECT   0x8006 Release the end­to­end audio path. Normal disconnect from source or destination
AUDIO_LINK_RELEASE   0x8005 Used to release audio path backwards stepwise from node to node when setup meets busy or faulty link
STATION_LISTEN   0x0061 Message from remote exchange. Set station in listen mode. Shut mic
STATION_CONVERSATION   0x0060 Message from remote exchange. Set station in conversation mode. Stop tone and open mic.
STATION_TRANSFER   0x0062 Message from remote exchange: Transfer of B subscriber.
CHECK_AUDIO_PATH   0x800E Check of established audio path at regular intervals
AUDIO_PATH_CHECK_OK   0x800F Positive response to CHECK_AUDIO_PATH
AUDIO_CH_LOOPBACK_REQ   0x8010 Request for loopback audio connection. Used by the Audio Channel Testing process
AUDIO_CH_LOOPBACK_ACK   0x8011 Positive acknowledge of AUDIO_CH_LOOPBACK_REQ
AUDIO_CH_FAULTY   0x8013 Response to AUDIO_CH_LOOPBACK_REQ: Requested channel was faulty
LOOPBACK_IMPOSSIBLE   0x8014 Response to AUDIO_CH_LOOPBACK_REQ
AUDIO_CH_DISCON   0x8012 Disconnect a audio channel after loopback test
AUDIO_CH_TONE_REQ   0x8015 Request a peer exchange to put a 500Hz tone on a audio channel
AUDIO_M_PATH_SETUP   0x8016 Communication in a multi-node network
AUDIO_M_PATH_OK   0x8017 Contains statuses for an AUDIO_M_PATH_SETUP from one or more destination exchanges
AUDIO_M_LINK_OK   0x8019 Per­ hop positive response to AUDIO_M_PATH_SETUP
AUDIO_M_PATH_BACKTRACK   0x8018 AUDIO_M_PATH_SETUP failed
VCP_MEET_REQ   0x0069 Request answer to global group call
BUILD_GLOB_GRP   0x0070 Broadcast message to all exchanges to make them rebuild global group indexes
GLOB_GRP_MEMB   0x006A A exchange tells which global groups this exchange is member of by broadcasting this to all exchanges
RESET_AUDIO_LINK   0x8000 Reset audio link between nodes. Message not used in current AlphaCom version
CONF_JOIN   0x0078 Exchange wants to join conference, asks root-exchange to setup connection back to sender
CONF_MEMB_CHK   0x0079 Ask whether any neighbor exchange has any ordinary member left in conference
CONF_ORD_MEMB   0x007A An exchange tells its neighbors that it has ordinary member left in conference
CONF_IS_ROOT   0x007B Broadcast message. Sender informs that it is root of conference
CONF_NOT_ROOT   0x007C Broadcast message. Sender informs that it is no longer root of conference
AUDIO_M_FEED_REQ   0x801A Global Simplex Conference: Some station is pressing the M-key when participating in a conference
AUDIO_M_FEED_STOP   0x801B Global Simplex Conference: The station is releasing the M-key
AUDIO_PATH_DELAY   0x8007 Set Duplex switch delay



System Maintenance

Message Short name Message no, Hex Description
SET_NODE_NUMBER   0x006D Change the node number of an exchange
ROUTE_ALPHAPRO_MSG   0x006E Send AlphaPro message via AlphaNet to/from a remote node
CONSOLE_REQ   0x007E Log on to system debug console (TST)
CONSOLE_DISC   0x007F Log off from system debug console (TST)



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.
  • 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!