项目作者: todbot

项目描述 :
Some CircuitPython tricks, mostly reminders to myself
高级语言:
项目地址: git://github.com/todbot/circuitpython-tricks.git
创建时间: 2021-02-27T00:20:51Z
项目社区:https://github.com/todbot/circuitpython-tricks

开源协议:

下载


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:

Table of Contents

But it’s probably easiest to do a Cmd-F/Ctrl-F find on keyword of idea you want.

Inputs

Read a digital input as a Button

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

Can also do:

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

Read a Potentiometer

  1. import board
  2. import analogio
  3. potknob = analogio.AnalogIn(board.A1)
  4. position = potknob.value # ranges from 0-65535
  5. 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

  1. import touchio
  2. import board
  3. touch_pin = touchio.TouchIn(board.GP6)
  4. # on Pico / RP2040, need 1M pull-down on each input
  5. if touch_pin.value:
  6. 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

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

Debounce a pin / button

  1. import board
  2. from digitalio import DigitalInOut, Pull
  3. from adafruit_debouncer import Debouncer
  4. button_in = DigitalInOut(board.D3) # defaults to input
  5. button_in.pull = Pull.UP # turn on internal pull-up resistor
  6. button = Debouncer(button_in)
  7. while True:
  8. button.update()
  9. if button.fell:
  10. print("press!")
  11. if button.rose:
  12. 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

  1. import board
  2. from digitalio import DigitalInOut, Pull
  3. from adafruit_debouncer import Button
  4. button_in = DigitalInOut(board.D3) # defaults to input
  5. button_in.switch_to_input(Pull.UP) # turn on internal pull-up resistor
  6. button = Button(button_in)
  7. while True:
  8. button.update()
  9. if button.pressed:
  10. print("press!")
  11. if button.released:
  12. print("release!")
  13. if button.short_count > 1: # detect multi-click
  14. print("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.

  1. import board
  2. import keypad
  3. button_pins = (board.GP0, board.GP1, board.GP2, board.GP3, board.GP4)
  4. buttons = keypad.Keys(button_pins, value_when_pressed=False, pull=True)
  5. while True:
  6. button = buttons.events.get() # see if there are any key events
  7. if button: # there are events!
  8. if button.pressed:
  9. print("button", button.key_number, "pressed!")
  10. if button.released:
  11. print("button", button.key_number, "released!")

Otherwise, you can use adafruit_debouncer:

  1. import board
  2. from digitalio import DigitalInOut, Pull
  3. from adafruit_debouncer import Debouncer
  4. button_pins = (board.GP0, board.GP1, board.GP2, board.GP3, board.GP4)
  5. buttons = [] # will hold list of Debouncer objects
  6. for pin in button_pins: # set up each pin
  7. tmp_pin = DigitalInOut(pin) # defaults to input
  8. tmp_pin.pull = Pull.UP # turn on internal pull-up resistor
  9. buttons.append( Debouncer(tmp_pin) )
  10. while True:
  11. for i in range(len(buttons)):
  12. buttons[i].update()
  13. if buttons[i].fell:
  14. print("button",i,"pressed!")
  15. if buttons[i].rose:
  16. print("button",i,"released!")

And you can use adafruit_debouncer on touch pins too:

  1. import board, touchio, adafruit_debouncer
  2. touchpad = adafruit_debouncer.Debouncer(touchio.TouchIn(board.GP1))
  3. while True:
  4. touchpad.update()
  5. if touchpad.rose: print("touched!")
  6. if touchpad.fell: print("released!")

Outputs

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

  1. import board
  2. import digitalio
  3. ledpin = digitalio.DigitalInOut(board.D2)
  4. ledpin.direction = digitalio.Direction.OUTPUT
  5. ledpin.value = True

Can also do:

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

Output Analog value on a DAC pin

Different boards have DAC on different pins

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

Output a “Analog” value on a PWM pin

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

Control Neopixel / WS2812 LEDs

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

Control a servo, with animation list

  1. # servo_animation_code.py -- show simple servo animation list
  2. import time, random, board
  3. from pwmio import PWMOut
  4. from adafruit_motor import servo
  5. # your servo will likely have different min_pulse & max_pulse settings
  6. servoA = servo.Servo(PWMOut(board.RX, frequency=50), min_pulse=500, max_pulse=2250)
  7. # the animation to play
  8. animation = (
  9. # (angle, time to stay at that angle)
  10. (0, 2.0),
  11. (90, 2.0),
  12. (120, 2.0),
  13. (180, 2.0)
  14. )
  15. ani_pos = 0 # where in list to start our animation
  16. while True:
  17. angle, secs = animation[ ani_pos ]
  18. print("servo moving to", angle, secs)
  19. servoA.angle = angle
  20. time.sleep( secs )
  21. 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)

  1. import time, board, neopixel
  2. led_pin = board.GP5 # which pin the LED strip is on
  3. num_leds = 10
  4. colors = ( (255,0,0), (0,255,0), (0,0,255), 0xffffff, 0x000000 )
  5. leds = neopixel.NeoPixel(led_pin, num_leds, brightness=0.1)
  6. i = 0
  7. while True:
  8. print("led:",i)
  9. for c in colors:
  10. leds[i] = c
  11. time.sleep(0.2)
  12. 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.

  1. # CircuitPython 7 with or without rainbowio module
  2. import time, board, neopixel
  3. try:
  4. from rainbowio import colorwheel
  5. except:
  6. def colorwheel(pos):
  7. if pos < 0 or pos > 255: return (0, 0, 0)
  8. if pos < 85: return (255 - pos * 3, pos * 3, 0)
  9. if pos < 170: pos -= 85; return (0, 255 - pos * 3, pos * 3)
  10. pos -= 170; return (pos * 3, 0, 255 - pos * 3)
  11. led = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.4)
  12. while True:
  13. led.fill( colorwheel((time.monotonic()*50)%255) )
  14. time.sleep(0.05)

Make moving rainbow gradient across LED strip

See demo of it in this tweet.

  1. import time, board, neopixel, rainbowio
  2. num_leds = 16
  3. leds = neopixel.NeoPixel(board.D2, num_leds, brightness=0.4, auto_write=False )
  4. delta_hue = 256//num_leds
  5. speed = 10 # higher numbers = faster rainbow spinning
  6. i=0
  7. while True:
  8. for l in range(len(leds)):
  9. leds[l] = rainbowio.colorwheel( int(i*speed + l * delta_hue) % 255 )
  10. leds.show() # only write to LEDs after updating them all
  11. i = (i+1) % 255
  12. 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.

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

