Message Catalog (Reference)

This new packet format is used from v0.3.0 on. The messages are defined in the packet_layout.xml file. The content below is generated from this XML definition.

Index

MessageGroup (ID)Message (ID)Packet Length in Bits (Bytes) of Possible Message TypesValidity
GetSetSetGetDeliverStatusAckAckStatus
Generic (0)DeviceInfo (2)95 (12)---163 (21)-200 (25)released
HardwareError (3)----91 (12)--released
BatteryStatus (5)95 (12)---90 (12)-127 (16)released
RXCycle (8)95 (12)159 (20)159 (20)159 (20)147 (19)109 (14)184 (23)test
GPIO (1)DigitalPort (1)95 (12)103 (13)103 (13)-91 (12)109 (14)128 (16)released
DigitalPortTimeout (2)95 (12)231 (29)231 (29)-219 (28)109 (14)256 (32)released
DigitalPin (5)95 (12)99 (13)99 (13)-87 (11)109 (14)124 (16)released
DigitalPinTimeout (6)95 (12)115 (15)115 (15)-103 (13)109 (14)140 (18)released
AnalogPort (10)95 (12)191 (24)191 (24)-179 (23)109 (14)216 (27)test
Weather (10)Temperature (1)95 (12)---99 (13)-136 (17)released
HumidityTemperature (2)95 (12)---109 (14)-146 (19)released
BarometricPressureTemperature (3)95 (12)---116 (15)-153 (20)released
Humidity (4)95 (12)---93 (12)-130 (17)released
Environment (11)Brightness (1)95 (12)---90 (12)-127 (16)released
Distance (2)95 (12)---97 (13)-134 (17)released
ParticulateMatter (3)95 (12)---243 (31)-280 (35)test
Display (40)Text (1)95 (12)431 (54)431 (54)-419 (53)109 (14)456 (57)test
Backlight (2)95 (12)107 (14)107 (14)-95 (12)109 (14)132 (17)test
Controller (45)MenuSelection (1)95 (12)223 (28)223 (28)223 (28)211 (27)109 (14)248 (31)test
InfraredRemoteCode (10)-119 (15)--107 (14)109 (14)-test
Audio (50)Tone (1)95 (12)102 (13)102 (13)-90 (12)109 (14)127 (16)test
Melody (2)95 (12)475 (60)475 (60)-463 (58)109 (14)500 (63)test
Dimmer (60)Brightness (1)95 (12)102 (13)102 (13)-90 (12)109 (14)127 (16)released
Animation (2)95 (12)127 (16)127 (16)-115 (15)109 (14)152 (19)released
Color (10)95 (12)101 (13)101 (13)-89 (12)109 (14)126 (16)released
ColorAnimation (11)95 (12)210 (27)210 (27)-198 (25)109 (14)235 (30)released

Message Definition Validity

Each message definition has one of the following validity values:

  • test: This message is used by a device under development or a device that is planned in the future and has not proven to be working as needed yet. The definition may change.
  • released: This message is used by an SHC device already built up and in use. The format should not be changed anymore. (Please note that there's never a guarantee that a format doesn't change anymore.)
  • deprecated: This message should not be used anymore and may be removed some day.
If you want to define new messages, consider to discuss it first with me via mail. This ensures finding a good (understandable and future-proof) representation of the data and avoiding duplicates.

Message Group Generic (0)

Description: This group contains messages useful for different devices.

