Actions

Difference between revisions of "DIP"

From Zenitel Wiki

('''<code>agc</code>''' - Audio Group Connect)
 
(21 intermediate revisions by 5 users not shown)
Line 1: Line 1:
DIP is the control protocol used between Stentofon IP stations and AlphaCom E exchanges. It is used for all data-communication with the IP stations, such as call control, LED settings and display text to the station, and key presses and inputs from the station.
+
{{A}}
 +
'''DIP''' is the control protocol used between STENTOFON IP stations and AlphaCom E exchanges. It is used for all data-communication with the IP stations, such as call control, LED settings and display text to the station, and key presses and inputs from the station.
  
 
DIP is short for "Display-data over IP", and refers to the ASLT display data protocol. This protocol was based on 9600 baud one-way transmission while DIP is transmitted both ways over IP (TCP and UDP).
 
DIP is short for "Display-data over IP", and refers to the ASLT display data protocol. This protocol was based on 9600 baud one-way transmission while DIP is transmitted both ways over IP (TCP and UDP).
  
The commands are written as human readable text.
+
See also ACDP message: [[DIP FWD]]
Maximum DIP message length: 500 bytes.
+
[[Category:INCA Technical Articles]]
Command parameters are separated by space (0x20).
+
[[Category:Protocols]]
Number values is coded as hex. Exception is IP adresses with dot notation 10.5.2.3.
 
Text strings are enclosed by quotes "". 
 
Text strings containing " are code as \"
 
Text constants without space can be coded without " (stu)
 
 
 
See also [[IP Station Audio Interface]] for more information on how the audio streams are set up to IP stations using DIP.
 
 
 
= Protocol specification =
 
AlphaCom side TCP port: 50001.<br>
 
Station side TCP port: (Any).<br>
 
Station side UDP port: (Specified in '''<code>con</code>''' command).
 
 
 
AlphaCom listens for IP stations on TCP port 50001. When an IP station is powered up, it connects to this port and sends the '''<code>stu</code>''' command to AlphaCom. AlphaCom then specifies UDP voice ports and optionally UDP command port with the '''<code>con</code>''' command.
 
 
 
= DIP Commands =
 
Current version: 00.04.<br>
 
 
 
== Commands from AlphaCom to IP stations: ==
 
 
 
=== '''<code>con</code>''' - Configure station ===
 
<ref> con <phy_ind> <dirno> <name> <volume> <port0> <pri0> <port1> <pri1> <port2> <pri2> ...
 
        <port_udp> <mcast-ip> <mac-addr> <backlight> <priv>
 
''Example:
 
    008 con 8 "2310    " "IP Station  " 6 EE48 2 EE4A 3 EE4C 1 C351 239.192.101.0 0013cb0006ac''
 
The '''<code>con</code>''' command is sent from AlphaCom once during startup, after the station has reported with the '''<code>stu</code>''' command. It may also be sent after AlphaCom database configuration changes.
 
:''ref'': Physical number for addressed station.
 
:''phy_ind'': Physical number of the station. This number specifies the ''ref'' parameter values used in all later commands for identifying this station.
 
:''dirno'': Text info for showing on station's display and web-page.
 
:''name'': Text info for showing on station's display and web-page.
 
:''volume'': Volume level for the station. Hex value 00-1F.
 
:''port0'': UDP port for voice logical-channel 0.
 
:''pri0'': Priority for voice logical-channel 0.
 
:''port1'': UDP port for voice logical-channel 1.
 
:''pri1'': Priority for voice logical-channel 1.
 
:''port2'': UDP port for voice logical-channel 2.
 
:''pri2'': Priority for voice logical-channel 2.
 
:''port_udp'': UDP port for DIP commands over UDP multicast (since AMCD 10.20).
 
:''mcast-ip'': Multicast address for DIP commands over UDP multicast (since AMCD 10.20).
 
:''mac-addr'': [[MAC address (AMC-IP)|MAC address]] of AlphaCom. Use to sort out "agc"/"age" messages received on multicast (since AMCD 10.23).
 
:''backlight'': Common backlight level 0-1F (since AMCD 10.43).
 
:''priv'': Station in private/open (since AMCD 10.43).
 
 
 
 
 
=== '''<code>auc</code>''' - Audio Connect ===
 
<ref> auc <port> <codec> <packetlen> <volume> <config-bitmap>
 
:''ref'': Physical number for addressed station.
 
:''amc-ip'': Remote IP address for voice stream.
 
:''port'': Remote UDP port for voice stream.
 
::Hex value 0000-FFFF.
 
:''codec'':
 
