MySensors Library & Examples  2.3.1
Classes | Macros | Enumerations | Functions | Variables
MyMessage.h File Reference

Detailed Description

API and type declarations for MySensors messages.

+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  MyMessage
 MyMessage is used to create, manipulate, send and read MySensors messages. More...
 

Macros

#define PROTOCOL_VERSION   (2u)
 The version of the protocol.
 
#define MAX_MESSAGE_LENGTH   (32u)
 The maximum size of a message (including header)
 
#define HEADER_SIZE   (7u)
 The size of the header.
 
#define MAX_PAYLOAD   (MAX_MESSAGE_LENGTH - HEADER_SIZE)
 The maximum size of a payload depends on MAX_MESSAGE_LENGTH and HEADER_SIZE.
 
#define BIT(n)   ( 1<<(n) )
 Bit indexing macro.
 
#define BIT_MASK(len)   ( BIT(len)-1 )
 Create a bitmask of length 'len'.
 
#define BF_MASK(start, len)   ( BIT_MASK(len)<<(start) )
 Create a bitfield mask of length starting at bit 'start'.
 
#define BF_PREP(x, start, len)   ( ((x)&BIT_MASK(len)) << (start) )
 Prepare a bitmask for insertion or combining.
 
#define BF_GET(y, start, len)   ( ((y)>>(start)) & BIT_MASK(len) )
 Extract a bitfield of length 'len' starting at bit 'start' from 'y'.
 
#define BF_SET(y, x, start, len)   ( y= ((y) &~ BF_MASK(start, len)) | BF_PREP(x, start, len) )
 Insert a new bitfield value 'x' into 'y'.
 
#define mSetVersion(_message, _version)   BF_SET(_message.version_length, _version, 0, 2)
 Set version field.
 
#define mGetVersion(_message)   ((uint8_t)BF_GET(_message.version_length, 0, 2))
 Get version field.
 
#define mSetSigned(_message, _signed)   BF_SET(_message.version_length, _signed, 2, 1)
 Set signed field.
 
#define mGetSigned(_message)   ((bool)BF_GET(_message.version_length, 2, 1))
 Get signed field.
 
#define mSetLength(_message, _length)   BF_SET(_message.version_length, _length, 3, 5)
 Set length field.
 
#define mGetLength(_message)   ((uint8_t)BF_GET(_message.version_length, 3, 5))
 Get length field.
 
#define mSetCommand(_message, _command)   BF_SET(_message.command_ack_payload, _command, 0, 3)
 Set command field.
 
#define mGetCommand(_message)   ((uint8_t)BF_GET(_message.command_ack_payload, 0, 3))
 Get command field.
 
#define mSetRequestAck(_message, _rack)   BF_SET(_message.command_ack_payload, _rack, 3, 1)
 Set ack-request field.
 
#define mGetRequestAck(_message)   ((bool)BF_GET(_message.command_ack_payload, 3, 1))
 Get ack-request field.
 
#define mSetAck(_message, _ackMsg)   BF_SET(_message.command_ack_payload, _ackMsg, 4, 1)
 Set ack field.
 
#define mGetAck(_message)   ((bool)BF_GET(_message.command_ack_payload, 4, 1))
 Get ack field.
 
#define mSetPayloadType(_message, _pt)   BF_SET(_message.command_ack_payload, _pt, 5, 3)
 Set payload type field.
 
#define mGetPayloadType(_message)   ((uint8_t)BF_GET(_message.command_ack_payload, 5, 3))
 Get payload type field.
 
#define miGetCommand()   ((uint8_t)BF_GET(command_ack_payload, 0, 3))
 Internal getter for command field.
 
#define miSetLength(_length)   BF_SET(version_length, _length, 3, 5)
 Internal setter for length field.
 
#define miGetLength()   ((uint8_t)BF_GET(version_length, 3, 5))
 Internal getter for length field.
 
