Measuring¶

Your measurement device can measure data for one or more properties. For each properties, your measurement device cen take multiple measurements in in time. The needforheat-generic-firmware library provides various convenience functions you can use to:

Registering a measurement property¶

Each property has its own:

property_name
format
unit

Before a NeedForHeat server accepts a property from any measurement device, the property first needs to be registered on that server.

In a future version of the NeedForHeat API and NeedForHeat server, we may drop this requirement.

Property value formatting¶

To format your measurement values, your firmware only needs to specify a printf format string for each property_name.

Example: adding a property formatter

Measurements::Measurement::AddFormatter("example", "%d"); // (1)!

example is the property name. %d is the printf format string that this property uses to format its value before it is sent to the NeedForHeat server via the NeedForHeat API in a JSON string.

Creating and timestamping a measurement¶

Before your firmware creates a measurement instance, it should have added a formatter for the measurement's property, as illustrated in the sectione Property value formatting above.

Two ways are available in the needforheat-generic-firmware library for your firmware to attach a timestamp to a measurement.

Using the current task time timestamp¶

If your firmware code does NOT specify a timestamp, the measurement timestamp will be set to the current task time before the measurement is uploaded securely. This is often a good default choice: all measurements of all properties that were started at the same time are guaranteed to have the same timestamp, which often makes analysis easier.

Example: creating a measurement with the current task time (the default)

#include <measurements.hpp>

int exampleValue = 1;

Measurements::Measurement exampleMeasurement("example", exampleValue); // (1)!

Create a new measurement with property type example and the value exampleValue. Since no timestamp is provided by the firmware, the generic firmware will attach the current task time to this measuerment value before it is uploaded to a NeedForHeat server via the NeedForHeat API.

Specifying a custom timestamp¶

If your firmware code specifies a custom timestamp, then this timestamp will be used when the measurement is uploaded securely. This may be a good choice for measurements that take such a long time to establish that using the current task time no longer seems appropriate. A disadvantage of this option is that it becomes harder during analysis to group measurements of different properties that were started at the same.

Example: creating a measurement with a custom timestamp

#include <measurements.hpp>

int exampleValue = 1;
time_t now = time(nullptr);

Measurements::Measurement exampleMeasurement("example", exampleValue, now); // (1)!

Create a new measurement with property type example and the value exampleCounter and timestamp now, i.e. the Unix timestamp of the device clock when the code evaluates time(nullptr).

Adding a measurement to the upload queue¶

The secure upload queue is a queue in volatile memory of the device, to which measurements can be added. Uploading queued measurements is not done immediately, but at a later moment.

In order to gain access to the secure upload queue, your measurement task first needs to get an instance of the queue. Each measurement device only has one instance of such a queue, shared by all measurement tasks, which may run in parallel.

A measurement can be added to the secure upload queue as shown below:

Getting access to the queue and adding a measurement

#include <secure_upload.hpp>

auto secureUploadQueue = SecureUpload::Queue::GetInstance();

secureUploadQueue.AddMeasurement(exampleMeasurement);