circuitpython-tricks

A small list of tips & tricks I find myself needing when working with CircuitPython. I find these examples useful when picking up a new project and I just want some boilerplate to get started. Also see the circuitpython-tricks/larger-tricks directory for additional ideas.

An older version of this page is a Learn Guide on Adafruit too!

If you're new to CircuitPython overall, there's no single reference, but:

The Python Tutorial on Python.org, since "CircuitPython is Python" mostly. (approx. Python 3.4)
CircuitPython API reference, particularly the "Core Modules > Modules" section in the left sidebar
- for compiled-in libraries like displayio, usb, audioio, ulab.numpy
Pure-Python libraries in Adafruit Library Bundle for drivers & helpers libraries like board, neopixel & ble
and CircuitPython Essentials Learn Guide of course

Inputs
- Read a digital input as a Button
- Read a Potentiometer
- Read a Touch Pin / Capsense
- Read a Rotary Encoder
- Debounce a pin / button
- Set up and debounce a list of pins
Outputs
- Output HIGH / LOW on a pin (like an LED)
- Output Analog value on a DAC pin
- Output a "Analog" value on a PWM pin
- Control Neopixel / WS2812 LEDs
- Control a servo, with animation list
Neopixels / Dotstars
- Moving rainbow on built-in board.NEOPIXEL
- Make moving rainbow gradient across LED strip
- Fade all LEDs by amount for chase effects
Audio
- Audio out using PWM
- Audio out using DAC
- Audio out using I2S
- Play multiple sounds with audiomixer
- Playing MP3 files
- Making simple tones
USB
- Rename CIRCUITPY drive to something new
- Detect if USB is connected or not
- Get CIRCUITPY disk size and free space
- Programmatically reset to UF2 bootloader
USB Serial
- Print to USB Serial
- Read user input from USB Serial, blocking
- Read user input from USB Serial, non-blocking (mostly)
- Read keys from USB Serial
- Read user input from USB serial, non-blocking
USB MIDI
- Sending MIDI with adafruit_midi
- Sending MIDI with bytearray
- MIDI over Serial UART
- Receving MIDI USB and MIDI Serial UART together
- Enable USB MIDI in boot.py (for ESP32S2 and STM32F4)
WiFi / Networking
- Scan for WiFi Networks, sorted by signal strength
- Ping an IP address
- Get IP address of remote host
- Fetch a JSON file
- Serve a webpage via HTTP
- Set RTC time from NTP
- Set RTC time from time service
- What the heck is settings.toml?
- What the heck is secrets.py?
Displays (LCD / OLED / E-Ink) and displayio
- Get default display and change display rotation
- Display an image
- Display background bitmap
- Image slideshow
- Dealing with E-Ink "Refresh Too Soon" error
I2C
- Scan I2C bus for devices
- Speed up I2C bus
Timing
- Measure how long something takes
- More accurate timing with ticks_ms(), like Arduino millis()
Board Info
- Display amount of free RAM
- Show microcontroller.pin to board mappings
- Determine which board you're on
- Support multiple boards with one code.py
Computery Tasks
- Formatting strings
- Formatting strings with f-strings
- Using regular expressions to "findall" strings
- Make and use a config file
- Run different code.py on startup
Coding Techniques
- Map an input range to an output range
- Constrain an input to a min/max
- Turn a momentary value into a toggle
- Do something every N seconds without sleep()
System error handling
- Preventing Ctrl-C from stopping the program
- Prevent auto-reload when CIRCUITPY is touched
- Raspberry Pi Pico boot.py Protection
Hacks
- Using the REPL
Python tricks
- Create list with elements all the same value
- Convert RGB tuples to int and back again
- Storing multiple values per list entry
Python info
- Display which (not built-in) libraries have been imported
- List names of all global variables
- Display the running CircuitPython release
Host-side tasks
- Installing CircuitPython libraries
  - Installing libraries with circup
  - Copying libraries by hand with cp
- Preparing images for CircuitPython
- Preparing audio files for CircuitPython
- Circup hacks
About this guide

Inputs

Read a digital input as a Button

import board
from digitalio import DigitalInOut, Pull
button = DigitalInOut(board.D3) # defaults to input
button.pull = Pull.UP # turn on internal pull-up resistor
print(button.value)  # False == pressed

Can also do:

