We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FIWARE.OpenSpecification.IoT.Backend.DeviceManagement R5 - FIWARE Forge Wiki

FIWARE.OpenSpecification.IoT.Backend.DeviceManagement R5

From FIWARE Forge Wiki

Jump to: navigation, search
Name FIWARE.OpenSpecification.IoT.Backend.DeviceManagement
Chapter IoT Services Enablement,
Catalogue-Link to Implementation IDAS
Owner Telefonica I+D, Carlos Ralli



Within this document you find a self-contained open specification of a FIWARE generic enabler, please consult as well the FIWARE Product Vision, the website on http://www.fiware.org and similar pages in order to understand the complete context of the FIWARE platform.


Legal Notice

Please check the following Legal Notice to understand the rights to use these specifications.


The Backend Device Management GE is normally the central enabler at the IoT backend for most common scenarios.

Basically, it provides the following features:

  • Connect physical devices to a FIWARE platform. Devices and/or gateways may use different standard or propietary communication protocols and APIs. The following sections provide details on currently/planned supported protocols, how to configure and scale up the translators (IoT-Agents) plus information on extensibility.
  • Manages IoT-related NGSI Context Entities. It handles the connection (northbound) to a FIWARE NGSI Broker to create one Context Entity per physical connected device. For most cases, FIWARE Application developers will only interact with those NGSI Entities. On the other hand, IoT integrators will also interact with the devices' ADMIN API and the devices' protocols APIs.
  • IoT Edge Management. This functionality is provided within the "IoT Manager" module, which has been delivered in FIWARE Release 5. It provides IoT Integrators with the ability of transforming devices specific Data Models into the Data Models defined at the NGSI level by different verticals (Smartcities, SmartAgrifood, Smartports, etc.). In the future it will also help on the configuration, operation and monitoring of IoT end-nodes, IoT Gateways and IoT networks.

The following diagram depicts its overall planned architecture.

Main Components

IoT Agents

The IoT Agents are the software modules handling South IoT Specific protocols and North OMA NGSI interaction. The minimum configuration of a Backend Device Management GE in a FIWARE ecosystem includes at least one IoT Agent.

IoT Agents must:

  • Handle the creation of an NGSI Context Entity in a ContextBroker (at its northbound) per each one of the connected IoT Devices.
  • Act as Context Producer for those attributes related to sensing capabilities or observations.
  • Provide an Administration/Configuration API.

IoT Agents may:

  • Perform Commands triggering whenever a developer updates specific attributes in a Northbound ContextBroker. In this case, the IoT Agent will register itself and play the role of Context Provider of those specific actuation attributes. If this functionality is not provided, the IoT Agent must implement an API to receive commands and deliver them to devices.

Currently, the following IoT Agents are specified in the roadmap:

  • UL2.0. Ultralight2.0 is an open specification for devices semantics (capabilities, observations, commands). This IoT Agent handles devices using this representation over HTTP or MQTT topics and over IPv4 or IPv6 connections. This agent exposes also an ADMIN API over HTTP and the NGSI REST API towards NGSI Brokers, both over IPv4 and IPv6.
  • JSON. This IoT Agent handles JSON objects representing devices comunications using this representation over HTTP or MQTT topics and also over IPv4 or IPv6 connections. This agent exposes also an ADMIN API over HTTP and the NGSI REST API towards NGSI Brokers, both over IPv4 and IPv6.
  • LWM2M/CoAP. This IoT Agent connects devices compliant with the ETSIM2M and OneM2M southbound proposition: OMA Lightweight M2M specification over the REST protocol for constraint devices/networks (IETF CoAP) and UDP/IPv4 or UDP/IPv6 connections. This agent exposes also an ADMIN API over HTTP and the NGSI REST API towards NGSI Brokers, both over IPv4 and IPv6.
  • Generic IoT Agent library (coded in node.js). A skeleton of a generic IoT agent is provided to help IoT integrators to cope with new standards or propietary protocols.


