Date

Overview

I have an upcoming project that needs wifi, cheep and serial. Normally I would just pick up an Arduino.

However recently I noticed the ESP32 SoC.

I brought a few from DF-Robot "No affiliation". Its cheep, has WIFI, serial and can run MicroPython.

Wait? Python on a microcontroller?? :D Yep!

There has been a project to port Python 3 to Micro's, you can find out more about MicroPython here.
So now you have your ESP32 SoC and are thinking how to get MicroPython on to it.
You have two choices :

  1. Install the precompiled firmware binary.
  2. Build your own firmware binary

This post will cover both options, but more so will focus on building your own firmware binary.

Requirements

If you only want to flash prebuilt images you just need the "Kernel Options" and "esptool" sections of the requirements.

If you want to build your own firmware you will need all of the requirements section.

Instructions to just flash a precompiled binary will be at the bottom of this guide.

Kernel Options

You will need the following kernel options set :

  • CONFIG_USB_ACM

esptool

esptool is used to write/read images and settings from the ESP32 SoC.
It will be needed for any write/read/erase operation

Installing esptool

esptool is a pip package, the best way to install this is :

pip install esptool

For Gentoo Linux you may need to use the following syntax :

pip install esptool --user

ToolChain

You will need a copy of the xtensa-esp32 toolchain.

At the time of writing this guide the current version was 1.22.0-61

ESP IDF

This is the Espressif dev framework
The stable/supported version of the ESP IDF is set via git commit hash tags, more on that later.

Buildtools

Your operating system will need various tools to support building the firmware.
If you are using Gentoo, your set.
However if you are not using Gentoo take a look over the following page and the refrence section in this post.

Micropython-esp32

This code is managed in the MicroPython-esp32 github account.

Building your own firmware

Unpack xtensa-esp32-elf

This guide makes use of 64bit binary and library files, if you have a 32bit system your will need to change to to the 32bit package.

Download the xtensa-esp32-elf tarball.
At the time of this guide the latest version was 1.22.0-61.

Unpack this into /opt.

tar -xvf tensa-esp32-elf-linux64-1.22.0-61-gab8375a-5.2.0.tar.gz -C /opt

You can unpack this anywhere really. Next we need to ensure the bin folder is part of your systems path.

You can add a bash alias, add a file to profile.d or export when you need it.

For now lets just export it :

export PATH=$PATH:/opt/xtensa-esp32-elf/bin

I prefer to add a file into "/etc/profile.d" to make this more permanent, however refer to your disto's advice.

ESP IDF

This code is managed via github, follow the steps to fetch the code. For now do not worry about what commit is pulled.

I like to unpack this into a directory under my home folder, however you can select any location.

git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
git submodule update --init

Finial directory "~/code/esp-idf"

Micropython-ESP32

You will need to checkout the latest code from the MicroPython-ESP32 githib account.
Follow the steps below to fetch the code.
I like to unpack this into a directory under my home folder, however you can select any location.

git clone --recursive https://github.com/micropython/micropython-esp32.git

Finial directory is "~/code/micropython-esp32/esp32"

Initial set up of MicroPython-ESP32

We need to set up two things before we can start :

  1. Build cross compiler support
  2. A makefile to suit out environment

Building cross compiler support

Run the following commands to build cross compiler support.

cd micropython-esp32

^ micropython-esp32, should be the directory that git checked out in the above step.

make -C mpy-cross

That is all that is needed for now.

Craft a makefile

We need to override some Makefile settings to suit our build environment.
The base minimum you need to set is :

  • ESPIDF location
  • Serial port device of the ESP32

For example I create a makefile in "~/code/micropython-esp32/esp32" that contains the following :

ESPIDF = /home/brendan/code/esp-idf   
PORT = /dev/ttyACM0      
include Makefile     

ESPIDF, is where we did the git checkout of the esp-idf. PORT, is the serial device of the ESP32 when plugged in. include, just pulls in the global Makefile.