Fade all LEDs by amount for chase effects

  1. import time
  2. import board, neopixel
  3. num_leds = 16
  4. leds = neopixel.NeoPixel(board.D2, num_leds, brightness=0.4, auto_write=False )
  5. my_color = (55,200,230)
  6. dim_by = 20 # dim amount, higher = shorter tails
  7. pos = 0
  8. while True:
  9. leds[pos] = my_color
  10. leds[:] = [[max(i-dim_by,0) for i in l] for l in leds] # dim all by (dim_by,dim_by,dim_by)
  11. pos = (pos+1) % num_leds # move to next position
  12. leds.show() # only write to LEDs after updating them all
  13. time.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:

  1. # a short piezo song using tone()
  2. import time, board, simpleio
  3. while True:
  4. for f in (262, 294, 330, 349, 392, 440, 494, 523):
  5. simpleio.tone(board.A0, f, 0.25)
  6. 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:

  1. import time, board, audiocore, audiopwmio
  2. audio = audiopwmio.PWMAudioOut(board.GP0)
  3. wave = audiocore.WaveFile("laser2.wav")
  4. audio.play(wave)
  5. while True:
  6. 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.

  1. import time, board
  2. from audiocore import WaveFile
  3. from audiopwmio import PWMAudioOut as AudioOut
  4. wave = WaveFile("laser2.wav") # can also be filehandle from open()
  5. audio = AudioOut(board.GP0) # must be PWM-capable pin
  6. while True:
  7. print("audio is playing:",audio.playing)
  8. if not audio.playing:
  9. audio.play(wave)
  10. wave.sample_rate = int(wave.sample_rate * 0.90) # play 10% slower each time
  11. time.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.

  1. import time, board
  2. import audiocore, audioio # DAC
  3. wave_file = open("laser2.wav", "rb")
  4. wave = audiocore.WaveFile(wave_file)
  5. audio = audioio.AudioOut(board.A0) # must be DAC-capable pin, A0 on QTPy Haxpress
  6. while True:
  7. print("audio is playing:",audio.playing)
  8. if not audio.playing:
  9. audio.play(wave)
  10. wave.sample_rate = int(wave.sample_rate * 0.90) # play 10% slower each time
  11. time.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.

  1. # for e.g. Pico RP2040 pins bit_clock & word_select pins must be adjacent
  2. import board, audiobusio, audiocore
  3. audio = audiobusio.I2SOut(bit_clock=board.GP0, word_select=board.GP1, data=board.GP2)
  4. 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.

  1. import time, board
  2. from audiocore import WaveFile
  3. from audioio import AudioOut
  4. import audiomixer
  5. wave = WaveFile("laser2.wav", "rb")
  6. audio = AudioOut(board.A0) # assuming QTPy M0 or Itsy M4
  7. mixer = audiomixer.Mixer(voice_count=1, sample_rate=22050, channel_count=1,
  8. bits_per_sample=16, samples_signed=True, buffer_size=2048)
  9. audio.play(mixer) # never touch "audio" after this, use "mixer"
  10. while True:
  11. print("mixer voice is playing:", mixer.voice[0].playing)
  12. if not mixer.voice[0].playing:
  13. time.sleep(1)
  14. print("playing again")
  15. mixer.voice[0].play(wave)
  16. 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.

  1. import time, board, audiocore, audiomixer
  2. from audiopwmio import PWMAudioOut as AudioOut
  3. wav_files = ("loop1.wav", "loop2.wav", "loop3.wav")
  4. wavs = [None] * len(wav_files) # holds the loaded WAVs
  5. audio = AudioOut(board.GP2) # RP2040 example
  6. mixer = audiomixer.Mixer(voice_count=len(wav_files), sample_rate=22050, channel_count=1,
  7. bits_per_sample=16, samples_signed=True, buffer_size=2048)
  8. audio.play(mixer) # attach mixer to audio playback
  9. for i in range(len(wav_files)):
  10. print("i:",i)
  11. wavs[i] = audiocore.WaveFile(open(wav_files[i], "rb"))
  12. mixer.voice[i].play( wavs[i], loop=True) # start each one playing
  13. while True:
  14. print("doing something else while all loops play")
  15. 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:

  1. import board, audiobusio, audiocore, audiomp3
  2. num_voices = 2
  3. i2s_bclk, i2s_wsel, i2s_data = board.GP9, board.GP10, board.GP11 # BCLK, LCLK, DIN on PCM5102
  4. audio = audiobusio.I2SOut(bit_clock=i2s_bclk, word_select=i2s_wsel, data=i2s_data)
  5. mixer = audiomixer.Mixer(voice_count=num_voices, sample_rate=22050, channel_count=1,
  6. bits_per_sample=16, samples_signed=True)
  7. audio.play(mixer) # attach mixer to audio playback
  8. wav_file = "/amen1_22k_s16.wav" # in 'circuitpython-tricks/larger-tricks/breakbeat_wavs'
  9. mp3_file = "/vocalchops476663_22k_128k.mp3" # in 'circuitpython-tricks/larger-tricks/wav'
  10. # https://freesound.org/people/f-r-a-g-i-l-e/sounds/476663/
  11. wave = audiocore.WaveFile(open(wav_file, "rb"))
  12. mp3 = audiomp3.MP3Decoder(open(mp3_file, "rb"))
  13. mixer.voice[0].play( wave )
  14. mixer.voice[1].play( mp3 )
  15. while True:
  16. 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.

  1. # this goes in boot.py not code.py!
  2. new_name = "TRINKEYPY0"
  3. import storage
  4. storage.remount("/", readonly=False)
  5. m = storage.getmount("/")
  6. m.label = new_name
  7. storage.remount("/", readonly=True)

Detect if USB is connected or not

  1. import supervisor
  2. if supervisor.runtime.usb_connected:
  3. led.value = True # USB
  4. else:
  5. led.value = False # no USB

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

  1. def is_usb_connected():
  2. import storage
  3. try:
  4. storage.remount('/', readonly=False) # attempt to mount readwrite
  5. storage.remount('/', readonly=True) # attempt to mount readonly
  6. except RuntimeError as e:
  7. return True
  8. return False
  9. is_usb = "USB" if is_usb_connected() else "NO USB"
  10. print("USB:", is_usb)

Get CIRCUITPY disk size and free space

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

Programmatically reset to UF2 bootloader

  1. import microcontroller
  2. microcontroller.on_next_reset(microcontroller.RunMode.UF2)
  3. microcontroller.reset()

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

  1. import microcontroller
  2. microcontroller.on_next_reset(microcontroller.RunMode.BOOTLOADER)
  3. microcontroller.reset()

USB Serial

Print to USB Serial

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

Read user input from USB Serial, blocking

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

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

  1. import time
  2. import supervisor
  3. print("Type something when you're ready")
  4. last_time = time.monotonic()
  5. while True:
  6. if supervisor.runtime.serial_bytes_available:
  7. my_str = input()
  8. print("You entered:", my_str)
  9. if time.monotonic() - last_time > 1: # every second, print
  10. last_time = time.monotonic()
  11. print(int(last_time),"waiting...")

Read keys from USB Serial

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

Read user input from USB serial, non-blocking

  1. class USBSerialReader:
  2. """ Read a line from USB Serial (up to end_char), non-blocking, with optional echo """
  3. def __init__(self):
  4. self.s = ''
  5. def read(self,end_char='\n', echo=True):
  6. import sys, supervisor
  7. n = supervisor.runtime.serial_bytes_available
  8. if n > 0: # we got bytes!
  9. s = sys.stdin.read(n) # actually read it in
  10. if echo: sys.stdout.write(s) # echo back to human
  11. self.s = self.s + s # keep building the string up
  12. if s.endswith(end_char): # got our end_char!
  13. rstr = self.s # save for return
  14. self.s = '' # reset str to beginning
  15. return rstr
  16. return None # no end_char yet
  17. usb_reader = USBSerialReader()
  18. print("type something and press the end_char")
  19. while True:
  20. mystr = usb_reader.read() # read until newline, echo back chars
  21. #mystr = usb_reader.read(end_char='\t', echo=False) # trigger on tab, no echo
  22. if mystr:
  23. print("got:",mystr)
  24. 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.

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 Winterbloom’s SmolMIDI to be faster
to parse MIDI messages, since by design it does less.

