Class: TheThingsNode #
Include TheThingsNode class and create a pointer to the singleton instance like this:
#include <TheThingsNode.h>
TheThingsNode *node;
Method: setup #
Use the static setup()
method in your sketch’s setup()
function to create or get the class singleton.
void setup() {
node = TheThingsNode::setup();
}
Method: loop #
In your loop()
function, call the singleton’s loop()
method.
void loop() {
node->loop();
}
This will:
- Restore USB communication, if the Node has a USB data connection.
- Call the function set via
onWake()
. - Find out why the device woke up and call the function set via the related
on*()
method. - Call the function set via
onSleep()
. - Sleep the Node, unless the Node has a USB data connection and hasn’t been configured to also sleep in that case.
Don’t add any other code in your
loop()
function, but useonWake()
,onInterval()
andonSleep()
instead, to prevent unpredictable behavior.
Method: onWake #
Set a callback that will run first thing every time the Node wakes up, which is when an interrupt changes because of interaction with the button, motion sensor or temperature sensor. The device also wakes up every 8 seconds, which is the longest we can make it sleep.
void onWake(void(*callback)(void));
Usage:
void setup() {
node = TheThingsNode::setup();
node->onWake(wake);
}
void wake() {
node->setColor(TTN_GREEN);
}
Method: onSleep #
Set a callback that will run last thing before the Node goes back to sleep for 8 seconds or until an interrupt changes because of interaction with the button, motion sensor or temperature sensor.
void onSleep(void(*callback)(void));
void(*callback)(void)
: Function to be called, with no arguments nor return value.
Usage:
void setup() {
node = TheThingsNode::setup();
node->onSleep(sleep);
}
void sleep() {
node->setColor(TTN_BLACK);
}
Pay attention, this internal sleep method of the library does not put the LoRa module (RN2483 or RN2903) into sleep mode and thus your node may consume 3mA even in sleep mode. You need to manually set the LoRa module to sleep and wake. Check the example BatteryMonitorLPP.
Interval #
Instead of using your loop()
function, use configInterval()
and onInterval()
to set a function to be called on a certain interval:
void setup() {
node = TheThingsNode::setup();
// Call every 30s instead of the default 60
node->configInterval(true, 30000);
node->onInterval(interval);
}
void interval() {
node->showStatus();
}
Method: onInterval #
Set a callback that will run on a certain interval. This will automatically enable the interval.
void onInterval(void(*callback)(void));
void(*callback)(void)
: Function to be called, with no arguments nor return value.
Method: configInterval #
void configInterval(bool enabled, uint32_t ms);
void configInterval(bool enabled);
bool enabled
: Enable or disable the interval callback. Enabled automatically byonInterval()
, but you can use this method to temporarily disable it. Defaults tofalse
.uint32_t ms
: Minimal time between calling the interval callback. Defaults to60000
or 60 seconds.
If the Node has no USB data connection or is configured to also sleep in that case, it will only wake up every 8 seconds to check if the interval callback should run. This means setting
ms
to less than8000
makes no sense. It also means that the maximum time between calls can be up to 8 seconds longer thanms
if it wakes up to handle button or sensor interaction in between.
Method: showStatus #
Writes information about the device and sensors to Serial
.
void showStatus();
Will write something like:
Light: 25
Temperature: 23.16 C
Temperature alert: No
Moving: No
Button pressed: No
Color: Yellow
USB connected: Yes
Battery voltage: 4704 MV
Light #
Configure and read the light sensor.
Method: configLight #
Configure the light sensor.
void configLight(bool enabled, uint8_t gain);
void configLight(bool enabled);
bool enabled
: Enable or disable the light sensor. Defaults tofalse
.uint8_t gain
: TODO. Value between0
and3
. Defaults to1
.
Method: getLight #
Get the current value of the light sensor as an unsigned integer of 2 bytes.
uint16_t getLight();
Make sure you have enabled the light sensor or the value will be
0
.
Temperature #
Use and configure the temperature sensor.
Method: getTemperatureAsInt #
Get the current value of the temperature sensor in Celsius, rounded to a signed integer of 1 byte.
int8_t getTemperatureAsInt();
You can call this method even if the temperature alert has been disabled. The sensor will be woken up shortly to get the current temperature.
Method: getTemperatureAsFloat #
Get the current value of the temperature sensor in Celsius as signed float of 4 bytes.
float getTemperatureAsFloat();
You can call this method even if the temperature alert has been disabled. The sensor will be woken up shortly to get the current temperature.
Method: configTemperature #
Configure the temperature sensor.
void configTemperature(bool enabled, MCP9804_Resolution resolution, int8_t lower, int8_t upper, int8_t critical, MCP9804_Hysteresis hysteresis);
void configTemperature(bool enabled, MCP9804_Resolution resolution);
void configTemperature(bool enabled);
-
bool enabled
: Enable or disable the temperature sensor. Enabled automatically byonTemperature()
, but you can use this method to temporarily disable the sensor and therefore the alerts. Defaults tofalse
. -
MCP9804_Resolution resolution = R_DEGREES_0_0625
: Set the resolution (precision) of the sensor. One of:R_DEGREES_0_5000
: +0.5 CR_DEGREES_0_2500
: +0.25 CR_DEGREES_0_1250
: +0.125 CR_DEGREES_0_0625
: +0.0625 (default)
See the sensor’s data sheet, section 5.2.4 for more details.
-
int8_t lower
: Alert when temperature in Celsius is lower. Defaults to0
. -
int8_t upper
: Alert when temperature in Celsius is higher. Defaults to30
. -
int8_t critical = 55
: Alert when temperature in Celsius is higher. Defaults to55
, above which you run the risk of battery failure. -
MCP9804_Hysteresis hysteresis = H_DEGREES_0_0
: Set the margin for the bounds, before an alert is triggered. One of:H_DEGREES_0_0
: 0 C (default)H_DEGREES_1_5
: +1.5 CH_DEGREES_3_0
: +3 CH_DEGREES_6_0
: +6 C
See the sensor’s data sheet, section 5.2.2 for more details.
Method: onTemperatureAlert #
Register a function to be called when temperature exceeds the configured bounds. This will automatically enable the temperature alerts.
void onTemperature(void(*callback)(void));
void(*callback)(void)
: Function to be called, with no arguments nor return value.
Method: hasTemperatureAlert #
Returns true
if the current temperature exceeds the configured bounds for the alert. This also works if the alert itself is temporarily disabled.
bool hasTemperatureAlert();
Motion #
Use and configure the motion sensor.
Method: onMotionStart #
Set a function to be called when motion starts. This will automatically enable the motion sensor.
void onMotionStart(void(*callback)(void));
void(*callback)(void)
: Function to be called, with no arguments nor return value.
Method: onMotionStop #
Set a function to be called when motions stops. This will automatically enable the motion sensor.
void onMotionStop(void(*callback)(unsigned long duration));
void(*callback)
: Function to be called.unsigned long duration
: Time since the motion began, in ms.
Method: isMoving #
Returns true
if the device is currently moving. Requires the sensor to be enabled via onMotionStart()
, onMotionStop()
or setMotion()
.
Method: getAcceleration #
Returns the acceleration measured by the motion sensor in units of g-force. Each of the values x, y and z falls in the range -2g to +2g. This function is useful to determine the orientation of the sensor relative to the earth, as gravity causes a 1g acceleration towards the centre of the earth. Requires the sensor to be enabled via onMotionStart()
, onMotionStop()
or setMotion()
.
void getAcceleration(float *x, float *y, float *z);
float *x
: Float to store the acceleration along the x-axis.float *y
: Float to store the acceleration along the y-axis.float *z
: Float to store the acceleration along the z-axis.
Method: configMotion #
Enable or disable the motion sensor. The sensor will be enabled automatically by onMotionStart()
and onMotionStop()
, but you can use this method to temporarily disable the sensor.
void configMotion(bool enabled);
bool enabled
: Enable or disable the sensor.
Button #
Respond to interaction with the button.
Method: onButtonPress #
Set a function to be called when the button is pressed down.
void onButtonPress(void(*callback)(void));
void(*callback)(void)
: Function to be called, with no arguments nor return value.
Method: onButtonRelease #
Set a function to be called when the button is released.
void onButtonRelease(void(*callback)(unsigned long duration));
void(*callback)
: Function to be called.unsigned long duration
: Time since the button was pressed, in ms.
Method: isButtonPressed #
Returns true
if the button is currently pressed.
bool isButtonPressed();
Method: configButton #
Enable or disable the button callback. Will be enabled automatically by onButtonPress()
and onButtonRelease()
, but you can use this method to temporarily disable it.
void configButton(bool enabled);
bool enabled
: Enable or disable the button callback.
LED #
Configure the LED.
Method: setColor #
Combine one or more LEDs to get a primary or additive color.
setColor(ttn_color color);
ttn_color color
: Set to one of:TTN_RED
TTN_GREEN
TTN_BLUE
TTN_YELLOW
: Red and greenTTN_CYAN
: Green and blueTTN_MAGENTA
: Red and blueTTN_WHITE
: Red, green and blueTTN_BLACK
: None
Method: setRGB #
Turn one or more LEDs on or off.
void setRGB(bool red = false, bool green = false, bool blue = false);
bool red = false
: Set totrue
to turn the red LED on. Defaults tofalse
.bool green = false
: Set totrue
to turn the green LED on. Defaults tofalse
.bool blue = false
: Set totrue
to turn the blue LED on. Defaults tofalse
.
Combine colors to create additives, e.g. red plus green makes yellow.
Method: setRed #
Turn the red LED on or off.
void setRed(bool on = true);
bool on = true
: Set totrue
to turn the red LED on. Defaults totrue
.
Method: setGreen #
Turn the red LED on or off.
void setGreen(bool on = true);
bool on = true
: Set totrue
to turn the green LED on. Defaults totrue
.
Method: setBlue #
Turn the red LED on or off.
void setBlue(bool on = true);
bool on = true
: Set totrue
to turn the blue LED on. Defaults totrue
.
Method: getColor #
Returns the current color of the LED.
ttn_color getColor();
Returns one of:
TTN_RED
TTN_GREEN
TTN_BLUE
TTN_YELLOW
: Red and greenTTN_CYAN
: Green and blueTTN_MAGENTA
: Red and blueTTN_WHITE
: Red, green and blueTTN_BLACK
: None
Method: colorToString #
Returns a string for the color passed to it.
String colorToString(ttn_color color);
ttn_color color
: Color to return a string for.
Returns one of:
"Red"
:TTN_RED
"Green"
:TTN_GREEN
"Blue"
:TTN_BLUE
"Yellow"
:TTN_YELLOW
"Cyan"
:TTN_CYAN
"Magenta"
:TTN_MAGENTA
"White"
:TTN_WHITE
"Black"
:TTN_BLACK
Method: getRed #
Returns true
if the red LED is currently on.
bool getRed();
Method: getGreen #
Returns true
if the green LED is currently on.
bool getGreen();
Method: getBlue #
Returns `true if the blue LED is currently on.
bool getBlue();
USB #
Monitor the USB data connection.
Method: isUSBConnected #
Returns true
if the Node has a data connection over USB.
bool isUSBConnected();
Method:: configUSB #
Enable or disable deep sleep when a USB data connection is active.
void configUSB(bool deepSleep);
bool deepSleep
: Set totrue
to sleep the Node even if a USB data connection is active. Defaults tofalse
.
When disabled, the loop()
method will delay 100ms until an interrupt has changed or configured interval has been reached. When enabled, it will sleep until woken up by an interrupt change or every 8s.
When the Node goes into sleep, the Serial Monitor will loose its connection. The Node will try to reopen the connection when it wakes up, but Serial Monitor might not always be able to pick it up.
Method: getBattery #
Returns the battery level in millivolt (mV) as a unsigned integer of 2 bytes.
uint16_t getBattery();