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.IoTBroker - FIWARE Forge Wiki


From FIWARE Forge Wiki

Jump to: navigation, search
Name FIWARE.OpenSpecification.IoT.Backend.IoTBroker
Chapter Internet-of-Things Service Enablement,
Catalogue-Link to Implementation IoT Broker
Owner NEC, Stefan Gessler



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.


  • Copyright © 2016 by NEC

Legal Notice

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


Role of IoT Broker GE

The IoT Broker GE is an IoT Backend enabler. It is forseen to run on a machine in a data center, where it serves as a middleware which enables fast and easy access to Internet-of-Things data. Instead of having to deal with the technical details of existing FIWARE IoT installations, application developers only need to set up their application to communicate with the IoT Broker in order to retrieve the data they need. The IoT Broker takes care of the task of communicating with the different IoT Devices and Gateways to retrieve the needed information on behalf of the applications.

Data model and interface outline

The main interface exposed by the IoT Broker GE is FIWARE NGSI. This API has been developed by the FIWARE community as a binding of the OMA NGSI(Next Generation Service Interface) Context Management standard (OMA NGSI 9/10). This interface is exposed both southbound towards IoT Gateways and Devices and northbound towards IoT Applications. In other words, the IoT Broker GE retrieves information from IoT Gateways and Devices via the FIWARE NGSI protocol, while the same protocol is can be used by applications to retrieve information from the IoT Broker GE. The IoT Broker aggregates, filters, translates, and enriches the FIWARE NGSI based information before passing it to the applications.

FIWARE NGSI comprises of an information model and two distinct interfaces for information exchange. The information model is centered on the concept of so-called context entities. Context entities represent arbitrary objects of the real world, and the state of such objects is described in terms of the values of attributes. In addition, metadata can be used to describe properties of attribute values. In the context of the Internet-of-Things, context entities are used for representing devices like sensors and the values they measure. Additionally, and even more importantly, arbitrary physical objects (Things) like rooms, vehicles, or persons and their attributes like temperature or location, is as well expressed by FIWARE NGSI context entities.

The two FIWARE NGSI context management interfaces distinguish between two types of information. The first type is called context information and consists of attribute values and associated metadata as described above. In other words, context information is information about the state of context entities. This kind of information is exchanged using the operations the have been defined in OMA NGSI 10 and adopted by FIWARE NGSI. The second type of information is context availability information, i.e., information on where context information can be retrieved by OMA NGSI 10 operations. This kind of information is exchanged using the operations defined in OMA NGSI 9. More details and references on these interfaces can be found below.

Functionality outline

IoT Broker GE internal architecture

The IoT Broker GE is the point of contact for accessing information about things and their attributes (see data model above). Applications can access this information using the NGSI 10 interface of the IoT Broker. In the overall FI-WARE reference architecture [7], the Context Broker GE from the Data & Context Chapter enables up-to-date access to Context Information (not only things) by any application. Such Context Information can be of any nature and comprises, but is not limited to, the Context Information about things that is made available by the IoT Broker GE. However, the IoT Broker GE can as well be accessed by any number of applications directly via its NGSI 10 interface. This enables a simpler setup when applications only use IoT information.

The NGSI context management interface describes three types of operations for exchanging context information. The first and most basic kind of operation is a simple query. When an application invokes the query, it expects to receive context information as the response. The second kind of operation is a subscription. When an application subscribes to certain context information, it just receives a subscription ID as the response. Context information is then sent to the application in the form of notifications. Finally, there is a mode of information exchange defined in the NGSI context interface where information updates are sent without the need to ask for them. When the IoT Broker receives such updates, it forwards the information to some default application that is responsible for further processing and/or storing such updates. In the FI-WARE reference architecture this application is the Context Broker GE.