import time, board, digitalio
button = digitalio.DigitalInOut(board.D3)
button.switch_to_input(digitalio.Pull.UP)
while True:
    print("button pressed:", button.value == False) # False == pressed
    time.sleep(0.1)

Read a Potentiometer

import board
import analogio
potknob = analogio.AnalogIn(board.A1)
position = potknob.value  # ranges from 0-65535
pos = potknob.value // 256  # make 0-255 range

Note: While AnalogIn.value is 16-bit (0-65535) corresponding to 0 V to 3.3V, the MCU ADCs can have limitations in resolution and voltage range. This reduces what CircuitPython sees. For example, the ESP32 ADCs are 12-bit w/ approx 0.1 V to 2.5 V range (e.g. value goes from around 200 to 50,000, in steps of 16)

Read a Touch Pin / Capsense

import touchio
import board
touch_pin = touchio.TouchIn(board.GP6)
# on Pico / RP2040, need 1M pull-down on each input
if touch_pin.value:
print("touched!")

Read a Rotary Encoder

import board
import rotaryio
encoder = rotaryio.IncrementalEncoder(board.GP0, board.GP1) # must be consecutive on Pico
print(encoder.position)  # starts at zero, goes neg or pos

Debounce a pin / button

import board
from digitalio import DigitalInOut, Pull
from adafruit_debouncer import Debouncer
button_in = DigitalInOut(board.D3) # defaults to input
button_in.pull = Pull.UP # turn on internal pull-up resistor
button = Debouncer(button_in)
while True:
    button.update()
    if button.fell:
        print("press!")
    if button.rose:
      print("release!")

Set up and debounce a list of pins

import board
from digitalio import DigitalInOut, Pull
from adafruit_debouncer import Debouncer
button_pins = (board.GP0, board.GP1, board.GP2, board.GP3, board.GP4)
buttons = []   # will hold list of Debouncer objects
for pin in button_pins:   # set up each pin
    tmp_pin = DigitalInOut(pin) # defaults to input
    tmp_pin.pull = Pull.UP      # turn on internal pull-up resistor
    buttons.append( Debouncer(tmp_pin) )
while True:
    for i in range(len(buttons)):
        buttons[i].update()
        if buttons[i].fell:
            print("button",i,"pressed!")
        if buttons[i].rose:
            print("button",i,"released!")

If your board's CircuitPython has the keypad library (most do), then I recommend using it. It's not just for key matrixes! And it's more efficient and, since it's built-in, reduces a library dependency.

import board
import keypad
button_pins = (board.GP0, board.GP1, board.GP2, board.GP3, board.GP4)
buttons = keypad.Keys(button_pins, value_when_pressed=False, pull=True)

while True:
    button = buttons.events.get()  # see if there are any key events
    if button:                      # there are events!
      if button.pressed:
        print("button", button.key_number, "pressed!")
      if button.released:
        print("button", button.key_number, "released!")

Outputs

Output HIGH / LOW on a pin (like an LED)

import board
import digitalio
ledpin = digitalio.DigitalInOut(board.D2)
ledpin.direction = digitalio.Direction.OUTPUT
ledpin.value = True

Can also do:

ledpin = digitalio.DigitalInOut(board.D2)
ledpin.switch_to_output(value=True)

Output Analog value on a DAC pin

Different boards have DAC on different pins

import board
import analogio
dac = analogio.AnalogOut(board.A0)  # on Trinket M0 & QT Py
dac.value = 32768   # mid-point of 0-65535

Output a "Analog" value on a PWM pin

import board
import pwmio
out1 = pwmio.PWMOut(board.MOSI, frequency=25000, duty_cycle=0)
out1.duty_cycle = 32768  # mid-point 0-65535 = 50 % duty-cycle

Control Neopixel / WS2812 LEDs

import neopixel
leds = neopixel.NeoPixel(board.NEOPIXEL, 16, brightness=0.2)
leds[0] = 0xff00ff  # first LED of 16 defined
leds[0] = (255,0,255)  # equivalent
leds.fill( 0x00ff00 )  # set all to green

Control a servo, with animation list

# servo_animation_code.py -- show simple servo animation list
import time, random, board
from pwmio import PWMOut
from adafruit_motor import servo

# your servo will likely have different min_pulse & max_pulse settings
servoA = servo.Servo(PWMOut(board.RX, frequency=50), min_pulse=500, max_pulse=2250)

# the animation to play
animation = (
    # (angle, time to stay at that angle)
    (0, 2.0),
    (90, 2.0),
    (120, 2.0),
    (180, 2.0)
)
ani_pos = 0 # where in list to start our animation

