Fullscreen HTML5Med Res (??MB)HTML4

Make it with Micromite Phil Boyce – hands on with the mighty PIC-powered, BASIC microcontroller Part 29: Internet connection with an ESP32 Wi-Fi module – Part 2 L ast month, we began to explore how to use a low-cost ESP32 Wi-Fi module with a Micromite so that data could be extracted from the Internet. We initially worked through a simple test that used a USB-to-serial module (connected directly to the ESP32) to ensure that the Wi-Fi module responded to AT commands typed into a Terminal window (see Fig.5 from last month). We then connected the ESP32 directly to the Micromite Keyring Computer (MKC) with just five wires and downloaded a program (NTP_TimeDemo.txt) to extract time and date information from the Internet and then display it in the Terminal window. This month, we will continue exploring the topic of Wi-Fi by first explaining briefly how the NTP_TimeDemo program works. Then we will move onto another neat little demo program that extracts real-time weather data from the Internet. However, for this code to work we will first need to sign up to a free service provider (openweathermap.org) – and we’ll show you how to do this too. TimeDemo We start by explaining how last month’s NTP_TimeDemo program works. Bearing in mind you are reading an electronics magazine rather than a coding magazine; we will discuss the ‘building block’ steps used rather than going into the full details behind each and every command and line of code. Remember that the Micromite User Manual can be referred to for explanations of any MMBASIC command used in the program. Likewise, the use and structure of each AT Command is detailed on the ESP manufacturer’s website (http://bit.ly/pe-may21-exp). Micromite code The code in this article is available for download from the PE website. 54 The main building-blocks of the NTP_ TimeDemo program are as follows – each one is briefly explained in a separate bullet point:  The program begins with five lines of code that configure various setting values – namely, your Wi-Fi SSID and password, and the web address of up to three NTP time servers. These values are then used later in the program. The reason behind defining them at the start of the program is so that it makes it easier to locate them within the program if you need to alter any of them.  Next, the Debug variable is set to a value of 0 or a non-zero value. When set to 0, the Terminal screen limits the information displayed to just the data that is relevant. Setting Debug to any other value (non-zero) will result in more details being shown, such as the full responses from the ESP32 to any AT command it receives. Hopefully, you tried Debug values of 0 and 1, as explained near the end of last month’s article (also refer to Fig.7 from last month).  The string array AT_Response$(40) is declared so that there is room to store the responses from the ESP32 to any AT command that it receives. Most AT Commands will result in just one or two response lines, but some commands will potentially produce a lot more responses, as we shall see later in this article.  The serial COM port that the ESP32 is connected to is opened for communication at a baud rate of 115,200. We also set a large receive buffer (with a storage capacity of 8192 bytes) so that we don’t lose any data bytes sent from the ESP32  Two Escape Codes are used to clear the Terminal screen, and to position the cursor in the top-left corner  A series of AT commands are then sent to configure the ESP32 module. Each is sent one at a time with a subroutine (SendAT), and the response is then checked by another subroutine (CheckAT). Both subroutines are explained later in more detail (along with the variables used, such as ValuePointer). However, for now, let’s simply look at what each AT command is doing in the process flow of the program.  ATE1 (switch Echo on). This makes the ESP32 module immediately respond with the AT command that it was sent. It can be used to ensure that the response bytes received are indeed relevant to the command sent (rather than to an earlier command sent).  AT+CWMODE? (check the ESP32’s mode: Access Point or Station). The ESP32 needs to be in ‘Station’ mode, and hence needs to be set to a value of 1. In the program, we check its value, and if not set to Station mode, then we set it to 1 with the AT command AT+MODE=1  AT+CIPSTATUS (obtain the connection status details). This command returns a value that indicates the current connection status. When the ESP32 is used for the first time, it will not be connected to any Wi-Fi network, so the status returned will be 0 or 1. But once the ESP32 has been configured with your local Wi-Fi network’s SSID and password, then on powerup, the ESP32 will automatically attempt to reconnect to the network previously used (the values are all stored in memory, until changed). A CIPSTATUS value of 2, or more, indicates that a connection is made. So, in our program we check for a value of less than 2, in which case it indicates that we need to configure the ESP32 – see next command. Practical Electronics | June | 2021  AT+CWJAP=”SSID”,”Password” (connect to an Access Point). This command uses the SSID$ and PWD$ information (set in the first two lines at the start of the program) to connect the ESP32 module to your wireless router. Providing the SSID and password are correct, the ESP32 should connect to your wireless network without any issues. Note that CHR$(34) simply defines the quote (“) character – and these are required around the SSID and password parameters.  AT+CIPSNTPCFG=1,0,”NTP1”,”NTP2”,”NTP3” (set the time-zone, and define the NTP servers). This command uses the three NTP servers defined at the start of the program; ie, the information stored in NTP1$, NTP2$, and NTP3$ (again, using CHR$(34) where necessary to surround each parameter). Note: the second parameter (ie, the ‘0’, highlighted in bold) defines the offset from Coordinated Universal Time (UTC) in whole hours. Since writing this article, the UK has moved into British Summer Time, and hence this can be changed to ‘-1’ to reflect the one-hour difference from UTC (try it!)  AT+CIPSNTPTIME? (get the time). Not much to say here apart from the fact that the time information is returned in the response that gets stored in AT_Response$(2) (see the CheckAT section opposite for more details on the structure of response data from the ESP32). For completeness, the ESP32 responds to this command with three lines; for example: being sought, and if so, the subroutine ends. While waiting for a response, the code continually checks the value of the MMBASIC Timer (which is set to zero immediately after the AT command has been sent) and compares it with the value in AT_TimeOut. If the Timer value is bigger than the value loaded into AT_TimeOut, then the subroutine ends. This explains the functionality of this subroutine. If you are familiar with MMBASIC then you can probably understand each line of code in the subroutine. However, if you are not a coder, or are not yet familiar with MMBASIC, then the above explanation provides you with a high-level understanding of what is happening. SUB CheckAT This building-block overview should give you a better understanding of how the program works. However, there are two critical subroutines used within the program that also need explaining: SUB SendAT and SUB CheckAT. This subroutine helps to process any response line(s) from the ESP32. It checks that the AT command sent is indeed ‘echoed’ back, and hence it ensures that any subsequent response lines are relevant to the AT command that was sent. So, this subroutine begins by checking that AT_Response$(1) (ie, the first response line) matches AT_CMD$, and if not, it exits with an error message. If it does match (as it should), then it next checks that the last response line contains ‘OK’ (again, as it should). The number of response-lines received (by calling SUB SendAT) is stored in the variable AT_ResponseLineCnt – and this gets incremented in SUB SendAT whenever it receives a completed response line. The value in ValuePointer is used to reference which response line contains the data we are actually interested in (for the AT command that was sent). The value in ValueStartPosition then points to where within the response line the relevant data is contained (ie, which character position the relevant data starts at). This data is then stored in the string Response$ for potential use by the main program code. Referring back to the three-line example response above (for requesting the Internet server time by sending AT command: AT+CIPSNTPTIME?), you will see the relevant data was contained in the second line starting at the 14th character – ie, ValuePointer=2 and ValueStartPosition=14 SUB SendAT OpenWeather Map AT+CIPSNTPTIME? +CIPSNTPTIME:Wed Apr 21 11:31:03 2021 OK  Finally, the PRINT command displays the time and date on the Terminal screen. It effectively displays the string content of the second line of the response (ie, AT_Response$(2)) starting from the 14th character (check this in the example three-line response above). This subroutine deals with sending an AT command; and Before downloading the next demo program (WeatherDemo.txt), it also waits for the response(s) sent by the ESP32. This we first need to sign-up to the data provider openweathermap. subroutine can also check for a specific response (and if org. Once you have completed the registration process, you detected, causes the subroutine to end). If no response is will be provided with a unique ‘account code’ (or for our received within a certain timeframe, experienced readers, an API key). This then the subroutine ends (returning to API key is then needed to be set in the the main program code). program code so that our program can The command to be sent is loaded into extract the weather data for any valid AT_CMD$, the timeout period (in mS) is location requested. Without an API key, loaded into AT_TimeOut, and any specific you will not be able to access any data response being sought (ie, matched) is from openweathermap.org loaded into AT_Success$. These are Registration is free, and it is relatively all set in the main program code prior to straightforward, so let’s work through calling SUB SendAT. Once the command this process. Note that the following steps is sent, the subroutine waits for any were correct at the time of writing this characters received into the COM port’s article. The process may change in the input buffer. Any characters received are future, but the concept will remain the worked through (in order) byte-by-byte; same in that you will sign up for your and the receipt of a carriage-return plus very own unique API key. line feed (ie, CHR$(10) and CHR$(13)) will signify the end of a response-line. Step 1 The end result of this subroutine is Open a browser and visit openweathermap. that any response received from the org. Then click on the Sign In link (near ESP32 is stored, line-by-line, in the the top-right corner) followed by Create array AT_Response$(x). Upon receipt Fig.1. To create an openweathermap.org an Account (under the Username and of a response, it is checked with AT_ account, begin by entering a username, email Password input boxes). This will take Success$ to see if it matches what is address and password. you to the start of the sign-up process (see Practical Electronics | June | 2021 55 should be automatically logged in, but if not, use your login details as entered in Step 1). From the website, you will see your unique API key that has been assigned to you. Make a note of this (see Fig.5). If you have trouble locating your API key, then click on your name (shown near the top-right corner on the ‘Menu Bar’ across the top of the page) and select My API Keys from the dropdown list. Step 6 Fig.2. You need to confirm a few parameters to complete your request for an account. Fig.1). Simply enter a valid email address, along with your choice of username and password. These will be used to log into your openweathermap.org account. Step 2 Scroll down, tick the relevant tick-boxes, and then click on the Create Account button (see Fig.2). Step 3 You should see a confirmation message appear, confirming that you have been sent an email. This will be sent to the email address entered in Step 1 (see Fig.3). Step 4 Open the email and click on the Verify your email button (see Fig.4). Step 5 You will then be taken back to the openweathermap.org website (you For much more detail about using this data service, click on the API link on the menu bar, and then click on API doc for Current Weather Data (see Fig.6). This will take you to a page giving lots of useful information and examples. Step 7 Now that you have your unique API key, you can test it directly from within your browser. Note: after sign-up, you may need to wait for your API key to be activated – this can take up to an hour or two, but certainly no longer than 24 hours. To test that your API key is active, open a new tab in your browser, and carefully type the following into your address bar: api.openweathermap.org/data/2.5/ weather?q=London,uk&APPID=XXXXXX Here XXXXXX is your API key. On pressing Enter, you should see lots of text appear on a webpage (see Fig.7). This text is the current weather data for the location entered in the address bar (in this case, London). Note that this step will only work if you correctly type in the above with a valid, active API key. So how do we use the ESP32 to use this data? JSON Fig.3. Once you have completed a successful account request, an email confirmation will be sent to you. The text you see returned (as shown in Fig.7) is what the ESP32 module will receive. A quick glance and you will see Fig.4. Click on the ‘Verify your email’ button to complete the sign-up process. 56 Fig.5. On returning to the website, you can log in to view your API key. lots of quotes, commas, curly brackets, square brackets, and colons. In computer speak, this is a JSON (JavaScript Object Notation) response, and its format is typical of that for data that is readily available from the Internet. The structure generally follows the template of : “parameter name”:”parameter value” The WeatherDemo.txt program includes an additional subroutine, SUB GetData that breaks this data up into name and value, and then formats it neatly for display on the Terminal screen. How this subroutine works is a bit beyond the scope of this article, so for now we’ll just simply say that this subroutine formats the JSON response for displaying the data on the Terminal screen. WeatherDemo Now that you have your unique API key, download the program WeatherDemo. txt from the June 2021 page of the PE website. Once this program is installed on your Micromite, use the Editor to change the first line of program code so that it is set with your unique API code. You need to get this exact, so take your time, and ensure it matches 100%. At the time of writing, the API key will comprise 32 hexadecimal characters. In addition, you will also need to enter your Wi-Fi network’s SSID and password at the start of the program. This is done in the same way as setting up the NTP_TimeDemo program. Once these three settings have been made, RUN the program, and then enter a country, city, or town location (such as London) and press Enter. You should then see a response similar Practical Electronics | June | 2021 Fig.6. Click on the ‘API doc’ link to view more details as to how to use the openweathermap.org data service. Fig.7. You can test that your API key is active by using the browser’s address bar (see text). Here is the resultant weather data for London. to that shown in Fig.8. If you enter an unrecognised location, you will see a message saying so. Note that there tends to be a US bias when it comes to location names, so entering ‘Stratford’ will result in (one of) the US Stratford(s) as opposed to the UK Stratford – remember also that there is more than one Stratford in the UK! In this situation, be more specific with the area; ie, Poplar (for the one in London, as opposed to Suffolk or Warwickshire), and then you should see the London, UK location. So, do check that the resultant ‘Country’ parameter shown on the screen displays “country”:“GB” if you’re after British locations (as opposed to “country”:“US” which refers to American locations). If you look through the weather data that is returned, you will see things such as the current temperature, min and max temperature, cloud cover, pressure, humidity and so on. Each line on the screen is stored in the array AT_Response$(x) and can be used in your own main program code to perform certain actions. For example, you could connect a graphical TFT screen to the MKC, and create a weather station that displays relevant data and icons based on the data stored in the AT_Response$() array. Now there’s a challenge for you! Next month We’ll see how the WeatherDemo program uses AT commands to send a request to openweathermap.org for weather data. Plus, we’ll unveil our first Make It Questions? Please email Phil at: Wi t h M i c r o m i t e contactus<at>micromite.org PCB. Until then, have FUN! Practical Electronics | June | 2021 Fig.8. Entering a valid location into the WeatherDemo.txt program will result in the live weather data being shown. Here we can see how cold it is in Antarctica! 57