View source for Stentofon Simple Link Layer

The '''Stentofon Simple Link Layer''' is a point-to-point link layer can be used for inter-node links, links to local devices and as an operator interface. (Multiple devices can be connected to a single link using a SCE board or something similar).

To get response messages back to the port, you must define at least one external device on this port. If several devices are set up on the port, the lowest device number will be used as default device number in commands where device number is not stated explicitly.

There are no link addresses, polling, time-outs, acknowledgments, re-transmissions or any explicit multipoint support.

== Link Layer Output Message Format ==

Outgoing AlphaNet network layer messages are formatted like this:
 HHHHHH...HH=SS<CR><LF>
<HH> represents a binary byte as 2 hexadecimal digits.

Long text parameters are usually located at the end of a data message.  In this case the exchange will send the text as readable ASCII within quotes.

 HHHHHH...HH”tttt”=SS<CR><LF>
“ and = are syntax delimiters in the format. <br />
<SS> is the 8-bit checksum of the original binary network layer message represented as 2 hex digits. The checksum is an ISO-1155 (bytewise XOR) checksum.

If the trailing text parameter(s) contains any “ or control characters, the leading bytes of the text will be hex-coded instead up to and including the last “  or control character (as if the trailing text parameter(s) started there instead).  What is considered trailing text parameter(s) is the same as for the ISO-1745-based link layers (Using the internal “Encoding Hint”).

== Link Layer Input Message Syntax ==

The Input Message Syntax is a superset of the Output Message Format. 
 HHHHHH...HH=SS<CR>
The basic format is a hex coded network layer message, including check sum.  This format is excellent when produced by a computer controlling the exchange.

Example ([[DIAL DIGITS]]): 
 '''0101 0141 01 41 1234 0050 3201107F 20102F'''<CR>
* Incoming messages are terminated by <CR>.  The optional <LF> and any other control characters or spaces after <CR> before the next message are discarded.  
* The incoming messages (without the terminating <CR> and other inter-message characters) are converted by the same preprocessor as is used for AlphaNet messages from Command Strings before they are routed towards their destination.  If the converter finds syntax, length or checksum errors, the message is discarded silently.  Messages without checksum are always accepted as long as they do not have any other errors.

=== Parsing of commands ===

Many additions and simplifications are allowed to facilitate Operator (and Event Handler Action String) use. 
 $DD L101 G102<CR>               
 $DIAL_DIGITS L101 G102<CR>
* The '''parsing is “stateless'''”, so Hex bytes and formatting specifiers do NOT change meaning depending on sequence.  
* '''Uppercase/Lowercase''' is not significant, except inside strings (I.e. inside “”, ‘’ or ``). 
* '''Whitespace''' is defined as a sequence of one or more of these characters:<br />
‘ ‘ (space), ‘,’ (comma), <TAB>, <LF>, <FF>, <BS> and <BEL>. <br />
Whitespace is allowed and ignored everywhere, except in the middle of hex-bytes, decimal numbers, directory numbers, strings, message type names, etc.<br />  
Whitespace is however often necessary when used to delimit the parameter (list) of a formatting specifier from whatever follows after.  If the (last) parameter is a (decimal/directory) number, whitespace must be used if a hex-coded byte follows. Whitespace is also needed after message type names/acronyms if the following is a letter, digit or underscore (‘_’). (See below for more on formatting specifiers).

=== Formatting Specifers ===

All formatting specifiers are a single (non-hex-digit, non-whitespace) graphic “key” character plus sometimes parameters (or text delimited by same key character). 

'''Positioning'''

It’s not necessary to fill in all bytes in the headers.  Reserved characters are used to set the position in the message where the following bytes will be filled in (the omitted fields have default values, see below).


 Network        Application   Application
 <u>layer header</u>   <u>header      </u>  <u>parameters</u>         
 <u>0101</u> <u>0141</u> <u>00</u>   <u>41</u> <u>0000</u> <u>????</u>  <u>       ...</u>
 Src  Dest Hop  Cl Ref  Msg   
 <u>dev </u> <u>dev </u> <u>cn</u>t  <u>ss</u> <u>    </u> <u>id  </u> 
 &uarr;    &uarr;    &uarr;       &uarr;    &uarr;     &uarr;
 <    @    H       R    M     :
   <*   @*      H*      $name




