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
- Detect button double-click
- 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
- Light each LED in order
- Moving rainbow on built-in board.NEOPIXEL
- Make moving rainbow gradient across LED strip
- Fade all LEDs by amount for chase effects
Audio
- Making simple tones
- Play a WAV file
- Audio out using PWM
- Audio out using DAC
- Audio out using I2S
- Use audiomixer to prevent audio crackles
- Play multiple sounds with audiomixer
- Playing MP3 files
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 Keyboard & Mouse
- Sending keystrokes and mouse moves
USB MIDI
- Sending MIDI with adafruit_midi
- Sending MIDI with bytearray
- MIDI over Serial UART
- Receiving MIDI
- Receiving MIDI USB and MIDI Serial UART together
- Enable USB MIDI in boot.py (for ESP32-S2 and STM32F4)
WiFi / Networking
- Scan for WiFi Networks, sorted by signal strength
- Join WiFi network with highest 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
- Turn off REPL on built-in display
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()
- Control garbage collection for reliable timing
- Converting milliseconds to seconds: 0.004 * 1000 != 4, sometimes
Board Info
- Get CPU speed (and set it!)
- 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
Using the REPL
- Display built-in modules / libraries
- Turn off built-in display to speed up REPL printing
- Useful REPL one-liners
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
  - Finding where circup stores its files
- Building CircuitPython
About this guide

Inputs

Read a digital input as a Button

importboardfromdigitalioimportDigitalInOut, Pullbutton=DigitalInOut(board.D3) # defaults to inputbutton.pull=Pull.UP# turn on internal pull-up resistorprint(button.value) # False == pressed

Can also do:

importtime, board, digitaliobutton=digitalio.DigitalInOut(board.D3)
button.switch_to_input(digitalio.Pull.UP)
whileTrue:
print("button pressed:", button.value==False) # False == pressedtime.sleep(0.1)

But you probably want to use keypad to get debouncing and press/release events. You can use it for a single button!

importboard, keypadkeys=keypad.Keys((board.D3,), value_when_pressed=False, pull=True)
whileTrue:
ifkey:=keys.events.get():
ifkey.pressed:
print("pressed key!")

Note: be sure to add the comma when using a single button (e.g. (board.D3,))

Read a Potentiometer

importboardimportanalogiopotknob=analogio.AnalogIn(board.A1)
position=potknob.value# ranges from 0-65535pos=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

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

You can also get an "analog" touch value with touch_pin.raw_value to do basic proximity detection or even theremin-like behavior.

Read a Rotary Encoder

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

Debounce a pin / button

But you probably want to use keypad to get debouncing and press/release events. You can use it for a single button!

importboard, keypadkeys=keypad.Keys((board.D3,), value_when_pressed=False, pull=True)
whileTrue:
ifkey:=keys.events.get():
ifkey.pressed:
print("pressed key!", key.key_number)
ifkey.released:
print("released key!", key.key_number)

Note: be sure to add the comma when using a single button (e.g. (board.D3,))

If your board doesn't have keypad, you can use adafruit_debouncer from the bundle.

importboardfromdigitalioimportDigitalInOut, Pullfromadafruit_debouncerimportDebouncerbutton_in=DigitalInOut(board.D3) # defaults to inputbutton_in.pull=Pull.UP# turn on internal pull-up resistorbutton=Debouncer(button_in)
whileTrue:
button.update()
ifbutton.fell:
print("press!")
ifbutton.rose:
print("release!")

Note: Most boards have the native keypad module that can do keypad debouncing in a much more efficient way. See Set up and debounce a list of pins

Detect button double-click

importboardfromdigitalioimportDigitalInOut, Pullfromadafruit_debouncerimportButtonbutton_in=DigitalInOut(board.D3) # defaults to inputbutton_in.switch_to_input(Pull.UP) # turn on internal pull-up resistorbutton=Button(button_in)
whileTrue:
button.update()
ifbutton.pressed:
print("press!")
ifbutton.released:
print("release!")
ifbutton.short_count>1: # detect multi-clickprint("multi-click: click count:", button.short_count)

Set up and debounce a list of pins

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.

importboardimportkeypadbutton_pins= (board.GP0, board.GP1, board.GP2, board.GP3, board.GP4)
buttons=keypad.Keys(button_pins, value_when_pressed=False, pull=True)
whileTrue:
button=buttons.events.get() # see if there are any key eventsifbutton: # there are events!ifbutton.pressed:
print("button", button.key_number, "pressed!")
ifbutton.released:
print("button", button.key_number, "released!")