while True:
    angle, secs = animation[ ani_pos ]
    print("servo moving to", angle, secs)
    servoA.angle = angle
    time.sleep( secs )
    ani_pos = (ani_pos + 1) % len(animation) # go to next, loop if at end

Neopixels / Dotstars

Moving rainbow on built-in `board.NEOPIXEL`

In CircuitPython 7, the rainbowio module has a colorwheel() function. Unfortunately, the rainbowio module is not available in all builds. In CircuitPython 6, colorwheel() is a built-in function part of _pixelbuf or adafruit_pypixelbuf.

The colorwheel() function takes a single value 0-255 hue and returns an (R,G,B) tuple given a single 0-255 hue. It's not a full HSV_to_RGB() function but often all you need is "hue to RGB", wher you assume saturation=255 and value=255. It can be used with neopixel, adafruit_dotstar, or any place you need a (R,G,B) 3-byte tuple. Here's one way to use it.

# CircuitPython 7 with or without rainbowio module
import time, board, neopixel
try:
    from rainbowio import colorwheel
except:
    def colorwheel(pos):
        if pos < 0 or pos > 255:  return (0, 0, 0)
        if pos < 85: return (255 - pos * 3, pos * 3, 0)
        if pos < 170: pos -= 85; return (0, 255 - pos * 3, pos * 3)
        pos -= 170; return (pos * 3, 0, 255 - pos * 3)

led = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.4)
while True:
    led.fill( colorwheel((time.monotonic()*50)%255) )
    time.sleep(0.05)

Make moving rainbow gradient across LED strip

See demo of it in this tweet.

import time, board, neopixel, rainbowio
num_leds = 16
leds = neopixel.NeoPixel(board.D2, num_leds, brightness=0.4, auto_write=False )
delta_hue = 256//num_leds
speed = 10  # higher numbers = faster rainbow spinning
i=0
while True:
  for l in range(len(leds)):
    leds[l] = rainbowio.colorwheel( int(i*speed + l * delta_hue) % 255  )
  leds.show()  # only write to LEDs after updating them all
  i = (i+1) % 255
  time.sleep(0.05)

A shorter version using a Python list comprehension. The leds[:] trick is a way to assign a new list of colors to all the LEDs at once.

import supervisor, board, neopixel, rainbowio
num_leds = 16
speed = 10  # lower is faster, higher is slower
leds = neopixel.NeoPixel(board.D2, 16, brightness=0.4)
while True:
  t = supervisor.ticks_ms() / speed
  leds[:] = [rainbowio.colorwheel( t + i*(255/len(leds)) ) for i in range(len(leds))]

Fade all LEDs by amount for chase effects

import time
import board, neopixel
num_leds = 16
leds = neopixel.NeoPixel(board.D2, num_leds, brightness=0.4, auto_write=False )
my_color = (55,200,230)
dim_by = 20  # dim amount, higher = shorter tails
pos = 0
while True:
  leds[pos] = my_color
  leds[:] = [[max(i-dim_by,0) for i in l] for l in leds] # dim all by (dim_by,dim_by,dim_by)
  pos = (pos+1) % num_leds  # move to next position
  leds.show()  # only write to LEDs after updating them all
  time.sleep(0.05)

Audio

In CircuitPython, there are three different techniques to output audio:

audioio -- uses built-in DAC
audiopwmio -- uses PWM like arduino analogWrite(), requires RC filter to convert to analog
audiobusio -- output I2S data stream, requires external I2S decoder hardware

CircuitPython's support on particular microcontroller may include support for more than one of the above:

e.g. SAMD51 (Feather M4) supports DAC and I2S, RP2040 (Pico) supports PWM and I2S

CircuitPython can play WAV and MP3 files, but they must be formatted correctly.

See Preparing Audio Files for CircuitPython

Audio out using PWM

This uses the audiopwmio library, only available for Raspberry Pi Pico (or other RP2040-based boards) and NRF52840-based boards like Adafruit Feather nRF52840 Express. On RP2040-based boards, any pin can be PWM Audio pin. See the audiopwomio Support Matrix for which boards support audiopwmio.