Sending MIDI with adafruit_midi

  1. import usb_midi
  2. import adafruit_midi
  3. from adafruit_midi.note_on import NoteOn
  4. from adafruit_midi.note_off import NoteOff
  5. midi_out_channel = 3 # human version of MIDI out channel (1-16)
  6. midi = adafruit_midi.MIDI( midi_out=usb_midi.ports[1], out_channel=midi_out_channel-1)
  7. def play_note(note,velocity=127):
  8. midi.send(NoteOn(note, velocity)) # 127 = highest velocity
  9. time.sleep(0.1)
  10. 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

  1. import usb_midi
  2. midi_out = usb_midi.ports[1]
  3. midi_out_channel = 3 # MIDI out channel (1-16)
  4. note_on_status = (0x90 | (midi_out_channel-1))
  5. note_off_status = (0x80 | (midi_out_channel-1))
  6. def play_note(note,velocity=127):
  7. midi_out.write( bytearray([note_on_status, note, velocity]) )
  8. time.sleep(0.1)
  9. 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.

  1. import busio
  2. midi_out_channel = 3 # MIDI out channel (1-16)
  3. note_on_status = (0x90 | (midi_out_channel-1))
  4. note_off_status = (0x80 | (midi_out_channel-1))
  5. # must pick board pins that are UART TX and RX pins
  6. midi_uart = busio.UART(tx=board.GP16, rx=board.GP17, baudrate=31250)
  7. def play_note(note,velocity=127):
  8. midi_uart.write( bytearray([note_on_status, note, velocity]) )
  9. time.sleep(0.1)
  10. midi_uart.write( bytearray([note_off_status, note, 0]) )

Receiving MIDI

  1. import usb_midi # built-in library
  2. import adafruit_midi # install with 'circup install adafruit_midi'
  3. from adafruit_midi.note_on import NoteOn
  4. from adafruit_midi.note_off import NoteOff
  5. midi_usb = adafruit_midi.MIDI(midi_in=usb_midi.ports[0])
  6. while True:
  7. msg = midi_usb.receive()
  8. if msg:
  9. if isinstance(msg, NoteOn):
  10. print("usb noteOn:",msg.note, msg.velocity)
  11. elif isinstance(msg, NoteOff):
  12. 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.

  1. import board, busio
  2. import usb_midi # built-in library
  3. import adafruit_midi # install with 'circup install adafruit_midi'
  4. from adafruit_midi.note_on import NoteOn
  5. from adafruit_midi.note_off import NoteOff
  6. uart = busio.UART(tx=board.TX, rx=board.RX, baudrate=31250, timeout=0.001)
  7. midi_usb = adafruit_midi.MIDI( midi_in=usb_midi.ports[0], midi_out=usb_midi.ports[1] )
  8. midi_serial = adafruit_midi.MIDI( midi_in=uart, midi_out=uart )
  9. while True:
  10. msg = midi_usb.receive()
  11. if msg:
  12. if isinstance(msg, NoteOn):
  13. print("usb noteOn:",msg.note, msg.velocity)
  14. elif isinstance(msg, NoteOff):
  15. print("usb noteOff:",msg.note, msg.velocity)
  16. msg = midi_serial.receive()
  17. if msg:
  18. if isinstance(msg, NoteOn):
  19. print("serial noteOn:",msg.note, msg.velocity)
  20. elif isinstance(msg, NoteOff):
  21. 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” (:=)

  1. while True:
  2. while msg := midi_usb.receive() or midi_uart.receive():
  3. if isinstance(msg, NoteOn) and msg.velocity != 0:
  4. note_on(msg.note, msg.velocity)
  5. elif isinstance(msg,NoteOff) or isinstance(msg,NoteOn) and msg.velocity==0:
  6. 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.

  1. # boot.py
  2. import usb_hid
  3. import usb_midi
  4. usb_hid.disable()
  5. usb_midi.enable()
  6. print("enabled USB MIDI, disabled USB HID")

WiFi / Networking

Scan for WiFi Networks, sorted by signal strength

Note: this is for boards with native WiFi (ESP32)

  1. import wifi
  2. networks = []
  3. for network in wifi.radio.start_scanning_networks():
  4. networks.append(network)
  5. wifi.radio.stop_scanning_networks()
  6. networks = sorted(networks, key=lambda net: net.rssi, reverse=True)
  7. for network in networks:
  8. print("ssid:",network.ssid, "rssi:",network.rssi)

Join WiFi network with highest signal strength

  1. import wifi
  2. def join_best_network(good_networks, print_info=False):
  3. """join best network based on signal strength of scanned nets"""
  4. networks = []
  5. for network in wifi.radio.start_scanning_networks():
  6. networks.append(network)
  7. wifi.radio.stop_scanning_networks()
  8. networks = sorted(networks, key=lambda net: net.rssi, reverse=True)
  9. for network in networks:
  10. if print_info: print("network:",network.ssid)
  11. if network.ssid in good_networks:
  12. if print_info: print("connecting to WiFi:", network.ssid)
  13. try:
  14. wifi.radio.connect(network.ssid, good_networks[network.ssid])
  15. return True
  16. except ConnectionError as e:
  17. if print_info: print("connect error:",e)
  18. return False
  19. good_networks = {"todbot1":"FiOnTheFly", # ssid, password
  20. "todbot2":"WhyFlyWiFi",}
  21. connected = join_best_network(good_networks, print_info=True)
  22. if connected:
  23. print("connected!")

Ping an IP address

Note: this is for boards with native WiFi (ESP32)

  1. import os
  2. import time
  3. import wifi
  4. import ipaddress
  5. ip_to_ping = "1.1.1.1"
  6. wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
  7. password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
  8. print("my IP addr:", wifi.radio.ipv4_address)
  9. print("pinging ",ip_to_ping)
  10. ip1 = ipaddress.ip_address(ip_to_ping)
  11. while True:
  12. print("ping:", wifi.radio.ping(ip1))
  13. time.sleep(1)

Get IP address of remote host

  1. import os, wifi, socketpool
  2. wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
  3. password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
  4. print("my IP addr:", wifi.radio.ipv4_address)
  5. hostname = "todbot.com"
  6. pool = socketpool.SocketPool(wifi.radio)
  7. addrinfo = pool.getaddrinfo(host=hostname, port=443) # port is required
  8. print("addrinfo", addrinfo)
  9. ipaddr = addrinfo[0][4][0]
  10. print(f"'{hostname}' ip address is '{ipaddr}'")

Fetch a JSON file

Note: this is for boards with native WiFi (ESP32)

  1. import os
  2. import time
  3. import wifi
  4. import socketpool
  5. import ssl
  6. import adafruit_requests
  7. wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
  8. password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
  9. print("my IP addr:", wifi.radio.ipv4_address)
  10. pool = socketpool.SocketPool(wifi.radio)
  11. session = adafruit_requests.Session(pool, ssl.create_default_context())
  12. while True:
  13. response = session.get("https://todbot.com/tst/randcolor.php")
  14. data = response.json()
  15. print("data:",data)
  16. time.sleep(5)

Serve a webpage via HTTP

Note: this is for boards with native WiFi (ESP32)

The adafruit_httpserver library
makes this pretty easy, and has good examples. You can tell it to either server.serve_forver()
and do all your computation in your @server.route() functions, or use server.poll() inside a while-loop.
There is also the Ampule library.

  1. import time, os, wifi, socketpool
  2. from adafruit_httpserver.server import HTTPServer
  3. from adafruit_httpserver.response import HTTPResponse
  4. my_port = 1234 # set this to your liking
  5. wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
  6. password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
  7. server = HTTPServer(socketpool.SocketPool(wifi.radio))
  8. @server.route("/") # magic that attaches this function to "server" object
  9. def base(request):
  10. my_str = f"<html><body><h1> Hello! Current time.monotonic is {time.monotonic()}</h1></body></html>"
  11. return HTTPResponse(body=my_str, content_type="text/html")
  12. # or for static content: return HTTPResponse(filename="/index.html")
  13. print(f"Listening on http://{wifi.radio.ipv4_address}:{my_port}")
  14. server.serve_forever(str(wifi.radio.ipv4_address), port=my_port) # never returns

