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
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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | DeviceType | EnumValue | 1 Byte | The 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 |
- | - | - | 91 | 128 | VersionMajor | UIntValue | 1 Byte | Different major version means incompatible changes. MinVal: 0, MaxVal: 255 |
- | - | - | 99 | 136 | VersionMinor | UIntValue | 1 Byte | Different minor number means new functionality without breaking compatibility. MinVal: 0, MaxVal: 255 |
- | - | - | 107 | 144 | VersionPatch | UIntValue | 1 Byte | The patch version is changed when backwards-compatible bug fixes are made. MinVal: 0, MaxVal: 255 |
- | - | - | 115 | 152 | VersionHash | UIntValue | 4 Bytes | The beginning of the revision ID hash (as reported by Git). MinVal: 0, MaxVal: 4294967295 |
- | - | - | 147 | 184 | HardwareVersionMajor | UIntValue | 1 Byte | Different major version means a major redesign of the schematic or PCB layout. MinVal: 0, MaxVal: 255 |
- | - | - | 155 | 192 | HardwareVersionMinor | UIntValue | 1 Byte | Different 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | - | ErrorCode | EnumValue | 1 Byte | Lists 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | Percentage | UIntValue | 7 Bits | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | 95 | 83 | 120 | OnSec | UIntValue | 2 Bytes | This 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 |
111 | 111 | 111 | 99 | 136 | OffSec | UIntValue | 2 Bytes | This 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 |
127 | 127 | 127 | 115 | 152 | OnRemainingSec | UIntValue | 2 Bytes | The 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 |
143 | 143 | 143 | 131 | 168 | OffRemainingSec | UIntValue | 2 Bytes | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | On | BoolValue[8] | 1 Bit x 8 | Tells 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
Structured array with 2 sub elements |
95 | 95 | - | 83 | 120 | On | BoolValue[8] | 1 Bit x 8 | Tells if the pin is on (at high level) or not (low level). |
96 | 96 | - | 84 | 121 | TimeoutSec | UIntValue[8] | 2 Bytes x 8 | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Pos | UIntValue | 3 Bits | The number of the pin in the port. MinVal: 0, MaxVal: 7 |
98 | 98 | - | 86 | 123 | On | BoolValue | 1 Bit | Tells 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Pos | UIntValue | 3 Bits | The number of the pin in the port. MinVal: 0, MaxVal: 7 |
98 | 98 | - | 86 | 123 | On | BoolValue | 1 Bit | Tells if the pin is on (at high level) or not (low level). |
99 | 99 | - | 87 | 124 | TimeoutSec | UIntValue | 2 Bytes | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
Structured array with 2 sub elements |
95 | 95 | - | 83 | 120 | On | BoolValue[8] | 1 Bit x 8 | Tells if the pin is on (voltage over trigger threshold) or not. |
96 | 96 | - | 84 | 121 | Voltage | UIntValue[8] | 11 Bits x 8 | This 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | Temperature | IntValue | 2 Bytes | temperature [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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | Humidity | UIntValue | 10 Bits | relative humidity permill, 0..1000 (other values not defined) MinVal: 0, MaxVal: 1000 |
- | - | - | 93 | 130 | Temperature | IntValue | 2 Bytes | temperature [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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | BarometricPressure | UIntValue | 17 Bits | barometric pressure in pascal MinVal: 0, MaxVal: 131071 |
- | - | - | 100 | 137 | Temperature | IntValue | 2 Bytes | temperature [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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | Humidity | UIntValue | 10 Bits | relative 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | Brightness | UIntValue | 7 Bits | brightness 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | Distance | UIntValue | 14 Bits | distance 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
- | - | - | 83 | 120 | TypicalParticleSize | UIntValue | 10 Bits | Typical Particle Size [1/100 μm]. Use 1023 when value invalid. MinVal: 0, MaxVal: 1023 |
Structured array with 3 sub elements |
- | - | - | 93 | 130 | Size | UIntValue[5] | 1 Byte x 5 | Maximum 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 |
- | - | - | 101 | 138 | MassConcentration | UIntValue[5] | 10 Bits x 5 | Mass concentration [1/10 μg/m3], considering the defined size. Use 1023 when the value is invalid. MinVal: 0, MaxVal: 1023 |
- | - | - | 111 | 148 | NumberConcentration | UIntValue[5] | 12 Bits x 5 | Number 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | PosY | UIntValue | 5 Bits | Y (line) position at which the text shall be displayed. Line numbers above 3 are for the corresponding virtual lines / pages. MinVal: 0, MaxVal: 31 |
100 | 100 | - | 88 | 125 | PosX | UIntValue | 7 Bits | X (character) position at which the text shall be displayed. MinVal: 0, MaxVal: 79 |
107 | 107 | - | 95 | 132 | Format | UIntValue | 4 Bits | Format, font, or other value which modifies how the text is displayed. Depends on the implementation of the device. MinVal: 0, MaxVal: 15 |
111 | 111 | - | 99 | 136 | Text | ByteArray | 40 Bytes | 40 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Mode | EnumValue | 4 Bits | The 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 |
99 | 99 | - | 87 | 124 | AutoTimeoutSec | UIntValue | 1 Byte | This 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.
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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | 95 | 83 | 120 | Index | UIntValue[16] | 1 Byte x 16 | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | - | - | 83 | - | Code | ByteArray | 3 Bytes | 3 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Tone | UIntValue | 7 Bits | Tone 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Repeat | UIntValue | 4 Bits | The number of times the melody will be repeated. 0 means infinitely. MinVal: 0, MaxVal: 15 |
99 | 99 | - | 87 | 124 | AutoReverse | BoolValue | 1 Bit | If true, the melody will be played back in the normal direction and then in reverse order. |
Structured array with 3 sub elements |
100 | 100 | - | 88 | 125 | Time | UIntValue[25] | 5 Bits x 25 | The 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 |
105 | 105 | - | 93 | 130 | Effect | UIntValue[25] | 3 Bits x 25 | Define 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 |
108 | 108 | - | 96 | 133 | Tone | UIntValue[25] | 7 Bits x 25 | Index 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Brightness | UIntValue | 7 Bits | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | AnimationMode | EnumValue | 2 Bits | If 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 |
97 | 97 | - | 85 | 122 | TimeoutSec | UIntValue | 2 Bytes | The time for the animation. Use 0 to disable this. MinVal: 0, MaxVal: 65535 |
113 | 113 | - | 101 | 138 | StartBrightness | UIntValue | 7 Bits | The brightness in percent at the beginning of the animation. MinVal: 0, MaxVal: 100 |
120 | 120 | - | 108 | 145 | EndBrightness | UIntValue | 7 Bits | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Color | UIntValue | 6 Bits | The 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) | Name | Type | Size | Description |
Set | SetGet | Deliver | Status | AckStatus |
95 | 95 | - | 83 | 120 | Repeat | UIntValue | 4 Bits | The number of times the animation will be repeated. 0 means infinitely. MinVal: 0, MaxVal: 15 |
99 | 99 | - | 87 | 124 | AutoReverse | BoolValue | 1 Bit | If true, the animation will be played back in the normal direction and then in reverse order. |
Structured array with 2 sub elements |
100 | 100 | - | 88 | 125 | Time | UIntValue[10] | 5 Bits x 10 | The 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 |
105 | 105 | - | 93 | 130 | Color | UIntValue[10] | 6 Bits x 10 | The 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) |