Introduction

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.

A PDF documentation of the protocol and its tools is available: MTD16 Protocol.

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.

Byte n+0

Byte n+1

messageLength

messageCode

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.