For some specific HW Devices/IoT-end nodes and protocols/APIs, SDKs (client/device side tools) might be optionally provided for certain Hardware platforms in order to facilitate testing and integration activities.

Those SDKs are not installed in the Backend but at the devices or gateways to be connected. However, SDKs depend on specific communciation protocols and thus specific IoT Agents, so they are provided together with them and not as IoT Edge GEs.

For FIWARE Release 4, an SDK related to Ultralight2.0/HTTP Agent is provided.

IoT Agent Manager

The IoT Agent Manager is an optional module that will interface with all the IoT Agents installed in a datacenter throughtout their Administration/Configuration API. This will enable a single point to launch, configure, operate and monitor all IoT-Agents in a FIWARE Ecosystem.

This module will be specified in FIWARE Release 5.

IoT Edge Management

The IoT Edge Manager is an optional module that will interface with IoT end-nodes, IoT Gateways and IoT network APIs throughtout their IoT Edge API in order to operate and monitor the IoT Edge insfrastructure, that means connectivity, gateways and devices.

This module will be specified in FIWARE Release 6.

Basic Concepts

The Backend Device Management GE is based on the usage of the following protocols: FIWARE NGSI, Ultralight2.0 and OMA-LWM2M.






Main Interactions

IoT Agent: Ultralight2.0/HTTP

This IoT Agent connects devices (or Gateways grouping devices) described with the open description Ultralight2.0 over the HTTP protocol.

For FIWARE Release 4 onwards commands will be triggered from specific attributes in the related NGSI Context Entity.

The following subsections detail the main interactions needed to work with this specific IoT Agent.

Service Creation

This operation is thought for private instances of the component or Admin users of the FIWARE Lab public instance.

Each tenant (customer or group of users) is expected to use a different service. This is the way this GE enables multitenancy.

A Service is tied to a shared secret, called API-KEY, that all devices (or gateways) need to know to be able to send measurements or receive commands to/from the IoT Agent.

Devices sending observations with a FIWARE-Service "S1" and FIWARE-Service-Path "PATH" headers will be represented up north in the ContextBroker as NGSI Entities with the same FIWARE-Service and FIWARE-Service-Path.

In order to create a Service, an admin will run a specific HTTP POST request. HTTP GET operation at the same URL will return the existing services.

Device Registration/Creation

Before a device sends observations it needs to be registered. This registry will include the Device ID, Entity ID, Entity type, attributes, static attributes and command parameters related to the device.

Depending on the specific service agreements, device resgistration might be carried out by an Admin, regular users or both.

To register a device, an HTTP POST request will be run.

Device Observation

Once a device is registered, observations might be sent with a simple HTTP POST request (executed from the Device or a gateway) that includes the Device ID and the API-KEY in the URL.

Device Commands

There are two ways to send UL2.0 commands: Push and Pooling modes.

  • Push commands are send to devices in a synchronous way. Therefore it assumes always-on reachable devices (or gateways) implementing an HTTP server.
  • Pooling commands are queued in the IoT Agent until a Device asks for them. The Admin APÎ implements a method to check out the status of commands addressed to a specific device.

For the case of Pooling commands, Devices (or gateways) will run an HTTP request and get the full queue of pending commands. Push devices will run an HTTP serever to synchronously receive the command once delivered to the IoT-Agent.

Administration/Configuration API

The current Admin/Config for this IoT Agent comprises the above-described Functions "Service Creation", "Device Model Creation" and "Device Register".

IoT Agent: Ultralight2.0/MQTT

To be provided in the next Architecture release.

IoT Agent: LWM2M/CoAP

This IoT Agent connects Lightweight M2M Clients (devices), communicating over COAP, to the NGSI Context Broker in the Data Chapter. In this release, the IOT Agent accepts writes to device attributes through writes in the Context Entities, but it doesn’t support full commands.

The following sections detail the main interactions with the agent (without entering in low-level details).

Device Provisioning