{|border="1"  
|-
!style="background:#ffdead;" width="30pt"|Char
!style="background:#ffdead;" width="500pt"colspan="3"|Set current position to field:
!style="background:#ffdead;" width="30pt" |Example
|-
|align=center|<||Source Node (I.e. the beginning of the message)||align=center|<0101
|-
|align=center|@||'''Destination Node'''||align=center|@0241 or @2
|-
|align=center|H||Hop Count||align=center|H05
|-
|align=center|R||Reference||align=center|R1234
|-
|align=center|M||Message Type||align=center|M0050
|-
|align=center|$||'''Message type'''<br />Parameter: '''Message type name''' (or defined shortcut) consisting of up to 42 alphanumeric characters or underscores (‘_’).  <br />
(The current position is set to after the “Message Type” field).
|align=center|$DD<br />$DIAL_DIGITS
|-
|align=center|>||the current end of the message||align=center|>
|-
|align=center|:||the start of the message parameters||align=center|:
|-
|align=center|*||the next byte (adding 0 byte if needed).  <br />‘<*’  means “Source Device”<br />‘@*’  means “Destination Device”<br />‘H*’  means “Message Class” ||align=center|@*FF
|-
|}

Positioning takes into account optional network layer fields, but their length must then be set BEFORE positioning to anywhere after them.  Previously written application layer header/parameter fields can NOT be expected to be moved to their correct places when the Optional Fields Length is set.
<br /><br />

'''Miscellaneous'''

{|border="1"  
|-
!style="background:#ffdead;" width="30pt"|Char
!style="background:#ffdead;" width="500pt"colspan="3"|Function:
!style="background:#ffdead;" width="30pt" |Example
|-
|align=center|#||Start a '''comment''' string terminated by the same character (or the end of the message <CR>) who’s contents are discarded and ignored by the exchange.<br /> 
Any character except the delimiter itself is allowed in the string.
|align=center|#Comment<CR>
|-
|align=center|=||'''Check sum next'''Parameter: Hexadecimal byte value (2 or 1 digits) to verify the checksum against. <br />Should not occur more than once per message.
|align=center|=12
|-
|}

=== Default values for ommitted header fields ===

All header fields except the message type field can be omitted by positioning as described above.  These fields will get a default value in the AlphaCom. 

 Network        Application   
 <u>layer header</u>   <u>header&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</u>            
 <u>0101</u> <u>0141</u> <u>00</u>   <u>41</u> <u>0000</u> <u>????</u> 
 Src  Dest Hop  Cl Ref  Msg   
 <u>dev </u> <u>dev </u> <u>cn</u>t  <u>ss</u> <u>    </u> <u>iD&nbsp;&nbsp;</u> 


{| 
|-
!width="30pt"colspan="2"|Network Layer:
!width="500pt"colspan="3"|&nbsp;
|-
|Source Node:||<own node number>
|-
|Source Device:||<first configured device on the link> (Or 0xC8 “Bit_Bucket” if there is no device)
|-
|Destination Node :||<own node number>
|-
|Destination Device:||0x41 (ALPHACOM_DEV_ID)
|-
|Hop Count:||0
|-
|Opt. Fields Length:||0 (I.e. Optional fields omitted.  This is same byte as Hop Count.)
|-
|}
<br />
{| 
|-
!width="30pt"colspan="2"|Application Layer:
!width="500pt"colspan="3"|&nbsp;
|-
|Message Class:||0x41 (ALPHACOM_CLASS)
|-
|Reference:||0x0000
|-
| Message Type:||No default! Must be specified explicitly.
|-
|}
<br /><br />

=== Format examples ===
Simple example in own exchange:
 $DD L101 G102
Send same message to destination node 2:
 @2 $DD L101 G102
<br /><br />

=== Default values for omitted message fields ===

The optional message fields are added in the exchange that actually processes a message.  If you use the @ field to route a message to a different node in AlphaNet, all optional fields will get default values in that exchange.<br />  
There are two problems you should be aware of:
* Node numbers in directory numbers.
A dir.no entered as L123 will be expanded internally with node number 0, which in turn is changed to the processing node’s number.

* Fields that supply related information like name strings for directory numbers.
A message like SEND_MAIL has several fields describing the A subscriber.  If the optional fields are left out, they will be looked up in the remote exchange given that the A directory number is found there.


Example when used from Event Handler, using parameters to let the source exchange look up names:
Station 101 in node 1 will be queued on 102 in node 2.  Name in queue display will be correct, and a call-back (70+8) will set up a conversation to the correct node/station.
 @2 $SM  L(1)101  L102  U100 NM17 GV U0 ‘%1.nam()’ U0

== Encoding of standard parameter types ==

=== Raw hex ===

You can always type a parameter’s hexadecimal value directly, byte by byte.
{|
|-
|width="30pt"|1
|width="90pt"|means 0x01
|-
|01||means 0x01
|-
|0001||means 0x0001
|-
|}

=== Data type encoding ===