#define miSetVersion(_version)   BF_SET(version_length, _version, 0, 2)
 Internal setter for version field.
 
#define miGetVersion()   ((uint8_t)BF_GET(version_length, 0, 2))
 Internal getter for version field.
 
#define miSetRequestAck(_rack)   BF_SET(command_ack_payload, _rack, 3, 1)
 Internal setter for ack-request field.
 
#define miGetRequestAck()   ((bool)BF_GET(command_ack_payload, 3, 1))
 Internal getter for ack-request field.
 
#define miSetAck(_ack)   BF_SET(command_ack_payload, _ack, 4, 1)
 Internal setter for ack field.
 
#define miGetAck()   ((bool)BF_GET(command_ack_payload, 4, 1))
 Internal getter for ack field.
 
#define miSetPayloadType(_pt)   BF_SET(command_ack_payload, _pt, 5, 3)
 Internal setter for payload type field.
 
#define miGetPayloadType()   (uint8_t)BF_GET(command_ack_payload, 5, 3)
 Internal getter for payload type field.
 

Enumerations

enum  mysensors_command_t {
  C_PRESENTATION = 0, C_SET = 1, C_REQ = 2, C_INTERNAL = 3,
  C_STREAM = 4
}
 The command field (message-type) defines the overall properties of a message. More...
 
enum  mysensors_internal_t {
  I_BATTERY_LEVEL = 0, I_TIME = 1, I_VERSION = 2, I_ID_REQUEST = 3,
  I_ID_RESPONSE = 4, I_INCLUSION_MODE = 5, I_CONFIG = 6, I_FIND_PARENT_REQUEST = 7,
  I_FIND_PARENT_RESPONSE = 8, I_LOG_MESSAGE = 9, I_CHILDREN = 10, I_SKETCH_NAME = 11,
  I_SKETCH_VERSION = 12, I_REBOOT = 13, I_GATEWAY_READY = 14, I_SIGNING_PRESENTATION = 15,
  I_NONCE_REQUEST = 16, I_NONCE_RESPONSE = 17, I_HEARTBEAT_REQUEST = 18, I_PRESENTATION = 19,
  I_DISCOVER_REQUEST = 20, I_DISCOVER_RESPONSE = 21, I_HEARTBEAT_RESPONSE = 22, I_LOCKED = 23,
  I_PING = 24, I_PONG = 25, I_REGISTRATION_REQUEST = 26, I_REGISTRATION_RESPONSE = 27,
  I_DEBUG = 28, I_SIGNAL_REPORT_REQUEST = 29, I_SIGNAL_REPORT_REVERSE = 30, I_SIGNAL_REPORT_RESPONSE = 31,
  I_PRE_SLEEP_NOTIFICATION = 32, I_POST_SLEEP_NOTIFICATION = 33
}
 Type of internal messages (for internal messages) More...
 
enum  mysensors_stream_t {
  ST_FIRMWARE_CONFIG_REQUEST = 0, ST_FIRMWARE_CONFIG_RESPONSE = 1, ST_FIRMWARE_REQUEST = 2, ST_FIRMWARE_RESPONSE = 3,
  ST_SOUND = 4, ST_IMAGE = 5, ST_FIRMWARE_CONFIRM = 6, ST_FIRMWARE_RESPONSE_RLE = 7
}
 Type of data stream (for streamed message) More...
 
enum  mysensors_payload_t {
  P_STRING = 0, P_BYTE = 1, P_INT16 = 2, P_UINT16 = 3,
  P_LONG32 = 4, P_ULONG32 = 5, P_CUSTOM = 6, P_FLOAT32 = 7
}
 Type of payload. More...
 

Functions

class MyMessage __attribute__ ((packed))
 Doxygen will complain without this comment.
 
 MyMessage (void)
 
 MyMessage (const uint8_t sensor, const uint8_t type)
 
char i2h (const uint8_t i) const
 
void clear (void)
 Clear message contents.
 
