ESP32: a look at the built-in BASIC interpreter

The ESP32 module, developed by Espressif Systems, is certainly one of the most successful and widespread low-cost embedded systems on the market. The SoC (System-on-Chip) features an extremely compact footprint, ntegrating in a single chip a high-performance microcontroller (both mono-core and dual-core versions are available), RAM and flash memory, a wide set of peripherals and, last but not least , a complete transceiver with Wi-Fi and Bluetooth low energy (BLE) interface.

The module can be programmed using the framework developed by Espressif Systems (ESP-IDF, acronym for Espressif Integrated Development Framework, available on GitHub), but there is also a plugin developed for the Arduino IDE development environment, which allows developers to use several basic libraries, creating a sketch as if it were an AVR-family microcontroller. The following picture, for instance, shows how to select the proper board type for programming an ESP32-based board through Arduino IDE (the plugin shall have been previously installed through the Boards Manager tool).

There are, however, other ways in which it is possible to program the ESP32 module, such as for example MicroPython (whose image is constantly updated), Lua and more.

In this article, however, we will explore a somewhat hidden and little-known functionality of the ESP32 module: the ROM-based BASIC interpreter. Yes, you really understood: inside the silicon chip of each ESP32 module, the designers of Espressif Systems have burned the image of a BASIC language interpreter, very compact but sufficiently complete. It must be said at the outset that this BASIC interpreter was not added as a development system or as an additional programming language, but rather as a debugging tool to test various features of the card and check for any hardware problems. The same Espressif’s official documentation states:

“When an ESP32 is unable to boot from flash ROM (and the fuse disabling it hasn’t been blown), it boots into a rom console. The console is based on TinyBasic, and statements entered should be in the form of BASIC statements. As is common in the BASIC language, without a preceeding line number, commands entered are executed immediately; lines with a prefixed line number are stored as part of a program.”

So, it is clear the BASIC ROM console is mainly intended for debugging purposes, a kind of recovery tool.

As we will see shortly, it is possible to activate this functionality even on a perfectly functioning card using a simple trick. The activation of the BASIC interpreter is performed by the SoC when it is not possible to boot from the flash memory. To simulate this condition (and here is the trick), it is possible to act on the MTDI pin (corresponding to GPIO 12). MTDI is a “strapping pin”, which is a particular pin whose state (high or low) is examined by the SoC during boot. By default, MTDI has an internal pull-down that keeps it at the low logical value (0). In this condition, the internal low dropout regulator (LDO) is set to the voltage of 3.3V and the board works correctly (unless a real flash memory failure occurs). If, on boot, the MTDI pin is in the high logic state (1), the internal LDO is set to the voltage of 1.8V. This condition causes errors in accessing flash memory and the consequent forced activation of the console ROM. These aspects are documented in the component datasheet, as shown in the following image.

What we have to do, therefore, is to connect the pin corresponding to the GPIO 12 (MTDI) to the 3.3V pin, inserting a 10 kOhm resistor (brown-black-orange) in the wiring in order to limit the current on the I/O pin . The 3.3V and GPIO12 pin position varies from board to board, based on the choices made by the individual manufacturer. Then, please check the documentation accompaning your ESP32-based board use the PCB screen printing as a reference.

Once the wiring is complete, power the board via USB cable, activate the serial monitor and press the RESET button. At this point you should observe a serial log similar to the following, confirming the built-in command interpreter has been activated as the consequence of a flash read error:

Good! We are now ready for playing with this tool. The first two commands we can try, just for practicing, are about and help:

From the first, we can see that the ROM console is based on the TinyBasic Plus tool developed by Mike Field and Scott Lawrence. With the help command, we get a list of the available commands. A detailed description of those command is available here, but people who have already used BASIC on other hardware platforms will immediately feel at ease. As for me, I found the commands that allow you to configure the direction and status of GPIOs very useful.

The first way for configuring I/O signals is based on the memory read and write functions, PEEK and POKE, respectively. This is a very low level mode and requires in-depth knowledge of the ESP32 module, which can also be found by consulting the component datasheet. The following example reads the contents of address 0x3FF44004 (register GPIO_OUT_REG), put it in OR with 0x04 (binary 100) and finally writes the value at the same address. This corresponds to setting GPIO2 high:

The address could be a memory address or a register. In this case, as we can see again on the datasheet, the address is inside the 4kB address space reserved for GPIO:

The second way, much simpler and more immediate, is to use the IODIR (set GPIO input or output direction), IOSET (set value of an output GPIO) and IOGET (get the value of an input GPIO) functions. Here is an example which first sets the direction of GPIO2 as output, then get and sets its value:

Being an introductory article, I think this is enough for now. The reader can practise with the tool writing simple program which can be directly tested on the board (unfortunately, it is not possibile to save the program).

The built-in ROM console is indeed a valuable tool which deserves some attention and can prove particularly useful for debugging or for checking on-the-fly some GPIOs.