Device

Description

An apparatus (hardware + software + firmware) intended to accomplish a particular task (sensing the environment, actuating, etc.). A Device is a tangible object which contains some logic and is producer and/or consumer of data. A Device is always assumed to be capable of communicating electronically via a network.

This data model has been partially developed in cooperation with mobile operators and the GSMA.

This data model reuses concepts coming from the SAREF Ontology part of ETSI standards.

Data Model

The data model is defined as shown below:

  • id : Unique identifier.

  • type : Entity type. It must be equal to Device.

  • source : A sequence of characters giving the source of the entity data.

    • Attribute type: Property. Text or URL
    • Optional
  • dataProvider : Specifies the URL to information about the provider of this information

    • Attribute type: Property. URL
    • Optional
  • category : See attribute category from DeviceModel. Optional but recommended to optimize queries.

  • controlledProperty : See attribute controlledProperty from DeviceModel. Optional but recommended to optimize queries.

  • controlledAsset : The asset(s) (building, object, etc.) controlled by the device.

    • Attribute type: Property. List of Text or Reference(s) to another entity.
    • Optional
  • mnc : This property identifies the Mobile Network Code (MNC) of the network the device is attached to. The MNC is used in combination with a Mobile Country Code (MCC) (also known as a "MCC / MNC tuple") to uniquely identify a mobile phone operator/carrier using the GSM, CDMA, iDEN, TETRA and 3G / 4G public land mobile networks and some satellite mobile networks.

    • Attribute type: Property. Text
    • Optional
  • mcc : Mobile Country Code - This property identifies univoquely the country of the mobile network the device is attached to.

    • Attribute type: Property. Text
    • Optional
  • macAddress : The MAC address of the device.

    • Attribute type: Property. List of Text
    • Optional
  • ipAddress : The IP address of the device. It can be a comma separated list of values if the device has more than one IP address.

    • Attribute type: Property. List of Text
    • Optional
  • supportedProtocol : See attribute supportedProtocol from DeviceModel. Needed if due to a software update new protocols are supported. Otherwise it is better to convey it at DeviceModel level.

  • configuration : Device's technical configuration. This attribute is intended to be a dictionary of properties which capture parameters which have to do with the configuration of a device (timeouts, reporting periods, etc.) and which are not currently covered by the standard attributes defined by this model.

    • Attribute type: Property. StructuredValue
    • Attribute metadata:
      • dateModified : Last update timestamp of this attribute.
        • Metadata type: DateTime
        • Read-Only. Automatically generated.
    • Optional
  • location : Location of this device represented by a GeoJSON geometry of type point.

  • name : A mnemonic name given to the device.

    • Normative References: name
    • Optional
  • description : Device's description.

  • dateInstalled : A timestamp which denotes when the device was installed (if it requires installation).

    • Attribute type: Property. DateTime
    • Optional
  • dateFirstUsed : A timestamp which denotes when the device was first used.

    • Attribute type: Property. DateTime
    • Optional
  • dateManufactured : A timestamp which denotes when the device was manufactured.

    • Attribute type: Property. DateTime
    • Optional
  • hardwareVersion : The hardware version of this device.

    • Attribute type: Property. Text
    • Optional
  • softwareVersion : The software version of this device.

    • Attribute type: Property. Text
    • Optional
  • firmwareVersion : The firmware version of this device.

    • Attribute type: Property. Text
    • Optional
  • osVersion : The version of the host operating system device.

    • Attribute type: Property. Text
    • Optional
  • dateLastCalibration : A timestamp which denotes when the last calibration of the device happened.

    • Attribute type: Property. DateTime
    • Optional
  • serialNumber : The serial number assigned by the manufacturer.

  • provider : The provider of the device.

  • refDeviceModel : The device's model.

    • Attribute type: Property. Reference to an entity of type DeviceModel.
    • Optional
  • batteryLevel : Device's battery level. It must be equal to 1.0 when battery is full. 0.0 when battery ìs empty. -1 when transiently cannot be determined.

    • Type: Number
    • Allowed values: Interval [0,1] or -1
    • Attribute metadata:
      • timestamp: Timestamp when the last update of the attribute happened. This value can also appear as a FIWARE TimeInstant
    • Optional
  • rssi : Received signal strength indicator for a wireless enabled device. It must be equal to 1.0 when the signal strength is maximum. 0.0 when signal is missing. -1.0 when it cannot be determined.

    • Type: Number
    • Allowed values: Interval [0,1] and -1
    • Attribute metadata:
      • timestamp: Timestamp when the last update of the attribute happened. This value can also appear as a FIWARE TimeInstant
    • Optional
  • deviceState : State of this device from an operational point of view. Its value can be vendor dependent.

    • Type: Text
    • Attribute metadata:
      • timestamp: Timestamp when the last update of the attribute happened. This value can also appear as a FIWARE TimeInstant
    • Optional
  • dateLastValueReported : A timestamp which denotes the last time when the device successfully reported data to the cloud.

    • Attribute type: Property. DateTime
    • Optional
  • value : A observed or reported value. For actuator devices, it is an attribute that allows a controlling application to change the actuation setting. For instance, a switch device which is currently on can report a value "on"of type Text. Obviously, in order to toggle the referred switch, this attribute value will have to be changed to "off".

    • Attribute type: Property. Any type, depending on the device. Usually Text or QuantitativeValue.
    • Attribute metadata:
      • timestamp: Timestamp when the last update of the attribute happened. This value can also appear as a FIWARE TimeInstant
    • Optional
  • dateModified : Last update timestamp of this entity.

    • Attribute type: Property. DateTime
    • Read-Only. Automatically generated.
  • dateCreated : Entity's creation timestamp.

    • Attribute type: Property. DateTime
    • Read-Only. Automatically generated.
  • owner : The owners of a Device.

    • Attribute type: Property. List of references to Person or Organization or List of URIs.
    • Optional

