Here at Adafruit we're always looking for ways to make making easier - whether that's making breakout boards for hard-to-solder sensors or writing libraries to simplify motor control. Our new favorite way to program is CircuitPython.

Why CircuitPython?

CircuitPython is a variant of MicroPython, a very small version of Python that can fit on a microcontroller. Python is the fastest-growing programming language. It's taught in schools, used in coding bootcamps, popular with scientists and of course programmers at companies use it a lot!

CircuitPython adds the Circuit part to the Python part. Letting you program in Python and talk to Circuitry like sensors, motors, and LEDs!

CircuitPython on Microcontrollers

For a couple years now we've had CircuitPython for microcontrollers like our SAMD21 series with Feather/Trinket/CircuitPlayground/Metro M0, as well as the ESP8266 WiFi microcontroller, nRF52 bluetooth microcontroller and SAMD51 series.

All of these chips have something in common - they are microcontrollers with hardware peripherals like SPI, I2C, ADCs etc. We squeeze Python into 'em and can then make the project portable.

But...sometimes you want to do more than a microcontroller can do. Like HDMI video output, or camera capture, or serving up a website, or just something that takes more memory and computing than a microcontroller board can do...

CircuitPython Libraries on Linux & Google Coral

The next obvious step is to bring CircuitPython ease of use back to 'desktop Python'. We've got tons of projects, libraries and example code for CircuitPython on microcontrollers, and thanks to the flexibility and power of Python its pretty easy to get it working with micro-computers like Google Coral or other 'Linux with GPIO pins available' single board computers.

We'll use a special library called adafruit_blinka (named after Blinka, the CircuitPython mascot) to provide the layer that translates the CircuitPython hardware API to whatever library the Linux board provides. For example, on Coral we use the python libgpiod bindings. For any I2C interfacing we'll use ioctl messages to the /dev/i2c device. For SPI we'll use the spidev python library, etc. These details don't matter so much because they all happen underneath the adafruit_blinka layer.

The upshot is that any code we have for CircuitPython will be instantly and easily runnable on Linux computers like Google Coral.

In particular, we'll be able to use all of our device drivers - the sensors, led controllers, motor drivers, HATs, bonnets, etc. And nearly all of these use I2C or SPI!

Wait, isn't there already something that does this - Periphery?

Periphery is a pure python hardware interface class for Coral, it works just fine for I2C, SPI and GPIO but  doesn't work with our drivers as its a different API

By letting you use CircuitPython libraries on Raspberry Pi via adafruit_blinka, you can unlock all of the drivers and example code we wrote! And you can keep using periphery if you like. We save time and effort so we can focus on getting code that works in one place, and you get to reuse all the code we've written already.

What about other Linux SBCs?

Yep! Blinka can easily be updated to add other boards. We've started with the one we've got, so we could test it thoroughly. If you have other SBC board you'd like to adapt check out the adafruit_blinka code on github, pull requests are welcome as there's a ton of different Linux boards out there!

Your Coral dev board comes blank, and will need to be flashed in order to load the firmware on. The process involves flashing a runtime image onto an SD card and once it boots, the runtime flashes the board with a system image.

The Coral Getting Started guide will show you the process. It's not pleasant unless you happen to have all the right cables and software already, it should take you around 15 minutes.

You'll need USB C cables and adapters!

When connecting HATs or Bonnets, the tall heatsink of the Coral can interfere with attaching it - be sure to pick up some 2x20 GPIO Lifters or Stacking headers!

Once you've got the Coral flashed, you will be able to set up and test WiFi:

Verify you have a WiFi connection with sudo ping 8.8.8.8

The good news about the mendel distribution is it already has Python3 installed by default

Install libgpiod

libgpiod is what we use for gpio toggling. To install run this command:

After installation you should be able to import gpiod from within Python3

Update Your Board and Python

Run the standard updates:

and

Check UART, I2C and SPI

A vast number of our CircuitPython drivers use UART, I2C and SPI for interfacing. Luckily, they're already enabled. Check by running ls /dev/i2c* /dev/spi*

Install the support software with

You can get info about the I2C interfaces with sudo i2cdetect -l

