# D15: Hypercat / SenML representation #

In order for the data manipulated by the system to be distributed over
HyperCat[1], it needs to be serialisable as SenML[2]

## SenML representation ##

SenML is a simple representation that can carry a number of data points for
multiple data series in a single data frame. It can be serialised to XML or
JSON. A SenML frame has the ability to specify base values for a number of
attributes to avoid having them repeated in individual data point entries.
This can be particularly useful to convey concentrator and device level
attributes.

JSON generated from a OpenTRV device for a single sensor:

[ "2015-06-16T00:01:17Z", "", {"@":"4b62","+":7,"vac|h":74,"v|%":0,"tT|C":5} ]

Possible SenML representation (assuming 12345678 is the ID of the concentrator):

{
    "bn": "urn:dev:id:12345678/4b62/",
    "bt": 1433894477,
    "e": [
        { "n": "+",   "v": 7 },
        { "n": "vac", "v": 74, "u": "h" },
        { "n": "v",   "v": 0,  "u": "%" },
        { "n": "tT",  "v": 5,  "u": "Cel" }
    ]
}

When dealing with multiple entries with different time stamps, such as:

[ "2015-06-16T00:01:17Z", "", {"@":"4b62","+":7,"vac|h":74,"v|%":0,"tT|C":5} ]
[ "2015-06-16T00:01:39Z", "", {"@":"6363","+":3,"vac|h":26,"v|%":0,"tT|C":7} ]
[ "2015-06-16T00:02:39Z", "", {"@":"6363","+":4,"vC|%":328,"T|C16":329,"O":1} ]

We could move the device ID to the "n" attribute:

{
    "bn": "urn:dev:id:12345678/",
    "bt": 1433894477,
    "e": [
        { "n": "4b62/+",   "v": 7,  "t": 0 },
        { "n": "4b62/vac", "v": 74, "t": 0, "u": "h" },
        { "n": "4b62/v",   "v": 0,  "t": 0, "u": "%" },
        { "n": "4b62/tT",  "v": 5,  "t": 0, "u": "Cel" },
        { "n": "6363/+",   "v": 3,  "t": 22 },
        { "n": "6363/vac", "v": 26, "t": 22, "u": "h" },
        { "n": "6363/v",   "v": 0,  "t": 22, "u": "%" },
        { "n": "6363/tT",  "v": 7,  "t": 22, "u": "Cel" },
        { "n": "6363/+",   "v": 4,  "t": 22 },
        { "n": "6363/vC",  "v": 328, "t": 22, "u": "%" },
        { "n": "6363/T",   "v": 20.5625, "t": 22, "u": "Cel" },
        { "n": "6363/O",   "v": 1,  "t": 22 }
    ]
}

Or when dealing with multiple entries for a single sensor:

{
    "bn": "urn:dev:id:12345678/4b62/tT",
    "bt": 1433894477,
    "bu": "Cel",
    "e": [
        { "v": 5, "t": 0 },
        { "v": 6, "t": 5 }
    ]
}

Note on units: SenML support a limited number of units as standard. However,
those units can be extended by using any unit in the UCUM standard[3] by
prefixing the name with "UCUM:". This has an implication for non-standard
units such as C16 that should be transformed into a standard unit.

Note on my notes: I didn't convert the "h" unit as I can't remember what it is.

Note on timestamps: they are formatted as an integer that is the number of
seconds in the UNIX epoch. If using this format, we should ensure that those
values are always in the UTC time zone.

## HyperCat catalogue ##

HyperCat adds catalogue capability on top of the data at a well known URL for
a particular service. That URL has a top level catalogue that points to other
catalogues. So for example, the following catalogue has one sub-catalogue for
devices:

{
  "item-metadata": [
    {
      "rel": "urn:X-tsbiot:rels:isContentType",
      "val": "application/vnd.tsbiot.catalogue+json"
    },
    {
      "rel": "urn:X-tsbiot:rels:hasDescription:en",
      "val": "all catalogues"
    }
  ],
  "items": [
    {
      "href": "/cats/devices",
      "i-object-metadata": [
        {
          "rel": "urn:X-tsbiot:rels:isContentType",
          "val": "application/vnd.tsbiot.catalogue+json"
        },
        {
          "rel": "urn:X-tsbiot:rels:hasDescription:en",
          "val": "Devices"
        }
      ]
    }
  ]
}

And that sub-catalogue lists the sensors:

{
  "item-metadata": [
    {
      "rel": "urn:X-tsbiot:rels:isContentType",
      "val": "application/vnd.tsbiot.catalogue+json"
    },
    {
      "rel": "urn:X-tsbiot:rels:hasDescription:en",
      "val": "Devices"
    }
  ],
  "items": [
    {
      "href": "https://config28.flexeye.com/v1/iot_Default/dms/Eseye_DM/devices/Device_1131",
      "i-object-metadata": [
        {
          "rel": "urn:X-tsbiot:rels:hasDescription:en",
          "val": "Funky sensor"
        },
        {
          "rel": "http://purl.oclc.org/NET/ssnx/ssn#SensingDevice",
          "val": "Sensor"
        },
        {
          "rel": "urn:X-tsbiot:rels:isContentType",
          "val": "application/json"
        },
        {
          "rel": "urn:X-senml:u",
          "val": "https://config28.flexeye.com/v1/iot_Default/dms/Eseye_DM/devices/Device_1131/senML/json"
        },
        {
          "rel": "http://www.loa-cnr.it/ontologies/DUL.owl#hasLocation",
          "val": "https://config28.flexeye.com/v1/iot_Default/applications/eyeHack"
        }
      ]
    }
  ]
}

Note that there may be several levels of catalogues and that the leaf catalogue
tends to list individual sensors on a single leaf node. The hierarchy of
catalogues could be something like:

/cats/concentrator/XXX/device/YYY/sensors/

Or

/cats/device/XXX/YYY/sensors/

We should also include in the "i-object-metadata" structure important
information such as unit, metric, name, etc. Some of those may be repeated in
the SenML data but are useful in the catalogue to enable filtering.
One option at the catalogue level, rather than specify the unit, would be to
specify the metric (e.g. "temperature" rather than "°C") as this is enough
for a platform to understand haw to handle the sensor, assuming it can handle
all units in that metric.

EnergyDeck will probably have a catalogue URL that follows the following
pattern (this will be confirmed during implementation):

/cats                               | root catalogue of catalogues
/cats/assets                        | catalogue of assets
/cats/metering-points               | catalogue of metering points across all assets
/cats/asset/x                       | catalogue of catalogues for asset x
/cats/asset/x/assets                | sub-catalogue of assets for asset x
/cats/asset/x/metering-points       | catalogue of metering points (~devices) attached to an asset
/cats/asset/x/metering-point/y      | catalogue of catalogues for MP y associated with asset x
/cats/metering-point/y              | ... with direct access shortcut
/cats/metering-point/y/linked       | catalogue of MPs related to MP y
/cats/metering-point/y/series       | catalogue of data series for MP y
/cats/metering-point/y/series/z/    | catalogue of catalogues for series z in MP y
/cats/metering-point/y/series/z/raw | raw data points for series z in MP y
/cats/metering-point/y/series/z/1m  | data points at 1 minute granularity
/cats/metering-point/y/series/z/30m | data points at 30 minute granularity
/cats/metering-point/y/series/z/1Y  | data points at 1 year granularity

## References ##

[1] http://www.hypercat.io/
[2] https://tools.ietf.org/id/draft-jennings-senml-10.txt
[3] http://unitsofmeasure.org/ucum.html