Set RTC time from NTP

Note: this is for boards with native WiFi (ESP32)

Note: You need to set my_tz_offset to match your region

  1. # copied from:
  2. # https://docs.circuitpython.org/projects/ntp/en/latest/examples.html
  3. import time, os, rtc
  4. import socketpool, wifi
  5. import adafruit_ntp
  6. my_tz_offset = -7 # PDT
  7. wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
  8. password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
  9. print("Connected, getting NTP time")
  10. pool = socketpool.SocketPool(wifi.radio)
  11. ntp = adafruit_ntp.NTP(pool, tz_offset=my_tz_offset)
  12. rtc.RTC().datetime = ntp.datetime
  13. while True:
  14. print("current datetime:", time.localtime())
  15. time.sleep(5)

Set RTC time from time service

Note: this is for boards with native WiFi (ESP32)

This uses the awesome and free WorldTimeAPI.org site,
and this example will fetch the current local time (including timezone and UTC offset)
based on the geolocated IP address of your device.

  1. import time, os, rtc
  2. import wifi, ssl, socketpool
  3. import adafruit_requests
  4. wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
  5. password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
  6. print("Connected, getting WorldTimeAPI time")
  7. pool = socketpool.SocketPool(wifi.radio)
  8. request = adafruit_requests.Session(pool, ssl.create_default_context())
  9. print("Getting current time:")
  10. response = request.get("http://worldtimeapi.org/api/ip")
  11. time_data = response.json()
  12. tz_hour_offset = int(time_data['utc_offset'][0:3])
  13. tz_min_offset = int(time_data['utc_offset'][4:6])
  14. if (tz_hour_offset < 0):
  15. tz_min_offset *= -1
  16. unixtime = int(time_data['unixtime'] + (tz_hour_offset * 60 * 60)) + (tz_min_offset * 60)
  17. print(time_data)
  18. print("URL time: ", response.headers['date'])
  19. rtc.RTC().datetime = time.localtime( unixtime ) # create time struct and set RTC with it
  20. while True:
  21. print("current datetime: ", time.localtime()) # time.* now reflects current local time
  22. time.sleep(5)

Also see this more concise version from @deilers78.

What the heck is settings.toml?

It’s a config file that lives next to your code.py and is used to store
WiFi credentials and other global settings. It is also used (invisibly)
by many Adafruit libraries that do WiFi.
You can use it (as in the examples above) without those libraries.
The settings names used by CircuitPython are documented in
CircuitPython Web Workflow.

Note: You can use any variable names for your WiFI credentials
(a common pair is WIFI_SSID and WIFI_PASSWORD), but if you use the
CIRCUITPY_WIFI_* names that will also start up the
Web Workflow

You use it like this for basic WiFi connectivity:

  1. # settings.toml
  2. CIRCUITPY_WIFI_SSID = "PrettyFlyForAWiFi"
  3. CIRCUITPY_WIFI_PASSWORD = "mysecretpassword"
  4. # code.py
  5. import os, wifi
  6. print("connecting...")
  7. wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
  8. password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
  9. print("my IP addr:", wifi.radio.ipv4_address)

What the heck is secrets.py?

It’s an older version of the settings.toml idea.
You may see older code that uses it.

Displays (LCD / OLED / E-Ink) and displayio

displayio
is the native system-level driver for displays in CircuitPython. Several CircuitPython boards
(FunHouse, MagTag, PyGamer, CLUE) have displayio-based displays and a
built-in board.DISPLAY object that is preconfigured for that display.
Or, you can add your own I2C or SPI display.

Get default display and change display rotation

Boards like FunHouse, MagTag, PyGamer, CLUE have built-in displays.
display.rotation works with all displays, not just built-in ones.

  1. import board
  2. display = board.DISPLAY
  3. print(display.rotation) # print current rotation
  4. display.rotation = 0 # valid values 0,90,180,270

Display an image

Using displayio.OnDiskBitmap

CircuitPython has a built-in BMP parser called displayio.OnDiskBitmap:
The images should be in non-compressed, paletized BMP3 format.
(how to make BMP3 images)

  1. import board, displayio
  2. display = board.DISPLAY
  3. maingroup = displayio.Group() # everything goes in maingroup
  4. display.root_group = maingroup # show our maingroup (clears the screen)
  5. bitmap = displayio.OnDiskBitmap(open("my_image.bmp", "rb"))
  6. image = displayio.TileGrid(bitmap, pixel_shader=bitmap.pixel_shader)
  7. maingroup.append(image) # shows the image

Using adafruit_imageload