Note: JSON Schemas are intended to capture the data type and associated constraints of the different Attributes, regardless their final representation format in NGSI(v2, LD).

Examples

Normalized Example

Normalized NGSI response

{
    "id": "device-9845A",
    "type": "Device",
    "category": {
        "value": ["sensor"]
    },
    "batteryLevel": {
        "value": 0.75
    },
    "dateFirstUsed": {
        "type": "DateTime",
        "value": "2014-09-11T11:00:00Z"
    },
    "controlledAsset": {
        "value": ["wastecontainer-Osuna-100"]
    },
    "serialNumber": {
        "value": "9845A"
    },
    "mcc": {
        "value": "214"
    },
    "value": {
        "value": "l%3D0.22%3Bt%3D21.2"
    },
    "refDeviceModel": {
        "type": "Relationship",
        "value": "myDevice-wastecontainer-sensor-345"
    },
    "rssi": {
        "value": 0.86
    },
    "controlledProperty": {
        "value": ["fillingLevel", "temperature"]
    },
    "owner": {
        "value": ["http://person.org/leon"]
    },
    "mnc": {
        "value": "07"
    },
    "ipAddress": {
        "value": ["192.14.56.78"]
    },
    "deviceState": {
        "value": "ok"
    }
}

key-value pairs Example

Sample uses simplified representation for data consumers ?options=keyValues

    {
        "id": "device-9845A",
        "type": "Device",
        "category": ["sensor"],
        "controlledProperty": ["fillingLevel""temperature"],
        "controlledAsset":["wastecontainer-Osuna-100"],
        "ipAddress": ["192.14.56.78"],
        "mcc": "214",
        "mnc": "07",
        "batteryLevel": 0.75,
        "serialNumber": "9845A",
        "refDeviceModel":"myDevice-wastecontainer-sensor-345",
        "rssi": 0.86,
        "value": "l=0.22;t=21.2",
        "deviceState": "ok",
        "dateFirstUsed": "2014-09-11T11:00:00Z",
        "owner": ["http://person.org/leon"]
    }

LD Example

Sample uses the NGSI-LD representation

{
    "id": "urn:ngsi-ld:Device:device-9845A",
    "type": "Device",
    "category": {
        "type": "Property",
        "value": ["sensor"]
    },
    "batteryLevel": {
        "type": "Property",
        "value": 0.75
    },
    "dateFirstUsed": {
        "type": "Property",
        "value": {
            "@type": "DateTime",
            "@value": "2014-09-11T11:00:00Z"
        }
    },
    "controlledAsset": {
        "type": "Relationship",
        "object": ["urn:ngsi-ld::wastecontainer-Osuna-100"]
    },
    "serialNumber": {
        "type": "Property",
        "value": "9845A"
    },
    "mcc": {
        "type": "Property",
        "value": "214"
    },
    "value": {
        "type": "Property",
        "value": "l%3D0.22%3Bt%3D21.2"
    },
    "refDeviceModel": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:DeviceModel:myDevice-wastecontainer-sensor-345"
    },
    "rssi": {
        "type": "Property",
        "value": 0.86
    },
    "controlledProperty": {
        "type": "Property",
        "value": ["fillingLevel", "temperature"]
    },
    "owner": {
        "type": "Property",
        "value": ["http://person.org/leon"]
    },
    "mnc": {
        "type": "Property",
        "value": "07"
    },
    "ipAddress": {
        "type": "Property",
        "value": ["192.14.56.78"]
    },
    "deviceState": {
        "type": "Property",
        "value": "ok"
    },
    "@context": [
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld",
        "https://schema.lab.fiware.org/ld/context"
    ]
}

N.B.: This example to work in Orion Context Broker implementation of NGSI v2, requires that value attribute is URL Encoded. As documented here = is a forbidden character.

Test it with a real service

T.B.D.

Issues

  • Is function really needed?
  • Do we need a state attribute as it happens in SAREF?
  • Check consistency with oneM2M and SAREF ontologies.