In order for the system to recognize the device and do the appropriate mapping to NGSI context elements, one of two things must happen: either the device is provisioned in advance into the system, or a service is provisioned in the system and the device assigned to it. In the former case, the DeviceID will be used to identify the device, using it as the Endpoint name in LWM2M. The following pieces of data can be specified in provisioning: device ID, security information, NGSI entity mappings and types of attributes provided.

Service creation

For those cases where the devices are not specified individually, services can be provisioned as a whole. A service is identified by a pair of (resource, APIKey) attributes, and can contain roughly the same kind of information as the device provisioning requests. The specified resource corresponds to a LWM2M server endpoint where the clients will send their requests (the APIKey will be used in southbound security interactions, not implemented in the first version of the Agent).

Each time a device arrives to the specified endpoint, it will be assigned to the proper service based on the endpoint.

Device Registration

Every device in LWM2M must register to the LWM2M server before starting any interaction. In this registration the LWM2M client has to indicate the following information to the server: Endpoint name (DeviceID) and supported objects (a list of links for every OMA LWM2M object that can be accesed by the server). The LWM2M server uses this information to assign the device to a service (or to retrieve the device information in case it has been individually provisioned).

Based on the service or device information, the server will decide what attributes of the objects provisioned by the device are active, lazy or commands, and it will register itself in the Context Broker as the Context Provider of those in the two last categories (lazy and commands).

For those attributes defined as active, the server will emit an Observe request (Information Reporting interface in LWM2M), indicating the desired timeout between measures to be received (using the WriteAttributes operation).

Device lazy observation

For those attributes of the devices that marked as lazy, the updates and reads of Context Entities in the Context Broker GE will be mapped to Read and Write operations from the Device Management Interface in LWM2M.

Device active observation

For those attributes of the devices marked as active, a Observe operation is issued from the server upon registration, expecting subsequent measures to be issued as Notify responses to the Observe message (as stated in the Information Reporting Interface of the LWM2M Specification).

Device command

Commands are issued as changes in a particular value in the Context Entity, and are mapped to Execute operations from the server to the client. The status of the execution is mantained in a special attribute in the Context Entity, that is updated with any upcoming information to the server.

Basic Design Principles

  • Face IoT fragmentation: Today's IoT framework considers a number of vertical silos exploiting different M2M technologies and protocols. The Backend Device Management GE aims to offer a simple and flexible solution to connect any kind of IoT devices to a FIWARE ecosystem.
  • Modular design: Functionalities (including supporting different IoT southbound protocols) are provided as modules. The minimum configuration of a Backend Device Management GE in a Datacenter comprises one single IoT-Agent. Other configurations may add other IoT Agents, the IoT Agent Manager or the IoT Edge Manager. All those modules might be installed in the same or different virtual machines for the sake of scalability and redundancy.
  • Easy extensibility: An skeleton of an IoT-Agent should be provided to allow IoT integrators to create new IoT Agent modules for non supported standards or propietary device/gateway protocols.

Detailed Open Specifications

Following is a list of Open Specifications linked to this Generic Enabler. Specifications labeled as "PRELIMINARY" are considered stable but subject to minor changes derived from lessons learned during last interactions of the development of a first reference implementation planned for the current Major Release of FI-WARE. Specifications labeled as "DRAFT" are planned for future Major Releases of FI-WARE but they are provided for the sake of future users.

Open API Specifications

Other Open Specifications


Re-utilised Technologies/Specifications

The Backend Device Management GE is based on RESTful Design Principles. The technologies and specifications used in this GE are:

  • RESTful web services
  • HTTP/1.1 (RFC2616)
  • XML data serialization format.

Terms and definitions

