Differences

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

--- en:edu:zmitac:macro:embedeed:lab:esp-on-site [2021/11/02 22:22] – pczekalski
+++ en:edu:zmitac:macro:embedeed:lab:esp-on-site [2023/04/05 12:23] (current) – [Task 1] pczekalski
@@ Line 2: / Line 2: @@
 While ESP 8266 (Espressiff) is, in general, a network processor with broad applications in IoT, here we focus on using it as an embedded-class microcontroller.\\
-===== Laboratory hardware in details =====
+===== Laboratory hardware in detail =====
 Each team is given the following configuration with a pre-built hardware stack.
@@ Line 11: / Line 11: @@
 <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?400|}}
@@ Line 25: / Line 25: @@
 </figure>
-<note warning>Do not try to read temperature and humidity too frequently. Once every 5s is quite enough both for information and safe enough to not let your readings race with the communication protocol. If you read too frequent, your sensor may not be able to deliver data on time and you will obtain a 'nan' (not a number) instead of temperature and humidity.</note>
+<note warning>Do not try to read temperature and humidity too frequently. Once every 5s is enough for information and safe enough not to let your readings race with the communication protocol. If you read too frequently, your sensor may not be able to deliver data on time, and you will obtain a 'nan' (not a number) instead of temperature and humidity.</note>
 ==== 2x16 LCD display shield ====
 [[https://www.dfrobot.com/wiki/index.php/Arduino_LCD_KeyPad_Shield_(SKU:_DFR0009)|2x16 characters LCD shield]] with keypad (buttons)
@@ Line 34: / Line 34: @@
 ===== Software =====
-You will be using Visual Studio Code with PlatformIO plugin to author software for the ESP8266.
+You will be using Visual Studio Code with the PlatformIO plugin to author software for the ESP8266.
-The framework (software stack) is Arduino compatible with the popular source code model:
+The framework (software stack) is Arduino-compatible with the popular source code model:
 <code c>
 #include <Arduino.h>
 void setup() {
-  // put your setup code here, to run once:
+  // put your setup code here to run once:
 }
 void loop() {
-  // put your main code here, to run repeatedly:
+  // put your main code here to run repeatedly:
 }
 </code>
-Firmware uploading is done via USB cable providing a COM (serial) port to the PC computer, you're developing software on. You can also use the same port to trace (send communicates) from your code to the console.
+Firmware uploading is done via a USB cable providing a COM (serial) port to the PC computer you're developing software on. You can also use the same port to trace (send communications) from your code to the console (so-called "serial monitor").
-<note important>Computers in the laboratory rooms 320 and 321 and 336 use "freezing" software which means that for every startup, computers are restored to their initial state. All changes done to the local storage are then lost! Keep your work in some other place between meetings i.e. [[http://gitlab.aei.polsl.pl|AEI GIT]], [[https://drive.google.com|Google Drive]] and so on.</note>
+<note important>Computers in laboratory rooms 320 and 321, and 336 use "freezing" software, meaning that computers are restored to their initial state for every startup. All changes done to the local storage are then lost! Keep your work in some other place between meetings i.e. [[http://gitlab.aei.polsl.pl|AEI GIT]], [[https://drive.google.com|Google Drive]] and so on.</note>
 ==== VSCode, PlatformIO and project configuration ====
-In any case, creating a new project under PlatformIO should follow this general settings, regarding Board and Framework (see figure {{ref>platformionewproject}}):
+In any case, creating a new project under PlatformIO should follow these general settings, 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}}
@@ Line 66: / Line 66: @@
 framework = arduino
 </code>
+It is also necessary to configure the serial port name that is used for uploading your firmware and monitoring. 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>
+<note tip>Check your COM port in the Device Manager (Windows) or terminal (dev for Linux / macOS). It can be different than in the example above!</note>
+=== 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 ribbot to execute most common actions</caption>
+</figure>
 === Libraries ===
@@ Line 88: / Line 107: @@
 === Hardware-software components and libraries ===
 Interfacing hardware requires the use of particular GPIOs. Laboratory nodes and hardware used needs specific configuration. 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:
@@ Line 109: / Line 129: @@
 </code>
-== LCD keypad ==
+It is also necessary to tell the library about the display organisation as there is a variety of configurations possible. Here, the organisation is 2 lines, 16 columns each, so in the code you need to explicitly initialise it:
-The LCD shield has 6 buttons. One of them 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 voltage appearing on the AD0 input using Ohm's law.
+<code c>
+...
+lcd.begin(16,2);
+...
+</code>
-<figure LCD1602buttons>
+Some useful methods of the ''LiquidCrystal'' class include (among others):
+<code c>
+...
+lcd.setCursor(x,y);
+...
+lcd.print(...);
+...
+</code>
-<caption>2x16 LCD shield button connection diagram</caption>
+<note tip>LCD module has a standard ASCII (US) set of characters embedded. It is possible to re-program it, i.e. for Polish-specific letters like ąęółśćżź and virtually any other symbol. If you do not re-program it, pleas use English alphabet only for messaging.</note>
+== Keypad ==
+The LCD shield has six buttons. One of them 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 note below).
+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>
+<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:
@@ Line 128: / Line 166: @@
   int nAdcReading = 0;
 ...
-  nAD0 = analogRead(ADCPIN);
+  nAdcReading = analogRead(ADCPIN);
 ...
 </code>
@@ Line 135: / Line 173: @@
 == 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 obviously you need to refer to it in the source code:
+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 obviously, 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
@@ Line 146: / Line 185: @@
 </code>
-To access sensor readings it is necessary to instantiate a communication class that binds the hardware to the 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
@@ Line 175: / Line 214: @@
 </code>
-To convert float into the string with formatting use ''sprintf'' function:
+To convert float into the string with formatting, use ''sprintf'' function:
 <code c>
 ...
@@ Line 183: / Line 222: @@
 ...
 </code>
-<note tip>''sprintf'' uses number of wildcards that are rendered with data. Refer to the c/c++ documentation on ''sprintf''. Here <code c>%2.1f</code> means: having float number render it to string using two digits before decimal point and one after. Temperature in our lab is always above 10C. <code c>%%</code> is an escape character to print a <code c>%</code> (percent) symbol.
+<note tip>''sprintf'' uses a number of wildcards that are 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, the same that is used for flashing.
+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, the same that is used for flashing.
-To open serial communication, one must invoke begin with appropriate bps setting on the ''Serial'' singleton object (usually in ''Setup()'' function:
+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.
+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>
@@ Line 201: / Line 240: @@
 Serial.println(...);
 </code>
-Both functions accept a wide range of argument types with no need to explicitly convert to string.
+Both functions accept a wide range of argument types with no need to convert to string explicitly.
 ===== Tasks to do during labs =====
 ==== Task 1 ====
 Write on the LCD screen your name (in the first line) and the city name you live in (in the second line).
+=== Advanced ===
+Make it animated (each line) in the loop, towards the left or right.
 ==== Task 2 ====
-Present on the LCD screen current environmental parameters: temperature and humidity, as read from the DHT sensor. In the first line, there should be headers stating: ''Temp.: '' and then temperature that rounds to 1 decimal place, and then the unit ''C'' (in Celsius). Use string formatting functions like ''sprintf'' and so on. The second line of the LCD screen should present relative humidity, in the following form ''Hum:'', then relative humidity in per cent (rounded to the integer) and then unit as ''%Rh''.
+Present on the LCD screen set of current environmental parameters: temperature and humidity, as read from the DHT sensor. In the first line, there should be headers stating: ''Temp.: '' and then temperature that rounds to 1 decimal place, and then the unit ''C'' (in Celsius). Use string formatting functions like ''sprintf'' and so on. The second line of the LCD screen should present relative humidity, in the following form ''Hum.:'', then relative humidity in per cent (rounded to the integer) and then unit as ''%Rh''.
 Update information at most every 1s, but on the other hand, short enough to notify changes when keeping the sensor in your hand or blowing into it. 5s seems to be a reasonable delay between consecutive readings.
 ==== Task 3 ====
-Present on the LCD screen the absolute value of the ADC 0 (analogue to digital converter) value and button name that has been pressed.
+Present on the LCD screen the absolute value of the ADC 0 (analogue to digital converter) value and the button name that has been pressed.
-The Upper LCD screen line should present current AD0 readings and the lower should present decoded button name. Mind, every LCD shield is slightly different, so you may need to run an absolute AD0 value reader to grab values reported when particular buttons are pressed, then update your solution with a decoder function that will return the button name, as detected by the absolute AD0 readings.
+The Upper LCD screen line should present current AD0 readings, and the lower should present decoded button name. Mind, every LCD shield is slightly different, so you may need to run an absolute AD0 value reader to grab values reported when particular buttons are pressed, then update your solution with a decoder function that will return the button name, as detected by the absolute AD0 readings.
-Note, ESP8266 default AD0 resolution is 10 bits, so AD0 reading can range from 1 to 1024 (or 0 to 1023).
+Note that ESP8266's default AD0 resolution is 10 bits, so AD0 reading can range from 0 to 1024.
+<note tip>One of the buttons won't work. It is natural to ask the supervisor for details if you're interested in why.</note>
+<note tip>Bonus question, why is there 1024 reading, while the lowest is 0 and it is 10 bits range (so 0..1023 is valid)?</note>