From 8a8f56af7d09e9e706db122525ea297891164103 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 4 Jun 2024 10:19:29 +0200 Subject: [PATCH] Switch to WSL --- NGSI-LD IoT Agent.postman_collection.json | 2 +- README.ja.md | 8 ++++---- README.md | 9 +++++---- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/NGSI-LD IoT Agent.postman_collection.json b/NGSI-LD IoT Agent.postman_collection.json index 87704c1..d74d7a5 100644 --- a/NGSI-LD IoT Agent.postman_collection.json +++ b/NGSI-LD IoT Agent.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "440d42df-16d5-4da2-9a24-c7def3f674a4", "name": "NGSI-LD IoT Agent", - "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 20.10 or higher and Docker Compose 1.29 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> ```", + "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 20.10 or higher and Docker Compose 1.29 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" }, "item": [ diff --git a/README.ja.md b/README.ja.md index 045514d..cd982ed 100644 --- a/README.ja.md +++ b/README.ja.md @@ -35,7 +35,7 @@ IoT デバイスを接続して、 - [IoT Agent for UltraLight 2.0 の設定](#iot-agent-for-ultralight-20-configuration) - [前提条件](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [起動](#start-up) - [IoT Agent のプロビジョニング](#provisioning-an-iot-agent) - [IoT Agent サービスの正常性の確認](#checking-the-iot-agent-service-health) @@ -373,11 +373,11 @@ docker version Docker バージョン 20.10 以降と Docker Compose 1.29 以上を使用していることを確認し、 必要に応じてアップグレードしてください。 - + -## Cygwin +## WSL -シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは [cygwin](http://www.cygwin.com/) +シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは [を使用して Windows に Linux をインストールする方法](https://learn.microsoft.com/ja-jp/windows/wsl/install) をダウンロードして、Windows 上の Linux ディストリビューションと同様のコマンドライン機能を提供する必要があります。 diff --git a/README.md b/README.md index bf8840d..29fc05a 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ The tutorial uses [cUrl](https://ec.haxx.se/) commands throughout, but is also a - [IoT Agent for UltraLight 2.0 Configuration](#iot-agent-for-ultralight-20-configuration) - [Prerequisites](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [Start Up](#start-up) - [Provisioning an IoT Agent](#provisioning-an-iot-agent) - [Checking the IoT Agent Service Health](#checking-the-iot-agent-service-health) @@ -362,10 +362,11 @@ docker version Please ensure that you are using Docker version 20.10 or higher and Docker Compose 1.29 or higher and upgrade if necessary. -## Cygwin +## WSL -We will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/) -to provide a command-line functionality similar to a Linux distribution on Windows. +We 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) to provide a command-line +functionality similar to a Linux distribution on Windows. # Start Up