Packet Structure

The basic packet structure is:

aaa XX bbb DEVICE_ID DEVICE_ID DEVICE_ID CODE nnn PAYLOAD.....

It is a number of fixed-length ascii fields, separated by spaces, with a variable length payload at the end. See here for specific detail how to check that a packet is valid, before decoding the payload.

aaa: RSSI Value and bbb: Sequence Number

In short, these can usually be ignored; in particular, Evohome does not use sequence numbers.

WIP: The text aaa is the RSSI strength number field but it is not considered to be used by Evohome devices. WIP: The text bbb is a legacy message number field and this is not usually used in messages between Evohome devices.

These fields will have a 3-digit _decimal _number, with leading zeros, or --- if they are not used.

The RSSI field is used by a HGI80, and the 'strongest' (best) signal is set to a lower bound of 045 and the weakest (worst) has an upper bound of 095 (i.e. there is no 096).

Tip: A RSSI of 095 may indicate that the packet has come from your neighbour!

XX: Packet Verb and CODE: Packet Code (WIP)

Packet type will be one of the following:

• ' I' information (note the space before the I)
• 'RQ' request
• 'RP' response (to a request)
• ' W' write (note the space before the W)

Documentation on each code is available separately.

Beware: For historical reasons, the name commonly used for packet codes may - strictly speaking - be misleading, for example Zone Temperature (30C9) can contain a temperature that is the temperature of a device rather than a zone.

PAYLOAD: Packet Payload and nnn: Length

The payload is a sequence of (8-bit) bytes represented in hexadecimal (i.e. 00 to FF) and with a maximum length of 48 (minimum length 1). If the message will not fit into the payload, then additional packets are sent (or can be requested) with the remaining portion of the message (e.g. codes 000A, 0404).

Payload length is interpreted as a decimal number with leading zeros.

Beware: The payload length field is the length of the payload in pairs of hexadecimal characters. Thus, a PAYLOAD of 001234 would have nnn equal to 003, which is 6 characters; 034 is 68 characters.

The payload for a given code will not always be a particular length (this is true even for payloads that are not arrays):

095  I ---  --:------  --:------ THM:227486 1100 005 0018040400
095  I --- BDR:171587  --:------ BDR:171587 1100 008 00180404007FFF01

Each payload is decoded according to its packet type, code, and the sending device_type to provide a message (e.g. 'set the system to away mode'). For example, a temperature packet (30C9) from:

• a device: is the temperature recorded by that device, and is always of length 6 bytes
• the controller: is an array of temperatures (one for each zone), and in thus a multiple of 6 bytes

The first byte of a payload may contain an index value, such as a zone_idx (00 to 0B), a domain_id (F9, FA, FC), or some other value.

Beware: A value of 00 is not always for zone 0.

For some packets, usually from the controller, the payload may be an array of payloads, each with its own index value (see code 30C9), for example:

045  I --- 01:145038 --:------ 01:145038 2309 018 00076C0107D002079E03073A0406D60506D6

where the payload, 00076C0107D00..., can be shown as and array of 6 zone entries:

00-076C 01-07D0 02-079E 03-073A 04-06D6 05-06D6

CHECK: Beware, the zone_idx numbers to not have to be an ascending sequence, for example, if zone 3 is deleted, the devices in zone 4 will continue to believe themselves to be in zone_idx == 04 (even if, ultimately, that is the only zone).

What's in a Payload

The encoding of the payload varies greatly, according to the packet code. Notably, it can contain device numbers, command codes, and ASCII characters. Numbers (integers and floats) may be stored as hexadecimal, integers, or even a sequence of bits.

Many packets have no functional payload, those will be 00, with a length of 001.

DEVICE_ID: Device address fields

Valid packets have three address fields that may contain a device ID, for example: 12:123456 and 18:105324. In this standard device ID format, the two digits before the colon (:) represent the device type.

Device IDs may also appear in payloads, although they will appear a hexadecimal format, for example: 3C6FA9 and 06368E. An evohome controller's ID can be obtained through its user interface and will be in this format.

Device types & Device ID formats

See Device IDs for detail on this data structure (such as device types, and converting between the two formats).

Address fields

Packets are invariably from (sent by) the device that is in the first address field (the only known exception to this is for non-evohome devices).

Packets are usually to (sent to) the device in the third address field. For announcements, the 3rd address will match the 1st, for example, here are the packets send by a controller every sync interval:

045  I --- 01:145038 --:------ 01:145038 1F09 003 FF073F
045  I --- 01:145038 --:------ 01:145038 2309 021 0007D00107D002079E03073A04079E0506D606073A
045  I --- 01:145038 --:------ 01:145038 30C9 021 0007DF01080B0207D10307660407550508100608AB

There are special device IDs, such as --:------ (no device) and 63:262142 (aka FFFFFF) (null device).

049  I --- 30:082155 63:262142 --:------ 10E0 038 000001C90011006C...
053  I --- 04:189082 63:262142 --:------ 1FC9 006 0030C912E29A

WIP: HGI and CTL are conventions used ...