NGSI-LD Step-by-Step
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.
Should I use NGSI-LD or NGSI-v2?
FIWARE offers two flavours of the NGSI interfaces:
- NGSI-v2 offers JSON based interoperability used in individual Smart Systems
- NGSI-LD offers JSON-LD based interoperability used for Federations and Data Spaces
Of the two, NGSI-LD is more complex and relies on the introduction of a JSON-LD
@context. A full understanding of JSON-LD (Linked Data) is required to obtain the benefits of NGSI-LD , which allows for interoperability across apps and organisations.In general, you should use NGSI-LD when creating a data space or introducing a system of systems aproach.
Use NGSI-v2 for simpler isolated systems. More information about NGSI-v2 can be found here
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.
Prerequisites
The NGSI-LD tutorials are designed to run under any Unix environment, the tested configuration and
GitPod environment is currently based on Ubuntu 22.04.2 LTS. However, there may
be some minor issues when running the tutorials directly on Windows machines or Apple M1 Silicon amd64 systems, and
the following Virtual Box set-up or WSL set-up can be used when facing issues.
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/OS follow the instructions here.
- To install Docker on Unix follow the instructions here.
Postman 
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.getpostman.com. All the FIWARE Postman collections can be downloaded directly from the Postman API network.
GitPod 
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. The default environment
is based on Ubuntu and includes Java 11.0.16 and Maven 3.8.6.
Apache Maven 
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. Apache Maven 3.8.6 or higher is recommended.
JQ 
jq is a lightweight and flexible command-line JSON processor which can be used to format
the JSON responses received from the context broker and other FIWARE components. More information about how to use jq
can be found here. jq-1.6 is
recommended.
Windows Subsystem for Linux
We will start up our services using a simple bash script. Windows users should download the Windows Subsystem for Linux to provide a command-line functionality similar to a Linux distribution on Windows.
Context Brokers
The NGSI-LD tutorials can be run using any context broker offering the NGSI-LD API, currently the FIWARE Catalogue offers three compliant context brokers:
- Orion-LD - A compact NGSI-LD Context Broker requiring fewer resources
- Scorpio - An NGSI-LD Context Broker, which can also be used in federated environments
- Stellio - An NGSI-LD Context Broker with Keycloak integration
Which NGSI-LD Context Broker should I use?
The mission of the FIWARE Foundation is to develop an open sustainable ecosystem around public, royalty-free and implementation-driven software platform standards that will ease the creation of Smart Applications in multiple sectors.
As such, the FIWARE Foundation would recommend any compliant context broker that is following the ESTI NSGI-LD specifications. The precise context broker you pick will depend upon your chosen use case. Different scenarios may call for a faster context broker, one with a smaller footprint, one which is more secure, etc. etc.
NGSI-LD (Next Generation Service Interface with Linked Data), is the API exported by FIWARE Context Brokers, and used for the integration of platform components within a “Powered by FIWARE” platform and by applications to update or consume context information. The concept of Linked Data based upon JSON-LD payloads is fundamental to effectively passing data between participating organisations.
The NGSI-LD Specification is regularly updated published by ETSI. The latest specification is version 1.7.1 which was published in June 2023.
An Excel file detailing the current compatibility of the bleeding edge development version of each context broker (Orion-LD, Scorpio, Stellio) against the features of the 1.6.1 specification can be found here
Data models
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.
101. Understanding @context
102. Working with @context
103. CRUD Operations
104. Concise Payloads
105. Merge-Patch and Put
106. Entity Relationships
107. Subscriptions
108. Registrations
109. Temporal Operations
110. Extended Properties
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
Integrating NGSI-v2 Systems
These tutorials show how to create data spaces using NGSI-LD and access NGSI-v2 sources