Message Structure
The serial protocol used between the Gateway and the Controller is a simple semicolon separated list of values. The last part of each "command" is the payload. All commands ends with a newline. The serial commands has the following format:
node-id ; child-sensor-id ; command ; ack ; type ; payload \n
You can play around with the debug output from your gateway or nodes using our online log parser.
| Message Part | Comment |
|---|---|
node-id |
The unique id of the node that sends or should receive the message (address) |
child-sensor-id |
Each node can have several sensors attached. This is the child-sensor-id that uniquely identifies one attached sensor |
command |
Type of command sent - See table below |
ack |
The ack parameter has the following meaning: Outgoing: 0 = unacknowledged message, 1 = request ack from destination node, Incoming: 0 = normal message, 1 = this is an ack message |
type |
Depending on command, the type field has different meaning. See tables below |
payload |
The payload holds the message coming in from sensors or instruction going out to actuators. |
**The maximum payload size is 25 bytes!**
The nRF24L01+ has a maximum of 32 bytes. The MySensors library (version 2.x) uses 7 bytes for the message header.
command
| Type | Value | Comment |
|---|---|---|
| presentation | 0 | Sent by a node when they present attached sensors. This is usually done in the ** presentation()** function which runs at startup. |
| set | 1 | This message is sent from or to a sensor when a sensor value should be updated |
| req | 2 | Requests a variable value (usually from an actuator destined for controller). |
| internal | 3 | This is a special internal message. See table below for the details |
| stream | 4 | Used for OTA firmware updates |
presentation
When a presentation message is sent from a sensor, type can one the following:
The payload of presentation message will be set to the library version (node device) or an optional description for the sensors.
| Type | Value | Comment | Variables |
|---|---|---|---|
| S_DOOR | 0 | Door and window sensors | V_TRIPPED, V_ARMED |
| S_MOTION | 1 | Motion sensors | V_TRIPPED, V_ARMED |
| S_SMOKE | 2 | Smoke sensor | V_TRIPPED, V_ARMED |
| S_BINARY | 3 | Binary device (on/off) | V_STATUS, V_WATT |
| S_DIMMER | 4 | Dimmable device of some kind | V_STATUS (on/off), V_PERCENTAGE (dimmer level 0-100), V_WATT |
| S_COVER | 5 | Window covers or shades | V_UP, V_DOWN, V_STOP, V_PERCENTAGE |
| S_TEMP | 6 | Temperature sensor | V_TEMP, V_ID |
| S_HUM | 7 | Humidity sensor | V_HUM |
| S_BARO | 8 | Barometer sensor (Pressure) | V_PRESSURE, V_FORECAST |
| S_WIND | 9 | Wind sensor | V_WIND, V_GUST, V_DIRECTION |
| S_RAIN | 10 | Rain sensor | V_RAIN, V_RAINRATE |
| S_UV | 11 | UV sensor | V_UV |
| S_WEIGHT | 12 | Weight sensor for scales etc. | V_WEIGHT, V_IMPEDANCE |
| S_POWER | 13 | Power measuring device, like power meters | V_WATT, V_KWH, V_VAR, V_VA, V_POWER_FACTOR |
| S_HEATER | 14 | Heater device | V_HVAC_SETPOINT_HEAT, V_HVAC_FLOW_STATE, V_TEMP, V_STATUS |
| S_DISTANCE | 15 | Distance sensor | V_DISTANCE, V_UNIT_PREFIX |
| S_LIGHT_LEVEL | 16 | Light sensor | V_LIGHT_LEVEL (uncalibrated percentage), V_LEVEL (light level in lux) |
| S_ARDUINO_NODE | 17 | Arduino node device | |
| S_ARDUINO_REPEATER_NODE | 18 | Arduino repeating node device | |
| S_LOCK | 19 | Lock device | V_LOCK_STATUS |
| S_IR | 20 | Ir sender/receiver device | V_IR_SEND, V_IR_RECEIVE, V_IR_RECORD |
| S_WATER | 21 | Water meter | V_FLOW, V_VOLUME |
| S_AIR_QUALITY | 22 | Air quality sensor e.g. MQ-2 | V_LEVEL, V_UNIT_PREFIX |
| S_CUSTOM | 23 | Use this for custom sensors where no other fits. | |
| S_DUST | 24 | Dust level sensor | V_LEVEL, V_UNIT_PREFIX |
| S_SCENE_CONTROLLER | 25 | Scene controller device | V_SCENE_ON, V_SCENE_OFF |
| S_RGB_LIGHT | 26 | RGB light | V_RGB, V_WATT |
| S_RGBW_LIGHT | 27 | RGBW light (with separate white component) | V_RGBW, V_WATT |
| S_COLOR_SENSOR | 28 | Color sensor | V_RGB |
| S_HVAC | 29 | Thermostat/HVAC device | V_STATUS, V_TEMP, V_HVAC_SETPOINT_HEAT, V_HVAC_SETPOINT_COOL, V_HVAC_FLOW_STATE, V_HVAC_FLOW_MODE, V_HVAC_SPEED |
| S_MULTIMETER | 30 | Multimeter device | V_VOLTAGE, V_CURRENT, V_IMPEDANCE |
| S_SPRINKLER | 31 | Sprinkler device | V_STATUS (turn on/off), V_TRIPPED (if fire detecting device) |
| S_WATER_LEAK | 32 | Water leak sensor | V_TRIPPED, V_ARMED |
| S_SOUND | 33 | Sound sensor | V_LEVEL (in dB), V_TRIPPED, V_ARMED |
| S_VIBRATION | 34 | Vibration sensor | V_LEVEL (vibration in Hz), V_TRIPPED, V_ARMED |
| S_MOISTURE | 35 | Moisture sensor | V_LEVEL (water content or moisture in percentage?), V_TRIPPED, V_ARMED |
| S_INFO | 36 | LCD text device | V_TEXT |
| S_GAS | 37 | Gas meter | V_FLOW, V_VOLUME |
| S_GPS | 38 | GPS Sensor | V_POSITION |
| S_WATER_QUALITY | 39 | Water quality sensor | V_TEMP, V_PH, V_ORP, V_EC, V_STATUS |
set, req
When a set or request message is being sent, the type has to be one of the following:
| Type | Value | Comment | Used by |
|---|---|---|---|
| V_TEMP | 0 | Temperature | S_TEMP, S_HEATER, S_HVAC, S_WATER_QUALITY |
| V_HUM | 1 | Humidity | S_HUM |
| V_STATUS | 2 | Binary status. 0=off 1=on | S_BINARY, S_DIMMER, S_SPRINKLER, S_HVAC, S_HEATER, S_WATER_QUALITY |
| V_PERCENTAGE | 3 | Percentage value. 0-100 (%) | S_DIMMER, S_COVER |
| V_PRESSURE | 4 | Atmospheric Pressure | S_BARO |
| V_FORECAST | 5 | Whether forecast. One of "stable", "sunny", "cloudy", "unstable", "thunderstorm" or "unknown" | S_BARO |
| V_RAIN | 6 | Amount of rain | S_RAIN |
| V_RAINRATE | 7 | Rate of rain | S_RAIN |
| V_WIND | 8 | Windspeed | S_WIND |
| V_GUST | 9 | Gust | S_WIND |
| V_DIRECTION | 10 | Wind direction 0-360 (degrees) | S_WIND |
| V_UV | 11 | UV light level | S_UV |
| V_WEIGHT | 12 | Weight (for scales etc) | S_WEIGHT |
| V_DISTANCE | 13 | Distance | S_DISTANCE |
| V_IMPEDANCE | 14 | Impedance value | S_MULTIMETER, S_WEIGHT |
| V_ARMED | 15 | Armed status of a security sensor. 1=Armed, 0=Bypassed | S_DOOR, S_MOTION, S_SMOKE, S_SPRINKLER, S_WATER_LEAK, S_SOUND, S_VIBRATION, S_MOISTURE |
| V_TRIPPED | 16 | Tripped status of a security sensor. 1=Tripped, 0=Untripped | S_DOOR, S_MOTION, S_SMOKE, S_SPRINKLER, S_WATER_LEAK, S_SOUND, S_VIBRATION, S_MOISTURE |
| V_WATT | 17 | Watt value for power meters | S_POWER, S_BINARY, S_DIMMER, S_RGB_LIGHT, S_RGBW_LIGHT |
| V_KWH | 18 | Accumulated number of KWH for a power meter | S_POWER |
| V_SCENE_ON | 19 | Turn on a scene | S_SCENE_CONTROLLER |
| V_SCENE_OFF | 20 | Turn of a scene | S_SCENE_CONTROLLER |
| V_HVAC_FLOW_STATE | 21 | Mode of header. One of "Off", "HeatOn", "CoolOn", or "AutoChangeOver" | S_HVAC, S_HEATER |
| V_HVAC_SPEED | 22 | HVAC/Heater fan speed ("Min", "Normal", "Max", "Auto") | S_HVAC, S_HEATER |
| V_LIGHT_LEVEL | 23 | Uncalibrated light level. 0-100%. Use V_LEVEL for light level in lux. | S_LIGHT_LEVEL |
| V_VAR1 | 24 | Custom value | Any device |
| V_VAR2 | 25 | Custom value | Any device |
| V_VAR3 | 26 | Custom value | Any device |
| V_VAR4 | 27 | Custom value | Any device |
| V_VAR5 | 28 | Custom value | Any device |
| V_UP | 29 | Window covering. Up. | S_COVER |
| V_DOWN | 30 | Window covering. Down. | S_COVER |
| V_STOP | 31 | Window covering. Stop. | S_COVER |
| V_IR_SEND | 32 | Send out an IR-command | S_IR |
| V_IR_RECEIVE | 33 | This message contains a received IR-command | S_IR |
| V_FLOW | 34 | Flow of water/gas (in meter) | S_WATER, S_GAS |
| V_VOLUME | 35 | Water/gas volume | S_WATER, S_GAS |
| V_LOCK_STATUS | 36 | Set or get lock status. 1=Locked, 0=Unlocked | S_LOCK |
| V_LEVEL | 37 | Used for sending level-value | S_DUST, S_AIR_QUALITY, S_SOUND (dB), S_VIBRATION (hz), S_LIGHT_LEVEL (lux) |
| V_VOLTAGE | 38 | Voltage level | S_MULTIMETER |
| V_CURRENT | 39 | Current level | S_MULTIMETER |
| V_RGB | 40 | RGB value transmitted as ASCII hex string (I.e "ff0000" for red) | S_RGB_LIGHT, S_COLOR_SENSOR |
| V_RGBW | 41 | RGBW value transmitted as ASCII hex string (I.e "ff0000ff" for red + full white) | S_RGBW_LIGHT |
| V_ID | 42 | Optional unique sensor id (e.g. OneWire DS1820b ids) | S_TEMP |
| V_UNIT_PREFIX | 43 | Allows sensors to send in a string representing the unit prefix to be displayed in GUI. This is not parsed by controller! E.g. cm, m, km, inch. | S_DISTANCE, S_DUST, S_AIR_QUALITY |
| V_HVAC_SETPOINT_COOL | 44 | HVAC cold setpoint | S_HVAC |
| V_HVAC_SETPOINT_HEAT | 45 | HVAC/Heater setpoint | S_HVAC, S_HEATER |
| V_HVAC_FLOW_MODE | 46 | Flow mode for HVAC ("Auto", "ContinuousOn", "PeriodicOn") | S_HVAC |
| V_TEXT | 47 | Text message to display on LCD or controller device | S_INFO |
| V_CUSTOM | 48 | Custom messages used for controller/inter node specific commands, preferably using S_CUSTOM device type. | S_CUSTOM |
| V_POSITION | 49 | GPS position and altitude. Payload: latitude;longitude;altitude(m). E.g. "55.722526;13.017972;18" | S_GPS |
| V_IR_RECORD | 50 | Record IR codes S_IR for playback | S_IR |
| V_PH | 51 | Water PH | S_WATER_QUALITY |
| V_ORP | 52 | Water ORP : redox potential in mV | S_WATER_QUALITY |
| V_EC | 53 | Water electric conductivity μS/cm (microSiemens/cm) | S_WATER_QUALITY |
| V_VAR | 54 | Reactive power: volt-ampere reactive (var) | S_POWER |
| V_VA | 55 | Apparent power: volt-ampere (VA) | S_POWER |
| V_POWER_FACTOR | 56 | Ratio of real power to apparent power: floating point value in the range [-1,..,1] | S_POWER |
internal
The internal messages are used for different tasks in the communication between sensors, the gateway to controller and between sensors and the gateway.
When an internal messages is sent, the type has to be one of the following:
| Type | Value | Comment |
|---|---|---|
| I_BATTERY_LEVEL | 0 | Use this to report the battery level (in percent 0-100). |
| I_TIME | 1 | Sensors can request the current time from the Controller using this message. The time will be reported as the seconds since 1970 |
| I_VERSION | 2 | Used to request gateway version from controller. |
| I_ID_REQUEST | 3 | Use this to request a unique node id from the controller. |
| I_ID_RESPONSE | 4 | Id response back to node. Payload contains node id. |
| I_INCLUSION_MODE | 5 | Start/stop inclusion mode of the Controller (1=start, 0=stop). |
| I_CONFIG | 6 | Config request from node. Reply with (M)etric or (I)mperal back to sensor. |
| I_FIND_PARENT | 7 | When a sensor starts up, it broadcast a search request to all neighbor nodes. They reply with a I_FIND_PARENT_RESPONSE. |
| I_FIND_PARENT_RESPONSE | 8 | Reply message type to I_FIND_PARENT request. |
| I_LOG_MESSAGE | 9 | Sent by the gateway to the Controller to trace-log a message |
| I_CHILDREN | 10 | A message that can be used to transfer child sensors (from EEPROM routing table) of a repeating node. |
| I_SKETCH_NAME | 11 | Optional sketch name that can be used to identify sensor in the Controller GUI |
| I_SKETCH_VERSION | 12 | Optional sketch version that can be reported to keep track of the version of sensor in the Controller GUI. |
| I_REBOOT | 13 | Used by OTA firmware updates. Request for node to reboot. |
| I_GATEWAY_READY | 14 | Send by gateway to controller when startup is complete. |
| I_SIGNING_PRESENTATION | 15 | Provides signing related preferences (first byte is preference version). |
| I_NONCE_REQUEST | 16 | Used between sensors when requesting nonce. |
| I_NONCE_RESPONSE | 17 | Used between sensors for nonce response. |
| I_HEARTBEAT_REQUEST | 18 | Heartbeat request |
| I_PRESENTATION | 19 | Presentation message |
| I_DISCOVER_REQUEST | 20 | Discover request |
| I_DISCOVER_RESPONSE | 21 | Discover response |
| I_HEARTBEAT_RESPONSE | 22 | Heartbeat response |
| I_LOCKED | 23 | Node is locked (reason in string-payload) |
| I_PING | 24 | Ping sent to node, payload incremental hop counter |
| I_PONG | 25 | In return to ping, sent back to sender, payload incremental hop counter |
| I_REGISTRATION_REQUEST | 26 | Register request to GW |
| I_REGISTRATION_RESPONSE | 27 | Register response from GW |
| I_DEBUG | 28 | Debug message |
| I_SIGNAL_REPORT_REQUEST | 29 | Device signal strength request |
| I_SIGNAL_REPORT_REVERSE | 30 | Internal |
| I_SIGNAL_REPORT_RESPONSE | 31 | Device signal strength response (RSSI) |
| I_PRE_SLEEP_NOTIFICATION | 32 | Message sent before node is going to sleep |
| I_POST_SLEEP_NOTIFICATION | 33 | Message sent after node woke up (if enabled) |
Examples
Here are a few example of the serial protocol in action (from the gateways perspective).
Received message from radio network from one of the sensors: Incoming presentation message from node 12 with child sensor 6. The presentation is for a binary light S_BINARY. The payload holds a description of the sensor. Gateway passes this over to the controller.
12;6;0;0;3;My Light\nReceived message from radio network from one of the sensors: Incoming temperature V_TEMP message from node 12 with child sensor 6. The gateway passed this over to the controller.
12;6;1;0;0;36.5\nReceived command from the controller that should be passed to radio network: Outgoing message to node 13. Set V_BINARY variable to 1 (=turn on) for child sensor 7. No ack is requested from destination node.
13;7;1;0;2;1\n