MySensors Library & Examples  2.3.1
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:

ESYS SUB Message Comment
!MCO BGN HW ERR Error HW initialization (e.g. ext. EEPROM)
MCO BGN INIT %s,CP=%s,REL=%d,VER=%s (%d) Core initialization, capabilities (CP), 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 SLP MS=%lu,SMS=%d,I1=%d,M1=%d,I2=%d,M2=%d Sleep node, time (MS), smartSleep (SMS), Int1/M1, Int2/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 uint8_t sensorType, const char *description="", const bool ack=false)
 
bool sendSketchInfo (const char *name, const char *version, const bool ack=false)
 
bool send (MyMessage &msg, const bool ack=false)
 
bool sendBatteryLevel (const uint8_t level, const bool ack=false)
 
bool sendHeartbeat (const bool ack=false)
 
bool sendSignalStrength (const int16_t level, const bool ack=false)
 
bool sendTXPowerLevel (const uint8_t level, const bool ack=false)
 
bool request (const uint8_t childSensorId, const uint8_t variableType, const uint8_t destination=GATEWAY_ADDRESS)
 
bool requestTime (const bool ack=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 uint8_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)
 
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 &message) __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 hwInitialization 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

bool _processInternalCoreMessage ( void  )

Processes internal core message.

Returns
True if no further processing required
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.
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)
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.
controllerConfig_t getControllerConfig ( void  )

Returns the most recent node configuration received from controller

uint8_t getNodeId ( void  )

Return this nodes id.

uint8_t getParentNodeId ( void  )

Return the parent node id.

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.
void loop ( void  )

Main loop.

Main loop.

bool present ( const uint8_t  sensorId,
const uint8_t  sensorType,
const char *  description = "",
const bool  ack = 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.
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
descriptionA textual description of the sensor.
Returns
true Returns true if message reached the first stop on its way to destination.
Examples:
SecureActuator.ino.
void presentNode ( void  )

Sends node information to the gateway.

void receive ( const MyMessage message)

Callback for incoming messages.

Parameters
messageCallback for incoming messages.
messageThe message to handle.
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.
bool requestTime ( const bool  ack = false)

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

Parameters
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
Returns
true Returns true if message reached the first stop on its way to destination.
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.
bool send ( MyMessage msg,
const bool  ack = false 
)

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

Parameters
msgMessage to send
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
Returns
true Returns true if message reached the first stop on its way to destination.
bool sendBatteryLevel ( const uint8_t  level,
const bool  ack = false 
)

Send this nodes battery level to gateway.

Parameters
levelLevel between 0-100(%)
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
Returns
true Returns true if message reached the first stop on its way to destination.
bool sendHeartbeat ( const bool  ack = 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
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
Returns
true Returns true if message reached the first stop on its way to destination.
bool sendSignalStrength ( const int16_t  level,
const bool  ack = false 
)

Send this nodes signal strength to gateway.

Parameters
levelSignal strength can be RSSI if the radio provide it, or another kind of calculation
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
Returns
true Returns true if message reached the first stop on its way to destination.
bool sendSketchInfo ( const char *  name,
const char *  version,
const bool  ack = 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
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
Returns
true Returns true if message reached the first stop on its way to destination.
Examples:
SecureActuator.ino.
bool sendTXPowerLevel ( const uint8_t  level,
const bool  ack = false 
)

Send this nodes TX power level to gateway.

Parameters
levelFor instance, can be TX power level in dbm
ackSet this to true if you want destination node to send ack back to this node. Default is not to request any ack.
Returns
true Returns true if message reached the first stop on its way to destination.
void setup ( void  )

Called after node initialises but before main loop.

Called after node initialises but before main loop.

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)
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)
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)
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 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)
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 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)
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 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)
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.
bool wait ( const uint32_t  waitingMS,
const uint8_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