Protocol Basics

Messages are exchanged between devices (including central units) by way of message frames sent out by a device (source). These messages can be received by any other device. Depending on the destination address and configuration of the receiving device, it will decide how to handle the message:

A receiving device configured as peer will be adressed as destination of the message and acknowledge the reception of the message by means of an ACK frame. This way the source device will know if the message was received and can try retransmission upon timeout.
Messages addressed to the special broadcast address will not be acknowledged and can be used for measurement data or alike that are of volatile nature.

Device Address

Every device is addressed by a unique 3-byte ID (aka 'HM-ID'). This address is usually expressed in hexadezimal form, ommiting any hex denominating prefix commonly used in programming languages (prefix '0x'). Valid device IDs range from 000001 to FFFFFE. ID 000000 is reserved as broadcast address when sending out data frames that do not require acknowledgement.

Message Frames

All message frames follow the same structure with a fixed-length message header and a variable-length payload:

             |                               Message Header                                  |              Payload
-------------+-------------------------------------------------------------------------------+----------------------------------
Index        |   0   |   1   |   2   |   3   |   4   |   5   |   6   |   7   |   8   |   9   |   10  |        ...       | Len-1
-------------+-------+-------+-------+-------+-----------------------+-----------------------+----------------------------------
Description  |  Len  | Count | Flags | Type  |     Source-Address    |  Destination-Address  |    (depending on message type)

Len

Length of the complete message frame, including header and payload. Maximum allowed length is 26.

Count

Message frame counter, incremented by the source device each time a message is sent.

Flags

Message status flags, for more information see Message Flags

Type

Defines how the payload is to be interpreted. For more details, see message_type

Source-Address

3-Byte address of the source device. Often referred to as HMID.

Destination-Address

3-Byte address of the destination. Broadcasts are addressed to 000000. Also see HMID.

Payload

Carries the information transported by the message frame. Payload content is to be interpreted according to the message_type

Message Flags

The message flags byte carries status information relevant for protocol handling. It comprises the following bits:

0x80: Message to master or message could be repeated
0x40: Repeated message
0x20: ACK requested
0x10: Burst transmission
0x08: unknown
0x04: Config mode (broadcast)
0x02: Wake me up
0x01: Wakeup

Message Types

The message type defines how the payload oof the message is to be interpreted.

Todo:

Write much more about message types.

Decide if every message type should have its own subsubsection

Device Model

Device Channels

Device properties are organized in form of channels, with special channel 0 that represents the device entity that communicates with others and at least one more channel that represents a sensor, actuator, or alike.

Device Registers

Seen from the protocol prespective, the configuration of a device is represented in form of registers each of which has an ID for identification and a one-byte-content that affects the behavior of the device. Registers are solely used for configuration purposes. Static information that is hardcoded into the device software, like serial number or HMID, is not represented by registers but can be queried using special messages.

Often, register specifications are written as a list of ID:VALUE pairs:

List0: 02:01 05:00 0A:AB 0B:CD 0C:EF 14:05 24:05 25:DC 26:05 27:03 00:00

This example shows that the device is paired to ID 'ABCDEF', represented by registers 0A, 0B and 0C.

A device organizes registers in the context of lists that are used for specific purposes:

List0

Represents the device configuration. Each device has exactly one instance of this list and it is associated with channel 0.

List1

Represents per-channel configuration. Each channel of a device must have a List1 and one of List3 or List4.

List2

List3

List4

List5..List9

In the NewAskSin framework, registers are defined