# Device commands
The Network Command protocol makes it possible to get and set configuration, manage channel allocation and adaptive power management for End Devices.
End Device Command messages are defined by the protocol and MAY be extended by the use of proprietary commands. The Command ID is set in the Command (Cmd) field of the frame and the payload is command specific.
| Command ID 1 byte | Command payload |
|---|
The following table list the Commands that and End Device MAY support:
| ID | Command Description | Payload |
|---|---|---|
| 0x0x | Device operation | |
| 0x00 | No-operation | |
| 0x01 | Reboot | |
| 0x02 | Power off | |
| 0x03 | Factory reset | |
| 0x04 | Clear Content Store | |
| 0x1x | Status request | |
| 0x11 | Send Battery level event | |
| 0x12 | Send Device Info event | |
| 0x13 | Send Feature Info event | |
| 0x14 | Send Device status event | |
| 0x2x | Configuration | |
| 0x21 | Set Time | Timestamp |
| 0x22 | Set Network configuration | Network configuration |
| 0x23 | Set Feature Name configuration | Feature Name configuration |
| 0x24 | Set Feature NetID+Name configuration | Feature NetID+Name configuration |
| 0x25 | Set Feature Event Producer cfg | Feature Event Producer configuration |
| 0x26 | Set Feature Event Consumer cfg | Feature Event Consumer configuration |
| 0x27 | Disable Feature | Feature ID |
| 0x3x | Software scheduling | |
| 0x31 | Schedule Software update | Timestamp, Name-hash, uint16 freq, byte[16] software decryption key |
| 0x32 | Cancel Software update | Timestamp, Name-hash |
| 0x4x | Messaging | |
| 0x41 | Wake up at this time and listen for data | Network time |
| 0x42 | Wake up at this time and listen for data on freq X | Network time, freq |
| 0x5x - 0xDx | Reserved | |
| 0x50 - 0xDF | Reserved | |
| 0xEx | Proprietary | |
| 0xE0 - 0xEF | Proprietary commands | |
| 0xFx | Proprietary | |
| 0xF0 - 0xFF | Reserved |
# 0x0X - Device operation
# Reboot (0x01)
Request that the device reboots itself.
# Power off (0x02)
Request that the device power off itself.
# Factory reset (0x03)
Request that the device Factory reset itself.
# Clear Content Store (0x04)
Request that the device clears it's Content Store.
# 0x1X - Status request
# Send Battery level event (0x11)
Sends the battery level, in percent.
The message has the following format:
| Battery level [%] |
|---|
| 1 byte |
# Send Device Info (0x12)
Request that the device sends a Device info event. This request has no payload.
# Send Feature Info (0x13)
Request that the device sends a Feature Info event. This request has no payload.
# Send Feature Status (0x14)
Request that the device sends a Feature Status event. This request has no payload.
# 0x2X - Configuration
# Set Time (0x21)
Requests that the device sets its own time. It MUST do that by retrieving the time from the network.
# Set Network configuration (0x22)
In order for a Device to communicate with its network, it needs to know it's Network ID and the Network key. In order for a device to trust the data it receives, devices use a network key. This Network configuration message consists of the Network ID, a Key properties field describing the method and key ID followed by the key itself. If the Z-Mesh Public Key is used, the Key field not present.
The Payload MAC field is generated from the first 3 fields fields: Net ID, KeyProps and Key, using the key from the Key field.
| Net ID | KeyProps | Key | Payload MAC |
|---|---|---|---|
| 4 bytes | 1 byte | 0/16 bytes | 4 bytes |
The Payload MAC is placed in the payload field of the final frame. When sent, it will have the MAC attached which is generated from the current main Network Key. At the receiving end, the frame is decrypted the Payload MAC verifies that the Key is correct.
# Key Properties (KeyProps)
The Key Properties field holds the NwkkeyId and the method used for generating the message authentication code. The field is composed as follows:
| NwkKey Method | RFU | Default | NwkKeyId |
|---|---|---|---|
| [7:6] | [5:3] | [2] | [1:0] |
The Default field is a bit that, when set, tells the Device to use this Network Key as default key when sending data. Only one of the four keys in a network can be default but devices MUST be able to hold up to four Network Keys. Multiple network keys allows for networks within networks (VLANs) and eases the transistion to a new Network Key.
# NwkKey Method
The Network Key is used to generate the Message Authentication Code (MAC), which is a cryptographic signature that can be used to validate that the message has not been tampered with. The method can be chosen by setting the NwkKey Method field as follows:
| Method | MAC |
|---|---|
| 0 | None |
| 1 | AES-128-CMAC |
| 2-3 | RFU |
# Set Feature Name Configuration (0x23)
To associate a feature with a Content Name, the following Feature Name Configuration message is sent to the device. The payload contains the following fields:
- Feature ID
- Content Name - The Content Name Hash for the feature
- Encryption method and key number (ID)
- IV and Key - Encryption key to use for the Content
This table details the message payload format.
| Feature ID | Content Name | EncMethod | IV | Key |
|---|---|---|---|---|
| 1 byte | 6 bytes | 1 byte | 0/9 bytes | 0/16 bytes |
If encryption is not used, then the IV and KEY fields are omitted.
# Set Feature NetID + Name Configuration (0x24)
To associate a feature with a Network ID and a Content Name, the following Feature Name Configuration message is sent to the device. The payload contains the following fields:
- Feature ID
- Network ID
- Content Name - The Content Name Hash for the feature
- IV and Key - Encryption key to use for the Content
This table details the message payload format.
| Feature ID | NetID | Content Name | EncMethod | IV | Key |
|---|---|---|---|---|---|
| 1 byte | 4 bytes | 6 bytes | 1 byte | 9 bytes | 16 bytes |
If encryption is not used, then the IV and KEY fields are omitted.
# Set Feature Event Producer Configuration (0x25)
This configuration message informs the device how to send messages to the configured Content Name. Features that produce events at a regular interval will set the Event Interval field to a value greater than zero. Rule Conditions instructs the feature to send the event when the rule applies, eg. when a temperature is above a certain threshold value (denoted with the C in the Rule-C-X field).
The payload field contains the following:
| Feature ID | SerFmt | Event Group | Event Type | Event Interval | NumRules | Rule-C-1 | Rule-C-2 | ... | Rule-C-N |
|---|---|---|---|---|---|---|---|---|---|
| 1 byte | 1 bytes | 1 byte | 1 byte | 2 bytes | 1 byte | X bytes | X bytes | ... | X bytes |
Event Group and Event Type fields tells the Feature what message format is to be used for producing messages. Message formats are specified in the Application layer.
See rules below for a description of the format.
# Set Feature Event Consumer Configuration (0x26)
This configuration message informs the device what to do with receive messages on the configured Content Name. Rules contains both Conditions and Actions (denoted with Rule-CA-X below)and if supported by device and contained in the this message, the device MUST apply them to each incoming message.
The payload field contains the following:
| Feature ID | SerFmt | Event Group | Event Type | Interest Interval | TimerExp | Timer Action | NumRules | Rule-CA-1 | Rule-CA-2 | ... | Rule-CA-N |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 byte | 1 bytes | 1 byte | 1 byte | 2 bytes | 2 bytes | 1 byte | 1 byte | X bytes | X bytes | ... | X bytes |
Event Group and Event Type fields tells the Feature what message format is to be expected. Message formats are specified in the Application layer.
# Interest Interval
A value of 0 (zero) means that this FeatureID should not send out Interest messages. A non-zero value specifies, in seconds, the interval at which Interest messages are sent out.
Battery-driven event-consumers are sleeping most of the time so they will wake up and send out an interest message and wait for the content message reply, with the interval specified in this field. Mains-powered devices SHOULD also set this to a non-zero value so that the Content-Stores PIT tables know where to forward data (Interest subscribe).
# TimerExp
This field specifies the seconds between recurring events or 0 (zero) if it is only event driven.
# TimerAction
Specifies the Action to take when the timer expires.
# Rule Conditon
When the feature receives new content, the rule-logic will match the input against the Condition and Condition Value.
For example, if the Condition field contains 0x02 and the Condition Value contains 26.0, the rule will match when the input value received is less than 26.0. If the input is 0x20 and the Condition Value contains "OK", the rule will match when the exact string "OK" is received.
The NumRules field describes the number of rules following the NumRules field. Each Rule field describes how to match the incoming message. The Rule Condition contains three fields, the Condition (containing Data Type and Operator), a Condition Value to compare with and a Data Offset that describes where in the payload the data can be found.
| Condition | Condition Value | Data Offset |
|---|---|---|
| 1 byte | N bytes | 1 byte |
# Condition
The Condition field is composed as follows:
| RFU | Data Type | RFU | Operator |
|---|---|---|---|
| [7] | [6:4] | [3] | [2:0] |
Data Type
The Data Type field describes the types of data is to be compared.
| Type | Description | Value field |
|---|---|---|
| 0 | Number (Float) | 4-byte IEEE-754 single-presision floating point |
| 1 | Number (double) | 8-byte IEEE-754 double-presision floating point |
| 2 | Text | First byte contains length of text |
| 3 | Time | 6 bytes timestamp in milliseconds since EPOC |
| 4 | Location | First byte contains length of GeoHash |
| 5-7 | Reserved |
Operator
The Operator fields can contain the following values:
| Operator | Number | Text | Time | Location |
|---|---|---|---|---|
| 0 | = | Equals | Exact | Exact |
| 1 | != | Not equals | Before | Within |
| 2 | < | Contains | After | Not within |
| 3 | <= | Not Contains | ||
| 4 | > | Empty | ||
| 5 | >= | Not Empty |
# Condition Value
The Data Type and length of the Condition Value field is specified by the Data-Type field in the Condition byte. For a Floating point (Data Type = 0) it will contain 4-bytes.
# Data Offset
Data Offset describes the starting position of the Data Value to be compared with the Condition Value. As the payload in a Content Message contains either a single value, eg. temperature, or multiple values like lat. lon. from a GPS, G-forces from an accelerometer in X,Y,Z-form or a combination of data-types. In order for a Rule to select the right Data Value to compare with the Condition (Operator and Condition Value),
# Rule Action
Rule Actions instructs the device what action to take if the Condition matches. Most actions can be accomplished using the Action byte without needing the Action Value byte(s), but some cases may need to set a floating point value or a timestamp for a specific purpose.
| Action | Action Value |
|---|---|
| 1 byte | 0-M bytes |
# Action & Action Value
The Action byte describes what action to take. This table shows the possible actions:
| Action | Action Value | Description |
|---|---|---|
| 0 | Off | |
| 1 | On | |
| 2 | Toggle | |
| 3 | Increment1 | |
| 4 | Decrement1 | |
| 5 | Increment2 | |
| 6 | Decrement2 | |
| 7 - 15 | Reserved | |
| 16 | Float | Action Value number |
| 17 | Double | Action Value number |
| 18 | Text | Action Value text (first byte contains length) |
| 19 | 6 bytes | Action Value Time |
| 20 | Byte array | Action Value Location (first byte contains length) |
| 21 - 127 | Reserved | |
| -1 - -100 | Level (int8 1 to 100) | |
| -101 - -128 | Reserved |
The Action Value field is only present when the Action value is between 16 and 20 (both incl.).
# Disable Feature (0x27)
This command will cause the device to disable the feature with the Feature ID contained in the payload. When called, the device SHOULD call it's de-init feature which in turn will cause the feature to not respond to Interest messages or in any way send out data.
This details the message payload format.
| Feature ID |
|---|
| 1 byte |
# 0x3X - Software Update scheduling
# Schedule Software update (0x31)
In order for a sleepy device to know when an software (firmware) update is due to be broadcasted, it must receive a Software Update schedule message. This message contains the following information:
| Update Time | Name hash | MTU | Enc. type | Enc. IV | Enc. Key |
|---|---|---|---|---|---|
| 6 bytes | 6 bytes | 2 bytes | 1 byte | 6 bytes | 16 bytes |
# Cancel Software update (0x32)
This will cancel an update schedules to be executed in the future.
| Timestamp | Name hash |
|---|---|
| 6 bytes | 6 bytes |
# 0x4X - Messaging
# Wake up at this time and listen for data (0x41)
A sleepy device MAY suport waking up at a specified time.
The message has the following format:
| Wakeup Time [ms] | Listen time [ms] |
|---|---|
| 6 bytes | 2 bytes |
# Wake up at this time and listen for data on freq X (0x42)
A sleepy device MAY suport waking up at a specified time listening on a specified frequency.
The message has the following format:
| Wakeup Time [ms] | Listen time [ms] | Frequency [Hz] |
|---|---|---|
| 6 bytes | 2 bytes | 4 bytes |