Getting Started with CircuitPython

MicroPython

CircuitPython is a spin-off of the well-known MicroPython. An efficient implementation of Python 3, with a small subset of the Python Stdlib, optimised for microcontrollers (Cortex-based MCU, for example).

Even thought Python 3 is a powerful language, this implementation fits in 256KB of Flash and uses around 16KB of RAM. So it is suitable for the majority of the mid-range ARM-based microcontrollers.

The main difference between MicroPython and CircuitPython, is that the latest is sponsored and maintained by Adafruit. One of the global leaders developing boards and add-ons for microcontrollers’ enthusiasts. Apart from that:

  • It’s based on MicroPython (stable) releases, and not the master branch.
  • It’s implementation is focus on Adafruit products (basically Atmel’s M0, M4 devices and ESP8266).
  • Floats and Doubles are enabled by default.
  • USB is natively supported on all boards (with capable hardware).
  • Does not support concurrency.

CircuitPython comes pre-installed on many Adafruit boards, but if it’s not present, or you have moved away from it (going to Arduino), you can always installed a CircuitPython (or MicroPython) bootloader that can be downloaded from:

Take into consideration that there are specific builds for each kind of board / CPU. Moreover, some Adafruit libraries, are not supported on MicroPython, for example the Bus Device library.

The Integrated Development Environment

CircuitPython (and MicroPython too) comes with an integrated REPL (Read-Eval-Print-Loop) that can be accessed using the built-in USB-Serial port present in all devices. But, some of this microcontrollers present a USB Drive where we can download Python (and other kind of) files, so the board can used them.

Adafruit recommends using the Mu Editor, but I find it very limited and mainly oriented to beginners when it comes to programming languages. Most of use (developers) use Visual Studio code, and more sophisticated IDEs, with features like:

  • Integrated version control (Git)
  • Autocomplete
  • Linters
  • Automatic code formatter
  • Included Markdown editor / preview for documentation

That’s why using an IDE like Visual Studio Code makes more sense when writing an advanced application. An extension for VS Code can be found on its MarketPlace. It’s compatible with CircuitPython latests stable release (5.3.x), it’s Open Source, but it has a few issues.

Visual Studio Code with CircuitPython extension demonstrating demo autocomplete feature.
Board selection in Visual Studio Code with CircuitPython extension.

Feel free to start coding with Mu if you want to start with a more stable IDE, which also was design specifically for CircuitPython.

Mu Editor (with Dark mode).
Mu Editor has different modes based on the target platform.

Libraries and Examples

Take into consideration downloading and installing Adafruit’s CircuitPython libraries, which can be fount at https://circuitpython.org/libraries. Also, it’s always a good idea to start looking at some examples in order to get familiar with it. A bundle with a lot of examples can be download from https://github.com/adafruit/Adafruit_CircuitPython_Bundle.

Keeping Circuit Python library up-to-date

CircUp is a dependency management tool for CircuitPython developed by Adafruit. It has a very simple CLI that let’s you list, install, remove and even update, any dependency needed inside your device.

Moreover, the version of each installed library is saved in a requirements.txt file in the working directory, so it’s really simple to keep dependencies organised and versiones on Git.

Installation is done using pip, either directly or using virtualenv. Python 3.5 or higher is requiered.

pip3 install --user circup
Usage: circup [OPTIONS] COMMAND [ARGS]...
  A tool to manage and update libraries on a CircuitPython device.
Options:
  --verbose  Comprehensive logging is sent to stdout.
  --version  Show the version and exit.
  --help     Show this message and exit.
Commands:
  freeze     Output details of all the modules found on the connected...
  install    Install a named module onto the device.
  list       Lists all out of date modules found on the connected...
  show       Show a list of available modules in the bundle.
  uninstall  Uninstall a named module(s) from the connected device.
  update     Update modules on the device. Use --all to automatically update
             all modules.

Rollback from MicroPython to Arduino on ESP32

Arduino logo

I hope you find MicroPython is VERY useful and perfect for you. But just in case it doesn’t, or for any reason you want to rollback to Arduino. Here is how to do it.

Requisites

ESPTool (already installed if you went from Arduino to MicroPython)

pip3 install esptool

If there is a permissions problem doing this, try to run pip3 install either by using “sudo” or “–user” flag.

Steps

The following example assumes the USB port can be found at /dev/cu.SLAB_USBtoUART, but you may find it at /dev/ttyUSB0

  1. Erase your ESP32 Flash.