For basic usage the IoT Broker is a stateless component in the sense that it neither stores context information (i.e. attribute values) nor context availability information. Instead, it interacts with the whole IoT deployment in order to satisfy the requests it receives from the Context Broker GE or final applications: When receiving a query on Context Information, e.g. attributes of Context entities, the IoT Broker GE first contacts the IoT Discovery GE to perform a discovery. Using the resulting availability information, the IoT Broker then contacts the information providers (depicted as IoT Agent in the figure) using NGSI 10 to receive the actual attribute values. Note that the number of information providers to be contacted can be arbitrary. The information is then aggregated and returned to the application. For subscription it is applied a similar approach but with a concept of asynchronous query: once the IoT Broker receives a context subscription request, the IoT Broker subscribe for context availability to the IoT Discovery GE; when a notification of availability of context matching the context subscription is issued to the IoT Broker (caused by a context registration to the IoT Discovery GE by a context provider), the latter initialize a context subscription to the context provider and links it to the original context subscription; when the IoT broker receives a context notification this will be forwarded to the subscriber. For the subscription scenario the IoT Broker is stateful since it needs to keep track of existing subscriptions using the Subscription Storage. This includes both subscriptions received from applications and subscription issued to IoT Agents (e.g. Gateway Data Handling GE) by the IoT Broker

In case of advanced usage IoT Broker keeps also context states as represented in the architecture picture. Firstly, the IoT Broker includes a repository of context registrations (aka ConfMan) that is information about where certain context information can be retrieved. The latter is a new feature since version 4.2, and its purpose is to enable usage of the IoT Broker without an external IoT Discovery GE for simple scenarios.

Secondly, the IoT Broker is able to process context information passing through it and indexing it before to persistently storing in a Key-Value Store (CouchDB). This functionality is available since version 5.2.

Finally, the IoT Broker is capable to query a Knowledge Base Server which can add semantic behavior to IoT query/subscription. For instance when a context of a certain type is requested, also all the sub-types will be taken into consideration in the response.

In the above picture, all the mentioned component are depicted. It is worth to note in the architecture picture the difference between rounded and squared boxes: the firsts are modules which can be enabled only together with an IoT Broker instance, the lasts are standalone components and works as autonomous servers. For this reason it is possible the IoT Broker can be scaled by replicating the IoT Broker core instance, see figure below. All the basic IoT Broker functionalities load can be distributed among several instances.

IoT Broker GE internal architecture

Basic Concepts

The IoT Broker GE is based on the OMA NGSI context data model [1].


The IoT Broker GE implements FI-WARE's RESTful binding specification of the OMA NGSI context management interface (FI-WARE NGSI specifications for short). More specifically, the GE implements the full set of NGSI-10 operations, where it acts both as a client and as a server. As for NGSI-9, the IoT Broker GE acts as a client and implements only the server function required for receiving context availability notifications.

FI-WARE NGSI Context Management specifications are based on the NGSI Context Management specifications defined by OMA (Open Mobile Alliance) [2]. They take the form of a RESTful binding specification of the two context management interfaces defined in the OMA NGSI Context Management specifications, namely NGSI-9 [3] and NGSI-10 [4]. They also solve some ambiguities in the OMA specs and extend them when necessary to implement the FI-WARE Vision.

You can visit the FI-WARE NGSI Open RESTful API Specification [5] to learn the main concepts underlying FI-WARE NGSI Context Management specifications. Please also refer to the e-learning course [9] on the IoT Broker Generic Enabler.

Additional Concepts

Associations in FI-WARE NGSI

One of the central features of the FI-WARE IoT Backend is its ability to derive information about arbitrary things (cars, people, houses, etc.) from device level information. The link between these two levels of abstraction is provided by the association concept defined for FI-WARE NGSI. A definition of the concept and its representation in NGSI-9 messages can be found on the NGSI association definition page [6]. An association is an ordered pair consisting of a sensor-level entity (possibly with an attribute name) and a thing-level entity (possibly enhanced with an attribute name). The interpretation of such a pair is that the sensor provides information about the thing.

