Differences

This shows you the differences between two versions of the page.

--- en:edu:zmitac:macro:iot:lab [2022/03/16 10:49] – pczekalski
+++ en:edu:zmitac:macro:iot:lab [2024/04/21 16:17] (current) – [Laboratory scenarios] pczekalski
@@ Line 1: / Line 1: @@
 ===== Laboratory on the Internet of Things =====
 Welcome to the laboratory of the Internet of Things.
-Students are about to perform a number of laboratory tasks. Each task is to be finished with a report summarizing on what and how it was done. The report should be prepared in PDF form and eventually ZIPped along with extra files like source code, resources, etc.
+Students are about to perform a number of laboratory tasks. Each task is to be finished with a report summarizing on what and how it was done. The report should be prepared in PDF form and eventually ZIPped with extra files like source code, resources, etc.
 <pagebreak>
@@ Line 12: / Line 12: @@
 <caption>WeMos D1 R2 development board</caption>
 </figure>
-Note, this microcontroller even if its board reminds Arduino Uno has different logic voltage (here 0..3.3V while  Arduino Uno uses classical 0..5V logic) and has different pinout numbering. Detail on the following figure:
+Note, this microcontroller, even if its board reminds Arduino Uno has a different logic voltage (here 0..3.3V while  Arduino Uno uses classical 0..5V logic) and has different pinout numbering. Detail on the following figure:
 <figure wemosd1r2pinout>
 {{:en:edu:zmitac:macro:iot:pinout_0g-00005444_wifi-d1r2-esp8266.jpg?200|}}
@@ Line 28: / Line 28: @@
 {{:en:edu:zmitac:macro:iot:wy-wietlacz-lcd-dla-arduino-1602-klawiatura-tarcza-modu-16x2-5-v-niebieskim-pod-wietleniem-z.jpg?200|}}
 <caption>LCD shield 2x16 characters</caption>
