MySensors Library & Examples  2.3.2
Modules | Classes | Macros | Functions
+ Collaboration diagram for MySensorsCore:

Detailed Description

API declaration for MySensorsCore.

MySensorsCore-related log messages, format: [!]SYSTEM:[SUB SYSTEM:]MESSAGE

MySensorsCore debug log messages:

E SYS SUB Message Comment
! MCO BGN HW ERR Error HW initialization (e.g. ext. EEPROM)
MCO BGN INIT %s,CP=%s,FQ=%d,REL=%d,VER=%s Core initialization, capabilities (CP), CPU frequency [Mhz] (FQ), release number (REL), library version (VER)
MCO BGN BFR Callback before()
MCO BGN STP Callback setup()
MCO BGN INIT OK,TSP=%d Core initialised, transport status (TSP): 0=not initialised, 1=initialised, NA=not available
MCO BGN NODE UNLOCKED Node successfully unlocked (see signing chapter)
! MCO BGN TSP FAIL Transport initialization failed
MCO REG REQ Registration request
MCO REG NOT NEEDED No registration needed (i.e. GW)
! MCO SND NODE NOT REG Node is not registered, cannot send message
MCO PIM NODE REG=%d Registration response received, registration status (REG)
! MCO WAI RC=%d Recursive call detected in wait(), level (RC)
MCO SLP MS=%lu,SMS=%d,I1=%d,M1=%d,I2=%d,M2=%d Sleep node, time (MS), smartSleep (SMS), Int1 (I1), Mode1 (M1), Int2 (I2), Mode2 (M2)
MCO SLP WUP=%d Node woke-up, reason/IRQ (WUP)
! MCO SLP NTL Sleeping not possible, no time left
! MCO SLP FWUPD Sleeping not possible, FW update ongoing
! MCO SLP REP Sleeping not possible, repeater feature enabled
! MCO SLP TNR Transport not ready, attempt to reconnect until timeout (MY_SLEEP_TRANSPORT_RECONNECT_TIMEOUT_MS)
MCO NLK NODE LOCKED. UNLOCK: GND PIN %d AND RESET Node locked during booting, see signing chapter for additional information
MCO NLK TSL Set transport to sleep

Modules

 MyNodeLock
 API declaration for MyNodeLock.
 

Classes

struct  controllerConfig_t
 Controller configuration. More...
 
struct  coreConfig_t
 Node core configuration. More...
 

Macros

#define GATEWAY_ADDRESS   ((uint8_t)0)
 Node ID for GW sketch.
 
#define NODE_SENSOR_ID   ((uint8_t)255)
 Node child is always created/presented when a node is started.
 
#define MY_CORE_VERSION   ((uint8_t)2)
 core version
 
#define MY_CORE_MIN_VERSION   ((uint8_t)2)
 min core version required for compatibility
 
#define MY_WAKE_UP_BY_TIMER   ((int8_t)-1)
 Sleeping wake up by timer.
 
#define MY_SLEEP_NOT_POSSIBLE   ((int8_t)-2)
 Sleeping not possible.
 
#define INTERRUPT_NOT_DEFINED   ((uint8_t)255)
 _sleep() param: no interrupt defined
 
#define MODE_NOT_DEFINED   ((uint8_t)255)
 _sleep() param: no mode defined
 
#define VALUE_NOT_DEFINED   ((uint8_t)255)
 Value not defined.
 
#define FUNCTION_NOT_SUPPORTED   ((uint16_t)0)
 Function not supported.
 

Functions

uint8_t getNodeId (void)
 
uint8_t getParentNodeId (void)
 
void presentNode (void)
 
bool present (const uint8_t sensorId, const mysensors_sensor_t sensorType, const char *description="", const bool requestEcho=false)
 
bool sendSketchInfo (const char *name, const char *version, const bool requestEcho=false)
 
bool send (MyMessage &msg, const bool requestEcho=false)
 
bool sendBatteryLevel (const uint8_t level, const bool requestEcho=false)
 
bool sendHeartbeat (const bool requestEcho=false)
 
bool sendSignalStrength (const int16_t level, const bool requestEcho=false)
 
