This is not going to be a comprehensive project, but a list of things I discovered while getting a ESP8266-12E to run Lua, which may help you get going. If you are already using ESP8266 or NodeMCU you already know these things, nothing for you here. The project will stop at the point where I get blink.lua to work, anything further belongs elsewhere as far as I'm concerned. Also I will only discuss Linux but many of the tools I used are cross-platform.

How I got sucked in involved

I'm always a sucker for bargains so when I saw that the development board shown in the photo for sale on AliExpress for $2, I thought cheap ~~headaches~~ entertainment! The description mentioned running Lua. I have been an admirer of this lightweight embeddable language for many years but never wrote anything substantial in it. So I ordered one and it arrived in about 3 weeks, pretty good for economy delivery.

Connecting it up is easy

All you need is a USB A to MicroUSB cable. I found that some of my cables rescued from the e-waste bin, are actually charging only cables, not data cables. Once connected, you will see the USB to serial converter (FTDI type) device detected. This is not necessarily the CP2102; the Chinese manufacturer may have used another chip, so that area of the board may look slightly different. But it doesn't matter as long there is a driver for Linux. The device /dev/ttyUSB0 was created. You should check for any steps you have to take to make the device R/W to your account. In my case I am already in the dialout group, so I had permissions. Do not run your software as root, this is sloppy, hazardous, and unnecessary.

Get a terminal session

I had earlier installed the requisite packages for Arduino. This is one of many tutorials on the Internet for doing this. By the way a shout out to Random Nerd Tutorials who have a lot of documentation resources for the ESP8266. You can then develop in C++ Arduino style, using the Espressif toolchain. You can use the serial terminal to talk to the ESP8266.

However I wanted Lua so I looked for something else and found Esplorer, which is a Java based IDE for developing in Lua or MicroPython for the ESP8266. It also has an excellent serial interface. Support the author if you like the software.

Lua is not preloaded

The AliExpress listing makes it sound like Lua is already on the board. It is not. It's supported and you have to flash it yourself. This is obvious when you think about it. Why would the factory spend a bit more money and time adding this software? And it may be out of date by the time you get the board. So it's for the best that you flash the latest software yourself anyway.

At this point I should mention the definitive NodeMCU documentation site.

The boot sequence

There is actually a comprehensive list of steps that the MCU will take to boot. I'll just write about what you need to know.

When reset, the MCU serial interface is set to 74880 baud (yes!). You will see a boot banner, among other things showing boot mode(x,y). x will be 1 or 3, meaning boot from serial or boot from flash. How do you select? It's done by GPIO0 (D3). Leaving it open boots to flash, taking it to ground by holding down the Flash button boots to serial. I thought I needed a jumper to do this, but that's what the Flash button is for, duh! So to flash firmware, hold down the Flash button, and click the Reset button, then you can release the Flash button.

The firmware will switch to 115200 baud. That's why text is shown as garbage after the firmware takes control. In practice you can leave your terminal emulator at this speed. Only if you need some boot info do you need 74880 baud.

If like my board, Lua isn't installed yet, it will print out something about BELTLINE-01. Must be built-in firmware in the chip.

Pin header spacing

At this point I should mention that the spacing between the two rows of header pins is 1 inch so it won't fit on a narrow breadboard, or rather there will be no room to insert jumpers. You need a wide breadboard and probably to straddle the power bus.

Getting the Lua firmware

The instructions for building the firmware involves getting the software from Github and compiling. But there is a shortcut, you can use a cloud build service, as mentioned in the instructions. You select the modules you want included, give your email, and start the build. If you are a newbie like me, just accept the default and add more modules in future builds. When the build is finished, you are emailed links to the binaries which you should fetch within 24 hours. If you like the service, send the author some beer or use his affiliate link to shop on AliExpress and Banggood.

Flashing the firmware

Esplorer doesn't have a flasher, so from the NodeMCU doco I found esptool.py. It turned out that my Linux distro already has this in the repository so all I had to do was install it. There is a GUI wrapper for this tool also. The command I used was:

esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash -fm dio 0x00000 mynodemcu.bin

Remember to hold down the Flash button while clicking on the Reset button before issuing the command. Of course, disconnect the Esplorer session first.

There is progress indication, After several seconds, the image will be flashed onto the MCU.

Verifying the Lua firmware

Now connect with Esplorer at 115200 baud, hit reset, and you should get a banner like this:

NodeMCU 3.0.0.0 built on nodemcu-build.com provided by frightanic.com
    branch: release
    commit: 136e09739b835d6dcdf04034141d70ab755468c6
    release: 3.0.0-release_20210201
    release DTS: 202102010145
    SSL: false
    build type: integer
    LFS: 0x0 bytes total capacity
    modules: file,gpio,net,node,tmr,uart,wifi
 build 2021-02-11 12:47 powered by Lua 5.1.4 on SDK 3.0.1-dev(fce080e)
cannot open init.lua:
>

The > is the prompt. You can click on the Heap button, which will get this response:

> =node.heap()
43472

You can confirm that the Lua interpreter works by typing in the text box and hitting Send:

> =print("Hello world\r\n")
Hello world

Last step, getting blink to work

In the program window of Esplorer on the left type in this program and save it on the local filesystem:

gpio.mode(4, gpio.OUTPUT)
while true do
    gpio.write(4, gpio.HIGH)
    tmr.delay(1000000)
    gpio.write(4, gpio.LOW)
    tmr.delay(1000000)
end

Then hit the Send to ESP button and you should see the blue LED blink.

Why 4 in the gpio function calls? Well first look at the pinout reference and see that GPIO 2 is connected to the LED. Next look at the GPIO module reference and see that this is D4.

That's it. I'm going to have fun and I hope you do too. I still think it's pretty amazing that for $2 you can get a WiFi capable MCU board. If you are going to be making heaps of gadgets, you might want to look at just buying the Espressif ESP8266 module only which is about $1. The development board puts a 5V to 3.3V regulator, a USB to serial chip, a MicroUSB connector, buttons, LED, and header pins around the Espressif module. But you would really have to make heaps to save significantly.

But wait wait, what about Arduino and MicroPython?

For the Arduino, the C++ code compiles to native Espressif code and you would flash it in the same way as the Lua interpreter.

For MicroPython presumably you would flash the MicroPython interpreter and then use the Esplorer IDE to develop in it. I've got enough experience with the snake elsewhere so I'll be playing with Lua.

Project Details