MySensors Library & Examples  2.3.1
MyMessage.h
Go to the documentation of this file.
1 /*
2  * The MySensors Arduino library handles the wireless radio link and protocol
3  * between your home built sensors/actuators and HA controller of choice.
4  * The sensors forms a self healing radio network with optional repeaters. Each
5  * repeater and gateway builds a routing tables in EEPROM which keeps track of the
6  * network topology allowing messages to be routed to nodes.
7  *
8  * Created by Henrik Ekblad <[email protected]>
9  * Copyright (C) 2013-2018 Sensnology AB
10  * Full contributor list: https://github.com/mysensors/MySensors/graphs/contributors
11  *
12  * Documentation: http://www.mysensors.org
13  * Support Forum: http://forum.mysensors.org
14  *
15  * This program is free software; you can redistribute it and/or
16  * modify it under the terms of the GNU General Public License
17  * version 2 as published by the Free Software Foundation.
18  */
19 
31 #ifndef MyMessage_h
32 #define MyMessage_h
33 
34 #ifdef __cplusplus
35 #include <Arduino.h>
36 #include <stdint.h>
37 #endif
38 
39 #define PROTOCOL_VERSION (2u)
40 #define MAX_MESSAGE_LENGTH (32u)
41 #define HEADER_SIZE (7u)
42 #define MAX_PAYLOAD (MAX_MESSAGE_LENGTH - HEADER_SIZE)
43 
44 typedef enum {
47  C_SET = 1,
48  C_REQ = 2,
49  C_INTERNAL = 3,
50  C_STREAM = 4
52 
53 #if !DOXYGEN // Hide until we migrate
54 typedef enum {
56  S_DOOR = 0,
57  S_MOTION = 1,
58  S_SMOKE = 2,
59  S_BINARY = 3,
60  S_LIGHT = 3,
61  S_DIMMER = 4,
62  S_COVER = 5,
63  S_TEMP = 6,
64  S_HUM = 7,
65  S_BARO = 8,
66  S_WIND = 9,
67  S_RAIN = 10,
68  S_UV = 11,
69  S_WEIGHT = 12,
70  S_POWER = 13,
71  S_HEATER = 14,
72  S_DISTANCE = 15,
73  S_LIGHT_LEVEL = 16,
74  S_ARDUINO_NODE = 17,
75  S_ARDUINO_REPEATER_NODE = 18,
76  S_LOCK = 19,
77  S_IR = 20,
78  S_WATER = 21,
79  S_AIR_QUALITY = 22,
80  S_CUSTOM = 23,
81  S_DUST = 24,
82  S_SCENE_CONTROLLER = 25,
83  S_RGB_LIGHT = 26,
84  S_RGBW_LIGHT = 27,
85  S_COLOR_SENSOR = 28,
86  S_HVAC = 29,
87  S_MULTIMETER = 30,
88  S_SPRINKLER = 31,
89  S_WATER_LEAK = 32,
90  S_SOUND = 33,
91  S_VIBRATION = 34,
92  S_MOISTURE = 35,
93  S_INFO = 36,
94  S_GAS = 37,
95  S_GPS = 38,
96  S_WATER_QUALITY = 39
97 } mysensors_sensor_t;
98 
100 typedef enum {
101  V_TEMP = 0,
102  V_HUM = 1,
103  V_STATUS = 2,
104  V_LIGHT = 2,
105  V_PERCENTAGE = 3,
106  V_DIMMER = 3,
107  V_PRESSURE = 4,
108  V_FORECAST = 5,
109  V_RAIN = 6,
110  V_RAINRATE = 7,
111  V_WIND = 8,
112  V_GUST = 9,
113  V_DIRECTION = 10,
114  V_UV = 11,
115  V_WEIGHT = 12,
116  V_DISTANCE = 13,
117  V_IMPEDANCE = 14,
118  V_ARMED = 15,
119  V_TRIPPED = 16,
120  V_WATT = 17,
121  V_KWH = 18,
122  V_SCENE_ON = 19,
123  V_SCENE_OFF = 20,
124  V_HVAC_FLOW_STATE = 21,
125  V_HEATER = 21,
126  V_HVAC_SPEED = 22,
127  V_LIGHT_LEVEL = 23,
128  V_VAR1 = 24,
129  V_VAR2 = 25,
130  V_VAR3 = 26,
131  V_VAR4 = 27,
132  V_VAR5 = 28,
133  V_UP = 29,
134  V_DOWN = 30,
135  V_STOP = 31,
136  V_IR_SEND = 32,
137  V_IR_RECEIVE = 33,
138  V_FLOW = 34,
139  V_VOLUME = 35,
140  V_LOCK_STATUS = 36,
141  V_LEVEL = 37,
142  V_VOLTAGE = 38,
143  V_CURRENT = 39,
144  V_RGB = 40,
145  V_RGBW = 41,
146  V_ID = 42,
147  V_UNIT_PREFIX = 43,
148  V_HVAC_SETPOINT_COOL = 44,
149  V_HVAC_SETPOINT_HEAT = 45,
150  V_HVAC_FLOW_MODE = 46,
151  V_TEXT = 47,
152  V_CUSTOM = 48,
153  V_POSITION = 49,
154  V_IR_RECORD = 50,
155  V_PH = 51,
156  V_ORP = 52,
157  V_EC = 53,
158  V_VAR = 54,
159  V_VA = 55,
160  V_POWER_FACTOR = 56,
161 } mysensors_data_t;
162 #endif
163 
164 
166 typedef enum {
168  I_TIME = 1,
169  I_VERSION = 2,
173  I_CONFIG = 6,
177  I_CHILDREN = 10,
180  I_REBOOT = 13,
190  I_LOCKED = 23,
191  I_PING = 24,
192  I_PONG = 25,
195  I_DEBUG = 28,
202 
203 
205 typedef enum {
210  ST_SOUND = 4,
211  ST_IMAGE = 5,
215 
217 typedef enum {
218  P_STRING = 0,
219  P_BYTE = 1,
220  P_INT16 = 2,
221  P_UINT16 = 3,
222  P_LONG32 = 4,
223  P_ULONG32 = 5,
224  P_CUSTOM = 6,
227 
228 
229 
230 #ifndef BIT
231 #define BIT(n) ( 1<<(n) )
232 #endif
233 #define BIT_MASK(len) ( BIT(len)-1 )
234 #define BF_MASK(start, len) ( BIT_MASK(len)<<(start) )
235 
236 #define BF_PREP(x, start, len) ( ((x)&BIT_MASK(len)) << (start) )
237 #define BF_GET(y, start, len) ( ((y)>>(start)) & BIT_MASK(len) )
238 #define BF_SET(y, x, start, len) ( y= ((y) &~ BF_MASK(start, len)) | BF_PREP(x, start, len) )
239 
240 // Getters/setters for special bit fields in header
241 #define mSetVersion(_message,_version) BF_SET(_message.version_length, _version, 0, 2)
242 #define mGetVersion(_message) ((uint8_t)BF_GET(_message.version_length, 0, 2))
243 
244 #define mSetSigned(_message,_signed) BF_SET(_message.version_length, _signed, 2, 1)
245 #define mGetSigned(_message) ((bool)BF_GET(_message.version_length, 2, 1))
246 
247 #define mSetLength(_message,_length) BF_SET(_message.version_length, _length, 3, 5)
248 #define mGetLength(_message) ((uint8_t)BF_GET(_message.version_length, 3, 5))
249 
250 #define mSetCommand(_message,_command) BF_SET(_message.command_ack_payload, _command, 0, 3)
251 #define mGetCommand(_message) ((uint8_t)BF_GET(_message.command_ack_payload, 0, 3))
252 
253 #define mSetRequestAck(_message,_rack) BF_SET(_message.command_ack_payload, _rack, 3, 1)
254 #define mGetRequestAck(_message) ((bool)BF_GET(_message.command_ack_payload, 3, 1))
255 
256 #define mSetAck(_message,_ackMsg) BF_SET(_message.command_ack_payload, _ackMsg, 4, 1)
257 #define mGetAck(_message) ((bool)BF_GET(_message.command_ack_payload, 4, 1))
258 
259 #define mSetPayloadType(_message, _pt) BF_SET(_message.command_ack_payload, _pt, 5, 3)
260 #define mGetPayloadType(_message) ((uint8_t)BF_GET(_message.command_ack_payload, 5, 3))
261 
262 
263 // internal access for special fields
264 #define miGetCommand() ((uint8_t)BF_GET(command_ack_payload, 0, 3))
265 
266 #define miSetLength(_length) BF_SET(version_length, _length, 3, 5)
267 #define miGetLength() ((uint8_t)BF_GET(version_length, 3, 5))
268 
269 #define miSetVersion(_version) BF_SET(version_length, _version, 0, 2)
270 #define miGetVersion() ((uint8_t)BF_GET(version_length, 0, 2))
271 
272 #define miSetRequestAck(_rack) BF_SET(command_ack_payload, _rack, 3, 1)
273 #define miGetRequestAck() ((bool)BF_GET(command_ack_payload, 3, 1))
275 #define miSetAck(_ack) BF_SET(command_ack_payload, _ack, 4, 1)
276 #define miGetAck() ((bool)BF_GET(command_ack_payload, 4, 1))
277 
278 #define miSetPayloadType(_pt) BF_SET(command_ack_payload, _pt, 5, 3)
279 #define miGetPayloadType() (uint8_t)BF_GET(command_ack_payload, 5, 3)
280 
281 
282 #if defined(__cplusplus) || defined(DOXYGEN)
283 
287 {
288 private:
289  char* getCustomString(char *buffer) const;
291 public:
295  MyMessage(void);
296 
302  MyMessage(const uint8_t sensor, const uint8_t type);
303 
309  char i2h(const uint8_t i) const;
310 
314  void clear(void);
315 
322  char* getStream(char *buffer) const;
323 
327  char* getString(char *buffer) const;
328 
333  const char* getString(void) const;
334 
339  void* getCustom(void) const;
340 
345  bool getBool(void) const;
346 
351  uint8_t getByte(void) const;
352 
357  float getFloat(void) const;
358 
363  int16_t getInt(void) const;
364 
369  uint16_t getUInt(void) const;
370 
375  int32_t getLong(void) const;
376 
381  uint32_t getULong(void) const;
382 
387  uint8_t getCommand(void) const;
388 
393  bool isAck(void) const;
394 
399  MyMessage& setType(const uint8_t type);
400 
405  MyMessage& setSensor(const uint8_t sensor);
406 
411  MyMessage& setDestination(const uint8_t destination);
412 
418  MyMessage& set(const void* payload, const uint8_t length);
419 
424  MyMessage& set(const char* value);
425 #if !defined(__linux__)
426 
430  MyMessage& set(const __FlashStringHelper* value);
431 #endif
432 
438  MyMessage& set(const float value, const uint8_t decimals);
439 
444  MyMessage& set(const bool value);
445 
450  MyMessage& set(const uint8_t value);
451 
456  MyMessage& set(const uint32_t value);
457 
462  MyMessage& set(const int32_t value);
463 
468  MyMessage& set(const uint16_t value);
469 
474  MyMessage& set(const int16_t value);
475 
476 #else
477 
478 typedef union {
479  struct {
480 
481 #endif
482  uint8_t last;
483  uint8_t sender;
484  uint8_t destination;
485 
491  uint8_t version_length;
492 
500 
501  uint8_t type;
502  uint8_t sensor;
504  /*
505  * Each message can transfer a payload. We add one extra byte for string
506  * terminator \0 to be "printable" this is not transferred OTA
507  * This union is used to simplify the construction of the binary data types transferred.
508  */
509  union {
510  uint8_t bValue;
511  uint16_t uiValue;
512  int16_t iValue;
513  uint32_t ulValue;
514  int32_t lValue;
515  struct {
516  float fValue;
517  uint8_t fPrecision;
518  };
519  struct {
520  uint8_t version;
521  uint8_t sensorType;
522  };
523  char data[MAX_PAYLOAD + 1];
524  } __attribute__((packed));
525 #if defined(__cplusplus) || defined(DOXYGEN)
526 } __attribute__((packed));
527 #else
528 };
529 uint8_t array[HEADER_SIZE + MAX_PAYLOAD + 1];
530 } __attribute__((packed)) MyMessage;
531 #endif
532 
533 #endif
534 
char i2h(const uint8_t i) const
Requests a variable value (usually from an actuator destined for controller).
Definition: MyMessage.h:48
Request for a nonce.
Definition: MyMessage.h:183
Sketch name.
Definition: MyMessage.h:178
const char * getString(void) const
Get payload as string.
uint32_t ulValue
unsigned long value (32-bit)
Definition: MyMessage.h:513
Internal MySensors messages (also include common messages provided/generated by the library)...
Definition: MyMessage.h:49
mysensors_command_t
The command field (message-type) defines the overall properties of a message.
Definition: MyMessage.h:45
Payload type is binary.
Definition: MyMessage.h:224
Payload is nonce data.
Definition: MyMessage.h:184
Inclusion mode.
Definition: MyMessage.h:172
uint8_t type
8 bit - Type varies depending on command
Definition: MyMessage.h:501
int16_t iValue
signed integer value (16-bit)
Definition: MyMessage.h:512
MyMessage is used to create, manipulate, send and read MySensors messages.
Definition: MyMessage.h:286
ID response.
Definition: MyMessage.h:171
Time (request/response)
Definition: MyMessage.h:168
int16_t getInt(void) const
Get signed 16-bit integer payload.
uint8_t version_length
Definition: MyMessage.h:491
Register response from GW.
Definition: MyMessage.h:194
Payload type is float32.
Definition: MyMessage.h:225
uint8_t destination
8 bit - Id of destination node
Definition: MyMessage.h:484
Gateway ready.
Definition: MyMessage.h:181
New FW details to initiate OTA FW update.
Definition: MyMessage.h:207
Payload type is INT32.
Definition: MyMessage.h:222
Reboot request.
Definition: MyMessage.h:180
char data[MAX_PAYLOAD+1]
Buffer for raw payload data.
Definition: MyMessage.h:523
Mark running firmware as valid (MyOTAFirmwareUpdateNVM + mcuboot)
Definition: MyMessage.h:212
Battery level.
Definition: MyMessage.h:167
FW config structure, stored in eeprom.
Definition: MyOTAFirmwareUpdate.h:114
uint8_t last
8 bit - Id of last node this message passed
Definition: MyMessage.h:482
Payload type is INT16.
Definition: MyMessage.h:220
ID request.
Definition: MyMessage.h:170
Device signal strength request.
Definition: MyMessage.h:196
char * getStream(char *buffer) const
float getFloat(void) const
Get float payload.
Log message.
Definition: MyMessage.h:176
float fValue
< Float messages
Definition: MyMessage.h:516
MyMessage & setType(const uint8_t type)
Set message type.
uint8_t getByte(void) const
Get unsigned 8-bit integer payload.
uint8_t getCommand(void) const
Getter for command type.
Register request to GW.
Definition: MyMessage.h:193
uint8_t version
< Presentation messages
Definition: MyMessage.h:520
uint32_t getULong(void) const
Get unsigned 32-bit integer payload.
void clear(void)
Clear message contents.
MyMessage & setSensor(const uint8_t sensor)
Set which child sensor this message belongs to.
Payload type is UINT32.
Definition: MyMessage.h:223
For firmware and other larger chunks of data that need to be divided into pieces. ...
Definition: MyMessage.h:50
Find parent response.
Definition: MyMessage.h:175
uint8_t sender
8 bit - Id of sender node (origin)
Definition: MyMessage.h:483
Internal.
Definition: MyMessage.h:197
Debug message.
Definition: MyMessage.h:195
Sound.
Definition: MyMessage.h:210
Presentation message.
Definition: MyMessage.h:186
bool isAck(void) const
Getter for ack-flag.
Heartbeat response.
Definition: MyMessage.h:189
Response FW block.
Definition: MyMessage.h:209
Message sent before node is going to sleep.
Definition: MyMessage.h:199
Children.
Definition: MyMessage.h:177
Config (request/response)
Definition: MyMessage.h:173
Request new FW, payload contains current FW details.
Definition: MyMessage.h:206
int32_t getLong(void) const
Get signed 32-bit integer payload.
#define MAX_PAYLOAD
The maximum size of a payload depends on MAX_MESSAGE_LENGTH and HEADER_SIZE.
Definition: MyMessage.h:42
Find parent.
Definition: MyMessage.h:174
Image.
Definition: MyMessage.h:211
#define HEADER_SIZE
The size of the header.
Definition: MyMessage.h:41
uint16_t uiValue
unsigned integer value (16-bit)
Definition: MyMessage.h:511
Node is locked (reason in string-payload)
Definition: MyMessage.h:190
Payload type is byte.
Definition: MyMessage.h:219
mysensors_internal_t
Type of internal messages (for internal messages)
Definition: MyMessage.h:166
Message sent after node woke up (if enabled)
Definition: MyMessage.h:200
In return to ping, sent back to sender, payload incremental hop counter.
Definition: MyMessage.h:192
Heartbeat request.
Definition: MyMessage.h:185
Response FW block with run length encoded data.
Definition: MyMessage.h:213
MyMessage(void)
uint8_t sensor
8 bit - Id of sensor that this message concerns.
Definition: MyMessage.h:502
Discover response.
Definition: MyMessage.h:188
bool getBool(void) const
Get bool payload.
Payload type is string.
Definition: MyMessage.h:218
Provides signing related preferences (first byte is preference version)
Definition: MyMessage.h:182
mysensors_payload_t
Type of payload.
Definition: MyMessage.h:217
uint8_t sensorType
Sensor type hint for controller, see table above.
Definition: MyMessage.h:521
Ping sent to node, payload incremental hop counter.
Definition: MyMessage.h:191
void * getCustom(void) const
Get custom payload.
Discover request.
Definition: MyMessage.h:187
Device signal strength response (RSSI)
Definition: MyMessage.h:198
MyMessage & setDestination(const uint8_t destination)
Set final destination node id for this message.
uint16_t getUInt(void) const
Get unsigned 16-bit integer payload.
uint8_t command_ack_payload
Definition: MyMessage.h:499
Request FW block.
Definition: MyMessage.h:208
Sent by a node when they present attached sensors. This is usually done in presentation() at startup...
Definition: MyMessage.h:46
Sketch version.
Definition: MyMessage.h:179
Payload type is UINT16.
Definition: MyMessage.h:221
This message is sent from or to a sensor when a sensor value should be updated.
Definition: MyMessage.h:47
Version.
Definition: MyMessage.h:169
mysensors_stream_t
Type of data stream (for streamed message)
Definition: MyMessage.h:205
uint8_t fPrecision
Number of decimals when serializing.
Definition: MyMessage.h:517
int32_t lValue
signed long value (32-bit)
Definition: MyMessage.h:514
uint8_t bValue
unsigned byte value (8-bit)
Definition: MyMessage.h:510