You can test to see what I2C addresses are connected by running sudo i2cdetect -y 0 (internal I2C) or sudo i2cdetect -y 1 (pins #3 and #5) and sudo i2cdetect -y 1 (pins #27 and #28)

You'll note there looks like an RTC on address 0x68 (a common RTC address). Some addresses are pre-allocated by the kernel (unavailable UU)

For the GPIO interface chips, you can check with sudo gpiodetect and sudo gpioinfoto see the 5 32-pin busses

To enable UART1, you can use the following command:

Install Python libraries

Now you're ready to install all the python support

Run the following command to install adafruit_blinka

The computer will install a few different libraries such as adafruit-pureio (our ioctl-only i2c library), spidev (for SPI interfacing), Adafruit-GPIO (for detecting your board) and of course adafruit-blinka

That's pretty much it! You're now ready to test.

Create a new file called blinkatest.py with nano or your favorite text editor and put the following in:

Save it and run at the command line with

You should see the following, indicating digital i/o, I2C and SPI all worked

The first step with any new hardware is the 'hello world' of electronics - blinking an LED. This is very easy with CircuitPython and Coral. We'll extend the example to also show how to wire up a button/switch.

Coral Dev Board Pinout

Note that the GPIO pins on the Coral roughly correspond to the Raspberry Pi GPIO

Similarities:

• 5V, 3.3V and GND pins are all in the same locations
• Main I2C port is on pins #3 and #5
• Main SPI port is on pins #19, 21, 23, 24 and 26
• Main UART port is on pins #8 and #10 note that this is shared with the console so you will conflict with the built in serial console unless you disable the console on these pins
• I2S is available on same pins as Raspberry Pi

Differences:

• There's a UART3 on pins #7 and #11 but these don't seem to be available (/dev/ttymxc2 does not exist) so these pins cannot be used for GPIO
• I2S is enabled by default so you cannot use pins #12, 35, 38, 40 for GPIO
• PWM is enabled on pins #15, #32 and #33 so these pins cannot be used for GPIO but you can use them to create PWM outputs
• The secondary I2C port is available for you to use (pins #27 and #28)
• Raspberry Pi GPIO #22 is known as GPIO_P13
• Raspberry Pi GPIO #23 is known as GPIO_P16 (output only)
• Raspberry Pi GPIO #24 is known as GPIO_P18
• Raspberry Pi GPIO #25 is known as GPIO_P22
• Raspberry Pi GPIO #5 is known as GPIO_P29
• Raspberry Pi GPIO #6 is known as GPIO_P31
• Raspberry Pi GPIO #16 is known as GPIO_P36
• Raspberry Pi GPIO #26 is known as GPIO_P37 (output only)

Parts Used

Any old LED will work just fine as long as its not an IR LED (you can't see those) and a 470 to 2.2K resistor

Some tactile buttons or switches

We recommend using a breadboard and some female-male wires.

You can use a Cobbler to make this a little easier, the pins will be labeled according to Raspberry Pi names so just check the Coral names!

Wiring

Connect the Coral Ground pin to the blue ground rail on the breadboard.

• Connect one side of the tactile switch to Coral GPIO_P13
  
• Connect a ~10K pull up resistor from GPIO_P13 to 3.3V
• Connect the other side of the tactile switch to the ground rail
• Connect the longer/positive pin of the LED to Coral GPIO_P16
• Connect the shorter/negative pin of the LED to a 470ohm  to 2.2K resistor, the other side of the resistor goes to ground rail

There's no Coral Fritzing object, so we sub'd a Raspberry Pi in

Double-check you have the right wires connected to the right location, it can be tough to keep track of pins as there are forty of them!

No additional libraries are needed so we can go straight on to the example code

However, we recommend running a pip3 update!

pip3 install --upgrade adafruit_blinka

Blinky Time!

The finish line is right up ahead, lets start with an example that blinks the LED on and off once a second (half a second on, half a second off):

Verify the LED is blinking. If not, check that it's wired to GPIO #16, the resistor is installed correctly, and you have a Ground wire to the Coral.

Type Control-C to quit

Button It Up

Now that you have the LED working, lets add code so the LED turns on whenever the button is pressed

Press the button - see that the LED lights up!

Type Control-C to quit

Some Linux boards, like the Coral, have PWM outputs. You can use these to pulse LEDs to dim them, or color mix, control motor speeds with a motor driver, or even hobby servos!

Supported Pins

The Coral only has 3 PWM pins:

• Pin #33 is PWM1
• Pin #32 is PWM2
• Pin #15  is PWM3

These are independent PWM outputs, each can have a different frequency and duty cycle

You can check that the 3 PWM's are enabled with ls /sys/class/pwm/

PWM with Fixed Frequency - LEDs

This example will show you how to use PWM to fade an LED.

Wire up an LED like before, but this time to PWM3 and GND

Double-check you have the right wires connected to the right location, it can be tough to keep track of pins as there are forty of them!

No additional libraries are needed so we can go straight on to the example code

However, we recommend running a pip3 update!

pip3 install --upgrade adafruit-blinka

Verify the LED is blinking. If not, check that it's wired to GPIO #15, the resistor is installed correctly, and you have a Ground wire to the Coral.

Type Control-C to quit

Servo Control

In order to use servos, we take advantage of pwmio. Now, in theory, you could just use the raw pwmio calls to set the frequency to 50 Hz and then set the pulse widths. But we would rather make it a little more elegant and easy!

So, instead we will use adafruit_motor which manages servos for you quite nicely

Install it with pip3 install adafruit-circuitpython-motor

The PWM output from the Coral is only 2.5V peak, and not very strong, so you need to buffer it, we recommend using an HC4050 or similar low cost level shifter/buffer. Wire VCC and GND to 5V and GND on the Coral, and then the PWM output goes into one of the 6 inputs of the '4050.

• Connect the servo's brown or black ground wire to ground
• Connect the servo's red power wire to 5V power, USB power is good for a servo or two. For more than that, you'll need an external battery pack. Do not use 3.3V for powering a servo!
• Connect the servo's yellow or white signal wire to the control/data pin. In this case we're using the shifted PWM3

PWM Output with Variable Frequency - Buzzers

This example will show you how to beep a piezo buzzer at different PWM frequencies

Connect a common Piezo buzzer to PWM3 and GND. Don't connect a speaker unless you have an amplifier - the pins on the Coral can only drive small buzzers!

If you want to make lots of tones, we recommend using the tone helper functions in simpleio

Install it with pip3 install adafruit-circuitpython-simpleio and then follow this guide page

The output of the PWM pins isn't very strong, so if you want louder beeps, use the '4050 level shifting arrangement above

The most popular electronic sensors use I2C to communicate. This is a 'shared bus' 2 wire protocol, you can have multiple sensors connected to the two SDA and SCL pins as long as they have unique addresses (check this guide for a list of many popular devices and their addresses)

Lets show how to wire up a popular BME280. This sensor provides temperature, barometric pressure and humidity data over I2C

We're going to do this in a lot more depth than our guide pages for each sensor, but the overall technique is basically identical for any and all I2C sensors.

Honestly, the hardest part of using I2C devices is figuring out the I2C address and which pin is SDA and which pin is SCL!

Parts Used

We recommend using a breadboard and some female-male wires.

You can use a Cobbler to make this a little easier, the pins are then labeled!

Wiring

• Connect the Coral 3.3V power pin to Vin
• Connect the Coral GND pin to GND
• Connect the Pi SDA pin to the BME280 SDI
• Connect the Pi SCL pin to to the BME280 SCK

Double-check you have the right wires connected to the right location, it can be tough to keep track of Pi pins as there are forty of them!

After wiring, we recommend running I2C detection with sudo i2cdetect -y 1 to verify that you see the device, in this case its address 77

Install the CircuitPython BME280 Library

OK onto the good stuff, you can now install the Adafruit BME280 CircuitPython library.

As of this writing, not all libraries are up on PyPI so you may want to search before trying to install. Look for circuitpython and then the driver you want.

(If you don't see it you can open up a github issue on circuitpython to remind us!)

Once you know the name, install it with

pip3 install adafruit-circuitpython-bme280

You'll notice we also installed a dependancy called adafruit-circuitpython-busdevice. This is a great thing about pip, if you have other required libraries they'll get installed too!

We also recommend an adafruit-blinka update in case we've fixed bugs:

pip3 install --upgrade adafruit_blinka

Run that code!

The finish line is right up ahead. You can now run one of the (many in some cases) example scripts we've written for you.

Check out the examples for your library by visiting the repository for the library and looking in the example folder. In this case, it would be https://github.com/adafruit/Adafruit_CircuitPython_BME280/tree/master/examples

Save this code to your Pi by copying and pasting it into a text file, downloading it directly from the Pi, etc.

Then in your command line run

python3 bme280_simpletest.py

The code will loop with the sensor data until you quit with a Control-C

That's it! Now if you want to read the documentation on the library, what each function does in depth, visit our readthedocs documentation at

https://circuitpython.readthedocs.io/projects/bme280/en/latest/

SPI is less popular than I2C but still you'll see lots of sensors and chips use it. Unlike I2C, you don't have everything share two wires. Instead, there's three shared wires (clock, data in, data out) and then a unique 'chip select' line for each chip.

The nice thing about SPI is you can have as many chips as you like, even the same kind, all share the three SPI wires, as long as each one has a unique chip select pin.

The formal/technical names for the 4 pins used are:

• SPI clock - called SCLK, SCK or CLK
• SPI data out - called MOSI for Microcomputer Out Serial In. This is the wire that takes data from the Linux computer to the sensor/chip. Sometimes marked SDI or DI on chips
• SPI data in - called MISO for Microcomputer In Serial Out. This is the wire that takes data to the Linux computer from the sensor/chip. Sometimes marked SDO or DO on chips
• SPI chip select - called CS or CE or SS

Remember, connect all SCK, MOSI and MISO pins together (unless there's some specific reason/instruction not to) and a unique CS pin for each device.

SPI on microcontrollers is fairly simple, you have an SPI peripheral and you can transfer data on it with some low level command. Its 'your job' as a programmer to control the CS lines with a GPIO. That's how CircuitPython is structured as well. busio does just the SPI transmit/receive part and busdevice handles the chip select pin as well.

Linux, on the other hand, doesn't let you send data to SPI without a CS line, and the CS lines are fixed in hardware as well. For example on the Coral, there's two CS pins available for the hardware SPI pins - ESPI1_SS0 and ESPI1_SS1 - and you have to use them. (In theory there's an ioctl option called no_cs but this does not actually work)

The upshot here is - to let you use more than 1 peripheral on SPI, we decided to let you use any CS pins you like, CircuitPython will toggle it the way you expect. But when we transfer SPI data we always tell the kernel to use ESPI1_SS0. ESPI1_SS0 will toggle like a CS pin, but if we leave it disconnected, its no big deal

The upshot here is basically never connect anything to ESPI1_SS0. Use whatever chip select pin you define in CircuitPython and just leave the ESPI1_SS0 pin alone, it will toggle as if it is the chip select line, completely on its own, so you shouldn't try to use it as a digital input/output/whatever.

Parts Used

OK now that we've gone thru the warning, lets wire up an SPI MAX31855 thermocouple sensor, this particular device doesn't have a MOSI pin so we'll not connect it.

We recommend using a breadboard and some female-male wires.

You can use a Cobbler to make this a little easier, the pins are then labeled!

Wiring

• Connect the Coral 3.3V power pin to Vin
• Connect the Coral GND pin to GND
• Connect the Coral SCLK pin to the MAX31855 CLK
• Connect the Coral MISO pin to to the MAX31855 DO
• Connect the Coral GPIO_P29 pin to to the MAX31855 CS

Double-check you have the right wires connected to the right location, it can be tough to keep track of Pi pins as there are forty of them!

Install the CircuitPython MAX31855 Library

OK onto the good stuff, you can now install the Adafruit MAX31855 CircuitPython library.

As of this writing, not all libraries are up on PyPI so you may want to search before trying to install. Look for circuitpython and then the driver you want.

(If you don't see it you can open up a github issue on circuitpython to remind us!)

Once you know the name, install it with

pip3 install adafruit-circuitpython-max31855

You'll notice we also installed a few other dependancies called spidev, adafruit-pureio, adafruit-circuitpython-busdevice and more. This is a great thing about pip, if you have other required libraries they'll get installed too!

We also recommend an adafruit-blinka update in case we've fixed bugs:

pip3 install --upgrade adafruit_blinka

Run that code!

The finish line is right up ahead. You can now run one of the (many in some cases) example scripts we've written for you.

Check out the examples for your library by visiting the repository for the library and looking in the example folder. In this case, it would be https://github.com/adafruit/Adafruit_CircuitPython_MAX31855/tree/master/examples

As of this writing there's only one example. But that's cool, here it is:

Save this code to your Coral by copying and pasting it into a text file, downloading it directly from the Coral, etc.

Change the line that says

cs = digitalio.DigitalInOut(board.D5)

to

cs = digitalio.DigitalInOut(board.GPIO_P29)

Then in your command line run

python3 max31855_simpletest.py

The code will loop with the sensor data until you quit with a Control-C

That's it! Now if you want to read the documentation on the library, what each function does in depth, visit our readthedocs documentation at

https://circuitpython.readthedocs.io/projects/max31855/en/latest/

After I2C and SPI, the third most popular "bus" protocol used is serial (also sometimes referred to as 'UART'). This is a non-shared two-wire protocol with an RX line, a TX line and a fixed baudrate. The most common devices that use UART are GPS units, MIDI interfaces, fingerprint sensors, thermal printers, and a scattering of sensors.

One thing you'll notice fast is that most linux computers have minimal UARTs, often only 1 hardware port. And that hardware port may be shared with a console.

There are two ways to connect UART / Serial devices to your Coral. With a USB adapter and via the onboard pins

We'll demonstrate wiring up & using an Ultimate GPS with both methods

The Easy Way - An External USB-Serial Converter

By far the easiest way to add a serial port is to use a USB to serial converter cable or breakout. They're not expensive, and you simply plug it into the USB port. On the other end are wires or pins that provide power, ground, RX, TX and maybe some other control pads or extras.

Here are some options, they have varying chipsets and physical designs but all will do the job. We'll list them in order of recommendation.

The first cable is easy to use and even has little plugs that you can arrange however you like, it contains a CP2102

The CP2104 Friend is low cost, easy to use, but requires a little soldering, it has an '6-pin FTDI compatible' connector on the end, but all pins are broken out the sides

Both the FTDI friend and cable use classic FTDI chips, these are more expensive than the CP2104 or PL2303 but sometimes people like them!

You can wire up the GPS by connecting the following

• GPS Vin  to USB 5V or 3V (red wire on USB console cable)
• GPS Ground to USB Ground (black wire)
• GPS RX to USB TX (green wire)
• GPS TX to USB RX (white wire)

Once the USB adapter is plugged in, you'll need to figure out what the serial port name is. You can figure it out by unplugging-replugging in the USB and then typing dmesg | tail -10 (or just dmesg) and looking for text like this:

At the bottom, you'll see the 'name' of the attached device, in this case its ttyUSB0, that means our serial port device is available at /dev/ttyUSB0

The Hard Way - Using Built-in UART

If you don't want to plug in external hardware to the Coral you can use the built in UART on the RX/TX pins. 

Like the Raspberry Pi the Coral uses the RX/TX pins for a console, so this isn't recommended because you will conflict with the built in UART console!

You can use the built in UART via /dev/ttymxc0

Wire the GPS as follows:

Install the CircuitPython GPS Library

OK onto the good stuff, you can now install the Adafruit GPS CircuitPython library.

As of this writing, not all libraries are up on PyPI so you may want to search before trying to install. Look for circuitpython and then the driver you want.

(If you don't see it you can open up a github issue on circuitpython to remind us!)

Once you know the name, install it with

pip3 install pyserial adafruit-circuitpython-gps

You'll notice we also installed a dependancy called pyserial. This is a great thing about pip, if you have other required libraries they'll get installed too!

We also recommend an adafruit-blinka update in case we've fixed bugs:

pip3 install --upgrade adafruit_blinka

Run that code!

The finish line is right up ahead. You can now run one of the (many in some cases) example scripts we've written for you.

Check out the examples for your library by visiting the repository for the library and looking in the example folder. In this case, it would be https://github.com/adafruit/Adafruit_CircuitPython_GPS/tree/master/examples

Lets start with the simplest, the echo example

We'll need to configure this code to work with our UART port name.

• If you're using a USB-to-serial converter, the device name is probably /dev/ttyUSB0 - but check dmesg to make sure
• If you're using the built-in UART on the Coral, the device name is /dev/ttymxc0

Comment out the lines that reference board.TX, board.RX and busio.uart and uncomment the lines that import serial and define the serial device, like so:

And update the "/dev/ttyUSB0" device name if necessary to match your USB interface

Whichever method you use, you should see output like this, with $GP "NMEA sentences" - there probably wont be actual location data because you haven't gotten a GPS fix. As long as you see those $GP strings sorta like the below, you've got it working!

That's just a taste of what we've got working so far

We're adding more support constantly, so please hold tight and visit the adafruit_blinka github repo to share your feedback and perhaps even submit some improvements!

ToDo's

• There's no documentation on how to enable UART3 - waiting on Google to publish info
• There's no documentation on how to disable the console to free up UART1 - waiting on Google to publish info