::g711u
 
::g711a
 
::g722
 
:''packetlen'':
 
::Hex value 0A (10ms), 14 (20ms).
 
:''volume'':
 
::Hex value 00-1F.
 
:''config-bitmap'':
 
::Bit:0  1 = Use station's Echo canceler for open duplex conversation.
 
::Bit:1  1 = Send Only/simplex: Send mic audio to given address, mute speaker, no echo cancel.
 
::Bit:2  1 = incoming call, 0 = outgoing call.
 
 
 
=== '''<code>aue</code>''' - Audio End ===
 
<ref> aue
 
:''ref'': Physical number for addressed station.
 
 
 
=== '''<code>agc</code>''' - Audio Group Connect ===
 
<ref> agc <logical-chan> <op> <mcast-ip> <codec> <group-bitmap> <mac-addr> <config-bitmap>
 
The '''<code>agc</code>''' command is sent over TCP (unicast) or UDP (multicast). It may come either from AlphaCom or from a forwarding IP station. Since it may be sent over unreliable UDP protocol it is repeated by the sender each 5th second. If the first message is lost, the next will probably come through.
 
:''ref'': Physical number for addressed station.
 
:''logical-chan'': Channel number for UDP voice. The channels' ports are previously congfigured by the '''<code>con</code>''' command.
 
::1 = group call
 
::2 = program distribution
 
:''op'':
 
::lst - Receive multicast and playout
 
::fwd - Receive unicast, forward to multicast and playout
 
:''mcast-ip'': Multicast IP for the group voice.
 
:''codec'':
 
::g711u
 
::g711a
 
::g722
 
:''group-bitmap'': Optional, variable length. Stations addressed by this multicast message ''in addition to'' the one addressed by ''ref''.
 
::Hex value. 0-FFFFF... One bit per station selected. '1' value in position N means station with physical no = N + ''ref'' is included. Example: ''ref''=3, bitmap=81 means that phys. no 3, 4 and 11 are included.
 
::(Since AMCD 10.23, always present, empty group is a single "0")
 
:''mac-addr'': [[MAC address (AMC-IP)|MAC address]] of AlphaCom, should match MAC address received in "con" message. Since AMCD 10.23.
 
:''config-bitmap'':
 
::0001 = Handset and volume override on station for this call.(AMCD 10.23)
 
 
 
=== '''<code>age</code>''' - Audio Group End  ===
 
<ref> age <logical-chan> <op> <group-bitmap> <mac-addr>
 
The '''<code>age</code>''' command is sent over TCP (unicast) or UDP (multicast). It may come either from AlphaCom or from a forwarding IP station. Since it may be sent over unreliable UDP protocol it may not be received, and the IP station should have implemented a timeout mechanism to simulate the  '''<code>age</code>''' command if the expected repetition of '''<code>agc</code>''' commands is missing for a long time.
 
:''ref'': Physical number for addressed station.
 
:''logical-chan'': Same as for '''<code>agc</code>''' command.
 
:''op'': Same as for '''<code>agc</code>''' command.
 
:''group-bitmap'': Same as for '''<code>agc</code>''' command.
 
:''mac-addr'': [[MAC address (AMC-IP)|MAC address]] of AlphaCom, should match MAC address received in "con" message. Since AMCD 10.23.
 
 
 
=== '''<code>bon</code>''' - Volume-boost on ===
 
<ref> bon
 
:''ref'': Physical number for addressed station.
 
 
 
=== '''<code>bof</code>''' - Volume-boost off ===
 
<ref> bof
 
:''ref'': Physical number for addressed station.
 
 
 
=== '''<code>ind stl</code>''' - Set StationLED indicator ===
 
<ref> ind stl <remindertype> <onoff>
 
:''ref'': Physical number for addressed station.
 
:''remindertype:
 
::0 = static
 
::1 = blink each 4th second (mail notification)
 
::2 = blink each 1 second (priority mail notification)
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>ind dak</code>''' - Set DAKLED indicator ===
 
<ref> ind dak <no> <indno> <blinktype> <onoff>
 
:''ref'': Physical number for addressed station.
 
:''no'':
 
::Hex value. 0-FFFF.
 
::0 = DAK 1.
 
::1 = DAK 2.
 
::...
 
::FFFF = Reset all DAK indicators.
 
:''indno'':
 
::0 = Red LED.
 
::1 = Green LED.
 
:''blinktype'':
 
::0 = static.
 
::1 = slow blink.
 