You can also use the adafruit_imageload library that supports slightly more kinds of BMP files,
(but should still be paletized BMP3 format
as well as paletized PNG and GIF files. Which file format to choose?

  • BMP images are larger but faster to load
  • PNG images are about 2x smaller than BMP and almost as fast to load
  • GIF images are a little bigger than PNG but much slower to load
  1. import board, displayio
  2. import adafruit_imageload
  3. display = board.DISPLAY
  4. maingroup = displayio.Group() # everything goes in maingroup
  5. display.root_group = maingroup # set the root group to display
  6. bitmap, palette = adafruit_imageload.load("my_image.png")
  7. image = displayio.TileGrid(bitmap, pixel_shader=palette)
  8. maingroup.append(image) # shows the image

How displayio is structured

CircuitPython’s displayio library works like:

  • an image Bitmap (and its Palette) goes inside a TileGrid
  • a TileGrid goes inside a Group
  • a Group is shown on a Display.

Display background bitmap

Useful for display a solid background color that can be quickly changed.

  1. import time, board, displayio
  2. display = board.DISPLAY # get default display (FunHouse,Pygamer,etc)
  3. maingroup = displayio.Group() # Create a main group to hold everything
  4. display.root_group = maingroup # put it on the display
  5. # make bitmap that spans entire display, with 3 colors
  6. background = displayio.Bitmap(display.width, display.height, 3)
  7. # make a 3 color palette to match
  8. mypal = displayio.Palette(3)
  9. mypal[0] = 0x000000 # set colors (black)
  10. mypal[1] = 0x999900 # dark yellow
  11. mypal[2] = 0x009999 # dark cyan
  12. # Put background into main group, using palette to map palette ids to colors
  13. maingroup.append(displayio.TileGrid(background, pixel_shader=mypal))
  14. time.sleep(2)
  15. background.fill(2) # change background to dark cyan (mypal[2])
  16. time.sleep(2)
  17. background.fill(1) # change background to dark yellow (mypal[1])

Another way is to use
vectorio:

  1. import board, displayio, vectorio
  2. display = board.DISPLAY # built-in display
  3. maingroup = displayio.Group() # a main group that holds everything
  4. display.root_group = maingroup # put maingroup on the display
  5. mypal = displayio.Palette(1)
  6. mypal[0] = 0x999900
  7. background = vectorio.Rectangle(pixel_shader=mypal, width=display.width, height=display.height, x=0, y=0)
  8. maingroup.append(background)

Or can also use
adafruit_display_shapes:

  1. import board, displayio
  2. from adafruit_display_shapes.rect import Rect
  3. display = board.DISPLAY
  4. maingroup = displayio.Group() # a main group that holds everything
  5. display.root_group = maingroup # add it to display
  6. background = Rect(0,0, display.width, display.height, fill=0x000000 ) # background color
  7. maingroup.append(background)

Image slideshow

  1. import time, board, displayio
  2. import adafruit_imageload
  3. display = board.DISPLAY # get display object (built-in on some boards)
  4. screen = displayio.Group() # main group that holds all on-screen content
  5. display.root_group = screen # add it to display
  6. file_names = [ '/images/cat1.bmp', '/images/cat2.bmp' ] # list of filenames
  7. screen.append(displayio.Group()) # placeholder, will be replaced w/ screen[0] below
  8. while True:
  9. for fname in file_names:
  10. image, palette = adafruit_imageload.load(fname)
  11. screen[0] = displayio.TileGrid(image, pixel_shader=palette)
  12. time.sleep(1)

Note: Images must be in palettized BMP3 format.
For more details, see Preparing images for CircuitPython

Dealing with E-Ink “Refresh Too Soon” error

E-Ink displays are damaged if refreshed too frequently.
CircuitPython enforces this, but also provides display.time_to_refresh,
the number of seconds you need to wait before the display can be refreshed.
One solution is to sleep a little longer than that and you’ll never get the error.
Another would be to wait for time_to_refresh to go to zero, as show below.

  1. import time, board, displayio, terminalio
  2. from adafruit_display_text import label
  3. mylabel = label.Label(terminalio.FONT, text="demo", x=20,y=20,
  4. background_color=0x000000, color=0xffffff )
  5. display = board.DISPLAY # e.g. for MagTag
  6. display.root_group = mylabel
  7. while True:
  8. if display.time_to_refresh == 0:
  9. display.refresh()
  10. mylabel.text = str(time.monotonic())
  11. time.sleep(0.1)

Turn off REPL on built-in display

If you have a board with a built-in display (like Feather TFT, Cardputer, FunHouse, etc),
CircuitPython will set up the display for you and print the REPL to it.
But if you want a more polished look for your project, you can turn off the REPL
from printing on the built-in display by putting this at at the top of both
your boot.py and code.py

  1. # put at top of both boot.py & code.py
  2. import board
  3. board.DISPLAY.root_group = None

I2C

Scan I2C bus for devices

from:
CircuitPython I2C Guide: Find Your Sensor

  1. import board
  2. i2c = board.I2C() # or busio.I2C(pin_scl,pin_sda)
  3. while not i2c.try_lock(): pass
  4. print("I2C addresses found:", [hex(device_address)
  5. for device_address in i2c.scan()])
  6. i2c.unlock()

One liner to copy-n-paste into REPL for quicky I2C scan:

  1. import board; i2c=board.I2C(); i2c.try_lock(); [hex(a) for a in i2c.scan()]; i2c.unlock()

Speed up I2C bus

CircuitPython defaults to 100 kHz I2C bus speed. This will work for all devices,
but some devices can go faster. Common faster speeds are 200 kHz and 400 kHz.

  1. import board
  2. import busio
  3. # instead of doing
  4. # i2c = board.I2C()
  5. i2c = busio.I2C( board.SCL, board.SDA, frequency=200_000)
  6. # then do something with 'i2c' object as before, like:
  7. oled = adafruit_ssd1306.SSD1306_I2C(width=128, height=32, i2c=i2c)

Timing

Measure how long something takes

Generally use time.monotonic() to get the current “uptime” of a board in fractional seconds.
So to measure the duration it takes CircuitPython to do something like:

  1. import time
  2. start_time = time.monotonic()
  3. # put thing you want to measure here, like:
  4. import neopixel
  5. stop_time = time.monotonic()
  6. print("elapsed time = ", stop_time - start_time)

Note that on the “small” versions of CircuitPython in the QT Py M0, Trinket M0, etc.,
the floating point value of seconds will become less accurate as uptime increases.

More accurate timing with ticks_ms(), like Arduino millis()

If you want something more like Arduino’s millis() function, the supervisor.ticks_ms()
function returns an integer, not a floating point value. It is more useful for sub-second
timing tasks and you can still convert it to floating-point seconds for human consumption.

  1. import supervisor
  2. start_msecs = supervisor.ticks_ms()
  3. import neopixel
  4. stop_msecs = supervisor.ticks_ms()
  5. print("elapsed time = ", (stop_msecs - start_msecs)/1000)

Control garbage collection for reliable timing

The CircuitPython garbage collector makes it so you don’t have to deal with
memory allocations like you do in languages like C/C++. But when it runs, it can pause your
program for tens of milliseconds in some cases. For timing-sensitive applications,
you can exhibit some control over the garbage collector so it only runs when
you want it (like in the “shadow” after a timing-critical event)

Here’s one way to do this.

  1. import gc
  2. from adafruit_ticks import ticks_ms, ticks_add, ticks_less
  3. gc.collect() # collect any garbage before we...
  4. gc.disable() # disable automatic garbage collection
  5. dmillis = 10 # how many millis between explicit gc
  6. deadline = ticks_add(ticks_ms(), dmillis)
  7. while True:
  8. now = ticks_ms()
  9. if ticks_diff(now, deadline) >= 0:
  10. deadline = ticks_add(now, dmillis)
  11. gc.collect() # explicitly run a garbage collection cycle
  12. # do timing-sensitive thing here

Converting milliseconds to seconds: 0.004 * 1000 != 4, sometimes

When doing timing-sensitive tasks in CircuitPython, you may have code that looks like this (say from the above):

  1. from adafruit_ticks import ticks_ms, ticks_add, ticks_less
  2. check_secs = 0.004 # check_secs is seconds between checks
  3. check_millis = check_secs * 1000 # convert to millis
  4. deadline = ticks_add(ticks_ms(), check_millis)
  5. while True:
  6. now = ticks_ms()
  7. if ticks_less(now,deadline) >= 0:
  8. deadline = ticks_add(now, check_millis)
  9. do_periodic_task() # do timing-critical thing every 'check_secs'

This seems more accurate than using time.monotonic() since it’s using the millisecond-accurate supervisor.ticks_ms property, the timing resolution of CircuitPython.
This seems to work, until you pass in check_secs = 0.004, because the ticks_*() functions expect an integer and int(0.004*1000) = 3. If you were
using the above code to output an accurate timing signal, it’s now going to be 25% off from what you expect. This is ultimately because CircuitPython has reduced floating point precision (30-bit instead of 32-bit) (further discusion here).
In short: stick to integer milliseconds.

Board Info

Get CPU speed (and set it!)

CircuitPython provides a way to get the microcontroller’s CPU frequency with
microcontroller.cpu.frequency.

  1. import microcontroller
  2. print("CPU speed:", microcontroller.cpu.frequency)

On some chips (most notably Pico P2040), you can also set this value. Overclock your Pico!
It’s safe to double the RP2040 speed, Raspberry Pi officially supports up to 200 MHz.
CircuitPython will adjust its internal timings, but you should
do this change before creating any peripheral objects like UARTs or displays.

  1. import microcontroller
  2. microcontroller.cpu.frequency = 250_000_000 # run at 250 MHz instead of 125 MHz

Display amount of free RAM

from: https://learn.adafruit.com/welcome-to-circuitpython/frequently-asked-questions

  1. import gc
  2. print( gc.mem_free() )

Show microcontroller.pin to board mappings

from https://gist.github.com/anecdata/1c345cb2d137776d76b97a5d5678dc97

  1. import microcontroller
  2. import board
  3. for pin in dir(microcontroller.pin):
  4. if isinstance(getattr(microcontroller.pin, pin), microcontroller.Pin):
  5. print("".join(("microcontroller.pin.", pin, "\t")), end=" ")
  6. for alias in dir(board):
  7. if getattr(board, alias) is getattr(microcontroller.pin, pin):
  8. print("".join(("", "board.", alias)), end=" ")
  9. print()

Determine which board you’re on

  1. import os
  2. print(os.uname().machine)
  3. 'Adafruit ItsyBitsy M4 Express with samd51g19'

To get the chip family

  1. import os
  2. print(os.uname().sysname)
  3. 'ESP32S2'

Support multiple boards with one code.py

  1. import os
  2. board_type = os.uname().machine
  3. if 'QT Py M0' in board_type:
  4. tft_clk = board.SCK
  5. tft_mosi = board.MOSI
  6. spi = busio.SPI(clock=tft_clk, MOSI=tft_mosi)
  7. elif 'ItsyBitsy M4' in board_type:
  8. tft_clk = board.SCK
  9. tft_mosi = board.MOSI
  10. spi = busio.SPI(clock=tft_clk, MOSI=tft_mosi)
  11. elif 'Pico' in board_type:
  12. tft_clk = board.GP10 # must be a SPI CLK
  13. tft_mosi= board.GP11 # must be a SPI TX
  14. spi = busio.SPI(clock=tft_clk, MOSI=tft_mosi)
  15. else:
  16. print("unsupported board", board_type)

Computery Tasks

Formatting strings

  1. name = "John"
  2. fav_color = 0x003366
  3. body_temp = 98.65
  4. fav_number = 123
  5. print("name:%s color:%06x temp:%2.1f num:%d" % (name,fav_color,body_temp,fav_number))
  6. # 'name:John color:ff3366 temp:98.6 num:123'

Formatting strings with f-strings

(doesn’t work on ‘small’ CircuitPythons like QTPy M0)

  1. name = "John"
  2. fav_color = 0xff3366
  3. body_temp = 98.65
  4. fav_number = 123
  5. print(f"name:{name} color:{fav_color:06x} temp:{body_temp:2.1f} num:{fav_number}")
  6. # 'name:John color:ff3366 temp:98.6 num:123'

Using regular expressions to “findall” strings

Regular expressions are a really powerful way to match information in and parse data
from strings. While CircuitPython has a version of the re regex module you may know
from desktop Python, it is very limited. Specifcally it doesn’t have the very useful
re.findall() function. Below is a semi-replacement for findall().

  1. import re
  2. def find_all(regex, some_str):
  3. matches = []
  4. while m := regex.search(some_str):
  5. matches.append( m.groups() )
  6. some_str = some_str[ m.end(): ] # get past match
  7. return matches
  8. my_str = "<thing>thing1 I want</thing> <thing>thing2 I want</thing> <thing>thing3 I want</thing>"
  9. regex1 = re.compile('<thing.*?>(.*?)<\/thing>')
  10. my_matches = find_all( regex1, my_str )
  11. print("matches:", my_matches)

Make and use a config file

  1. # my_config.py
  2. config = {
  3. "username": "Grogu Djarin",
  4. "password": "ig88rules",
  5. "secret_key": "3a3d9bfaf05835df69713c470427fe35"
  6. }
  7. # code.py
  8. from my_config import config
  9. print("secret:", config['secret_key'])
  10. # 'secret: 3a3d9bfaf05835df69713c470427fe35'

Run different code.py on startup

Use microcontroller.nvm to store persistent state across
resets or between boot.py and code.py, and declare that
the first byte of nvm will be the startup_mode.
Now if you create multiple code.py files (say) code1.py, code2.py, etc.
you can switch between them based on startup_mode.

  1. import time
  2. import microcontroller
  3. startup_mode = microcontroller.nvm[0]
  4. if startup_mode == 1:
  5. import code1 # runs code in `code1.py`
  6. if startup_mode == 2:
  7. import code2 # runs code in `code2.py`
  8. # otherwise runs 'code.py`
  9. while True:
  10. print("main code.py")
  11. time.sleep(1)

Note: in CircuitPyton 7+ you can use supervisor.set_next_code_file()
to change which .py file is run on startup.
This changes only what happens on reload, not hardware reset or powerup.
Using it would look like:

  1. import supervisor
  2. supervisor.set_next_code_file('code_awesome.py')
  3. # and then if you want to run it now, trigger a reload
  4. supervisor.reload()

Coding Techniques

Map an input range to an output range

  1. # simple range mapper, like Arduino map()
  2. def map_range(s, a1, a2, b1, b2):
  3. return b1 + ((s - a1) * (b2 - b1) / (a2 - a1))
  4. # example: map 0-0123 value to 0.0-1.0 value
  5. val = 768
  6. outval = map_range( val, 0,1023, 0.0,1.0 )
  7. # outval = 0.75

Constrain an input to a min/max

The Python built-in min() and max() functions can be used together
to make something like Arduino’s constrain() to clamp an input between two values.

  1. # constrain a value to be 0-255
  2. outval = min(max(val, 0), 255)
  3. # constrain a value to be 0-255 integer
  4. outval = int(min(max(val, 0), 255))
  5. # constrain a value to be -1 to +1
  6. outval = min(max(val, -1), 1)

Turn a momentary value into a toggle

  1. import touchio
  2. import board
  3. touch_pin = touchio.TouchIn(board.GP6)
  4. last_touch_val = False # holds last measurement
  5. toggle_value = False # holds state of toggle switch
  6. while True:
  7. touch_val = touch_pin.value
  8. if touch_val != last_touch_val:
  9. if touch_val:
  10. toggle_value = not toggle_value # flip toggle
  11. print("toggle!", toggle_value)
  12. last_touch_val = touch_val

Do something every N seconds without sleep()

Also known as “blink-without-delay”

  1. import time
  2. last_time1 = time.monotonic() # holds when we did something #1
  3. last_time2 = time.monotonic() # holds when we did something #2
  4. while True:
  5. if time.monotonic() - last_time1 > 2.0: # every 2 seconds
  6. last_time1 = time.monotonic() # save when we do the thing
  7. print("hello!") # do thing #1
  8. if time.monotonic() - last_time2 > 5.0: # every 5 seconds
  9. last_time2 = time.monotonic() # save when we do the thing
  10. print("world!") # do thing #2

Note: a more accurate of this uses ticks_ms()
and maybe turning off gc / garbage collection.

System error handling

Preventing Ctrl-C from stopping the program

Put a try/except KeyboardInterrupt to catch the Ctrl-C
on the inside of your main loop.

  1. while True:
  2. try:
  3. print("Doing something important...")
  4. time.sleep(0.1)
  5. except KeyboardInterrupt:
  6. print("Nice try, human! Not quitting.")

Also useful for graceful shutdown (turning off neopixels, say) on Ctrl-C.

  1. import time, random
  2. import board, neopixel, rainbowio
  3. leds = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.4 )
  4. while True:
  5. try:
  6. rgb = rainbowio.colorwheel(int(time.monotonic()*75) % 255)
  7. leds.fill(rgb)
  8. time.sleep(0.05)
  9. except KeyboardInterrupt:
  10. print("shutting down nicely...")
  11. leds.fill(0)
  12. break # gets us out of the while True