Otherwise, you can use adafruit_debouncer:

importboardfromdigitalioimportDigitalInOut, Pullfromadafruit_debouncerimportDebouncerbutton_pins= (board.GP0, board.GP1, board.GP2, board.GP3, board.GP4)
buttons= [] # will hold list of Debouncer objectsforpininbutton_pins: # set up each pintmp_pin=DigitalInOut(pin) # defaults to inputtmp_pin.pull=Pull.UP# turn on internal pull-up resistorbuttons.append( Debouncer(tmp_pin) )
whileTrue:
foriinrange(len(buttons)):
buttons[i].update()
ifbuttons[i].fell:
print("button",i,"pressed!")
ifbuttons[i].rose:
print("button",i,"released!")

And you can use adafruit_debouncer on touch pins too:

importboard, touchio, adafruit_debouncertouchpad=adafruit_debouncer.Debouncer(touchio.TouchIn(board.GP1))
whileTrue:
touchpad.update()
iftouchpad.rose: print("touched!")
iftouchpad.fell: print("released!")

Outputs

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

importboardimportdigitalioledpin=digitalio.DigitalInOut(board.D2)
ledpin.direction=digitalio.Direction.OUTPUTledpin.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

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

Output a "Analog" value on a PWM pin

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

Control Neopixel / WS2812 LEDs

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

Control a servo, with animation list

# servo_animation_code.py -- show simple servo animation listimporttime, random, boardfrompwmioimportPWMOutfromadafruit_motorimportservo# your servo will likely have different min_pulse & max_pulse settingsservoA=servo.Servo(PWMOut(board.RX, frequency=50), min_pulse=500, max_pulse=2250)
# the animation to playanimation= (
# (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 animationwhileTrue:
angle, secs=animation[ ani_pos ]
print("servo moving to", angle, secs)
servoA.angle=angletime.sleep( secs )
ani_pos= (ani_pos+1) %len(animation) # go to next, loop if at end

Neopixels / Dotstars

Light each LED in order

You can access each LED with Python array methods on the leds object. And you can set the LED color with either an RGB tuple ((255,0,80)) or an RGB hex color as a 24-bit number (0xff0050)

importtime, board, neopixelled_pin=board.GP5# which pin the LED strip is onnum_leds=10colors= ( (255,0,0), (0,255,0), (0,0,255), 0xffffff, 0x000000 )
leds=neopixel.NeoPixel(led_pin, num_leds, brightness=0.1)
i=0whileTrue:
print("led:",i)
forcincolors:
leds[i] =ctime.sleep(0.2)
i= (i+1) %num_leds

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 moduleimporttime, board, neopixeltry:
fromrainbowioimportcolorwheelexcept:
defcolorwheel(pos):
ifpos<0orpos>255: return (0, 0, 0)
ifpos<85: return (255-pos*3, pos*3, 0)
ifpos<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)
whileTrue:
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.

importtime, board, neopixel, rainbowionum_leds=16leds=neopixel.NeoPixel(board.D2, num_leds, brightness=0.4, auto_write=False )
delta_hue=256//num_ledsspeed=10# higher numbers = faster rainbow spinningi=0whileTrue:
forlinrange(len(leds)):
leds[l] =rainbowio.colorwheel( int(i*speed+l*delta_hue) %255 )
leds.show() # only write to LEDs after updating them alli= (i+1) %255time.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.

importsupervisor, board, neopixel, rainbowionum_leds=16speed=10# lower is faster, higher is slowerleds=neopixel.NeoPixel(board.D2, 16, brightness=0.4)
whileTrue:
t=supervisor.ticks_ms() /speedleds[:] = [rainbowio.colorwheel( t+i*(255/len(leds)) ) foriinrange(len(leds))]

Fade all LEDs by amount for chase effects

importtimeimportboard, neopixelnum_leds=16leds=neopixel.NeoPixel(board.D2, num_leds, brightness=0.4, auto_write=False )
my_color= (55,200,230)
dim_by=20# dim amount, higher = shorter tailspos=0whileTrue:
leds[pos] =my_colorleds[:] = [[max(i-dim_by,0) foriinl] forlinleds] # dim all by (dim_by,dim_by,dim_by)pos= (pos+1) %num_leds# move to next positionleds.show() # only write to LEDs after updating them alltime.sleep(0.05)