Message DeviceInfo (2)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 80 bits
Description: Reports DeviceType, current firmware version and hardware revision. Firmware version information is only available when set in source code, which is usually only done for official builds by the build robot. Hardware revision is set in E2P or detected by the firmware.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120DeviceTypeEnumValue1 ByteThe DeviceType can be used to adapt the behavior or representation of the SHC device at the server software (e.g. FHEM).
Values: 0 = BaseStation, 10 = Proxy, 20 = EnvSensor, 40 = PowerSwitch, 43 = IRTransceiver, 45 = Controller, 50 = RGBDimmer, 60 = Dimmer, 70 = SoilMoistureMeter, 80 = Thermostat, 90 = TeaMaker
---91128VersionMajorUIntValue1 ByteDifferent major version means incompatible changes.
MinVal: 0, MaxVal: 255
---99136VersionMinorUIntValue1 ByteDifferent minor number means new functionality without breaking compatibility.
MinVal: 0, MaxVal: 255
---107144VersionPatchUIntValue1 ByteThe patch version is changed when backwards-compatible bug fixes are made.
MinVal: 0, MaxVal: 255
---115152VersionHashUIntValue4 BytesThe beginning of the revision ID hash (as reported by Git).
MinVal: 0, MaxVal: 4294967295
---147184HardwareVersionMajorUIntValue1 ByteDifferent major version means a major redesign of the schematic or PCB layout.
MinVal: 0, MaxVal: 255
---155192HardwareVersionMinorUIntValue1 ByteDifferent minor number means updated schematic or PCB layout with minor functionality changes and usually compatibility of the firmware.
MinVal: 0, MaxVal: 255

Message HardwareError (3)


Possible MessageTypes: Status
Validity: released
Length w/o Header + HeaderExtension: 8 bits
Description: Reports detected problems with the hardware.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83-ErrorCodeEnumValue1 ByteLists the type of error that occurred.
Values: 0 = ExternalReset, 1 = BrownOutReset, 2 = WatchdogReset, 3 = TransceiverWatchdogReset, 4 = TransceiverPowerCycle

Message BatteryStatus (5)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 7 bits
Description: Tells the current battery status in percent. Please note that the "Get" may not be answered because a device does not listen to requests.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120PercentageUIntValue7 BitsThe remaining capacity of the battery from 0 (empty) to 100 (full).
MinVal: 0, MaxVal: 100

Message RXCycle (8)