Prevent auto-reload when CIRCUITPY is touched

Normally, CircuitPython restarts anytime the CIRCUITPY drive is written to.
This is great normally, but is frustrating if you want your code to keep running,
and you want to control exactly when a restart happens.

  1. import supervisor
  2. supervisor.runtime.autoreload = False # CirPy 8 and above
  3. #supervisor.disable_autoreload() # CirPy 7 and below

To trigger a reload, do a Ctrl-C + Ctrl-D in the REPL or reset your board.

Raspberry Pi Pico boot.py Protection

Also works on other RP2040-based boards like QTPy RP2040.
From https://gist.github.com/Neradoc/8056725be1c209475fd09ffc37c9fad4

Also see getting into Safe Mode with a REPL one-liner.

  1. # Copy this as 'boot.py' in your Pico's CIRCUITPY drive
  2. # Useful in case Pico locks up (which it's done a few times on me)
  3. import board
  4. import time
  5. from digitalio import DigitalInOut,Pull
  6. led = DigitalInOut(board.LED)
  7. led.switch_to_output()
  8. safe = DigitalInOut(board.GP14) # <-- choose your button pin
  9. safe.switch_to_input(Pull.UP)
  10. def reset_on_pin():
  11. if safe.value is False:
  12. import microcontroller
  13. microcontroller.on_next_reset(microcontroller.RunMode.SAFE_MODE)
  14. microcontroller.reset()
  15. led.value = False
  16. for x in range(16):
  17. reset_on_pin()
  18. led.value = not led.value # toggle LED on/off as notice
  19. time.sleep(0.1)