import time, board
from audiocore import WaveFile
from audiopwmio import PWMAudioOut as AudioOut
wave_file = open("laser2.wav", "rb")
wave = WaveFile(wave_file)
audio = AudioOut(board.TX) # must be PWM-capable pin
while True:
    print("audio is playing:",audio.playing)
    if not audio.playing:
      audio.play(wave)
      wave.sample_rate = int(wave.sample_rate * 0.90) # play 10% slower each time
    time.sleep(0.1)

Note: Sometimes the audiopwmio driver gets confused, particularly if there's other USB access, so you may have to reset the board to get PWM audio to work again.

Note: PWM output must be filtered and converted to line-level to be usable. Use an RC circuit to accomplish this, see this twitter thread for details.

Audio out using DAC

Some CircuitPython boards (SAMD51 "M4" & SAMD21 "M0") have built-in DACs that are supported. The code is the the same as above, with just the import line changing. See the audioio Support Matrix for which boards support audioio.

import time, board
import audiocore, audioio # DAC
wave_file = open("laser2.wav", "rb")
wave = audiocore.WaveFile(wave_file)
audio = audioio.AudioOut(board.A0)  # must be DAC-capable pin, A0 on QTPy Haxpress
while True:
  print("audio is playing:",audio.playing)
  if not audio.playing:
    audio.play(wave)
    wave.sample_rate = int(wave.sample_rate * 0.90) # play 10% slower each time
  time.sleep(0.1)

Audio out using I2S

Unlike PWM or DAC, most CircuitPython boards support driving an external I2S audio board. This will also give you higher-quality sound output than DAC or PWM. See the audiobusio Support Matrix for which boards support audiobusio.

# for e.g. Pico RP2040 pins bit_clock & word_select pins must be adjacent
import board, audiobusio, audiocore
audio = audiobusio.I2SOut(bit_clock=board.GP0, word_select=board.GP1, data=board.GP2)
audio.play( audiocore.WaveFile("laser2.wav","rb") )

Play multiple sounds with audiomixer

This example assumes WAVs that are mono 22050 Hz sample rate, w/ signed 16-bit samples.

import time, board, audiocore, audiomixer
from audiopwmio import PWMAudioOut as AudioOut

wav_files = ("loop1.wav", "loop2.wav", "loop3.wav")
wavs = [None] * len(wav_files)  # holds the loaded WAVs

audio = AudioOut(board.GP1)  # RP2040 example
mixer = audiomixer.Mixer(voice_count=len(wav_files), sample_rate=22050, channel_count=1,
                         bits_per_sample=16, samples_signed=True)
audio.play(mixer)  # attach mixer to audio playback

for i in range(len(wav_files)):
    print("i:",i)
    wavs[i] = audiocore.WaveFile(open(wav_files[i], "rb"))
    mixer.voice[i].play( wavs[i], loop=True) # start each one playing

while True:
    print("doing something else while all loops play")
    time.sleep(1)

Also see the many examples in larger-tricks.

Playing MP3 files

Once you have set up audio output (either directly or via AudioMixer), you can play WAVs or MP3s through it, or play both simultaneously.

For instance, here's an example that uses an I2SOut to a PCM5102 on a Raspberry Pi Pico RP2040 to simultaneously play both a WAV and an MP3:

import board, audiobusio, audiocore, audiomp3
num_voices = 2

i2s_bclk, i2s_wsel, i2s_data = board.GP9, board.GP10, board.GP11 # BCLK, LCLK, DIN on PCM5102

audio = audiobusio.I2SOut(bit_clock=i2s_bclk, word_select=i2s_wsel, data=i2s_data)
mixer = audiomixer.Mixer(voice_count=num_voices, sample_rate=22050, channel_count=1,
                         bits_per_sample=16, samples_signed=True)
audio.play(mixer) # attach mixer to audio playback

wav_file = "/amen1_22k_s16.wav" # in 'circuitpython-tricks/larger-tricks/breakbeat_wavs'
mp3_file = "/vocalchops476663_22k_128k.mp3" # in 'circuitpython-tricks/larger-tricks/wav'
# https://freesound.org/people/f-r-a-g-i-l-e/sounds/476663/

wave = audiocore.WaveFile(open(wav_file, "rb"))
mp3 = audiomp3.MP3Decoder(open(mp3_file, "rb"))
mixer.voice[0].play( wave )
mixer.voice[1].play( mp3 )

while True:
    pass   # both audio files play

Note: For MP3 files, be aware that since this is doing software MP3 decoding, you will likely need to re-encode the MP3s to lower bitrate and sample rate (max 128 kbps and 22,050 Hz) to be playable the lower-end CircuitPython devices like the Pico / RP2040.

