Labels and Selectors

Labels can be attached to objects, such as devices. Labels are intended to be used to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system. Labels can be used to organize and to select subsets of objects. Labels can be attached to objects at creation time and subsequently added and modified at any time.

Device with labels

"device": {
  "name" : "IoT Device 1",
  "labels": [
    "Label 1",
    "My Label 2",
    "IoT Roomsensors",
    "IoT Tracking Sensors"
  ]
}
JS

Motivation

Labels enable users to map their own organizational structures onto objects like devices in a loosely coupled fashion, without requiring clients to store these mappings.

In IoT application often multi-dimensional entities will need to be added to objects. For example device properties like the sensors it support, it´s connectivity or meta informations related to it´s installation location.

Examples for device labeling:

  • Labeling by build-in sensors: "temperature", "humidity" or "Has Temperatur Sensor"
  • Labeling vy device connectivity: "lorawan", "bluetooth" or "LoRaWAN Connectivity"
  • Labeling by firmware aspects: "firmware 1.0.2", "Firmware 2.1.0" or just "1.0.2"

These are just examples of commonly used labels; you are free to develop your own conventions.

Valid label names

The name is required and must be 120 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]). In between the start and the end character any other alphanumeric character ([a-z0-9A-Z]), dashes (-), underscores (_), dots (.) and space(s) can be used. The labels name have to be at least 3 characters long.

Example names 

Valid namesconnectivityLoRaWANLoRa-WAN1.11.0.2 Firmwaresensors.temperaturlora1-0
Invalid names:sensor_labelTürsensor传感器My传感器

Objects allowing to attach label

The following list does show all objects which allow to use labels:

  • devices

Label selectors

Unlike ids, labels do not provide uniqueness. In general, we expect many objects like devices to carry the same label(s).

Via a label selector, integrations can identify a set of objects (=devices). The label selector is the core grouping primitive in thingsHub. Per default the selector will combine multiple labels by an logical OR.

An empty label selector (that is, one with zero requirements) selects NO object and will lead to a integration which will not export / expose any data.


Selector Examples

The following four devices are given:


Device 1Device 2Device 3Device 4
Labels
"labels": [
  "temperature",
  "humidity",
  "lorawan",
  "loriot-connector"
]
CODE
"labels": [
  "temperature",
  "lorawan"
]
CODE
"labels": [
  "lorawan",
  "firmware 1.0.2"
]
CODE
"labels": [
  "humidity",
  "lorawan",
  "bluetooth",
  "firmware 2.0.0"
]
CODE

Using the following selector for an integration will lead to the following results:

SelectorResultTranslates logically into SQL statement
"selector": {
  "$or":[
    "lorawan"
  ]
}
CODE
  • Device 1
  • Device 2
  • Device 3
  • Device 4

SELECT * FROM devices

WHERE label = "lorawan"

"selector": {
  "$or":[
    "lorawan",
    "firmware 1.0.2"
  ]
}
CODE
  • Device 1
  • Device 3

SELECT * FROM devices

WHERE label = "lorawan" OR label = "firmware 1.0.2"

"selector": {
  "$or":[
    "manufacturer nke-watteco"
  ]
}
CODE
  • None of the example devices

SELECT * FROM devices

WHERE label = "manufacturer nke-watteco"

COMING Q1/2019: LABEL SETS
Not available at present


"selector": {
  "$or":[
    ["temperature","firmware 1.0.2"],
      ["humidity","firmware 2.0.0","lorawan"]
  ]
}
CODE
  • Device 1
  • Device 4

SELECT * FROM devices

WHERE (label = "temperature" AND label = "firmware 1.0.2")
OR (label = "humidity" AND label = "firmware 2.0.0" AND label = "lorawan")