17. Datum¶

In SolarNetwork a datum is the fundamental time-stamped data structure collected by SolarNodes and stored in SolarNet. It is a collection of properties associated with a specific information source at a specific time.

In this example datum description, we have all the comopnents of a datum:

A datum stream is the collection of datum from a single node for a single source over time.

A datum object is modeled as a flexible structure with the following core elements:

A datum is uniquely identified by the three combined properties (nodeId, sourceId, created).

17.1 Datum source IDs¶

Source IDs are user-defined strings used to distinguish between different information sources within a single node. For example, a node might collect data from an energy meter on source ID Meter and a solar inverter on Solar. SolarNetwork does not place any restrictions on source ID values, other than a 64-character limit. However, there is are some conventions used within SolarNetwork that are useful to follow, especially for larger deployment of nodes with many source IDs:

• Keep IDs as short as, for example Meter1 is better than Schneider ION6200 Meter - Main Building.
• Use a path-like structure to encode a logical hierarchy, in least specific to most specific order. For example /S1/B1/M1 could imply the first meter in the first building on the first site.
• The + and # characters should not be used. This is actually a constraint in the MQTT protocol used in parts of SolarNetwork, where the MQTT topic name includes the source ID. These characters are MQTT topic filter wildcards, and cannot be used in topic names.
• Avoid using wildcard special characters.

The path-like structure becomes useful in places where wildcard patterns are used, like security policies or datum queries. It is generally worthwhile spending some time planning on a source ID taxonomy to use when starting a new project with SolarNetwork.

17.2 Datum samples¶

The properties included in a datum object are known as datum samples. The samples are modeled as a collection of named properties, for example the temperature and humidity properties in the earlier example datum could be represented like this:

{
    "temperature" : 21.5,
    "humidity"    : 68
}

Another datum samples acquired from a power meter might look like this:

{
    "watts"     : 2150,
    "wattHours" : 6834834349,
    "mode"      : "auto"
}

17.3 Datum property classifications¶

The datum samples are actually further organized into three classifications:

These classifications help SolarNetwork understand how to aggregate the datum samples over time. When SolarNode uploads a datum to SolarNetwork, the sample will include the classification of each property. The previous example would thus more accurately be represented like this:

{
  "i": {
    "watts"     : 2150 // (1)!
  },
  "a": {
    "wattHours" : 6834834349 // (2)!
  },
  "s": {
    "mode"      : "auto" // (3)!
  }
}

1. watts is an instantaneous measurement of power that does not accumulate
2. wattHours is an accumulating measurement of the accrual of energy over time
3. mode is a status message that is not a number