This is a collection of NGSI-LD tutorials for the FIWARE system. Each tutorial consists of a series of exercises to demonstrate the correct use of individual FIWARE components and shows the flow of context data within a simple Smart Solution either by connecting to a series of dummy IoT devices or manipulating the context directly or programmatically.
How to Use
Each tutorial is a self-contained learning exercise designed to teach the developer about a single aspect of FIWARE. A summary of the goal of the tutorial can be found in the description at the head of each page. Every tutorial is associated with a GitHub repository holding the configuration files needed to run the examples. Most of the tutorials build upon concepts or enablers described in previous exercises the to create a complex smart solution which is "powered by FIWARE".
The tutorials are split according to the chapters defined within the FIWARE catalog and are numbered in order of difficulty within each chapter hence an introduction to a given enabler will occur before the full capabilities of that element are explored in more depth.
It is recommended to start with reading the full Core Context Management: The NGSI-LD Interface Chapter before moving on to other subjects, as this will give you a fuller understanding of the role of context data in general. However, it is not necessary to follow all the subsequent tutorials sequentially - as FIWARE is a modular system, you can choose which enablers are of interest to you.
The OpenAPI Specification (commonly known as Swagger) is an API description format for REST APIs. A Swagger spec allows you to describe an entire API (such as NGSI-LD itself) however in this tutorial we shall be concentrating on using Swagger to define data models.
API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines.
The complete OpenAPI Specification can be found on GitHub:
OpenAPI 3.0 Specification. This is
important since we will need a well-defined structure to be able to generate
Docker and Docker Compose
To keep things simple, all components will be run using Docker. Docker is a container technology which allows to different components isolated into their respective environments.
- To install Docker on Windows follow the instructions here.
- To install Docker on Mac follow the instructions here.
- To install Docker on Linux follow the instructions here.
Docker Compose is a tool for defining and running multi-container Docker applications. A series of
are used to configure the required services for the application. This means all container services can be brought up in
a single command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux
users will need to follow the instructions found here.
You can check your current Docker and Docker Compose versions using the following commands:
docker-compose -v docker version
Important In recent versions,
docker-composeis already included as part of the main
dockerclient, Please ensure that you are using Docker version 20.10 or higher and Docker Compose 1.29 or higher and upgrade if necessary. If you are unable to upgrade and stuck using an older version you can still run the tutorials by adding a
legacyparameter at the end the
./servicesscript commands e.g.
services start legacy
If using a linux distro with an outdated docker-compose, the files can be installed directly as shown:
sudo curl -L "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose
If you are using docker-compose in Ubuntu with VMware and faced the following error: ERROR: Couldn't connect to Docker
http+docker://localunixsocket - is it running?
It can be solved by owning the
/var/run/docker.sock Unix socket as shown:
sudo chown $USER /var/run/docker.sock
The tutorials which use HTTP requests supply a collection for use with the Postman utility. Postman is a testing framework for REST APIs. The tool can be downloaded from www.postman.com. All the FIWARE Postman collections can be downloaded directly from the Postman API network.
Gitpod is an open-source Kubernetes application for ready-to-code cloud development environments that spins up an automated dev environment for each task, in the cloud. It enables you to run the tutorials in a cloud development environment directly from your browser or your Desktop IDE.
Cygwin for Windows
The tutorials start up their services using a simple Bash script. When working locally, Windows users should download cygwin to provide a command-line functionality similar to a Linux distribution on Windows.
Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information. Maven can be used to define and download our dependencies and to build and package Java or Scala code into a JAR file.
The tutorials define a series of data-models to be used within the
@context. More information about the classes and
attributes used can be found in the following:
List of Tutorials
Core Context Management: The NGSI-LD Interface
These first tutorials are an introduction to the NGSI-LD Context Brokers, and are an essential first step when learning to use NGSI-LD.
102. Working with
103. CRUD Operations
104. Entity Relationships
107. Temporal Operations
Internet of Things, Robots and third-party systems
In order to make a context-based system aware of the state of the real world, it will need to access information from Robots, IoT Sensors or other suppliers of context data such as social media. It is also possible to generate commands from the context broker to alter the state of real-world objects themselves.
201. Introduction to IoT Sensors
202. Provisioning the Ultralight IoT Agent
203. Provisioning the JSON IoT Agent
Core Context Management: History Management
These tutorials show how to manipulate and store context data, so it can be used for further processing.
304. Querying Time Series Data (Crate-DB)
305. Big Data Analysis (Flink)
306. Big Data Analysis (Spark)
Security: Identity Management
These tutorials show how to create and administer users within an application, and how to restrict access to assets, by assigning roles and permissions.
401. Administrating Users and Organizations
402. Managing Roles and Permissions
Processing, Analysis and Visualization
These tutorials show how to create, process, analyze or visualize context information.
507. Cloud-Edge Computing