MicroPython on ESP32: Tools – esptool.py

These are my notes on using some MicroPython specific tools in relation to a ESP32-DevKitC board.

These notes are for v2.1 of the esptool; an ESP8266 and ESP32 serial bootloader utility.

esptool has a number of functions, but I will only speak to those features required to identify the chip, get flash information and load the MicroPython firmware. See the docs for more information.

Installing esptool

(myproject) $ pip install esptool

Confirm install

(myproject) $ esptool.py version

Display chip information (chip_id)

(myproject) $ esptool.py -p /dev/ttyUSB0 chip_id
esptool.py v2.1
Connecting......
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Uploading stub...
Running stub...
Stub running...
Chip ID: 0x7240ac40964
Hard resetting...

Display Flash memory information (flash_id)

(myproject) $ esptool.py -p /dev/ttyUSB0 flash_id
esptool.py v2.1
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Uploading stub...
Running stub...
Stub running...
Manufacturer: c8
Device: 4016
Detected flash size: 4MB
Hard resetting...

Display MAC address of wifi adapter (read_mac)

(myproject) $ esptool.py -p /dev/ttyUSB0 read_mac
esptool.py v2.1
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Uploading stub...
Running stub...
Stub running...
MAC: 24:0a:c4:09:64:c8
Hard resetting...

Loading MicroPython Firmware
You will need MicroPython firmware http://micropython.org/download#esp32
I download to a directory named images in my project folder. Since the ESP32 code is under development, I check out the GitHub commit page for the chip for any interesting new bits.

When loading to a board that does not already have MicroPython loaded, you should erase the entire flash before flashing the MicroPython firmware.

(myproject) $ esptool.py -p /dev/ttyUSB0 erase_flash
esptool.py v2.1
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 5.0s
Hard resetting...

Now load the firmware with the write_flash command
The general form is:

esptool.py write_flash -p <port> -z <address> <filename>
  -p                    specify the port
  <port>                the port to use  i.e. /dev/ttyUSB0
  -z   			Compress data in transfer (default unless --no-stub is
                        specified)
  <address> <filename>  Address followed by binary filename, separated by
                        space

(myproject) $ esptool.py -p /dev/ttyUSB0 write_flash -z 0x1000 images/esp32-20170916-v1.9.2-272-g0d183d7f.bin
esptool.py v2.1
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB
Compressed 902704 bytes to 566927...
Wrote 902704 bytes (566927 compressed) at 0x00001000 in 50.0 seconds (effective 144.4 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting...

Verify the firmware loaded correctly

(myproject) $ miniterm.py --raw /dev/ttyUSB0 115200
--- Miniterm on /dev/ttyUSB0  115200,8,N,1 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---

>>>

Now do a hard reset using the reset button on the board

>>> ets Jun  8 2016 00:22:57

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371 
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:0x3fff0010,len:4
load:0x3fff0014,len:4268
load:0x40078000,len:0
load:0x40078000,len:10648
entry 0x4007a56c
I (982) cpu_start: Pro cpu up.
I (983) cpu_start: Single core mode
I (984) heap_init: Initializing. RAM available for dynamic allocation:
I (994) heap_init: At 3FFAE2A0 len 00001D60 (7 KiB): DRAM
I (1013) heap_init: At 3FFD4158 len 0000BEA8 (47 KiB): DRAM
I (1032) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
I (1052) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
I (1072) heap_init: At 4008F3A8 len 00010C58 (67 KiB): IRAM
I (1091) cpu_start: Pro cpu start user code
I (1152) cpu_start: Starting scheduler on PRO CPU.
OSError: [Errno 2] ENOENT
MicroPython v1.9.2-272-g0d183d7f on 2017-09-16; ESP32 module with ESP32
Type "help()" for more information.
>>> 

You should verify that the firmware specified in the banner after the reset matches that firmware that you just loaded. In this case, v1.9.2-272-g0d183d7f

May the Zen of Python be with you.