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: 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) | 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, 20 = EnvSensor, 40 = PowerSwitch, 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 |
Message HardwareError (3)
Possible MessageTypes: Status
Validity: test
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 |
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 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 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) |
