Measures
and Logs

Implementation : a sub "measures"by ressources

Most of the time a measure is related to a resource: device, sequence, installation, …
For exemple: the measure “energy” is related to a "meter", “temperature” to a thermostat,  a "state: switched-on” to a light, ….
But a measure can also be linked to another resource: "number of time a sequence has run", "number of time a user has connected itself to an installation", …

As a result, a measure is a sub-collection of a resource

A measure is composed of two sets of data

1 / Meta data

It describes a measure. searchable with a GET. A resource could support many measures, for instance a weather station can support a measure for the wind, the brightness and the temperature. Each of them is defined by a set of properties being the metadata describing the measure. 

The meta-data describing a measure are :

• Name : a friendly name (example : external wind”, “indoor temperature”)
• Type : Use to regroup measures in categories describing its format and potential operations (speed, temperature)
• Unit : for a type, different units can exist (Temperature can use Celsius or Fahrenheit as unit, Speed can use m/s or Km/h or mph
• Periodicity :  indicate at which periodicity the values are recorded
  

In case of our weather station, we have three measures :

Note :  A measure can return per timestamp one or several values. The unit is only for the first one (the most important one).

2 / Value data

In order to interrogate the values, a specific query language is available.
Here under are the keywords to use in order to interrogate a measure data

• start-date  (mandatory)
• end-date   (mandatory in order to avoid a return with too many values)
• [step]        (optional : minute, month, year, etc …)
  

For a MEASURE, different operations are available such as average, sum, min-max, count, list.

Note : if no [step] is specified, it will take the periodicity set by default in the device

As a developer, any operations can be used on a MEASURE (average, sum, count, etc…), but sometimes the return can have no real meaning. 
For instance, if an average operation is made on a boolean data (the switched-on of a light) the data will be returned but will have no real meaning. 
Knowing that a light has switched-on 0,654 times on average for the past month could not be explicit.

An example with Domovea installation composed by three devices :

• One energy meter with one sensor which measure energy with a periodicity of one value per minute
• One weather station with three sensors (temperature, brightness, wind)
• One light with no sensor but with the state of the light that is recorded
  

The major endpoints of that installation are:

/installations/{id}
/installations/{id}/lights/{id}
/installations/{id}/house-meters/{id}
/installations/{id}/weather-stations/{id}

So the first thing to do is knowing which kind of meta-data is measure for those devices.
In a postman software I use a GET function

Now that I know what to call, I can use "Post" operation:

What is a log ?

A log is the recording of a non-metric data on a time basis. 
A non-metric is a value on which operations (sum, average, …) cannot be done
It follows the same characteristics than a MEASURE about periodicity, and number of properties (1 or many) per LOG

Implementation : a sub collection « logs » by ressources

For the devices, the log can be an error number and an error message, it can be an event such as an alarm alert, the change of an installation/configuration property.
Important the major difference between a log and a measure is the fact that a log is a non-metric data on which no calculation can be done.
As a result, a,log is a sub-collection of a resource, for example :

A log is composed of two set of data

1 / Meta Data

The meta-data = describing a log. searchable with a GET
The values-data = the data log . Searchable with a POST /OPERATORS and a specific QUERY LANGUAGE

The meta-data describing a log is composed by :

• A complete name : “errors”, “car plug/unplugged”
• A Periodicity :  indicate at which periodicity the values are recorded
  

In the case of our charging-stations, we have two logs :

2 / Value Data

In order to interrogate the values, a specific query language is available.
Here under are the keywords to use in order to interrogate a measure data

• start-date  (mandatory)
• end-date   (mandatory in order to avoid a return with too many values)
  

On a LOG, two operations are available list and count.