Introduction: CircuitPython With an Itsybitsy M4 Express 1: Setup

By
About: Retired teacher of computing - started 1967 with FORTRAN IV. I now play with development boards such as Raspberry Pi, Pico, Arduino, micro:bit and Adafruit CircuitPython boards like the Insybitsy M4 and Circui…

New to coding? Only used Scratch and want to move on to a textual language which give easy access to Physical computing with LEDs, switches, displays and sensors? Then this may be for you.

I have noticed that this site contains many Instructables about coding with Arduinos using the Arduino IDE but very few about Python. I have been teaching coding since 1968. (Back then we called it programming and used FORTRAN IV with Hollerith cards for input!) Since those early days I have used many different languages with students (11 years to adult) including LISP, Pascal and many different versions on BASIC.

More recently many schools in the UK have begun using Python in their lessons as pupils make the move from 'block' coding with Scratch or similar to text statements. Python is probably an easier step up than using the Arduino IDE. CircuitPython code can be executed by simply saving the code to the development board as if it were a USB drive. I have successfully used Python for Physical Computing with 8 to 11 year olds in my granddaughter's primary school Coding Club.

I've decided to use Adafruit's Itsybitsy M4 Express for these Instructables for the following reasons:

  • Inexpensive – under $15 (£15)
  • Easy to set up and program with CircuitPython (a version of Python ideal for those new to coding)
  • Digital Input/Output pins - it is great fun playing with Blinkies
  • Analogue pins – 12 bit ADC and DAC - high accuracy
  • Red LED and RGB DotStar LEDs built in
  • Drives Neopixels directly
  • I2C and SPI supported – for sensors and displays
  • Wide range of drivers in the extensive library
  • Fast and powerful - ultra fast ATSAMD51 Cortex M4 processor running at 120 MHz
  • Plenty of memory - 2MB of SPI Flash memory for CircuitPython code or data files
  • Great support from Adafruit with full documention, guides and an internet help Forum
  • Only needs an old laptop or computer – no dedicated monitor, keyboard, power supply or mouse.
  • User can convert to Arduino IDE, on the same board, once they have gained experienced with Python.

This first Instructable explains how to set up your board and run your first scripts.

Step 1: What You Need to Get Started

Hardware:

  • Itsybitsy M4 Express (adafruit.com, Pimoroni.com)
  • microUSB cable
  • Computer - an old laptop will do
  • Soldering iron
  • Solder
  • Breadboard
  • Female header strip (Optional)

Software:

  • Mu Editor

Download the Mu editor from https://codewith.mu

Install it on your computer. Very easy with full instructions on the site.

Step 2: Check That CircuitPython Is Installed

Open File Explorer on your computer.

Plug the small end of the USB cable into the connector on the Itsybitsy.

Plug the other end of the cable into a USB port on your computer.

You should see a new drive appear called CIRCUITPY. (If not; then go on to the UPDATE page.)

Double click boot_out and you should see a message like this:

Adafruit CircuitPython 3.1.1
on 2018-11-02; Adafruit ItsyBitsy M4 Express with samd51g19

This shows that you have older version of CircuitPython as we are currently on version 4. This will be OK for now, we will update the version later. Adafruit frequently improves CircuitPython and publishes updates. These updates are very easy to install.

Navigate to your documents folder and create a new folder called Code-with-Mu inside it.

Start up the Mu Editor

Step 3: Using the Mu Editor for Your First Program

Click the Serial icon at the top of the editor. This should open the REPL window at the bottom of the screen. In the bottom left corner it should say Adafruit. Mu has recognised that a CircuitPython board has been connected to the computer.

We can now write our first program or script. Click the mouse in the upper window and type in:

print("Hello, World!")

Click on the Save icon. Select the CIRCUITPY drive. Type main.py in the title box and click on the Save button.

This does a great deal. Your script is saved to your Itsybitsy with the name "main.py". Any file with this name is immediately executed by the board. The output from the print statement appears in the lower, REPL window.

Edit the program line to:

print("\nHello, coder!") and click on the Save icon.

Try adding a few similar print statements and run your new code.

Watch your Itsybitsey as you upload a script. The flashing green DotStar goes RED while the script is saved and returns to GREEN.

Let's make an error to see what happens. Just delete the final quote character and run the script again. The editor indicates the error and the output indicates the type of error - syntax - and the line number - to help you correct the error. The DotStar indicates the fault by changing colour. More about this in a later section.

Correct the mistake and run the script again.

We now need to save our script somewhere safe so that we can use it later.

Double click the tab above your script. Navigate to your documents Code-with-Mu folder and save your script there with a useful filename such as FirstProg.py. Notice the file name and path is flashed at the bottom of the editor.

Step 4: Your Second Script - Blink

Type in the script, save it to CIRCUITPY as main.py and click Yes to replace the previous main.py.

( Always use the filename main.py for your script when saving to your ItsyBitsy. CircuitPython then immediately runs the new script.)

What the script does:

  • Imports libraries for the pin names on the board, time to control delays and digital pins control,
  • Sets up pin 13 to output voltages to the on board red LED
  • Runs an endless loop to turn the LED ON and OFF
  • Waits for short delays so that the LED blinks.

The script has plenty of comments to explain what is going on. Comments start with a '#' character. They are for human use to help remind you of your thinking at the time. Good scripts have plenty of comments.

  1. Try changing the values in the sleep() statements.
  2. Keep the LED on for twice as long as it is off.
  3. What happens if the delays are very short? (0.001 seconds)

