Sensor library

Overview

The sensor library defines a canonical set of predefined sensor and control capabilities. A sensor capability describes the part of a device that can measure some quantity, while a control capability describes the part of a device that can be modified, changed or in some way remotely controlled.

The library is logically divided into subpackages related to the domain that the capability fits best, although applications are free to select capabilities from any domain. The name of the capability follows the naming conventions of fragments. There are Java representations of each of these capabilities that can be found in the Java packages corresponding to the fragment names.

Environmental capabilities

Environmental capabilities include sensors that measure properties of the environment such as temperature, humidity and wind speed.

c8y_TemperatureSensor

A temperature sensor reports the temperature in degrees Celsius (C). In a managed object, a temperature sensor is modeled as a simple empty fragment:

"c8y_TemperatureSensor" : {}

c8y_TemperatureMeasurement

Measurement Units Description
T C Measured temperature. 
"c8y_TemperatureMeasurement": {
    "T": { "value": 23, "unit": "C" }
}

c8y_MotionSensor

A motion sensor detects motion. Simple motion sensors may just detect if there is motion or not, based on some predefined threshold. More complicated motion sensors (such as police speed radars) can measure the actual speed of the motion. It is assumed in the model that only the speed towards or away from the sensor is measured. The unit for this sensor type are kilometers per hour (km/h). In a managed object, a motion sensor is modeled as a simple empty fragment:

"c8y_MotionSensor" : {}

c8y_MotionMeasurement

Measurement Units Description
motionDetected none Boolean value indicating if motion has been detected (non-zero value) or not (zero value).
speed km/h Measured speed towards (+ve) or away (-ve) from the sensor.
"c8y_MotionMeasurement": {
  "motionDetected": { "value": 1.0, "unit": "", "type": "BOOLEAN" },
  "speed": { "value": -63.2, "unit": "km/h" }
}

c8y_AccelerationSensor

An acceleration sensor, or accelerometer, is a device that measures acceleration along an axis. This sensor model does not define the direction of that axis. The units for this sensor type are meters per second per second (m/s2). In a managed object, an acceleration sensor is modeled as a simple empty fragment:

"c8y_AccelerationSensor" : {}

c8y_AccelerationMeasurement

Measurement Units Description
acceleration m/s2 Measured acceleration along the sensor axis (direction of the sensor axis is not defined in this measurement).
"c8y_AccelerationMeasurement": {
  "acceleration": { "value": 8.36, "unit": "m/s2" }
}

c8y_LightSensor

A light sensor measures the intensity of light. In a managed object, a light sensor is modeled as a simple empty fragment:

"c8y_LightSensor" : {}

c8y_LightMeasurement

Light is measured with two main alternative sets of units: radiometry consists of measurements of light power at all wavelengths, while photometry measures light with wavelength weighted with respect to a standardized model of human brightness perception. Photometry is useful, for example, to quantify illumination (lighting) intended for human use.

Measurement Units Description
e lux Photometrical light measurement
"c8y_LightMeasurement": {
    "e": { "value": 8.36, "unit": "lux" }
}

c8y_HumiditySensor

A humidity sensor measures the amount of water vapour in the air. In a managed object, a humidity sensor is modeled as a simple empty fragment:

"c8y_HumiditySensor" : {}

c8y_HumidityMeasurement

There are three main measurements of humidity: absolute, relative and specific. Absolute humidity is the water content of air. Relative humidity, expressed as a percentage, measures the current absolute humidity relative to the maximum for that temperature. Specific humidity is a ratio of the water vapour content of the mixture to the total air content on a mass basis.

Measurement Units Description
h %RH Relative humidity measurement
"c8y_HumidityMeasurement" : {
  "h" : { "value" : 13.37, "unit": "%RH"}
}

c8y_MoistureSensor

A moisture sensor measures the water content of a substance. In a managed object, a moisture sensor is modeled as a simple empty fragment:

"c8y_MoistureSensor" : {}

c8y_MoistureMeasurement

There are three main measurements of moisture: absolute, relative and specific. Absolute moisture is the absolute water content of a substance. Relative moisture, expressed as a percentage, measures the current absolute moisture relative to the maximum for that temperature. Specific humidity is a ratio of the water vapour content of the mixture to the total substance content on a mass basis.

Measurement Units Description
moisture % Relative moisture measurement
"c8y_MoistureMeasurement" : {
  "moisture" : { "value" : 13.37, "unit" : "%" }
}

c8y_DistanceSensor

A distance sensor measures the distance between itself and the closest object in a certain direction. In a managed object, a distance sensor is modeled as a simple empty fragment:

"c8y_DistanceSensor" : {}

c8y_DistanceMeasurement

Measurement Units Description
distance mm Distance measurement
"c8y_DistanceMeasurement" : {
  "distance" : { "value" : 13.37, "unit" : "mm" }
}

Energy

Electricity sensor

At the most basic level electricity sensors (electricity meters, watt-hour meters) measure energy consumption (usually measured in kWh), however they can measure much more depending on their complexity, such as “demand”, or instantaneous power (usually measured in W), reactive power, harmonic distortion, and more. Meters can measure for a single phase (typical just for home usage) or for three phases.

c8y_SinglePhaseElectricitySensor

In a managed object, a single phase electricity meter is modeled as a simple empty fragment:

"c8y_SinglePhaseElectricitySensor" : {}

c8y_SinglePhaseEnergyMeasurement

