RAU6 Dokuwiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== IoT Networks: Laboratory 1 - Introduction ======
Introduction to IoT programming.

You will likely use Visual Studio Code with the PlatformIO plugin during labs to author code for the IoT device. 
Devices are connected to the PC via a USB cable, but they expose a serial port to the operating system. You need to check the COM port number, which varies from PC to PC, and configure your project accordingly.
<note tip>You can use the default COM port transfer speed, but in any case, when using the COM port as a trace, you need to configure the transmission speed on the code side. The default is 9600 (bps).</note>

==== Hardware ====
Each team is given the following IoT microcontroller:
  * [[https://wiki.wemos.cc/products:d1:d1|Wemos D1 R2]] development board:
<figure wemosd1r2>
{{:en:edu:zmitac:macro:iot:3122a92a-8355-4148-8041-390ca7c39605.jpg?200|}}
<caption>WeMos D1 R2 development board</caption>
</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|}}
<caption>WeMos D1 R2 pinout</caption>
</figure>


  * DHT 11 temperature and humidity sensor
<figure DHT>
{{:en:edu:zmitac:macro:iot:dht11_gallery_image-1.jpg?100 |}}
<caption>DHT 11 temperature and humidity sensors</caption>
</figure>
  * [[https://www.dfrobot.com/wiki/index.php/Arduino_LCD_KeyPad_Shield_(SKU:_DFR0009)|2x16 characters LCD shield]] with keypad
<figure lcd2x16shield>
{{: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>

==== VSCode, PlatformIO, and project configuration ====

In any case, creating a new project under PlatformIO should follow this general setting, regarding Board and Framework (see figure {{ref>platformionewproject}}):
<figure platformionewproject>
{{: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]
platform = espressif8266
board = d1_mini
framework = arduino
</code>

Configuring the serial port name used for uploading your firmware and monitoring is also necessary. 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>

=== Hardware-software components and libraries ===
Interfacing hardware requires the use of particular GPIOs. Laboratory nodes and hardware used need specific configurations. The following chunks of code will help to set up proper hardware-software configuration.

== LCD display ==
Built-in LED on the microcontroller development board can help to manage simple tracing of the code execution:
<code c>
#define LED_BUILTIN 14
</code>

Your LCD shield is a 2x16 character driven by a Hitachi HD44780 controller. You can use a library to use it easily. The PlatformIO will pull the library automatically if defined in the ''platformio.ini'' file:
<code c>
lib_deps = Arduino-libraries/LiquidCrystal
</code>

<code c>
#include <LiquidCrystal.h>
</code>

To initialize it and instantiate the controller object, use the following GPIO definition and initialization:
<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>

It is also necessary to tell the library about the display organization, as various configurations are possible. Here, the organization is 2 lines, 16 columns each, so in the code, you need to explicitly initialize it:
<code c>
...
lcd.begin(16,2);
...
</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 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>


== 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 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>
...
dht.begin();
delay(1000);
...
</code>

The sensor class returns data (among others) in a float containing temperature (in C) and relative humidity (in percent):
<code c>
...
  float hum = dht.readHumidity();
  float temp = dht.readTemperature();
...
</code>
==== Software ====
String formatting may be a challenge. A straightforward approach is to allocate a character buffer of the size of the LCD or just one display's line, or any other size, large enough to handle your text.
<code c>
...
char buffer [50];
...
</code>

To convert float into the string with formatting, use ''sprintf'' function:
<code c>
...
  sprintf(buffer,"%2.1f C",temp);
...
  sprintf(buffer,"%2.1f%%Rh",hum);
...
</code>
<note tip>''sprintf'' uses a number of wildcards rendered with data. Refer to the c/c++ documentation on ''sprintf''. Here <code c>%2.1f</code> means: having a float number render it to string using two digits before the decimal point and one after. The temperature in our lab is always above 10C. <code c>%%</code> is an escape character to print a <code c>%</code> (percent) symbol.
<code c>
delay(time)
</code> is measured in milliseconds.</note>
==== Tracing ====
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 used for flashing.
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>
9600 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.


==== 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 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 in the network have fixed IP addresses; overlapping causes the unavailability of your solution and this service, also to other teams! Use only DHCP for obtaining a network address.</note>

To connect to the wireless network, use the following credentials:
  * SSID: internal.IOT
  * Passkey: IoTlab32768
  * IP address: DHCP, 192.168.90.10-192.168.90.254

==== Network services ====

=== MQTT ===
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 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
  * User: vrel
  * Password: vrel2018

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
  * User: vrel
  * Password: vrel2018

<figure zmitacnetworkingiot>
{{:en:edu:zmitac:macro:iot:zmitac_network_infrastructure.png?600|}}
<caption>Zmitac network infrastructure for the IoT labs</caption>
</figure>

=== Node Red and Node Red Dashboard ===
A Node RED server is working on the same Raspberry Pi 2 as MQTT and in a private address pool only, available through //internal.IoT// on 192.168.90.5 address, port 1880: 
  * [[http://192.168.90.5:1880]] - main editor
  * [[http://192.168.90.5:1880/ui]] - Node RED dashboard
Log in using the following credentials:
  * User: //contact supervisor//
  * Password: //contact supervisor//

==== Laboratory scenarios ====
All teams share the same scenario yet; please note that MQTT messages exchanged between devices shall be coordinated among team members not to overlay one another.
<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 1 ===
**Getting ready with your development environment**\\
In this scenario, you will write your first "Hello World" application for ESP8266.
Using the selected IDE, write code that:
  - Flashes built-in LED every 1 second (1s on; 1s off);
  - 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 mainboard, under the display and its colour is blue.</note>
<code c>
...
#define LED_BUILTIN 14
...
</code>

The standard serial port speed is 9600 (bps). Connect the COM port monitor (a plug icon in the PlatformIO toolbar) once you compile and upload your code to see the "Hello World" message.
<code c>
...
Serial.begin(9600);
...
</code>

Advanced:
  * 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 2 ===
** 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.\\

Report:
  * Present algorithm.
  * Include source code.
<pagebreak>

=== Scenario 3 ===
** Using Keypad **\\
Extend Scenario 2 with a counter that increments on the keypress of the Keypad Shield (any but SELECT!).

Report:
  * Describe how you solved the problem of the asynchronous key presses/releases processing.
  * Include source code.
<pagebreak>