A Dreamer's Lair

eQ-3 Max Cube message protocol decrypted: Part 3, the ‘M’ word

In this part of the series of articles about the Cube Message Protocol, I’m going to discuss the Metadata message, the ‘M’ message. It is one of the messages that the cubes sends when connecting to it for the first time. Also the message can be requested by using the m: command.

The metadata contains, as the name already tells us, metadata about our collection of eQ-3 devices.

Like the H message, the M message contains a comma separated list of strings in the form of

          
M:00,01,VgIGAgpMaXZpbmdSb29tDMAeAwRIYWxsC64PBQhCYXRoUm9v=
          

The first two parameters are (yet) unknown. The third and last string is a Base64 encoded string. It contains the definitions for all rooms (or groups if you will) and devices. The decoded bytes will look something like this

          
0000: 56 02 06 02 0a 4c 69 76   V....Liv
0008: 69 6e 67 52 6f 6f 6d 0c   ingRoom.
0010: c0 1e 03 04 48 61 6c 6c   ....Hall
0018: 0b ae 0f 05 08 42 61 74   .....Bat
0020: 68 52 6f 6f 6d 06 c9 22   hRoom...
0028: 04 07 42 65 64 52 6f 6f   ..BedRoo
0030: 6d 0b aa e9 01 09 48 6f   m.....Ho
0038: 62 62 79 52 6f 6f 6d 06   bbyRoom.
0040: c9 41 06 09 53 70 61 72   .A..Spar
0048: 65 52 6f 6f 6d 0c c0 51   eRoom..Q
0050: 0f 03 0a 12 bd 4b 45 51   .....KEQ
0058: 30 37 30 34 37 35 32 13   0704752.
0060: 54 68 65 72 6d 6f 73 74   Thermost
0068: 61 74 48 6f 62 62 79 52   atHobbyR
0070: 6f 6f 6d 01 01 06 c9 41   oom....A
0078: 4b 45 51 30 33 35 32 32   KEQ03522
0080: 37 36 15 52 61 64 69 61   76.Radia
0088: 74 6f 72 48 6f 62 62 79   torHobby
0090: 52 6f 6f 6d 52 65 61 72   RoomRear
0098: 01 01 06 c8 0c 4b 45 51   .....KEQ
          

The metadata contains the following information

          
Position   Information
===================================================
00:        Meta Data Magic. Should always be 0x56
01:        Meta data version. Should always be 0x02
02:        Number of Rooms
xx-(yy-1): Meta Data for each room.
yy:        Number of Devices
(yy+1)-zz: Meta Data for each device
          

The magic number and meta data version always seem a fixed number. Perhaps the meta data version will be increased when a new meta data version is composed by eQ-3. So perhaps it’s best to check in your code that both numbers are 0x56 and 0x02 and log a warning if they ever change.

After the first two bytes, the next byte indicates the number of rooms (or groups) as defined in the Cube followed by a sequence of blocks of data, one for each room. The metadata for each room looks something like this

          
0000:          02 0a 4c 69 76   V....Liv
0008: 69 6e 67 52 6f 6f 6d 0c   ingRoom.
0010: c0 1e                     ..

Position    Information
=========================================
00:         Room ID (1 byte)
01:         Length of Room Name (1 byte)
02-(xx-1):  Room Name
xx:         Room Master Address (3 bytes)
          

In the above example, the Room has an ID of 2, contains a name of 10 (0x0a) characters which is LivingRoom and has an address of 0x0cc01e which translates as decimal 835614.

After the sequence of rooms, the next byte contains the number of devices followed by a sequence of blocks of data, one for each device. The metadata for each device looks something like this

          
0050:    03 0a 12 bd 4b 45 51   .....KEQ
0058: 30 37 30 34 37 35 32 13   0704752.
0060: 54 68 65 72 6d 6f 73 74   Thermost
0068: 61 74 48 6f 62 62 79 52   atHobbyR
0070: 6f 6f 6d 01               oom.

Position    Information
==========================================
00:         Device Type (1 byte)
01:         RF Address (3 byte)
04:         Serial Number (10 bytes)
0E:         Length of Device Name (1 byte)
0F-(xx-1):  Device Name
xx:         Room ID
          

In the above example the device type is 3, the address is 0x0a12bd which translates as decimal 660157. The serial number for this device is KEQ0704752. The name is 19 (0x13) bytes long with the value of ThermostatHobbyRoom. Lastly, the device is part of room with ID 1.

I have defined the device type, in C#, as an enumeration with the following definition

          
/// <summary>
/// Enumeration of possible Max Device Types.
/// The int value of the enumeration is important since it links
/// to the device type number in the MAX device.
/// </summary>
public enum MaxDeviceType
{
    Cube = 0,
    RadiatorThermostat = 1,
    RadiatorThermostatPlus = 2,
    WallThermostat = 3,
    ShutterContact = 4,
    EcoButton = 5
}
          

So in the above example the device (type 3) would be a Wall Thermostat Device.

And that’s it for the M message!

    One comment so far | Leave your own comment

  1. 2/29/2016 | 13:37 Permalink

    Hi,
    I want to thank you for your great work on the MAX! protocol. I’m on the way switching from FS20 to MAX! using my own control-software. It is mainly based on Perl-cgi’s.
    I started to implement the ‘H’, ‘M’, ‘C/L’ response interpreters using your informations.
    Your summary was very useful in reading the hello/metadata/configuration from the cube!!!
    …but now I stuck with some general questions:
    I know, that it is possible to get “live” data aka L-Responses by sending “l:\n\r” requests.
    I don’t understand the mechanism how I can address a dedicated device to get it’s L-Response. Using “l:\n\r” always replies one L-Response from one dedicated Wall-Thermostat!?
    How can I address the other devices to get the “live” data?
    A simple task would be to read out the status of the shutter contacts one after another, which would be task of some specialized CGIs.
    Please can you give me advice or a link to a source of informations on polling the devices?

    Thx in advance
    Michi

    Respond to this comment

  2. Or

    Your email address will not be published. Required fields are marked *

    *



    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>