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.
<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:
  

‘ ‘ (space), ‘,’ (comma), <TAB>, <LF>, <FF>, <BS> and <BEL>.
Whitespace is allowed and ignored everywhere, except in the middle of hex-bytes, decimal numbers, directory numbers, strings, message type names, etc.
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
layer header   header        parameters         
0101 0141 00   41 0000 ????         ...
Src  Dest Hop  Cl Ref  Msg   
dev  dev  cnt  ss      id   
↑    ↑    ↑       ↑    ↑     ↑
<    @    H       R    M     :
  <*   @*      H*      $name

Char	Set current position to field:	Example
<	Source Node (I.e. the beginning of the message)	<0101
@	Destination Node	@0241 or @2
H	Hop Count	H05
R	Reference	R1234
M	Message Type	M0050
$	Message type Parameter: Message type name (or defined shortcut) consisting of up to 42 alphanumeric characters or underscores (‘_’). (The current position is set to after the “Message Type” field).	$DD $DIAL_DIGITS
>	the current end of the message	>
:	the start of the message parameters	:
*	the next byte (adding 0 byte if needed). ‘<*’ means “Source Device” ‘@*’ means “Destination Device” ‘H*’ means “Message Class”	@*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.

Miscellaneous

Char	Function:	Example
#	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. Any character except the delimiter itself is allowed in the string.	#Comment<CR>
=	Check sum nextParameter: Hexadecimal byte value (2 or 1 digits) to verify the checksum against. Should not occur more than once per message.	=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   
layer header   header                  
0101 0141 00   41 0000 ???? 
Src  Dest Hop  Cl Ref  Msg   
dev  dev  cnt  ss      iD   

Network Layer:
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.)

Application Layer:
Message Class:	0x41 (ALPHACOM_CLASS)
Reference:	0x0000
Message Type:	No default! Must be specified explicitly.

Format examples

Simple example in own exchange:

$DD L101 G102

Send same message to destination node 2:

@2 $DD L101 G102

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

1	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:

Data Type	Prefix	Parameter descr, Comment	Example
UINT SINT1	U S	Decimal number which is inserted into the message as a single UINT1/SINT1 field. - 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).	U1 means 0x01 U17 means 0x11
UINT2	W	Decimal number which is inserted into the message as a single UINT2 field.	W1 means 0x0001
UINT4	Q	Decimal number which is inserted into the message as a single UINT4 field.	Q1 means 0x00000001
TEXT16	'	Start a string terminated by the same character (or the end of the message) that is inserted as a TEXT16 field into the message. - Any character except the delimiter is allowed in the string. - The string value is truncated or padded with spaces as necessary to become exactly 16 bytes long.	'Alarm' means: "Alarm " 1234567890123456
text or byte string (free length)	" '	Start a string terminated by the same character (or the end of the message) that is inserted as-is into the message. - Any character except the delimiter is allowed in the string. - This allows one string parameter to contain another string parameter!	“Very long string to log to printer for station `Guard`”

Data Type	Prefix	Parameter descr, Comment	Example
NET_OBJ_REF	G	NRF_DIGIT_STRING NRF_GLOBAL_DIRNO Parameter:   Directory number NULL value:'V' Note: Max 10 digits in AMC 08.00	G1234 GV
NET_OBJ_REF	L	NRF_LOCAL_DIRNO Optional parameter:   Decimal node number in () default 0 (local_node) Parameter:   Directory number NULL value:'V'	L(2)101 L101 LV, L(2)V
NET_OBJ_REF	N	NRF_LOCAL_ENTITY Optional parameter:   Decimal node number in () default 0 (local_node) Optional parameter:   Decimal entity class in / / “magic character”, see below default 8 (ecl_station) Optional parameter: Decimal entity subclass in {} default omitted Parameter: Decimal physical number "Magic character" for entity class is A ECL_ABSENT (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)   ECL_STATION is default (8) U ECL_USER (9) + 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)	N(2)1   is station 1 in node 2 N/6/1 is program 1 NP1 is program 1   N(2){3}4   N1 is station 1 NM255 is all mails NG1 is group 1 NP1 is program 1   N1 is station 1 NU1 is user 1
NET_OBJ_REF	P	NRF_PHYS_ADDR (Supported from AMC 09.03) Parameters: 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.	P2/65/23/31     node 2, device 65, board 23, port 31 P//2/3     Own node, device 65, board 2, port 3 P     Own node, device 65, board 1, port 1
NET_OBJ_REF	I	INVALID_NRF (no parameters)

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

#GO!	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.

#!ACK+	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:

#ACK ON	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.

#OK	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