Sensor library

The sensor library defines a canonical set of predefined sensor and control capabilities. A sensor capability describes that part of a device that can measure some quantity, and a control capability describes that 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 to which that capability best fits, although applications a free to select capabilities from any domain. The name of the capability follows the Fragment naming convention. 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, wind speed, etc.

Temperature Sensor

A temperature sensor reports temperature in degrees Celsius (C).

Inventory representation

In a managed object, a temperature sensor is modelled as a simple empty fragment:

"c8y_TemperatureSensor" : {}

Measurement

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

Motion Sensor

A motion sensor detects motion. Simple motion sensors may just detect if there is, or is not motion based on some predefined threshold, whereas 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 untis for this sensor type are kilometres per hour (km/h).

Inventory representation

In a managed object, a motion sensor is modelled as a simple empty fragment:

"c8y_MotionSensor" : {}

Measurement

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" }
  }

Acceleration Sensor

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 untis for this sensor type are metres per second per second (m/s2).

Inventory representation

In a managed object, an acceleration sensor is modelled as a simple empty fragment:

"c8y_AccelerationSensor" : {}

Measurement

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" }
}

Light Sensor

I light sensor measures the intensity of light.

Inventory representation

In a managed object, a light sensor is modelled as a simple empty fragment:

"c8y_LightSensor" : {}

Measurement

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 standardised 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" }
}

Humidity Sensor

A humidity sensor measures the amount of water vapour in the air.

Inventory representation

In a managed object, a humidity sensor is modelled as a simple empty fragment:

"c8y_HumiditySensor" : {}

Measurement

There are three main measurements of humidity: absolute, relative and specific. Absolute humidity is the water content of air. Relative humidity, expressed as a percent, 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"}
}

Moisture Sensor

A moisture sensor measures the water content of a substance.

Inventory representation

In a managed object, a moisture sensor is modelled as a simple empty fragment:

"c8y_MoistureSensor" : {}

Measurement

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 percent, 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" : "%" }
}

Distance Sensor

A distance sensor measures the distance between itself and the closest object in certain direction.

Inventory representation

In a managed object, a distance sensor is modelled as a simple empty fragment:

"c8y_DistanceSensor" : {}

Measurement

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 (aka Electricity Meters, Watt-hour meters) measure energy consumption (usually measured in kWh), however they can measure much more depending upon their complexity, such as “demand”, or instantaneous power (usually measured in W), reactive power, harmonic distortion, etc. Meters can measure for a single phase (typical just for home usage) or for three phases.

Inventory representation - Single Phase Meter

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

"c8y_SinglePhaseElectricitySensor" : {}

Measurement - Single Phase Meter

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_SinglePhaseElectricityMeasurement": {
  "A+": { "value": 123, "unit": "kWh" },
  "A-": { "value": 2, "unit": "kWh" },
  "P+": { "value": 56, "unit": "W" },
  "P-": { "value": 0, "unit": "W" }
}

Inventory representation - Three Phase Meter

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

"c8y_ThreePhaseElectricitySensor" : {}

Measurement - Three Phase Meter

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_ThreePhaseElectricityMeasurement": {
  "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" }
}

Current sensor

A current sensor measures the current flowing through it.

Inventory representation

In a managed object, a current sensor is modelled as a simple empty fragment:

"c8y_CurrentSensor" : {}

Measurement

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

Voltage sensor

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

Measurement

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

Location Capabilities

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"
}

Properties “trackingProtocol” and “reportReason” are used by tracker agent and describes tracking context of positioning report: why the report was sent and in which protocol.

Common Capabilities

Relay Control

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.

Inventory representation

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 in to the open position, CLOSED commands it to the closed position.

The operation representation is the same as the inventory representation:

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

Control an Array of Relays

The c8y_RelayArray operation provides the functionality to control multiple relays.

Inventory representation

In a managed object, an array of relays' control model 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"
]

Mobile information

c8y_Mobile holds the information about the mobile connection status (e.g. cell information) and the sim card (e.g. ICCID) of the device. Whenever the status changes the fragment in the device should be updated. The assumption for not moving devices is that these values rarely change. For more frequently changing mobile information (e.g. signal strength) a measurement can be used.

Inventory representation

"c8y_Mobile" : {
  "imsi": "..."
  "imei": "..."
  "currentOperator": "..."
  "currentBand": "..."
  "connType": "..."
  "rssi": "..."
  "ecn0": "..."
  "rcsp": "..."
  "mnc": "..."
  "lac": "..."
  "cellId": "..."
  "msisdn": "..."
  "iccid": "..."
}

Measurement

Measurement Units Description
rssi dBm RSSI measurement
"c8y_SignalStrength": {
  "rssi": {
    "unit": "dBm",
    "value": -63
  }
}