CircuitPython on Linux & Orange Pi

The next obvious step is to bring CircuitPython 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 Orange Pi 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 Orange Pi 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 Orange Pi.

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 - WiringOP?

WiringOP, a modification of WiringPi, is for GPIO usage only, it doesn't work well for various I2C or SPI devices.

By letting you use CircuitPython on Raspberry Pi via adafruit_blinka, you can unlock all of the drivers and example code we wrote! And you can keep using WiringOP for pins, buttons and LEDs. 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 or other Orange Pi's?

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 an OrangePi or 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!

Once armbian is installed, its easy to tell what board you have, simply cat /etc/armbian-release and look for BOARD_NAME

Install ARMbian on your Orange Pi

We're only going to be using armbian, other distros could be made to work but you'd probably need to figure out how to detect the platform since we rely on /etc/armbian-release existing.

Download and install the latest armbian, for example we're using https://www.armbian.com/orange-pi-pc-plus/

There's some documentation to get started at https://docs.armbian.com/User-Guide_Getting-Started/

Logging in

Once installed, you may want to enable mdns so you can ssh [email protected] instead of needing to know the IP address:

• sudo apt-get install avahi-daemon

then reboot

Install Python and set Python 3 to Default

There's a few ways to do this, we recommend something like this

Of course change the version numbers if newer Python is distributed

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:

sudo apt-get update

sudo apt-get upgrade

and

sudo pip3 install --upgrade setuptools

Update all your python 3 packages with

pip3 freeze - local | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip3 install -U

and

sudo bash

pip3 freeze - local | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip3 install -U

Enable UART, I2C and SPI

A vast number of our CircuitPython drivers use UART, I2C and SPI for interfacing so you'll want to get those enabled.

You only have to do this once per board but by default all three interfaces are disabled!

Edit /boot/armbianEnv.txt and add these lines at the end, adjusting the overlay_prefix for your particular board

overlay_prefix=sun8i-h3
overlays=uart3 i2c0 spi-spidev
param_spidev_spi_bus=0


Once you're done with both and have rebooted, verify you have the I2C and SPI devices with the command ls /dev/i2c* /dev/spi*

You should see at least one i2c device and one spi device

You can also install WiringOP and then run gpio readall to see the MUX status. If you see ALT3 next to a pin, its a plain GPIO. If you see ALT4 or ALT5, its an SPI/I2C/UART peripheral

Install Python libraries

Now you're ready to install all the python support

Run the following command to install adafruit_blinka

pip3 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

sudo python3 blinkatest.py

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

Once armbian is installed, its easy to tell what board you have, simply cat /etc/armbian-release and look for BOARD_NAME

Install ARMbian on your Orange Pi

We're only going to be using armbian, other distros could be made to work but you'd probably need to figure out how to detect the platform since we rely on /etc/armbian-release existing.

Download and install the latest armbian, for example we're using https://www.armbian.com/orange-pi-r1/

There's some documentation to get started at https://docs.armbian.com/User-Guide_Getting-Started/

Connecting the GPIO/Debug Header

Because the Orange Pi R1 does not come with any GPIO headers, you will need to solder one in order to connect breakout boards.

Logging in using Serial

To log in through serial, you will need to connect a USB to TTL Serial cable up to the Orange Pi. You may also need to install some software. Be sure to check out our Adafruit's Raspberry Pi Lesson 5. Using a Console Cable guide. Although it is written for a Raspberry Pi, the drivers and cable connection should be the same.

Once installed, you may want to enable mDNS so you can ssh [email protected] instead of needing to know the IP address:

• sudo apt-get install avahi-daemon

then reboot

Connecting using DHCP and SSH

Another option that you may be available to you is to connect using SSH, or Secure Shell. To connect, you will need to have DHCP, or Dynamic Host Configuration Protocol, enabled and configured on your network and look up the IP address assigned to the Orange Pi R1.

By default, most routers have DHCP enabled and some routers will display all of the hosts connected to them through the web configuration panel. If you are able to retrieve the IP address, then you can connect through SSH.

