# CircuitPython on Raspberry Pi (Bare Metal / No OS)

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/107/780/medium800/circuitpython_IMG_4240.jpg?1641937751)

The Raspberry Pi single board computers (SBCs for short) are normally used with the Raspberry Pi OS. This is great for gaming and web browsing, but isn't designed for microcontroller-like tasks. Tasks like reading I2C sensors and SPI devices can be trickier. Furthermore, Linux system maintenance can be tricky for beginners.

Instead of Raspberry Pi OS, one can now use CircuitPython instead. CircuitPython running without another operating system (OS) is typically known as "bare metal". This greatly simplifies system maintenance and makes it easier to treat the Raspberry Pi like a microcontroller. In addition, running CircuitPython on the Raspberry Pi increases the amount of flash and RAM available to CircuitPython programs. Finally, it also adds the ability to use displayio on HDMI displays.

Folks may be running CircuitPython programs from within Raspberry Pi OS currently through Blinka. This is different from CircuitPython standalone because you edit the files using the computer itself and are limited by the underlying OS. See [the Blinka guide](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux) for details on how to use a CircuitPython program from within Raspberry Pi OS.

# Status

CircuitPython support for the Raspberry Pi SBCs was added in CircuitPython 7.1.0 and is done under the `broadcom` port. The list of known issues is available on [the CircuitPython GitHub project under the "broadcom" label](https://github.com/adafruit/circuitpython/issues?q=is%3Aopen+is%3Aissue+label%3Abroadcom).

## Parts
Select from the supported boards. Then look for accessories specific to that board (power supply, video cable, etc.). If the Compute Module 4 is used, a suitable carrier board like the official IO Board will be needed.

Featured
### Raspberry Pi Compute Module 4 - 4GB RAM, 32GB MMC and WiFi

[Raspberry Pi Compute Module 4 - 4GB RAM, 32GB MMC and WiFi](https://www.adafruit.com/product/4982)
The **Raspberry Pi Compute Module 4** is based on the [Raspberry Pi 4 Model B](http://www.adafruit.com/product/4297), but in a smaller form factor - perfect for embedding into products or projects without the bulk of a classic Raspberry Pi. You get all the computational...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4982)
[Related Guides to the Product](https://learn.adafruit.com/products/4982/guides)
![Angled shot of compute module.](https://cdn-shop.adafruit.com/640x480/4982-00.jpg)

Featured
### Raspberry Pi Compute Module 4 IO Board

[Raspberry Pi Compute Module 4 IO Board](https://www.adafruit.com/product/4787)
Exposing every interface from Raspberry Pi Compute Module 4, the **Compute Module 4 IO Board** provides a development platform and reference base-board design for the most powerful Compute Module yet.

The **Compute Module 4 IO Board**  is a development board...

In Stock
[Buy Now](https://www.adafruit.com/product/4787)
[Related Guides to the Product](https://learn.adafruit.com/products/4787/guides)
![Angled shot of large Raspberry Pi Compute Module 4 I/O Board.](https://cdn-shop.adafruit.com/640x480/4787-05.jpg)

Featured
### Raspberry Pi 4 Model B - 2 GB RAM

[Raspberry Pi 4 Model B - 2 GB RAM](https://www.adafruit.com/product/4292)
The Raspberry Pi 4 Model B is the newest Raspberry Pi computer made, and the Pi Foundation knows you can always make a good thing _better_! And what could make the Pi 4...

In Stock
[Buy Now](https://www.adafruit.com/product/4292)
[Related Guides to the Product](https://learn.adafruit.com/products/4292/guides)
![Angled Shot of the Raspberry Pi 4 Model B - 2 GB RAM](https://cdn-shop.adafruit.com/640x480/4292-13.jpg)

Featured
### Raspberry Pi Zero W

[Raspberry Pi Zero W](https://www.adafruit.com/product/3400)
If you didn't think that the Raspberry Pi Zero could possibly get any better, then boy do we have a pleasant surprise for you! The new **Raspberry Pi Zero W** offers all the benefits of the Pi Zero v1.3, but with one big difference – **built-in...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3400)
[Related Guides to the Product](https://learn.adafruit.com/products/3400/guides)
![Angled shot of Raspberry Pi Zero W computer.](https://cdn-shop.adafruit.com/640x480/3400-06.jpg)

Featured
### Raspberry Pi Zero 2 W

[Raspberry Pi Zero 2 W](https://www.adafruit.com/product/5291)
 **Raspberry Pi Zero 2 W** is the latest product in Raspberry Pi's most affordable range of single-board computers. The successor to the breakthrough Raspberry Pi Zero W, **Raspberry Pi Zero 2 W** is a form factor–compatible drop-in replacement for the...

Out of Stock
[Buy Now](https://www.adafruit.com/product/5291)
[Related Guides to the Product](https://learn.adafruit.com/products/5291/guides)
![Angled shot of a Raspberry Pi Zero 2 W.](https://cdn-shop.adafruit.com/640x480/5291-00.jpg)

# CircuitPython on Raspberry Pi (Bare Metal / No OS)

## Installation

CircuitPython builds for Raspberry Pi boards are available on circuitpython.org just like other microcontroller versions, under the Downloads section.

[Download from CircuitPython.org](https://circuitpython.org/downloads?q=raspberry+pi)
![](https://cdn-learn.adafruit.com/assets/assets/000/106/996/medium800/circuitpython_Screenshot_2021-12-03_at_15-18-01_CircuitPython_-_Downloads.png?1638573511)

Next, click on the board that you have.

![](https://cdn-learn.adafruit.com/assets/assets/000/106/997/medium800/circuitpython_Screenshot_2021-12-03_at_15-19-05_CircuitPython_-_Raspberry_Pi_Zero_2_W_Download.png?1638573752)

The board page allows you to download the stable or unstable release of CircuitPython. This notion of stability applies to CircuitPython as a whole, not necessarily the "port", meaning support for certain chip family. For the Raspberry Pi builds, always use "unstable" or "absolute latest" while the port is still in an alpha state (documented in the release notes.)

Additionally, you can also select a language for all of the serial messages including Python errors.

Broadcom builds come in two different file types:

- `.disk.img.zip` is full filesystem image that is typically used by "imager" programs like `rpi-imager`.
- `.kernel8.img`  or `.kernel.img` is only the CircuitPython portion of the image and can be copied directly onto an existing SD card.

The disk image is best to start with but may overwrite the CircuitPython filesystem if used for updating. (The actual behavior varies based on the imaging program.)

## Raspberry Pi Imager

Raspberry Pi (the company) has created an imager that makes it easy to write disk images to an SD card. We'll use it to write the CircuitPython disk image to a card. Install the Raspberry Pi Imager based on instructions from [the Raspberry Pi website](https://www.raspberrypi.com/software/).

Danger: 

After launching the Imager, click "Choose OS".

![](https://cdn-learn.adafruit.com/assets/assets/000/107/001/medium800/circuitpython_2021-12-03_18-00.png?1638583278)

Then, scroll down to the bottom of the popup and select "Use custom".

![](https://cdn-learn.adafruit.com/assets/assets/000/107/002/medium800/circuitpython_2021-12-03_18-04.png?1638583471)

![](https://cdn-learn.adafruit.com/assets/assets/000/107/003/medium800/circuitpython_2021-12-03_18-02.png?1638583478)

In the file selection dialog, pick the .disk.img.zip file that you downloaded earlier.

![](https://cdn-learn.adafruit.com/assets/assets/000/107/005/medium800/circuitpython_2021-12-03_18-07.png?1638583757)

Next, choose the storage device to write the disk image to. Make sure it's correct! It will be overwritten.

![](https://cdn-learn.adafruit.com/assets/assets/000/107/006/medium800/circuitpython_2021-12-03_18-10.png?1638583812)

![](https://cdn-learn.adafruit.com/assets/assets/000/107/007/medium800/circuitpython_2021-12-03_18-11.png?1638583908)

After selecting the disk you wish to write, the middle box will change. To initiate the write click "WRITE". Imager will confirm the selection.

![](https://cdn-learn.adafruit.com/assets/assets/000/107/734/medium800/circuitpython_2021-12-03_18-12.png?1641855284)

![](https://cdn-learn.adafruit.com/assets/assets/000/107/735/medium800/circuitpython_2021-12-03_18-13.png?1641855300)

After confirming the write, a progress bar will show for writing the SD card and then verifying the contents were written correctly.

![](https://cdn-learn.adafruit.com/assets/assets/000/107/736/medium800/circuitpython_2021-12-03_18-14.png?1641855323)

![](https://cdn-learn.adafruit.com/assets/assets/000/107/738/medium800/circuitpython_2021-12-03_18-15.png?1641855331)

After the SD card is written, remove it from the writer and insert it into an unpowered Raspberry Pi. Power the board up to start CircuitPython.

On first power up, CircuitPython will create a second partition on the SD card to use for the **CIRCUITPY** drive. On subsequent flashes, some writers may preserve this partition but others may not. So, make sure and back up your code prior to flashing.

## Upgrading

The CircuitPython disk image includes the CircuitPython code along with supporting code from the Pi folks and potentially erases the whole card.

If you want to just update CircuitPython, then you can download the kernel image alone (called kernel.img for Zeros and kernel8.img for Zero 2, Pi 3 and Pi 4.)

From circuitpython.org/downloads the filename is really long but the Raspberry Pi boot code only knows how to find the exact short name.

So, to update CircuitPython first download the kernel img file following the instructions above and then rename it to remove the circuitpython information.

![](https://cdn-learn.adafruit.com/assets/assets/000/107/744/medium800/circuitpython_2022-01-10_15-08.png?1641856343)

![](https://cdn-learn.adafruit.com/assets/assets/000/107/745/medium800/circuitpython_2022-01-10_15-10.png?1641856364)

After renaming the file, drag or copy the file onto BOOT. If your OS asks, confirm that you want to overwrite the existing file.

Info: 

Again, after upgrading, put the SD card back into your Pi when powered off and then power it up.

# CircuitPython on Raspberry Pi (Bare Metal / No OS)

## Connecting

Raspberry Pi boards are typically designed to make it easy to connect USB devices like mice and keyboards. In that case, the Raspberry Pi itself is known as a USB host. The rectangular USB-A connector usually designates the host side of a cable.

However, CircuitPython is usually acts as a device itself. That's how it presents a **CIRCUITPY** drive and/or acts as a keyboard. This is normally done with the small micro-B style plug.

Newer boards have USB-C which can indicate either USB device or host.

For CircuitPython on the Raspberry Pi, the USB device capable connector varies per board design. The board description on CircuitPython.org includes instructions. Below is info for official Raspberry Pi boards.

Warning: 

## Pi Zero and Zero W

Connect to the micro-B connector marked `USB`.

![](https://cdn-learn.adafruit.com/assets/assets/000/107/699/medium800/circuitpython_3400-00.jpg?1641500108)

## Pi Zero 2 W

Connect to the micro-B connector marked `USB`.

![](https://cdn-learn.adafruit.com/assets/assets/000/106/998/medium800/circuitpython_5291-00.jpg?1638575070)

## Pi 4 Model B

The USB-C power connector is also device capable. Use a powered USB hub to both power the Pi and connect it to your computer.

![](https://cdn-learn.adafruit.com/assets/assets/000/106/999/medium800/circuitpython_4296-11.jpg?1638575325)

## CM4 IO

The Raspberry Pi CM4 IO board has a dedicated micro-B connector for USB device.

![](https://cdn-learn.adafruit.com/assets/assets/000/107/000/medium800/circuitpython_4787-06.jpg?1638575526)

# CircuitPython on Raspberry Pi (Bare Metal / No OS)

## Using CircuitPython

The CircuitPython experience on the Raspberry Pi is very similar to the experience on all of the other USB capable CircuitPython boards. One difference is that the **CIRCUITPY** drive is on removable storage. So please leave the SD card inserted for the whole time CIrcuitPython is running.

## New to CircuitPython
If you are new to CircuitPython, then start by checking out the excellent [Welcome to CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython) and [CircuitPython Essentials](https://learn.adafruit.com/circuitpython-essentials/) guides. They'll get you started connecting to the CircuitPython serial and editing **code.py**. The essentials guide will provide basic examples for the common hardware interfaces.

[Welcome to CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython)
[CircuitPython Essentials](https://learn.adafruit.com/circuitpython-essentials/)
## Experienced CircuitPythonistas
The Raspberry Pi port is still very new and is likely missing modules you've used on other boards. Check out the [Support Matrix](https://circuitpython.readthedocs.io/en/latest/shared-bindings/support_matrix.html) for the lastest details on what is supported.

[Support Matrix](https://circuitpython.readthedocs.io/en/latest/shared-bindings/support_matrix.html)
## HDMI
One of the main benefits of CircuitPython on the Raspberry Pi, is the easy use of a connected HDMI display. These are the first CircuitPython boards to support HDMI output. (Audio output over HDMI isn't currently supported.)

When using a display, make sure it is connected on bootup. The GPU firmware will discover the connected display and start the video output. Once CircuitPython starts, it will start a 640x480 frame buffer for `displayio`'s normal terminal output. This is likely the wrong size for your display (but it's a safe bet for support.) So, you can reinitialize the CircuitPython framebuffer with a few lines of code. This code can be put into **boot.py** if you want to run it once on boot or in **code.py** if you want to change it later. The example sets the output to 1/4 the size of HDMI (half of each dimension) because large terminal framebuffers are a bit slow for CIrcuitPython to update.

```python
import displayio
import framebufferio
import videocore

displayio.release_displays()
fb = videocore.Framebuffer(1920 // 2, 1080 // 2)
display = framebufferio.FramebufferDisplay(fb)
```

After this re-initialization, `display` variable or `board.DISPLAY` can be used as normal. Check out the displayio guide for details.

[displayio Guide](https://learn.adafruit.com/circuitpython-display-support-using-displayio)
# CircuitPython on Raspberry Pi (Bare Metal / No OS)

## Debug

Warning: 

## Print Debugging

The easiest way to debug is by adding print statements into the CircuitPython C code and viewing the output over UART. UART is a serial connection that is available earlier than serial over USB and tends to be more reliable as well.

```cpp
#include "runtime.h"


...

// Acts like printf.
mp_printf(&mp_plat_print, "hello %d\n", 10);
```

The broadcom builds have the DEBUG UART enabled by default on the default RX and TX pins in the 40 pin header. Connect a USB to Serial converter to view the debug output.

One can also send serial input to CircuitPython over this connection.

## GDB

It is also possible to connect to the CPUs over GDB via openocd. See [the GDB guide](https://learn.adafruit.com/debugging-the-samd21-with-gdb) for installation and usage details.

The `broadcom-peripherals` library includes [configuration files for openocd](). Here is an example command to run from `ports/broadcom` from within the CircuitPython repo that uses a JLink to talk to the Pi.

```shell
openocd -d -f interface/jlink.cfg -f peripherals/openocd/bcm2835.cfg
```

Then, within GDB do this to connect to OpenOCD:
```
tar ext :3333
```


## Guide Products

### Raspberry Pi Compute Module 4 - 4GB RAM, 32GB MMC and WiFi

[Raspberry Pi Compute Module 4 - 4GB RAM, 32GB MMC and WiFi](https://www.adafruit.com/product/4982)
The **Raspberry Pi Compute Module 4** is based on the [Raspberry Pi 4 Model B](http://www.adafruit.com/product/4297), but in a smaller form factor - perfect for embedding into products or projects without the bulk of a classic Raspberry Pi. You get all the computational...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4982)
[Related Guides to the Product](https://learn.adafruit.com/products/4982/guides)
### Raspberry Pi Compute Module 4 IO Board

[Raspberry Pi Compute Module 4 IO Board](https://www.adafruit.com/product/4787)
Exposing every interface from Raspberry Pi Compute Module 4, the **Compute Module 4 IO Board** provides a development platform and reference base-board design for the most powerful Compute Module yet.

The **Compute Module 4 IO Board**  is a development board...

In Stock
[Buy Now](https://www.adafruit.com/product/4787)
[Related Guides to the Product](https://learn.adafruit.com/products/4787/guides)
### Raspberry Pi 4 Model B - 2 GB RAM

[Raspberry Pi 4 Model B - 2 GB RAM](https://www.adafruit.com/product/4292)
The Raspberry Pi 4 Model B is the newest Raspberry Pi computer made, and the Pi Foundation knows you can always make a good thing _better_! And what could make the Pi 4...

In Stock
[Buy Now](https://www.adafruit.com/product/4292)
[Related Guides to the Product](https://learn.adafruit.com/products/4292/guides)
### Raspberry Pi Zero W

[Raspberry Pi Zero W](https://www.adafruit.com/product/3400)
If you didn't think that the Raspberry Pi Zero could possibly get any better, then boy do we have a pleasant surprise for you! The new **Raspberry Pi Zero W** offers all the benefits of the Pi Zero v1.3, but with one big difference – **built-in...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3400)
[Related Guides to the Product](https://learn.adafruit.com/products/3400/guides)
### Raspberry Pi Zero 2 W

[Raspberry Pi Zero 2 W](https://www.adafruit.com/product/5291)
 **Raspberry Pi Zero 2 W** is the latest product in Raspberry Pi's most affordable range of single-board computers. The successor to the breakthrough Raspberry Pi Zero W, **Raspberry Pi Zero 2 W** is a form factor–compatible drop-in replacement for the...

Out of Stock
[Buy Now](https://www.adafruit.com/product/5291)
[Related Guides to the Product](https://learn.adafruit.com/products/5291/guides)

## Related Guides

- [Raspberry Pi Care and Troubleshooting](https://learn.adafruit.com/raspberry-pi-care-and-troubleshooting.md)
- [Boomy Pi Airplay Boombox](https://learn.adafruit.com/boomy-pi-airplay.md)
- [Make a Pi Trash Classifier with Machine Learning and Lobe](https://learn.adafruit.com/lobe-trash-classifier-machine-learning.md)
- [Pi SSD Media Server](https://learn.adafruit.com/pi-ssd-media-server.md)
- [Single Channel LoRaWAN Gateway for Raspberry Pi](https://learn.adafruit.com/raspberry-pi-single-channel-lorawan-gateway.md)
- [Adafruit IO Home: Lights and Temperature ](https://learn.adafruit.com/adafruit-io-house-lights-and-temperature.md)
- [Python Edge Speech Recognition with Voice2JSON](https://learn.adafruit.com/edge-speech-recognition-with-voice2json.md)
- [Mini Smart Home with Huzzah, HASSio and Crickit](https://learn.adafruit.com/mini-smart-home-with-esp8266-huzzah-feather-raspberry-pi-hassio-crickit.md)
- [Adafruit IO Home: Security ](https://learn.adafruit.com/adafruit-io-home-security.md)
- [Face Mask Efficacy Testing with SCIENCE!](https://learn.adafruit.com/raspberry-pi-camera-vision-face-mask-efficacy-testing.md)
- [reef-pi Guide 6: pH Monitoring](https://learn.adafruit.com/reef-pi-guide-7-ph-monitoring.md)
- [Raspberry Pi LED Matrix Sand Toy](https://learn.adafruit.com/matrix-led-sand.md)
- [PiGlass v2](https://learn.adafruit.com/piglass-v2-wearable-raspberry-pi-computer.md)
- [RGB LED Matrix Cube with 25,000 LEDs](https://learn.adafruit.com/rgb-led-matrix-cube-for-pi.md)
- [Programming with Scratch 2 or 3 on Raspberry Pi](https://learn.adafruit.com/programming-with-scratch-on-raspberry-pi.md)
- [BrainCraft Camera Case](https://learn.adafruit.com/braincraft-camera-case.md)