char * getStream (char *buffer) const
 
char * getString (char *buffer) const
 Copy the payload into the supplied buffer.
 
const char * getString (void) const
 Get payload as string. More...
 
void * getCustom (void) const
 Get custom payload. More...
 
bool getBool (void) const
 Get bool payload. More...
 
uint8_t getByte (void) const
 Get unsigned 8-bit integer payload. More...
 
float getFloat (void) const
 Get float payload. More...
 
int16_t getInt (void) const
 Get signed 16-bit integer payload. More...
 
uint16_t getUInt (void) const
 Get unsigned 16-bit integer payload. More...
 
int32_t getLong (void) const
 Get signed 32-bit integer payload. More...
 
uint32_t getULong (void) const
 Get unsigned 32-bit integer payload. More...
 
uint8_t getCommand (void) const
 Getter for command type. More...
 
bool isAck (void) const
 Getter for ack-flag. More...
 
MyMessagesetType (const uint8_t type)
 Set message type. More...
 
MyMessagesetSensor (const uint8_t sensor)
 Set which child sensor this message belongs to. More...
 
MyMessagesetDestination (const uint8_t destination)
 Set final destination node id for this message. More...
 
MyMessageset (const void *payload, const uint8_t length)
 Set entire payload. More...
 
MyMessageset (const char *value)
 Set payload to character array. More...
 
MyMessageset (const float value, const uint8_t decimals)
 Set payload to decimal number. More...
 
MyMessageset (const bool value)
 Set payload to bool value. More...
 
MyMessageset (const uint8_t value)
 Set payload to unsigned 8-bit integer value. More...
 
MyMessageset (const uint32_t value)
 Set payload to unsigned 32-bit integer value. More...
 
MyMessageset (const int32_t value)
 Set payload to signed 32-bit integer value. More...
 
MyMessageset (const uint16_t value)
 Set payload to unsigned 16-bit integer value. More...
 
MyMessageset (const int16_t value)
 Set payload to signed 16-bit integer value. More...
 

Variables

uint8_t bValue
 unsigned byte value (8-bit)
 
uint16_t uiValue
 unsigned integer value (16-bit)
 
int16_t iValue
 signed integer value (16-bit)
 
uint32_t ulValue
 unsigned long value (32-bit)
 
int32_t lValue
 signed long value (32-bit)
 
struct {
   float   fValue
 < Float messages
 
   uint8_t   fPrecision
 Number of decimals when serializing.
 
}; 
 
struct {
   uint8_t   version
 < Presentation messages More...
 
   uint8_t   sensorType
 Sensor type hint for controller, see table above.
 
}; 
 
char data [MAX_PAYLOAD+1]
 Buffer for raw payload data.
 
uint8_t last
 8 bit - Id of last node this message passed
 
uint8_t sender
 8 bit - Id of sender node (origin)
 
uint8_t destination
 8 bit - Id of destination node
 
uint8_t version_length
 
uint8_t command_ack_payload
 
uint8_t type
 8 bit - Type varies depending on command
 
uint8_t sensor
 8 bit - Id of sensor that this message concerns.
 
struct {
   float   fValue
 < Float messages
 
   uint8_t   fPrecision
 Number of decimals when serializing.
 
}; 
 
struct {
   uint8_t   version
 < Presentation messages More...
 
   uint8_t   sensorType
 Sensor type hint for controller, see table above.
 
}; 
 

Function Documentation

bool __attribute__::getBool ( void  ) const

Get bool payload.

Returns
a bool with the value of the payload (true/false)
uint8_t __attribute__::getByte ( void  ) const

Get unsigned 8-bit integer payload.

Returns
the value of the payload, 0 to 255
uint8_t __attribute__::getCommand ( void  ) const

Getter for command type.

Returns
mysensors_command_t
void* __attribute__::getCustom ( void  ) const

Get custom payload.

Returns
pointer to the raw payload
float __attribute__::getFloat ( void  ) const

