Using CircuitPython on the HW-394 ESP-WROOM-32 (ESP32) Development Board
2023-12-24 18:20 (11 months ago)
ytyng
I bought a development board with an ESP-WROOM-32 module from AliExpress by searching for ESP32 and selecting the one with "HW-394" printed on the board.
It came as a set of four for $16.
This board has a CH340C USB-to-serial chip. There seems to be another version without the "HW-394" print but with the same pattern here.
On Amazon Japan, there were many similar products (from unknown manufacturers) featuring ESP-WROOM-32 + CH340C (or other serial console chips).
Although I’m not sure if "HW-394" is the development board’s name, I will refer to this product as HW-394 henceforth due to the lack of an official name.
Postscript: I later found out that various manufacturers produce these boards under the ESP32 DevKitC standard.
Things to Note When Selecting
This product is only available on AliExpress and doesn’t have an official page, making it somewhat dubious.
When used with a small breadboard, one side of the pins becomes inaccessible because the board is too large. Therefore, I do not recommend it.
(In the photo, you can only use the pins on the left side.)
If you plan to use ESP32, it’s better to buy a board recommended on the CircuitPython official site for ESP32:
https://circuitpython.org/downloads?q=ESP32
The Seeed Studio XIAO ESP32C3 is compact, relatively inexpensive, and readily available in Japan.
Development Method
I will develop using a Mac (Apple Silicon M2).
Although ESP32 can transfer files and develop using a browser without USB serial connection, I will not be using that feature. Instead, I’ll transfer Python files via USB serial port.
I will write the code in PyCharm and use a shell script to flash it.
Checking the USB Serial Connection Port
Connect the HW-394 to the Mac via a USB-C cable. No driver installation is necessary.
After connecting, check the port with the following command:
python -m serial.tools.list_portsResults:
/dev/cu.Bluetooth-Incoming-Port
/dev/cu.usbserial-110
2 ports foundExcluding Bluetooth-Incoming-Port, /dev/cu.usbserial-110 is the USB serial port created.
If the serial port is not visible, try changing the cable and connecting directly without a hub, as USB hubs might not be recognized properly.
To handle the port in a shell script, I use the following to account for any changes in the numerical part:
port=$(ls -1 /dev/cu.usbserial* | head -n 1)Writing CircuitPython Firmware
Unlike RP2040 (RaspberryPi Pico, etc.), you cannot write firmware by dragging and dropping a uf2 file because ESP32 is not recognized as a storage device.
To write the firmware, use a library called esptool.
Installing esptool
python3 -m pip install esptoolIf using Pipenv, the following Pipfile should work:
Pipfile
[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true
[dev-packages]
[packages]
esptool = "*"
# Use a fork with bug fixes
adafruit-ampy = {git = "git+ssh://git@github.com/ytyng/ampy.git"}
[requires]
python_version = "3.9"pipenv installI will explain adafruit-ampy later. It is used for file transfers.
Getting the CircuitPython Firmware
There is no CircuitPython firmware specifically for HW-394. Therefore, use the firmware for the DOIT ESP32 Development Board, which has a similar configuration.
Use at your own risk as it is not the official firmware for this product.
Download the firmware by clicking DOWNLOAD .BIN NOW on the above page.
Writing the Firmware
Use esptool’s write_flash to write the firmware.
#!/usr/bin/env zsh
port=$(ls -1 /dev/cu.usbserial* |head -n 1)
esptool.py --chip esp32 --port $port \
--before default_reset --after hard_reset --no-stub \
write_flash --flash_mode dio 0x0 \
adafruit-circuitpython-doit_esp32_devkit_v1-en_US-8.2.9.binConnecting to Python REPL
You can use the Python console (REPL) on the board by connecting to the serial port.
Connect using the screen command.
#!/usr/bin/env zsh
port=$(ls -1 /dev/cu.usbserial* |head -n 1)
screen $port 115200Adafruit CircuitPython 8.2.9 on 2023-12-06; ESP32 Devkit V1 with ESP32
>>> import board
>>> dir(board)
['__class__', '__name__', 'D1', 'D12', 'D13', 'D14', 'D15', 'D16', 'D17', 'D18', 'D19', 'D2', 'D21', 'D22', 'D23', 'D25', 'D26', 'D27', 'D3', 'D32', 'D33', 'D34', 'D35', 'D4', 'D5', 'I2C', 'LED', 'MISO', 'MOSI', 'RX', 'RX0', 'RX2', 'SCK', 'SCL', 'SDA', 'SPI', 'TX', 'TX0', 'TX2', 'UART', 'VN', 'VP', 'board_id']Writing Python Code from Mac to Flash
To write files via the serial port, tools like rshell, mpfshell, ampy, and upydev can be used, but they seem to require the development board to be on MicroPython.
For example, in MicroPython, the module name might be ubinascii, while in CircuitPython, it’s binascii. As a result, MicroPython libraries often cannot be used directly in CircuitPython. Many MicroPython modules have a "u" prefix.
Among these tools, ampy is the simplest and easiest to modify for CircuitPython, so I forked and fixed it. Although a pull request has been raised on the original repository, it seems to be unmaintained and not merged.
Installing the Fixed ampy
You can install it using the Pipfile mentioned above or by running:
python3 -m pip install git+https://github.com/ytyng/ampy.gitWriting Python Code
Let's write a script to blink the D2 LED on the board.
blink_led_d2.py
import digitalio
import time
import board
print('brink_led.py loaded.')
led_pin = digitalio.DigitalInOut(board.D2)
led_pin.direction = digitalio.Direction.OUTPUT
while True:
led_pin.value = True
time.sleep(0.1)
led_pin.value = False
time.sleep(1.9)Writing to Flash
deploy.sh
#!/usr/bin/env zsh
export AMPY_PORT=$(ls -1 /dev/cu.usbserial* |head -n 1)
cd $(dirname $0)
ampy put blink_led_d21.py /code.pyAfter copying it as /code.py on the flash, press the reset button on the board marked EN, and it will execute and blink the LED.
I confirmed that changing the pin number allows blinking on other pins as well.
Comments