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

  • id : Unique identifier.

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

  • 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: 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: Text
    • Optional
  • mcc : Mobile Country Code - This property identifies univoquely the country of the mobile network the device is attached to.

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

    • Attribute type: 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: 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: StructuredValue
    • Attribute metadata:
      • dateModified : It captures the last modification timestamp of this attribute.
    • 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).

  • dateFirstUsed : A timestamp which denotes when the device was first used.

  • dateManufactured : A timestamp which denotes when the device was manufactured.

  • hardwareVersion : The hardware version of this device.

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

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

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

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

  • serialNumber : The serial number assigned by the manufacturer.

  • provider : The provider of the device.

  • refDeviceModel : The device's model.

    • Attribute type: 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. null when cannot be determined.

    • Type: Number
    • Allowed values: Interval [0,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.

  • 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: 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.

  • dateCreated : Entity's creation timestamp.

  • owner : The owners of a Device.

Note: JSON Schemas only capture the NGSI simplified representation, this means that to test the JSON schema examples with a FIWARE NGSI version 2 API implementation, you need to use the keyValues mode (options=keyValues).

Examples

{
  "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",
  "value": "l=0.22;t=21.2",
  "deviceState": "ok",
  "dateFirstUsed": "2014-09-11T11:00:00Z",
  "owner": ["http://person.org/leon"]
}

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.