As an alternative, “human readable” input is allowed.  Here is the encoding rules for the standard message parameter types defined in the AlphaCom data protocol:
{| border="1"  
|-
!style="background:#ffdead;" width="90pt"|Data Type
!style="background:#ffdead;" width="30pt"|Prefix
!style="background:#ffdead;" width="90pt"colspan="2"|Parameter descr, Comment
!style="background:#ffdead;" width="110pt"|Example
|-
|align=center|UINT<br />SINT1||align=center|U<br />S||Decimal number which is inserted into the message as a single UINT1/SINT1 field.<br /> 
- If a minus ‘-‘ precedes the number, the 2’s complement (negative) of the value is inserted instead.  - If the value does not fit into the field, the most significant part is discarded without notice (modulus reduction).
|align=center|U1  means 0x01<br />U17 means 0x11
|-
|align=center|UINT2||align=center|W||Decimal number which is inserted into the message as a single UINT2 field.||align=center|W1 means 0x0001
|-
|align=center|UINT4||align=center|Q||Decimal number which is inserted into the message as a single UINT4 field.||align=center|Q1 means 0x00000001
|-
|align=center|TEXT16||align=center|'||Start a string terminated by the same character (or the end of the message) that is inserted as a TEXT16 field into the message.<br />
- Any character except the delimiter is allowed in the string.<br />  
- The string value is truncated or padded with spaces as necessary to become exactly 16 bytes long.
|<pre>'Alarm' means: 
"Alarm           "
 1234567890123456</pre>
|-
|align=center|text or <br />byte string <br />(free length)||align=center|"<br />'||Start a string terminated by the same character (or the end of the message) that is inserted as-is into the message. <br />
- Any character except the delimiter is allowed in the string. <br /> 
- This allows one string parameter to contain another string parameter!
|align=center|“Very long string to log<br /> to printer for station<br /> `Guard`”
|-
|}


{| border="1"  
|-
!style="background:#ffdead;" width="90pt"|Data Type
!style="background:#ffdead;" width="30pt"|Prefix
!style="background:#ffdead;" width="90pt"colspan="2"|Parameter descr, Comment
!style="background:#ffdead;" width="110pt"|Example
|-
|NET_OBJ_REF||align=center|G||NRF_DIGIT_STRING<br />NRF_GLOBAL_DIRNO
{|
|-
|width="90pt"|Parameter:<br />&nbsp;
|width="110pt"|'''Directory number'''<br />NULL value:'V'
|-
|}Note:  Max 10 digits in AMC 08.00
|'''G1234'''<br />GV
|-
|NET_OBJ_REF||align=center|L||NRF_LOCAL_DIRNO
{|
|-
|width="90pt"|Optional parameter:<br />&nbsp;
|width="110pt"|Decimal node number in ()<br />default 0 (local_node)
|-
|Parameter:<br />&nbsp;||'''Directory number'''<br />NULL value:'V'
|-
|}
|L(2)101<br /><br />L101<br /> LV,  L(2)V
|-
|NET_OBJ_REF||align=center|N||NRF_LOCAL_ENTITY
{|
|-
|width="90pt"|Optional parameter:<br />&nbsp;
|width="110pt"|Decimal node number in ()<br />default 0 (local_node)
|-
|Optional parameter:<br />&nbsp;||Decimal entity class in / /<br />“magic character”, see below<br />default 8 (ecl_station)
|-
|Optional parameter:||Decimal entity subclass in {}<br />default omitted
|-
|Parameter:||'''Decimal physical number'''
|-
|}

----
"Magic character" for entity class is
{|
|-
|width="90pt"|A
|width="110pt"|ECL_ABSENT
|width="90pt"|(1)
|-
|!||ECL_ANNOUNCEMENT||(2)
|-
|O||ECL_FEATURE||(3)
|-
|M||ECL_MAIL||(4)
|-
|G||ECL_ST_GROUP||(5)
|-
|P||ECL_PROGRAM||(6)
|-
|C||ECL_PROG_CONF||(7)
|-
|&nbsp;||ECL_STATION is default||(8)
|-
|U||ECL_USER||(9)
|-
|<nowiki>+</nowiki>||ECL_MAIL_PRIO||(10)
|-
|I||ECL_FEAT_CONN||(11)
|-
|N||ECL_NODE||(12)
|-
|%||ECL_GLOB_NUMBER||(13)
|-
|&||ECL_GLOB_GROUP||(14)
|-
|F||ECL_O_DUPL_CONF||(15)
|-
|B||ECL_BOARD||(16)
|-
|D||ECL_DEVICE||(17)
|-
|R||ECL_AUDIO_RING||(18)
|-
|}
|
{|
|-
|width="90pt"|N(2)1<br />&nbsp;
|width="110pt"|is station 1 in<br />node 2
|-
|N/6/1||is program 1
|-
|NP1||is program 1
|-
|colspan="2"|&nbsp;
|-
|N(2){3}4<br />&nbsp;
|-
|'''N1'''||is station 1
|-
|}

----

NM255 is all mails
{|
|-
|width="90pt"|NG1
|width="110pt"|is group 1
|-
|NP1||is program 1
|-
|colspan="2"|&nbsp;
|-
|N1||is station 1
|-
|NU1||is user 1
|-
|}<br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br />
|-
|NET_OBJ_REF||align=center|P||NRF_PHYS_ADDR (Supported from AMC 09.03)<br />Parameters:<br />
:n/d/b/p

… where n, d, b, p are 
:- node number(1-254),
:- device number (65 – 68), 
:- board number (1 – 24) and 
:- port number (1- 32). 

Any of n, d, b, p can be omitted, the defaults are own node, master module (65), board 1, channel 1. Trailing ‘/’ can also be omitted. Space-characters are not allowed inside the specifer.
|
{|
|-
|width="90pt"|P2/65/23/31
|width="110pt"|&nbsp;
|-
|&nbsp;||node 2, device<br />65,  board 23,<br />port 31
|-
|P//2/3||&nbsp;
|-
|&nbsp;||Own node,<br />device 65, board<br />2, port 3
|-
|P||&nbsp;
|-
|&nbsp;||Own node,<br /> device 65, board<br />1, port 1
|-
|}
|-
|NET_OBJ_REF||align=center|I||INVALID_NRF<br />(no parameters)||&nbsp;
|-
|}
<br><br>