Associations potentially play a role for every operation supported by the IoT Broker.

  • The IoT Broker GE queries the ConfMan GE not only for context providers, but also for associations.
  • For resolving a queryContext operation, the IoT Broker uses the association concept to find out which lower-level entities, typically device-level entities, it has to retrieve from the context providers. For example, for finding out the speed of a certain car, the IoT Broker might ask for the measurement of a speedometer.
  • For the translation of thing-level subscriptions into device-level subscriptions the association concept is used in the same way as in the query case.
  • When context providers call the update operation of the IoT Broker GE, the latter analyzes associations in order to find out if updates of attribute values of Thing-level entities have to be triggered.

Main Interactions

The IoT Broker Generic Enabler is a middleware used for setting up and maintaining the data flows in IoT deployments. It is designed to interact with large numbers of IoT data providers and data consumers. On behalf of the consumers, the IoT Broker retrieves, assembles, and processes information from the providers, offering the consumers a simple interface and masking the complexity and heterogeneity of the Internet of Things. For this reason, the IoT Broker GE interacts potentially with a large number of Gateways, other Backend instances, Devices, and of course data consumers. Furthermore, the IoT Broker GE typically interacts with at least one instance of the IoT Discovery GE (but there also is a standalone mode since release 4.2). The latter is where the IoT Broker GE retrieves information about where information is available in the IoT installation.

In the FI-WARE architecture, the role of the data consumer is played by a Generic Enabler in the Data & Context Chapter: the Context Broker. The IoT Broker GE communicates with the Context Broker GE via the Northbound Interface. The Southbound interface is used to communicate with the so-called IoT Agents, which are providing data. The role of IoT Agent can be played by either the Backend Device Management GE, or by the Gateway Data Handling GE.

Query Context Handling

Queries are one-time requests for context information. They are realized by the queryContext operation of OMA NGSI-10. With NGSI-10, GEs or applications can query for Thing-level information. In reaction to a query (QueryContextRequest), the IoT Broker determines the set of IoT Agents that can provide the requested information. This is done by sending a DiscoverContextAvailability request to the IoT Discovery GE, which returns also (optionally) relevant associations between Thing-level entities/attributes and Device-level entities/attributes, and provides addresses of the IoT Agents who can provide the required information. If it is used the internal ConfMan and if the IoT knowledge feature is enabled, the contacted component will contact the external IoT Knowledge component in order to get leverage new knowledge and enhancing the availability discovery (for instance, if the query requests a specific type of entity, all other types semantically known as 'subtype' of the requested type will match the discovery). Then, optionally, the IoT Broker retrieves data from the CouchDB server (historical data if it is requested an historical query or latest data if it is a normal query). After this step, the IoT Broker GE queries the identified IoT Agents. All the context information are then aggregated (potentially also with the outcome of CouchDB). In case the Association feature is enabled, the IoT Broker maps Device-level entities to Thing-level entities. Finally the result is sent back to the GE or application that has issued the query.


Update Context handling

When an UpdateContext is sent to the IoT Broker and the communication does not fail, an ACK is sent back to the requestor with a UpdateContextResponse. If the historical feature is enabled, and the updateContext has specified an append or update as update action, the IoT Broker stores the update data in the CouchDB with a timestamp. If the association feature is enabled, the IoT Broker proceeds to discover the Thing-level entities associated to the Device-level entities about which it has received an update. For that reason the IoT Broker contacts the IoT Discovery GE using a discoverContextAvailability request. Then the context elements contained in the UpdateContext message is checked against the internal Subscription Storage of the IoT Broker aiming to identify subscribers interested to such context data. All the resulting subscribers will be then notified by the IoT Broker. Finally the IoT Broker forwards the update received to the Pub/Sub Broker GE. Note that a single received update may translate into several updates because attributes of several things may need to be updated as a result of an update of a device-level entity (e.g., the temperature measured by a given thermometer may lead to updates on a thing representing a room close to the thermometer, as well as updates on things representing the floor and the building where the room is located).


Subscription Handling

