CircuitPython’s APIs on MicroPython and CPython
Code written for CircuitPython’s own modules can often run unchanged on MicroPython-compatible firmware or on a desktop, because OmniPython provides those modules under their CircuitPython names. This page says which ones, where each runs, and where it differs from CircuitPython.
Where a module is in both CircuitPython and OmniPython, OmniPython follows CircuitPython’s names, arguments and behaviour. Where it can’t, the difference is listed under the module. On CircuitPython itself you use CircuitPython’s own native modules, so nothing here runs there unless it says so.
At a glance
Module |
MicroPython firmware |
Desktop CPython |
Comes from |
|---|---|---|---|
|
yes |
yes |
|
|
yes, with |
no |
|
|
yes, with |
yes, over Pillow |
|
|
yes, on ESP32, RP2 with Wi-Fi, unix and Windows |
yes, over python-zeroconf |
|
|
yes |
no |
|
|
yes, on boards that can be a USB device |
no |
|
|
yes, on the chips named below |
no |
|
|
yes, opt-in, needs PSRAM |
no |
|
|
yes, on the ESP32-P4 |
no |
|
|
yes, with |
no |
“With X built in” means the firmware has to be built with that module. The
default all set includes each firmware module here except picotts, which is
opt-in, as
Modules
lists. wifi and usb_hid are Python packages, installed with mip.
Not on this page: CircuitPython’s displayio, digitalio, busio and board.
MicroPython has its own machine for pins and buses, and OmniPython’s
board config names a board’s peripherals. A
CircuitPython program that uses those modules directly doesn’t run on
MicroPython as it stands.
Audio
audiodsp
gives MicroPython and CPython CircuitPython’s audio modules with the same import
names: audiocore (WaveFile and RawSample), audiomixer, synthio
(including MidiTrack), audiofilters, audiodelays, audiofreeverb,
audiospeed and audiomp3. They follow CircuitPython’s play(), stop(),
pause() and resume() behaviour too. On a desktop, pip install omnipython-audiodsp brings them; in firmware, the audiodsp module does.
Where one of them behaves differently from the CircuitPython you have, the upstream differences page says where.
Audio hardware
The audio modules make sound but don’t send it anywhere. On MicroPython
firmware built with audioif, audiobusio.I2SOut and audioi2sin.I2SIn do:
import audiobusio, audiocore, board
out = audiobusio.I2SOut(board.GPIO12, board.GPIO13, board.GPIO14)
out.play(sample, loop=True)
CircuitPython’s own I2SOut example runs unchanged apart from the three pins.
It differs in a few ways: a second I2SOut raises "Peripheral in use" as in
CircuitPython, pause() leaves the bus clocking zeros instead of disabling the
channel, and left_justified and external_clock raise NotImplementedError.
I2SOut also takes a few extras (port=, sample_rate=, main_clock_fs=,
data_in= and sink=, which writes to a file on a desktop build).
audioif
has the details, and Portable audio shows the same sound
reaching hardware on every platform. audiobusio isn’t available on desktop CPython: use audiodev
there.
jpegio
jpegio.JpegDecoder has CircuitPython’s API on MicroPython firmware built with
jpegio, and on a desktop in omnipython-desktop, where it runs over Pillow.
The firmware module also has a JpegEncoder, which CircuitPython doesn’t. Output
is RGB565. The
stub
lists each argument.
mdns
mdns.Server announces what a device offers on the network and finds what
others offer, with CircuitPython’s API. On firmware it runs on ESP32, on RP2
boards with a CYW43 radio, on unix and on Windows. A browser build has none. On a
desktop, omnipython-desktop’s mdns.py gives the same API over python-zeroconf.
See mdns.
wifi
wifi.radio over network.WLAN, so board code that joins a network runs
unchanged:
import wifi
wifi.radio.connect("ssid", "password")
print(wifi.radio.ipv4_address, wifi.radio.ap_info.rssi)
It differs from CircuitPython in these ways:
Addresses are strings, not
ipaddress.IPv4Address.wifi.ConnectionErroris a subclass ofOSError, so catchOSErrorto run on both.connect(..., timeout=0)starts joining and returns at once.channel=is accepted and ignored.Network.authmodeis the port’s integer.There is no
socketpool: usesocketorrequests.
To join from secrets.py or a network the board remembered, use
wifi_manager, which also runs on CircuitPython.
usb_hid
CircuitPython’s usb_hid on MicroPython boards that can be a USB device, from
the usb-hid package, over usb-device-hid. usb_hid.enable() takes
CircuitPython’s Device objects, including the custom gamepad and absolute
pointer. See USB, both ways round.
Display hardware
The display modules in displayif keep CircuitPython’s names where there is a CircuitPython module of the same job:
Module |
Runs on |
|---|---|
|
ESP32-P4, i.MX RT 1176, STM32H747 and H757 |
|
ESP32 (RGB LCD), i.MX RT 1062 |
|
RP2040 and RP2350 |
|
ESP32-S3, i.MX RT 1062, SAMD51, RP2 |
On a port that isn’t listed, the constructor raises. Boards running CircuitPython have these modules natively.
The arguments aren’t always CircuitPython’s: each module’s stub, such as
mipidsi.pyi,
has the exact signature. Displays shows how a program
reaches any of them through displaydev.
picotts
Text to speech on the board, behind the API of Adafruit’s adafruit_picotts.
You hand it an OmniPython audio output instead of CircuitPython’s audiobusio
object, and import it as picotts. It needs PSRAM and a firmware built with the
opt-in picotts module. See the
picotts README.
espcamera
On an ESP32-P4, cameraif is also importable as espcamera, with that module’s
properties (brightness, contrast, saturation) alongside cameraif’s own.
The
cameraif README
says where a program written for espcamera needs a change.
ulab
OmniPython firmware can carry ulab, the same project CircuitPython builds in.
Everything else
A CircuitPython module that isn’t on this page isn’t provided on MicroPython or CPython. If you need one, open an issue.