![\"GitHub\"](\"https://fiware.github.io/tutorials.Historic-Context/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 201: Introduction to IoT SensorsThis tutorial is an introduction to IoT devices and the usage of the\nUltraLight 2.0\nProtocol for constrained devices. The tutorial introduces a series of dummy agricultural IoT devices which are displayed\nwithin the browser and allows a user to interact with them. A complete understanding of all the terms and concepts\ndefined in this tutorial is necessary before proceeding to connect the IoT devices to an NGSI-LD context broker via a\nreal IoT Agent.
\nThe tutorial uses cUrl commands throughout, but is also available as\nPostman documentation
\nThe docker-compose files for this tutorial can be found on GitHub:
FIWARE 201: Introduction to IoT Sensors
\n\n\"A farm is a manipulative creature. There is no such thing as finished. Work comes in a stream and has no end. There\nare only the things that must be done now and things that can be done later..\"
\n— Kristin Kimball, The Dirty Life: On Farming, Food, and Love
\n
The Internet of Things (IoT) is a network of physical devices\nwhich are able to connect to a network and exchange data. Each \"thing\" or \"smart device\" is a gadget with embedded\nelectronics and software which can act as a sensor or actuator. Sensors are able to report the state of the real-world\naround them. Actuators are responsible for altering the state of the system, by responding to a control signal.
\nEach device is uniquely identifiable through its embedded computing system but is able to inter-operate within the\nexisting internet infrastructure.
\nFIWARE is a system for managing context information. For a smart solution based on the internet of Things, the context\nis provided by the array of attached IoT devices. Since each IoT device is a physical object which exists in the real\nworld, it will eventually be represented as a unique entity within the context.
\nIoT devices can range from simple to complex. Here are some examples of agricultural IoT devices which will be used\nwithin this tutorial:
\nAs you can see, the Irrigation System is an example of a pure actuator, as it only reacts to the given commands.\nMeanwhile the Soil Sensor is an example of a pure sensor, since it will only report on the state of the world as it\nsees it. Some devices such as an FMIS are able to both respond to commands and report on state in a meaningful way.
\nThe state information held within each device, as it will eventually be seen within the Context Broker is defined in the\ndiagram below:
\n![\"\"](\"https://fiware.github.io/tutorials.IoT-Sensors/img/entities-ld.png\")
UltraLight 2.0 is a\nlightweight text based protocol for constrained devices and communications where bandwidth and device memory resources\nare limited. The payload for measurement requests is a list of key-value pairs separated by the pipe | character.
e.g.
\n<key>|<value>|<key>|<value>|<key>|<value> etc..\nFor example a payload such as:
\nt|15|k|abc\nContains two attributes, one named \"t\" with value \"15\" and another named \"k\" with value \"abc\" are transmitted. Values in\nUltralight 2.0 are not typed (everything is treated as a string).
\nUltralight 2.0 defines a payload describing measures and commands to share between devices and servers but, does not\nspecify a single transport protocol. Instead, different transport protocol bindings (such as HTTP, MQTT and AMQP) can be\nused for different scenarios. For this tutorial we will be using HTTP as a transport protocol.
\nHTTP requests generated by the from the Context Broker and passed downwards towards an IoT device (via an IoT agent) are\nknown as southbound traffic. Southbound traffic consists of commands made to actuator devices which alter the state\nof the real world by their actions. For example a command to alter the state of a lamp to ON would switch on the lamp\nin real life. This in turn could alter the readings of other sensors nearby.
Setting up the southbound communication between an IoT Agent and IoT devices is known as provisioning. This ensures that\nthe IoT Agent holds sufficient information to be able to contact each IoT device. In other words it knows where to send\ncommands and which commands are supported. In order to send a command to a device, the IoT Agent sends a POST request to\nthe endpoint supplied by the device. The body of the POST request holds the command.
\nThe payload for Ultralight commands has the following format:
\n<device name>@<command>|<param|<param>\nWhere <device_name> is the entity id as held in the context broker, <command> is one of the supported commands and\nany additional required values are passed in subsequent parameters for example
urn:ngsi-ld:Robot:001@turn|left|30\nWill tell a device \"I am known as id=\"urn:ngsi-ld:Robot:001\" within the Context Broker. I would like the device\nlistening on this endpoint to perform the turn command. I have supplied the parameters left and '30 (degrees) as\nrequired for the device to be able to perform the maneuver\".
The defined Northbound response to an IoT Agent is as follows:
\nurn:ngsi-ld:Robot:001@turn|Turn ok\nWhich is saying \"I have complied with a request from the entity known as id=\"urn:ngsi-ld:Robot:001\" within the\nContext Broker. The command I have performed was a turn command. The result was Turn ok\".
As you can see, because the Southbound command defines the id used within the interaction, and the same data is also\nreturned, every response can always be associated to the appropriate entity held within the Context Broker.
Push commands can only be used if the device is able to supply a separate endpoint for listening to southbound traffic,\nan alternative polling mechanism can be used when all interactions are initiated from the device itself, but this is\nbeyond the scope of this tutorial.
\nRequests generated from an IoT device and passed back upwards towards the Context Broker (via an IoT agent) are known as\nnorthbound traffic. Northbound traffic consists of measurements made by sensor devices and relays the state of the\nreal world into the context data of the system. For example a measurement from a humidity sensor could be relayed back\ninto the context broker to indicate that the moisture level of the entity has changed. A subscription could be made to\nbe informed of such changes and there provoke further actions (such as turning on a sprinkler)
\nA device can report new measures to an IoT Agent using an HTTP GET request to a \"well-known\" endpoint (the path\n/iot/d) along with the following query parameters:
i (device ID): Device ID (unique for the API Key).k (API Key): API Key for the service the device is registered on.t (timestamp): Timestamp of the measure. Will override the automatic IoTAgent timestamp (optional).d (Data): Ultralight 2.0 payload.The i and k parameters are mandatory.
For example the request:
\n<iot-agent>/iot/d?i=humidity001&d=h|12\nWould indicate that the device id=motion001 wishes to inform the IoT Agent that is has made a real-world measurement\nh with the value 12. This would eventually be passed up into the Context Broker.
HTTP POST can also be used. Again the path will be /iot/d, but in this case, d (Data) is not necessary - the\nkey-value pairs of the measurement are passed as the body of the request. i and k query parameters are still\nmandatory:
i (device ID): Device ID (unique for the API Key).k (API Key): API Key for the service the device is registered on.t (timestamp): Timestamp of the measure. Will override the automatic IoTAgent timestamp (optional).Once again the i and k parameters are mandatory.
For the purpose of this tutorial, a series of dummy IoT devices have been created, which will eventually be attached to\nthe context broker. The state of each device can be seen on the UltraLight device monitor web page found at:\nhttp://localhost:3000/device/monitor
![\"FIWARE](\"https://fiware.github.io/tutorials.IoT-Sensors/img/farm-devices.png\")
The demo application will only make use of a single custom component acting as a set of dummy IoT devices. Every IoT\ndevice will be using the\nUltraLight 2.0\nprotocol running over HTTP. Since all interactions are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.IoT-Sensors/img/architecture-ld.png\")
The necessary configuration information can be seen in the services section of the associated docker-compose.yml file:
tutorial:\n image: fiware/tutorials.ngsi-ld\n hostname: iot-sensors\n container_name: fiware-tutorial\n networks:\n - default\n expose:\n - \"3000\"\n - \"3001\"\n ports:\n - \"3000:3000\"\n - \"3001:3001\"\n environment:\n - \"DEBUG=tutorial:*\"\n - \"PORT=3000\"\n - \"IOTA_HTTP_HOST=iot-agent\"\n - \"IOTA_HTTP_PORT=7896\"\n - \"DUMMY_DEVICES_PORT=3001\" # Port used by the dummy IOT devices to receive commands\n - \"DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov\"\nThe tutorial container is listening on two ports:
3000 is exposed so we can see the web page displaying the Dummy IoT devices.3001 is exposed purely for tutorial access - so that cUrl or Postman can make UltraLight commands without\nbeing part of the same network.The tutorial container is driven by environment variables as shown:
The other tutorial container configuration values described in the YAML file are not used in this tutorial.
When describing the messages being passed through a working smart solution we will refer to two further components which\nare not used in this tutorial, but will be needed to complete the system subsequently.
\nIt is therefore necessary to understand a sample device protocol first, and fully comprehend how messages are passed\nthrough the system to subsequently understand the purpose of the IoT Agent middleware. In this tutorial you will be\nplaying the role of an IoT Agent making commands to devices and receiving measurements from them.
\nTo keep things simple all components will be run using Docker. Docker is a container\ntechnology which allows to different components isolated into their respective environments.
\nDocker Compose is a tool for defining and running multi-container Docker applications. A\nYAML file 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
\nYou can check your current Docker and Docker Compose versions using the following commands:
\ndocker-compose -v\ndocker version\nPlease ensure that you are using Docker version 18.03 or higher and Docker Compose 1.21 or higher and upgrade if\nnecessary.
\nWe will start up our services using a simple bash script. Windows users should download cygwin\nto provide a command-line functionality similar to a Linux distribution on Windows.
\nAll services can be initialized from the command-line by running the bash script provided within the repository. Please\nclone the repository and create the necessary images by running the commands as shown:
\ngit clone https://github.com/FIWARE/tutorials.IoT-Sensors.git\ncd tutorials.IoT-Sensors\ngit checkout NGSI-LD\n\n./services start;\nThis command will also import seed data from the previous\nFarm Management example on startup.
\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./services stop\n
To 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
\nThe device monitor can be found at: http://localhost:3000/device/monitor
Within this tutorial you will be playing the role of the missing IoT Agent component, making Southbound commands to the\nattached IoT devices and receiving Northbound measurements as the environment changes within the store. All the commands\nare made as HTTP POST requests using Ultralight syntax and therefore are very simple. It is worthwhile keeping an eye on\nthe device monitor page as it shows all the Northbound traffic generated by the devices themselves.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"What are IoT devices?","slug":"what-are-iot-devices"},{"content":"What is Ultralight 2.0?","slug":"what-is-ultralight-20"},{"content":"Architecture","slug":"architecture"},{"content":"Prerequisites","slug":"prerequisites"},{"content":"Start Up","slug":"start-up"},{"content":"Communicating with IoT Devices","slug":"communicating-with-iot-devices"}],"owner":"513743","collectionId":"a0361f79-2e44-4465-bdb2-80e2a0aac0e0","publishedId":"TVK76LPh","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5DC0CF"},"publishDate":"2020-09-14T11:01:56.000Z"},"item":[{"name":"Irrigation System Commands","item":[{"name":"Turn on the Irrigation System","id":"cfa10837-85a8-44cf-b1bc-e5a9e2905a8a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Device:water001@on"},"url":"localhost:3001/iot/water001","description":"The body of the request is in Ultralight syntax and consists of the id of the device (urn:ngsi-ld:Device:water001)\nas held in the Context Broker and the name of the command (on) to invoke on the device.
The response returns the command and the result of the action.
\nIf you are viewing the device monitor page, you can see the state of the water sprinkler change.
\n![](\"https://fiware.github.io/tutorials.IoT-Sensors/img/water-on.png\")
This example shows how to turn off the irrigation system. In this case, the device is also listening for multiple commands off a single endpoint and interpreting the payload body.
\n","urlObject":{"path":["iot","water001"],"host":["localhost:3001"],"query":[],"variable":[]}},"response":[],"_postman_id":"33979914-cc4e-4438-a878-b66147bb78e0"}],"id":"b1c71b15-3bb7-430d-a062-1c5fdbedcb3c","description":"An Irrigation System water sprinkler is an example of an actuator. It can respond to commands, but the device does\nnot supply any measurements from the real world.
\n","event":[{"listen":"prerequest","script":{"id":"d856a054-7166-4e9a-b2fd-16ffb3199be8","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"98833aee-4d64-4a0f-ba2c-85403ac36649","type":"text/javascript","exec":[""]}}],"_postman_id":"b1c71b15-3bb7-430d-a062-1c5fdbedcb3c"},{"name":"Tractor Commands","item":[{"name":"Send an order to start the tractor","id":"f3c041aa-0d82-464f-97ac-86aede8f9ed8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Device:tractor001@start"},"url":"localhost:3001/iot/tractor001","description":"This example shows how a real IoT Agent would send an Ultralight command to a Tractor FMIS to move it from an idle\nto an active state. The unit with the Tractor itself has already supplied an endpoint /iot/tractor001 where it is\nlistening for commands.
The body of the request consists of the id of the device (urn:ngsi-ld:Device:tractor001) as held in the Context\nBroker and the name of the command (start) to invoke on the device.
The response returns the command and the result of the action.
\nOnce the tractor is activated, the location and activity of the tractor will alter dependent upon whether the internal GPS\ndetects movement. The measurement is actively reported and requests to the IoT Broker can be seen on the device monitor\npage.
\nThe body of the request consists of the id of the device (urn:ngsi-ld:Lamp:001)\nas held in the Context Broker and the name of the command (on) to invoke on the device.
The response returns the command and the result of the action.
\nOnce the lamp is switched the luminocity level will alter dependent upon whether the internal\nmotion sensor detects movement. The measurement is actively reported and requests to the\nIoT Broker can be seen on the device monitor page.
\n","urlObject":{"path":["iot","tractor001"],"host":["localhost:3001"],"query":[],"variable":[]}},"response":[],"_postman_id":"f3c041aa-0d82-464f-97ac-86aede8f9ed8"},{"name":"Send an order to stop the tractor","id":"8f093565-5ef0-4280-a6a4-5f4628e3037f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Device:tractor001@stop"},"url":"localhost:3001/iot/tractor001","description":"This example shows how a real IoT Agent would send an Ultralight command to a Tractor FMIS to return the vehicle to\nan idle state. The Tractor has already supplied an endpoint /iot/tractor001 where it is listening for commands.
The body of the request consists of the id of the device (urn:ngsi-ld:Device:tractor001) as held in the Context\nBroker and the name of the command (stop) to invoke on the device.
The response returns the command and the result of the action.
\n","urlObject":{"path":["iot","tractor001"],"host":["localhost:3001"],"query":[],"variable":[]}},"response":[],"_postman_id":"8f093565-5ef0-4280-a6a4-5f4628e3037f"}],"id":"5796042d-3de7-4afa-b95d-07abfcd8f874","description":"An FMIS System on the dashboard of a tractor is an example of a combined actuator and sensor.
\n","event":[{"listen":"prerequest","script":{"id":"9005f80d-3aed-4c31-8d1c-552d4c0f91b2","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d87ab942-53eb-48d2-8d4b-0c2a115cdd47","type":"text/javascript","exec":[""]}}],"_postman_id":"5796042d-3de7-4afa-b95d-07abfcd8f874"},{"name":"Filling Station Commands","item":[{"name":"Remove hay from the barn","id":"adceee10-6f43-4b14-912e-a6d9e4dadc77","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Device:filling001@remove"},"url":"localhost:3001/iot/filling001","description":"This example shows how a real IoT Agent would send an Ultralight command to a Filling Station to unload the barn. The\nFilling Station has already supplied an endpoint /iot/filling001 where it is listening for commands.
The response returns the command and the result of the action.
\nOnce the command is sent, some time will pass and the level of the filling station will change. The changes of state are\nactively reported to the IoT Broker when they occur, and the updated state of the FillingStation can be seen on the\ndevice monitor page.
\nThe body of the request consists of the id of the device (urn:ngsi-ld:Device:filling001) as held in the Context\nBroker and the name of the command (remove) to invoke on the device.
This example shows how a real IoT Agent would send a command to a Smart Door to open the door.\nThe Smart Door has already supplied an endpoint /iot/door001 where it is listening for commands.
The body of the request consists of the id of the device (urn:ngsi-ld:Door:001)\nas held in the Context Broker and the name of the command (open) to invoke on the device.
The response returns the command and the result of the action.
\nThe state of the Smart Door can be seen on the device monitor page. Customers may now enter and\nthe motion sensor may pick up movement and send measurements to the IoT Broker.
\nThe Northbound HTTP requests generated by the motion sensor can also be viewed on the device monitor page.
\n","urlObject":{"path":["iot","door001"],"host":["localhost:3001"],"query":[],"variable":[]}},"response":[],"_postman_id":"90976240-04b8-4d7c-9aa8-59687b4ca96b"}],"id":"44e2c0a6-932c-4b69-904b-ab5b2b2e4771","description":"The Filling Station is an electronic device which can be sent a command to request that feed is added or removed\nfrom the silo. It can also report on its load level. In reality such a device would be connected to the FMIS to request\nthat a worker fills the silo when it gets too low, but in this case we are treating the device as both a sensor and and\nactuator.
\nMeasurements will be sent to the IoT Agent as the state changes.
\n","event":[{"listen":"prerequest","script":{"id":"759642ba-f5ab-471f-8d17-c9bc837c85a5","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"0f7159a3-07fe-45fa-a9ea-e07e379bf400","type":"text/javascript","exec":[""]}}],"_postman_id":"44e2c0a6-932c-4b69-904b-ab5b2b2e4771"},{"name":"Sending Measures","item":[{"name":"Humidity Sensor - Measurement","id":"b54db858-36f1-4b85-b624-bfff9911099b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"text/plain"}],"body":{"mode":"raw","raw":"c|1"},"url":"http://localhost:7896/iot/d?k=4jggokgpepnvsb2uv4s40d59ov&i=humidity001","description":"This example simulates a request coming from the device humidity001
The request to the previously provisioned resource iot/d is in UltraLight 2.0 format and identifies the device\nhumidity and passes a known API key.
The example as written won't work unless the IoT Agent exists and is listening on the appropriate endpoint (/iot/d) to\nprocess the measure. However this measure is the class of request generated by all Ultralight 2.0. sensors.
The SoilSensor, AnimalCollars and TemperatureSensors found on the farm are not actuators since they do not\nrespond to commands, however they does actively monitor and measures the state of things in the real world. If any of\nthe other commands have been sent, the various dummy sensors will also start to respond.
\nThe Northbound HTTP requests generated by the sensors can be also viewed on the device monitor page.
\n![](\"https://fiware.github.io/tutorials.IoT-Sensors/img/device-measures.png\")