Note: For MP3 files and setting loop=True when playing, there is a small delay when looping. WAV files loop seemlessly.

Making simple tones

For devices that only have pwmio capability, you can make simple tones. The simpleio library can be used for this:

# a short piezo song using tone()
import time, board, simpleio
while True:
    for f in (262, 294, 330, 349, 392, 440, 494, 523):
        simpleio.tone(board.A0, f, 0.25)
    time.sleep(1)

An example of boards with pwmio but no audio are ESP32-S2-based boards like FunHouse, where you cannot play WAV files, but you can make beeps. A larger example is this gist: https://gist.github.com/todbot/f35bb5ceed013a277688b2ca333244d5

USB

Rename CIRCUITPY drive to something new

For instance, if you have multiple of the same device. The label can be up to 11 characters. This goes in boot.py not code.py and you must powercycle board.

# this goes in boot.py not code.py!
new_name = "TRINKEYPY0"
import storage
storage.remount("/", readonly=False)
m = storage.getmount("/")
m.label = new_name
storage.remount("/", readonly=True)

Detect if USB is connected or not

import supervisor
if supervisor.runtime.usb_connected:
  led.value = True   # USB
else:
  led.value = False  # no USB

An older way that tries to mount CIRCUITPY read-write and if it fails, USB connected:

def is_usb_connected():
    import storage
    try:
        storage.remount('/', readonly=False)  # attempt to mount readwrite
        storage.remount('/', readonly=True)  # attempt to mount readonly
    except RuntimeError as e:
        return True
    return False
is_usb = "USB" if is_usb_connected() else "NO USB"
print("USB:", is_usb)

Get CIRCUITPY disk size and free space

import os
fs_stat = os.statvfs('/')
print("Disk size in MB", fs_stat[0] * fs_stat[2] / 1024 / 1024)
print("Free space in MB", fs_stat[0] * fs_stat[3] / 1024 / 1024)

Programmatically reset to UF2 bootloader

import microcontroller
microcontroller.on_next_reset(microcontroller.RunMode.UF2)
microcontroller.reset()

Note: in older CircuitPython use RunMode.BOOTLOADER and for boards with multiple bootloaders (like ESP32-S2):

import microcontroller
microcontroller.on_next_reset(microcontroller.RunMode.BOOTLOADER)
microcontroller.reset()

USB Serial

Print to USB Serial

print("hello there")  # prints a newline
print("waiting...", end='')   # does not print newline
for i in range(256):  print(i, end=', ')   # comma-separated numbers

Read user input from USB Serial, blocking

while True:
    print("Type something: ", end='')
    my_str = input()  # type and press ENTER or RETURN
    print("You entered: ", my_str)

Read user input from USB Serial, non-blocking (mostly)

import time
import supervisor
print("Type something when you're ready")
last_time = time.monotonic()
while True:
    if supervisor.runtime.serial_bytes_available:
        my_str = input()
        print("You entered:", my_str)
    if time.monotonic() - last_time > 1:  # every second, print
        last_time = time.monotonic()
        print(int(last_time),"waiting...")

Read keys from USB Serial

import time, sys, supervisor
print("type charactcers")
while True:
    n = supervisor.runtime.serial_bytes_available
    if n > 0:  # we read something!
        s = sys.stdin.read(n)  # actually read it in
        # print both text & hex version of recv'd chars (see control chars!)
        print("got:", " ".join("{:s} {:02x}".format(c,ord(c)) for c in s))
    time.sleep(0.01) # do something else

Read user input from USB serial, non-blocking

class USBSerialReader:
    """ Read a line from USB Serial (up to end_char), non-blocking, with optional echo """
    def __init__(self):
        self.s = ''
    def read(self,end_char='\n', echo=True):
        import sys, supervisor
        n = supervisor.runtime.serial_bytes_available
        if n > 0:                    # we got bytes!
            s = sys.stdin.read(n)    # actually read it in
            if echo: sys.stdout.write(s)  # echo back to human
            self.s = self.s + s      # keep building the string up
            if s.endswith(end_char): # got our end_char!
                rstr = self.s        # save for return
                self.s = ''          # reset str to beginning
                return rstr
        return None                  # no end_char yet