Possible MessageTypes: Get, Set, SetGet, Deliver, Status, Ack, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 64 bits
Description: For devices which are not available for incoming messages the whole time (listening in receive mode), this message describes the cycle for this functionality. It's used in battery powered devices to reduce power consumption.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
95959583120OnSecUIntValue2 BytesThis is the time in seconds for which the device will stay in receive mode per cycle. When setting this, it influences only all future cycles, not the current one. The value is permanently remembered on the device. The special value 0 means that the value shall not be modified. 65535 means that the device shall stay in receive mode the whole time (in this case, RXOffSec needs to be set to 0, and will be set to 0 as well). The device might reject setting the value too low (so it would practically not be reachable anymore) with an error in the Ack message.
MinVal: 0, MaxVal: 65535
11111111199136OffSecUIntValue2 BytesThis is the time in seconds for which the device will turn off reception per cycle. When setting this, it influences only all future cycles, not the current one. The value is permanently remembered on the device. The special value 0 means that the value shall not be modified. 65535 means that the device shall switch off reception forever (in this case, RXOnSec needs to be set to 0, and will be set to 0 as well). Since the device would never be reachable anymore, the device can (and usually will) reject this request, or any other request with a value it considers too high with an error in the Ack message.
MinVal: 0, MaxVal: 65535
127127127115152OnRemainingSecUIntValue2 BytesThe time for which the device will stay in receive mode in the current cycle, listening to messages, until it switches off receive mode and will not listen anymore to incoming requests. 0 indicates that receive mode is off already. The value can only be set when it is still in receive mode (otherwise it can't react to messages). In a Set request, 0 means to ignore the value. 65535 means forever and might be rejected.
MinVal: 0, MaxVal: 65535
143143143131168OffRemainingSecUIntValue2 BytesThe time for which the device will still not listen to any messages, until it switches on receive mode and starts listening again to incoming requests. The device can send this as a status message just before it goes to RX off mode. 0 indicates that receive mode is on already. The value can only be set when the device is in receive mode. Setting it means that the device switches off reception immediately for the given time. In a Set request, 0 means to ignore the setting. 65536 ("forever") or a value which the device considers being too high might be rejected with an error in the Ack.
MinVal: 0, MaxVal: 65535

Message Group GPIO (1)

Description: This group contains messages for general I/O functions. The meaning of the values is not known to the SHC devices. It depends on the connected parts (e.g. switches). The values have to be processed by the user/server software appropriately.

Message DigitalPort (1)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 8 bits
Description: This is the state of the complete digital port, containing up to 8 pins.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120OnBoolValue[8]1 Bit x 8Tells if the pin is on (at high level) or not (low level).

Message DigitalPortTimeout (2)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 136 bits
Description: This is the state of the complete digital port, containing up to 8 pins, including a timeout value per pin.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
Structured array with 2 sub elements
9595-83120OnBoolValue[8]1 Bit x 8Tells if the pin is on (at high level) or not (low level).
9696-84121TimeoutSecUIntValue[8]2 Bytes x 8The time after which the switch is automatically toggled again. Use 0 to disable this.
MinVal: 0, MaxVal: 65535
End of structured array (size: 17 Bits x 8)

Message DigitalPin (5)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 4 bits
Description: This represents the state of one pin of the digital port.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120PosUIntValue3 BitsThe number of the pin in the port.
MinVal: 0, MaxVal: 7
9898-86123OnBoolValue1 BitTells if the pin is on (at high level) or not (low level).

Message DigitalPinTimeout (6)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 20 bits
Description: This represents the state of one pin of the digital port, including a timeout value.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120PosUIntValue3 BitsThe number of the pin in the port.
MinVal: 0, MaxVal: 7
9898-86123OnBoolValue1 BitTells if the pin is on (at high level) or not (low level).
9999-87124TimeoutSecUIntValue2 BytesThe time after which the switch is automatically toggled again. Use 0 to disable this.
MinVal: 0, MaxVal: 65535

Message AnalogPort (10)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 96 bits
Description: This is the voltage of up to 8 ADC channels. The ATMega328 in the PDIP package has only 6 ADCs and one ADC may be blocked by the battery voltage measurement, so there may be less than 8 ADC values reported depending on the device and configuration.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
Structured array with 2 sub elements
9595-83120OnBoolValue[8]1 Bit x 8Tells if the pin is on (voltage over trigger threshold) or not.
9696-84121VoltageUIntValue[8]11 Bits x 8This is the voltage level in mV.
MinVal: 0, MaxVal: 1100
End of structured array (size: 12 Bits x 8)

Message Group Weather (10)

Description: This message group contains messages for weather data.

Message Temperature (1)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 16 bits
Description: This is a message containing temperature only.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120TemperatureIntValue2 Bytestemperature [1/100 degree celsius], -50°C = -5000, 50°C = 5000
MinVal: -32768, MaxVal: 32767

Message HumidityTemperature (2)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 26 bits
Description: This is a message containing humidity and temperature.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120HumidityUIntValue10 Bitsrelative humidity permill, 0..1000 (other values not defined)
MinVal: 0, MaxVal: 1000
---93130TemperatureIntValue2 Bytestemperature [1/100 degree celsius], -50°C = -5000, 50°C = 5000
MinVal: -32768, MaxVal: 32767

Message BarometricPressureTemperature (3)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 33 bits
Description: This is a message containing barometric pressure and temperature.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120BarometricPressureUIntValue17 Bitsbarometric pressure in pascal
MinVal: 0, MaxVal: 131071
---100137TemperatureIntValue2 Bytestemperature [1/100 degree celsius], -50°C = -5000, 50°C = 5000
MinVal: -32768, MaxVal: 32767

Message Humidity (4)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 10 bits
Description: This is a message containing humidity.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120HumidityUIntValue10 Bitsrelative humidity permill, 0..1000 (other values not defined)
MinVal: 0, MaxVal: 1000

Message Group Environment (11)

Description: This message group contains messages for environmental data except weather data.

Message Brightness (1)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 7 bits

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120BrightnessUIntValue7 Bitsbrightness in percent
MinVal: 0, MaxVal: 100

Message Distance (2)


Possible MessageTypes: Get, Status, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 14 bits

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120DistanceUIntValue14 Bitsdistance in cm
MinVal: 0, MaxVal: 16383

Message ParticulateMatter (3)


Possible MessageTypes: Get, Status, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 160 bits

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
---83120TypicalParticleSizeUIntValue10 BitsTypical Particle Size [1/100 μm]. Use 1023 when value invalid.
MinVal: 0, MaxVal: 1023
Structured array with 3 sub elements
---93130SizeUIntValue[5]1 Byte x 5Maximum particle size [1/10 µm] which is considered in the MassConcentration and NumberConcentration. Use 0 when the array element is not used.
MinVal: 0, MaxVal: 255
---101138MassConcentrationUIntValue[5]10 Bits x 5Mass concentration [1/10 μg/m3], considering the defined size. Use 1023 when the value is invalid.
MinVal: 0, MaxVal: 1023
---111148NumberConcentrationUIntValue[5]12 Bits x 5Number concentration [1/10 #/cm3], considering the defined size. Use 4095 when the value is invalid.
MinVal: 0, MaxVal: 4095
End of structured array (size: 30 Bits x 5)

Message Group Display (40)

Description: This message group contains messages for displays.

Message Text (1)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 336 bits
Description: This is a message to get/set text content at a specified position.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120PosYUIntValue5 BitsY (line) position at which the text shall be displayed. Line numbers above 3 are for the corresponding virtual lines / pages.
MinVal: 0, MaxVal: 31
100100-88125PosXUIntValue7 BitsX (character) position at which the text shall be displayed.
MinVal: 0, MaxVal: 79
107107-95132FormatUIntValue4 BitsFormat, font, or other value which modifies how the text is displayed. Depends on the implementation of the device.
MinVal: 0, MaxVal: 15
111111-99136TextByteArray40 Bytes40 bytes for the text that shall be displayed. The end of the text is marked with a 0 byte if it's shorter than 40 characters.

Message Backlight (2)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 12 bits
Description: This is a message to get/set the backlight mode of a display.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120ModeEnumValue4 BitsThe backlight mode defines when the backlight is switched on. The setting 'Auto' means the backlight is switched on automatically after user interaction and off after a timeout.
Values: 0 = On, 1 = Off, 2 = Auto
9999-87124AutoTimeoutSecUIntValue1 ByteThis is the timeout in seconds after which the backlight is switched off in mode 'Auto'. The value 0 shall be treated as not to change the value when sending a request to the device.
MinVal: 0, MaxVal: 255

Message Group Controller (45)

Description: This message group contains messages for controller / HMI devices.

Message MenuSelection (1)


Possible MessageTypes: Get, Set, SetGet, Deliver, Status, Ack, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 128 bits
Description: These are the value indexes of selected menu items. It depends on the configuration of a specific controller device which value each index represents. The indexes of selected menu entries should start with 1, and 0 should be treated as 'not updated' (in a Status/AckStatus/Deliver message) or 'not to be updated' (in a Set/SetGet request). This is to allow smaller (16 byte) packets when there are few menu entries.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
95959583120IndexUIntValue[16]1 Byte x 16The index of the selected value of a menu entry.
MinVal: 0, MaxVal: 255

Message InfraredRemoteCode (10)


Possible MessageTypes: Set, Status, Ack
Validity: test
Length w/o Header + HeaderExtension: 24 bits
Description: The three bytes within this packet represent a NEC code that can be received or transmitted.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
95--83-CodeByteArray3 Bytes3 bytes for the NEC code.

Message Group Audio (50)

Description: This message group contains messages for audio input/output.

Message Tone (1)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 7 bits
Description: This is a message to get/set playback of a continuous tone which doesn't stop until another one is requested.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120ToneUIntValue7 BitsTone according frequency table. 0 means OFF.
MinVal: 0, MaxVal: 116

Message Melody (2)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 380 bits
Description: This is a message to play a series of tones (set) or get the currently playing one.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120RepeatUIntValue4 BitsThe number of times the melody will be repeated. 0 means infinitely.
MinVal: 0, MaxVal: 15
9999-87124AutoReverseBoolValue1 BitIf true, the melody will be played back in the normal direction and then in reverse order.
Structured array with 3 sub elements
100100-88125TimeUIntValue[25]5 Bits x 25The playback time between the previous tone and the new one. The number of seconds used is 0.05 * 1.3 ^ Time and covers the range from 0.03s to 170s. Use 0 to mark the end of the melody. Further values will be ignored.
MinVal: 0, MaxVal: 31
105105-93130EffectUIntValue[25]3 Bits x 25Define how the tone is played. 0: Tone is played immediately (default). 1: A sliding tone from the previous to the new one. A sliding tone from or to tone index 0 (off) is not possible. The new tone / no tone will be played back immediately in this case. Other values are free for future use.
MinVal: 0, MaxVal: 1
108108-96133ToneUIntValue[25]7 Bits x 25Index according frequency table. 0 means OFF. The last index (or the first when AutoReverse is true) of the melody will remain audible after the melody is completed.
MinVal: 0, MaxVal: 116
End of structured array (size: 15 Bits x 25)

Message Group Dimmer (60)

Message Brightness (1)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 7 bits
Description: This is to set a fixed brightness.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120BrightnessUIntValue7 BitsThe brightness in percent. 0 = Off.
MinVal: 0, MaxVal: 100

Message Animation (2)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 32 bits
Description: This is the state of the dimmer output voltage and its timeout value.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120AnimationModeEnumValue2 BitsIf a time is set, use this animation mode to change the brightness over time (none = leave at start state for the whole time and switch to end state at the end).
Values: 0 = none, 1 = linear
9797-85122TimeoutSecUIntValue2 BytesThe time for the animation. Use 0 to disable this.
MinVal: 0, MaxVal: 65535
113113-101138StartBrightnessUIntValue7 BitsThe brightness in percent at the beginning of the animation.
MinVal: 0, MaxVal: 100
120120-108145EndBrightnessUIntValue7 BitsThe brightness in percent at the end of the animation.
MinVal: 0, MaxVal: 100

Message Color (10)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 6 bits
Description: This is to set a fixed color.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120ColorUIntValue6 BitsThe color is according to the 6 bit color palette used in SHC.
MinVal: 0, MaxVal: 63

Message ColorAnimation (11)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: released
Length w/o Header + HeaderExtension: 115 bits
Description: This is to set a color animation.

Offset (Bits)NameTypeSizeDescription
SetSetGetDeliverStatusAckStatus
9595-83120RepeatUIntValue4 BitsThe number of times the animation will be repeated. 0 means infinitely.
MinVal: 0, MaxVal: 15
9999-87124AutoReverseBoolValue1 BitIf true, the animation will be played back in the normal direction and then in reverse order.
Structured array with 2 sub elements
100100-88125TimeUIntValue[10]5 Bits x 10The time for the animation between the current color and the next one. The number of seconds used is 0.05 * 1.3 ^ Time and covers the range from 0.03s to 170s. Use 0 to mark the end of the animation. Further values will be ignored.
MinVal: 0, MaxVal: 31
105105-93130ColorUIntValue[10]6 Bits x 10The color is according to the 6 bit color palette used in SHC. The last color (or the first when AutoReverse is true) of the animation will remain visible after the animation is completed.
MinVal: 0, MaxVal: 63
End of structured array (size: 11 Bits x 10)