Collaboration diagram for MySensorsCore:

Detailed Description

API declaration for MySensorsCore.

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

[!] Exclamation mark is prepended in case of error or warning
SYSTEM:
- MCO messages emitted by MySensorsCore
SUB SYSTEMS:
- MCO:BGN from _begin()
- MCO:REG from _registerNode()
- MCO:SND from send()
- MCO:PIM from _processInternalCoreMessage()
- MCO:NLK from _nodeLock()

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)

void	sleepHandler (bool sleep)

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

sleepingMS	Number 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

pos	The position to fetch value from (0-255)

Returns: Value to store in position

Examples: SecureActuator.ino.

◆ loop()

void 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

sensorId	Select a unique sensor id for this sensor. Choose a number between 0-254.
sensorType	The sensor type. See sensor typedef in MyMessage.h.
description	A textual description of the sensor.
requestEcho	Set 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.

Parameters

message The message to handle.

Definition at line 87 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

childSensorId	The unique child id for the different sensors connected to this Arduino. 0-254.
variableType	The variableType to fetch
destination	The 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

requestEcho Set 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

pos	The position to store value in (0-255)
value	to 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

msg	Message to send
requestEcho	Set 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

level	Level between 0-100(%)
requestEcho	Set 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

requestEcho Set 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

level	Signal strength can be RSSI if the radio provide it, or another kind of calculation
requestEcho	Set 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

name	String containing a short Sketch name or NULL if not applicable
version	String containing a short Sketch version or NULL if not applicable
requestEcho	Set 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

level	For instance, can be TX power level in dbm
requestEcho	Set 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.

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

sleepingMS	Number of milliseconds to sleep.
smartSleep	Set 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

interrupt	Interrupt that should trigger the wakeup
mode	RISING, FALLING, CHANGE
sleepingMS	Number of milliseconds to sleep or 0 to sleep forever
smartSleep	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)

◆ 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

interrupt1	First interrupt that should trigger the wakeup
mode1	Mode for first interrupt (RISING, FALLING, CHANGE)
interrupt2	Second interrupt that should trigger the wakeup
mode2	Mode for second interrupt (RISING, FALLING, CHANGE)
sleepingMS	Number of milliseconds to sleep or 0 to sleep forever
smartSleep	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)

◆ sleepHandler()

void sleepHandler ( bool sleep )

Sleep handler will be called right before and right after entering sleep mode. Applications can define own handler to optimize powering down peripherals before entering sleep.

Parameters

sleep true if entering sleep, false if exiting

◆ 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

sleepingMS Number 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

interrupt	Interrupt that should trigger the wakeup
mode	RISING, FALLING, CHANGE
sleepingMS	Number 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

interrupt1	First interrupt that should trigger the wakeup
mode1	Mode for first interrupt (RISING, FALLING, CHANGE)
interrupt2	Second interrupt that should trigger the wakeup
mode2	Mode for second interrupt (RISING, FALLING, CHANGE)
sleepingMS	Number 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

waitingMS Number 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

waitingMS	Number of milliseconds to wait.
cmd	Command 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

waitingMS	Number of milliseconds to wait.
cmd	Command of incoming message.
msgtype	Message type.

Returns: True if specified message received

Detailed Description

Modules

Classes

Macros

Functions

Function Documentation

◆ _processInternalCoreMessage()

◆ _sendRoute()

◆ _sleep()

◆ doYield()

◆ getControllerConfig()

◆ getNodeId()

◆ getParentNodeId()

◆ getSleepRemaining()

◆ loadState()

◆ loop()

◆ present()

◆ presentNode()

◆ receive()

◆ request()

◆ requestTime()

◆ saveState()

◆ send()

◆ sendBatteryLevel()

◆ sendHeartbeat()

◆ sendSignalStrength()

◆ sendSketchInfo()

◆ sendTXPowerLevel()

◆ setup()

◆ sleep() [1/3]

◆ sleep() [2/3]

◆ sleep() [3/3]

◆ sleepHandler()

◆ smartSleep() [1/3]

◆ smartSleep() [2/3]

◆ smartSleep() [3/3]

◆ wait() [1/3]

◆ wait() [2/3]

◆ wait() [3/3]