Difference between revisions of "Devices - Message Sequences"
From Zenitel Wiki
(→Device Down) |
(→Related articles) |
||
| (36 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| + | {{A}} | ||
Some DP messages are part of a message sequence. The most common sequences are documented here, with comments on timeouts etc. | Some DP messages are part of a message sequence. The most common sequences are documented here, with comments on timeouts etc. | ||
| − | |||
==Devices== | ==Devices== | ||
===Device Types === | ===Device Types === | ||
| − | The protocol has a UINT1 value (Device Type) for identifying types of devices. Current types are: | + | The protocol has a UINT1 value (Device Type) for identifying types of [[device|devices]]. Current types are: |
Device Type Description | Device Type Description | ||
0 0x00 Illegal | 0 0x00 Illegal | ||
| − | 1 0x01 AlphaCom Intercom Exchange | + | 1 0x01 AlphaCom Intercom Exchange |
| − | 2 0x02 RIO | + | 2 0x02 RIO Remote I/O unit with RCIs and RCOs |
| − | 3 0x03 Control Handler PC with call queuing features | + | 3 0x03 Control Handler PC with call queuing features |
| − | 4 0x04 Operator | + | 4 0x04 Operator Passive device, for Simple Link Layer terminal |
| − | 255 0xFF Unknown External computer with unspesific functionality | + | 255 0xFF Unknown External computer with unspesific functionality |
| − | |||
===Control Up === | ===Control Up === | ||
[[File:ControlUP.PNG|thumb|250px|Control Up]] | [[File:ControlUP.PNG|thumb|250px|Control Up]] | ||
| Line 22: | Line 21: | ||
The device responds with the [[DEVICE_INFO]] message and normal operation begins. | The device responds with the [[DEVICE_INFO]] message and normal operation begins. | ||
| − | |||
| − | ISO1745: The Control Device starts polling all devices in it’s table immediately. | + | The device periodically receives a <[[PING]]> message (are you alive?) which is answered by a <[[PONG]]> message (I’m alive). The AlphaCom Pings it’s devices every 40 seconds, and uses 1,1 second between each device. |
| + | |||
| + | [[ISO_Data_Link_Layer | ISO1745]] and [[Stentofon_Multidrop_protocol | SMD]]: The Control Device starts polling all devices in it’s table immediately. | ||
<br style="clear:both;" /> | <br style="clear:both;" /> | ||
===Device Up=== | ===Device Up=== | ||
| + | [[File:DeviceUP.PNG|thumb|250px|Device Up]] | ||
When a device comes up, either by power on, internal or external reset, it will inform the Control Device immediately by sending a [[RESET_TAKEN]] message. | When a device comes up, either by power on, internal or external reset, it will inform the Control Device immediately by sending a [[RESET_TAKEN]] message. | ||
Before AMC 07.09: No active reporting of reset, so procedure for “device down” as described below was always used. | Before AMC 07.09: No active reporting of reset, so procedure for “device down” as described below was always used. | ||
| − | Then it waits for a [[ | + | Then it waits for a [[RESET_DEVICE]] and/or [[GET_DEVICE]] message. These are the only two messages the device will handle in this state. All other messages are acknowledged and discarded. A device is by default set to this state upon power on/reset. This means that previous programming is cleared and there is no events to report. |
| − | + | [[ISO_Data_Link_Layer | ISO1745]] : The Link Layer is notified and the device is polled for messages. To avoid reset looping, the Control Device will not react to [[RESET_TAKEN]] in all start-up states. <br> | |
| + | [[Stentofon_Multidrop_protocol | SMD]] : The Link Layer is always polling all devices. | ||
<br style="clear:both;" /> | <br style="clear:both;" /> | ||
===Device Down === | ===Device Down === | ||
| − | The Control Device knows a device is down, or has been reset, when it does not respond on the [[PING]] message. The AlphaCom requires | + | [[File:DeviceDOWN.PNG|thumb|250px|Device Down]] |
| + | The Control Device knows a device is down, or has been reset, when it does not respond on the [[PING]] message. The AlphaCom requires 2 missing [[PONG]]s before reporting “device error” | ||
| − | (40 seconds * | + | (40 seconds * 2 = 80 seconds). |
If the [[PING]]s times out, a [[RESET_DEVICE]] message is sent to the device and the procedure follows the same pattern as described for “Control Up”. | If the [[PING]]s times out, a [[RESET_DEVICE]] message is sent to the device and the procedure follows the same pattern as described for “Control Up”. | ||
| Line 48: | Line 51: | ||
This operation continues until the device is up again or the Control Device is informed not to control this device. | This operation continues until the device is up again or the Control Device is informed not to control this device. | ||
| − | ISO1745: | + | [[ISO_Data_Link_Layer | ISO1745]] and [[Stentofon_Multidrop_protocol | SMD]]: The device is polled continuously even when not responding (required to detect [[RESET_TAKEN]] at any time). |
Before AMC 07.09: If a device is down (unavailable), the Link Layer is informed (table updated), and the device is not polled for messages. | Before AMC 07.09: If a device is down (unavailable), the Link Layer is informed (table updated), and the device is not polled for messages. | ||
| Line 60: | Line 63: | ||
==Conversation set-up / cancel== | ==Conversation set-up / cancel== | ||
===General=== | ===General=== | ||
| − | There | + | There are two ways to handle conversations from an external computer: |
| − | *Dedicated computer control ([[CONN_REQUEST]]) | + | *'''Dedicated computer control ([[CONN_REQUEST]])''' |
| − | There is a number of DP messages intended for set-up and monitoring of conversations. All commands are acknowledged by response messages. Each conversation is assigned a “connection reference” number that must be used by later data commands. | + | :There is a number of DP messages intended for set-up and monitoring of conversations. All commands are acknowledged by response messages. Each conversation is assigned a “connection reference” number that must be used by later data commands. |
| − | *Station emulation ([[DIAL_DIGITS]]) | + | *'''Station emulation ([[DIAL_DIGITS]])''' |
| − | The computer can simulate use of an intercom station. There are no direct acknowledgements, but it’s possible to monitor broadcast messages that will indicate success on the functional level. All commands use the station dir.no as reference. | + | :The computer can simulate use of an intercom station. There are no direct acknowledgements, but it’s possible to monitor broadcast messages that will indicate success on the functional level. All commands use the station dir.no as reference. |
The first method is best for computer control, but the second one will also work. In both cases, the computer should use timers to supervise the success of each command, and re-transmit the command if timeout. | The first method is best for computer control, but the second one will also work. In both cases, the computer should use timers to supervise the success of each command, and re-transmit the command if timeout. | ||
| − | AlphaNet makes things more complicated. [[ | + | AlphaNet makes things more complicated. [[CONN_REQUEST]] is supported for AlphaNet set-up from AMC 07.60. Broadcasts of station events are only transmitted in the local exchange, and they contain only a reference to the AlphaNet audio channel, not the dir.no from the remote exchange. This can be solved using the Event Handler to send DP messages. |
One external computer can control many simultaneous conversations, of course. As usual, the response messages are identified with the <reference> field from command messages’ application headers. | One external computer can control many simultaneous conversations, of course. As usual, the response messages are identified with the <reference> field from command messages’ application headers. | ||
| Line 73: | Line 76: | ||
===Dedicated computer control=== | ===Dedicated computer control=== | ||
====Call Set-up==== | ====Call Set-up==== | ||
| + | [[File:CallSetup.PNG|thumb|250px|Call Setup]] | ||
If [[CONN_REQUEST]] results in a conversation, AlphaCom creates a call-object, and responds with a reference to this object. The external application must use this call-reference in all following messages to the AlphaCom. | If [[CONN_REQUEST]] results in a conversation, AlphaCom creates a call-object, and responds with a reference to this object. The external application must use this call-reference in all following messages to the AlphaCom. | ||
| Line 78: | Line 82: | ||
If the exchange does not receive [[CONN_REF_ACK]], [[CONN_REFERENCE]] will be retransmitted. This means that the external application must be able to handle several [[CONN_REFERENCE]] with identical <conn_ref>. | If the exchange does not receive [[CONN_REF_ACK]], [[CONN_REFERENCE]] will be retransmitted. This means that the external application must be able to handle several [[CONN_REFERENCE]] with identical <conn_ref>. | ||
| + | <br style="clear:both;" /> | ||
====Call Cancel==== | ====Call Cancel==== | ||
| − | + | [[File:CallCancel.PNG|thumb|250px|Call cancel]] | |
The conversation is cancelled immediately when [[DISC_REQ]] is received. | The conversation is cancelled immediately when [[DISC_REQ]] is received. | ||
| − | See also general comments | + | See also general comments below. |
| + | <br style="clear:both;" /> | ||
| + | ====Conversation Disconnected by station==== | ||
| + | [[File:ConvDiscon.PNG|thumb|250px|Conversation Disconnected by station]] | ||
| + | The exchange informs the external application that an on-going conversation has been cancelled by some event in the exchange (C-key from any station, or priority applied from some other station). | ||
| + | '''Note:''' If the conversation was set up with <req.ack> = 1, the external application MUST handle the DISCONNECTED message. | ||
| − | + | See also general comments below. | |
| − | + | <br style="clear:both;" /> | |
| − | |||
| − | |||
| − | |||
| − | See also general comments | ||
====Notes to implementation==== | ====Notes to implementation==== | ||
| − | *AMC waiting: xxx_ACK message state | + | *'''AMC waiting: xxx_ACK message state''' |
| − | Whenever the exchange waits for an _ACK message, the DP message receiver is in a state which just accepts the awaited _ACK message. The exchange uses a 10 sec. timer, and does 2 more retransmissions. This means that if the external application gets “out of synch” with the exchange, the exchange will ignore set-up or cancel for max. 30 seconds, then things comes to life again. | + | :Whenever the exchange waits for an _ACK message, the DP message receiver is in a state which just accepts the awaited _ACK message. The exchange uses a 10 sec. timer, and does 2 more retransmissions. This means that if the external application gets “out of synch” with the exchange, the exchange will ignore set-up or cancel for max. 30 seconds, then things comes to life again. |
| − | - Note AMC softwares before version 08.00: The DP message handler processes one DP message at a time internally, and awaits internal success messages before a response is returned to the external application. If an internal abnormal situation occurred, the DP message handler could get stuck and all DP message processing would hang until reset. This is handled by an internal timeout from AMC 08.00. | + | :- Note AMC softwares before version 08.00: The DP message handler processes one DP message at a time internally, and awaits internal success messages before a response is returned to the external application. If an internal abnormal situation occurred, the DP message handler could get stuck and all DP message processing would hang until reset. This is handled by an internal timeout from AMC 08.00. |
| − | *AMC sending: xxx_ACK message information | + | *'''AMC sending: xxx_ACK message information''' |
| − | The _ACK messages from the exchange gives no information about timing of conversation set-up/cancel. They are only a DP functional acknowledge of the preceding command. | + | :The _ACK messages from the exchange gives no information about timing of conversation set-up/cancel. They are only a DP functional acknowledge of the preceding command. |
| − | *The various Data Link Layers introduces delays | + | *'''The various Data Link Layers introduces delays''' |
| − | The worst case is ISO1745 point-to-point which polls the external computer only once per second (default value, can be changes using TST). This means that manual handling of a station (dialing, C-key) can occur asynchronously with DP message handling of the same station, which in turn means that the external application gets “out of synch” with the exchange for a period. | + | :The worst case is ISO1745 point-to-point which polls the external computer only once per second (default value, can be changes using TST). This means that manual handling of a station (dialing, C-key) can occur asynchronously with DP message handling of the same station, which in turn means that the external application gets “out of synch” with the exchange for a period. |
===Station emulation=== | ===Station emulation=== | ||
====Call Set-up==== | ====Call Set-up==== | ||
| + | [[File:CallSetup2.PNG|thumb|250px|Call Setup]] | ||
It’s possible to dial any directory number, both stations and features. | It’s possible to dial any directory number, both stations and features. | ||
| Line 113: | Line 120: | ||
A successful open conversation finally causes a [[CONN_STATUS_BC]] broadcast message. This message contains a <conn_ref> that must be stored to mach future [[DISCON_STATUS_BC]] messages (if needed). | A successful open conversation finally causes a [[CONN_STATUS_BC]] broadcast message. This message contains a <conn_ref> that must be stored to mach future [[DISCON_STATUS_BC]] messages (if needed). | ||
| + | <br style="clear:both;" /> | ||
====Call Cancel==== | ====Call Cancel==== | ||
| − | + | [[File:CallCancel2.PNG|thumb|250px|Call cancel]] | |
Any on-going activity on a station can be terminated using a [[C_KEY]] message. | Any on-going activity on a station can be terminated using a [[C_KEY]] message. | ||
| + | |||
Remember that C_KEY in idle will cancel audio program, so don’t use too many C_KEYs just to be safe…. | Remember that C_KEY in idle will cancel audio program, so don’t use too many C_KEYs just to be safe…. | ||
| − | + | <br style="clear:both;" /> | |
====Conversation Disconnected by station==== | ====Conversation Disconnected by station==== | ||
| + | [[File:ConvDiscon2.PNG|thumb|250px|Conversation Disconnected by station]] | ||
The exchange informs the external application that an on-going conversation has been cancelled by some event in the exchange (C-key from any station, or priority applied from some other station). | The exchange informs the external application that an on-going conversation has been cancelled by some event in the exchange (C-key from any station, or priority applied from some other station). | ||
| − | + | <br style="clear:both;" /> | |
====Notes to implementation==== | ====Notes to implementation==== | ||
| Line 135: | Line 145: | ||
* [[CONN_REQUEST]] has an A-sub priority setting, but if one connection is established with this priority, the next one will use the same priority and thus fail. This is considered a design flaw and will be corrected in an upcoming AMC version. CONN_REQUEST will then force the A-sub idle before setting up a new connection. | * [[CONN_REQUEST]] has an A-sub priority setting, but if one connection is established with this priority, the next one will use the same priority and thus fail. This is considered a design flaw and will be corrected in an upcoming AMC version. CONN_REQUEST will then force the A-sub idle before setting up a new connection. | ||
| − | Note also that the protocol’s requirement for command/acknowledge sequences is implemented so that further commands are not accepted while the exchange waits for an acknowledge. | + | :Note also that the protocol’s requirement for command/acknowledge sequences is implemented so that further commands are not accepted while the exchange waits for an acknowledge. |
* [[DIAL_DIGITS]] does just what the name says, and the exchange ignores digits dialled during the cancel tone. | * [[DIAL_DIGITS]] does just what the name says, and the exchange ignores digits dialled during the cancel tone. | ||
| Line 150: | Line 160: | ||
See comments for each of the various data protocol messages related to conversation. | See comments for each of the various data protocol messages related to conversation. | ||
| + | |||
| + | == Related articles== | ||
| + | [[System_integration_-_Implementation]] | ||
| + | |||
| + | |||
| + | [[Category: AMC Software]] | ||
Latest revision as of 08:21, 8 September 2017
Some DP messages are part of a message sequence. The most common sequences are documented here, with comments on timeouts etc.
Contents
Devices
Device Types
The protocol has a UINT1 value (Device Type) for identifying types of devices. Current types are:
Device Type Description 0 0x00 Illegal 1 0x01 AlphaCom Intercom Exchange 2 0x02 RIO Remote I/O unit with RCIs and RCOs 3 0x03 Control Handler PC with call queuing features 4 0x04 Operator Passive device, for Simple Link Layer terminal 255 0xFF Unknown External computer with unspesific functionality
Control Up
The Control Device normally has a table for the devices it is responsible for. When the Control Device starts (power on/reset) it begins resetting these devices, one at a time in an orderly fashion.
The reset is initiated by sending a RESET_DEVICE message to the device.
After a timeout period (default 1 second) a GET_DEVICE message follows.
The device responds with the DEVICE_INFO message and normal operation begins.
The device periodically receives a <PING> message (are you alive?) which is answered by a <PONG> message (I’m alive). The AlphaCom Pings it’s devices every 40 seconds, and uses 1,1 second between each device.
ISO1745 and SMD: The Control Device starts polling all devices in it’s table immediately.
Device Up
When a device comes up, either by power on, internal or external reset, it will inform the Control Device immediately by sending a RESET_TAKEN message.
Before AMC 07.09: No active reporting of reset, so procedure for “device down” as described below was always used.
Then it waits for a RESET_DEVICE and/or GET_DEVICE message. These are the only two messages the device will handle in this state. All other messages are acknowledged and discarded. A device is by default set to this state upon power on/reset. This means that previous programming is cleared and there is no events to report.
ISO1745 : The Link Layer is notified and the device is polled for messages. To avoid reset looping, the Control Device will not react to RESET_TAKEN in all start-up states.
SMD : The Link Layer is always polling all devices.
Device Down
The Control Device knows a device is down, or has been reset, when it does not respond on the PING message. The AlphaCom requires 2 missing PONGs before reporting “device error”
(40 seconds * 2 = 80 seconds).
If the PINGs times out, a RESET_DEVICE message is sent to the device and the procedure follows the same pattern as described for “Control Up”.
The Control Device periodically sends the RESET_DEVICE/GET_DEVICE sequence to this device. AlphaCom tries every 40 seconds for a device with status “device error”.
This operation continues until the device is up again or the Control Device is informed not to control this device.
ISO1745 and SMD: The device is polled continuously even when not responding (required to detect RESET_TAKEN at any time).
Before AMC 07.09: If a device is down (unavailable), the Link Layer is informed (table updated), and the device is not polled for messages.
Notes to implementation
The GET_DEVICE message must be implemented so that it’s allowed alone. Only the sequence RESET_DEVICE / GET_DEVICE shall change the device’s mode to normal operation. This implementation allows a data protocol tool to query for present devices independent of their operational status.
Note that both DEVICE_INFO and PONG has optional parameters intended for configuration monitoring. Especially in an AlphaNet where devices can be very far away, this information can be very useful for service purposes.
Conversation set-up / cancel
General
There are two ways to handle conversations from an external computer:
- Dedicated computer control (CONN_REQUEST)
- There is a number of DP messages intended for set-up and monitoring of conversations. All commands are acknowledged by response messages. Each conversation is assigned a “connection reference” number that must be used by later data commands.
- Station emulation (DIAL_DIGITS)
- The computer can simulate use of an intercom station. There are no direct acknowledgements, but it’s possible to monitor broadcast messages that will indicate success on the functional level. All commands use the station dir.no as reference.
The first method is best for computer control, but the second one will also work. In both cases, the computer should use timers to supervise the success of each command, and re-transmit the command if timeout.
AlphaNet makes things more complicated. CONN_REQUEST is supported for AlphaNet set-up from AMC 07.60. Broadcasts of station events are only transmitted in the local exchange, and they contain only a reference to the AlphaNet audio channel, not the dir.no from the remote exchange. This can be solved using the Event Handler to send DP messages.
One external computer can control many simultaneous conversations, of course. As usual, the response messages are identified with the <reference> field from command messages’ application headers.
Dedicated computer control
Call Set-up
If CONN_REQUEST results in a conversation, AlphaCom creates a call-object, and responds with a reference to this object. The external application must use this call-reference in all following messages to the AlphaCom.
The conversation is set up immediately when CONN_REQUEST is received.
If the exchange does not receive CONN_REF_ACK, CONN_REFERENCE will be retransmitted. This means that the external application must be able to handle several CONN_REFERENCE with identical <conn_ref>.
Call Cancel
The conversation is cancelled immediately when DISC_REQ is received.
See also general comments below.
Conversation Disconnected by station
The exchange informs the external application that an on-going conversation has been cancelled by some event in the exchange (C-key from any station, or priority applied from some other station).
Note: If the conversation was set up with <req.ack> = 1, the external application MUST handle the DISCONNECTED message.
See also general comments below.
Notes to implementation
- AMC waiting: xxx_ACK message state
- Whenever the exchange waits for an _ACK message, the DP message receiver is in a state which just accepts the awaited _ACK message. The exchange uses a 10 sec. timer, and does 2 more retransmissions. This means that if the external application gets “out of synch” with the exchange, the exchange will ignore set-up or cancel for max. 30 seconds, then things comes to life again.
- - Note AMC softwares before version 08.00: The DP message handler processes one DP message at a time internally, and awaits internal success messages before a response is returned to the external application. If an internal abnormal situation occurred, the DP message handler could get stuck and all DP message processing would hang until reset. This is handled by an internal timeout from AMC 08.00.
- AMC sending: xxx_ACK message information
- The _ACK messages from the exchange gives no information about timing of conversation set-up/cancel. They are only a DP functional acknowledge of the preceding command.
- The various Data Link Layers introduces delays
- The worst case is ISO1745 point-to-point which polls the external computer only once per second (default value, can be changes using TST). This means that manual handling of a station (dialing, C-key) can occur asynchronously with DP message handling of the same station, which in turn means that the external application gets “out of synch” with the exchange for a period.
Station emulation
Call Set-up
It’s possible to dial any directory number, both stations and features.
If a station dir.no is dialled, a CALL_STATUS_BC broadcast may be sent from the AlphaCom. Zero or more may come, if the setup progresses through camp-on-busy, private ringing and then finally open call.
A successful open conversation finally causes a CONN_STATUS_BC broadcast message. This message contains a <conn_ref> that must be stored to mach future DISCON_STATUS_BC messages (if needed).
Call Cancel
Any on-going activity on a station can be terminated using a C_KEY message.
Remember that C_KEY in idle will cancel audio program, so don’t use too many C_KEYs just to be safe….
Conversation Disconnected by station
The exchange informs the external application that an on-going conversation has been cancelled by some event in the exchange (C-key from any station, or priority applied from some other station).
Notes to implementation
Station emulation is simple to implement, as no timeouts and possible retransmissions is needed. It’s OK to use for applications where a human operator can re-send a command if the exchange does not behave as expected. On the other hand, if the external computer shall work unattended you should use the _REQUEST messages!
You can always use station emulation in mix with the safer method, as the exchange will always handle station keyboard events.
Rapid cancel/connect sequences
Rapid sequence of connection/cancel/connection must be handled with some care. This situation occurs frequently for a computer that handles a call queue, if the operator wants to go on to the next conversation just by clicking a screen symbol. The problem is the period from a cancel operation is started until the cancel tone is finished, some 200 milliseconds.
- CONN_REQUEST has an A-sub priority setting, but if one connection is established with this priority, the next one will use the same priority and thus fail. This is considered a design flaw and will be corrected in an upcoming AMC version. CONN_REQUEST will then force the A-sub idle before setting up a new connection.
- Note also that the protocol’s requirement for command/acknowledge sequences is implemented so that further commands are not accepted while the exchange waits for an acknowledge.
- DIAL_DIGITS does just what the name says, and the exchange ignores digits dialled during the cancel tone.
The current solution to this problem is to insert a delay of at least 200 ms after a cancel operation before a new operation on the same station (either the external application initiated a cancel, or the exchange informed about a cancel).
Note that slow link layers may introduce delays that hide this problem, but these delays are random and may cause operations to fail irregularly.
Use of <reference> fields
The AlphaNet data protocol has a message header <reference> field that links commands to the exchange with the response messages. The <reference> field is “owned” by the external application, and can typically be used to identify internal software processes and/or data structures.
For conversations, the <reference> field used in the initial CONN_REQUEST will be stored in the exchange. The <reference> will be used in disconnect response messages that comes later, both if the disconnect is initiated from the external application, or from the exchange.
This convention gives possible non-standard behaviour for the DISC_REQ message. But as most external applications would use an identification for the on-going conversation anyhow, it should not cause any problem. Just use same <reference> as the CONN_REQUEST that set up the conversation, then DISC_REQ will give standard behaviour!
See comments for each of the various data protocol messages related to conversation.