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
GetSetSetGetStatusAckAckStatus
Generic (0)Version (1)95 (12)--139 (18)-176 (22)deprecated
DeviceInfo (2)95 (12)--147 (19)-184 (23)test
HardwareError (3)---91 (12)--test
BatteryStatus (5)95 (12)--90 (12)-127 (16)test
GPIO (1)DigitalPort (1)95 (12)103 (13)103 (13)91 (12)109 (14)128 (16)test
DigitalPortTimeout (2)95 (12)231 (29)231 (29)219 (28)109 (14)256 (32)test
DigitalPin (5)95 (12)99 (13)99 (13)87 (11)109 (14)124 (16)test
DigitalPinTimeout (6)95 (12)115 (15)115 (15)103 (13)109 (14)140 (18)test
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)test
HumidityTemperature (2)95 (12)--109 (14)-146 (19)test
BarometricPressureTemperature (3)95 (12)--116 (15)-153 (20)test
Humidity (4)95 (12)--93 (12)-130 (17)test
Environment (11)Brightness (1)95 (12)--90 (12)-127 (16)test
Distance (2)95 (12)--97 (13)-134 (17)test
PowerSwitch (20)SwitchState (1)95 (12)112 (14)112 (14)100 (13)109 (14)137 (18)deprecated
SwitchStateExt (2)95 (12)231 (29)231 (29)219 (28)109 (14)256 (32)deprecated
Dimmer (60)Brightness (1)95 (12)102 (13)102 (13)90 (12)109 (14)127 (16)test
Animation (2)95 (12)127 (16)127 (16)115 (15)109 (14)152 (19)test
Color (10)95 (12)101 (13)101 (13)89 (12)109 (14)126 (16)test
ColorAnimation (11)95 (12)210 (27)210 (27)198 (25)109 (14)235 (30)test

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, you should discuss this in the forums first. 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 Version (1)


Possible MessageTypes: Get, Status, AckStatus
Validity: deprecated
Length w/o Header + HeaderExtension: 56 bits
Description: Reports the current firmware version. Version information is only available when set in source code, which is usually only done for official builds by the build robot.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
--83120MajorUIntValue1 ByteDifferent major version means incompatible changes.
MinVal: 0, MaxVal: 255
--91128MinorUIntValue1 ByteDifferent minor number means new functionality without breaking compatibility.
MinVal: 0, MaxVal: 255
--99136PatchUIntValue1 ByteThe patch version is changed when backwards-compatible bug fixes are made.
MinVal: 0, MaxVal: 255
--107144HashUIntValue4 BytesThe beginning of the revision ID hash (as reported by Git).
MinVal: 0, MaxVal: 4294967295

Message DeviceInfo (2)


Possible MessageTypes: Get, Status, AckStatus
Validity: test
Length w/o Header + HeaderExtension: 64 bits
Description: Reports DeviceType and current firmware version. Version information is only available when set in source code, which is usually only done for official builds by the build robot.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
--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, 20 = EnvSensor, 40 = PowerSwitch, 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

Message HardwareError (3)


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

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

Message BatteryStatus (5)


Possible MessageTypes: Get, Status, AckStatus
Validity: test
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
SetSetGetStatusAckStatus
--83120PercentageUIntValue7 BitsThe remaining capacity of the battery from 0 (empty) to 100 (full).
MinVal: 0, MaxVal: 100

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: test
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
SetSetGetStatusAckStatus
959583120OnBoolValue[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: test
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
SetSetGetStatusAckStatus
Structured array with 2 sub elements
959583120OnBoolValue[8]1 Bit x 8Tells if the pin is on (at high level) or not (low level).
969684121TimeoutSecUIntValue[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: test
Length w/o Header + HeaderExtension: 4 bits
Description: This represents the state of one pin of the digital port.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
959583120PosUIntValue3 BitsThe number of the pin in the port.
MinVal: 0, MaxVal: 7
989886123OnBoolValue1 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: test
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
SetSetGetStatusAckStatus
959583120PosUIntValue3 BitsThe number of the pin in the port.
MinVal: 0, MaxVal: 7
989886123OnBoolValue1 BitTells if the pin is on (at high level) or not (low level).
999987124TimeoutSecUIntValue2 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
SetSetGetStatusAckStatus
Structured array with 2 sub elements
959583120OnBoolValue[8]1 Bit x 8Tells if the pin is on (voltage over trigger threshold) or not.
969684121VoltageUIntValue[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: test
Length w/o Header + HeaderExtension: 16 bits
Description: This is a message containing temperature only.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
--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: test
Length w/o Header + HeaderExtension: 26 bits
Description: This is a message containing humidity and temperature.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
--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: test
Length w/o Header + HeaderExtension: 33 bits
Description: This is a message containing barometric pressure and temperature.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
--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: test
Length w/o Header + HeaderExtension: 10 bits
Description: This is a message containing humidity.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
--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: test
Length w/o Header + HeaderExtension: 7 bits

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

Message Distance (2)


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

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

Message Group PowerSwitch (20)

Message SwitchState (1)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: deprecated
Length w/o Header + HeaderExtension: 17 bits
Description: This is the state of the relais and its timeout value.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
959583120OnBoolValue1 BitTells if the switch is on (active).
969684121TimeoutSecUIntValue2 BytesThe time after which the switch is automatically toggled again. Use 0 to disable this.
MinVal: 0, MaxVal: 65535

Message SwitchStateExt (2)


Possible MessageTypes: Get, Set, SetGet, Status, Ack, AckStatus
Validity: deprecated
Length w/o Header + HeaderExtension: 136 bits
Description: This is the state of up to 8 relais and its timeout values.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
959583120OnBoolValue[8]1 Bit x 8
10310391128TimeoutSecUIntValue[8]2 Bytes x 8The time after which the switch is automatically toggled again. Use 0 to disable this.
MinVal: 0, MaxVal: 65535

Message Group Dimmer (60)

Message Brightness (1)


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

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
959583120BrightnessUIntValue7 BitsThe brightness in percent. 0 = Off.
MinVal: 0, MaxVal: 100

Message Animation (2)


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

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
959583120AnimationModeEnumValue2 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
979785122TimeoutSecUIntValue2 BytesThe time for the animation. Use 0 to disable this.
MinVal: 0, MaxVal: 65535
113113101138StartBrightnessUIntValue7 BitsThe brightness in percent at the beginning of the animation.
MinVal: 0, MaxVal: 100
120120108145EndBrightnessUIntValue7 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: test
Length w/o Header + HeaderExtension: 6 bits
Description: This is to set a fixed color.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
959583120ColorUIntValue6 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: test
Length w/o Header + HeaderExtension: 115 bits
Description: This is to set a color animation.

Offset (Bits)NameTypeSizeDescription
SetSetGetStatusAckStatus
959583120RepeatUIntValue4 BitsThe number of times the animation will be repeated. 0 means infinitely.
MinVal: 0, MaxVal: 15
999987124AutoReverseBoolValue1 BitIf true, the animation will be played back in the normal direction and then in reverse order.
Structured array with 2 sub elements
10010088125TimeUIntValue[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
10510593130ColorUIntValue[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)