::2 = fast blink.
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>ind out</code>''' - Set Output indicator ===
 
<ref> ind out <no> <indno> <blinktype> <onoff>
 
:''ref'': Physical number for addressed station.
 
:''no'':
 
::Hex value. 0-FFFF.
 
::0 = Output 1. (On IP substation this is the Relay output).
 
::1 = Output 2. (On IP substation this is the Spare output).
 
::FFFF = Reset all output indicators.
 
:''indno'':
 
::0 = Indno 0. (On IP substation this is the only valid indno).
 
:''blinktype'':
 
::0 = static.
 
::1 = slow blink.
 
::2 = fast blink.
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>sbl</code>''' - Set Backlight (Suggestion) ===
 
<ref> sbl <type> <level>
 
:''ref'': Physical number for addressed station.
 
:''type'':
 
::0 = Common backlight level
 
::1 = Main LCD backlight.
 
::2 = Main keyboard backlight.
 
::(3 = Second LCD backlight.)
 
::(4 = Second keyboard backlight.)
 
:''level'':
 
::Hex value 00-1F
 
 
 
=== '''<code>tone</code>''' - Output tone ===
 
<ref> tone <frequency> <volume> <on_len> <off_len> <on_duration> <off_duration>
 
:''ref'': Physical number for addressed station.
 
:''frequency'':
 
::0 = Turn off tone.
 
::1 ->  = Frequency in Hz
 
:''volume'': Volume for the tone. Independent of station's normal audio volume.
 
::Hex value 00-1F.
 
:''on_len'': On-length to play the tone. 1ms resolution.
 
::Hex value 0-FFF (4 sec max)
 
::0 ->  = length in 1 ms resolution.
 
:''off_len'': Off-length to mute the tone. 1ms resolution.
 
::Hex value 0-FFF (4 sec max)
 
