{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"a0361f79-2e44-4465-bdb2-80e2a0aac0e0","name":"NGSI-LD IoT Sensors","description":"\nThis tutorial is an introduction to IoT devices and the usage of the\n[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\nProtocol for constrained devices. The tutorial introduces a series of dummy agricultural IoT devices which are displayed\nwithin the browser and allows a user to interact with them. A complete understanding of all the terms and concepts\ndefined in this tutorial is necessary before proceeding to connect the IoT devices to an NGSI-LD context broker via a\nreal IoT Agent.\n\nThe tutorial uses [cUrl](https://ec.haxx.se/) commands throughout, but is also available as\n[Postman documentation](https://fiware.github.io/tutorials.IoT-Sensors/)\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Historic-Context/icon/GitHub-Mark-32px.png) [FIWARE 201: Introduction to IoT Sensors](https://github.com/Fiware/tutorials.IoT-Sensors)\n\n# What are IoT devices?\n\n> \"A farm is a manipulative creature. There is no such thing as finished. Work comes in a stream and has no end. There\n> are only the things that must be done now and things that can be done later..\"\n>\n> — Kristin Kimball, The Dirty Life: On Farming, Food, and Love\n\nThe [Internet of Things](https://www.linux.com/news/who-needs-internet-things) (IoT) is a network of physical devices\nwhich are able to connect to a network and exchange data. Each \"thing\" or \"smart device\" is a gadget with embedded\nelectronics and software which can act as a sensor or actuator. Sensors are able to report the state of the real-world\naround them. Actuators are responsible for altering the state of the system, by responding to a control signal.\n\nEach device is uniquely identifiable through its embedded computing system but is able to inter-operate within the\nexisting internet infrastructure.\n\nFIWARE is a system for managing context information. For a smart solution based on the internet of Things, the context\nis provided by the array of attached IoT devices. Since each IoT device is a physical object which exists in the real\nworld, it will eventually be represented as a unique entity within the context.\n\nIoT devices can range from simple to complex. Here are some examples of agricultural IoT devices which will be used\nwithin this tutorial:\n\n-   A **Soil Sensor** can report on the amount of moisture in the ground\n-   A **Temperature Sensor** can be queried to return current air or soil temperature\n-   A **Filling Sensor** can report the amount of feed left in a silo\n-   An **Irrigation System** can be sent a command to activate and turn on for a short period\n-   **Animal Collars** can be used to track the location, health and stress-levels of livestock\n-   **Farm Management Information Systems** placed in agricultural machinery can be used send and receive instructions\n    to labourers, track the state of tasks and follow the progress of them.\n\nAs you can see, the **Irrigation System** is an example of a pure actuator, as it only reacts to the given commands.\nMeanwhile the **Soil Sensor** is an example of a pure sensor, since it will only report on the state of the world as it\nsees it. Some devices such as an **FMIS** are able to both respond to commands and report on state in a meaningful way.\n\nThe state information held within each device, as it will eventually be seen within the Context Broker is defined in the\ndiagram below:\n\n![](https://fiware.github.io/tutorials.IoT-Sensors/img/entities-ld.png)\n\n# What is Ultralight 2.0?\n\n[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) is a\nlightweight text based protocol for constrained devices and communications where bandwidth and device memory resources\nare limited. The payload for measurement requests is a list of key-value pairs separated by the pipe `|` character.\n\ne.g.\n\n```\n<key>|<value>|<key>|<value>|<key>|<value> etc..\n```\n\nFor example a payload such as:\n\n```\nt|15|k|abc\n```\n\nContains two attributes, one named \"t\" with value \"15\" and another named \"k\" with value \"abc\" are transmitted. Values in\nUltralight 2.0 are not typed (everything is treated as a string).\n\nUltralight 2.0 defines a payload describing measures and commands to share between devices and servers but, does not\nspecify a single transport protocol. Instead, different transport protocol bindings (such as HTTP, MQTT and AMQP) can be\nused for different scenarios. For this tutorial we will be using HTTP as a transport protocol.\n\n## Southbound Traffic (Commands)\n\nHTTP requests generated by the from the Context Broker and passed downwards towards an IoT device (via an IoT agent) are\nknown as southbound traffic. Southbound traffic consists of **commands** made to actuator devices which alter the state\nof the real world by their actions. For example a command to alter the state of a lamp to `ON` would switch on the lamp\nin real life. This in turn could alter the readings of other sensors nearby.\n\n### Push Command using HTTP POST\n\nSetting up the southbound communication between an IoT Agent and IoT devices is known as provisioning. This ensures that\nthe IoT Agent holds sufficient information to be able to contact each IoT device. In other words it knows where to send\ncommands and which commands are supported. In order to send a command to a device, the IoT Agent sends a POST request to\nthe endpoint supplied by the device. The body of the POST request holds the command.\n\nThe payload for Ultralight commands has the following format:\n\n```\n<device name>@<command>|<param|<param>\n```\n\nWhere `<device_name>` is the entity `id` as held in the context broker, `<command>` is one of the supported commands and\nany additional required values are passed in subsequent parameters for example\n\n```\nurn:ngsi-ld:Robot:001@turn|left|30\n```\n\nWill tell a device _\"I am known as `id=\"urn:ngsi-ld:Robot:001\"` within the Context Broker. I would like the device\nlistening on this endpoint to perform the `turn` command. I have supplied the parameters `left` and '`30` (degrees) as\nrequired for the device to be able to perform the maneuver\"_.\n\nThe defined Northbound response to an IoT Agent is as follows:\n\n```\nurn:ngsi-ld:Robot:001@turn|Turn ok\n```\n\nWhich is saying _\"I have complied with a request from the entity known as `id=\"urn:ngsi-ld:Robot:001\"` within the\nContext Broker. The command I have performed was a `turn` command. The result was `Turn ok`\"_.\n\nAs you can see, because the Southbound command defines the `id` used within the interaction, and the same data is also\nreturned, every response can always be associated to the appropriate entity held within the Context Broker.\n\nPush commands can only be used if the device is able to supply a separate endpoint for listening to southbound traffic,\nan alternative polling mechanism can be used when all interactions are initiated from the device itself, but this is\nbeyond the scope of this tutorial.\n\n## Northbound Traffic (Measurements)\n\nRequests generated from an IoT device and passed back upwards towards the Context Broker (via an IoT agent) are known as\nnorthbound traffic. Northbound traffic consists of **measurements** made by sensor devices and relays the state of the\nreal world into the context data of the system. For example a measurement from a humidity sensor could be relayed back\ninto the context broker to indicate that the moisture level of the entity has changed. A subscription could be made to\nbe informed of such changes and there provoke further actions (such as turning on a sprinkler)\n\n### Measurement using HTTP GET\n\nA device can report new measures to an IoT Agent using an HTTP GET request to a \"well-known\" endpoint (the path\n`/iot/d`) along with the following query parameters:\n\n-   `i` (device ID): Device ID (unique for the API Key).\n-   `k` (API Key): API Key for the service the device is registered on.\n-   `t` (timestamp): Timestamp of the measure. Will override the automatic IoTAgent timestamp (optional).\n-   `d` (Data): Ultralight 2.0 payload.\n\nThe `i` and `k` parameters are mandatory.\n\nFor example the request:\n\n```\n<iot-agent>/iot/d?i=humidity001&d=h|12\n```\n\nWould indicate that the device `id=motion001` wishes to inform the IoT Agent that is has made a real-world measurement\n`h` with the value `12`. This would eventually be passed up into the Context Broker.\n\n### Measurement using HTTP POST\n\nHTTP POST can also be used. Again the path will be `/iot/d`, but in this case, `d` (Data) is not necessary - the\nkey-value pairs of the measurement are passed as the body of the request. `i` and `k` query parameters are still\nmandatory:\n\n-   `i` (device ID): Device ID (unique for the API Key).\n-   `k` (API Key): API Key for the service the device is registered on.\n-   `t` (timestamp): Timestamp of the measure. Will override the automatic IoTAgent timestamp (optional).\n\nOnce again the `i` and `k` parameters are mandatory.\n\n#### Device Monitor\n\nFor the purpose of this tutorial, a series of dummy IoT devices have been created, which will eventually be attached to\nthe context broker. The state of each device can be seen on the UltraLight device monitor web page found at:\n`http://localhost:3000/device/monitor`\n\n![FIWARE Monitor](https://fiware.github.io/tutorials.IoT-Sensors/img/farm-devices.png)\n\n# Architecture\n\nThe demo application will only make use of a single custom component acting as a set of dummy IoT devices. Every IoT\ndevice will be using the\n[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\nprotocol running over HTTP. Since all interactions are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.\n\n![](https://fiware.github.io/tutorials.IoT-Sensors/img/architecture-ld.png)\n\nThe necessary configuration information can be seen in the services section of the associated `docker-compose.yml` file:\n\n```yaml\ntutorial:\n    image: fiware/tutorials.ngsi-ld\n    hostname: iot-sensors\n    container_name: fiware-tutorial\n    networks:\n        - default\n    expose:\n        - \"3000\"\n        - \"3001\"\n    ports:\n        - \"3000:3000\"\n        - \"3001:3001\"\n    environment:\n        - \"DEBUG=tutorial:*\"\n        - \"PORT=3000\"\n        - \"IOTA_HTTP_HOST=iot-agent\"\n        - \"IOTA_HTTP_PORT=7896\"\n        - \"DUMMY_DEVICES_PORT=3001\" # Port used by the dummy IOT devices to receive commands\n        - \"DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov\"\n```\n\nThe `tutorial` container is listening on two ports:\n\n-   Port `3000` is exposed so we can see the web page displaying the Dummy IoT devices.\n-   Port `3001` is exposed purely for tutorial access - so that cUrl or Postman can make UltraLight commands without\n    being part of the same network.\n\nThe `tutorial` container is driven by environment variables as shown:\n\n| Key                   | Value                        | Description                                                                                                                                                                        |\n| --------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| DEBUG                 | `tutorial:*`                 | Debug flag used for logging                                                                                                                                                        |\n| WEB_APP_PORT          | `3000`                       | Port used by web-app which displays the dummy device data                                                                                                                          |\n| IOTA_HTTP_HOST        | `iot-agent`                  | The hostname of the missing IoT Agent - used in a later tutorial                                                                                                                   |\n| IOTA_HTTP_PORT        | `7896`                       | The port that the missing IoT Agent will be listening on. `7896` is a common default for UltraLight over HTTP                                                                      |\n| DUMMY_DEVICES_PORT    | `3001`                       | Port used by the dummy IoT devices to receive commands                                                                                                                             |\n| DUMMY_DEVICES_API_KEY | `4jggokgpepnvsb2uv4s40d59ov` | Random security key used for UltraLight interactions - this will be used in a later tutorial to ensure the integrity of interactions between the devices and the missing IoT Agent |\n\nThe other `tutorial` container configuration values described in the YAML file are not used in this tutorial.\n\nWhen describing the messages being passed through a working smart solution we will refer to two further components which\nare not used in this tutorial, but will be needed to complete the system subsequently.\n\n-   The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) is used for holding the context data of\n    the smart solution. As you know all interactions with the context broker must be made using\n    [NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/full_api.json)\n-   An IoT Agent acts as a middleware component converting\n    [NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/full_api.json)\n    requests (from the context broker) into a protocol (such as\n    [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual))\n    usable by the IoT devices themselves.\n\nIt is therefore necessary to understand a sample device protocol first, and fully comprehend how messages are passed\nthrough the system to subsequently understand the purpose of the IoT Agent middleware. In this tutorial you will be\nplaying the role of an IoT Agent making commands to devices and receiving measurements from them.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container\ntechnology which allows to different components isolated into their respective environments.\n\n-   To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n-   To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n-   To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Entity-Relationships/master/docker-compose.yml) is used\nconfigure the required services for the application. This means all container services can be brought up in a single\ncommand. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users\nwill need to follow the instructions found [here](https://docs.docker.com/compose/install/)\n\nYou can check your current **Docker** and **Docker Compose** versions using the following commands:\n\n```console\ndocker-compose -v\ndocker version\n```\n\nPlease ensure that you are using Docker version 18.03 or higher and Docker Compose 1.21 or higher and upgrade if\nnecessary.\n\n## Cygwin\n\nWe will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n\n# Start Up\n\nAll services can be initialized from the command-line by running the bash script provided within the repository. Please\nclone the repository and create the necessary images by running the commands as shown:\n\n```console\ngit clone https://github.com/FIWARE/tutorials.IoT-Sensors.git\ncd tutorials.IoT-Sensors\ngit checkout NGSI-LD\n\n./services start;\n```\n\nThis command will also import seed data from the previous\n[Farm Management example](https://github.com/FIWARE/tutorials.Context-Providers) on startup.\n\n> :information_source: **Note:** If you want to clean up and start over again you can do so with the following command:\n>\n> ```console\n> ./services stop\n> ```\n\n# Communicating with IoT Devices\n\nTo follow the tutorial correctly please ensure you have the device monitor page available in your browser and click on\nthe page to enable audio before you enter any cUrl commands. The device monitor displays the current state of an array\nof dummy devices using Ultralight 2.0 syntax\n\n#### Device Monitor\n\nThe device monitor can be found at: `http://localhost:3000/device/monitor`\n\nWithin this tutorial you will be playing the role of the missing IoT Agent component, making Southbound commands to the\nattached IoT devices and receiving Northbound measurements as the environment changes within the store. All the commands\nare made as HTTP POST requests using Ultralight syntax and therefore are very simple. It is worthwhile keeping an eye on\nthe device monitor page as it shows all the Northbound traffic generated by the devices themselves.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"513743","team":157450,"collectionId":"a0361f79-2e44-4465-bdb2-80e2a0aac0e0","publishedId":"TVK76LPh","public":true,"publicUrl":"https://documenter-api.postman.tech/view/513743/TVK76LPh","privateUrl":"https://go.postman.co/documentation/513743-a0361f79-2e44-4465-bdb2-80e2a0aac0e0","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5DC0CF"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.6","publishDate":"2020-09-14T11:01:56.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/d7085d490b9144732c65203aa6e3b68b31884d1c33a86b8a00d15da75147ae33","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TVK76LPh"}