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_SpeedMeasurement
| 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_SpeedMeasurement": {
"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"
]