bool sendTXPowerLevel (const uint8_t level, const bool requestEcho=false)
 
bool request (const uint8_t childSensorId, const uint8_t variableType, const uint8_t destination=GATEWAY_ADDRESS)
 
bool requestTime (const bool requestEcho=false)
 
controllerConfig_t getControllerConfig (void)
 
void saveState (const uint8_t pos, const uint8_t value)
 
uint8_t loadState (const uint8_t pos)
 
void wait (const uint32_t waitingMS)
 
bool wait (const uint32_t waitingMS, const mysensors_command_t cmd)
 
bool wait (const uint32_t waitingMS, const mysensors_command_t cmd, const uint8_t msgtype)
 
void doYield (void)
 
int8_t sleep (const uint32_t sleepingMS, const bool smartSleep=false)
 
int8_t sleep (const uint8_t interrupt, const uint8_t mode, const uint32_t sleepingMS=0, const bool smartSleep=false)
 
int8_t sleep (const uint8_t interrupt1, const uint8_t mode1, const uint8_t interrupt2, const uint8_t mode2, const uint32_t sleepingMS=0, const bool smartSleep=false)
 
int8_t smartSleep (const uint32_t sleepingMS)
 
int8_t smartSleep (const uint8_t interrupt, const uint8_t mode, const uint32_t sleepingMS=0)
 
int8_t smartSleep (const uint8_t interrupt1, const uint8_t mode1, const uint8_t interrupt2, const uint8_t mode2, const uint32_t sleepingMS=0)
 
int8_t _sleep (const uint32_t sleepingMS, const bool smartSleep=false, const uint8_t interrupt1=INTERRUPT_NOT_DEFINED, const uint8_t mode1=MODE_NOT_DEFINED, const uint8_t interrupt2=INTERRUPT_NOT_DEFINED, const uint8_t mode2=MODE_NOT_DEFINED)
 
uint32_t getSleepRemaining (void)
 
void _begin (void)
 Node initialisation.
 
void _process (void)
 Main framework process.
 
bool _processInternalCoreMessage (void)
 Processes internal core message. More...
 
void _infiniteLoop (void)
 Puts node to a infinite loop if unrecoverable situation detected.
 
void _registerNode (void)
 Handles registration request.
 
bool _sendRoute (MyMessage &message)
 Sends message according to routing table. More...
 
void receive (const MyMessage &) __attribute__((weak))
 Callback for incoming messages. More...
 
void receiveTime (uint32_t) __attribute__((weak))
 Callback for incoming time messages.
 
void presentation (void) __attribute__((weak))
 Node presentation.
 
void before (void) __attribute__((weak))
 Called before node initialises.
 
void preHwInit (void) __attribute__((weak))
 Called before any hardware initialisation is done.
 
void setup (void) __attribute__((weak))
 Called after node initialises but before main loop. More...
 
void loop (void) __attribute__((weak))
 Main loop. More...
 

Function Documentation

◆ _processInternalCoreMessage()

bool _processInternalCoreMessage ( void  )

Processes internal core message.

Returns
True if no further processing required

◆ _sendRoute()

bool _sendRoute ( MyMessage message)

Sends message according to routing table.

Parameters
message
Returns
true Returns true if message reached the first stop on its way to destination.

◆ _sleep()

int8_t _sleep ( const uint32_t  sleepingMS,
const bool  smartSleep = false,
const uint8_t  interrupt1 = INTERRUPT_NOT_DEFINED,
const uint8_t  mode1 = MODE_NOT_DEFINED,
const uint8_t  interrupt2 = INTERRUPT_NOT_DEFINED,
const uint8_t  mode2 = MODE_NOT_DEFINED 
)

Sleep (PowerDownMode) the MCU and radio. Wake up on timer or pin change for two separate interrupts. See: http://arduino.cc/en/Reference/attachInterrupt for details on modes and which pin is assigned to what interrupt. On Nano/Pro Mini: 0=Pin2, 1=Pin3