Measurement Units Description
A+ kWh Total active energy, in
A- kWh Total active energy, out
P+ W Total active power, in
P- W Total active power, out
"c8y_SinglePhaseEnergyMeasurement": {
  "A+": { "value": 123, "unit": "kWh" },
  "A-": { "value": 2, "unit": "kWh" },
  "P+": { "value": 56, "unit": "W" },
  "P-": { "value": 0, "unit": "W" }
}

c8y_ThreePhaseElectricitySensor

In a managed object, a three phase electricity meter is modeled as a simple empty fragment:

"c8y_ThreePhaseElectricitySensor" : {}

c8y_ThreePhaseEnergyMeasurement

Measurement Units Description
A+ kWh Total active energy in, summed across phases
A+:1(2, 3) kWh Active energy in for phase 1, 2 or 3
A- kWh Total active energy out, summed across phases
A-:1(2, 3) kWh Active energy out for phase 1, 2, 3
P+ W Total active power in, summed across phases
P+:1(2, 3) W Active power in for phase 1, 2 or 3
P-:1(2, 3) W Active power out for phase 1, 2 or 3
Ri+ kVArh Total reactive inductive energy, in
Ri- kVArh Total reactive inductive energy, out
Rc+ kVArh Total reactive capacitive energy, in
Rc- kVArh Total reactive capacitive energy, out
Qi+ kVAr Total reactive inductive power, in
Qi- kVAr Total reactive inductive power, out
Qc+ kVAr Total reactive capacitive power, in
Qc- kVAr Total reactive capacitive power, out
"c8y_ThreePhaseEnergyMeasurement": {
  "A+": { "value": 435, "unit": "kWh" },
  "A-": { "value": 23, "unit": "kWh" },
  "P+": { "value": 657, "unit": "W" },
  "P-": { "value": 0, "unit": "W" },
  "A+:1": { "value": 123, "unit": "kWh" },
  "A-:1": { "value": 2, "unit": "kWh" },
  "P+:1": { "value": 56, "unit": "W" },
  "P-:1": { "value": 0, "unit": "W" },
  "A+:2": { "value": 231, "unit": "kWh" },
  "A-:2": { "value": 23, "unit": "kWh" },
  "P+:2": { "value": 516, "unit": "W" },
  "P-:2": { "value": 2, "unit": "W" },
  "A+:3": { "value": 1423, "unit": "kWh" },
  "A-:3": { "value": 422, "unit": "kWh" },
  "P+:3": { "value": 16, "unit": "W" },
  "P-:3": { "value": 9, "unit": "W" },
  "Ri+": { "value": 231, "unit": "kVArh" },
  "Ri-": { "value": 23, "unit": "kVArh" },
  "Rc+": { "value": 342, "unit": "kVArh" },
  "Rc-": { "value": 43, "unit": "kVArh" },
  "Qi+": { "value": 234, "unit": "kVAr" },
  "Qi-": { "value": 645, "unit": "kVAr" },
  "Qc+": { "value": 76, "unit": "kVAr" },
  "Qc-": { "value": 34, "unit": "kVAr" }
}

c8y_CurrentSensor

A current sensor measures the current flowing through it. In a managed object, a current sensor is modeled as a simple empty fragment:

"c8y_CurrentSensor" : {}

c8y_CurrentMeasurement

Measurement Units Description
current A Current measurement
"c8y_CurrentMeasurement" : {
  "current" : { "value" : 13.37, "unit" : "A" }
}

c8y_VoltageMeasurement

A voltage sensor measures the voltage difference between two points in an electric circuit.

Measurement Units Description
voltage V Voltage measurement
"c8y_VoltageMeasurement" : {
  "voltage" : { "value" : 13.37, "unit" : "V" }
}

Location capabilities

c8y_Position

c8y_Position reports the geographical location of an asset in terms of latitude, longitude and altitude. Altitude is given in meters. To report the current location of an asset or a device, c8y_Position is added to the managed object representing the asset or device. To trace the position of an asset or a device, c8y_Position is sent as part of an event of type c8y_LocationUpdate.

"c8y_Position": {
  "alt": 67,
  "lng": 6.15173,
  "lat": 51.211977,
  "trackingProtocol" : "TELIC",
  "reportReason" : "Time Event"
}

The properties trackingProtocol and reportReason are used by a tracker agent and describe the tracking context of a positioning report: why the report was sent and in which protocol.

Info: Sending the c8y_LocationUpdate event does not update the location fragment on the managed object as opposed to SmartREST template 402 which does both.

Common capabilities

c8y_Relay

A relay is a kind of binary state switch which can be in the states OPEN or CLOSED. Relays can be used for many purposes, for example to connect or disconnect the consumer power supply through a smart energy meter. In a managed object, a relay control model includes the state of the control. When the control state changes, the inventory model should be updated to include the new state:

"c8y_Relay": {
  "relayState" : "OPEN"
}

Operations

Operation States Description
state OPEN, CLOSED OPEN commands the relay into the open position, CLOSED commands it to the closed position

The operation representation is the same as the inventory representation:

"c8y_Relay": {
  "relayState" : "OPEN"
}

c8y_RelayArray

The c8y_RelayArray operation provides the functionality to control multiple relays. In a managed object, the control model of an array of relays includes the state of each relay. When the state changes, the inventory model should be replaced with the new state:

"c8y_RelayArray" : [
  "OPEN",
  "CLOSED",
  "CLOSED",
  "OPEN"
]

Operations

The operation representation is the same as the inventory representation:

"c8y_RelayArray" : [
  "OPEN",
  "CLOSED",
  "CLOSED",
  "OPEN"
]