Thingsquare device power modes

The Thingsquare firmware allows a device to run in a few different modes, depending on what suits the application best. The modes are connected, feather, and deadleaf mode.

The power modes

Mode: connected

In connected mode, the device maintains a TLS-connection with the backend servers. This is a rather costly connection to maintain, hence this is used mostly for gateways - which typically have an Ethernet connection - and when devices perform a firmware update over the air. When a device is updating the firmware over the air, it will establish and maintain such a connection for the duration of the firmware transfer and update process.

In all other aspects, the device behaves as a feather device.

Mode: feather

In feather mode, the device is responsive to variables and commands from the backend. It constantly duty cycles the radio, and routes packets for other participants in the network, yet does not maintain a TLS-connection.

The setting period is used to control how often the device sends sensordata, see below.

This is the default mode for devices except gateways. If no other mode is set through the use of thsq_set_default_mode() the device will be in feather mode, unless it's a gateway, then it's connected.

An example of this mode can be seen in the following image. The regular big bumps are increases in power consumption when the radio is briefly turned on.

Mode: deadleaf

In deadleaf mode, the device optimizes for power. This means keeping the radio off and deep sleeping the CPU as much as possible. This means that the device will from time to time - on the order of minutes depending on settings - wake up the radio, find synchronization with the multichannel radio protocol, and poll for new data from the backend server. Since the radio is turned off most of the time, a deadleaf device cannot route packets for others.

The device will thus take longer to reach if you want to eg reconfigure settings since there is no way to contact it before it decides to wake up again. For devices with BLE beacons, it will also by default lower the beacon rate to optimize for longer lifetime.

Once in deadleaf-mode, there are a number of settings that can be tweaked to balance lifetime against latency and data updates. The Thingsquare module powerconf collects all these in a handy module that can be used to set default values.

As follows, the settings can be controlled using variables, but have defaults that they fall back on if a varible is not defined.

An example of this mode can be seen in the following image. In contrast to the feather mode, the radio is completely turned off until needed. The few remaining bumps are various things, mostly the CPU handling small tasks.

Setting: period

The period setting sets how often the device reports sensor data. The variable is set in seconds, eg setting period to 300 means the device will roughly every 5 minutes report sensor data to the backend. For slow moving sensor data, such as indoor ambient temperature, setting this to 15 or 30 minutes is a good trade-off (900 or 1800). The default value is 1800 seconds (30 minutes).

When the time to send sensor data is now, the system will invoke the Thingsquare event callbacks with the THSQ_PERIOD event. See documentation on callbacks. Note that this event happens roughly every period seconds. To avoid lock-in constant collision scenarios - where two or more devices with the same period keeps want to transmit at the same time and perpetually interfere with each-other - the event is invoked at a random occasion in the interval [period / 2, period].

The period setting is valid not only for deadleaf devices, but for all devices. However, due to the power constrained nature of the typical deadlead device, this might be the primary setting to tweak to reduce power consumption.

Setting: stats

In a similar vein as period, stats set how often a device will transmit health statistics, such as network and RF measurements and statistics that help troubleshoot networks and devices. Just as period, stats is set in seconds. The default value is 1800 seconds (30 minutes).

The stats setting is used with all devices.

Setting: beacons

For devices that transmit BLE beacons, setting beacons to 0 will make the device minimize the use of BLE beacons. Otherwise, if beacons is set to 1, the device will send beacons more often in order to make device discovery from a smartphone app faster. This setting has no effect on devices withouth BLE. The default value is 0, meaning it will minimize the use of beacons.

Setting: deadleaf

Devices in deadleaf mode will keep the radio off as much as possible. From time to time, as set in seconds by the deadleaf variable, the device will wake up and poll the network parent.

This may entail having to search and find multichannel synchronization, which can be a costly operation. The multichannel protocol loses synchronization after about 5-10 minutes so setting deadleaf to 30 minutes means that the radio is used extremely little but reachability to the device is very slow, and actually can be more power costly than a smaller value that does not entail having to synchronize.

Note that if the device has a high deadleaf and a small period, for example 1 hour and 1 minute respectively, can mean the device manages to keep synch despite polling the network parent seldomly, hence the costly synchronization is avoided despite long deadleaf period.

The default value of deadleaf is 60 seconds, ie one minute.

Setting the power mode

The device power mode is controlled through the mode and the default mode. The default mode cannot be changed other through from within the firmware, while the mode variable can be, and is, changed during the normal operating conditions, such as a firmware update over the air.

The mode variable takes precedence over the default mode. The default mode is what the device uses when it boots up, but since it will try getting mode from the backend, it might be overriden.

The default mode is by default feather.

Setting the power mode from the server

The mode of a device may be set from the backend by setting the d variable mode. If no mode variable is set, the device defaults to the default power mode. Setting the mode variable to eg connected will make it start the TLS-connection.

Setting the default power mode

Setting the default mode is very easy. Use the void thsq_set_default_mode(const char *mode); defined in thsq.h, with either of the strings connected, feather, or deadleaf.

For example the example client file client-deadleaf.c contains the following,

#include "thsq.h"

void
app(void)
{
  thsq_set_default_mode("deadleaf");
}

That is all. This is all necessary for the device to optimize for power and try deep sleeping as much as possible.

However, for gateway devices, this is redundant due to the firmware network stack already taking priority. Hence, it is on a gateway not necessary to set the mode.

Dos and don'ts

  • Do set the default mode only once, in the application startup function, app(). Changing this during runtime may lead to unreliable and undefined behavior.

  • Do not set mode or default mode on gateways. They will already be in connected mode and handles this automatically.

Use cases

To answer "What power mode should I use?", you have to consider the requirements for the device at hand. Will it require battery-powered operation? Will it be required to route packets for others? A deadleaf device must have a feather or gateway nearby that it can send to.

Unless a device needs to operate on batteries, or are otherwise power-wise constrained, the normal power mode is feather. If a device is battery operated, then the normal case is deadleaf. There can of course be cases where a battery operated device is in feather mode, for example when powered by solar power in a sunny climate.