This section comprises a summary of terms and definitions introduced during the previous sections. It intends to establish a vocabulary that will be help to carry out discussions internally and with third parties (e.g., Use Case projects in the EU FP7 Future Internet PPP). For a summary of terms and definitions managed at overall FI-WARE level, please refer to FIWARE Global Terms and Definitions

  • Thing. One instance of a physical object, living organism, person or concept interesting to a person or an application from the perspective of a FI-WARE instance, one particular usage area or to several usage areas. Examples of physical objects are: building, table, bridge (classes), the Kreml, the tennis table from John’s garden, the Tower bridge (instances). Examples of living organisms are: frog, tree, person (classes), the green frog from the garden, the oak tree in front of this building, Dr. Green.
  • Class of thing. Defines the type of a thing in the style of object-oriented programming: a construct that is used as a blueprint to create instances, defining constituent members which enable class instances to have state and behavior. An example of class of thing is “person”, whereas an instance of a thing is “Dr. Green”, with all the static/dynamically changing properties of this particular person.
  • Group of things. A physical/logical group of things. Examples are all office buildings from Munich, all bridges above the Thames, all screws from a drawer, the planes of Lufthansa currently above Germany, all cars inside a traffic jam driven by a female driver, the trees from the Amazonian forest, the squids from the Mediterranean see the mushrooms from Alice’s garden, all the fish from the aquarium of John., the soccer team of Manchester, the colleagues from OrangeLabs currently working abroad (from the perspective of France), all patients above 60 years of age of Dr. Green, the traffic jams from Budapest, the wheat crop in France in the year 2011, the Research and Development Department of the company Telefónica.
  • Device. Hardware entity, component or system that may be in a relationship with a thing or a group of things called association. A device has the means either to measure properties of a thing/group of things and convert it to an analog or digital signal that can be read by a program or user or to potentially influence the properties of a thing/group of things or both to measure/influence. In case when it can only measure the properties, then we call it a sensor. In case when it can potentially influence the properties of a thing, we call it an actuator. Sensors and actuators may be elementary or composed from a set of elementary sensors/actuators. The simplest elementary sensor is a piece of hardware measuring a simple quantity, such as speed of the wind, and displaying it in a mechanical fashion. Sensors may be the combination of software and hardware components, such as a vehicle on-board unit, that consists of simple sensors measuring various quantities such as the speed of the car, fuel consumption etc and a wireless module transmitting the measurement result to an application platform. The simplest elementary actuator is a light switch. We have emphasized potentially because as a result of the light switch being switched on it is not sure that the effect will be that light bulb goes on: only an associated sensor will be able to determine whether it went on or not. Other examples of devices are smart meters, mobile POS devices. More sophisticated devices may have a unique identifier, embedded computing capabilities and local data storage utilities, as well as embedded communication capabilities over short and/or long distances to communicate with IoT backend. Simple devices may not have all these capabilities and they can for instance only disclose the measurement results via mechanical means. In this latter case the further disclosure of the measurement result towards IoT backend requires another kind of device, called IoT Gateway.
  • Association. It is a physical/logical relationship between a device and a thing or a device and a group of things or a group of devices and a group of things from the perspective of a FI-WARE instance, an application within a usage area project or other stakeholder. A device is associated with a thing if it can sense or (potentially) influence at least one property of the thing, property capturing an aspect of the thing interesting to a person or an application from the perspective of a FI-WARE instance, one particular usage area or to several usage areas. Devices are associated with things in fully dynamic or mainly static or fully static manner. The association may have several different embodiments: physical attachment, physical embedding, physical neighborhood, logical relation etc. Physical attachment means that the device is physically attached to the thing in order to monitor and interact with it, enabling the thing to be connected to the Internet. An example is the on-board device installed inside the vehicle to allow sending sensor data from the car to the FI-WARE instances. Physical embedding means that the device is deeply built inside the thing or almost part of the thing. An example of physical embedding is the GPS sensor inside a mobile phone. Physical neighborhood means that the device is in the physical neighborhood of the thing, but not in physical contact with it. An example of physical neighborhood is the association of the mobile phone of a subscriber who is caught in a traffic jam with the traffic jam itself: the mobile phone is the device, the traffic jam is the thing and the association means that the mobile phone is in the physical neighborhood of the area inside which the traffic jam is constrained (e.g. within 100 m from the region where the average speed of cars is below 5 km/h). Logical association means that there is a relationship between the device and the thing which is neither fully physical in the sense of attachment or embedding, nor fully physical proximity related. An example of logical association is between the car and the garage door opener of the garage where the car usually parks during the night.
  • IoT gateway. A device that additionally to or instead of sensing/actuating provides inter-networking and protocol conversion functionalities between devices and IoT backend potentially in any combination of these hosts a number of features of one or several Generic Enablers of the IoT Service Enablement. It is usually located at proximity of the devices to be connected. An example of an IoT gateway is a home gateway that may represent an aggregation point for all the sensors/actuators inside a smart home. The IoT gateway will support all the IoT backend features, taking into consideration the local constraints of devices such as the available computing, power, storage and energy consumption. The level of functional split between the IoT backend and the IoT gateway will also depend on the available resources on the IoT gateway, the cost and quality of connectivity and the desired level for the distribution of intelligence and service abstraction.
  • IoT resource. Computational elements (software) that provide the technical means to perform sensing and/or actuation on the device. There may be one-to-one or one-to-many relationship between a device and its IoT resource. Actuation capabilities exposed by the IoT resource may comprise configuration of the management/application features of the device, such as connectivity, access control, information, while sensing may comprise the gathering of faults, performance metrics, accounting/administration data from the device, as well as application data about the properties of the thing with which the device is associated. The resource is usually hosted on the device.
  • Management service. It is the feature of the IoT resource providing programmatic access to readable and/or writable data belonging to the functioning of the device, comprising a subset of the FCAPS categories, that is, configuration management, fault management, accounting /access management/administration, performance management/provisioning and security management. The extent of the subset depends on the usage area. Example of configuration management data is the IP endpoint of the IoT backend instance to which the device communicates. Example of fault management is an error given as a result of the overheating of the device because of extensive exposure to the sun. Example of accounting/administration is setting the link quota for applications using data from a certain sensor. Example of security management is the provisioning of a list of device ID-s of peer devices with which the device may directly communicate.
  • Application service. It is the feature of the IoT resource providing programmatic access to readable or writable data in connection with the thing which is associated with the device hosting the resource. The application service exchanges application data with another device (including IoT gateway) and/or the IoT backend. Measured sensory data are example of application data flowing from devices to sensors. Setting the steering angle of a security camera or sending a “start wetting” command to the irrigation system are examples of application data flowing from the application towards the sensor.
  • Event. An event can be defined as an activity that happens, occurs in a device, gateway, IoT backend or is created by a software component inside the IoT service enablement. The digital representation of this activity in a device, IoT resource, IoT gateway or IoT backend instance, or more generally, in a FI-WARE instance, is also called an event. Events may be simple and complex. A simple event is an event that is not an abstraction or composition of other events. An example of a simple event is that “smart meter X got broken”. A complex event is an abstraction of other events called member events. For example a stock market crash or a cellular network blackout is an abstraction denoting many thousand of member events. In many cases a complex event references the set of its members, the implication being that the event contains a reference. For example, the cellular network blackout may be caused by a power failure of the air conditioning in the operator’s data center. In other cases such a reference may not exist. For example there is no accepted agreement as to which events are members of a stock market crash complex event. Complex events may be created of simple events or other complex events by an IoT resource or the IoT backend instance.
  • IoT Backend. Provides management functionalities for the devices and IoT domain-specific support for the applications. Integrant component of FI-WARE instances.
  • IoT application. An application that uses the application programming interface of the IoT service enablement component. May have parts running on one/set of devices, one/set of IoT gateways and one/set of IoT backends.
  • Virtual thing. It is the digital representation of a thing inside the IoT service enablement component. Consists of a set of properties which are interesting to a person or an application from the perspective of a FI-WARE instance, one particular usage area or to several usage areas. Classes of things have the same set of properties, only the value of the properties change from instance to instance.
Personal tools
Create a book