Fix modules in MicroPython-ESP32

I noticed there where some broken symlinks in the modules directory for esp32.
While this will not prevent you from compiling the firmware, it will leave out some cool functions.

For me the broken modules where "urequests.py" and "upysh.py"

$ ls -la
total 28
drwxr-xr-x 2 brendan brendan 4096 Jul 13 21:35 .
drwxr-xr-x 4 brendan brendan 4096 Jul 13 21:41 ..
-rw-r--r-- 1 brendan brendan  173 Jul 13 21:35 apa106.py
-rw-r--r-- 1 brendan brendan  173 Jul 13 21:35 _boot.py
lrwxrwxrwx 1 brendan brendan   28 Jul 13 21:35 dht.py -> ../../esp8266/modules/dht.py
lrwxrwxrwx 1 brendan brendan   32 Jul 13 21:35 ds18x20.py -> ../../esp8266/modules/ds18x20.py
-rw-r--r-- 1 brendan brendan 1034 Jul 13 21:35 flashbdev.py
-rw-r--r-- 1 brendan brendan  961 Jul 13 21:35 inisetup.py
-rw-r--r-- 1 brendan brendan  884 Jul 13 21:35 neopixel.py
lrwxrwxrwx 1 brendan brendan   32 Jul 13 21:35 onewire.py -> ../../esp8266/modules/onewire.py
lrwxrwxrwx 1 brendan brendan   19 Jul 13 21:35 upip.py -> ../../tools/upip.py
lrwxrwxrwx 1 brendan brendan   28 Jul 13 21:35 upip_utarfile.py -> ../../tools/upip_utarfile.py
lrwxrwxrwx 1 brendan brendan   39 Jul 13 21:35 upysh.py -> ../../../micropython-lib/upysh/upysh.py
lrwxrwxrwx 1 brendan brendan   47 Jul 13 21:35 urequests.py -> ../../../micropython-lib/urequests/urequests.py

Run the following to fix the broken symlinks :

cd ~/code/micropython-esp32/esp32/modules
rm upysh.py && rm urequests.py
wget https://raw.githubusercontent.com/micropython/micropython-lib/master/upysh/upysh.py
wget https://raw.githubusercontent.com/micropython/micropython-lib/master/urequests/urequests.py

Check for supported ESP IDF git tag

Next we need to check if the checkout of the ESP IDF is a supported tag version for MicroPyython-ESP32.

Change into the following directory :

cd ~/code/micropython-esp32/esp32

Then run :

make

You might see something like this (assuming you have the set up right :

Current git hash:   9b30f66facf1d47764618b8a9256d41067468411
Supported git hash: 9b955f4c9f1b32652ea165d3e4cdaad01bba170e

This means the tag version of ESP-IDF is not a supported tag version for MicroPython-ESP32.
If you see the same tag versions it means you have a supported git tag version already.

To fix this run the following commands :

cd ~/code/esp-idf
git checkout -b 9b955f4c9f1b32652ea165d3e4cdaad01bba170e

Substitute the hash tag above with the one that is displayed in the output from the make command above.

Compile and install firmware

Now we can flash the stock firmware we just built.
Run the following commands :

cd ~/code/micropython-esp32/esp32

Note, ensure you have plugged in the ESP32 device and no other serial applications are currently using the device.

make
make erase
make deploy

Check it!

If you got no errors from the above steps you can connect to the serial port of the ESP32.
There re many ways to do this, I prefer minicom however anything that can access a serial device should work.
Connection settings are "118000,8-n-1".

Once connected you should see the python ">>>" prompt. If you do not hit reset on the board or "Ctrl-D".
The boot sequence looks like this :

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)                      
ets Jun  8 2016 00:22:57                

rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee                
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2                  
load:0x3fff0008,len:8
load:0x3fff0010,len:3408
load:0x40078000,len:9488
load:0x40080000,len:252
entry 0x40080034
I (2277) cpu_start: Pro cpu up.
I (2277) cpu_start: Single core mode
I (2278) heap_alloc_caps: Initializing. RAM available for dynamic allocation:
I (2320) heap_alloc_caps: At 3FFAE2A0 len 00001D60 (7 KiB): DRAM
I (2381) heap_alloc_caps: At 3FFD5328 len 0000ACD8 (43 KiB): DRAM
I (2444) heap_alloc_caps: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
I (2508) heap_alloc_caps: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
I (2573) heap_alloc_caps: At 400924E4 len 0000DB1C (54 KiB): IRAM
I (2635) cpu_start: Pro cpu start user code
I (2794) cpu_start: Starting scheduler on PRO CPU.
esp32 ftw
MicroPython v1.9.1-219-g3580284e-dirty on 2017-07-13; ESP32 module with ESP32
Type "help()" for more information.
>>>

.... Yes MicroPython is currently single core only for now.
I did try enable the second "app" core but MicroPython failed to run.

Making it run your own code.

OK, so having a python shell on your micro is cool, but pretty useless really.
You are going to want to run your own python code on boot.

To do this your going to need to edit and create a few files.

main.py

This is the file that will get called on boot.
I do not like to put much in here apart from importing other scripts/modules.
Do note if your code enters a loop you will never see the REPL prompt.
This is not really a problem once your code fully works.

Change into the following directory :

cd ~/code/micropython-esp32/esp32/modules

Create a file called "main.py".
For now, as an example put the following code into "main.py" :

import my_code

Next, create a file in the same directory called "my_code.py", the contents of the file should be :

print('esp32 ftw')

Save the files. As You can see this is a pretty useless example, we are just printing one line. You can import as many modules as you like inside of "main.py".

Next change to the following directory :

cd ~/code/micropython-esp32/esp32

Then edit the file "main.c". We need to make the following changes :

--- main.c.org  2017-07-13 21:55:13.297607472 +0800
+++ main.c  2017-07-13 21:55:31.331312047 +0800
@@ -85,7 +85,7 @@
     pyexec_frozen_module("_boot.py");
     pyexec_file("boot.py");
     if (pyexec_mode_kind == PYEXEC_MODE_FRIENDLY_REPL) {
-        pyexec_file("main.py");
+        pyexec_frozen_module("main.py");
     }

     for (;;) {

This tells MicroPython to load our main.py from firmware bin rather then from the onboard file system.
I have not yet found a way to upload files to the DF-Robot ESP32 file system. As part of the firmware build process.
We have enough storage in firmware space anyway. In addition the DF-Robot ESP32 has no SD-Card slot.

Next follow the normal flashing steps :

make
make erase
make deploy

That's it!, by now you should be able to compile your own firmware, include your own python modules and run them at boot time.

Flashing pre built firmware

If you just want to mess around with MicroPython via a REPL prompt you can easily flash a pre made binary firmware.
This also may be handy to just test out a new device if you are having issues with the above steps. After all electronic parts can be faulty!

You will need a working install of esptool, as listed in the prerequisites and the Kernel support, nothing else is needed.

Download a prebuild firmware.
At the time of writing this the current version was "esp32-20170714-v1.9.1-219-g3580284e".

Plug in the ESp32 bord and run the following commands :

esptool.py -p /dev/ttyACM0 erase_flash
esptool.py -p /dev/ttyACM0 --baud 460800 write_flash --flash_size=detect 0 esp32-20170711-v1.9.1-219-g3580284e.bin

Where : "/dev/ttyACM0" is the serial device of my ESP32.
Where : "esp32-20170711-v1.9.1-219-g3580284e.bin" is the downloaded binary MicroPython firmware.

After this you can connect via minicom or another application that an access the serial port. As descibed in section "Check it!" above.

References :


Comments

There are no comments yet. Email me and I will add your comment.