![\"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 Protocol for \nconstrained devices. The tutorial introduces a series of dummy IoT devices which are displayed within the browser and\nallows a user to interact with them. A complete understanding of all the terms and concepts defined in this\ntutorial is necessary before proceeding to connect the IoT devices to the Orion Context Broker via a real IoT Agent.
\nThe docker-compose files for this tutorial can be found on GitHub:
FIWARE 201: Introduction to IoT Sensors
\n\n\"All our knowledge begins with the senses.\"
\n— Immanuel Kant (Critique of Pure Reason)
\n
The Internet of Things (IoT) is a network of physical\ndevices which are able to connect to a network and exchange data. Each \"thing\" or \"smart device\" is a gadget\nwith embedded electronics and sofware which can act as a sensor or actuator. Sensors are able to report the\nstate of the real-world around them. Actuators are responsible for altering the state of the system, by responding\nto 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,\nthe context is provided by the array of attached IoT devices. Since each IoT device is a physical object which\nexists in the real world, 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 IoT devices which will be used within this tutorial:
\nOPEN, CLOSED or LOCKED), ON or OFF).\nWhen switched on, a motion sensor within the device checks to see if light is is needed and will dim if no-one is nearby.\nFurthermore the device can be report on the current luminocity of the bulb.As you can see, the Bell is an example of a pure actuator, as it only reacts to the given commands. Meanwhile the \nMotion Sensor is an example of a pure sensor, since it will only report on the state of the world as it sees it.\nThe other two devices 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 in the diagram below:
\n![\"\"](\"https://fiware.github.io/tutorials.IoT-Sensors/img/entities.png\")
UltraLight 2.0 is a lightweight text based protocol for constrained devices and communications where\nbandwidth and device memory resources are limited. The payload for measurement requests is\na 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. \nValues in Ultralight 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, \ndoes not specify a single transport protocol. Instead, different transport protocol bindings (such as HTTP,\nMQTT and AMQP) can be used 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\nan IoT agent) are known as southbound traffic. Southbound traffic consists of commands made to \nactuator devices which alter the state of the real world by their actions. For example a command\nto alter the state of a lamp to ON would switch on the lamp in real life. This in turn could alter\nthe readings of other sensors nearby.
Setting up the southbound communication between an IoT Agent and IoT devices is known as provisioning.\nThis ensures that the IoT Agent holds sufficient information to be able to contact each IoT device.\nIn other words it knows where to send commands and which commands are supported. In order to send a\ncommand to a device, the IoT Agent sends a POST request to the 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 any 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 listening on this\nendpoint to perform the turn command. I have supplied the parameters left and 30 (degrees) as required for the device to be able to perform the manuever\".
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 Context Broker.\nThe 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, any response can always be associated to an entity\nheld 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, an alternative polling mechanism\ncan be used when all interactions are initiated from the device itself, but this is beyond the scope of this tutorial
\nRequests generated from an IoT device and passed back upwards towards the Context Broker (via an \nIoT agent) are known as northbound traffic. Northbound traffic consists of measurements made\nby sensor devices and relays the state of the real world into the context data of the system.\nFor example a measurement from a humidity sensor could be relayed back into the context broker\nto indicate that the moisture level of the entity has changed. A subscription could be made\nto be informed of such changes and there provoke further actions (such as turning on a sprinkler)
\nA device can report new measures to the IoT Platform using an HTTP GET request to a \"well-known\" endpoint\n(the path /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=motion001&d=c|12\nWould indicate that the device id=motion001 wishes to inform the IoT Agent that is has made a real-world measurement c with\nthe 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 - \nthe key-value pairs of the measurement are passed as the body of the request. 'i and k query parameters are\nstill mandatory:
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 the context broker.\nThe state of each device can be seen on the UltraLight device monitor web-page found at: http://localhost:3000/device/monitor
![\"FIWARE](\"https://fiware.github.io/tutorials.IoT-Sensors/img/device-monitor.png\")
The demo application will only make use of a single custom component acting as a set of\ndummy IoT devices. Every IoT device will be using the UltraLight 2.0 protocol running over HTTP.\nSince all interactions are initiated by HTTP requests, the entities can be containerized and run from exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.IoT-Sensors/img/architecture.png\")
The necessary configuration information can be seen in the services section of the associated docker-compose.yml file:
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 - \"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 context-provider 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\nwithout being part of the same network.The context-provider container is driven by environment variables as shown:
The other context-provider 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 comprehend how \nmessages are passed through the system to subsequently understand the purpose of the IoT Agent\nmiddleware. In this tutorial you will be playing the role of an IoT Agent making commands to\ndevices and receiving measurements from them.
\nTo keep things simple all components will be run using Docker. Docker is a container technology\nwhich 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 sevices can be brought up in a single \ncommmand. 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
\nWe will start up our services using a simple bash script. Windows users should download cygwin to provide a\ncommand line functionality similar to a Linux distribution on Windows.
\nAll services can be initialised from the command line by running the bash script provided within the repository:
\n./services create; ./services start;\nThis command will also import seed data from the previous Stock 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 the page to enable audio\nbefore you enter any cUrl commands. The device monitor displays the current state of an array of 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, \nmaking Southbound commands to the attached IoT devices and receiving Northbound measurements\nas the environment changes within the store. All the commands are made as HTTP POST requests\nusing Ultralight syntax and therefore are very simple. It is worthwhile keeping an eye on the \ndevice monitor page as it shows all the Northbound traffic generated\nby 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":"4d0c5bf7-9f5d-42aa-b11d-c8994b5bc26e","publishedId":"RW84ts7D","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"4C4C4C","highlight":"45D3DD"},"publishDate":"2020-01-02T11:01:41.000Z"},"item":[{"name":"Bell Commands","item":[{"name":"Ring a bell","id":"e3fbe45b-4d73-41d4-818a-41c94f42a4d8","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Bell:001@ring"},"url":"localhost:3001/iot/bell001","description":"This example shows how a real IoT Agent would send commands to an actuator. The Bell has supplied an endpoint\n/iot/bell001 where it is listening for commands.
The body of the request is in Ultralight syntax and consists of the id of the device (urn:ngsi-ld:Bell:001)\nas held in the Context Broker and the name of the command (ring) 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 bell change.
\n![](\"https://fiware.github.io/tutorials.IoT-Sensors//img/bell-ring.gif\")
A bell is an example of an actuator. It can respond to commands, but the device does not supply \nan measurements from the real world.
\n","event":[{"listen":"prerequest","script":{"id":"bc8f4f9a-ae81-400f-b1a4-8e48296614aa","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"aff17d91-f510-4436-af77-b0232b6f1d01","type":"text/javascript","exec":[""]}}],"_postman_id":"fea791c1-f652-4a07-a8a5-cd2535d0be62"},{"name":"Smart Lamp Commands","item":[{"name":"Switch on a Smart Lamp","id":"6b6cbc65-5c82-4903-ac6d-718f29ad0f64","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Lamp:001@on"},"url":"localhost:3001/iot/lamp001","description":"This example shows how a real IoT Agent would send an Ultralight command to a Smart Lamp to switch it on.\nThe Smart Lamp has already supplied an endpoint /iot/lamp001 where it is listening for commands.
The 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","lamp001"],"host":["localhost:3001"],"query":[],"variable":[]}},"response":[],"_postman_id":"6b6cbc65-5c82-4903-ac6d-718f29ad0f64"},{"name":"Switch off a Smart Lamp","id":"42708a3f-e6d8-4efc-8282-9649d7b17f3a","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Lamp:001@off"},"url":"localhost:3001/iot/lamp001","description":"This example shows how a real IoT Agent would send an Ultralight command to a Smart Lamp to switch it off.\nThe Smart Lamp has already supplied an endpoint /iot/lamp001 where it is listening for commands.
The 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 (off) to invoke on the device.
The response returns the command and the result of the action.
\nOnce the lamp is switched off the luminocity level does not alter. The latest Ultralight measurement (s|OFF|l|0) as\nsent to the IoT Broker can be seen on the device monitor page.
The Smart Lamp can be switched on and off remotely - it also registers luminocity.\nIt contains a motion sensor wtihin it and will slowly dim as time passes (provided \nno movement is detected)
\nMeasurements will be sent to the IoT Agent as the state and/or luminocity changes.
\n","event":[{"listen":"prerequest","script":{"id":"802c632d-fc4c-4cbe-998e-96a46a38d041","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"7d215fac-dcf6-4457-9a75-5713851d0764","type":"text/javascript","exec":[""]}}],"_postman_id":"3cce131f-6b20-493d-9f03-838888d55d8e"},{"name":"Smart Door Commands","item":[{"name":"Unlock a Door","id":"9b27f5a5-aaaf-4f1e-aec2-b79e8889124f","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Door:001@unlock"},"url":"localhost:3001/iot/door001","description":"This example shows how a real IoT Agent would send an Ultralight command to a Smart Door to unlock 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 (unlock) to invoke on the device.
The response returns the command and the result of the action.
\nOnce the Smart Door is unlocked, it will automatically open and close as customers enter. The changes\nof state are actively reported to the IoT Broker, and the sate of the Smart Door can be seen on the\ndevice monitor page.
\nThe motion sensor within the store is not an actuator - it does not respond to commands, however\nit does actively measure the number of customers passing by. If the door is unlocked, the motion\nsensor will detect movement and send an Ultralight measurements back up to the IoT Broker.
\nThe Northbound HTTP requests generated by the motion sensor can be also viewed on the device monitor page.
\n![](\"https://fiware.github.io/tutorials.IoT-Sensors//img/door-open.gif\")
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":"3892cd0b-efef-4b9b-ada2-6f8d7557c457"},{"name":"Close a Door","id":"45dcedaa-4ec1-417f-a248-b169c3748d58","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Door:001@close"},"url":"localhost:3001/iot/door001","description":"This example shows how a real IoT Agent would send a command to a Smart Door to close 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 (close) to invoke on the device.
The response returns the command and the result of the action.
\nSince the door is currently unlocked, customers can still enter, and re-open the door themselves.\nIf motion is detected, the motion sensor will 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":"45dcedaa-4ec1-417f-a248-b169c3748d58"},{"name":"Lock a Door","id":"da07cb16-7fd4-4401-b836-f70e4b47e0dd","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"urn:ngsi-ld:Door:001@lock"},"url":"localhost:3001/iot/door001","description":"This example shows how a real IoT Agent would send an Ultralight command to a Smart Door to lock 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 (lock) to invoke on the device.
The response returns the command and the result of the action.
\nOnce the door is locked, no further customers may enter. The Motion Sensor will report no\nfurther movement detected, the door cannot be opened manually and the Smart Lamp will\nslowly return to the ambient lighting level.
\nThe Northbound HTTP requests generated by the Smart Lamp can be viewed on the device monitor page.
\n![](\"https://fiware.github.io/tutorials.IoT-Sensors//img/door-lock.gif\")
A Smart Door is an electronic door which can be sent commands to be locked or unlocked remotely.\nIt can also report on its current state (OPEN, CLOSED or LOCKED),
Measurements will be sent to the IoT Agent as the state changes.
\n","event":[{"listen":"prerequest","script":{"id":"9440e43e-b668-4012-9b00-b67cfa285688","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"8d00da62-cf31-492b-9e79-13a8482e691c","type":"text/javascript","exec":[""]}}],"_postman_id":"99ce65e9-7745-43c4-9f06-ff1ea99ffd82"},{"name":"Motion Sensor - Measurement","id":"ddadb98a-f08a-4021-bad1-b77f8f04ed9c","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=motion001","description":"This example simulates a request coming from the device motion001
The request to the previously provisioned resource iot/d is in UltraLight 2.0 format\nand identifies the device motion001 and passes a known API key.
A similar request was made in the previous tutorial (before the IoT Agent was connected)\nwhen the door was unlocked, you will have seen the state of each motion sensor changing\nand a Northbound request will be logged in the device monitor.
\n","urlObject":{"protocol":"http","path":["iot","d"],"host":["localhost:7896"],"query":[{"key":"k","value":"4jggokgpepnvsb2uv4s40d59ov"},{"key":"i","value":"motion001"}],"variable":[]}},"response":[],"_postman_id":"ddadb98a-f08a-4021-bad1-b77f8f04ed9c"}],"event":[{"listen":"prerequest","script":{"id":"a0054544-01fb-4022-abd3-00a1125d9bca","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d5080300-3a8f-4e79-9cb0-3109d21f78df","type":"text/javascript","exec":[""]}}],"variable":[{"key":"ultralight","value":"localhost:3001"},{"key":"iot-agent-southport","value":"localhost:7896","type":"string"}]}