== Producing site-specific (engineering use) formatted messages ==

It’s possible to generate any byte sequence using the Simle Link Layer format.  Remember that this link layer is just a way to position into a byte buffer, and fill in values byte by byte (It’s just when you send to [[device]] 65 that the AlphaCom tries to make sense out of it).  

Alt 1:  Private message class, to node 1, device 2:
 ''@0102 H*44 …then any binary or ASCII format you like…'' 
Alt 2:  AlphaCom class message, private message value, to node 1, device 2:
 ''@0102 M7000 …then any parameters you like…''

== Simple Link Layer functions for testing ==

Lines starting with the comment prefix'#' will be discared silently by the receiving layer.<br />To assist debugging of data protocol applications, there is some special comments.

=== Link Layer Startup ===

Immediately after exchange reset, before the first messages is sent or received, a startup acknowledge is output both terminated- and prefixed with <CR><LF>.

{|border="1"
|-
|width="100pt"|#GO!
|width="900pt"|Link startup
|-
|}
(This startup acknowledge might be omitted by future software versions.)


=== Link Layer Commands ===

Any line starting with “#!” (after discarding any initial spaces and/or control characters) is taken as a Link Layer Command. The terminating <CR> must come IMMEDIATELY after the command. 

{|border="1"
|-
|width="100pt"|#!ACK+
|width="900pt"|Turn Link Layer Operator Acknowledges ON.
|-
|#!ACK-||Turn Link Layer Operator Acknowledges OFF (default).
|-
|#!ACK?||Show Link Layer Operator Acknowledges Flag State.
|-
|}

=== Link Layer Responses ===

Currently possible responses to Link Layer Commands are:
{|border="1"
|-
|width="100pt"|#ACK ON
|width="900pt"|Link Layer Operator Acknowledges is (Turned) ON
|-
|#ACK OFF||Link Layer Operator Acknowledges is (Turned) OFF
|-
|#ILL CMD||Missing/Undefined Link Layer Command Keyword
|-
|#BAD CMD||Link Layer Command Syntax Error
|-
|}
Framing is as for Link Layer Message Acknowledges (<LF> prefix and <CR><LF> termination as described below).  These responses are however always output regardless of the Link Layer Acknowledges Flag value.


=== Link Layer Message Acknowledgments ===

Link Layer Acknowledgments are output for every non-empty input line, when they are enabled 
(with “#!ACK+”). 

These codes are always terminated by <CR><LF> and prefixed with <LF>.  The <LF> prefix makes the input (locally echoed in the terminal (emulator)) look sensible together with the acknowledge. 

The error numbers will always be decimal integers.

{|border="1"
|-
|width="100pt"|#OK
|width="900pt"|Message routed—Link Layer Parsing went OK
(The message may still be rejected by the network layer router or the application at the destination).
|-
|#ERROR - 1||Checksum digit missing
|-
|#ERROR - 2||Unknown Stuff (Unexpected character encountered)
|-
|#ERROR - 3||Network Layer Message Too Long (Not room in Buffer)
|-
|#ERROR - 4||Missing/Empty Parameter (No Digit found)
|-
|#ERROR - 5||Hex numbers in parameters not supported 
|-
|#ERROR - 6||Checksum Error
|-
|#ERROR - 7||Message Type Field Missing (Message too short)
|-
|#ERROR - 8||Formatting Specifier not supported
|-
|#ERROR - 9||Message Type Name/Acronym Not Recognized
|-
|#ERROR - 10||Missing ‘)’ or ‘/’ or ‘}’ after node/ecl/esc override
|-
|}

[[Category:Protocols]]