The 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>;message-type>;ack>;sub-type>;payload>\n
The maximum payload size is 25 bytes!
The NRF24L01+ has a maximum of 32 bytes. The MySensors library (version 1.5) uses 7 bytes for the message header.
| Type | Value | Comment |
|---|---|---|
| presentation | 0 | Sent by a node when they present attached sensors. This is usually done in setup() 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. |
If you feel that these sub-types don’t fit your needs, there are some custom varaibles that you can use. However, you think that people maybe have the same issue, you can modify the liberary and add your variable, then, pull your modifications to the development branch.
When a presentation message is sent from a sensor, sub-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.
Use this for custom sensors where no other fits.When a set or request message is being sent, the sub-type has to be one of the following:
Whether forecast. One of “stable”, “sunny”, “cloudy”, “unstable”, “thunderstorm” or “unknown” Armed status of a security sensor. 1=Armed, 0=Bypassed Tripped status of a security sensor. 1=Tripped, 0=Untripped Accumulated number of KWH for a power meter Mode of header. One of “Off”, “HeatOn”, “CoolOn”, or “AutoChangeOver” HVAC/Heater fan speed (“Min”, “Normal”, “Max”, “Auto”) Uncalibrated light level. 0-100%. Use V_LEVEL for light level in lux. This message contains a received Set or get lock status. 1=Locked, 0=Unlocked RGB value transmitted as ASCII hex string (I.e “ff0000” for red) RGBW value transmitted as ASCII hex string Optional unique sensor id (e.g. OneWire DS1820b ids) 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. Flow mode for HVAC (“Auto”, “ContinuousOn”, “PeriodicOn”)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 sub-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 sensor. Payload contains sensor 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_REQUEST_SIGNING | 15 | Used between sensors when initialting signing. |
| I_GET_NONCE | 16 | Used between sensors when requesting nonce. |
| I_GET_NONCE_RESPONSE | 17 | Used between sensors for nonce response. |
| I_HEARTBEAT | 18 | |
| I_PRESENTATION | 19 | |
| I_DISCOVER | 20 | |
| I_DISCOVER_RESPONSE | 21 |
| Type | Value | Comment |
|---|---|---|
| ST_FIRMWARE_CONFIG_REQUEST | 0 | |
| ST_FIRMWARE_CONFIG_RESPONSE | 1 | |
| ST_FIRMWARE_REQUEST | 2 | |
| ST_FIRMWARE_RESPONSE | 3 | |
| ST_SOUND | 4 | Used to transfer sound to controller |
| ST_IMAGE | 5 | Used to transfer image to controller |
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_LIGHT. The payload holds a description of the sensor. Gateway passes this over to the controller.
12;6;0;0;3;My Light\n
Received 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\n
Received command from the controller that should be passed to radio network: Outgoing message to node 13. Set V_LIGHT variable to 1 (=turn on) for child sensor 7. No ack is requested from destination node.
13;7;1;0;2;1\n
There are some messages which are processed by the MySensors library. Which means that you don’t have to implement an action for them.
© Copyright 2015, MySensors.org. Revision 85dfdc09 .
Built with Sphinx using a theme provided by Read the Docs. Read the Docs v: latestVersions latest Downloads pdf htmlzip epub On Read the Docs Project Home Builds Free document hosting provided by Read the Docs.