Stentofon Simple Link Layer

Stentofon Simple Link Layer

This 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): 010101410141123400503201107F20102F<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).

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<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).	$DD<br\>$DIAL_DIGITS
>	the current end of the message	>
:	the start of the message parameters	:
*	the next byte (adding 0 byte if needed). <br\>‘<*’ means “Source Device”<br\>‘@*’ means “Destination Device”<br\>‘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. <br\><br\>

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.<br\> 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. <br\>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 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.)

<br\>

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

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<br\>SINT1	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).	U1 means 0x01<br\>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.<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.	‘Alarm‘ <br\>means “Alarm “ 1234567890123456
text or <br\>byte string <br\>(free length)	"<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!	“Very long string to log<br\> to printer for station<br\> `Guard`”

Data Type	Prefix	Parameter descr, Comment	Example
NET_OBJ_REF	G	NRF_DIGIT_STRING<br\>NRF_GLOBAL_DIRNO<br\> Parameter: Directory number NULL value: ‘V’ Note: Max 10 digits in AMC 08.00	G1234<br\>GV
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.<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.	‘Alarm‘ <br\>means “Alarm “ 1234567890123456
text or <br\>byte string <br\>(free length)	"<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!	“Very long string to log<br\> to printer for station<br\> `Guard`”