-</figure>
-  * A selected number of teams will also experiment with a Plantower air quality sensors: [[http://www.plantower.com/en/content/?108.html|PMS5003]] or [[http://www.plantower.com/en/content/?110.html|PMS7003]]
-<figure pms>
-{{:en:edu:zmitac:macro:iot:pms5003-front.png?200 |}}{{:en:edu:zmitac:macro:iot:pms7003-front-view.png?200 |}}
-<caption>PMS 5003 (left) and PMS 7003 (right) air quality sensors</caption>
 </figure>
-==== Software ====
-You will be writing an application for end nodes (ESP8266) in C++. Additionally, some skills on NodeJS/Javascript and eventually Java/C# for preparing a dashboard and/or cloud solution will be needed.
+==== VSCode, PlatformIO, and project configuration ====
-Development IDEs are a choice of:
-  * Arduino IDE with Espressif ESP8266 development toolchain,
+In any case, creating a new project under PlatformIO should follow this general setting regarding Board and Framework (see figure {{ref>platformionewproject}}):
-  * Visual Studio Code with the PlatformIO extension:
+<figure platformionewproject>
-Sample ''platformio.ini'' file for the project is:
+{{:en:edu:zmitac:macro:embedeed:lab:screenshot_from_2021-10-13_12-43-38.png?800|:img}}
+<caption>Project configuration settings in VSCode/PlatformIO</caption>
+</figure>
+This configuration brings the following project configuration file ''platformio.ini'':
 <code>
 [env:d1_mini]
@@ Line 47: / Line 45: @@
 framework = arduino
 </code>
-Additionally, you may need to use an MQTT client, i.e. MQTT Explorer: [[http://mqtt-explorer.com/|MQTT Explorer]].
-<note important>Computers in laboratory rooms 320, 321 and 336 use freezing software which means that for every startup, computers are restored to their initial state.</note>
+It is also necessary to configure the serial port name used for uploading your firmware and monitoring (if you use it). In the case of this microcontroller, it is the same port, so the ''platformio.ini'' file should be modified with the following (assuming the serial port is, i.e., ''COM3''):
+<code>
+...
+upload_port = COM3
+monitor_port = COM3
+...
+</code>
+=== Running your code ===
+To execute your code, you need to compile it and upload it to the microcontroller.\\
+The easiest way to interact with PlatformIO is to use its blue ribbon bar, located at the bottom of the VSCode (image {{ref>pioribbon}}:
+<figure pioribbon>
+{{:en:edu:zmitac:macro:embedeed:lab:screenshot_from_2021-12-06_16-22-15en.png?600|}}
+<caption>PlatformIO ribbon to execute most common actions</caption>
+</figure>
+==== Software ====
+You will be writing an application for end nodes (ESP8266) in C++ using VS Code.\\
+Additionally, you may need to use an MQTT client, i.e., MQTT Explorer: [[http://mqtt-explorer.com/|MQTT Explorer]].
+<note important>Computers in laboratory rooms 320, 321, and 336 use "freezing" software, which means that for every startup, computers are restored to their initial state.</note>
 ==== Networking ====
-There is a WiFi 2.4GHz, IPv4 network available to the students. This is a PRIVATE network. This network is separated from the Internet but all connected devices to it can talk to another. There is a DHCP server with networking addressing scope 192.168.90.10-192.168.90.254.
+There is a WiFi 2.4GHz IPv4 network available to the students. This is a PRIVATE network. This network is separated from the Internet, but all connected devices can talk to one another. There is a DHCP server with networking addressing scope 192.168.90.10-192.168.90.254.
-<note warning>Do not use static IP! Some services present in the network have fixed IP addresses, overlapping it causes unavailability of your solution and this service, also to other teams! Use the only DHCP for obtaining a network address.</note>
+<note warning>Do not use static IP! Some services in the network have fixed IP addresses; overlapping causes the unavailability of your solution and this service to other teams! Use only DHCP to obtain a network address.</note>
 To connect to the wireless network, use the following credentials:
@@ Line 63: / Line 80: @@
 === MQTT ===
-There is an MQTT Broker, binding WiFi PRIVATE network and the PUBLIC Internet. This way you can route MQTT messages from your end node devices connected to the ''internal.IOT'' network to the external tools i.e. cloud-based dashboard or storage via i.e. publishing from your end node IoT device through the PRIVATE network to MQTT Broker and subscribing to those messages from the cloud using PUBLIC Internet. \\
+There is an MQTT Broker, a binding WiFi PRIVATE network, and the PUBLIC Campus network. This way, you can route MQTT messages from your end node devices connected to the ''internal.IOT'' network to the external tools, i.e., cloud-based dashboard or storage via, i.e., publishing from your end node IoT device through the PRIVATE network to MQTT Broker and subscribing to those messages from the cloud using PUBLIC Campus network. Please note the context (thus, the IP address of the MQTT broker) changes depending on which device and network you're using. The following network schema should be of help {{ref>zmitacnetworkingiot}}. \\
-You can access it from the Internet PUBLIC network, using the following configuration and credentials:
+You can access the MQTT broker from the Campus PUBLIC network using the following configuration and credentials:
   * Address: 157.158.56.54
   * Port: 1883 for plain text, 8883 for secure communication
@@ Line 71: / Line 88: @@
   * Password: vrel2018
-You can also access it from the aforementioned PRIVATE network, using the following configuration and credentials:
+You can also access the MQTT broker from the ''internal.IOT'' PRIVATE network using the following configuration and credentials:
   * Address: 192.168.90.5
   * Port: 1883 for plain text, 8883 for secure communication
@@ Line 77: / Line 94: @@
   * Password: vrel2018
-=== Node Red and Node Red Dashboard ===
+<figure zmitacnetworkingiot>
-A Node RED server is working on same Raspberry Pi 2 as MQTT and in private address pool only, available through //internal.IoT// on 192.168.90.5 address, port 1880:
+{{:en:edu:zmitac:macro:iot:zmitac_network_infrastructure.png?600|}}
-  * [[http://192.168.90.5:1880]] - main editor
+<caption>Zmitac network infrastructure for the IoT labs</caption>
-  * [[http://192.168.90.5:1880/ui]] - Node RED dashboard
+</figure>
-Login using the following credentials:
+==== Tracing ====
-  * User: //contact supervisor//
+There is no direct debugging capability in this environment. Yet, it is possible to send log/trace messages to the PC console over a serial (serial over USB) port, which is used for flashing.
-  * Password: //contact supervisor//
+To open serial communication, one must invoke begin with the appropriate bps setting on the ''Serial'' singleton object (usually in ''Setup()'' function:
+<code c>
+Serial.begin(9600);
+</code>
+is the default speed, but you can change it in the ''platformio.ini'' file.
+It is possible to send virtually any message to the console (keep in mind, you need explicitly open Serial  Monitor in the VS code) using:
+<code c>
+...
+Serial.print(...);
+//or
+Serial.println(...);
+...
+</code>
+Both functions accept a wide range of argument types without needing to convert to string explicitly.
+<note tip>Note: there is a limit on the character set that is ASCII only. We suggest avoiding "special" characters, which are language-specific.</note>
 ==== Laboratory scenarios ====
-All teams share the same scenario yet please note that in particular, MQTT messages exchanged between devices shall be coordinated among team members not to overlay one another.
+All teams share the same scenario yet; please note that MQTT messages exchanged between devices shall be coordinated among team members so as not to overlay one another.
-<note tip>Mind keeping your code between meetings. It is regular that every next laboratory meeting you will extend your code by something extra.</note>
+<note tip>Mind keeping your code between meetings. It is regular that at every next laboratory meeting, you will extend your code by something extra.</note>
 <pagebreak>
 === Scenario Lab1 ===
 **Getting ready with your development environment**\\
@@ Line 96: / Line 129: @@
   - Sends a message via serial port to the serial port monitor: ''Hello World''
-<note tip>The GPIO the built-in LED is connected to is number 14. Physically it is located almost in the middle of the main board, under the display and its colour is blue.</note>
+<note tip>The GPIO the built-in LED is connected to is number 14. Physically, it is located almost in the middle of the mainboard, under the display, and its colour is blue.</note>
 <code c>
 #define LED_BUILTIN 14
 </code>
+Note, to use tracing with the ''Serial.print(...)'' singleton object, you need to tell VS Code which port to use to receive tracing messages you send from your code. Mind including in the ''platformio.ini'' file the appropriate configuration (here COM3 is a sample; check yours in PC configuration):
+<code>
+...
+monitor_port = COM3
+...
+</code>
+Obligatory:
+  * Provide a solution using ''millis()'' instead of ''delay()''
 Advanced:
-  * Use timer/interrupt to flash the LED instead of an infinite loop.
+  * Use a timer/interrupt to flash the LED instead of an infinite loop.
+  *
 Report:
   * Describe your approach and include source code in the report
 <pagebreak>
 === Scenario Lab2 ===
 ** Using LCD **\\
-In this scenario, you will write an application that writes on the LCD Display.\\
-Your code shall implement a message ''Hello IoT'' in the upper line, and a counter ticking every second in the lower one.\\
-Additionally, present a label ''LEFT/RIGHT/UP/DOWN'' when a key is pressed on the 6 keys keypad, located down to the LCD display module. The label should appear in a lower line of the LCD, along with ticking counter that is still working. The label should disappear when the key is released.
-To control LCD it is easiest to use a software library (add to the ''platformio.ini'' file:
+In this scenario, you will write an application that reports on the LCD Display.\\
+Your code shall implement a message ''Hello IoT'' in the upper line and a counter ticking every second in the lower one.\\
+Additionally, present a label ''LEFT/RIGHT/UP/DOWN'' when a key is pressed on the 6-key keypad located below the LCD display module. The label should appear in a lower line of the LCD, along with a ticking counter that is still working. The label should disappear when the key is released.
+== The LCD Display ==
+To control LCD, it is easiest to use a software library (add to the ''platformio.ini'' file:
 <code>
 ...
@@ Line 119: / Line 166: @@
 </code>
+Your LCD shield is 2x16 characters. To initialize it use the following GPIO definition:
-Your LCD shield is a 2x16 characters one. To initialise it use following GPIO definition:
 <code c>
 const int rs = 12, en = 13, d4 = 4, d5 = 0, d6 = 2, d7 = 14;
 LiquidCrystal lcd(rs, en, d4, d5, d6, d7);
 </code>
+Remember to initialize it in your code; you need to tell the library the physical organization of the display:
+<code c>
+...
+  lcd.begin(16,2); //2 lines, 16 characters each
+...
+</code>
+== Keypad ==
+The LCD shield has 6 buttons. One is hard-wired to the reset function, but other buttons (marked SELECT, UP, DOWN, RIGHT, LEFT) can be read through voltage analysis delivered into the AD0 (Analogue to Digital Converter, Channel 0) existing in the ESP8266 chip. Buttons are connected the way that they short the connection, and every button creates a separate voltage divider between pull-up and respectable resistance, different for each button (see figure {{ref>LCD1602buttons}} for connection diagram). To estimate readings, you can calculate the voltage appearing on the AD0 input using Ohm's law.
+<figure LCD1602buttons>
+{{:en:edu:zmitac:macro:embedeed:lab:bd7bbc8c7a07465bf42d955bc4635eca6f9ca3f0.jpeg?800|}}
+<caption>2x16 LCD shield connection diagram including buttons</caption>
+</figure>
+Note there is an assumption that you press only one button at a time. If no button is pressed, Vcc goes to the AD0, and you get maximum reading (see schematics on figure {{ref>LCD1602buttons}} above and warning note below, on readings AD0).
+<note warning>Because of the LCD shield construction and the fact that ESP8266 can accept out of the box on their AD0 input voltage range of 0..3.3V only (actually 0..1V but there is a voltage divider in the middle), you're unable to grab button SELECT pressed, because shorting it causes input voltage to on the AD0 to be ~3.7V, while when no button is pressed, the input voltage on AD0 is 5V. Both are far beyond the measurable range, so you will always get a maximum reading (1024) in both cases, and there is no way to distinguish them without electrical modification.</note>
+Reading an AD0 is as simple as:
+<code c>
+#define ADCPIN 0
+...
+  int nAdcReading = 0;
+...
+  nAD0 = analogRead(ADCPIN);
+...
+</code>
 Report:
-  * Describe how did you solve the problem of the asynchronous processing of the keypresses/releases.
+  * Describe how you solved the problem of the asynchronous key presses/releases processing.
   * Include source code.
 <pagebreak>
 === Scenario Lab3 ===
-** Presenting temperature and humidity on the local, LCD screen **\\
+** Presenting temperature and humidity on the local LCD screen **\\
-In this scenario, you will measure temperature and relative humidity using the attached DHT 11 / DHT 22 and present it on the screen.
+In this scenario, you will measure temperature and relative humidity using the attached DHT 11 and present it on the screen.
-In the first row, there should appear a label ''Temperature:'' or ''Humidity:'' while in the lower, measured value, right-aligned along with the measurement unit. Switching between presenting temperature and humidity should be possible using Up/Down keys from the keypad and changing temperature between Celsius and Fahrenheit, using Left/Right keys. Measurements should be present along with a unit: ''C/F'' (for temperature) and ''%Rh'' for humidity. The temperature should be present with one decimal point while humidity as an integer.
+In the first row, a label should appear ''Temperature:'' or ''Humidity:'' while in the lower, measured value, right-aligned along with the measurement unit. Switching between presenting temperature and humidity should be possible using the Up/Down keys from the keypad and changing the temperature between Celsius and Fahrenheit using the Left/Right keys. Measurements should include a unit: ''C/F'' (for temperature) and ''%Rh'' for humidity. The temperature should be present with one decimal point, while humidity should be an integer.
-<note tip>The DHT sensor is connected to the GPIO 5 pin. The blue sensor is DHT 11 while the white one is DHT 22. Mind to define appropriate constant definition in the source code. Choose between correct definition:</note>
+== Temperature and humidity sensor ==
+There is a DHT11 (blue) sensor connected to the __GPIO 5__.\\
+There are two libraries needed to handle reading from the sensor: a common sensor communication library and a specific one for DHT sensors, both by Adafruit, so two more entries are needed in the ''platformio.ini'' file, and you need to refer to it in the source code:
+<code>
+lib_deps =
+	adafruit/Adafruit Unified Sensor@^1.1.4
+	adafruit/DHT sensor library@^1.4.3
+</code>
+<code c>
+#include <Adafruit_Sensor.h>
+#include <DHT.h>
+</code>
+To access sensor readings, it is necessary to instantiate a communication class that binds the hardware to the code:
 <code c>
 #define DHTTYPE DHT11   // DHT 11
+#define DHTPIN 5
+DHT dht(DHTPIN, DHTTYPE,50);
 </code>
+It is also necessary to initialize the sensor class and give it some time to set up:
 <code c>
-#define DHTTYPE DHT22 // DHT 22  (AM2302), AM2321
+...
+dht.begin();
+delay(1000);
+...
+</code>
+The sensor class returns data (among others) in a float containing temperature (in C) and relative humidity (in per cent):
+<code c>
+...
+  float hum = dht.readHumidity();
+  float temp = dht.readTemperature();
+...
 </code>
 Report:
-  * Present a circuit with connections (LCD, keypad and sensor).
+  * Present a circuit with connections (LCD, keypad, and sensor).
   * Present an algorithm for both overall program flow and for obtaining measurements.
   * Include your code with appropriate comments.
@@ Line 151: / Line 255: @@
 === Scenario Lab4 ===
 ** Connecting to the network **\\
-In this scenario, you will use ESP 8266 networking. There are three, independent tasks to be completed today:
+Connect your ESP8266 (as a client, STA mode) to the PRIVATE //internal.IOT// network with an address obtained from the DHCP server. Present the connection status (''connected/disconnected'') in the upper row of the LCD and your ''IP address'' in the second line.
-  * List all WiFi networks over the serial port to the serial monitor.
-  * Implement a simple web server: using your ESP8266 prepare an Access Point (AP mode) you can connect to directly, using your mobile phone. Implement simple built-in LED control via a web browser, directly from your mobile phone. Present information on the LCD when the client connects to your ESP.
-<note important>Remeber to use unique SSID name - coordinate it with other teams!</note>
-  * Connect your ESP8266 (as a client, STA mode) to the PRIVATE //internal.IOT// network with an address obtained from the DHCP server. Present connection status (''connected/disconnected'') in the upper row of the LCD and your ''IP address'' in the second line.
 Report:
-  * Provide your observation on how much time (more-less) it takes to connect to the ESP configured as AP and eventually observe the delay when switching on and off the built-in LED. Note - provide estimated value, not a detailed measurement.
+  * When using ESP in STA mode, observe whether the subsequent running of the solution attaches a new or the same IP address via the DHCP server.
-  * When using ESP in STA mode, observe if the consequent running of the solution brings new or the same IP address attached via the DHCP server.
   * Include source code.
 <pagebreak>
 === Scenario Lab5 ===
 **Sending data to the network**\\
-In this scenario you're going to implement a fully functional IoT end-node, sending measurements to the MQTT Broker.
+In this scenario, you will implement a fully functional IoT end-node and send measurements to the MQTT Broker.
-Use your solution from the last step of Lab4 and also Lab3. Measure temperature and humidity, present them on the screen as in case of the Lab3 scenario and parallel, publish them as MQTT messages to the Broker.
+Use your solution from the last step of Lab4 and also Lab3. Measure temperature and humidity, present them on the screen as in the case of the Lab3 scenario, and parallel, publish them as MQTT messages to the Broker.
-<note important>Mind to make an agreement with other sections to let you do not overlap with MQTT Message Topics. They should be unique for all teams!</note>
+<note important>Mind agreeing with other sections to let you do not overlap with MQTT Message Topics. They should be unique for all teams!</note>
-Using any software-based MQTT client, subscribe to the messages using a PRIVATE or PUBLIC network and observe results. You can use a PC computer you're developing your solution for this task.
+Using any software-based MQTT client, subscribe to the messages using a PRIVATE or PUBLIC network and observe results. You can use a PC to develop a solution for this task.
-The simplest starting point is to use pub-sub MQTT client library:
+The simplest starting point is to use the pub-sub MQTT client library:
 <code c>
 #include <ESP8266WiFi.h>
 #include <PubSubClient.h>
 </code>
-You may also want to define MQTT topic(s) and constant payloads (i.e. those related to the last-will flag) using ''#define'' statement. It is also good idea to put connection constants here:
+You may also want to define MQTT topic(s) and constant payloads (i.e., those related to the last-will flag) using ''#define'' statement. It is also a good idea to put connection constants here:
 <code c>
 //WiFi and MQTT server credentials
@@ Line 190: / Line 290: @@
 Mind, ''192.168.90.5'' is your MQTT server address.
-To use pub-sub client you must instantiate a global object, using a network client, i.e. ''WiFiClient'':
+To use the pub-sub client, you must instantiate a global object using a network client, i.e., ''WiFiClient'':
 <code c>
 ...
@@ Line 199: / Line 299: @@
 </code>
-Then connect your MQTT pub-sub client to the server. You can define a separate function in case you need to repeat this process when connection is down (for any reason), to simplify reconnect procedure:
+Somewhere in the ''setup()'' function, once your wifi is already connected, bind server data to the MQTT client object:
+<code c>
+...
+client.setServer(<server>,1883); //standard port is 1883, change accordingly if needed
+...
+</code>
+Then, connect your MQTT pub-sub client to the server. You can define a separate function in case you need to repeat this process when the connection is down (for any reason) to simplify reconnect procedure:
 <code c>
@@ Line 219: / Line 326: @@
 </code>
-Advanced:
+To publish a single message, use:
-  * Implement a "last will" informing that device has lost connection (suddenly, not a via disconnect). Present last available measurements as persistent. Present device state changing a persistent message on connect/disconnect to let the subscribers know the state of your device. To implement controlled disconnect, use //select// key from the keypad (you can assume that you may need to restart device to get it back on the network but you also may implement a bistable logic: first click of the //select// triggers MQTT disconnect, the second click connects it back to the Broker).
+<code c>
+...
+client.publish(<topic>,<payload>);
+...
+</code>
+Note that receiving messages requires periodical execution of the ''client.loop();'' function. Add it to your code's ''void loop()...'' function. If you send messages only (publish but do not subscribe), using ''client.loop();'' is not obligatory.
+**Advanced**:
+  * Implement a "last will" informing that the device has lost connection (suddenly, not via disconnect)—present the last available measurements as persistent. Present the device state by changing a persistent message on connect/disconnect to let the subscribers know the state of your device. To implement controlled disconnect, use //select// key from the keypad (you can assume that you may need to restart the device to get it back on the network, but you also may implement a bistable logic: the first click of the //select// triggers MQTT disconnect, the second click connects it back to the Broker).
-To publish last-will message, you may use an extended version of the P''ubSubClient.connect()'' function (i.e. in your ''reconnect()'' function:
+To publish a last-will message, you may use an extended version of the P''ubSubClient.connect()'' function (i.e., in your ''reconnect()'' function:
 <code c>
 ...
@@ Line 228: / Line 344: @@
 ...
 </code>
-And once connected you may notify the dashboard (if any) that you're back, on-line:
+Once connected, you may notify the dashboard (if any) that you're back online:
 <code c>
 ...
@@ Line 236: / Line 352: @@
-Report:
+**Report**:
   * Provide your MQTT message Topics and Payload formats (semantics).
   * Include source code.
-<pagebreak>
-=== Scenario Lab6 ===
-** Visualising your data **\\
-In this scenario, use the public cloud tools or local ones, to visualise your data over time (Temperature, Humidity). Prepare a dashboard presenting current and former data, along with capabilities.
-Advanced:
-  * Prepare device state visualisation (''connected/disconnected/lost connection'').
-  * Use local dashboard's store or a database to present hourly information as a chart (temperature, humidity).
-<pagebreak>
-**Evaluation**
-As labs 3 through 5 constitute somehow a solid solution, every team is asked to prepare a presentation of their achievements to share it with other groups. The presentation should be some 10min in the form of the PDF presentation on-screen, using DLP projector in the laboratory room.
 <pagebreak>