$ esptool.py --port /dev/cu.SLAB_USBtoUART erase_flash
esptool.py v2.8
Serial port /dev/cu.SLAB_USBtoUART
Connecting........__
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, Coding Scheme None
Crystal is 40MHz
MAC: 24:0a:c4:0c:94:78
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 4.1s
Hard resetting via RTS pin...

  2. Thanks it! You can now go back to Arduino IDE and build and run programs on your ESP32 board!

Another useful ESPTool’s sub command

ESPTool let us retrieve the MAC address of the device from our host. This can be used for several things, like for example creating specific setup files. In order to read the ESP32 MAC address, run ESPTool with the subcommand “read_mac” as shown below

$ esptool.py --port /dev/cu.SLAB_USBtoUART read_mac
esptool.py v2.8
Serial port /dev/cu.SLAB_USBtoUART
Connecting........__
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, Coding Scheme None
Crystal is 40MHz
MAC: 24:0a:c4:9d:24:28
Uploading stub...
Running stub...
Stub running...
MAC: 24:0a:c4:9d:24:28
Hard resetting via RTS pin...

MicroPython on an ESP32

MicroPython

Requirements

Software on the host

ESPTools and Adafruit AMPY are required. Both can be installed using pip3. The recommended version of Python on the host is Python 3.7

pip3 install esptool --upgrade
pip3 install adafruit-ampy --upgrade

Firmware for the ESP32 module

MicroPython for ESP32. The latests firmware (compatible with ESP-IDF v4.x) when writing can be found at http://micropython.org/resources/firmware/esp32-idf4-20191220-v1.12.bin

Installation

First of all erase your ESP32 completely by running the following command. Where /dev/ttyUSB0 is the Virtual COM port created by your board.

$ esptool.py --chip esp32 -p /dev/ttyUSB0 erase_flash
esptool.py v2.8
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, Coding Scheme None
Crystal is 40MHz
MAC: 24:0a:c4:0c:94:78
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 1.8s
Hard resetting via RTS pin...

Then, write the flash with the download image (esp32-idf4-20191220-v1.12.bin is this example).