usb_reader = USBSerialReader()
print("type something and press the end_char")
while True:
    mystr = usb_reader.read()  # read until newline, echo back chars
    #mystr = usb_reader.read(end_char='\t', echo=False) # trigger on tab, no echo
    if mystr:
        print("got:",mystr)
    time.sleep(0.01)  # do something time critical

USB MIDI

CircuitPython can be a MIDI controller, or respond to MIDI! Adafruit provides an adafruit_midi class to make things easier, but it's rather complex for how simple MIDI actually is. So for outputting MIDI, you can opt to just do raw bytearrays. For reading MIDI, I recommend Winterbloom's SmolMIDI.

Sending MIDI with adafruit_midi

import usb_midi
import adafruit_midi
from adafruit_midi.note_on import NoteOn
from adafruit_midi.note_off import NoteOff
midi_out_channel = 3 # human version of MIDI out channel (1-16)
midi = adafruit_midi.MIDI( midi_out=usb_midi.ports[1], out_channel=midi_out_channel-1)

def play_note(note,velocity=127):
    midi.send(NoteOn(note, velocity))  # 127 = highest velocity
    time.sleep(0.1)
    midi.send(NoteOff(note, 0))  # 0 = lowest velocity

Sending MIDI with bytearray

Since we're often battling timing issues in CircuitPython and humans can detect musical timing differences very easily, we can gain back some overhead by using usb_midi directly.

This code is equivalent to the above, without adafruit_midi

import usb_midi
midi_out = usb_midi.ports[1]
midi_out_channel = 3
note_on_status = (0x90 | (midi_out_channel-1))
note_off_status = (0x80 | (midi_out_channel-1))

def play_note(note,velocity=127):
    midi_out.write( bytearray([note_on_status, note, velocity]) )
    time.sleep(0.1)
    midi_out.write( bytearray([note_off_status, note, 0]) )

MIDI over Serial UART

Not exactly USB, but it is MIDI! Both adafruit_midi and the bytearray technique works for Serial MIDI too. With a simple MIDI out circuit you can control old hardware synths.

import busio
midi_out_channel = 3 # human version of MIDI out channel (1-16)
note_on_status = (0x90 | (midi_out_channel-1))
note_off_status = (0x80 | (midi_out_channel-1))
midi_uart = busio.UART(tx=board.GP16, rx=board.GP17, baudrate=31250)

def play_note(note,velocity=127):
    midi_uart.write( bytearray([note_on_status, note, velocity]) )
    time.sleep(0.1)
    midi_uart.write( bytearray([note_off_status, note, 0]) )

Receving MIDI USB and MIDI Serial UART together

MIDI is MIDI, so you can use either the midi_uart or the usb_midi.ports[] created above with adafruit_midi. Here's an example receiving MIDI from both USB and Serial on a QTPy RP2040. Note for receiving serial MIDI, you need an appropriate optoisolator input circuit, like this one for QTPys or this one for MacroPad RP2040.

import board, busio
import usb_midi        # built-in library
import adafruit_midi   # install with 'circup install adafruit_midi'
from adafruit_midi.note_on import NoteOn
from adafruit_midi.note_off import NoteOff

uart = busio.UART(tx=board.TX, rx=board.RX, baudrate=31250, timeout=0.001)
midi_usb = adafruit_midi.MIDI( midi_in=usb_midi.ports[0],  midi_out=usb_midi.ports[1] )
midi_serial = adafruit_midi.MIDI( midi_in=uart, midi_out=uart )

while True:
    msg = midi_usb.receive()
    if msg is not None:
        if isinstance(msg, NoteOn):
            print("usb noteOn:",msg.note, msg.velocity)
        elif isinstance(msg, NoteOff):
            print("usb noteOff:",msg.note, msg.velocity)
    msg = midi_serial.receive()
    if msg is not None:
        if isinstance(msg, NoteOn):
            print("serial noteOn:",msg.note, msg.velocity)
        elif isinstance(msg, NoteOff):
            print("serial noteOff:",msg.note, msg.velocity)

Enable USB MIDI in boot.py (for ESP32S2 and STM32F4)

Some CircuitPython devices like ESP32-S2 based ones, do not have enough USB endpoints to enable all USB functions, so USB MIDI is disabled by default. To enable it, the easiest is to disable USB HID (keyboard/mouse) support. This must be done in boot.py and the the board power cycled.

# boot.py
import usb_hid
import usb_midi
usb_hid.disable()
usb_midi.enable()
print("enabled USB MIDI, disabled USB HID")