Parameters
sleepingMSNumber of milliseconds to sleep or 0 to sleep forever
interrupt1(optional) First interrupt that should trigger the wakeup
mode1(optional) Mode for first interrupt (RISING, FALLING, CHANGE)
interrupt2(optional) Second interrupt that should trigger the wakeup
mode2(optional) Mode for second interrupt (RISING, FALLING, CHANGE)
smartSleep(optional) Set True if sending heartbeat and process incoming messages before going to sleep.
Returns
Interrupt number if wake up was triggered by pin change, MY_WAKE_UP_BY_TIMER if wake up was triggered by timer, MY_SLEEP_NOT_POSSIBLE if sleep was not possible (e.g. ongoing FW update)

◆ doYield()

void doYield ( void  )

Function to allow scheduler to do some work.

Remarks
Internally it will call yield, kick the watchdog and update led states.
Examples
SecurityPersonalizer.ino.

◆ getControllerConfig()

controllerConfig_t getControllerConfig ( void  )

Returns the most recent node configuration received from controller

◆ getNodeId()

uint8_t getNodeId ( void  )

Return this nodes id.

◆ getParentNodeId()

uint8_t getParentNodeId ( void  )

Return the parent node id.

◆ getSleepRemaining()

uint32_t getSleepRemaining ( void  )

Return the sleep time remaining after waking up from sleep. Depending on the CPU architecture, the remaining time can be seconds off (e.g. upto roughly 8 seconds on AVR).

Returns
Time remaining, in ms, when wake from sleep by an interrupt, 0 by timer (MY_WAKE_UP_BY_TIMER), undefined otherwise.

◆ loadState()

uint8_t loadState ( const uint8_t  pos)

Load a state (from local EEPROM).

Parameters
posThe position to fetch value from (0-255)
Returns
Value to store in position
Examples
SecureActuator.ino.

◆ loop()

void loop ( )

Main loop.

Main loop.

Definition at line 28 of file Echo.ino.

◆ present()

bool present ( const uint8_t  sensorId,
const mysensors_sensor_t  sensorType,
const char *  description = "",
const bool  requestEcho = false 
)

Each node must present all attached sensors before any values can be handled correctly by the controller. It is usually good to present all attached sensors after power-up in setup().

Parameters
sensorIdSelect a unique sensor id for this sensor. Choose a number between 0-254.
sensorTypeThe sensor type. See sensor typedef in MyMessage.h.
descriptionA textual description of the sensor.
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.
Examples
SecureActuator.ino.

◆ presentNode()

void presentNode ( void  )

Sends node information to the gateway.

◆ receive()

void receive ( const MyMessage message)

Callback for incoming messages.

Callback for incoming messages.

Parameters
messageThe message to handle.

Definition at line 86 of file DimmableLEDActuator.ino.

◆ request()

bool request ( const uint8_t  childSensorId,
const uint8_t  variableType,
const uint8_t  destination = GATEWAY_ADDRESS 
)

Requests a value from gateway or some other sensor in the radio network. Make sure to add callback-method in begin-method to handle request responses.

Parameters
childSensorIdThe unique child id for the different sensors connected to this Arduino. 0-254.
variableTypeThe variableType to fetch
destinationThe nodeId of other node in radio network. Default is gateway
Returns
true Returns true if message reached the first stop on its way to destination.

◆ requestTime()

bool requestTime ( const bool  requestEcho = false)

Requests time from controller. Answer will be delivered to receiveTime function in sketch.

Parameters
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.

◆ saveState()

void saveState ( const uint8_t  pos,
const uint8_t  value 
)

Save a state (in local EEPROM). Good for actuators to "remember" state between power cycles.

You have 256 bytes to play with. Note that there is a limitation on the number of writes the EEPROM can handle (~100 000 cycles on ATMega328).

Parameters
posThe position to store value in (0-255)
valueto store in position
Examples
SecureActuator.ino.

◆ send()

bool send ( MyMessage msg,
const bool  requestEcho = false 
)

Sends a message to gateway or one of the other nodes in the radio network

Parameters
msgMessage to send
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.

◆ sendBatteryLevel()

bool sendBatteryLevel ( const uint8_t  level,
const bool  requestEcho = false 
)

Send this nodes battery level to gateway.

