Introduction
This is a walkthrough of how I installed the Python-based esp8266/esp32 serial bootloader utility esptool on my Apple iMac – a 27-inch, Mid 2011 running macOS High Sierra – and used it to program an ESP8266 “Witty” module with esp8266/Basic. Python 3 was installed and a Python “venv” virtual environment was created to contain the python libraries used by esptool. As the version of macOS used does not include a driver for the “Witty” module’s interface adapter a third-party driver was installed.
Device driver for the witty’s interface
The witty uses a CH34x USB/serial chipset which macOS High Sierra (10.13) and earlier doesn’t have a native driver for. After connecting it to the iMac the witty’s (USB) serial port was not found. A driver for the CH34x chipset was found on GitHub at
https://github.com/adrianmihalko/ch340g-ch34g-ch34x-mac-os-x-driver
The latest version (1.5) of this driver is released as a signed package, however the signer of the package is not an “identified developer”. The security controls in this macOS haven’t been disabled so installing this package requires manual confirmation of its installation. That is done in System Preferences->Security & Privacy->[General] as shown here:
The driver was installed by following the installation instructions from the GitHub page – including the “force quit” suggestion to avoid having to reboot. After installing this driver for the CH34x the witty’s serial adapter appeared as /dev/tty.wchusbserialfd140
Installing Python 3
macOS comes with Python 2 installed as a “system” utility. Rather than risk interfering with the native python installation (by inadvertently introducing incompatible packages, etc.) I opted to install Python 3 from https://www.python.org/ I downloaded and ran the macOS 64-bit installer. The installation completed without incident.
Creating a “virtual environment” with venv
Not knowing where my Python development future might be headed I decided to use the “virtual environment” (venv) facility available in Python to keep any configuration changes and installed packages local to the project (to avoid running into configuration/package conflicts later with other Python projects). I created and activated a virtual environment named esp32-env within a project directory (named ESP32), updated its pip utility and installed esptool:
iMac:Documents ws$ mkdir ESP32 && cd ESP32 iMac:ESP32 ws$ python3 -m venv esp32-env iMac:ESP32 ws$ . esp32-env/bin/activate (esp32-env) iMac:ESP32 ws$ pip install --upgrade pip (esp32-env) iMac:ESP32 ws$ pip install --upgrade esptool
To verify that esptool was installed correctly I ran it without any arguments:
(esp32-env) iMac:ESP32 ws$ esptool.py
esptool.py v2.8
usage: esptool [-h] [--chip {auto,esp8266,esp32}] [--port PORT] [--baud BAUD] [--before {default_reset,no_reset,no_reset_no_sync}]
[--after {hard_reset,soft_reset,no_reset}] [--no-stub] [--trace] [--override-vddsdio [{1.8V,1.9V,OFF}]]
{load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,version}
...
esptool.py v2.8 - ESP8266 ROM Bootloader Utility
positional arguments:
{load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,version}
Run esptool {command} -h for additional help
load_ram Download an image to RAM and execute
dump_mem Dump arbitrary memory to disk
read_mem Read arbitrary memory location
write_mem Read-modify-write to arbitrary memory location
write_flash Write a binary blob to flash
run Run application code in flash
image_info Dump headers from an application image
make_image Create an application image from binary files
elf2image Create an application image from ELF file
read_mac Read MAC address from OTP ROM
chip_id Read Chip ID from OTP ROM
flash_id Read SPI flash manufacturer and device ID
read_flash_status Read SPI flash status register
write_flash_status Write SPI flash status register
read_flash Read SPI flash content
verify_flash Verify a binary blob against flash
erase_flash Perform Chip Erase on SPI flash
erase_region Erase a region of the flash
version Print esptool version
optional arguments:
-h, --help show this help message and exit
--chip {auto,esp8266,esp32}, -c {auto,esp8266,esp32}
Target chip type
--port PORT, -p PORT Serial port device
--baud BAUD, -b BAUD Serial port baud rate used when flashing/reading
--before {default_reset,no_reset,no_reset_no_sync}
What to do before connecting to the chip
--after {hard_reset,soft_reset,no_reset}, -a {hard_reset,soft_reset,no_reset}
What to do after esptool.py is finished
--no-stub Disable launching the flasher stub, only talk to ROM bootloader. Some features will not be available.
--trace, -t Enable trace-level output of esptool.py interactions.
--override-vddsdio [{1.8V,1.9V,OFF}]
Override ESP32 VDDSDIO internal voltage regulator (use with care)
Testing esptool with the witty
To test that esptool was working with my witty I tried its flash_id command. This worked without having to specify the serial port device. It confirmed the size of the flash – 4MB.
(esp32-env) iMac:ESP32 ws$ esptool.py flash_id esptool.py v2.8 Found 2 serial ports Serial port /dev/cu.wchusbserialfd140 Connecting.... Detecting chip type... ESP8266 Chip is ESP8266EX Features: WiFi Crystal is 26MHz MAC: ec:fa:bc:0c:e7:68 Uploading stub... Running stub... Stub running... Manufacturer: 20 Device: 4016 Detected flash size: 4MB Hard resetting via RTS pin...
As a further test I read out the entire flash, which still held the original “as-shipped” program, and saved it to a file:
(esp32-env) iMac:ESP32 ws$ esptool.py read_flash 0 0x400000 tmp.bin esptool.py v2.8 Serial port /dev/tty.wchusbserialfd140 Connecting.... Detecting chip type... ESP8266 Chip is ESP8266EX Features: WiFi Crystal is 26MHz MAC: ec:fa:bc:0c:e7:68 Uploading stub... Running stub... Stub running... 4194304 (100 %) 4194304 (100 %) Read 4194304 bytes at 0x0 in 399.4 seconds (84.0 kbit/s)... Hard resetting via RTS pin...
A hexdump examination of the saved file appeared reasonable – it was not all 0x00 or 0xff and included relevant-looking strings.
Uploading the esp8266/Basic image with esptool
The 4MB esp8266/basic image was downloaded from:
https://github.com/esp8266/Basic/blob/NewWebSockets/Flasher/Build/
The flashing instructions linked on the GitHub site are only relevant for the Windows flashing tool and don’t require, or indicate, the starting address in the flash to program the image to. After confirming the correct starting address with Peter Gheude – 0x0, esptool was executed with the write_flash command to write the image starting at address zero:
(esp32-env) iMac:ESP32 ws$ esptool.py write_flash 0 ~/Downloads/ESP8266Basic.cpp.bin esptool.py v2.8 Serial port /dev/tty.wchusbserialfd140 Connecting.... Detecting chip type... ESP8266 Chip is ESP8266EX Features: WiFi Crystal is 26MHz MAC: ec:fa:bc:0c:e7:68 Uploading stub... Running stub... Stub running... Configuring flash size... Auto-detected Flash size: 4MB Compressed 523104 bytes to 346130... Wrote 523104 bytes (346130 compressed) at 0x00000000 in 30.9 seconds (effective 135.4 kbit/s)... Hash of data verified. Leaving... Hard resetting via RTS pin...
Once the flash programming completed and the esptool had reset the witty, a WiFi access point was available with an ID created from the prefix string “ESP” and what looked as though it should have been the MAC address of the witty, however the actual id seen when browsing for its WiFi access point was: ESPEE:FA:BC:0C:E7:68
After connecting my iPhone’s WiFi to that access point the esp8266/Basic “home” page could be opened in the web browser at the URL http://192.168.4.1
Further ESP8266/ESP32 resources on this site can be found here.
Links to downloads/source code
CH34x device driver for macOS:
https://github.com/adrianmihalko/ch340g-ch34g-ch34x-mac-os-x-driver
Python 3:
https://www.python.org/
esptool:
https://github.com/espressif/esptool
esp8266/Basic:
https://github.com/esp8266/Basic/blob/NewWebSockets/Flasher/Build/
END