API Reference

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:

  1. Restore USB communication, if the Node has a USB data connection.
  2. Call the function set via onWake().
  3. Find out why the device woke up and call the function set via the related on*() method.
  4. Call the function set via onSleep().
  5. 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 use onWake(), onInterval() and onSleep() 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));

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));

Method: configInterval

void configInterval(bool enabled, uint32_t ms);
void configInterval(bool enabled);

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 than 8000 makes no sense. It also means that the maximum time between calls can be up to 8 seconds longer than ms 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);

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);

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));

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));

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));

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);

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);

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));

Method: onButtonRelease

Set a function to be called when the button is released.

void onButtonRelease(void(*callback)(unsigned long duration));

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);

LED

Configure the LED.

Method: setColor

Combine one or more LEDs to get a primary or additive color.

setColor(ttn_color color);

Method: setRGB

Turn one or more LEDs on or off.

void setRGB(bool red = false, bool green = false, bool blue = false);

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);

Method: setGreen

Turn the red LED on or off.

void setGreen(bool on = true);

Method: setBlue

Turn the red LED on or off.

void setBlue(bool on = true);

Method: getColor

Returns the current color of the LED.

ttn_color 
getColor();

Returns one of:

Method: colorToString

Returns a string for the color passed to it.

String colorToString(ttn_color color);

Returns one of:

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);

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();