CircuitPython

Notes about Circuit-Python.

On line is possible to find tons of documentation and description, this is just a my notes collection about Circuit-Python, another fast prototyping system like Arduino IDE.

Circuit-Python is a development environment that (supposedly) allows in a easy way to develop Python code for embedded and load it on compatible devices.

As many "new" way to deal with embedded the idea is maybe good, but like Arduino everything is based on what you can find.
Good way to fast prototyping though (like Arduino) so can be worth taking a look.

First of all, I'm quite sure the system was developed mainly thinking about Mac and Windows.
Using it under Linux is just a NIGHTMARE !

My Linux box for development

Note !
My Linux system IS A MESS !

I'm quite sure many problems I have are because the system messed up due to find a decent way to manage monitors with an old graphic card (hopefully soon I should be able to improve things)

My Linux system is supposedly based on KDE but running an ibrid of Gnome and Lubutnu (very complicate to explain why, let say is because the graphic card I have is quite poor and some GUI are not handled it correctly).

This just to give a possible explanation about the problems I have.

This article describes/documents what to do under Linux, specifically Ubuntu 18.04.

The basics - what is Circuit-Python ?

Ok, Circuit-Python

Very briefly we can say Circuit-Python is basically a kind of RTOS/Development system for embedded boards.

To develop some code under Circuit-Python we need few things :

a host running Windows/Mac/Linux and a USB port to connect compatible boards
a Circuit-Python compatible embedded board
an IDE (optional)
a way to load Circuit-Python in a board

Let start from the board.

Circuit-Python boards

Circuit-Python needs a board with already burned some code, called "firmware" (ok ok the term is generic but is what is used in Circuit-Python lingo to indicate the "code base" to have on the board).

Basically the loaded basic code in the board supports the peripherals and allow to "dialog" with an IDE to load user applications or anyway allow the board to be seen as a USB flash pen drive.
Circuit-Python can be seen as a kind of RTOS, capable to execute some code and interact with the development machine.

Adafruit but also others vendors, have Circuit-Python compatible boards.
For example :

But also other boards are supposedly compatible with Circuit-Python and exists a firmware for it, for example :

Adafruit Feather M0 Adalogger

The point is that without a compatible board running the base code of Circuit-Python is NOT possible to work.
On this page is possible to see what boards are currently supported by Circuit-Python.

The IDE

The IDE supposedly is necessary to facilitate the development of code and debug of the code.
Exists a specific IDE developed for Circuit-Python called Mu-editor and here is where the nightmare starts.

For Windows and Mac (I did not try to install on that systems yet) I'm sure the installers available are enough and straightforward but for Linux .. is a mess.

Is possible to use pip to install it but there are incompatibility with some versions of Python (suggested to use the 3.7), for Ubuntu is also possible to use snap for the installation, it do install it but the app crashes on some choices unless you install it using the --dev switch :

sudo snap install --edge mu-editor --devmode

Is also possible to install from github and pip (different procedure).

In the end I followed this set of instructions to install mu-editor on my machine using a virtual environment for Python 3.7 and FINALLY did compile but I'm not sure is actually usable, it doesn't full recognize the board connected and is quite unstable.

This is the most stable way I did find on my system to install and execute mu :

open a terminal
install venv
sudo pip3 install virtualenv
create a venv working directory (I did use MyApps)
virtualenv ~/MyApps
this creates a bin directory under ~/MyApps
activate the virtual environment
source ~/MyApps/bin/activate
clone the mu editor from gitHub
git clone https://github.com/mu-editor/mu.git
enter in the sandbox
cd mu
install the code
pip3 install -e ".[dev]"
execute it
python run.py

To run it after that :

open a terminal
activate the virtual environment
source ~/MyApps/bin/activate
enter in the sandbox
cd ~/MyApps/mu
execute it
python run.py

Note, is not necessary to use the IDE, is possible to edit the Python code with any editor and then manually load the code in the board.

More details in other articles devoted to specific boards.

IDE alternatives