Parameters
levelLevel between 0-100(%)
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.

◆ sendHeartbeat()

bool sendHeartbeat ( const bool  requestEcho = false)

Send a heartbeat message (I'm alive!) to the gateway/controller. The payload will be an incremental 16 bit integer value starting at 1 when sensor is powered on.

Parameters
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.

◆ sendSignalStrength()

bool sendSignalStrength ( const int16_t  level,
const bool  requestEcho = false 
)

Send this nodes signal strength to gateway.

Parameters
levelSignal strength can be RSSI if the radio provide it, or another kind of calculation
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.

◆ sendSketchInfo()

bool sendSketchInfo ( const char *  name,
const char *  version,
const bool  requestEcho = false 
)

Sends sketch meta information to the gateway. Not mandatory but a nice thing to do.

Parameters
nameString containing a short Sketch name or NULL if not applicable
versionString containing a short Sketch version or NULL if not applicable
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.
Examples
SecureActuator.ino.

◆ sendTXPowerLevel()

bool sendTXPowerLevel ( const uint8_t  level,
const bool  requestEcho = false 
)

Send this nodes TX power level to gateway.

Parameters
levelFor instance, can be TX power level in dbm
requestEchoSet this to true if you want destination node to echo the message back to this node. Default is not to request echo. If set to true, the final destination will echo back the contents of the message, triggering the receive() function on the original node with a copy of the message, with message.isEcho() set to true and sender/destination switched.
Returns
true Returns true if message reached the first stop on its way to destination.

◆ setup()

void setup ( )

Called after node initialises but before main loop.

Called after node initialises but before main loop.

Definition at line 20 of file Echo.ino.

◆ sleep() [1/3]

int8_t sleep ( const uint32_t  sleepingMS,
const bool  smartSleep = false 
)

Sleep (PowerDownMode) the MCU and radio. Wake up on timer.

Parameters
sleepingMSNumber of milliseconds to sleep.
smartSleepSet True if sending heartbeat and process incoming messages before going to sleep.
Returns
MY_WAKE_UP_BY_TIMER if timer woke it up, MY_SLEEP_NOT_POSSIBLE if not possible (e.g. ongoing FW update)

◆ sleep() [2/3]

int8_t sleep ( const uint8_t  interrupt,
const uint8_t  mode,
const uint32_t  sleepingMS = 0,
const bool  smartSleep = false 
)

Sleep (PowerDownMode) the MCU and radio. Wake up on timer or pin change. See: http://arduino.cc/en/Reference/attachInterrupt for details on modes and which pin is assigned to what interrupt. On Nano/Pro Mini: 0=Pin2, 1=Pin3

Parameters
interruptInterrupt that should trigger the wakeup
modeRISING, FALLING, CHANGE
sleepingMSNumber of milliseconds to sleep or 0 to sleep forever
smartSleepSet True if sending heartbeat and process incoming messages before going to sleep
Returns
Interrupt number if wake up was triggered by pin change, MY_WAKE_UP_BY_TIMER if wake up was triggered by timer, MY_SLEEP_NOT_POSSIBLE if sleep was not possible (e.g. ongoing FW update)

◆ sleep() [3/3]

int8_t sleep ( const uint8_t  interrupt1,
const uint8_t  mode1,
const uint8_t  interrupt2,
const uint8_t  mode2,
const uint32_t  sleepingMS = 0,
const bool  smartSleep = false 
)

Sleep (PowerDownMode) the MCU and radio. Wake up on timer or pin change for two separate interrupts. See: http://arduino.cc/en/Reference/attachInterrupt for details on modes and which pin is assigned to what interrupt. On Nano/Pro Mini: 0=Pin2, 1=Pin3

Parameters
interrupt1First interrupt that should trigger the wakeup
mode1Mode for first interrupt (RISING, FALLING, CHANGE)
interrupt2Second interrupt that should trigger the wakeup
mode2Mode for second interrupt (RISING, FALLING, CHANGE)
sleepingMSNumber of milliseconds to sleep or 0 to sleep forever
smartSleepSet True if sending heartbeat and process incoming messages before going to sleep.
Returns
Interrupt number if wake up was triggered by pin change, MY_WAKE_UP_BY_TIMER if wake up was triggered by timer, MY_SLEEP_NOT_POSSIBLE if sleep was not possible (e.g. ongoing FW update)

◆ smartSleep() [1/3]

int8_t smartSleep ( const uint32_t  sleepingMS)
Deprecated:
Use sleep(ms, true) instead Same as sleep(), send heartbeat and process incoming messages before going to sleep. Specify the time to wait for incoming messages by defining MY_SMART_SLEEP_WAIT_DURATION_MS to a time (ms).
Parameters
sleepingMSNumber of milliseconds to sleep.
Returns
MY_WAKE_UP_BY_TIMER if timer woke it up, MY_SLEEP_NOT_POSSIBLE if not possible (e.g. ongoing FW update)

◆ smartSleep() [2/3]

int8_t smartSleep ( const uint8_t  interrupt,
const uint8_t  mode,
const uint32_t  sleepingMS = 0 
)
Deprecated:
Use sleep(interrupt, mode, ms, true) instead Same as sleep(), send heartbeat and process incoming messages before going to sleep. Specify the time to wait for incoming messages by defining MY_SMART_SLEEP_WAIT_DURATION_MS to a time (ms).
Parameters
interruptInterrupt that should trigger the wakeup
modeRISING, FALLING, CHANGE
sleepingMSNumber of milliseconds to sleep or 0 to sleep forever
Returns
Interrupt number if wake up was triggered by pin change, MY_WAKE_UP_BY_TIMER if wake up was triggered by timer, MY_SLEEP_NOT_POSSIBLE if sleep was not possible (e.g. ongoing FW update)

◆ smartSleep() [3/3]

int8_t smartSleep ( const uint8_t  interrupt1,
const uint8_t  mode1,
const uint8_t  interrupt2,
const uint8_t  mode2,
const uint32_t  sleepingMS = 0 
)
Deprecated:
Use sleep(interrupt1, mode1, interrupt2, mode2, ms, true) instead Same as sleep(), send heartbeat and process incoming messages before going to sleep. Specify the time to wait for incoming messages by defining MY_SMART_SLEEP_WAIT_DURATION_MS to a time (ms).
Parameters
interrupt1First interrupt that should trigger the wakeup
mode1Mode for first interrupt (RISING, FALLING, CHANGE)
interrupt2Second interrupt that should trigger the wakeup
mode2Mode for second interrupt (RISING, FALLING, CHANGE)
sleepingMSNumber of milliseconds to sleep or 0 to sleep forever
Returns
Interrupt number if wake up was triggered by pin change, MY_WAKE_UP_BY_TIMER if wake up was triggered by timer, MY_SLEEP_NOT_POSSIBLE if sleep was not possible (e.g. ongoing FW update)

◆ wait() [1/3]

void wait ( const uint32_t  waitingMS)

Wait for a specified amount of time to pass. Keeps process()ing. This does not power-down the radio nor the Arduino. Because this calls process() in a loop, it is a good way to wait in your loop() on a repeater node or sensor that listens to messages.

Parameters
waitingMSNumber of milliseconds to wait.

◆ wait() [2/3]

bool wait ( const uint32_t  waitingMS,
const mysensors_command_t  cmd 
)

Wait for a specified amount of time to pass or until specified message received. Keeps process()ing. This does not power-down the radio nor the Arduino. Because this calls process() in a loop, it is a good way to wait in your loop() on a repeater node or sensor that listens to messages.

Parameters
waitingMSNumber of milliseconds to wait.
cmdCommand of incoming message.
Returns
True if specified message received

◆ wait() [3/3]

bool wait ( const uint32_t  waitingMS,
const mysensors_command_t  cmd,
const uint8_t  msgtype 
)

Wait for a specified amount of time to pass or until specified message received. Keeps process()ing. This does not power-down the radio nor the Arduino. Because this calls process() in a loop, it is a good way to wait in your loop() on a repeater node or sensor that listens to messages.

Parameters
waitingMSNumber of milliseconds to wait.
cmdCommand of incoming message.
msgtypeMessage type.
Returns
True if specified message received