Double click the tab above your script and save with the name Blink.py to your Code-with-Mu folder.

.

Step 5: Updating Your Version of CircuitPython

Navigate to https://circuitpython.org/downloads on the internet. Click on the picture of the Itsybitsy M4 Express (Not the M0 version).

Click on the purple button to download the .UF2 file.

Start File Explorer and locate the .UF2 file

Connect your Itsybitsy M4 Express to the USB port and locate its drive - CIRCUITPY

Double click the little reset button and the file name should change to ITSYM4BOOT from CIRCUITPY. You need to double click quite quickly.

Drag the UF2 file and drop it on the ITSYM4BOOT drive. The UF2 file will be copied to the IBM4 board and the drive name will return to CIRCUITPY.

Select the CIRCUITPY drive and double click the boot_out file.

You can read the new version number to check it has been updated.

Make a new folder on the CIRCUITPY drive called lib. We will need this in later Instructables to hold drivers for sensors and displays.

Restart the Mu editor. Load your main.py file from the IBM4 and save it back to the IBM4. The red LED should start blinking.

If you single click the reset button it will restart the loaded main.py script.

Step 6: The REPL

The window at the bottom of the editor, switched on and off with the Serial icon, is much more than just a print window.

"A read–eval–print loop (REPL), also termed an interactive top-level or language shell, is a simple, interactive computer programming environment that takes single user inputs (i.e., single expressions), evaluates them, and returns the result to the user; a program written in a REPL environment is executed piecewise." (Google)

Basically, if you write a single python statement into the REPL it executes it at once. Let's give it a try.

Click your mouse in the REPL window.

While running your script hold the <CTRL> key and tap <C> (CTRL-C). This halts your script.

Tap any key to enter the REPL and a '>>>' prompt appears.

type in print(4 + 100)

Immediately back comes the answer 104

Look at the picture and try a few of you own. (Try +, -, *, /, // and %)

Try this:

>>> import board

>>> dir(board)

['__class__', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'APA102_MOSI', 'APA102_SCK', 'D0', 'D1', 'D10', 'D11', 'D12', 'D13', 'D2', 'D3', 'D4', 'D5', 'D7', 'D9', 'I2C', 'MISO', 'MOSI', 'RX', 'SCK', 'SCL', 'SDA', 'SPI', 'TX', 'UART']

>>>

This is a list of the pin names available on the IBM4 board

To return to normal with a soft restart just type CTRL-D and main.py restarts.

Disconnecting your board

Always eject the CIRCUITPY drive before you disconnect from the computer. Never pull it out while it is transferring data.

Step 7: Putting on the Legs

The male headers are too long for the board so snap/cut 2 of them to the correct length.

Push them into a breadboard, place the IBM4 on top and solder them on. Make sure the board is the right way up! (Chip on top)

Do not put male headers across the top. I use a strip of 5 female headers across the top so that I can use all the pins. Use a vice to hold the strip of header firmly, close to the cut point. Use a sharp hacksaw to cut down the centre of a hole - the brass connector will drop out as you cut. File the cut edge to make a neat finish - no groove..

Soldering on the pins is not difficult. Look at the Arduino and Electronics courses if you have never used a soldering iron before. Being able to solder means you can make neat of long lasting versions of your projects on strip board and then reuse the breadboard.

To help prevent the board from overheating I suggest you do not solder down one side and then up the other. Leave gaps and fill in later. ie pins 10, RX, 2, A3, RS, BAT, 9, MI …...etc

Step 8: CircuitPython RGB Status Light - to Help You Find the Errors

ItsyBitsy M4 Express, and many other M0 and M4 boards all have a single NeoPixel or DotStar RGB LED on the board that indicates the status of CircuitPython. Here it is between the (C) and pin A0.

Here's what the colours and blinking mean:

  • steady GREEN: code.py (or code.txt, main.py, or main.txt) is running
  • pulsing GREEN: code.py (etc.) has finished or does not exist
  • steady YELLOW at start up: (4.0.0-alpha.5 and newer) CircuitPython is waiting for a reset to indicate that it should start in safe mode
  • pulsing YELLOW: Circuit Python is in safe mode: it crashed and restarted
  • steady WHITE: REPL is running
  • steady BLUE: boot.py is running

Colours with multiple flashes following indicate a Python exception and then indicate the line number of the error. The colour of the first flash indicates the type of error:

  • GREEN: IndentationError
  • CYAN: SyntaxError
  • WHITE: NameError
  • ORANGE: OSError
  • PURPLE: ValueError
  • YELLOW: other error

These are followed by flashes indicating the line number, including place value. WHITE flashes are thousands' place, BLUE are hundreds' place, YELLOW are tens' place, and CYAN are one's place. So, for example, an error on line 32 would flash YELLOW three times and then CYAN two times. Zeroes are indicated by an extra-long dark gap.

These are quite difficult to count. Always have the REPL window open when developing a script and the error messages, in English, will appear there.

Step 9: Looking Forward - Over to You

When I started this Instructable I expected it to be the first of a series exploring CircuitPython and Physical Computing. My plan for the next is to cover basic input and output with arithmetic, LEDs, switches, potentiometers and input statements. It will also cover looping methods and lists (arrays).

Before I write it I am requesting some feedback, so that I can tailor it to the audience.

The sort of things I would like to know are:

  • Is the pace OK?
  • Is the detail too much, too little or about right?
  • Would you like some practice exercises?

Over to you.