MacOS/Linux

Mac and Linux should have SSH installed by default and you can access it by going to the command line and typing ssh [email protected]if the IP address of your Orange Pi is 192.168.0.25.

Windows

The easiest way to connect with windows is to use a Terminal program called PuTTY from https://www.putty.org.

You can read more about connecting through SSH in our Adafruit's Raspberry Pi Lesson 6. Using SSH guide. Although this is written for Raspberry Pi, the steps should be the same.

Set your Python install to Python 3 Default

There's a few ways to do this, we recommend something like this

Of course change the version numbers if newer Python is distributed

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

Install Required pip3 Modules

For the Orange Pi R1, a couple of pip modules are required to smooth out the installation.

Run the following command.

sudo pip3 install wheel flask

Update Your Board and Python

Run the standard updates:

sudo apt-get update

sudo apt-get upgrade

and

sudo pip3 install --upgrade setuptools

Update all your python 3 packages with

pip3 freeze - local | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip3 install -U

and

sudo bash

pip3 freeze - local | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip3 install -U

Enable UART, I2C and SPI

A vast number of our CircuitPython drivers use UART, I2C and SPI for interfacing so you'll want to get those enabled.

You only have to do this once per board but by default all three interfaces are disabled!

Edit /boot/armbianEnv.txt and add these lines at the end, adjusting the overlay_prefix for your particular board

overlay_prefix=sun8i-h3
overlays=uart1 i2c0 spi-spidev usbhost2 usbhost3
param_spidev_spi_bus=1

Once you're done with both and have rebooted, verify you have the I2C and SPI devices with the command ls /dev/i2c* /dev/spi*

You should see at least one i2c device and one spi device

You can also install WiringOP-Zero and then run gpio readall to see the MUX status. If you see ALT3 next to a pin, it's a plain GPIO. If you see ALT4 or ALT5, its an SPI/I2C/UART peripheral

Install Python libraries

Now you're ready to install all the python support

Run the following command to install adafruit_blinka

sudo pip3 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

sudo python3 blinkatest.py

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 Orange Pi. We'll extend the example to also show how to wire up a button/switch.

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 Orange Pi name!

Wiring

Connect the Orange Pi Ground pin to the blue ground rail on the breadboard.

• Connect one side of the tactile switch to Orange Pi GPIO PA6
• Connect a ~10K pull up resistor from PA6 to 3.3V
• Connect the other side of the tactile switch to the ground rail
• Connect the longer/positive pin of the LED to Orange Pi GPIO PD14
• 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 Orange Pi PC 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 Pi 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 PD14, the resistor is installed correctly, and you have a Ground wire to the Orange Pi.

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

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 Orange Pi 3.3V power pin to Vin
• Connect the Orange Pi 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 0 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

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

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 Microcontroller 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 Microcontroller 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

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 Orange Pi PC, there's only one CS pins available for the hardware SPI pins - SPI_CS known as PC3 - and you have to use it. (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 SPI_CS. SPI_CS 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 SPI_CS. Use whatever chip select pin you define in CircuitPython and just leave the CS 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 Orange Pi 3.3V power pin to Vin
• Connect the Orange Pi GND pin to GND
• Connect the Pi SCLK pin to the MAX31855 CLK
• Connect the Pi MISO pin to to the MAX31855 DO
• Connect the Pi GPIO PA7 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 Pi by copying and pasting it into a text file, downloading it directly from the Pi, etc.

Change the line that says

cs = digitalio.DigitalInOut(board.D5)

to

cs = digitalio.DigitalInOut(board.PA7)

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 Orange Pi. The easy way, and the hard way.

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 Pi you can use the built in UART on the RX/TX pins. Unlike the Raspberry Pi, the Orange Pi isn't using the RX/TX pins for a console, those are on a different UART peripheral, so as long as you've activated UART3 (see the Install page) you should be good to go!

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

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 Orange Pi PC, the device name is /dev/ttyS3

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!