Home Contents | # Introduction | Mtd16 | Core4 Lua Commands

## SYNOPSIS

#include <lua/mtd16.lh>

## DESCRIPTION

Message Tag Data or MTD16 is a data encapsulation used by multiple Teratronik products. It is a binary format using a length-tag-data structure.

The mtd16 group of Lua commands help in dealing with such data in an abstract way.

Construct a new message using mtd16.new. Add a new message to it using mtd16:appendMessageCode and mtd16:append. When done, retrieve the binary encoding by calling mtd16:toData.

Conversely, to decode a binary message, construct an object calling mtd16.fromData. Walk the stored messages by calling mtd16:nextMessageCode. Walk the data contents of a message using mtd16:pairs() or specifically ask for a tagged item with mtd16:get or mtd16:getString.

Calling mtd16:trace helps in debugging by returning a human readable representation of the contents.

A textual representation of a message that can be decoded back into a binary message later can be retrieved with mtd16:toText and decoded with mtd16.fromText.

## FRAME FORMAT

All tag and length fields use 16 Bits and are stored least significant byte first (little endian). The length field indicates the number of bytes following after the length field.

One MTD16 message consists of a tagged header and zero or more tagged data parts.

n | Byte n+0 | Byte n+1
--- | --- | ---
0 | messageLength
2 | messageCode
4 | TaggedData
i | Byte i+0 | Byte i+1
--- | --- | ---
0 | Length
2 | Tag
4 | Data
...
i | Byte i+0 | Byte i+1
--- | --- | ---
0 | Length
2 | Tag
4 | Data

## TAG STRUCTURE

The fields messageCode and Tag follow a specific structure. The top four or top eight bits (thus, the first digit(s) when displayed in hexadecimal format) describe the data type of the contents. This helps tracing programs to display properly formatted traces without specifically knowing what's inside. Additionally, it helps converting the data to other formats, e.g. XML.

### Data types with type in top four bits of the tag

Code (hex) | Name | Symbol | Description
--- | --- | --- | ---
0 | Binary | MTD16DT_BINARY | Arbitrary binary data
1 | Integer | MTD16DT_INTEGER | Integer number. The length of the data part of the field is 1 .. 8 bytes. If the length is less than eight bytes, the unsent bytes are assumed to be zero.
2 | Bool | MTD16DT_BOOL | One byte of data: 0 means false, else true.
3 | String | MTD16DT_STRING | Text of arbitrary length using UTF-8 encoding.
4 | Date | MTD16DT_DATE | Same format as Integer, indicating the number of days since 1990-01-01.
5 | Time | MTD16DT_TIME | Same format as Integer, indicating the number of seconds since 00:00:00.
6 | DateTime | MTD16DT_DATETIME | Combined date and time. Length is always eight bytes. First four bytes encode the date as number of days since 1990-01-01. Second four bytes indicate the number of seconds since 00:00:00.
7 | BitArray | MTD16DT_BITARRAY | Arbitrary array of bits. First byte contains bits 0..7, etc... Bits beyond the length of the data contents must be assumed to be zero by the receiver.
9 | Network Address | MTD16DT_NETWORKADDRESS | Designed to support IPv4, IPv6 and MAC addresses, depending on the length. This implementation currently supports only IPv4 addresses in network byte order (MSB first). Field size for IPv4 is always four bytes.
C | List | MTD16DT_MESSAGE | Used to nest an array of multiple items of the same kind.
D | Request | MTD16DT_REQUEST | Message type used in the message header's messageCode field. The sender of a request always expects an answer of type Answer (see below).
E | Answer | MTD16DT_ANSWER | Message type used in the message header's messageCode field. This is an answer to a message of type Request.
F | Message | MTD16DT_MESSAGE | Message type used in the message header's messageCode field. Used for informative messages that require no answer and also to nest data inside another message.

### Data types with type in top eight bits of the tag

Code (hex) | Name | Symbol | Description
--- | --- | --- | ---
80 | Point | MTD16DT_POINT | Contains two 16-bit little endian signed integers, four bytes in total. First integer is x-coordinate, second is y-coordinate.
81 | Rect | MTD16DT_RECT | Contains four 16-bit little endian signed integers, eight bytes in total. The values are x-coordinate, y-coordinate, width and height.
82 | Size | MTD16DT_POINT | Contains two 16-bit little endian signed integers, four bytes in total. First integer is width, second is height.

The table mtd16.lutType contains a lookup table which maps the names shown above to their respective codes.

## NOTES

Note that Core4 Lua supports only integers of up to four bytes.

## SEE ALSO

#mtd16, mtd16.answerCode, mtd16.fromData, mtd16.fromText, mtd16.isNestedTag, mtd16.lutType, mtd16.new, mtd16.tagCode, mtd16.tagName, mtd16.tagNumber, mtd16.tagType, mtd16:append, mtd16:appendMessageCode, mtd16:contains, mtd16:get, mtd16:getNumber, mtd16:getString, mtd16:isEmpty, mtd16:isValid, mtd16:messageCode, mtd16:nextMessageCode, mtd16:pairs, mtd16:rewind, mtd16:tags, mtd16:toData, mtd16:toText, mtd16:trace, tostring(mtd16)