MySensors Library & Examples  2.3.2
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-2019 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 V2_MYS_HEADER_PROTOCOL_VERSION (2u)
40 #define V2_MYS_HEADER_SIZE (7u)
41 #define V2_MYS_HEADER_MAX_MESSAGE_SIZE (32u)
42 
43 #define V2_MYS_HEADER_VSL_VERSION_POS (0)
44 #define V2_MYS_HEADER_VSL_VERSION_SIZE (2u)
45 #define V2_MYS_HEADER_VSL_SIGNED_POS (2u)
46 #define V2_MYS_HEADER_VSL_SIGNED_SIZE (1u)
47 #define V2_MYS_HEADER_VSL_LENGTH_POS (3u)
48 #define V2_MYS_HEADER_VSL_LENGTH_SIZE (5u)
49 
50 #define V2_MYS_HEADER_CEP_COMMAND_POS (0)
51 #define V2_MYS_HEADER_CEP_COMMAND_SIZE (3u)
52 #define V2_MYS_HEADER_CEP_ECHOREQUEST_POS (3u)
53 #define V2_MYS_HEADER_CEP_ECHOREQUEST_SIZE (1u)
54 #define V2_MYS_HEADER_CEP_ECHO_POS (4u)
55 #define V2_MYS_HEADER_CEP_ECHO_SIZE (1u)
56 #define V2_MYS_HEADER_CEP_PAYLOADTYPE_POS (5u)
57 #define V2_MYS_HEADER_CEP_PAYLOADTYPE_SIZE (3u)
58 
59 #define MAX_MESSAGE_SIZE V2_MYS_HEADER_MAX_MESSAGE_SIZE
60 #define HEADER_SIZE V2_MYS_HEADER_SIZE
61 #define MAX_PAYLOAD_SIZE (MAX_MESSAGE_SIZE - HEADER_SIZE)
62 
63 // deprecated in 3.0.0
64 #define MAX_PAYLOAD MAX_PAYLOAD_SIZE
65 
66 typedef enum {
69  C_SET = 1,
70  C_REQ = 2,
71  C_INTERNAL = 3,
72  C_STREAM = 4,
77 
78 #if !DOXYGEN // Hide until we migrate
79 typedef enum {
81  S_DOOR = 0,
82  S_MOTION = 1,
83  S_SMOKE = 2,
84  S_BINARY = 3,
85  S_LIGHT = 3,
86  S_DIMMER = 4,
87  S_COVER = 5,
88  S_TEMP = 6,
89  S_HUM = 7,
90  S_BARO = 8,
91  S_WIND = 9,
92  S_RAIN = 10,
93  S_UV = 11,
94  S_WEIGHT = 12,
95  S_POWER = 13,
96  S_HEATER = 14,
97  S_DISTANCE = 15,
98  S_LIGHT_LEVEL = 16,
99  S_ARDUINO_NODE = 17,
100  S_ARDUINO_REPEATER_NODE = 18,
101  S_LOCK = 19,
102  S_IR = 20,
103  S_WATER = 21,
104  S_AIR_QUALITY = 22,
105  S_CUSTOM = 23,
106  S_DUST = 24,
107  S_SCENE_CONTROLLER = 25,
108  S_RGB_LIGHT = 26,
109  S_RGBW_LIGHT = 27,
110  S_COLOR_SENSOR = 28,
111  S_HVAC = 29,
112  S_MULTIMETER = 30,
113  S_SPRINKLER = 31,
114  S_WATER_LEAK = 32,
115  S_SOUND = 33,
116  S_VIBRATION = 34,
117  S_MOISTURE = 35,
118  S_INFO = 36,
119  S_GAS = 37,
120  S_GPS = 38,
121  S_WATER_QUALITY = 39
122 } mysensors_sensor_t;
123 
125 typedef enum {
126  V_TEMP = 0,
127  V_HUM = 1,
128  V_STATUS = 2,
129  V_LIGHT = 2,
130  V_PERCENTAGE = 3,
131  V_DIMMER = 3,
132  V_PRESSURE = 4,
133  V_FORECAST = 5,
134  V_RAIN = 6,
135  V_RAINRATE = 7,
136  V_WIND = 8,
137  V_GUST = 9,
138  V_DIRECTION = 10,
139  V_UV = 11,
140  V_WEIGHT = 12,
141  V_DISTANCE = 13,
142  V_IMPEDANCE = 14,
143  V_ARMED = 15,
144  V_TRIPPED = 16,
145  V_WATT = 17,
146  V_KWH = 18,
147  V_SCENE_ON = 19,
148  V_SCENE_OFF = 20,
149  V_HVAC_FLOW_STATE = 21,
150  V_HEATER = 21,
151  V_HVAC_SPEED = 22,
152  V_LIGHT_LEVEL = 23,
153  V_VAR1 = 24,
154  V_VAR2 = 25,
155  V_VAR3 = 26,
156  V_VAR4 = 27,
157  V_VAR5 = 28,
158  V_UP = 29,
159  V_DOWN = 30,
160  V_STOP = 31,
161  V_IR_SEND = 32,
162  V_IR_RECEIVE = 33,
163  V_FLOW = 34,
164  V_VOLUME = 35,
165  V_LOCK_STATUS = 36,
166  V_LEVEL = 37,
167  V_VOLTAGE = 38,
168  V_CURRENT = 39,
169  V_RGB = 40,
170  V_RGBW = 41,
171  V_ID = 42,
172  V_UNIT_PREFIX = 43,
173  V_HVAC_SETPOINT_COOL = 44,
174  V_HVAC_SETPOINT_HEAT = 45,
175  V_HVAC_FLOW_MODE = 46,
176  V_TEXT = 47,
177  V_CUSTOM = 48,
178  V_POSITION = 49,
179  V_IR_RECORD = 50,
180  V_PH = 51,
181  V_ORP = 52,
182  V_EC = 53,
183  V_VAR = 54,
184  V_VA = 55,
185  V_POWER_FACTOR = 56,
186 } mysensors_data_t;
187 #endif
188 
190 typedef enum {
192  I_TIME = 1,
193  I_VERSION = 2,
197  I_CONFIG = 6,
201  I_CHILDREN = 10,
204  I_REBOOT = 13,
214  I_LOCKED = 23,
215  I_PING = 24,
216  I_PONG = 25,
219  I_DEBUG = 28,
226 
228 typedef enum {
233  ST_SOUND = 4,
234  ST_IMAGE = 5,
238 
240 typedef enum {
241  P_STRING = 0,
242  P_BYTE = 1,
243  P_INT16 = 2,
244  P_UINT16 = 3,
245  P_LONG32 = 4,
246  P_ULONG32 = 5,
247  P_CUSTOM = 6,
250 
251 
252 #ifndef BIT
253 #define BIT(n) ( 1<<(n) )
254 #endif
255 #define BIT_MASK(len) ( BIT(len)-1 )
256 #define BF_MASK(start, len) ( BIT_MASK(len)<<(start) )
257 
258 #define BF_PREP(x, start, len) ( ((x)&BIT_MASK(len)) << (start) )
259 #define BF_GET(y, start, len) ( ((y)>>(start)) & BIT_MASK(len) )
260 #define BF_SET(y, x, start, len) ( y= ((y) &~ BF_MASK(start, len)) | BF_PREP(x, start, len) )
261 
262 // Getters/setters for special bit fields in header
263 // deprecated in 3.0.0
264 #define mSetVersion(_message, _version) _message.setVersion(_version)
265 #define mGetVersion(_message) _message.getVersion()
266 
267 #define mSetSigned(_message, _signed) _message.setSigned(_signed)
268 #define mGetSigned(_message) _message.getSigned()
269 
270 #define mSetLength(_message,_length) _message.setLength(_length)
271 #define mGetLength(_message) _message.getLength()
272 
273 #define mSetCommand(_message, _command) _message.setCommand(_command)
274 #define mGetCommand(_message) _message.getCommand()
275 
276 #define mSetRequestEcho(_message, _requestEcho) _message.setRequestEcho(_requestEcho)
277 #define mGetRequestEcho(_message) _message.getRequestEcho()
278 
279 #define mSetEcho(_message, _echo) _message.setEcho(_echo)
280 #define mGetEcho(_message) _message.getEcho()
281 
282 #define mSetPayloadType(_message, _payloadType) _message.setPayloadType(_payloadType)
283 #define mGetPayloadType(_message) _message.getPayloadType()
284 
285 #if defined(__cplusplus) || defined(DOXYGEN)
286 
290 {
291 private:
292  char* getCustomString(char *buffer) const;
293 
294 public:
295 
299  MyMessage(void);
300 
306  MyMessage(const uint8_t sensorId, const mysensors_data_t dataType);
307 
311  void clear(void);
312 
319  char* getStream(char *buffer) const;
320 
324  char* getString(char *buffer) const;
325 
330  const char* getString(void) const;
331 
336  void* getCustom(void) const;
337 
342  bool getBool(void) const;
343 
348  uint8_t getByte(void) const;
349 
354  float getFloat(void) const;
355 
360  int16_t getInt(void) const;
361 
366  uint16_t getUInt(void) const;
367 
372  int32_t getLong(void) const;
373 
378  uint32_t getULong(void) const;
379 
384  uint8_t getHeaderSize(void) const;
385 
390  uint8_t getMaxPayloadSize(void) const;
391 
396  uint8_t getExpectedMessageSize(void) const;
397 
402  bool isProtocolVersionValid(void) const;
403 
408  bool getRequestEcho(void) const;
409 
414  MyMessage& setRequestEcho(const bool requestEcho);
415 
420  uint8_t getVersion(void) const;
421 
425  MyMessage& setVersion(void);
426 
431  uint8_t getLength(void) const;
432 
437  MyMessage& setLength(const uint8_t length);
438 
443  mysensors_command_t getCommand(void) const;
444 
449  MyMessage& setCommand(const mysensors_command_t command);
450 
456 
461  MyMessage& setPayloadType(const mysensors_payload_t payloadType);
462 
467  bool getSigned(void) const;
468 
473  MyMessage& setSigned(const bool signedFlag);
474 
480  bool isAck(void) const;
481 
486  bool isEcho(void) const;
487 
492  MyMessage& setEcho(const bool echo);
493 
498  uint8_t getType(void) const;
499 
504  MyMessage& setType(const uint8_t messageType);
505 
510  uint8_t getLast(void) const;
511 
516  MyMessage& setLast(const uint8_t lastId);
517 
522  uint8_t getSender(void) const;
523 
528  MyMessage& setSender(const uint8_t senderId);
529 
534  uint8_t getSensor(void) const;
535 
540  MyMessage& setSensor(const uint8_t sensorId);
541 
546  uint8_t getDestination(void) const;
547 
552  MyMessage& setDestination(const uint8_t destinationId);
553 
559  MyMessage& set(const void* payload, const size_t length);
560 
565  MyMessage& set(const char* value);
566 #if !defined(__linux__)
567 
571  MyMessage& set(const __FlashStringHelper* value);
572 #endif
573 
579  MyMessage& set(const float value, const uint8_t decimals);
580 
585  MyMessage& set(const bool value);
586 
591  MyMessage& set(const uint8_t value);
592 
597  MyMessage& set(const uint32_t value);
598 
603  MyMessage& set(const int32_t value);
604 
609  MyMessage& set(const uint16_t value);
610 
615  MyMessage& set(const int16_t value);
616 
617 #else
618 
619 typedef union {
620  struct {
621 
622 #endif
623  uint8_t last;
624  uint8_t sender;
625  uint8_t destination;
626 
632  uint8_t version_length;
633 
641 
642  uint8_t type;
643  uint8_t sensor;
645  /*
646  * Each message can transfer a payload. We add one extra byte for string
647  * terminator \0 to be "printable" this is not transferred OTA
648  * This union is used to simplify the construction of the binary data types transferred.
649  */
650  union {
651  uint8_t bValue;
652  uint16_t uiValue;
653  int16_t iValue;
654  uint32_t ulValue;
655  int32_t lValue;
656  struct {
657  float fValue;
658  uint8_t fPrecision;
659  };
660  char data[MAX_PAYLOAD_SIZE + 1];
661  } __attribute__((packed));
662 #if defined(__cplusplus) || defined(DOXYGEN)
663 } __attribute__((packed));
664 #else
665 };
666 uint8_t array[HEADER_SIZE + MAX_PAYLOAD_SIZE + 1];
667 } __attribute__((packed)) MyMessage;
668 #endif
669 
670 #endif
671 
Requests a variable value (usually from an actuator destined for controller).
Definition: MyMessage.h:70
MyMessage(void)
Request for a nonce.
Definition: MyMessage.h:207
Sketch name.
Definition: MyMessage.h:202
MyMessage & setCommand(const mysensors_command_t command)
Setter for command type.
uint32_t ulValue
unsigned long value (32-bit)
Definition: MyMessage.h:654
Internal MySensors messages (also include common messages provided/generated by the library).
Definition: MyMessage.h:71
mysensors_command_t
The command field (message-type) defines the overall properties of a message.
Definition: MyMessage.h:67
Payload type is binary.
Definition: MyMessage.h:247
Payload is nonce data.
Definition: MyMessage.h:208
Inclusion mode.
Definition: MyMessage.h:196
uint8_t getLength(void) const
Getter for length.
uint8_t type
8 bit - Type varies depending on command
Definition: MyMessage.h:642
int16_t iValue
signed integer value (16-bit)
Definition: MyMessage.h:653
MyMessage & setRequestEcho(const bool requestEcho)
Setter for echo request.
MyMessage & setSigned(const bool signedFlag)
Setter for sign field.
uint8_t getMaxPayloadSize(void) const
getMaxPayloadSize
int16_t getInt(void) const
Get signed 16-bit integer payload.
MyMessage is used to create, manipulate, send and read MySensors messages.
Definition: MyMessage.h:289
ID response.
Definition: MyMessage.h:195
uint8_t getHeaderSize(void) const
getHeaderSize
Time (request/response)
Definition: MyMessage.h:192
const char * getString(void) const
Get payload as string.
uint8_t version_length
Definition: MyMessage.h:632
MyMessage & setLast(const uint8_t lastId)
Set last ID.
uint8_t getSensor(void) const
Get sensor ID of message.
bool getBool(void) const
Get bool payload.
bool getRequestEcho(void) const
Getter for echo request.
Register response from GW.
Definition: MyMessage.h:218
Payload type is float32.
Definition: MyMessage.h:248
MyMessage & setDestination(const uint8_t destinationId)
Set final destination node id for this message.
char * getStream(char *buffer) const
uint8_t getByte(void) const
Get unsigned 8-bit integer payload.
MyMessage & setSensor(const uint8_t sensorId)
Set which child sensor this message belongs to.
C_RESERVED_5.
Definition: MyMessage.h:73
MyMessage & setEcho(const bool echo)
Setter for echo-flag.
uint8_t destination
8 bit - Id of destination node
Definition: MyMessage.h:625
Gateway ready.
Definition: MyMessage.h:205
New FW details to initiate OTA FW update.
Definition: MyMessage.h:230
Payload type is INT32.
Definition: MyMessage.h:245
C_RESERVED_6.
Definition: MyMessage.h:74
Reboot request.
Definition: MyMessage.h:204
Mark running firmware as valid (MyOTAFirmwareUpdateNVM + mcuboot)
Definition: MyMessage.h:235
int32_t getLong(void) const
Get signed 32-bit integer payload.
Battery level.
Definition: MyMessage.h:191
FW config structure, stored in eeprom.
bool isEcho(void) const
Getter for echo-flag.
uint8_t last
8 bit - Id of last node this message passed
Definition: MyMessage.h:623
Payload type is INT16.
Definition: MyMessage.h:243
ID request.
Definition: MyMessage.h:194
Device signal strength request.
Definition: MyMessage.h:220
Log message.
Definition: MyMessage.h:200
C_INVALID_7.
Definition: MyMessage.h:75
float fValue
< Float messages
Definition: MyMessage.h:657
uint8_t command_echo_payload
Definition: MyMessage.h:640
Register request to GW.
Definition: MyMessage.h:217
void clear(void)
Clear message contents.
bool getSigned(void) const
Getter for sign field.
struct @4::@5 __attribute__
Doxygen will complain without this comment.
Definition: DigitalPin.h:65
MyMessage & setSender(const uint8_t senderId)
Set sender ID.
MyMessage & setLength(const uint8_t length)
Setter for length.
Payload type is UINT32.
Definition: MyMessage.h:246
For firmware and other larger chunks of data that need to be divided into pieces.
Definition: MyMessage.h:72
MyMessage & setPayloadType(const mysensors_payload_t payloadType)
Setter for payload type.
Find parent response.
Definition: MyMessage.h:199
uint8_t sender
8 bit - Id of sender node (origin)
Definition: MyMessage.h:624
#define MAX_PAYLOAD_SIZE
The maximum size of a payload depends on MAX_MESSAGE_SIZE and HEADER_SIZE.
Definition: MyMessage.h:61
mysensors_command_t getCommand(void) const
Getter for command type.
Debug message.
Definition: MyMessage.h:219
float getFloat(void) const
Get float payload.
Sound.
Definition: MyMessage.h:233
Presentation message.
Definition: MyMessage.h:210
Heartbeat response.
Definition: MyMessage.h:213
uint8_t getType(void) const
Get message type.
Response FW block.
Definition: MyMessage.h:232
Message sent before node is going to sleep.
Definition: MyMessage.h:223
Children.
Definition: MyMessage.h:201
Config (request/response)
Definition: MyMessage.h:197
Request new FW, payload contains current FW details.
Definition: MyMessage.h:229
Find parent.
Definition: MyMessage.h:198
uint8_t getExpectedMessageSize(void) const
getExpectedMessageSize
Image.
Definition: MyMessage.h:234
#define HEADER_SIZE
The size of the header.
Definition: MyMessage.h:60
uint16_t uiValue
unsigned integer value (16-bit)
Definition: MyMessage.h:652
Node is locked (reason in string-payload)
Definition: MyMessage.h:214
Payload type is byte.
Definition: MyMessage.h:242
void * getCustom(void) const
Get custom payload.
mysensors_internal_t
Type of internal messages (for internal messages)
Definition: MyMessage.h:190
Message sent after node woke up (if enabled)
Definition: MyMessage.h:224
In return to ping, sent back to sender, payload incremental hop counter.
Definition: MyMessage.h:216
Heartbeat request.
Definition: MyMessage.h:209
Response FW block with run length encoded data.
Definition: MyMessage.h:236
bool isProtocolVersionValid(void) const
isProtocolVersionValid
MyMessage(void)
uint8_t sensor
8 bit - Id of sensor that this message concerns.
Definition: MyMessage.h:643
bool isAck(void) const
Getter for echo-flag.
Discover response.
Definition: MyMessage.h:212
uint8_t getDestination(void) const
Get destination.
Payload type is string.
Definition: MyMessage.h:241
Provides signing related preferences (first byte is preference version)
Definition: MyMessage.h:206
mysensors_payload_t
Type of payload.
Definition: MyMessage.h:240
Ping sent to node, payload incremental hop counter.
Definition: MyMessage.h:215
mysensors_payload_t getPayloadType(void) const
Getter for payload type.
MyMessage & setType(const uint8_t messageType)
Set message type.
Discover request.
Definition: MyMessage.h:211
Device signal strength response (RSSI)
Definition: MyMessage.h:222
uint8_t getVersion(void) const
Getter for version.
char data[MAX_PAYLOAD_SIZE+1]
Buffer for raw payload data.
Definition: MyMessage.h:660
MyMessage & set(const void *payload, const size_t length)
Set entire payload.
uint8_t getSender(void) const
Get sender ID.
Request FW block.
Definition: MyMessage.h:231
Sent by a node when they present attached sensors. This is usually done in presentation() at startup.
Definition: MyMessage.h:68
uint32_t getULong(void) const
Get unsigned 32-bit integer payload.
Sketch version.
Definition: MyMessage.h:203
Payload type is UINT16.
Definition: MyMessage.h:244
This message is sent from or to a sensor when a sensor value should be updated.
Definition: MyMessage.h:69
Version.
Definition: MyMessage.h:193
mysensors_stream_t
Type of data stream (for streamed message)
Definition: MyMessage.h:228
MyMessage & setVersion(void)
Setter for version.
uint8_t fPrecision
Number of decimals when serializing.
Definition: MyMessage.h:658
int32_t lValue
signed long value (32-bit)
Definition: MyMessage.h:655
uint8_t getLast(void) const
Get last ID.
uint8_t bValue
unsigned byte value (8-bit)
Definition: MyMessage.h:651
uint16_t getUInt(void) const
Get unsigned 16-bit integer payload.