# Device events
Event messages are makes it possible for the Device Management system to gather insight into the network- and device operation.
End Device Event messages are defined by the protocol and MAY be extended by the use of proprietary events. The Event ID is set in the Event (Evt) field of the frame and the payload is event specific.
| Event ID 1 byte | Event payload |
|---|
| ID | Description | Payload |
|---|---|---|
| 0x0x | Device operation | |
| 0x00 | No event | |
| 0x01 | Device has been restarted | |
| 0x1x | Device info and status | |
| 0x11 | RFU | |
| 0x12 | Device Info | |
| 0x13 | Feature Info | |
| 0x14 | Device Status | |
| 0x2x | Configuration | |
| RFU | ||
| 0x3x | Software scheduling | |
| RFU | ||
| 0x4x | Messaging | |
| RFU | ||
| 0x5x - 0xDx | Reserved | |
| 0xE | Proprietary | |
| RFU | Proprietary events | |
| 0xFx | Reserved | |
| RFU | ||
# Device has been restarted (0x01)
Optional event.
# Send Device-Info event (0x12)
Devices SHOULD respond to Device Information interest messages and wireless sleepy devices MUST periodically send out a Device Information message. Information messages SHOULD be encrypted and Content Stores MUST store the latest message received.
The Device Information message contains the following information about itself:
- Manufacturer
- Model
- Software version
- Network key ID
- Device capabilities
- Face Attributes
- Face physical address or frequency
The response format is:
| Mfgr. len | Mfgr. | Model len | Model | FW Major | FW Minor | FW Patch | EncMethods | NwkKeyId | Dev.Cap | Num faces | Face.Attr |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 byte | len bytes | 1 byte | len bytes | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 2 bytes |
# Encryption method (EncMethods)
This bit-field describes the Encryption methods the devices supports. If the bit is cleared (0) it means that the encryption type is not supported. If the bit is set (1) it means that it is supported. Encryption is specific to a Content Name and applied to the payload field only.
See the IV column for how the Initialization vector is calculated.
| Bit | Encryption Method | IV | Description |
|---|---|---|---|
| 0 | None | No encryption | |
| 1 | AES-128-CTR | 0 & (IV << 80 | FSEQ << 32 | CTR) | 9 byte IV, 3 byte FSEQ and 4 byte CTR |
| 2-7 | RFU |
For example, a value of 3 means that the device supports None and AES-128-CTR for Device Management communication.
# NwkKeyId
This field specifies which Network Key is used by the device. A value of 0 means that no network key is used and hence no MAC is calculated. Values 1 to 3 means that the corresponding Network Key is used for generating the MAC.
# Device Capabilities (Dev.Cap)
A Device SHOULD report it's capabilities to help the Network Management and Monitoring services visualize the Z-Mesh network. This byte represents a list of the capabilities:
| RFU [7:4] | Forwarder [3] | Content Store [2] | Sleepy [1] | Mains powered [0] |
|---|
A Forwarder is a device with more that 2 or more interfaces that allows routing or re-broadcasting of packets. Most Forwarders are also Content Store, and if so MUST set the Content Store bit. If the device is sleeping or offline, meaning that it MAY cannot receive content, it can indicate this in the Sleepy bit. Devices that are Mains powered should set the Mains Powered to 1 and battery driven devices should set this bit to 0.
# Face Attributes (Face.Attr)
A network interface has many attributes. Each Face (network interface) is described using the following attributes:
| Enabled [15] | Permanent [14] | RFU [13:12] | Media Type [11:8] | Broadcast [7] | Encapsulation [6:4] | RFU [3:2] | MTU [1:0] |
|---|
The order of the list of Face Attributes MUST correspond to the Face number in the device.
# Enabled
When set (to 1), means that the Face is enabled.
# Permanent
This bit specifies whether the face is permanent or dynamically created. Permanent faces are radios and static UDP links wherea a non-permanent client UDP-connection to a Content Stores is treated as a dynamic face.
# Media Type
The following Media Types are available
| ID | Media Type |
|---|---|
| 0 | Custom |
| 1 | 2.4GHz radio |
| 2 | Sub-GHz radio |
| 3 | 802.3 Wired Ethernet |
| 4 | 802.11 Wirless Ethernet |
| 5 | 802.15.4 WPAN |
| 6 | Cellular |
| 7-15 | RFU |
# Broadcast
Set if the medium is a broadcast medium. Cleared if the medium is point-to-point.
# Encapsulation
Z-Mesh is designed to run directly on the physical medium, but it can also be tunneled inside other types of protocols. This field indicates to the Device Management and Network Monitoring services, how this network interface is connected.
| ID | Encapsulation | Description |
|---|---|---|
| 0 | None | Z-Mesh without encapsulation |
| 1 | UDP | Z-Mesh tunneled inside UDP |
| 2 | Cellular Non-IP | Z-Mesh tunneled in cellular non-ip |
| 3-7 | RFU |
# MTU size (Maximum Transmission Unit)
Software updates or messages that cannot fit in a single message, must be sent in multiple messages. In order to maximize the efficiency, the maximum transmission unit must be known. The following list contains the valid options:
| ID | MTU Size |
|---|---|
| 0 | 64 bytes |
| 1 | 128 bytes |
| 2 | 1280 bytes |
| 3 | RFU |
# Face Addr/Freq
| Type | Address / Frequncy |
|---|---|
| 1 byte | N bytes |
This field consists of a 1-byte Type field and the Address / Frequency field itself. The length of the Address / Frequency field depends on the type of address.
The Type field values from 0-127 is compatible with the ones found in the GLIBC <bits/sockets.h> header file. For example for IPv4 the Type is 2 and the Address / Frequency field is 4 bytes in length, for IPv6 the value is 10 and the Address / Frequency field is 16 bytes in length and for 802.15.4 the value is 36 and is 10 bytes. Values from 128 are Z-Mesh specific. The field values are defined as follows:
| Type | Address / Frequency field contents |
|---|---|
| 0 - 127 | Value as specified in GLIBC <bits/sockets.h> |
| 128 | 4-byte frequency in Hz |
| 129 - 255 | Reserved |
# Feature Info (0x13)
Devices can have any number of features. Each feature is broadcasting and/or listening to a Content Name using the encryption iv and key assigned to the Content Name. Devices communicating on a Content Name MUST use the same serialization- and message format. For instance, a temperature sensor could send 22.8 as JSON, or a PIR sensor could send 1 or 0 in binary.
The format is:
| Feature ID | Feature name len | Feature name | Properties | EncMethods | SerFmts | NumEvts | Evt. Grp.1 | Evt. Type1 | Evt.Grp.2 | Evt.Type2 | ... | Evt.Grp.N | Evt.TypeN |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 byte | 1 byte | 1-8 bytes | 1 byte | 1 byte | 1 bytes | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | ... | 1 byte | 1 byte |
# Properties
This field describes global properties of a feature. Some properties is producer-specific while some are consumer specific. This table details which properties are available for event-producers and -consumers.
| Bit | Producer | Consumer | Description |
|---|---|---|---|
| 0 | X | X | 0=Producer, 1=Consumer |
| 1 | X | Event Interval supported | |
| 2 | X | Action Timer supported | |
| 3 | X | X | Rules are supported |
| 4-8 | RFU |
# Encryption Methods (EncMethods)
Bit map describing the supported Encryption Methods. See Encryption methods.
# Serialization format (SerFmts)
Bit map describing the supported Serialization formats.
| Bit | Description |
|---|---|
| 0 | Binary (MSB) |
| 1 | JSON |
| 2 | CBOR |
| 3-6 | RFU |
| 7 | Timestamp |
Bit 7 indicates that the timestamp is or can be included in the data. If the Device/Feature is an Event Producer (Eg. temp sensor), bit 7 (Timestamp) indicates to the Device Management system that the feature supports timestamping the Event. If the Device/Feature is an Event Consumer (eg. SmartPlug), bit 7 indicates that it supports receiving timestamped data.
# Number of Events (NumEvts)
This field describes how many event-types this feature supports.
# Event Group
The Event Group.
# Event Type
Type of event.
# Device Status event 0x14
Devices MUST respond to Device status interest messages and wireless sleepy devices MUST periodically send out a Features status message. This message allows the management function of the network to know the following details:
- Battery level in percent (if applicable)
- Uptime
- Status of all features
The format is:
| Batt. | Uptime | Feature list length | Status1 | Status2 | ... | StatusN |
|---|---|---|---|---|---|---|
| 1 byte | 4 bytes | 1 byte | 2 bytes | 2 bytes | ... | 2 bytes |
The "Feature list length" describes the number of features in the following array.
# Status (Feature field)
The Status byte contains information about the state of a feature, such as if is subscribed to a Content Name, if an error has occured.:
| Subscribed [15] | RFU [14:10] | Level [9:8] | Status code [7:0] |
|---|
Subscribed If this bit is set, then the feature is subscribed to a Content Name and SHOULD be broadcasting/listening on the Content Name.
Level
| Level | Description |
|---|---|
| 0 | OK |
| 1 | Info |
| 2 | Warning |
| 3 | Error |
Status code
| Status code | Description |
|---|---|
| 0 | OK |
| 1 - 127 | RFU |
| 128 - 255 | Application specific status codes |
Feature Status codes can be used to alert a maintenance team about the state of a feature. This could be a dispenser running low on battery or fill-level or that the IR sensor is blocked.