Audio

If you're used to Arduino, making sound was mostly constrained to simple beeps using the Arduino tone() function. You can do that in CircuitPython too with pwmio and simpleio, but CircuitPython can also play WAV and MP3 files and become a fully-fledged audio synthesizer with synthio.

In CircuitPython, there are multiple core module libraries available to output audio:

pwmio -- use almost any GPIO pin to output simple beeps, no WAV/MP3/synthio
audioio -- uses built-in DAC to output WAV, MP3, synthio
audiopwmio -- like above, but uses PWM like arduino analogWrite(), requires RC filter to convert to analog
audiobusio -- outputs high-quality I2S audio data stream, requires external I2S decoder hardware

Different devices will have different audio modules available. Generally, the pattern is:

SAMD51 (e.g. "M4" boards) -- audioio (DAC) and audiobusio (I2S)
RP2040 (e.g. Pico) -- audiopwmio (PWM) and audiobusio (I2S)
ESP32 (e.g. QTPy ESP32) -- audiobusio (I2S) only

To play WAV and MP3 files, they usually must be resaved in a format parsable by CircuitPython, see Preparing Audio Files for CircuitPython

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()importtime, board, simpleiowhileTrue:
forfin (262, 294, 330, 349, 392, 440, 494, 523):
simpleio.tone(board.A0, f, 0.25)
time.sleep(1)

Play a WAV file

WAV files are easiest for CircuitPython to play. The shortest code to play a WAV file on Pico RP2040 is:

importtime, board, audiocore, audiopwmioaudio=audiopwmio.PWMAudioOut(board.GP0)
wave=audiocore.WaveFile("laser2.wav")
audio.play(wave)
whileTrue:
pass# wait for audio to finish playing

Details and other ways below.

Audio out using PWM

This uses the audiopwmio library, only available for RP2040 boards like Raspberry Pi Pico 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.

importtime, boardfromaudiocoreimportWaveFilefromaudiopwmioimportPWMAudioOutasAudioOutwave=WaveFile("laser2.wav") # can also be filehandle from open()audio=AudioOut(board.GP0) # must be PWM-capable pinwhileTrue:
print("audio is playing:",audio.playing)
ifnotaudio.playing:
audio.play(wave)
wave.sample_rate=int(wave.sample_rate*0.90) # play 10% slower each timetime.sleep(0.1)

Notes:

There will be a small pop when audio starts playing as the PWM driver takes the GPIO line from not being driven to being PWM'ed. There's currently no way around this. If playing multiple WAVs, consider using AudioMixer to keep the audio system running between WAVs. This way, you'll only have the startup pop.
If you want stereo output on boards that support it then you can pass in two pins, like: audio = audiopwmio.PWMAudioOut(left_channel=board.GP14, right_channel=board.GP15)
PWM output must be filtered and converted to line-level to be usable. Use an RC circuit to accomplish this, see this simple circuit or this twitter thread for details.
The WaveFile() object can take either a filestream (the output of open('filewav','rb')) or can take a string filename (wav=WaveFile("laser2.wav")).

Audio out using DAC

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

importtime, boardimportaudiocore, audioio# DACwave_file=open("laser2.wav", "rb")
wave=audiocore.WaveFile(wave_file)
audio=audioio.AudioOut(board.A0) # must be DAC-capable pin, A0 on QTPy HaxpresswhileTrue:
print("audio is playing:",audio.playing)
ifnotaudio.playing:
audio.play(wave)
wave.sample_rate=int(wave.sample_rate*0.90) # play 10% slower each timetime.sleep(0.1)

Note: if you want stereo output on boards that support it (SAMD51 "M4" mostly), then you can pass in two pins, like: audio = audioio.AudioOut(left_channel=board.A0, right_channel=board.A1)

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 adjacentimportboard, audiobusio, audiocoreaudio=audiobusio.I2SOut(bit_clock=board.GP0, word_select=board.GP1, data=board.GP2)
audio.play( audiocore.WaveFile("laser2.wav") )

Use audiomixer to prevent audio crackles

The default buffer used by the audio system is quite small. This means you'll hear corrupted audio if CircuitPython is doing anything else (having CIRCUITPY written to, updating a display). To get around this, you can use audiomixer to make the audio buffer larger. Try buffer_size=2048 to start. A larger buffer means a longer lag between when a sound is triggered when its heard.