$ esptool.py --chip esp32 -p /dev/ttyUSB0 write_flash -z 0x1000 esp32-idf4-20191220-v1.12.bin
esptool.py v2.8
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, Coding Scheme None
Crystal is 40MHz
MAC: 24:0a:c4:0c:94:78
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB
Compressed 1408512 bytes to 894711...
Wrote 1408512 bytes (894711 compressed) at 0x00001000 in 78.9 seconds (effective 142.9 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

Testing

After successfully flashing your ESP32 module, connect it to a Serial Monitor at 115200 baud. I like to use the embedded serial monitor that Arduino IDE has.

Perform a hard reset and you should see a console output like the one below:

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
Falling back to built-in command interpreter.
OK
>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:0x3fff0018,len:4
load:0x3fff001c,len:4988
load:0x40078000,len:10404
load:0x40080400,len:5680
entry 0x400806bc
 [0;32mI (519) cpu_start: Pro cpu up. [0m
 [0;32mI (519) cpu_start: Application information: [0m
 [0;32mI (519) cpu_start: Compile time:     Dec 20 2019 07:56:38 [0m
 [0;32mI (523) cpu_start: ELF file SHA256:  0000000000000000... [0m
 [0;32mI (529) cpu_start: ESP-IDF:          v4.0-beta1 [0m
 [0;32mI (534) cpu_start: Starting app cpu, entry point is 0x40083014 [0m
 [0;32mI (0) cpu_start: App cpu up. [0m
 [0;32mI (544) heap_init: Initializing. RAM available for dynamic allocation: [0m
 [0;32mI (551) heap_init: At 3FFAFF10 len 000000F0 (0 KiB): DRAM [0m
 [0;32mI (557) heap_init: At 3FFB6388 len 00001C78 (7 KiB): DRAM [0m
 [0;32mI (563) heap_init: At 3FFB9A20 len 00004108 (16 KiB): DRAM [0m
 [0;32mI (569) heap_init: At 3FFBDB5C len 00000004 (0 KiB): DRAM [0m
 [0;32mI (575) heap_init: At 3FFCC8A0 len 00013760 (77 KiB): DRAM [0m
 [0;32mI (582) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM [0m
 [0;32mI (588) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM [0m
 [0;32mI (594) heap_init: At 40099FB8 len 00006048 (24 KiB): IRAM [0m
 [0;32mI (601) cpu_start: Pro cpu start user code [0m
 [0;32mI (619) spi_flash: detected chip: generic [0m
 [0;32mI (619) spi_flash: flash io: dio [0m
 [0;32mI (620) cpu_start: Chip Revision: 1 [0m
 [0;33mW (621) cpu_start: Chip revision is higher than the one configured in menuconfig. Suggest to upgrade it. [0m
 [0;32mI (632) cpu_start: Starting scheduler on PRO CPU. [0m
 [0;32mI (0) cpu_start: Starting scheduler on APP CPU. [0m
MicroPython v1.12 on 2019-12-20; ESP32 module with ESP32
Type "help()" for more information.
>>> 

Integrated Development Environment

Any Python IDE may be useful for programming in MicroPython (or CircuitPython if you are using an Adafruit compatible board). I personally recommend using Mu (https://codewith.mu/). Mu is programmed in Python, so it works on Windows, Linux and macOS. It also has a portable (pen drive friendly version) which it makes it ideal for students that uses university computers.

Select ESP MicroPython. This preference can be changed later.

Testing the module can be done using the Python REPL that be have already flashed. For example, importing the machine package can give us access to getting and settings properties of our board. For example, the Huzzah32 (ESP32) board runs at 240MHz, but when flashing MicroPython the clock is set at 160Mhz. That can be check running:

MicroPython v1.12 on 2019-12-20; ESP32 module with ESP32
Type "help()" for more information.
>>> import machine
>>> machine.freq()
160000000
>>> 

Increasing the CPU frequency back to 240MHz can be done calling the same function as shown below:

>>> machine.freq(240000000)    # set frequency back to 240MHz
I (1604452) pm_esp32: Frequency switching config: CPU_MAX: 240, APB_MAX: 240, APB_MIN: 240, Light sleep: DISABLED
>>> machine.freq()
240000000
>>> 

Setting up ESP32 development environment in Linux (with Arduino IDE)

Arduino logo

Installing the IDE

Arduino logo

Download Arduino IDE from https://www.arduino.cc/en/Main/Software. The latest version when writing this a article is 1.8.12 (https://www.arduino.cc/download_handler.php?f=/arduino-1.8.12-linux64.tar.xz).

Extract the content of the tar.xz file where you want to have your Arduino IDE, and then, execute install.sh. If there is an error, like:

$ ./install.sh
Adding desktop shortcut, menu item and file associations for Arduino IDE...
ln: failed to create symbolic link '/usr/local/bin/arduino': Permission denied
Adding s

try to re run the script as root

$ sudo ./install.sh 

Installing the USB drivers

There are mainly two types of USB chips that may be used as Serial to USB converters, one from FTDI and the other one from SiLabs. In order to find out which chip your ESP32 board has, disconnect the board from your PC and run lsusb.

$ lsusb
Bus 002 Device 002: ID 0bda:0411 Realtek Semiconductor Corp. 4-Port USB 3.0 Hub
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 046d:c534 Logitech, Inc. Unifying Receiver
Bus 001 Device 010: ID 0bda:5411 Realtek Semiconductor Corp. 4-Port USB 2.0 Hub
Bus 001 Device 004: ID 8087:0aaa Intel Corp.
Bus 001 Device 003: ID 048d:8297 Integrated Technology Express, Inc. ITE Device(8595)
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Then, connect the board and repeat the command.

$ lsusb
Bus 002 Device 002: ID 0bda:0411 Realtek Semiconductor Corp. 4-Port USB 3.0 Hub
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 046d:c534 Logitech, Inc. Unifying Receiver
Bus 001 Device 012: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP2102/CP2109 UART Bridge Controller [CP210x family]
Bus 001 Device 010: ID 0bda:5411 Realtek Semiconductor Corp. 4-Port USB 2.0 Hub
Bus 001 Device 004: ID 8087:0aaa Intel Corp.
Bus 001 Device 003: ID 048d:8297 Integrated Technology Express, Inc. ITE Device(8595)
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

The new device, in this case a CP210x (Cygnal Integrated CP2102 / CP2109 UART Bridge Controller [CP210x family], is your ESP32 board.

Bus 001 Device 012: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP2102/CP2109 UART Bridge Controller [CP210x family]

Install USB driver for your board.

Adding ESP32 Boards to Arduino IDE

Arduino IDE does not support ESP32 boards (and many other 3rd party boards) by default. But adding an additional board to Arduino IDE, in this case, an ESP32 board is as easy as:

  • Start Arduino IDE and open Preferences window
  • In Additional Board Manager URLs, add the following link:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
  • You can add several board definitions, separating URLs with comma
  • Open Boards Manager from Tools; Boards; and install the ESP32 platform.
  • After installation, select your ESP32 board from Tools; Board menu.