Energest
See also: getting started with the Simple Energest system service at tutorial:simple-energest
The Energest module can be used to implement lightweight, software-based energy estimation approach for resource-constrained IoT devices. By tracking the time various hardware components such as the radio is turned on, and by knowing the power consumption of the component, it is possible to estimate the energy consumption.
The Energest Module
The Energest module provides functions for keeping track when components are on, off or in different modes. The API for the Energest module is shown in the following table.
Function |
Purpose |
---|---|
|
Get the system time from the Energest time source. |
|
The number of ticks per second from the Energest time source. |
|
Set the specified type to on and start tracking the time. |
|
Set the specified type to off and update the total time. |
|
Switch from tracking time for the first type to the second type. |
|
Get the total time Energest has been tracking. |
|
Flush the Energest times for all components that are currently turned on. |
|
Read the total time the specified type has been turned on. |
|
Initialize the Energest module. |
The macro ENERGEST_CURRENT_TIME
returns a platform dependent system time for use by the Energest module and the constant ENERGEST_SECOND
specifies the number of ticks per second.
The macros ENERGEST_ON
, ENERGEST_OFF
, and ENERGEST_SWITCH
are used to tell the Energest module when a component changes mode and is normally only called by platforms and device drivers. When a component switches from one mode to another, it is recommended to use ENERGEST_SWITCH
as it provides better accuracy.
The macro ENERGEST_GET_TOTAL_TIME()
returns the total time the Energest module has been tracking. This is normally the same as CPU + LPM + DEEP_LPM
but can be overridden by platforms that provide additional Energest types.
The function energest_flush
updates the total time for all types that are currently turned on.
The function energest_type_time
returns the total time the specified type has been turned on. energy_flush
should be called before reading the total time to ensure the total time has been updated.
The function energest_init()
is called by the system during the boot-up procedure to initialize the Energest module.
The Energest types
There are five Energest types predefined that all Contiki-NG platforms should support.
Type |
Purpose |
---|---|
|
The CPU is active. |
|
The CPU is in low power mode. |
|
The CPU is in deep low power mode. |
|
The radio is transmitting. |
|
The radio is listening. |
The first three are used to track the different modes of the CPU. Not all CPUs support both LPM and deep LPM and in that case, the unused type will always report 0 as time. The latter two types are used to track when the radio is turned on and the state of the radio.
Adding new Energest types in a platform
A platform can provide additional Energest types by defining ENERGEST_CONF_PLATFORM_ADDITIONS
in contiki-conf.h
. It is up to the platform to ensure that ENERGEST_ON
/ENERGEST_OFF
/ENERGEST_SWITCH
is called at appropriate times for the new Energest types.
#define ENERGEST_CONF_PLATFORM_ADDITIONS ENERGEST_TYPE_COMPONENT1,ENERGEST_TYPE_COMPONENT2
Adding new Energest types in an application
An application can provide additional Energest types by defining ENERGEST_CONF_ADDITIONS
in project-conf.h
. It is up to the application to ensure that ENERGEST_ON
/ENERGEST_OFF
/ENERGEST_SWITCH
is called at appropriate times for the new Energest types.
#define ENERGEST_CONF_ADDITIONS ENERGEST_TYPE_COMPONENT3,ENERGEST_TYPE_COMPONENT4
Platform configuration for Energest
By default, the Energest module will use the the Rtimer Library clock as time source but a platform might provide a different time source. The example below configures the Energest module to use the Contiki-NG system clock. Note that if the time source has too low resolution, it might not be able to track quick mode changes that happens faster than a few clock ticks.
#define ENERGEST_CONF_CURRENT_TIME clock_time
#define ENERGEST_CONF_TIME_T clock_time_t
#define ENERGEST_CONF_SECOND CLOCK_SECOND
Using the Energest Module
For an example how to use the Contiki-NG system service called use Simple Energest, see tutorial:simple-energest.
If need more features than the Simple Energest can provide, see tutorial:energest for an example how to directly use Energest from an application.