AudioMixer is also great if you want to play multiple WAV files at the same time.

importtime, boardfromaudiocoreimportWaveFilefromaudioioimportAudioOutimportaudiomixerwave=WaveFile("laser2.wav", "rb")
audio=AudioOut(board.A0) # assuming QTPy M0 or Itsy M4mixer=audiomixer.Mixer(voice_count=1, sample_rate=22050, channel_count=1,
bits_per_sample=16, samples_signed=True, buffer_size=2048)
audio.play(mixer) # never touch "audio" after this, use "mixer"whileTrue:
print("mixer voice is playing:", mixer.voice[0].playing)
ifnotmixer.voice[0].playing:
time.sleep(1)
print("playing again")
mixer.voice[0].play(wave)
time.sleep(0.1)

Play multiple sounds with audiomixer

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

importtime, board, audiocore, audiomixerfromaudiopwmioimportPWMAudioOutasAudioOutwav_files= ("loop1.wav", "loop2.wav", "loop3.wav")
wavs= [None] *len(wav_files) # holds the loaded WAVsaudio=AudioOut(board.GP2) # RP2040 examplemixer=audiomixer.Mixer(voice_count=len(wav_files), sample_rate=22050, channel_count=1,
bits_per_sample=16, samples_signed=True, buffer_size=2048)
audio.play(mixer) # attach mixer to audio playbackforiinrange(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 playingwhileTrue:
print("doing something else while all loops play")
time.sleep(1)

Note: M0 boards do not have audiomixer

Note: Number of simultaneous sounds is limited sample rate and flash read speed. Rules of thumb:

Built-in flash: 10 22kHz sounds simultanously
SPI SD cards: 2 22kHz sounds simultaneously

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:

importboard, audiobusio, audiocore, audiomp3num_voices=2i2s_bclk, i2s_wsel, i2s_data=board.GP9, board.GP10, board.GP11# BCLK, LCLK, DIN on PCM5102audio=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 playbackwav_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 )
whileTrue:
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.

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"importstoragestorage.remount("/", readonly=False)
m=storage.getmount("/")
m.label=new_namestorage.remount("/", readonly=True)

Detect if USB is connected or not

importsupervisorifsupervisor.runtime.usb_connected:
led.value=True# USBelse:
led.value=False# no USB

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

defis_usb_connected():
importstoragetry:
storage.remount('/', readonly=False) # attempt to mount readwritestorage.remount('/', readonly=True) # attempt to mount readonlyexceptRuntimeErrorase:
returnTruereturnFalseis_usb="USB"ifis_usb_connected() else"NO USB"print("USB:", is_usb)

Get CIRCUITPY disk size and free space

importosfs_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

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

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

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

USB Serial

Print to USB Serial

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

Read user input from USB Serial, blocking

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

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

importtimeimportsupervisorprint("Type something when you're ready")
last_time=time.monotonic()
whileTrue:
ifsupervisor.runtime.serial_bytes_available:
my_str=input()
print("You entered:", my_str)
iftime.monotonic() -last_time>1: # every second, printlast_time=time.monotonic()
print(int(last_time),"waiting...")

Read keys from USB Serial

importtime, sys, supervisorprint("type charactcers")
whileTrue:
n=supervisor.runtime.serial_bytes_availableifn>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)) forcins))
time.sleep(0.01) # do something else

Read user input from USB serial, non-blocking

classUSBSerialReader:
""" Read a line from USB Serial (up to end_char), non-blocking, with optional echo """def__init__(self):
self.s=''defread(self,end_char='\n', echo=True):
importsys, supervisorn=supervisor.runtime.serial_bytes_availableifn>0: # we got bytes!s=sys.stdin.read(n) # actually read it inifecho: sys.stdout.write(s) # echo back to humanself.s=self.s+s# keep building the string upifs.endswith(end_char): # got our end_char!rstr=self.s# save for returnself.s=''# reset str to beginningreturnrstrreturnNone# no end_char yetusb_reader=USBSerialReader()
print("type something and press the end_char")
whileTrue:
mystr=usb_reader.read() # read until newline, echo back chars#mystr = usb_reader.read(end_char='\t', echo=False) # trigger on tab, no echoifmystr:
print("got:",mystr)
time.sleep(0.01) # do something time critical

USB Keyboard & Mouse