Using the REPL

The “serial” REPL is the most useful diagnostic tools in CircuitPython.
Always have it open when saving your code to see any errors.
If you use a separate terminal program instead of an IDE, I recommend tio.

Display built-in modules / libraries

  1. Adafruit CircuitPython 6.2.0-beta.2 on 2021-02-11; Adafruit Trinket M0 with samd21e18
  2. >>> help("modules")
  3. __main__ digitalio pulseio supervisor
  4. analogio gc pwmio sys
  5. array math random time
  6. board microcontroller rotaryio touchio
  7. builtins micropython rtc usb_hid
  8. busio neopixel_write storage usb_midi
  9. collections os struct
  10. Plus any modules on the filesystem

Turn off built-in display to speed up REPL printing

By default CircuitPython will echo the REPL to the display of those boards with built-in displays.
This can slow down the REPL. So one way to speed the REPL up is to hide the displayio.Group that
contains all the REPL output.

  1. import board, displayio
  2. board.DISPLAY.root_group = None # turn off REPL printing
  3. board.DISPLAY.root_group = displayio.CIRCUITPYTHON_TERMINAL # turn back on REPL printing

In CircuitPython 8.x, you could do the below. In 9.x, the root_group is read-only
after it’s been assigned.

  1. import board
  2. board.DISPLAY.root_group.hidden = True
  3. board.DISPLAY.root_group.hidden = False # to turn it back on

Useful REPL one-liners

(yes, semicolons are legal in Python)

  1. # get into Safe Mode if you have REPL access
  2. import microcontroller; microcontroller.on_next_reset(microcontroller.RunMode.SAFE_MODE); microcontroller.reset()
  3. # load common libraries (for later REPL experiments)
  4. import time, board, analogio, touchio; from digitalio import DigitalInOut,Pull
  5. # create a pin and set a pin LOW (if you've done the above)
  6. pin = DigitalInOut(board.GP0); pin.switch_to_output(value=False)
  7. # print out board pins and objects (like `I2C`, `STEMMA_I2C`, `DISPLAY`, if present)
  8. import board; dir(board)
  9. # print out microcontroller pins (chip pins, not the same as board pins)
  10. import microcontroller; dir(microcontroller.pin)
  11. # release configured / built-in display
  12. import displayio; displayio.release_displays()
  13. # turn off auto-reload when CIRCUITPY drive is touched
  14. import supervisor; supervisor.runtime.autoreload = False
  15. # test neopixel strip, make them all purple
  16. import board, neopixel; leds = neopixel.NeoPixel(board.GP3, 8, brightness=0.2); leds.fill(0xff00ff)
  17. leds.deinit() # releases pin
  18. # scan I2C bus
  19. import board; i2c=board.I2C(); i2c.try_lock(); [hex(a) for a in i2c.scan()]; i2c.unlock()

Python tricks

These are general Python tips that may be useful in CircuitPython.

Create list with elements all the same value

  1. blank_array = [0] * 50 # creats 50-element list of zeros

Convert RGB tuples to int and back again

Thanks to @Neradoc for this tip:

  1. rgb_tuple = (255, 0, 128)
  2. rgb_int = int.from_bytes(rgb_tuple, byteorder='big')
  3. rgb_int = 0xFF0080
  4. rgb_tuple2 = tuple((rgb_int).to_bytes(3,"big"))
  5. rgb_tuple2 == rgb_tuple

Storing multiple values per list entry

Create simple data structures as config to control your program.
Unlike Arduino, you can store multiple values per list/array entry.

  1. mycolors = (
  2. # color val, name
  3. (0x0000FF, "blue"),
  4. (0x00FFFF, "cyan"),
  5. (0xFF00FF, "purple"),
  6. )
  7. for i in range(len(mycolors)):
  8. (val, name) = mycolors[i]
  9. print("my color ", name, "has the value", val)

Python info

How to get information about Python inside of CircuitPython.

Display which (not built-in) libraries have been imported

  1. import sys
  2. print(sys.modules.keys())
  3. # 'dict_keys([])'
  4. import board
  5. import neopixel
  6. import adafruit_dotstar
  7. print(sys.modules.keys())
  8. prints "dict_keys(['neopixel', 'adafruit_dotstar'])"

List names of all global variables

  1. a = 123
  2. b = 'hello there'
  3. my_globals = sorted(dir)
  4. print(my_globals)
  5. # prints "['__name__', 'a', 'b']"
  6. if 'a' in my_globals:
  7. print("you have a variable named 'a'!")
  8. if 'c' in my_globals:
  9. print("you have a variable named 'c'!")

Display the running CircuitPython release

With an established serial connection, press Ctrl+c:

  1. Adafruit CircuitPython 7.1.1 on 2022-01-14; S2Pico with ESP32S2-S2FN4R2
  2. >>>

Without connection or code running, check the boot_out.txt file in your CIRCUITPY drive.

  1. import os
  2. print(os.uname().release)
  3. '7.1.1'
  4. print(os.uname().version)
  5. '7.1.1 on 2022-01-14'

Host-side tasks

Things you might need to do on your computer when using CircuitPython.

Installing CircuitPython libraries

The below examples are for MacOS / Linux. Similar commands are used for Windows

Installing libraries with circup

circup can be used to easily install and update modules

  1. $ pip3 install --user circup
  2. $ circup install adafruit_midi
  3. $ circup update # updates all modules

