2016-10-06

Total newbie guide for MicroPython on ESP8266

OK, disclaimer first. I know completely nothing about microelectronics. With that in mind:

Mine goal is to create cheep battery powered thermometer which would be reporting temperature in fixed intervals using http via mine home router WiFi network. This was occupying mine mind from this article (in czech only, executive summary: ESP8266 is old, new and better ESP32 is on the way). Till reading that article I did not knew there is cheep SoC which can connect to WiFi and you can read from external sensors attached to it (i.e. thermometer). There is lots of guides for this exact thing.

Purchasing ESP8266 ESP-01 and USB programmer

On E-Bay I have bought 3 ESP8266 Serial WIFI Wireless Transceiver Module Send Receive LWIP AP+STA for $9.44 (I have no idea on what all these letters in the name mean, but you want ESP8266 version labelled as ESP-01). And because I'm scared of wiring anything myself, I have bought ESP01 Programmer Adapter UART GPIO0 ESP-01 Adaptateur ESP8266 USB nb (to connect ESP8266 to computer via serial port emulated via USB; you do not need to install any drivers on Fedora 24). It took less than 20 days to receive all the items.

Lets use Python

I like Python, so was very surprised that there is a way how to program in it on ESP8266: MicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems - especially MicroPython port for the WiFi modules based on Espressif ESP8266 chip.

To be able to build MicroPython, we need to build esp-open-sdk first.

Building toolchain: esp-open-sdk

esp-open-sdk if SDK for software development with the Espressif ESP8266 chips and at the end, it had 3.8GB on the disk and it contains some non-open-source binary blobs and I do not understand majority of the README, so I have decided to work with that as different user on my Fedora 24 system:

# dnf install autoconf gcc gcc-c++ gperf bison flex texinfo patch libtool ncurses-devel expat-devel pyserial help2man
# useradd esp
# sudo -u esp -i
$ git clone https://github.com/pfalcon/esp-open-sdk.git
$ cd esp-open-sdk/
$ make

I have taken this partly from Starting IoT development in Fedora (ESP8266), from Building and Running MicroPython on the ESP8266 (they are building in virtual machine here) and from esp8266/README.md in MicroPython git linked above.

Building MicroPython ESP8266 port

Now here we build binary image we will later upload to the chip.

$ git clone https://github.com/micropython/micropython.git
$ cd micropython/
$ git submodule update --init
$ make -C mpy-cross
$ export PATH=/home/esp/esp-open-sdk/xtensa-lx106-elf/bin:$PATH
$ cd esp8266/
$ make axtls
$ make

Flashing (uploading) MicroPython image to ESP8266

First try to talk to original firmware

Plug ESP8266 board into the UART-to-USB converter firmly and put it into USB port. Now you will see bunch of messages in journal (tail it with # journalctl -f). We need device name (that differs based on which USB port you will use). Now you can connect to serial console:

<date> <hostname> kernel: usb 3-1: new full-speed USB device number 6 using xhci_hcd
<date> <hostname> kernel: usb 3-1: New USB device found, idVendor=1a86, idProduct=7523
<date> <hostname> kernel: usb 3-1: New USB device strings: Mfr=0, Product=2, SerialNumber=0
<date> <hostname> kernel: usb 3-1: Product: USB2.0-Serial
<date> <hostname> kernel: ch341 3-1:1.0: ch341-uart converter detected
<date> <hostname> kernel: usb 3-1: ch341-uart converter now attached to ttyUSB0
<date> <hostname> mtp-probe[10120]: checking bus 3, device 6: "/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1"
<date> <hostname> mtp-probe[10120]: bus: 3, device: 6 was not an MTP device
<date> <hostname> systemd-udevd[10119]: Process '/usr/bin/setfacl -m g:lirc:rw ' failed with exit code 2.
$ screen /dev/ttyUSB0 115200

This will fail because your "esp" user does not have write permissions to /dev/ttyUSB0. What I did was I have added "esp" user to "dialout" group with # usermod -a -G dialout esp, logged out, in again and verified that I have the group with $ groups command. Once done, start screen again.

You can try some AT commands - e.g. to switch to "station" mode and then listing available "access points" (your home WiFi network should be amongst them) as noted in Getting Started with ESP8266 article. Note that you need to press "Ctrl+M" (i.e. carriage return, "Enter" worked for me as well) and "Ctrl+J" (i.e. linefeed) to submit each command.

AT+GMR
AT version:0.25.0.0(Jun  5 2015 16:27:16)
SDK version:1.1.1
Ai-Thinker Technology Co. Ltd.
Jun  5 2015 23:07:20

OK
AT+CWMODE=3

OK
AT+CWLAP
+CWLAP:(3,"Internet_80",-82,"5c:f4:ab:02:da:12",1)
+CWLAP:(3,"Stonehenge",-81,"48:5b:39:38:56:56",6)
+CWLAP:(3,"krakonos",-67,"10:c3:7b:d6:b8:34",10)

OK

Once done, to terminate screen, use "Ctrl+a \".

To get some detail on current serial port setup (mostly baud rate is important), use $ stty < /dev/ttyUSB0.

Upload new firmware

First you need to start into flashing mode - to do that you need to wire GPIO 0 to GND before pushing into USB port. If your USB-to-UART converter do not have any switch or so, you need to be creative. For me, one small wire squeezed between these two pins made the trick - see the photo :-)

No erase current flash content and upload yours (took me few tries to actually upload correct file, so make sure you are uploading build/firmware-combined.bin). It all takes below minute:

$ esptool.py -p /dev/ttyUSB0 -b 115200 erase_flash
$ esptool -p /dev/ttyUSB0 --baud 115200 write_flash --flash_size=8m --verify 0 build/firmware-combined.bin

So I have Python on that tiny chip now?

Remove whatever you have used to start in flashing mode and plug it in again to start in normal mode. Again, use screen to connect. Press "Enter" and say wow, familiar >>> is here!

>>> print("Hello world")
Hello world
>>> print(sys.version)
3.4.0
>>> print(sys.implementation)
(name='micropython', version=(1, 8, 4))
>>> print(sys.platform)
esp8266

Next step would be to learn how to access wifi in MicroPython.