Fullscreen HTML5Med Res (??MB)HTML4

where the PicoMite meets the Web The WebMite a Raspberry Pi Pico with MMBasic, WiFi and Internet Connectivity | Article and MMBasic by Geoff Graham | WebMite firmware by Peter Mather | M ost readers will be familiar with the PicoMite, which we introduced in January 2022 (siliconchip. au/Article/15177). It is a Raspberry Pi Pico programmed in the MMBasic language and is a very capable microcontroller at an extremely low price. Following that, the Raspberry Pi Foundation released the Raspberry Pi Pico W, which is very similar to the original Pico but with the addition of a WiFi module. In theory, you could take any Pico project and then add an internet connection… but it is not quite that easy. The internet and its protocols are complicated, with many protocol layers. That means it takes an experienced programmer to accomplish even the simplest task. That is where our new WebMite comes in. We have added to the Pico­ Mite firmware support for the wireless capability of the Pico W and the protocols (802.11n, DHCP, WPA-PSK, TCP, IP, TLS, HTML etc) that are necessary to access the internet. With the WebMite, you can easily: ; Connect to a WiFi network with a specified SSID and password. ; Implement a web server with advanced features. ; Query websites for data. ; Get the current time/date. ; Check the weather. ; Send emails. ; Publish and retrieve data from MQTT broker services (for IoT messaging). ; Remotely edit BASIC programs. ; Transfer files to and from the Pico over WiFi using TFTP. These features have been implemented using an easy-to-use programming framework with the flexibility to handle the unusual aspects of accessing internet resources. Later in this article, we will present an example of a simple web server that uses just 12 lines of BASIC code – that is all it takes to serve up a web page for your projects. The MMBasic language is an easyto-use programming environment. With the WebMite, you can easily add internet features to complex gadgets with touch-sensitive LCD panels, SD card support for storing files, connection to various sensors and so on. Loading the firmware As the hardware is already built for you (the Raspberry Pi Pico W, available for under $10), all you have to do to create the WebMite is load the appropriate firmware onto that module. Luckily, that is easy. The WebMite firmware c a n b e All that you need for the WebMite is an affordable Raspberry Pi Pico W. Australia's electronics magazine downloaded for free from the Silicon Chip website or the author’s website at http://geoffg.net/webmite.html It comes with a comprehensive 178-page user manual that includes a tutorial on BASIC programming for beginners. Loading the WebMite firmware on the Raspberry Pi Pico W is the same as with the original Raspberry Pi Pico and is described in the user manual. Essentially, you plug your Pico W into a USB port on your computer while holding down the button on the top of the module. The Pico will then create a pseudo USB drive on your computer, and you just drag and drop the WebMite firmware into that. When the transfer has been completed, the Pico will restart running the WebMite firmware and create a serial connection via its USB port. Once it has done that, you can use a terminal emulator like Tera Term (http://tera-term.en.lo4d.com) to access the WebMite’s console. If you then hit the Enter key on your keyboard, you will see the MMBasic prompt, a greater-than character (>). You can configure the WebMite, test commands, edit programs, and run them at this command prompt. Internal file system Before we get into the internet capabilities of the WebMite, we need to introduce the internal file system. It looks like an SD card to the programmer, but files are actually stored in the flash memory chip of the Raspberry Pi Pico W. You can open files for reading and writing, create and navigate directories and do all the things you can do with a physically attached SD card. That includes using the normal BASIC file commands such as OPEN, CLOSE, FILES etc. If you connect a removable SD card to the WebMite, it is accessed as drive “B:” while the internal file system is drive “A:”. siliconchip.com.au This internal file system has a capacity of about 600kB, and it is automatically created by the firmware when MMBasic is loaded onto the Raspberry Pi Pico (W). This is especially useful on the WebMite because, to set up a web server, you need somewhere to store the web pages and images to serve. The internal file system is perfect for the job. This feature was introduced in the last release of the PicoMite firmware, so if you are currently using the Pico­ Mite or the VGA PicoMite, consider upgrading to get this feature. Connecting to WiFi The WebMite can connect to any WiFi network running 802.11n (2.4GHz) with WPA-PSK security. The encryption must be either TKIP or AES (or both) and DHCP must be enabled on your router. These are standard requirements for most WiFi-enabled gadgets, so most routers are set up like this by default. To log into your network, use the command OPTION WIFI at the WebMite’s command prompt. For example, if your network is called MyNetwork and the password is secret, you would use this command at the command prompt (the quote characters are required): OPTION WIFI “MyNetwork”, “secret” This will be remembered and will be automatically reapplied on every reboot. It will also cause the WebMite to restart and drop the USB connection, so you will have to reconnect to access the command prompt again. You can check the IP address that your router gave to the WebMite with the command: PRINT MM.INFO(IP ADDRESS) Most routers will allocate the same address to the WebMite on every reboot. However, if you want to ensure the address will not change, go into your router’s configuration and allocate a static IP address to the WebMite. Incidentally, you can have many WebMites on your network with different IP addresses and they will not conflict. Remote connection via Telnet The WebMite could be installed in some inaccessible place, so the firmware allows you to use Telnet over your WiFi network to access siliconchip.com.au Screen 1: You can connect to the WebMite using Telnet over WiFi via Tera Term. This lets you do everything that you can do via a USB cable, including editing and running programs. the MMBasic console. This feature is enabled with the command: OPTION TELNET CONSOLE ON As before, this command will be remembered and automatically applied on every reboot. It will also cause the processor to restart, so you will have to reconnect to regain the command prompt. The recommended terminal emulator, Tera Term, supports Telnet, so all you need do is select that in the new connection dialog box and enter the WebMite’s IP address, as shown in Screen 1. You can do everything you can via a physical USB connection using Telnet, including editing and running programs... all over the WiFi! You can also use PuTTY in Windows or the telnet command in Linux or macOS (it is no longer part of the macOS by default, but you can install it via Homebrew). File transfers Another handy feature is the ability to transfer files to and from the WebMite over WiFi. This is done using TFTP (Trivial File Transfer Protocol) from a Windows, Mac or Linux computer. In Windows, this is built into the operating system; however, you must enable it first by going to the Control Panel, selecting “Programs and Features”, then “Turn Windows features on or off”. Finally, scroll down the list and tick TFTP Client. You can then send a file to the WebMite’s internal file system (drive A:) Australia's electronics magazine using the following command in a Command or Power Shell window: TFTP -i ipaddress PUT filename This protocol can also be used to retrieve files from the WebMite, eg: TFTP -i ipaddress GET filename Long string support Another new feature of the WebMite that needs explaining is long strings. Regular string (text) variables in MMBasic can store a maximum of 255 characters. However, most data transferred between an internet client and server is much longer than that. The WebMite has a series of routines called long strings to address this need. These work with strings of any length, limited only by the available RAM. Using them, you can pull long strings apart, search for specified text, copy parts of the text and so on. They mimic what the standard string functions do in MMBasic, although they are slower and clunkier (which is why they are only used when required). To allocate RAM for holding a long string, you need to declare an array of integers with a size (in bytes) that will fit the longest string expected. While declared as integers, the string routines do not store numbers in these; they are just used as memory blocks. For example: DIM INTEGER StrA(512),StrB(512) Each array is 512 integers, and an integer is eight bytes, so each array occupies 4KB of RAM (512B × 8). A August 2023  31 character is one byte, so each can store strings of up to 4,096 characters. These arrays are passed to the long string routines using empty brackets. For example, to copy StrB to StrA, you can use the command: LONG STRING COPY StrA(), StrB() Long strings are documented in the user manual. It is worthwhile to familiarise yourself with them as they are invaluable when dealing with the large amount of data sent over the internet. Web server functions Assuming that you have connected the WebMite to your WiFi network as described above, the next step in implementing a web server is to tell the firmware to start a TCP server. This is done with another OPTION command as follows (it must be entered at the command prompt): OPTION TCP SERVER PORT 80 Port 80 is the standard HTTP port, normally used for serving web pages. As with the other OPTION commands, this only needs to be entered once and will be remembered. It will also cause the WebMite to restart. In your program, you tell the server what to do if an incoming request is received with the command WEB TCP INTERRUPT. This specifies a subroutine that the firmware will call (interrupting the main program) whenever a request is received. Within your interrupt subroutine, you can retrieve the remote request using the command WEB TCP READ. This command needs a long string buffer for holding the text of the remote request (see above for a description of long strings). The request from the remote browser will look something like that shown in Screen 2. In this case, the browser is requesting a web page called “page. html”, but it could be the name of an image file or even a single forward slash (/), which is a request for the default page of the website (typically called “index.html”). The request could also be a notification that the user has clicked on a button or control on the web page and is expecting the WebMite to take some action. In that case, the text between the keywords GET and HTML will indicate the control involved and the user’s action. Some queries may use the keyword POST instead of GET, but the intention is the same; whatever is between the first keyword and HTML is the request from the remote browser. Sending a web page If the request is for a web page, you can send it using WEB TRANSMIT PAGE. This specifies a file formatted in HTML residing in the internal file system of the WebMite (described above) or on an SD card (if connected). When the firmware transmits the web page, it will scan the page for any embedded BASIC variables surrounded by curly brackets. It will substitute these with the current value of the variable. This facility lets you insert data your BASIC program has collected into the web page. For example, if your program had a variable called Humid which had the value of 42 and represented the current humidity, the following text in your HTML file: The current humidity is {Humid}% Screen 2: a web request from a remote browser will look like this. The important part is the text between the keywords GET and HTTP. In this case, the browser is requesting a web page called “page.html”, but it could be an image file or some text indicating that the user has clicked a control on the web page. 32 Silicon Chip Australia's electronics magazine Displays in the client’s browser as: The current humidity is 42% You can also send non web pages using the WEB TRANSMIT FILE command, which will send images, audio files and much more (without substituting for variables). Using these commands, you can create a web server that will serve up pages displaying whatever data you have collected. This server could also respond to remote commands from the user to turn on/off motors, pumps etc, as required. Whatever the WebMite can do locally, it can also do remotely! A simple web server This example will display the temperature and humidity in a fictional greenhouse. From the comfort of your living room, you could call up the web page on your phone, tablet or computer and see the current conditions for your plants, even though they may be located at the bottom of your garden. The whole program is shown in Program 1 and is about as simple as it gets at just 17 lines. The web page is even smaller, at only three lines. The first line of the program starts the web server and specifies the interrupt subroutine to be used for any incoming requests (“WebInterrupt”). The next four lines implement a simple loop where a DHT22 sensor (connected to the GP28 pin, as shown in Fig.1) is queried for the current temperature and humidity ten seconds. The command specifies that the results should be saved in CurrentTemp and CurrentHumid variables. The WebInterrupt subroutine, starting at line 7, is where the work is done Fig.1: here’s how to connect the DHT22 temperature/humidity sensor for the sample web server program in Program 1. siliconchip.com.au WEB TCP INTERRUPT WebInterrupt DO BITBANG HUMID GP28, CurrentTemp, CurrentHumid PAUSE 10000 LOOP SUB WebInterrupt LOCAL INTEGER a, p, t, b(512) FOR a = 1 To MM.INFO(MAX CONNECTIONS) WEB TCP READ a, b() p = LINSTR(b(), “GET”) t = LINSTR(b(), “HTTP”) If (p > 0) And (t > p) Then WEB TRANSMIT PAGE a, “index.html” ENDIF NEXT a END SUB in serving up the web page. Whenever the TCP server receives a request, it will call this subroutine, interrupting whatever the BASIC program was doing at the time. This subroutine first defines several local integer variables, including an array of integers called b(), used as a long string variable to hold the incoming data. The web server can handle multiple simultaneous requests, so the program starts a loop stepping through all possible connections. The WEB TCP READ command will read whatever is available on each connection and save any received data in the long string buffer b(). The following two lines look for GET and HTTP keywords in the received request. The next line checks that these keywords are present and in the correct order. In that case, we send the default web page, “index.html”. Note that we don’t care what file the remote browser actually requested; we just send the default page for every request. This web page is shown in Program 2 and consists of just three lines. The first line is the heading, and the next two define the text on the page. When the page is transmitted, the firmware will substitute the text {CurrentTemp} and {CurrentHumid} with the current values of those variables. “<BR />” in HTML is an instruction to the web browser to insert a new line (line BReak). Screen 3 shows the result displayed in a browser. This is a functional program, and if you have a Raspberry Pi Pico W handy, you can copy the files to it and have it working immediately. To make it easy, the WebMite firmware download includes both these files and a ‘readme’ file with detailed instructions. Give it siliconchip.com.au Program 1: this simple web server program displays the temperature and humidity in a fictional greenhouse. It is just 17 lines; the WebInterrupt subroutine starting at line 7 is where the work is done in serving up the web page. <H3>Greenhouse Monitor</H3> The temperature is {CurrentTemp}&degC <BR /> The humidity is {CurrentHumid}% Program 2: this is the web page HTML source for the program shown in Program 1. The first line defines a heading and the next two specify the text in the page. When the page is transmitted, the firmware will substitute the text {CurrentTemp} and {CurrentHumid} with the current values of those variables. a go and be prepared to be amazed at what the WebMite can do. Advanced server features Web infrastructure is a rich environment, so you can add many more features to your web pages. These include images, textured backgrounds, multiple pages and more. For example, you might want to display a graph of past temperatures and humidity for your hypothetical greenhouse. That can be done by defining a virtual LCD panel in the WebMite. This does not have an attached physical display, but regardless, you can draw your historical data on it using the graphical drawing commands built into MMBasic: line, pixel, text etc. You can save this image as a BMP file to the internal file system in the WebMite. Then, when a remote browser requests the web page with this embedded image, the browser will also ask for this file, and the user will see an image representing the graph of past temperatures and humidity that your program recorded. Screen 4 illustrates what it could look like. Even more useful is the ability to define HTML forms in the web page, including embedded controls such as Screen 3: how the simple web server appears to a user on a phone, tablet or computer. Screen 4: with a little more programming effort, you can extend the simple web server to display a graph of past temperatures and humidity readings for your greenhouse. Australia's electronics magazine August 2023  33 buttons, checkboxes, radio buttons, input text fields and much more. Using these, the user can, via the web page, send commands to the BASIC program running on the WebMite to do things like turn devices off/on, set parameters and so on. Screen 5 provides some examples of these. A wide range of controls is available but be warned that the HTML code can get complicated. The web page at www.w3schools.com/howto/default. asp lists these controls and their features, and has plenty of examples that you can copy into your web pages. This ability means that many projects that generally need an LCD screen with associated buttons and switches (or a touchscreen) can be converted to a web interface with the same functions and more. An excellent example is the Watering System Controller starting on page 36 of this issue. It uses the WebMite and there are no controls on the physical box. All the controller’s functions are configured and controlled exclusively via web pages in a browser. TCP client As well as acting as a web server, the WebMite can act as a client and get data from web servers on the internet. Three commands will do this for you: WEB OPEN TCP CLIENT, WEB TCP CLIENT REQUEST and WEB CLOSE TCP CLIENT. For example, if you wanted to get the default web Screen 5: you can include embedded controls such as buttons, checkboxes, radio buttons, input text fields and much more on a web page using HTML forms. The user can use these to send commands to the BASIC program running on the WebMite to turn devices off or on, set parameters and so on. 34 Silicon Chip page from a website called example. com, you could do it this way: DIM INTEGER b(512) WEB OPEN TCP CLIENT “example.com”, 80 WEB TCP CLIENT REQUEST “GET / HTTP”, b() WEB CLOSE TCP CLIENT Editor’s note: the WEB OPEN and WEB TCP commands should all be on a single line; the commands are shown split here due to limited column width. The web page would be saved in the long string buffer b() and you could pick it apart to get the data you wanted using the long string routines. There are many services available on the internet that can be accessed with the TCP client. Two that are documented in the WebMite user manual are getting the weather and sending emails. You need an account with a weather service to get the weather. The user manual describes how you can connect to Open Weather Map; you can get a wealth of data using their service, such as the current temperature and weather for a city or suburb, plus a forecast for the next day or two. Open Weather Map is free for the basic service and is accurate and comprehensive. Sending emails is a little more complicated, as most email relay services have protection to stop them from being used to send spam. To send an email, you need to connect to an SMTP relay service that will then send your email to its destination. The example in the user manual uses SendGrid for this task, as they allow a free account to send up to 100 emails a day (plenty for the WebMite). Sending an email is handy as it allows your WebMite-based gadget to alert you to errors and faults, provide regular status updates etc. For example, your greenhouse monitor could send an email if the temperature went too high or low. Many internet services now require a secure (encrypted) connection, so the WebMite also implements an experimental version of TLS (Transport Layer Security), an extra protocol layer above the TCP layer that supersedes the SSL protocol. Client-server applications use TLS to communicate across a network in a way designed to prevent eavesdropping Australia's electronics magazine and tampering; many sites insist that this protocol is used. Network Time Protocol Getting the current time and date is such a common task that the WebMite has a dedicated command for just this purpose using the Network Time Protocol (NTP) as follows: WEB NTP timeoffset With this command, the WebMite will get the date/time from a public time server pool and set the internal clock of the WebMite accordingly. This means that you do not need a realtime clock in your project; you don’t need a mechanism to adjust the time or date either. The parameter “timeoffset” is the local time zone as a floating point number. For example, “WEB NTP 9.5” will get the current time and set the clock in the WebMite to Adelaide time. Note that daylight saving compensation is not included in the NTP service. Another handy inclusion is a series of commands to post and retrieve data from an MQTT broker. MQTT (Message Queuing Telemetry Transport) is a protocol that enables a client to post data on a server (called an MQTT broker) for later retrieval by another client. It is rather like a bulletin board service for small computers. An example would be our greenhouse monitor. Say it was battery-­ powered; it could power up once an hour, measure the temperature/humidity, post the results to an MQTT broker and power down to save the battery. Separately, a client program on a PC could later read these messages, display the results and graph them. Conclusion In this summary of the WebMite firmware, we have not mentioned all the features that the WebMite inherited from the PicoMite. That includes the high-performance CPU, fully-­featured BASIC programming language, built-in program editor, support for touch-­ sensitive LCD panels, playing sound and music, external SD cards and an extensive range of communications protocols like serial and I2C. The Raspberry Pi Pico W costs little (~$10) and is readily available, so why not have a go? Load the free WebMite firmware and discover how easy it is to connect to the internet or turn this cheap device into a web server. SC siliconchip.com.au