::0 = Play the tone continuously. (Note: Value for ''on_len'' doesn't matter.)
 
::1 ->  = length in 1 ms resolution.
 
:''on_duration'': On-duration to play the ''on_len''/''off_len'' pattern.
 
::Hex value 0-28F4 (1048 sec max)
 
::0 = endless
 
::1 ->  = duration in 100 ms resolution.
 
:''off_duration'': Off-duration to mute the ''on_len''/''off_len'' pattern.
 
::Hex value 0-28F4 (1048 sec max)
 
::0 = Play the pattern for ''on_duration'' time, then stop.
 
::1 ->  = duration in 100 ms resolution.
 
 
 
=== '''<code>bleep</code>''' - Bleep (obsolete) ===
 
<ref> bleep <type> <duration on> <duration off> <volume>
 
:''ref'': Physical number for addressed station.
 
:''type'':
 
::0 = No tone (Turn off)
 
::1 = 500Hz
 
::2 = 400Hz
 
::3 = xxx
 
::4 = xxx
 
::5 = Configurable 1
 
::6 = Configurable 2
 
::7 = Configurable 3
 
::8 = Configurable 4
 
:''duration on'':
 
::1 ->  = duration in 100 ms resolution
 
:''duration off'':
 
::1 ->  = duration in 100 ms resolution
 
:''volume''
 
::Hex value 00-1F.
 
 
 
=== '''<code>vol</code>''' - Set station volume ===
 
<ref> vol <volume>
 
:''ref'': Physical number for addressed station.
 
:''volume''
 
::Hex value 00-1F.
 
 
 
=== '''<code>private</code>''' - Set station Open/Private state ===
 
<ref> private <private state>
 
:''ref'': Physical number for addressed station.
 
:''private state''
 
::Hex value 0 = OFF, 1 = ON.
 
 
 
=== '''<code>ping</code>''' - Ping ===
 
<ref> ping
 
:''ref'': Physical number for addressed station.
 
 
 
=== '''<code>mping</code>''' - Multicast Ping ===
 
<ref> mping <op> <mac_addr>
 
:''ref'': Physical number for addressed station, which is supposed to reply with mpong.
 
:''op'':
 
::lst - Receiver should reply with mpong
 
::fwd - Receive unicast, forward to multicast
 
:''mac_addr'': MAC address of AlphaCom. Should match the MAC address given in the "con" message.
 
 
 
AlphaCom tests that stations configured for multicast / relayed multicast, can be reached with multicast DIP messages. The mpong message is transmitted following the same rules as the "agc" and "age" message, except that a mping message only addresses one single station.
 
 
 
This test does not test for RTP reachability, see "err rtp" message for that.
 
 
 
== Display Text Support (Under construction) ==
 
 
 
The first implementation is based on the TouchLine (TL) display text output from AlphaCom converted to DIP. <br\>
 
(A later version might be based on HTML pages for extended graphical features.)
 
 
 
'''TL -> DIP changes'''
 
For DIP clarity the original TL protocol control characters is replaced with separate DIP commands.
 
For language support the text is coded in [[Wikipedia:UTF-8|UTF-8]]
 
[[UniCode supported]]
 
 
 
=== '''<code>dite</code>''' - Display a line of text on specified line and position (Suggestion) ===
 
(New format, suggested 2008-03-17:)
 
<ref> dite <disp> <font_> <flags> <posx> <posy> <text>
 
:''ref'': Physical number for addressed station.
 
:''disp'': Display number.
 
::1 = Main display (size 128x64 pixels).
 
:''font_'': Font type
 
::1 = 5x8  (horizontal spacing +1 pixel = 6 pixels width).
 
::2 = 8x15  (horizontal spacing included).
 
::3 = 10x16  (horizontal spacing +2 pixels = 12 pixels width).
 
:''flags'': Flags
 
::0001 = Inverted.
 
:''posx'': Horizontal position from left to right. Denotes left edge position of first character.
 
::Hex value  (Main display: 00-7F = 128 pixels)
 
:''posy'': Vertical position from top to bottom. Denotes top edge position of first character.
 
::Hex value  (Main display: 00-3F = 64 pixels)
 
:''text'': Display text coded as [[Wikipedia:UTF-8|UTF-8]]
 
(Old format:)
 
<ref> dite <disp> <line> <pos> <text>
 
:''ref'': Physical number for addressed station.
 
:''disp'': Display number.  ( 1 is main display, 2 is DAK display)
 
:''line'': Line number. ( 1 - 4 for main display, 1 - 100 for DAK display )
 
:''pos'':  Position on the line.( 1 - 20 )
 
:''text'': Display text coded as [[Wikipedia:UTF-8|UTF-8]]
 
 
 
=== '''<code>dicls</code>''' - Clear the display ===
 
<ref> dicls <disp>
 
(Parameters as described for '''<code>dite</code>''')
 
 
 
=== '''<code>dicb</code>''' - Start cursor blink at a specified position. ===
 
<ref> dicls <disp> <line> <pos>
 
(Parameters as described for '''<code>dite</code>''')
 
 
 
=== '''<code>dici</code>''' - Cursor invisible. ===
 
<ref> dicls <disp>
 
(Parameters as described for '''<code>dite</code>''')
 
 
 
=== '''<code>dicmd</code>''' - Send User Defined Command ([[DISPLAY_TEXT|$DSPL]])===
 
<ref> dicmd <payload>
 
:''ref'': Physical number for addressed station.
 
:''payload'': User defined array 0 - 50 bytes (HEX coded)
 
 
 
All commands sent by the $DSPL DP command not related to the ToutchLine display control are tunneled to the dicmd message.<br\>
 
Display Commands not forwarded:<br\>
 
0x00 -> 0x43
 
0x50 -> 0x5F
 
0xF0 -> 0xFF
 
 
 
Example:
 
[[DISPLAY_TEXT|$DSPL L101 U4 60AB0812]]
 
1 dicmd 60AB0812
 
Send user defined command to station 1 with 4 bytes of payload (firt byte is command).
 
 
 
== Commands from IP stations to AlphaCom: ==
 
=== '''<code>stu</code>''' - Station Up ===
 
<ref> stu <mac_addr> <ip> <dip_version> <sw_type> <sw_version> <hw_type> <hw_version>
 
''Example: 1 stu 0013cb00086c 10.5.101.48 00.02 A100G80222 01.01 8022 1''
 
This message is sent from IP station to AlphaCom once the TCP connection is established.
 
:''ref'': Physical number of the sending station.
 
:''mac_addr'': MAC address of the IP station.
 
::Format: 001122334455
 
:''ip'': IP address of the IP station.
 
:''dip_version'': DIP protocol version number used by IP station.
 
::Format: XX.XX (decimal).
 
:''sw_type'':
 
::A100G80222 - IP substation software
 
:''sw_version'':
 
::Format: XX.XX (decimal).
 
:''hw_type'':
 
::8021 - IP substation, old type (without RJ connectors).
 
::8022 - IP substation.
 
:''hw_version'':
 
::Format: X (decimal).
 
 
 
=== '''<code>evt inp</code>''' - Station Input Event ===
 
<ref> evt inp <no> <onoff>
 
:''ref'': Physical number of the sending station.
 
:''no'': Input no as specified by IP station hardware.
 
::0 = Input 1. (Key input 1 on IP substation).
 
::1 = Input 2. (Key input 2 on IP substation).
 
::2 = Input 3. (Key input 3 on IP substation).
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt key</code>''' - Station Key Event ===
 
<ref> evt key <no> <onoff>
 
:''ref'': Physical number of the sending station.
 
:''no'': Key no.
 
::0-9 = digits 0-9.
 
::0A  = *  (TODO: Verify this!)
 
::0B  = #  (TODO: Verify this!)
 
::(TODO: Add more key definitions for menu control keys here?)
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt mkey</code>''' - Station M-key Event ===
 
<ref> evt mkey <onoff>
 
:''ref'': Physical number of the sending station.
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt ckey</code>''' - Station C-key Event ===
 
<ref> evt ckey <onoff>
 
:''ref'': Physical number of the sending station.
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt dak</code>''' - Station DAK key Event ===
 
<ref> evt dak <no> <onoff>
 
:''ref'': Physical number of the sending station.
 
:''no'': DAK key no.
 
::0-... = DAK key 0-....
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt func</code>''' - Station Function key Event ===
 
<ref> evt func <no> <onoff>
 
:''ref'': Physical number of the sending station.
 
:''no'':
 
::0-3 = Function key 0-3 (keys below main LCD).
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt vke</code>''' - Station Volume key Event ===
 
<ref> evt vke <no> <onoff>
 
:''ref'': Physical number of the sending station.
 
:''no'':
 
::0 = Volume down key
 
::1 = Volume up key
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt blk</code>''' - Station Backlight key Event ===
 
<ref> evt blk <no> <onoff>
 
:''ref'': Physical number of the sending station.
 
:''no'':
 
::0 = Backlight down key
 
::1 = Backlight up key
 
:''onoff'':
 
::0 = off
 
::1 = on
 
 
 
=== '''<code>evt has</code>''' - Station Handset Event ===
 
<ref> evt has <onoff>
 
:''ref'': Physical number of the sending station.
 
:''onoff'':
 
::0 = off  (handset replaced, cancel conversation)
 
::1 = on  (handset lifted)
 
 
 
=== '''<code>evt hes</code>''' - Station Headset Event ===
 
<ref> evt hes <onoff>
 
:''ref'': Physical number of the sending station.
 
:''onoff'':
 
::0 = off  (headset replaced, cancel conversation)
 
::1 = on  (headset in use)
 
 
 
Note: Handset has priority over headset when both are in use.
 
 
 
=== '''<code>evt priv</code>''' - Station Open/Private mode Event ===
 
<ref> evt priv <onoff>
 
:''ref'': Physical number of the sending station.
 
:''onoff'':
 
::0 = off  (private mode off)
 
::1 = on  (private mode on)
 
 
 
=== '''<code>pong</code>''' - Pong ===
 
<ref> pong
 
:''ref'': Physical number of the sending station.
 
 
 
=== '''<code>mpong</code>''' - Multicast Pong ===
 
<ref> mpong
 
:''ref'': Physical number of the sending station.
 
 
 
Reply to the mping supervision message.
 
 
 
=== '''<code>ack</code>''' - Ack ===
 
<ref> ack <params...>
 
Ack is sent as response to sucessful command from AlphaCom. Parameters depend on the command that was received.
 
:''ref'': Physical number of the sending station.
 
 
 
=== '''<code>nak</code>''' - Nak ===
 
<ref> nak <params...>
 
Nak is sent as response to unsucessful command from AlphaCom. Parameters depend on the command that was received.
 
:''ref'': Physical number of the sending station.
 
 
 
=== '''<code>err rtp</code>''' - RTP audio missing===
 
<ref> err rtp <channel>
 
 
 
:''channel'': [[IP Station Audio Interface#Logical channels]].
 
 
 
"err rtp 0" means that a "auc" message was received, but no RTP audio followed. "err rtp 1" / "err rtp 2" means that a "agc" message was received and matched, but no RTP audio followed. IP stations delay sending of "err rtp" for 2 - 7 seconds after auc/agc to spread traffic load.
 
 
 
[[Category: IP Stations]]
 
[[Category:AlphaCom E Software]]
 

Latest revision as of 14:41, 7 September 2017

AlphaCom icon 300px.png

DIP is the control protocol used between STENTOFON IP stations and AlphaCom E exchanges. It is used for all data-communication with the IP stations, such as call control, LED settings and display text to the station, and key presses and inputs from the station.

DIP is short for "Display-data over IP", and refers to the ASLT display data protocol. This protocol was based on 9600 baud one-way transmission while DIP is transmitted both ways over IP (TCP and UDP).

See also ACDP message: DIP FWD