You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
"description": "This tutorial uses introduces the use of the MQTT protocol across IoT devices connecting to FIWARE. The [UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) IoT Agent\ncreated in the [previous tutorial](https://github.com/Fiware/tutorials.IoT-Agent) is reconfigured to\ncommunicate with a set of dummy IoT devices using MQTT\n\n# What is MQTT?\n\nMQTT is publish-subscribe-based messaging protocol used in the Internet of Things. It works on top of the TCP/IP\nprotocol, and is designed for connections with remote locations where a \"small code footprint\" is required or the\nnetwork bandwidth is limited. The goal is to provide a protocol, which is bandwidth-efficient and uses little\nbattery power.\n\nThe [previous tutorial](https://github.com/Fiware/tutorials.IoT-Agent) used HTTP as its transport mechanism between\nthe devices and the IoT Agent. HTTP uses a request/response paradigm where each device connects directly to the IoT Agent.\nMQTT is different in that publish-subscribe is event-driven and pushes messages to clients. It requires an additional\ncentral communication point (known as the MQTT broker) which it is in charge of dispatching all messages between the senders and the rightful receivers. Each client that publishes a message to the broker, includes a **topic** into the message. The **topic** is the routing information for the broker. Each client that wants to receive messages subscribes to a certain **topic** and the broker delivers all messages with the matching **topic** to the client. Therefore the clients don’t have to know each other, they only communicate over the **topic**. This architecture enables highly scalable solutions without dependencies between the data producers and the data consumers.\n\n\nThe UltraLight 2.0 IoT Agent will only send or interpret messages using the [UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) syntax,\nhowever it can be used to send and receive messages over multiple **transport** mechanisms. Therefore we\nare able to use the same FIWARE generic enabler to connect to a wider range of IoT devices.\n\n#### Mosquitto MQTT Broker\n\n[Mosquitto](https://mosquitto.org/) is a readily available, open source MQTT broker which will be used during this tutorial.\nIt is available licensed under EPL/EDL. More information can be found at https://mosquitto.org/\n\n\n#### Device Monitor\n\nFor the purpose of this tutorial, a series of dummy IoT devices have been created, which will be attached to the context broker. Details of the architecture and protocol used can be found in the [IoT Sensors tutorial](https://github.com/Fiware/tutorials.IoT-Sensors)\nThe state of each device can be seen on the UltraLight device monitor web-page found at: `http://localhost:3000/device/monitor`\n\n\n\n# Architecture\n\nThis application builds on the components created in [previous tutorials](https://github.com/Fiware/tutorials.IoT-Agent/). It\nwill make use of two FIWARE components - the [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) and the [IoT Agent for UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/). Usage of the Orion Context Broker is sufficient for an application to qualify as *“Powered by FIWARE”*.\nBoth the Orion Context Broker and the IoT Agent rely on open source [MongoDB](https://www.mongodb.com/) technology to keep persistence of the information they hold. We will also be using the dummy IoT devices created in the [previous tutorial](https://github.com/Fiware/tutorials.IoT-Agent/) \nAdditionally will add an instance of the [Mosquitto](https://mosquitto.org/) MQTT broker which is open source and available under the EPL/EDL.\n\n\nTherefore the overall architecture will consist of the following elements:\n\n* The FIWARE [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n* The FIWARE [IoT Agent for UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/) which will:\n + receive southbound requests using [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) and convert them to [UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) MQTT topics for the MQTT Broker\n + listen to the **MQTT Broker** on registered topics to send measurements northbound\n* The [Mosquitto](https://mosquitto.org/) **MQTT Broker** which acts as a central communication point, passing \n MQTT topics between the **IoT Agent** and IoT devices as necessary.\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 registrations\n + Used by the **IoT Agent** to hold device information such as device URLs and Keys\n* A webserver acting as set of [dummy IoT devices](https://github.com/Fiware/tutorials.IoT-Sensors) using the [UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) protocol running over MQTT.\n* The **Context Provider NGSI** proxy is not used in this tutorial. It does the following:\n + receive requests using [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n + makes requests to publicly available data sources using their own APIs in a proprietary format \n + returns context data back to the Orion Context Broker in [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) format.\n* The **Stock Management Frontend** is not used in this tutorial will it does the following:\n + Display store information\n + Show which products can be bought at each store\n + Allow users to \"buy\" products and reduce the stock count.\n\n\nSince all interactions between the elements are initiated by HTTP or MQTT requests over TCP, the entities can be containerized and run from exposed ports. \n\n\n\nThe necessary configuration information for wiring up the Mosquitto MQTT Broker, the IoT devices and the IoT Agent can be seen in the services section of the associated `docker-compose.yml` file:\n\n## Mosquitto Configuration\n\n```yaml\n mosquitto:\n image: eclipse-mosquitto\n hostname: mosquitto\n container_name: mosquitto\n networks:\n - default\n expose:\n - \"1883\"\n - \"9001\"\n ports:\n - \"1883:1883\"\n - \"9001:9001\"\n volumes:\n - ./mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf\n \n```\n\nThe `mosquitto` container is listening on two ports: \n\n* Port `3000` is exposed so we can post MQTT topics\n* Port `9001` is the standard port for HTTP/Websocket communications\n\nThe attached volume is a [configuration file](https://github.com/Fiware/tutorials.IoT-over-MQTT/blob/master/osquitto/mosquitto.conf) used to increase the debug level of the MQTT Message Broker.\n\n## Dummy IoT Devices Configuration\n\n```yaml\n context-provider:\n image: fiware/cp-web-app:latest\n hostname: context-provider\n container_name: context-provider\n networks:\n - default\n expose:\n - \"3000\"\n - \"3001\"\n ports:\n - \"3000:3000\"\n - \"3001:3001\"\n environment:\n - \"DEBUG=proxy:*\"\n - \"PORT=3000\"\n - \"DUMMY_DEVICES_PORT=3001\"\n - \"DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov\"\n - \"DUMMY_DEVICES_TRANSPORT=MQTT\"\n```\n\nThe `context-provider` 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\n without being part of the same network.\n\n\nThe `context-provider` container is driven by environment variables as shown:\n\n| Key |Value|Description|\n|-----|-----|-----------|\n|DEBUG|`proxy:*`| Debug flag used for logging |\n|PORT|`3000`|Port used by web-app which displays the dummy device data |\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\nThe other `context-provider` 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](http://fiware-iotagent-ul.readthedocs.io/en/latest/) can be instantiated within a Docker container. An official Docker image is available from [Docker Hub](https://hub.docker.com/r/fiware/iotagent-ul/) tagged `fiware/iotagent-ul`. The \nnecessary configuration can be seen below:\n\n```yaml\n iot-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_MONGO_HOST=mongo-db\"\n - \"IOTA_MONGO_PORT=27017\"\n - \"IOTA_MONGO_DB=iotagentul\"\n - \"IOTA_PROVIDER_URL=http://iot-agent:4041\"\n - \"IOTA_MQTT_HOST=mosquitto\"\n - \"IOTA_MQTT_PORT=1883\"\n```\n\nThe `iot-agent` container relies on the precence of the Orion Context Broker and uses a MongoDB database to hold device information 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\n without being part of the same network.\n\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_MONGO_HOST|`context-db`| The host name 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_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_MQTT_HOST|`mosquitto`| The host name of the MQTT Broker |\n|IOTA_MQTT_PORT|`1883`| The port the MQTT Broker is listening on to receive topics |\n\nAs you can see, use of the MQTT transport is driven by only two environment variables `IOTA_MQTT_HOST` and `IOTA_MQTT_PORT`\n\n# Prerequisites\n\n## Docker and Docker Compose \n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container technology 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.IoT-over-MQTT/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## Cygwin for Windows\n\nWe 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.\n\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 repository and create the necessary images by running the commands as shown:\n\n```console\ngit clone [email protected]:Fiware/tutorials.IoT-over-MQTT.git\ncd tutorials.IoT-over-MQTT\n\n./services create\n``` \n\n>**Note** The `context-provider` image has not yet been pushed to Docker hub.\n> Failing to build the Docker sources before proceeding will result in the following error:\n>\n>```\n>Pulling context-provider (fiware/cp-web-app:latest)...\n>ERROR: The image for the service you're trying to recreate has been removed.\n>```\n\n\nThereafter, all services can be initialized from the command line by running the [services](https://github.com/Fiware/tutorials.IoT-over-MQTT/blob/master/services) Bash script provided within the repository:\n\n```console\n./services start\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\n\n\n",
0 commit comments