Also other IDEs can be used, like PyCharm as described here altough is claimed not working.
Not sure I'm willing to spend much time on that issue.

Alternatively there is another way to work on a board.

Via the File Manager and a serial terminal.

When connecting a board to the computer via USB two channels are opened.
One is a serial channel, usually allocated to /dev/ttyACM0 and the other channel allows to see the accessible memory content via The File Manager.

Opening a serial terminal will allow to issue commands and debug the code, or at least showing errors.
Via this way is also possible to activate the REPL mode that allow to try interactively some code and access the memory.

To access the board for example, just use screen :

screen /dev/ttyACM0

This an example of the screen session running a test code to check the WiFI access on a ESP286 board.

Loading Circuit-Python in a board

Unless using a board with already loaded Circuit-Python firmware, is necessary to have a way to load it on the board.
Some boards have in the flash a code that when forced in bootloader mode, present themselves as an USB drive.
For these boards is enough to force the bootloader and then copy in it a file formatted in UF2 way (available here).
But for boards without presenting themselves as a USB drive, is necessary to "burn" a binary image (also available here) using a burner, like bossac.
Note that many distribution have bossac (for example sudo apt-get install bossa-cli) but often is an OLD version and not suitable with many boards.

CAUTION !
Pay a LOT of attention when using this tool since is possible to burn out the protection fuse of the board making it a useless brick !!

For example here is possible to find detailed instructions about how to install bossac from source.

Once having the utility working is enough to load the binary image in the board.
Note that if you have installed Arduino you should arelady have in it a version of bossac, however it is suggested to ALWAYS use the latest one.

Installing bossac from source on Ubuntu 18.04

Follow this procedure to install the latest bossac.
The example describes the installation over Ubuntu 18.04.

Before to start be sure to have installed on the system the basic to compile in C++ and :

the library libreadline-dev
sudo apt-get install libreadline-dev

Once the system is ready :

open a terminal
clone from git the latest source code from this gitHub repo : BOSSA.
In the example the release 1.9.1 is used.
enter in the created directory and compile the code
make
if everything is fine a directory bin will be created with 3 executable :

bossa
bossac
bossash

Circuit-Python structure

Ok, so to simplify the concept, let say Circuit-Python can be seen as a kind of RTOS.

The idea is simple, when the board is powered up Circuit-Python on the board execute whatever code is present.
When the board is connected via USB to a computer is seen as a USB flash pen drive.

A fresh installed Circuit-Python has very few thing "visible" in it and what is in depends about the type of board.
For example, after flashing the Adafruit Feather M0 Adalogger is seen as a drive with this files in it.
Note that LOT of what in the Circuit-Python is not visible nor accessible in this way (see the documentation about the Circuit-Python for the M0 adalogger).

Here what is in it :

The board is seen as a drive called CIRCUITPY and has an empty directory called lib, where to put any library needed for the specific job.

On the "root" is present a file called boot_out.txt containing some information about the installed version of Circuit-Python.

For example :

Adafruit CircuitPython 6.0.0 on 2020-11-16; Adafruit Feather M0 Adalogger with samd21g18

i.e. we can see the name of the board (Adafruit Feather M0 Adalogger), the type of processor (samd21g18) and the version of Circuit-Python installed (Adafruit CircuitPython 6.0.0 on 2020-11-16) that specify also the type of interface needed from an IDE to be recognized (Adafruit).

Note.
On many boards is enough to press twice the reset button to force the board in bootloader mode.
When in this mode is possible to flash it with the Circuit-Python, loading directly the code in UFS format or via bossac a binary image.

The code to be executed need to be placed in the root and the main file need to be called :

TBD

The M0 Adalogger doesn't have much flash, about 256K.
After loading Circuit-Python the available space on the board for libraries and code is about 40K !!! Not much indeed !

Now what ?

Ok, now we have a board with Circuit-Python working and an IDE running on the host.

At this point should be possible just to connect the board to the host and start the IDE that "should" recognize the board OR see the board as a USB flash pen drive and simply load the necessary code in it.