CircuitPython comes set up to be a USB keyboard and mouse. Many more details in CircuitPython Essentials but the basics are below. The adafruit_hid library needs to be installed from the the bundle. I do circup install adafruit_hid in a terminal.

Sending keystrokes and mouse moves

importtimeimportusb_hidfromadafruit_hid.keyboardimportKeyboardfromadafruit_hid.keycodeimportKeycodefromadafruit_hid.mouseimportMousekbd=Keyboard(usb_hid.devices)
mouse=Mouse(usb_hid.devices)
whileTrue:
time.sleep(1)
print("moving right")
kbd.send(Keycode.A) # types "a" (sends press() & release_all())mouse.move(x=50, y=0) # moves mouse slightly righttime.sleep(1)
print("moving left")
kbd.send(Keycode.B) # types "b" (sends press() & release_all())mouse.move(x=-50, y=0) # moves mouse slightly lefttime.sleep(1)

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.

For outputting MIDI, you can opt to deal with raw bytearrays, since most MIDI messages are just 1,2, or 3 bytes long. For reading MIDI, you may find TMIDI or SmolMIDI to be faster to parse MIDI messages, since by design it does less.

Sending MIDI with adafruit_midi

importusb_midiimportadafruit_midifromadafruit_midi.note_onimportNoteOnfromadafruit_midi.note_offimportNoteOffmidi_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)
defplay_note(note,velocity=127):
midi.send(NoteOn(note, velocity)) # 127 = highest velocitytime.sleep(0.1)
midi.send(NoteOff(note, 0)) # 0 = lowest velocity

Note: This pattern works for sending serial (5-pin) MIDI too, see below

Sending MIDI with bytearray

Sending MIDI with a lower-level bytearray is also pretty easy and could gain some speed for timing-sensitive applications. This code is equivalent to the above, without adafruit_midi

importusb_midimidi_out=usb_midi.ports[1]
midi_out_channel=3# MIDI out channel (1-16)note_on_status= (0x90| (midi_out_channel-1))
note_off_status= (0x80| (midi_out_channel-1))
defplay_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 (aka "5-pin MIDI") too. With a simple MIDI out circuit you can control old hardware synths.

importbusiomidi_out_channel=3# MIDI out channel (1-16)note_on_status= (0x90| (midi_out_channel-1))
note_off_status= (0x80| (midi_out_channel-1))
# must pick board pins that are UART TX and RX pinsmidi_uart=busio.UART(tx=board.GP16, rx=board.GP17, baudrate=31250)
defplay_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]) )

Receiving MIDI

importusb_midi# built-in libraryimportadafruit_midi# install with 'circup install adafruit_midi'fromadafruit_midi.note_onimportNoteOnfromadafruit_midi.note_offimportNoteOffmidi_usb=adafruit_midi.MIDI(midi_in=usb_midi.ports[0])
whileTrue:
msg=midi_usb.receive()
ifmsg:
ifisinstance(msg, NoteOn):
print("usb noteOn:",msg.note, msg.velocity)
elifisinstance(msg, NoteOff):
print("usb noteOff:",msg.note, msg.velocity)

Note with adafruit_midi you must import each kind of MIDI Message you want to handle.

Receiving 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.

importboard, busioimportusb_midi# built-in libraryimportadafruit_midi# install with 'circup install adafruit_midi'fromadafruit_midi.note_onimportNoteOnfromadafruit_midi.note_offimportNoteOffuart=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 )
whileTrue:
msg=midi_usb.receive()
ifmsg:
ifisinstance(msg, NoteOn):
print("usb noteOn:",msg.note, msg.velocity)
elifisinstance(msg, NoteOff):
print("usb noteOff:",msg.note, msg.velocity)
msg=midi_serial.receive()
ifmsg:
ifisinstance(msg, NoteOn):
print("serial noteOn:",msg.note, msg.velocity)
elifisinstance(msg, NoteOff):
print("serial noteOff:",msg.note, msg.velocity)

If you don't care about the source of the MIDI messages, you can combine the two if blocks using the "walrus operator" (:=)

whileTrue:
whilemsg:=midi_usb.receive() ormidi_uart.receive():
ifisinstance(msg, NoteOn) andmsg.velocity!=0:
note_on(msg.note, msg.velocity)
elifisinstance(msg,NoteOff) orisinstance(msg,NoteOn) andmsg.velocity==0:
note_off(msg.note, msg.velocity)

Enable USB MIDI in boot.py (for ESP32-S2 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 board power cycled.

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