Get float payload.

Returns
the floating-point value of the payload
int16_t __attribute__::getInt ( void  ) const

Get signed 16-bit integer payload.

Returns
the value of the payload, –32768 to 32767
int32_t __attribute__::getLong ( void  ) const

Get signed 32-bit integer payload.

Returns
the value of the payload, –2147483648 to 2147483647
char* __attribute__::getStream ( char *  buffer) const

If payload is something else than P_STRING you can have the payload value converted into string representation by supplying a buffer with the minimum size of 2*MAX_PAYLOAD+1. This is to be able to fit hex-conversion of a full binary payload.

Parameters
bufferpointer to a buffer that's at least 2*MAX_PAYLOAD+1 bytes large
const char* __attribute__::getString ( void  ) const

Get payload as string.

Returns
pointer to a char array storing the string
uint16_t __attribute__::getUInt ( void  ) const

Get unsigned 16-bit integer payload.

Returns
the value of the payload, 0 to 65535
uint32_t __attribute__::getULong ( void  ) const

Get unsigned 32-bit integer payload.

Returns
the value of the payload, 0 to 4294967295
char __attribute__::i2h ( const uint8_t  i) const

Single character hex (0 - 15) conversion

Parameters
ibyte (only lower 4 bits will be considered)
Returns
single char with the hex representation (0 to F) of the parameter
bool __attribute__::isAck ( void  ) const

Getter for ack-flag.

Returns
true if this is an ack message
__attribute__::MyMessage ( void  )

Default constructor

__attribute__::MyMessage ( const uint8_t  sensor,
const uint8_t  type 
)

Constructor

Parameters
sensorid of the child sensor for this message
typesee http://korturl.nu/stupidurl
MyMessage& __attribute__::set ( const void *  payload,
const uint8_t  length 
)

Set entire payload.

Parameters
payloadpointer to the buffer where the payload is stored
lengthof the payload
MyMessage & set ( const char *  value)

Set payload to character array.

Set payload to character array from flash.

Parameters
valuepointer to the character array. The array must be null-terminated.
MyMessage& __attribute__::set ( const float  value,
const uint8_t  decimals 
)

Set payload to decimal number.

Parameters
valuefloat
decimalsnumber of decimals to include
MyMessage& __attribute__::set ( const bool  value)

Set payload to bool value.

Parameters
valuetrue or false
MyMessage& __attribute__::set ( const uint8_t  value)

Set payload to unsigned 8-bit integer value.

Parameters
value(0 to 255)
MyMessage& __attribute__::set ( const uint32_t  value)

Set payload to unsigned 32-bit integer value.

Parameters
value(0 to 4294967295)
MyMessage& __attribute__::set ( const int32_t  value)

Set payload to signed 32-bit integer value.

Parameters
value(–2147483648 to 2147483647)
MyMessage& __attribute__::set ( const uint16_t  value)

Set payload to unsigned 16-bit integer value.

Parameters
value(0 to 65535)
MyMessage& __attribute__::set ( const int16_t  value)

Set payload to signed 16-bit integer value.

Parameters
value(–32768 to 32767)
MyMessage& __attribute__::setDestination ( const uint8_t  destination)

Set final destination node id for this message.

Parameters
destination
MyMessage& __attribute__::setSensor ( const uint8_t  sensor)

Set which child sensor this message belongs to.

Parameters
sensor
MyMessage& __attribute__::setType ( const uint8_t  type)

Set message type.

Parameters
typesee http://korturl.nu/stupidurl

Variable Documentation

uint8_t command_ack_payload

3 bit - Command type
1 bit - Request an ack - Indicator that receiver should send an ack back
1 bit - Is ack message - Indicator that this is the actual ack message
3 bit - Payload data type

uint8_t version

< Presentation messages

Library version

uint8_t version_length

2 bit - Protocol version
1 bit - Signed flag
5 bit - Length of payload