diff --git a/.env b/.env index 9b5973b..2aaee79 100644 --- a/.env +++ b/.env @@ -23,7 +23,7 @@ STELLIO_TIMESCALE_POSTGIS=16-2.14.2-3.4 CURL_VERSION=8.4.0 # IoT Agent JSON Variables -JSON_VERSION=3.3.0-distroless +JSON_VERSION=3.4.0-distroless IOTA_NORTH_PORT=4041 IOTA_SOUTH_PORT=7896 diff --git a/NGSI-LD IoT Agent JSON.postman_collection.json b/NGSI-LD IoT Agent JSON.postman_collection.json index 7623c5e..f30f095 100644 --- a/NGSI-LD IoT Agent JSON.postman_collection.json +++ b/NGSI-LD IoT Agent JSON.postman_collection.json @@ -2,8 +2,10 @@ "info": { "_postman_id": "8bc36db2-ad87-44d6-8485-b6b728b6d373", "name": "NGSI-LD IoT Agent JSON", - "description": "[![NGSI LD](https://img.shields.io/badge/NGSI-LD-d6604d.svg)](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf)\n[![JSON LD](https://img.shields.io/badge/JSON--LD-1.1-f06f38.svg)](https://w3c.github.io/json-ld-syntax/)\n[![UltraLight 2.0](https://img.shields.io/badge/Payload-Ultralight-27ae60.svg)](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n\n\nThis **NGSI-LD** tutorial introduces the concept of an **IoT Agent** and wires up the dummy\n[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) IoT\ndevices created in the [previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors) so that measurements can be\nread and commands can be sent using\n[NGSI LD](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf)\nrequests sent to an NGSI-LD compliant context broker such as the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/).\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.IoT-Agent/icon/GitHub-Mark-32px.png) [FIWARE 202: IoT Agents](https://github.com/Fiware/tutorials.IoT-Agent)\n\n# What is an IoT Agent?\n\n> \"Every act of communication is a miracle of translation.\"\n>\n> — Ken Liu (The Paper Menagerie and Other Stories)\n\nAn IoT Agent is a component that lets a group of devices send their data to and be managed from a Context Broker using\ntheir own native protocols. IoT Agents should also be able to deal with security aspects of the FIWARE platform\n(authentication and authorization of the channel) and provide other common services to the device programmer.\n\nAll **NGSI-LD**-based context brokers such as Scorpio, Stellio and Orion exclusively use the well-defined **NGSI-LD**\ninterface; this interface is also used when receiving instruction from third-parties and again when communicating with\n**NGSI-LD** aware components around the context broker itself. The north port of the IoT Agent is one such component\nwhich can communicate using **NGSI-LD** and the IoT Agent then translates the result so that all interactions beneath\nthis port occur using the **native protocol** of the attached devices.\n\nIn effect, this brings a standard interface to all IoT interactions at the context information management level. Each\ngroup of IoT devices are able to use their own proprietary protocols and disparate transport mechanisms under the hood\nwhilst the associated IoT Agent offers a facade pattern to handle this complexity.\n\nIoT Agents already exist or are in development for many IoT communication protocols and data models. Examples include\nthe following:\n\n- [IoTAgent-JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/) - a bridge between HTTP/MQTT messaging (with\n a JSON payload) and NGSI-LD\n- [IoTAgent-LWM2M](https://fiware-iotagent-lwm2m.readthedocs.io/en/latest) - a bridge between the\n [Lightweight M2M](https://www.omaspecworks.org/what-is-oma-specworks/iot/lightweight-m2m-lwm2m/) protocol and\n NGSI-LD\n- [IoTAgent-UL](https://fiware-iotagent-ul.readthedocs.io/en/latest) - a bridge between HTTP/MQTT messaging (with an\n UltraLight2.0 payload) and NGSI-LD\n- [IoTagent-LoRaWAN](https://fiware-lorawan.readthedocs.io/en/latest) - a bridge between the\n [LoRaWAN](https://www.thethingsnetwork.org/docs/lorawan/) protocol and NGSI-LD\n\n## Southbound Traffic (Commands)\n\nHTTP requests generated by the Orion 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.\n\nFor example to switch on a real-life UltraLight 2.0 **Irrigation System** the following interactions would occur:\n\n1. An NGSI-LD PATCH request is sent to the **Context broker** to update the current context of **Irrigation System**\n\n- this is effectively an indirect request invoke the `on` command of the **Irrigation System**\n\n2. The **Context Broker** finds the entity within the context and notes that the context provision for this attribute\n has been delegated to the IoT Agent\n3. Using the standard forwarding mechanism, the **Context broker** duplicates the PATCH request and forwards it to the\n North Port of the **IoT Agent** to invoke the command\n4. The **IoT Agent** receives this Southbound request and converts it to UltraLight 2.0 syntax and passes it on to the\n **Irrigation System**\n5. The **Irrigation System** switches on the water sprinkler and returns the result of the command to the **IoT Agent**\n in UltraLight 2.0 syntax\n6. The **IoT Agent** receives this Northbound request, interprets it and passes the result of the interaction into the\n context by making an NGSI-LD request to the **Context Broker**.\n7. The **Context Broker** receives this Northbound request and updates the context with the result of the command.\n\n![](https://fiware.github.io/tutorials.IoT-Agent/img/command-swimlane.png)\n\n- Requests between **User** and **Context Broker** use NGSI-LD\n- Requests between **Context Broker** and **IoT Agent** use NGSI-LD\n- Requests between **IoT Agent** and **IoT Device** use native protocols\n- Requests between **IoT Device** and **IoT Agent** use native protocols\n- Requests between **IoT Agent** and **Context Broker** use NGSI-LD\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.\n\nFor example for a real-life **Soil Sensor** to send a humidity reading, the following interactions would occur:\n\n1. A **Soil Sensor** makes a measurement and passes the result to the **IoT Agent**\n2. The **IoT Agent** receives this Northbound request, converts the result from UltraLight syntax and passes the result\n of the interaction into the context by making an NGSI-LD request to the **Context Broker**.\n3. The **Context Broker** receives this Northbound request and updates the context with the result of the measurement.\n\n![](https://fiware.github.io/tutorials.IoT-Agent/img/measurement-swimlane.png)\n\n- Requests between **IoT-Device** and **IoT-Agent** use native protocols\n- Requests between **IoT-Agent** and **Context-Broker** use NGSI-LD\n\n> **Note** Other more complex interactions are also possible, but this overview is sufficient to understand the basic\n> principles of an IoT Agent.\n\n## Common Functionality\n\nAs can be seen from the previous sections, although each IoT Agent will be unique since they interpret different\nprotocols, there will a large degree of similarity between IoT agents.\n\n- Offering a standard endpoint to listen to device updates\n- Offering a standard endpoint to listen to context data updates\n- Holding a list of devices and mapping context data attributes to device syntax\n- Security Authorization\n\nThis base functionality has been abstracted out into a common\n[IoT Agent framework library](https://iotagent-node-lib.readthedocs.io/)\n\n#### Device Monitor\n\nFor the purpose of this tutorial, a series of dummy agricultural IoT devices have been created, which will be attached\nto the context broker. Details of the architecture and protocol used can be found in the\n[IoT Sensors tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD) The state of each device can be\nseen on the UltraLight device monitor web page found at: `http://localhost:3000/device/monitor`\n\n![FIWARE Monitor](https://fiware.github.io/tutorials.IoT-Agent/img/farm-devices.png)\n\n# Architecture\n\nThis application builds on the components created in\n[previous tutorials](https://github.com/FIWARE/tutorials.Subscriptions/). It will make use of two FIWARE components - an\nNGSI-LD Context Broker such as [Orion](https://fiware-orion.readthedocs.io/en/latest/) and the\n[IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/). Usage of the Context Broker is\nsufficient for an application to qualify as _“Powered by FIWARE”_. Both the Orion Context Broker and the IoT Agent rely\non open source [MongoDB](https://www.mongodb.com/) technology to keep persistence of the information they hold. We will\nalso be using the dummy IoT devices created in the [previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/)\n\nTherefore the overall architecture will consist of the following elements:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests 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- The FIWARE [IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/) which will receive\n southbound requests 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 and convert them to\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n commands for the devices\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the **Orion Context Broker** to hold context data information such as data entities, subscriptions and\n registrations\n - Used by the **IoT Agent** to hold device information such as device URLs and Keys\n- The **Tutorial Application** does the following:\n - Offers static `@context` files defining the context entities within the system.\n - Acts as set of dummy [agricultural IoT devices](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD)\n using the\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n protocol running over HTTP.\n\nSince all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run\nfrom exposed ports.\n\n![](https://fiware.github.io/tutorials.IoT-Agent/img/architecture-ld.png)\n\nThe necessary configuration information for wiring up the IoT devices and the IoT Agent can be seen in the services\nsection of the associated `docker-compose.yml` file:\n\n## Dummy IoT Devices Configuration\n\n```yaml\ntutorial:\n image: quay.io/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\"\n - \"DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov\"\n - \"DUMMY_DEVICES_TRANSPORT=HTTP\"\n - \"IOTA_JSON_LD_CONTEXT=http://context:3000/data-models/ngsi-context.jsonld\"\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 IoT Agent for UltraLight 2.0 - see below |\n| IOTA_HTTP_PORT | `7896` | The port that the IoT Agent for UltraLight 2.0 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 - used to ensure the integrity of interactions between the devices and the IoT Agent |\n| DUMMY_DEVICES_TRANSPORT | `HTTP` | The transport protocol used by the dummy IoT devices |\n| IOTA_JSON_LD_CONTEXT | `http://context:3000/data-models/ngsi-context.jsonld` | The location of the `@context` file used to define the device data models |\n\nThe other `tutorial` container configuration values described in the YAML file are not used in this tutorial.\n\n## IoT Agent for UltraLight 2.0 Configuration\n\nThe [IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/) can be instantiated within a\nDocker container. An official Docker image is available from [Docker Hub](https://hub.docker.com/r/fiware/iotagent-ul/)\ntagged `fiware/iotagent-ul`. The necessary configuration can be seen below:\n\n```yaml\niot-agent:\n image: quay.io/fiware/iotagent-ul:latest\n hostname: iot-agent\n container_name: fiware-iot-agent\n depends_on:\n - mongo-db\n networks:\n - default\n expose:\n - \"4041\"\n - \"7896\"\n ports:\n - \"4041:4041\"\n - \"7896:7896\"\n environment:\n - IOTA_CB_HOST=orion\n - IOTA_CB_PORT=1026\n - IOTA_NORTH_PORT=4041\n - IOTA_REGISTRY_TYPE=mongodb\n - IOTA_LOG_LEVEL=DEBUG\n - IOTA_TIMESTAMP=true\n - IOTA_CB_NGSI_VERSION=ld\n - IOTA_AUTOCAST=true\n - IOTA_MONGO_HOST=mongo-db\n - IOTA_MONGO_PORT=27017\n - IOTA_MONGO_DB=iotagentul\n - IOTA_HTTP_PORT=7896\n - IOTA_PROVIDER_URL=http://iot-agent:4041\n - IOTA_JSON_LD_CONTEXT=http://context:3000/data-models/ngsi-context.jsonld\n - IOTA_FALLBACK_TENANT=openiot\n```\n\nThe `iot-agent` container relies on the precence of the Orion Context Broker and uses a MongoDB database to hold device\ninformation such as device URLs and Keys. The container is listening on two ports:\n\n- Port `7896` is exposed to receive Ultralight measurements over HTTP from the Dummy IoT devices\n- Port `4041` is exposed purely for tutorial access - so that cUrl or Postman can make provisioning commands without\n being part of the same network.\n\nThe `iot-agent` container is driven by environment variables as shown:\n\n| Key | Value | Description |\n| -------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| IOTA_CB_HOST | `orion` | Hostname of the context broker to update context |\n| IOTA_CB_PORT | `1026` | Port that context broker listens on to update context |\n| IOTA_NORTH_PORT | `4041` | Port used for Configuring the IoT Agent and receiving context updates from the context broker |\n| IOTA_REGISTRY_TYPE | `mongodb` | Whether to hold IoT device info in memory or in a database |\n| IOTA_LOG_LEVEL | `DEBUG` | The log level of the IoT Agent |\n| IOTA_TIMESTAMP | `true` | Whether to supply timestamp information with each measurement received from attached devices |\n| IOTA_CB_NGSI_VERSION | `LD` | Whether to supply use NGSI-LD when sending updates for active attributes |\n| IOTA_AUTOCAST | `true` | Ensure Ultralight number values are read as numbers not strings |\n| IOTA_MONGO_HOST | `context-db` | The hostname of mongoDB - used for holding device information |\n| IOTA_MONGO_PORT | `27017` | The port mongoDB is listening on |\n| IOTA_MONGO_DB | `iotagentul` | The name of the database used in mongoDB |\n| IOTA_HTTP_PORT | `7896` | The port where the IoT Agent listens for IoT device traffic over HTTP |\n| IOTA_PROVIDER_URL | `http://iot-agent:4041` | URL passed to the Context Broker when commands are registered, used as a forwarding URL location when the Context Broker issues a command to a device |\n| IOTA_JSON_LD_CONTEXT | `http://context:3000/data-models/ngsi-context.jsonld` | The location of the `@context` file used to define the device data models |\n| IOTA_FALLBACK_TENANT | `openiot` | The tenant to use if no explicit tenant has been received from communications |\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 24.0.x or higher and Docker Compose 2.24.x or higher and upgrade if\nnecessary.\n\n## WSL\n\nWe will start up our services using a simple bash script. Windows users should download the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n\n# Start Up\n\nBefore you start you should ensure that you have obtained or built the necessary Docker images locally. Please clone the\nrepository and create the necessary images by running the commands as shown:\n\n```console\ngit clone https://github.com/FIWARE/tutorials.IoT-Agent.git\ncd tutorials.IoT-Agent\ngit checkout NGSI-LD\n\n./services create\n```\n\nThereafter, all services can be initialized from the command-line by running the\n[services](https://github.com/FIWARE/tutorials.IoT-Agent/blob/NGSI-LD/services) Bash script provided within the\nrepository:\n\n```console\ngit clone https://github.com/FIWARE/tutorials.IoT-Agent.git\ncd tutorials.IoT-Agent\ngit checkout NGSI-LD\n\n./services orion|scorpio\n```\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# Provisioning an IoT Agent\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\n## Checking the IoT Agent Service Health\n\nYou can check if the IoT Agent is running by making an HTTP request to the exposed port:\n\n#### :one: Request:\n\n```console\ncurl -X GET \\\n 'http://localhost:4041/iot/about'\n```\n\nThe response will look similar to the following:\n\n```json\n{\n \"libVersion\": \"2.12.0-next\",\n \"port\": \"4041\",\n \"baseRoot\": \"/\",\n \"version\": \"1.13.0-next\"\n}\n```\n\n> **What if I get a `Failed to connect to localhost port 4041: Connection refused` Response?**\n>\n> If you get a `Connection refused` response, the IoT Agent cannot be found where expected for this tutorial - you will\n> need to substitute the URL and port in each cUrl command with the corrected IP address. All the cUrl commands tutorial\n> assume that the IoT Agent is available on `localhost:4041`.\n>\n> Try the following remedies:\n>\n> - To check that the docker containers are running try the following:\n>\n> ```console\n> docker ps\n> ```\n>\n> You should see four containers running. If the IoT Agent is not running, you can restart the containers as necessary.\n> This command will also display open port information.\n>\n> - If you have installed [`docker-machine`](https://docs.docker.com/machine/) and\n> [Virtual Box](https://www.virtualbox.org/), the context broker, IoT Agent and Dummy Device docker containers may\n> be running from another IP address - you will need to retrieve the virtual host IP as shown:\n>\n> ```console\n> curl -X GET \\\n> 'http://$(docker-machine ip default):4041/version'\n> ```\n>\n> Alternatively run all your curl commands from within the container network:\n>\n> ```console\n> docker run --network fiware_default --rm appropriate/curl -s \\\n> -X GET 'http://iot-agent:4041/iot/about'\n> ```", - "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + "description": "[![NGSI LD](https://img.shields.io/badge/NGSI-LD-d6604d.svg)](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf)\n[![JSON LD](https://img.shields.io/badge/JSON--LD-1.1-f06f38.svg)](https://w3c.github.io/json-ld-syntax/)\n[![UltraLight 2.0](https://img.shields.io/badge/Payload-Ultralight-27ae60.svg)](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n\n\nThis **NGSI-LD** tutorial introduces the concept of an **IoT Agent** and wires up the dummy\n[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) IoT\ndevices created in the [previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors) so that measurements can be\nread and commands can be sent using\n[NGSI LD](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf)\nrequests sent to an NGSI-LD compliant context broker such as the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/).\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.IoT-Agent/icon/GitHub-Mark-32px.png) [FIWARE 202: IoT Agents](https://github.com/Fiware/tutorials.IoT-Agent)\n\n# What is an IoT Agent?\n\n> \"Every act of communication is a miracle of translation.\"\n>\n> — Ken Liu (The Paper Menagerie and Other Stories)\n\nAn IoT Agent is a component that lets a group of devices send their data to and be managed from a Context Broker using\ntheir own native protocols. IoT Agents should also be able to deal with security aspects of the FIWARE platform\n(authentication and authorization of the channel) and provide other common services to the device programmer.\n\nAll **NGSI-LD**-based context brokers such as Scorpio, Stellio and Orion exclusively use the well-defined **NGSI-LD**\ninterface; this interface is also used when receiving instruction from third-parties and again when communicating with\n**NGSI-LD** aware components around the context broker itself. The north port of the IoT Agent is one such component\nwhich can communicate using **NGSI-LD** and the IoT Agent then translates the result so that all interactions beneath\nthis port occur using the **native protocol** of the attached devices.\n\nIn effect, this brings a standard interface to all IoT interactions at the context information management level. Each\ngroup of IoT devices are able to use their own proprietary protocols and disparate transport mechanisms under the hood\nwhilst the associated IoT Agent offers a facade pattern to handle this complexity.\n\nIoT Agents already exist or are in development for many IoT communication protocols and data models. Examples include\nthe following:\n\n- [IoTAgent-JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/) - a bridge between HTTP/MQTT messaging (with\n a JSON payload) and NGSI-LD\n- [IoTAgent-LWM2M](https://fiware-iotagent-lwm2m.readthedocs.io/en/latest) - a bridge between the\n [Lightweight M2M](https://www.omaspecworks.org/what-is-oma-specworks/iot/lightweight-m2m-lwm2m/) protocol and\n NGSI-LD\n- [IoTAgent-UL](https://fiware-iotagent-ul.readthedocs.io/en/latest) - a bridge between HTTP/MQTT messaging (with an\n UltraLight2.0 payload) and NGSI-LD\n- [IoTagent-LoRaWAN](https://fiware-lorawan.readthedocs.io/en/latest) - a bridge between the\n [LoRaWAN](https://www.thethingsnetwork.org/docs/lorawan/) protocol and NGSI-LD\n\n## Southbound Traffic (Commands)\n\nHTTP requests generated by the Orion 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.\n\nFor example to switch on a real-life UltraLight 2.0 **Irrigation System** the following interactions would occur:\n\n1. An NGSI-LD PATCH request is sent to the **Context broker** to update the current context of **Irrigation System**\n\n- this is effectively an indirect request invoke the `on` command of the **Irrigation System**\n\n2. The **Context Broker** finds the entity within the context and notes that the context provision for this attribute\n has been delegated to the IoT Agent\n3. Using the standard forwarding mechanism, the **Context broker** duplicates the PATCH request and forwards it to the\n North Port of the **IoT Agent** to invoke the command\n4. The **IoT Agent** receives this Southbound request and converts it to UltraLight 2.0 syntax and passes it on to the\n **Irrigation System**\n5. The **Irrigation System** switches on the water sprinkler and returns the result of the command to the **IoT Agent**\n in UltraLight 2.0 syntax\n6. The **IoT Agent** receives this Northbound request, interprets it and passes the result of the interaction into the\n context by making an NGSI-LD request to the **Context Broker**.\n7. The **Context Broker** receives this Northbound request and updates the context with the result of the command.\n\n![](https://fiware.github.io/tutorials.IoT-Agent/img/command-swimlane.png)\n\n- Requests between **User** and **Context Broker** use NGSI-LD\n- Requests between **Context Broker** and **IoT Agent** use NGSI-LD\n- Requests between **IoT Agent** and **IoT Device** use native protocols\n- Requests between **IoT Device** and **IoT Agent** use native protocols\n- Requests between **IoT Agent** and **Context Broker** use NGSI-LD\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.\n\nFor example for a real-life **Soil Sensor** to send a humidity reading, the following interactions would occur:\n\n1. A **Soil Sensor** makes a measurement and passes the result to the **IoT Agent**\n2. The **IoT Agent** receives this Northbound request, converts the result from UltraLight syntax and passes the result\n of the interaction into the context by making an NGSI-LD request to the **Context Broker**.\n3. The **Context Broker** receives this Northbound request and updates the context with the result of the measurement.\n\n![](https://fiware.github.io/tutorials.IoT-Agent/img/measurement-swimlane.png)\n\n- Requests between **IoT-Device** and **IoT-Agent** use native protocols\n- Requests between **IoT-Agent** and **Context-Broker** use NGSI-LD\n\n> **Note** Other more complex interactions are also possible, but this overview is sufficient to understand the basic\n> principles of an IoT Agent.\n\n## Common Functionality\n\nAs can be seen from the previous sections, although each IoT Agent will be unique since they interpret different\nprotocols, there will a large degree of similarity between IoT agents.\n\n- Offering a standard endpoint to listen to device updates\n- Offering a standard endpoint to listen to context data updates\n- Holding a list of devices and mapping context data attributes to device syntax\n- Security Authorization\n\nThis base functionality has been abstracted out into a common\n[IoT Agent framework library](https://iotagent-node-lib.readthedocs.io/)\n\n#### Device Monitor\n\nFor the purpose of this tutorial, a series of dummy agricultural IoT devices have been created, which will be attached\nto the context broker. Details of the architecture and protocol used can be found in the\n[IoT Sensors tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD) The state of each device can be\nseen on the UltraLight device monitor web page found at: `http://localhost:3000/device/monitor`\n\n![FIWARE Monitor](https://fiware.github.io/tutorials.IoT-Agent/img/farm-devices.png)\n\n# Architecture\n\nThis application builds on the components created in\n[previous tutorials](https://github.com/FIWARE/tutorials.Subscriptions/). It will make use of two FIWARE components - an\nNGSI-LD Context Broker such as [Orion](https://fiware-orion.readthedocs.io/en/latest/) and the\n[IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/). Usage of the Context Broker is\nsufficient for an application to qualify as _“Powered by FIWARE”_. Both the Orion Context Broker and the IoT Agent rely\non open source [MongoDB](https://www.mongodb.com/) technology to keep persistence of the information they hold. We will\nalso be using the dummy IoT devices created in the [previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/)\n\nTherefore the overall architecture will consist of the following elements:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests 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- The FIWARE [IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/) which will receive\n southbound requests 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 and convert them to\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n commands for the devices\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the **Orion Context Broker** to hold context data information such as data entities, subscriptions and\n registrations\n - Used by the **IoT Agent** to hold device information such as device URLs and Keys\n- The **Tutorial Application** does the following:\n - Offers static `@context` files defining the context entities within the system.\n - Acts as set of dummy [agricultural IoT devices](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD)\n using the\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n protocol running over HTTP.\n\nSince all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run\nfrom exposed ports.\n\n![](https://fiware.github.io/tutorials.IoT-Agent/img/architecture-ld.png)\n\nThe necessary configuration information for wiring up the IoT devices and the IoT Agent can be seen in the services\nsection of the associated `docker-compose.yml` file:\n\n## Dummy IoT Devices Configuration\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\"\n - \"DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov\"\n - \"DUMMY_DEVICES_TRANSPORT=HTTP\"\n - \"IOTA_JSON_LD_CONTEXT=http://context:3000/data-models/ngsi-context.jsonld\"\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 IoT Agent for UltraLight 2.0 - see below |\n| IOTA_HTTP_PORT | `7896` | The port that the IoT Agent for UltraLight 2.0 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 - used to ensure the integrity of interactions between the devices and the IoT Agent |\n| DUMMY_DEVICES_TRANSPORT | `HTTP` | The transport protocol used by the dummy IoT devices |\n| IOTA_JSON_LD_CONTEXT | `http://context:3000/data-models/ngsi-context.jsonld` | The location of the `@context` file used to define the device data models |\n\nThe other `tutorial` container configuration values described in the YAML file are not used in this tutorial.\n\n## IoT Agent for UltraLight 2.0 Configuration\n\nThe [IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/) can be instantiated within a\nDocker container. An official Docker image is available from [Docker Hub](https://hub.docker.com/r/fiware/iotagent-ul/)\ntagged `fiware/iotagent-ul`. The necessary configuration can be seen below:\n\n```yaml\niot-agent:\n image: fiware/iotagent-ul:latest\n hostname: iot-agent\n container_name: fiware-iot-agent\n depends_on:\n - mongo-db\n networks:\n - default\n expose:\n - \"4041\"\n - \"7896\"\n ports:\n - \"4041:4041\"\n - \"7896:7896\"\n environment:\n - IOTA_CB_HOST=orion\n - IOTA_CB_PORT=1026\n - IOTA_NORTH_PORT=4041\n - IOTA_REGISTRY_TYPE=mongodb\n - IOTA_LOG_LEVEL=DEBUG\n - IOTA_TIMESTAMP=true\n - IOTA_CB_NGSI_VERSION=ld\n - IOTA_AUTOCAST=true\n - IOTA_MONGO_HOST=mongo-db\n - IOTA_MONGO_PORT=27017\n - IOTA_MONGO_DB=iotagentul\n - IOTA_HTTP_PORT=7896\n - IOTA_PROVIDER_URL=http://iot-agent:4041\n - IOTA_JSON_LD_CONTEXT=http://context:3000/data-models/ngsi-context.jsonld\n - IOTA_FALLBACK_TENANT=openiot\n```\n\nThe `iot-agent` container relies on the precence of the Orion Context Broker and uses a MongoDB database to hold device\ninformation such as device URLs and Keys. The container is listening on two ports:\n\n- Port `7896` is exposed to receive Ultralight measurements over HTTP from the Dummy IoT devices\n- Port `4041` is exposed purely for tutorial access - so that cUrl or Postman can make provisioning commands without\n being part of the same network.\n\nThe `iot-agent` container is driven by environment variables as shown:\n\n| Key | Value | Description |\n| -------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| IOTA_CB_HOST | `orion` | Hostname of the context broker to update context |\n| IOTA_CB_PORT | `1026` | Port that context broker listens on to update context |\n| IOTA_NORTH_PORT | `4041` | Port used for Configuring the IoT Agent and receiving context updates from the context broker |\n| IOTA_REGISTRY_TYPE | `mongodb` | Whether to hold IoT device info in memory or in a database |\n| IOTA_LOG_LEVEL | `DEBUG` | The log level of the IoT Agent |\n| IOTA_TIMESTAMP | `true` | Whether to supply timestamp information with each measurement received from attached devices |\n| IOTA_CB_NGSI_VERSION | `LD` | Whether to supply use NGSI-LD when sending updates for active attributes |\n| IOTA_AUTOCAST | `true` | Ensure Ultralight number values are read as numbers not strings |\n| IOTA_MONGO_HOST | `context-db` | The hostname of mongoDB - used for holding device information |\n| IOTA_MONGO_PORT | `27017` | The port mongoDB is listening on |\n| IOTA_MONGO_DB | `iotagentul` | The name of the database used in mongoDB |\n| IOTA_HTTP_PORT | `7896` | The port where the IoT Agent listens for IoT device traffic over HTTP |\n| IOTA_PROVIDER_URL | `http://iot-agent:4041` | URL passed to the Context Broker when commands are registered, used as a forwarding URL location when the Context Broker issues a command to a device |\n| IOTA_JSON_LD_CONTEXT | `http://context:3000/data-models/ngsi-context.jsonld` | The location of the `@context` file used to define the device data models |\n| IOTA_FALLBACK_TENANT | `openiot` | The tenant to use if no explicit tenant has been received from communications |\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\nBefore you start you should ensure that you have obtained or built the necessary Docker images locally. Please clone the\nrepository and create the necessary images by running the commands as shown:\n\n```console\ngit clone https://github.com/FIWARE/tutorials.IoT-Agent.git\ncd tutorials.IoT-Agent\ngit checkout NGSI-LD\n\n./services create\n```\n\nThereafter, all services can be initialized from the command-line by running the\n[services](https://github.com/FIWARE/tutorials.IoT-Agent/blob/NGSI-LD/services) Bash script provided within the\nrepository:\n\n```console\ngit clone https://github.com/FIWARE/tutorials.IoT-Agent.git\ncd tutorials.IoT-Agent\ngit checkout NGSI-LD\n\n./services orion|scorpio\n```\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# Provisioning an IoT Agent\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\n## Checking the IoT Agent Service Health\n\nYou can check if the IoT Agent is running by making an HTTP request to the exposed port:\n\n#### :one: Request:\n\n```console\ncurl -X GET \\\n 'http://localhost:4041/iot/about'\n```\n\nThe response will look similar to the following:\n\n```json\n{\n \"libVersion\": \"2.12.0-next\",\n \"port\": \"4041\",\n \"baseRoot\": \"/\",\n \"version\": \"1.13.0-next\"\n}\n```\n\n> **What if I get a `Failed to connect to localhost port 4041: Connection refused` Response?**\n>\n> If you get a `Connection refused` response, the IoT Agent cannot be found where expected for this tutorial - you will\n> need to substitute the URL and port in each cUrl command with the corrected IP address. All the cUrl commands tutorial\n> assume that the IoT Agent is available on `localhost:4041`.\n>\n> Try the following remedies:\n>\n> - To check that the docker containers are running try the following:\n>\n> ```console\n> docker ps\n> ```\n>\n> You should see four containers running. If the IoT Agent is not running, you can restart the containers as necessary.\n> This command will also display open port information.\n>\n> - If you have installed [`docker-machine`](https://docs.docker.com/machine/) and\n> [Virtual Box](https://www.virtualbox.org/), the context broker, IoT Agent and Dummy Device docker containers may\n> be running from another IP address - you will need to retrieve the virtual host IP as shown:\n>\n> ```console\n> curl -X GET \\\n> 'http://$(docker-machine ip default):4041/version'\n> ```\n>\n> Alternatively run all your curl commands from within the container network:\n>\n> ```console\n> docker run --network fiware_default --rm appropriate/curl -s \\\n> -X GET 'http://iot-agent:4041/iot/about'\n> ```", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", + "_exporter_id": "513743", + "_collection_link": "https://fiware.postman.co/workspace/NGSI-LD-tutorials~60157bf9-a93f-4c6e-90d1-0917133c1872/collection/513743-8bc36db2-ad87-44d6-8485-b6b728b6d373?action=share&source=collection_link&creator=513743" }, "item": [ { @@ -62,7 +64,7 @@ "services" ] }, - "description": "Invoking group provision is always the first step in connecting devices since it is always necessary to supply an\nauthentication key with each measurement and the IoT Agent will not initially know which URL the context broker is\nresponding on.\n\nIt is also possible to set up default commands and attributes for all anonymous devices as well, but this is not done\nwithin this tutorial as we will be provisioning each device separately.\n\nThis example provisions an anonymous group of devices. It tells the IoT Agent that a series of devices will be sending\nmessages to the `IOTA_HTTP_PORT` (where the IoT Agent is listening for **Northbound** communications)\n\nIn the example the IoT Agent is informed that the `/iot/json` endpoint will be used and that devices will authenticate\nthemselves by including the token `4jggokgpepnvsb2uv4s40d59ov`. For an UltraLight IoT Agent this means devices will be\nsending GET or POST requests to:\n\n```\nhttp://iot-agent:7896/iot/d?i=&k=4jggokgpepnvsb2uv4s40d59ov\n```\n\nWhich should be familiar UltraLight 2.0 syntax from the\n[previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD).\n\nThe service group provisioning can also be used to define `attributes` mappings and common `static_attributes`. The\n`attributes` mappings define common aliases for anonymous incoming devices. For example the key `gps` can be defined to\nmap the `location` GeoProperty.\n\nWhen a measurement from an IoT device is received on the resource URL it needs to be interpreted and passed to the\ncontext broker. The `entity_type` attribute provides a default `type` for each device which has made a request (in this\ncase anonymous devices will be known as `Device` entities. Furthermore the location of the context broker (`cbroker`) is\nneeded, so that the IoT Agent can pass on any measurements received to the correct location. `cbroker` is an optional\nattribute - if it is not provided, the IoT Agent uses the context broker URL as defined in the configuration file,\nhowever it has been included here for completeness.\n" + "description": "Invoking group provision is always the first step in connecting devices since it is always necessary to supply an\nauthentication key with each measurement and the IoT Agent will not initially know which URL the context broker is\nresponding on.\n\nIt is also possible to set up default commands and attributes for all anonymous devices as well, but this is not done\nwithin this tutorial as we will be provisioning each device separately.\n\nThis example provisions an anonymous group of devices. It tells the IoT Agent that a series of devices will be sending\nmessages to the `IOTA_HTTP_PORT` (where the IoT Agent is listening for **Northbound** communications)\n\nIn the example the IoT Agent is informed that the `/iot/d` endpoint will be used and that devices will authenticate\nthemselves by including the token `4jggokgpepnvsb2uv4s40d59ov`. For an UltraLight IoT Agent this means devices will be\nsending GET or POST requests to:\n\n```\nhttp://iot-agent:7896/iot/d?i=&k=4jggokgpepnvsb2uv4s40d59ov\n```\n\nWhich should be familiar UltraLight 2.0 syntax from the\n[previous tutorial](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD).\n\nThe service group provisioning can also be used to define `attributes` mappings and common `static_attributes`. The\n`attributes` mappings define common aliases for anonymous incoming devices. For example the key `gps` can be defined to\nmap the `location` GeoProperty.\n\nWhen a measurement from an IoT device is received on the resource URL it needs to be interpreted and passed to the\ncontext broker. The `entity_type` attribute provides a default `type` for each device which has made a request (in this\ncase anonymous devices will be known as `Device` entities. Furthermore the location of the context broker (`cbroker`) is\nneeded, so that the IoT Agent can pass on any measurements received to the correct location. `cbroker` is an optional\nattribute - if it is not provided, the IoT Agent uses the context broker URL as defined in the configuration file,\nhowever it has been included here for completeness.\n" }, "response": [] }, @@ -86,7 +88,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"devices\": [\n {\n \"device_id\": \"temperature001\",\n \"entity_name\": \"urn:ngsi-ld:Device:temperature001\",\n \"entity_type\": \"Device\",\n \"timezone\": \"Europe/Berlin\",\n \"attributes\": [\n {\n \"object_id\": \"t\",\n \"name\": \"temperature\",\n \"type\": \"Property\",\n \"metadata\": {\n \"unitCode\": {\n \"type\": \"Text\",\n \"value\": \"CEL\"\n }\n }\n }\n ],\n \"static_attributes\": [\n {\n \"name\": \"controlledAsset\",\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Building:barn001\"\n }\n ]\n }\n ]\n}" + "raw": "{\n \"devices\": [\n {\n \"device_id\": \"temperature001\",\n \"entity_name\": \"urn:ngsi-ld:Device:temperature001\",\n \"entity_type\": \"Device\",\n \"apikey\": \"4jggokgpepnvsb2uv4s40d59ov\",\n \"timezone\": \"Europe/Berlin\",\n \"attributes\": [\n {\n \"object_id\": \"t\",\n \"name\": \"temperature\",\n \"type\": \"Property\",\n \"metadata\": {\n \"unitCode\": {\n \"type\": \"Text\",\n \"value\": \"CEL\"\n }\n }\n }\n ],\n \"static_attributes\": [\n {\n \"name\": \"controlledAsset\",\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Building:barn001\"\n }\n ]\n }\n ]\n}" }, "url": { "raw": "http://{{iot-agent}}/iot/devices", @@ -139,7 +141,7 @@ } ] }, - "description": "You can simulate a dummy IoT device measurement coming from the **Temperature Sensor** device `temperature001`, by\nmaking the following request.\n\nA similar request was made in the previous tutorial (before the IoT Agent was connected) when the sprinkler system was\nactivated, you will have seen the state of each sensor changing and a Northbound request will be logged in the device\nmonitor.\n\nIn this tutorial, now that the IoT Agent is connected, the service group has defined the endpoint upon which the IoT\nAgent is listening (`iot/json`) and the API key used to authenticate the request (`4jggokgpepnvsb2uv4s40d59ov`). Since both\nof these are recognized from the request, the measurement is valid.\n\nBecause we have specifically provisioned the device (`temperature001`) - the IoT Agent is able to map attributes before\nraising a request with the Orion Context Broker.\n" + "description": "You can simulate a dummy IoT device measurement coming from the **Temperature Sensor** device `temperature001`, by\nmaking the following request.\n\nA similar request was made in the previous tutorial (before the IoT Agent was connected) when the sprinkler system was\nactivated, you will have seen the state of each sensor changing and a Northbound request will be logged in the device\nmonitor.\n\nIn this tutorial, now that the IoT Agent is connected, the service group has defined the endpoint upon which the IoT\nAgent is listening (`iot/d`) and the API key used to authenticate the request (`4jggokgpepnvsb2uv4s40d59ov`). Since both\nof these are recognized from the request, the measurement is valid.\n\nBecause we have specifically provisioned the device (`temperature001`) - the IoT Agent is able to map attributes before\nraising a request with the Orion Context Broker.\n" }, "response": [] }, @@ -245,7 +247,7 @@ } ], "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/?type=Thing", + "raw": "http://{{orion}}/ngsi-ld/v1/entities/?type=Device", "protocol": "http", "host": [ "{{orion}}" @@ -259,7 +261,7 @@ "query": [ { "key": "type", - "value": "Thing" + "value": "Device" } ] }, @@ -287,7 +289,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"devices\": [\n {\n \"device_id\": \"water001\",\n \"entity_name\": \"urn:ngsi-ld:Device:water001\",\n \"entity_type\": \"Device\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://iot-sensors:3001/iot/water001\",\n \"commands\": [ \n {\n \"name\": \"on\",\n \"type\": \"command\"\n },\n {\n \"name\": \"off\",\n \"type\": \"command\"\n }\n ],\n \"static_attributes\": [\n {\"name\":\"controlledAsset\", \"type\": \"Relationship\",\"value\": \"urn:ngsi-ld:Building:barn001\"}\n \t]\n }\n ]\n}\n" + "raw": "{\n \"devices\": [\n {\n \"device_id\": \"water001\",\n \"entity_name\": \"urn:ngsi-ld:Device:water001\",\n \"entity_type\": \"Device\",\n \"apikey\": \"4jggokgpepnvsb2uv4s40d59ov\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://iot-sensors:3001/iot/water001\",\n \"commands\": [ \n {\n \"name\": \"on\",\n \"type\": \"command\"\n },\n {\n \"name\": \"off\",\n \"type\": \"command\"\n }\n ],\n \"static_attributes\": [\n {\"name\":\"controlledAsset\", \"type\": \"Relationship\",\"value\": \"urn:ngsi-ld:Building:barn001\"}\n \t]\n }\n ]\n}\n" }, "url": { "raw": "http://{{iot-agent}}/iot/devices", @@ -370,7 +372,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"devices\": [\n {\n \"device_id\": \"filling001\",\n \"entity_name\": \"urn:ngsi-ld:Device:filling001\",\n \"entity_type\": \"FillingLevelSensor\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://iot-sensors:3001/iot/filling001\",\n \"commands\": [\n {\n \"name\": \"add\",\n \"type\": \"command\"\n },\n {\n \"name\": \"remove\",\n \"type\": \"command\"\n }\n ],\n \"attributes\": [\n {\n \"object_id\": \"f\",\n \"name\": \"fillingLevel\",\n \"type\": \"Number\",\n \"metadata\": {\n \"unitCode\": {\n \"type\": \"Text\",\n \"value\": \"CAL\"\n }\n }\n }\n ],\n \"static_attributes\": [\n {\n \"name\": \"controlledAsset\",\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Building:barn001\"\n }\n ]\n }\n ]\n}" + "raw": "{\n \"devices\": [\n {\n \"device_id\": \"filling001\",\n \"entity_name\": \"urn:ngsi-ld:Device:filling001\",\n \"entity_type\": \"FillingLevelSensor\",\n \"apikey\": \"4jggokgpepnvsb2uv4s40d59ov\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://iot-sensors:3001/iot/filling001\",\n \"commands\": [\n {\n \"name\": \"add\",\n \"type\": \"command\"\n },\n {\n \"name\": \"remove\",\n \"type\": \"command\"\n }\n ],\n \"attributes\": [\n {\n \"object_id\": \"f\",\n \"name\": \"fillingLevel\",\n \"type\": \"Number\",\n \"metadata\": {\n \"unitCode\": {\n \"type\": \"Text\",\n \"value\": \"CAL\"\n }\n }\n }\n ],\n \"static_attributes\": [\n {\n \"name\": \"controlledAsset\",\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Building:barn001\"\n }\n ]\n }\n ]\n}" }, "url": { "raw": "http://{{iot-agent}}/iot/devices", @@ -407,7 +409,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"devices\": [\n {\n \"device_id\": \"tractor001\",\n \"entity_name\": \"urn:ngsi-ld:Device:tractor001\",\n \"entity_type\": \"Tractor\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://iot-sensors:3001/iot/tractor001\",\n \"commands\": [\n {\n \"name\": \"start\",\n \"type\": \"command\"\n },\n {\n \"name\": \"stop\",\n \"type\": \"command\"\n }\n ],\n \"static_attributes\": [\n {\n \"name\": \"category\",\n \"type\": \"Property\",\n \"value\": [\n \"sensor\",\n \"actuator\"\n ]\n },\n {\n \"name\": \"controlledAsset\",\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Building:barn001\"\n }\n ]\n }\n ]\n}" + "raw": "{\n \"devices\": [\n {\n \"device_id\": \"tractor001\",\n \"entity_name\": \"urn:ngsi-ld:Device:tractor001\",\n \"entity_type\": \"Tractor\",\n \"apikey\": \"4jggokgpepnvsb2uv4s40d59ov\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://iot-sensors:3001/iot/tractor001\",\n \"commands\": [\n {\n \"name\": \"start\",\n \"type\": \"command\"\n },\n {\n \"name\": \"stop\",\n \"type\": \"command\"\n }\n ],\n \"static_attributes\": [\n {\n \"name\": \"category\",\n \"type\": \"Property\",\n \"value\": [\n \"sensor\",\n \"actuator\"\n ]\n },\n {\n \"name\": \"controlledAsset\",\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Building:barn001\"\n }\n ]\n }\n ]\n}" }, "url": { "raw": "http://{{iot-agent}}/iot/devices", @@ -598,8 +600,8 @@ { "key": "Accept", "value": "application/json", - "type": "text", - "name": "Accept" + "name": "Accept", + "type": "text" } ], "url": { @@ -755,18 +757,17 @@ }, { "key": "Link", - "type": "text", - "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", + "type": "text" }, { "key": "Accept", - "name": "Accept", - "type": "text", - "value": "application/json" + "value": "application/json", + "type": "text" } ], "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/urn:ngsi-ld:Device:tractor:001", + "raw": "http://{{orion}}/ngsi-ld/v1/entities/urn:ngsi-ld:Device:tractor001", "protocol": "http", "host": [ "{{orion}}" @@ -775,7 +776,7 @@ "ngsi-ld", "v1", "entities", - "urn:ngsi-ld:Device:tractor:001" + "urn:ngsi-ld:Device:tractor001" ] }, "description": "The result of the command to ring the bell can be read by querying the entity within the Orion Context Broker. \n\nThe `TimeInstant` shows last the time any command associated with the entity has been invoked. the result of `ring` command can be see in the value of the `ring_info` attribute" @@ -828,8 +829,8 @@ }, { "key": "Link", - "type": "text", - "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", + "type": "text" } ], "body": { @@ -875,8 +876,8 @@ }, { "key": "Link", - "type": "text", - "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", + "type": "text" } ], "body": { @@ -918,18 +919,17 @@ }, { "key": "Link", - "type": "text", - "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + "value": "<{{ngsi-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", + "type": "text" }, { "key": "Accept", - "name": "Accept", - "type": "text", - "value": "application/json" + "value": "application/json", + "type": "text" } ], "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/urn:ngsi-ld:Device:filling:001", + "raw": "http://{{orion}}/ngsi-ld/v1/entities/urn:ngsi-ld:Device:filling001/", "protocol": "http", "host": [ "{{orion}}" @@ -938,7 +938,8 @@ "ngsi-ld", "v1", "entities", - "urn:ngsi-ld:Device:filling:001" + "urn:ngsi-ld:Device:filling001", + "" ] }, "description": "The result of the command to ring the bell can be read by querying the entity within the Orion Context Broker. \n\nThe `TimeInstant` shows last the time any command associated with the entity has been invoked. the result of `ring` command can be see in the value of the `ring_info` attribute" @@ -1083,8 +1084,8 @@ }, { "key": "Content-Type", - "name": "Content-Type", "value": "application/x-www-form-urlencoded", + "name": "Content-Type", "type": "text" } ], @@ -1276,7 +1277,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"devices\": [\n {\n \"device_id\": \"water002\",\n \"entity_name\": \"urn:ngsi-ld:Device:water002\",\n \"entity_type\": \"Device\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://context-provider:3001/iot/water002\",\n \"commands\": [ \n {\n \"name\": \"on\",\n \"type\": \"command\"\n },\n {\n \"name\": \"off\",\n \"type\": \"command\"\n }\n ],\n \"static_attributes\": [\n {\"name\":\"controlledAsset\", \"type\": \"Relationship\",\"value\": \"urn:ngsi-ld:Building:barn002\"}\n \t]\n }\n ]\n}\n" + "raw": "{\n \"devices\": [\n {\n \"device_id\": \"water002\",\n \"entity_name\": \"urn:ngsi-ld:Device:water002\",\n \"entity_type\": \"Device\",\n \"apikey\": \"4jggokgpepnvsb2uv4s40d59ov\",\n \"protocol\": \"PDI-IoTA-UltraLight\",\n \"transport\": \"HTTP\",\n \"endpoint\": \"http://context-provider:3001/iot/water002\",\n \"commands\": [\n {\n \"name\": \"on\",\n \"type\": \"command\"\n },\n {\n \"name\": \"off\",\n \"type\": \"command\"\n }\n ],\n \"static_attributes\": [\n {\n \"name\": \"controlledAsset\",\n \"type\": \"Relationship\",\n \"value\": \"urn:ngsi-ld:Building:barn002\"\n }\n ]\n }\n ]\n}" }, "url": { "raw": "http://{{iot-agent}}/iot/devices", @@ -1484,6 +1485,11 @@ { "key": "ngsi-context.jsonld", "value": "http://context/ngsi-context.jsonld" + }, + { + "key": "scorpio", + "value": "localhost:9090", + "type": "string" } ] } \ No newline at end of file diff --git a/README.ja.md b/README.ja.md index d498fb2..fe4c327 100644 --- a/README.ja.md +++ b/README.ja.md @@ -623,6 +623,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "temperature001", "entity_name": "urn:ngsi-ld:Device:temperature001", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "timezone": "Europe/Berlin", "attributes": [ { @@ -809,6 +810,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "water001", "entity_name": "urn:ngsi-ld:Device:water001", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/water001", @@ -918,6 +920,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "filling001", "entity_name": "urn:ngsi-ld:Device:filling001", "entity_type": "FillingLevelSensor", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/filling001", @@ -975,6 +978,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "tractor001", "entity_name": "urn:ngsi-ld:Device:tractor001", "entity_type": "Tractor", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/tractor001", @@ -1334,6 +1338,7 @@ curl -iX POST 'http://localhost:4041/iot/devices' \ "device_id": "water002", "entity_name": "urn:ngsi-ld:Device:water002", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/water002", @@ -1385,6 +1390,7 @@ curl -X GET \ "service_path": "/", "entity_name": "urn:ngsi-ld:Device:water002", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "endpoint": "http://iot-sensors:3001/iot/water002", "transport": "HTTP", "attributes": [], @@ -1442,6 +1448,7 @@ curl -X GET \ "service_path": "/", "entity_name": "urn:ngsi", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "endpoint": "http://iot-sensors:3001/iot/water002", "transport": "HTTP", "attributes": [], diff --git a/README.md b/README.md index edabebd..bc1d366 100644 --- a/README.md +++ b/README.md @@ -619,6 +619,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "temperature001", "entity_name": "urn:ngsi-ld:Device:temperature001", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "timezone": "Europe/Berlin", "attributes": [ { @@ -808,6 +809,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "water001", "entity_name": "urn:ngsi-ld:Device:water001", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/water001", @@ -916,6 +918,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "filling001", "entity_name": "urn:ngsi-ld:Device:filling001", "entity_type": "FillingLevelSensor", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/filling001", @@ -971,6 +974,7 @@ curl -L -X POST 'http://localhost:4041/iot/devices' \ "device_id": "tractor001", "entity_name": "urn:ngsi-ld:Device:tractor001", "entity_type": "Tractor", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/tractor001", @@ -1305,6 +1309,7 @@ curl -iX POST 'http://localhost:4041/iot/devices' \ "device_id": "water002", "entity_name": "urn:ngsi-ld:Device:water002", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "protocol": "PDI-IoTA-UltraLight", "transport": "HTTP", "endpoint": "http://iot-sensors:3001/iot/water002", @@ -1353,6 +1358,7 @@ The response includes all the commands and attributes mappings associated with t "service_path": "/", "entity_name": "urn:ngsi-ld:Device:water002", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "endpoint": "http://iot-sensors:3001/iot/water002", "transport": "HTTP", "attributes": [], @@ -1407,6 +1413,7 @@ The response includes all the commands and attributes mappings associated with a "service_path": "/", "entity_name": "urn:ngsi", "entity_type": "Device", + "apikey": "4jggokgpepnvsb2uv4s40d59ov", "endpoint": "http://iot-sensors:3001/iot/water002", "transport": "HTTP", "attributes": [],