Freshly update all modules to latest version (e.g. when going from CP 6 -> CP 7)
(This is needed because circup update doesn’t actually seem to work reliably)

  1. circup freeze > mymodules.txt
  2. rm -rf /Volumes/CIRCUITPY/lib/*
  3. circup install -r mymodules.txt

And updating circup when a new version of CircuitPython comes out:

  1. $ pip3 install --upgrade circup

Copying libraries by hand with cp

To install libraries by hand from the
CircuitPython Library Bundle
or from the CircuitPython Community Bundle (which circup doesn’t support), get the bundle, unzip it and then use cp -rX.

  1. cp -rX bundle_folder/lib/adafruit_midi /Volumes/CIRCUITPY/lib

Note: on limited-memory boards like Trinkey, Trinket, QTPy, you must use the -X option on MacOS
to save space. You may also need to omit unused parts of some libraries (e.g. adafruit_midi/system_exclusive is not needed if just sending MIDI notes)

Preparing images for CircuitPython

There’s two ways to load images for use with displayio:

displayio.OnDisBitmap():

  • can load “indexed” (aka “palette”) non-compressed BMP3 images
  • doesn’t load image into RAM (great for TileGrids)

adafruit_imageload

  • can load BMP3 images with RLE compression
  • loads entire image into RAM (thus you may run out of memory)
  • an load palette PNG images and GIF images
  • PNG image loading is almost as fast as BMP and uses 1/2 the disk space
  • GIF loading is very slow

To make images load faster generally, you can reduce the number of colors in the image.
The maximum number of colors is 256, but try reducing colors to 64 or even 2 if
it’s a black-n-white image.

Some existing Learn Guides:

And here’s some ways to do the conversions.

Online

Most online image converters do not create BMPs in the proper format:
BMP3, non-compressed, up to 256 colors in an 8-bit palette.

However @Neradoc found the site convert2bmp
will work when you set “Color:” mode to “8 (Indexed)”. Some initial tests show this works!
I’d recommend also trying out one of the following techniques too to have finer control.

The site https://cancerberosgx.github.io/magic/playground/ lets you
use any of the ImageMagick commands below to convert images. It’s really handy if you can’t
install ImageMagick locally.

Command-line: using ImageMagick

ImageMagick is a command-line image manipulation tool. With it,
you can convert any image format to BMP3 format. The main ImageMagick CLI command is convert.

  1. convert myimage.jpg -resize 240x240 -type palette -colors 64 -compress None BMP3:myimage_for_cirpy.bmp

You can also use this technique to create reduced-color palette PNGs:

  1. convert myimage.jpg -resize 240x240 -type palette -colors 64 myimage.png

Command-line: using GraphicsMagick

GraphicsMagick is a slimmer, lower-requirement
clone of ImageMagick. All GraphicsMagick commands are accessed via the gm CLI command.

  1. gm convert myimage.jpg -resize 240x240 -colors 64 -type palette -compress None BMP3:myimage_for_cirpy.bmp

Making images smaller or for E-Ink displays

To make images smaller (and load faster), reduce number of colors from 256.
If your image is a monochrome (or for use with E-Ink displays like MagTag), use 2 colors.
The “-dither” options
are really helpful for monochrome:

  1. convert cat.jpg -dither FloydSteinberg -colors 2 -type palette BMP3:cat.bmp

NodeJs: using gm

There is a nice wrapper around GraphicsMagick / Imagemagick with the gm library.
A small NodeJs program to convert images could look like this:

  1. var gm = require('gm');
  2. gm('myimage.jpg')
  3. .resize(240, 240)
  4. .colors(64)
  5. .type("palette")
  6. .compress("None")
  7. .write('BMP3:myimage_for_cirpy.bmp', function (err) {
  8. if (!err) console.log('done1');
  9. });

Python: using PIL / pillow

The Python Image Library (PIL) fork pillow
seems to work the best. It’s unclear how to toggle compression.

  1. from PIL import Image
  2. size = (240, 240)
  3. num_colors = 64
  4. img = Image.open('myimage.jpg')
  5. img = img.resize(size)
  6. newimg = img.convert(mode='P', colors=num_colors)
  7. newimg.save('myimage_for_cirpy.bmp')

Preparing audio files for CircuitPython

CircuitPython can play both WAV files and MP3 files, but there are specific
variants of these files that will work better, as some options require much more
processor demand. WAV files are much easier to play but take up more disk space.

WAV files

For WAV files, I’ve found the best trade-off in quality / flash-space / compatibility to be:

  • PCM 16-bit signed PCM
  • Mono (but stereo will work if using I2S or SAMD51)
  • 22050 Hz sample rate

And remember that these settings must match how you’re setting up the audiomixer object.
So for the above settings, you’d create an audiomixer.Mixer like:

  1. mixer = audiomixer.Mixer(voice_count=1, sample_rate=22050, channel_count=1,
  2. bits_per_sample=16, samples_signed=True)

To convert WAVs for CircuitPython, I like to use Audacity or the sox command-line tool.
Sox can convert just about any audio to the correct WAV format:

  1. sox loop.mp3 -b 16 -c 1 -r 22050 loop.wav

MP3 files

MP3 files require a lot more CPU to decode so in general you will want to
re-encode MP3s to be a lower bit-rate and lower sample-rate. These settings
seem to work okay on an lower-end chip like the Pico /RP2040:

  • 128 kbps data rate CBR or lower
  • 22050 Hz sample rate or lower
  • Mono

In sox, you can do this conversion with:

  1. sox loop.mp3 -c 1 -r 22050 -C 128 loop_22k_128kbps.mp3

Getting sox

To get sox on various platforms:

Some audio Learn Guide links:

Circup hacks

circup
is a great tool to help you install CircuitPython libraries. Think of it like pip or npm for CircuitPython.

Finding where circup stores its files

Instead of downloading the bundles by hand, circup has it already downloaded an unzipped.
Here’s how to find that directory:

  1. circup_dir=`python3 -c 'import appdirs; print(appdirs.user_data_dir(appname="circup", appauthor="adafruit"))'`
  2. ls $circup_dir

Building CircuitPython

If you want to build CircuitPython yourself, you can! It’s not too bad.
There’s a very good “Building CircuitPython” Learn Guide that I refer to all the time, since it goes through the main reasons
why you might want to build your own version of CircuitPython, including:

  • Adding “Frozen” Modules (libraries built-in to the firmware)
  • Setting different SPI flash chips (if your custom board uses a different kind of flash)
  • Adding a new board to CircuitPython

But if you just want a quick list of the commands to use to build, here’s what I use
(as of Jun 2024) to build CircuitPython for rp2040.

  1. git clone https://github.com/todbot/circuitpython circuitpython-todbot
  2. cd circuitpython-todbot
  3. pip3 install --upgrade -r requirements-dev.txt # do occasionally, after 'git pull'
  4. pip3 install --upgrade -r requirements-doc.txt # do occasionally, after 'git pull'
  5. cd ports/raspberrypi
  6. make fetch-port-submodules # takes a long time the first time ran, do after 'git pull' too
  7. make BOARD=raspberry_pi_pico # or other board name listed in ports/raspberrypi/boards/
  8. # make -C ../../mpy-cross # if you need mpy-cross

And for Espressif / ESP32 builds:

  1. git clone https://github.com/todbot/circuitpython circuitpython-todbot
  2. cd circuitpython-todbot
  3. pip3 install --upgrade -r requirements-dev.txt # do occasionally, after 'git pull'
  4. pip3 install --upgrade -r requirements-doc.txt # do occasionally, after 'git pull'
  5. cd ports/espressif
  6. make fetch-port-submodules # takes a long time the first time ran, do after 'git pull' too
  7. ./esp-idf/install.sh
  8. . ./esp-idf/export.sh
  9. pip3 install --upgrade -r requirements-dev.txt # because now we're using a new python
  10. pip3 install --upgrade -r requirements-doc.txt # because now we're using a new python
  11. make BOARD=adafruit_qtpy_esp32s3

Note, this assumes you’ve already installed the system-level prerequisites.
On MacOS, this is what I do to get those:

  1. brew install git git-lfs python3 gettext uncrustify cmake
  2. brew install gcc-arm-embedded # (the cask, not 'arm-none-eabi-gcc')

About this guide

  • Many of the code snippets are not considered “well-formatted”
    by Python linters. This guide favors brevity over strict style adherence.

  • The precursor to this guide is QTPy Tricks,
    which has similar but different (and still valid) fun things to do in CircuitPython.

  • This guide is the result of trying to learn Python via CircuitPython and
    from very enlightening discussions with John Edgar Park. I have a good background in
    other languages, but mostly C/C++, and have
    taught classes in Arduino for several years.
    This informs how I’ve been thinking about things in this guide.