Subscriptions are requests for information updates the issuer wishes to receive, under certain conditions to be specified in the request message. The picture shows the interaction diagram for the OMA NGSI-10 subscribeContext operation, but the same interaction pattern also applies to the updateContextSubscription and to the unsubscribeContext operations. Also in these interactions, like in Query Handling, the role of the IoT Discovery GE is to provide the addresses of the relevant information sources (i.e. the IoT agents) and, optionally, the relevant associations between the Device-level and Thing-level entities. Therefore, once the IoT Broker receives the SubscribeContextRequest, a subscription to context availability is issued by the IoT Broker to the IoT Discovery. The latter sends an ACK (with a SubscribeContextAvailabilityResponse) to the IoT Broker which will then send an ACK to the subscriber with a SubscribeContextResponse containing the identifier of the subscription. From now on the IoT Broker is waiting for notification of context availability (see Availability Notification section). In case the feature is enabled, the IoT Broker perform another step by requesting the local data storage (CouchDB) for matching data. In case of successful query, the results is encapsulated in a NotifyContextRequest and sent to the subscriber that will respond with an ACK (NotifyContextResponse).


Availability Notification

When a new IoT Agent becomes available as provider of context information and it declares it by sending a RegisterContextAvailabilityRequest to the IoT Discovery that respond with an ACK if the registration was successfully (RegisterContextAvailabilityResponse).

If the context provided matches with a subscription for context availability (see previous section) a notification of context availability is sent to the IoT Broker which replies with an ACK (NotifyContextAvailabilityResponse).

The latter step might be preceded by a knowledge query to the IoT Knowledge component, which can give added-value knowledge for establishing further possible matching. For instance, instead of considering a matching merely with the entity type specified in an availability subscription, it might be considered matching also all the supertypes (e.g. if an availability subscription looks for 'Sensor' entity type and the registration is declaring as its type 'BusSensor' which is semantically known as a subtype of 'Sensor', the availability subscription might (depending on the other paramters) be considered matching the registration). This step can be performed only by the internal ConfMan component.

Once the IoT Broker is aware of a new context provider, matching with a context subscription, a SubscribeContextRequest is issued to the context provider which will reply with a SubscribeContextResponse containing either a positive ACK if everything was successful otherwise with a negative ACK. At this point the IoT Broker will be waiting for context information notifications (see next section).



When the IoT Agents provide asynchronously context element by sending a notification (NotifyContextRequest) to the IoT Broker, the latter replies with an ACK if the reception was successfully.

If the feature is enable, the notification is stored in the database (CouchDB).

Furthermore if Association is enabled, a DiscoveryContextAvailabilityRequest is sent by the IoT Broker to the IoT Discover, in order to map the Device layer to the Things layer.

Finally the notification of context information is forwarded to the subscriber application.


Basic Design Principles

  • Stateless Design: The IoT Broker GE is stateless in the sense that no context information is stored by it. Its role in the Internet of Things is not to serve as a central data repository, but as a central point which retrieves and aggregates data from various sources on behalf of applications. The absence of states enables easy replication of IoT Broker GE instances, or federated deployments where multiple instances of the IoT Broker GE are responsible for different parts or domains of the Internet of Things. In such cases each IoT Broker GE instance serves as an IoT Agent for the other instances, and each IoT Broker GE can in principle retrieve any piece of information available in the IoT deployment.
  • Silent System: The IoT Broker enables IoT systems whose level of activity is proportional to the number and complexity of the requests by applications. This is due to the fact that the IoT Broker only queries IoT Agents when there are requests from applications. The principle of silent systems is particularly helpful when working with battery constrained devices. However, also systems that continuously produce data can be built using the IoT Broker GE. In this case, IoT Agents have to be configured to use the NGSI 10 update operation in order to deliver data independently of application requests.


Detailed Specifications

As the IoT Broker is using the FIWARE NGSI standard for communication with other enablers and applications, please the open API specification of FIWARE NGSI for more details on the API.

Re-utilised Technologies/Specifications

The IoT Broker GE relies on the following specifications:

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

The interface of the IoT Broker towards applications and information providers is FIWARE NGSI-10 (the context data interface of FIWARE NGSI), while the interaction with IoT Discovery is done via FIWARE NGSI-9 (the availability information interface of FIWARE NGSI).

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