CircuitPython Libraries on Linux & 96Boards DragonBoard

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 microcomputers like the DragonBoard 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 the DragonBoard we use the python libgpiod bindings. For any I2C interfacing we'll use ioctl messages to the /dev/i2c device. 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 the DragonBoard.

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

libgpiod is a python hardware interface class that works on the DragonBoard. It works just fine for I2C, SPI and GPIO but doesn't work with our drivers as it's a different API

By letting you use CircuitPython libraries on the DragonBoard via adafruit_blinka, you can unlock all of the drivers and example code we wrote! And you can keep using libgpiod 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 ones we've got, so we could test them 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!

Install Linaro on your DragonBoard 410c

We decided to try getting Blinka running in Linaro Debian because that's the recommended Debian installation available for the DragonBoard410c. Other distros could be made to work but you'd probably need to figure out how to detect the platform. Using other operating systems and CircuitPython is your call, we cannot provide support for that.

Download and install the latest linaro, for example we're using https://www.96boards.org/documentation/consumer/dragonboard/dragonboard410c/downloads/debian.md.html

There's some documentation to get started at https://www.96boards.org/documentation/consumer/dragonboard/dragonboard410c/installation/

Preparing the Board

Logging in

We've found the easiest way to connect is through a console cable, wired to the UART Serial port through a logic level shifter, and then on your computer, use a serial monitor at 115200 baud.

Once installed, you may want to enable mdns so you can ssh pi@linaro-developer instead of needing to know the IP address. First you will need to update, then install:

• sudo apt update
• sudo apt install avahi-daemon

then reboot

Connecting to the Network

Before you can use your DragonBoard 410c, you will need to connect to a network. The DragonBoard 410c does not come with any ethernet ports, but there's still a couple of different options available. The first option is to get a USB hub with an ethernet line.

Connecting to WiFi

The other option is to connect to an access point with the onboard WiFi. 

To see a list of WiFi Access point SSIDs, type:

nmcli dev wifi list

To connect to a WIFI access point, first create the connection, replacing YOUR_SSID with your WiFi name:

nmcli con add con-name WiFi ifname wlan0 type wifi ssid YOUR_SSID

Then set up the password for your access point by enabling WPA PSK. Change this to the appropriate type if your connection is different.

nmcli con modify WiFi wifi-sec.key-mgmt wpa-psk

And add your password, replacing YOUR_PASSWORD with your WiFi password:

nmcli con modify WiFi wifi-sec.psk YOUR_PASSWORD

Finally enable the connection:

nmcli con up WiFi

You can check the connection status by typing:

nmcli connection show

Set your Python install to Python 3 Default

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

• sudo apt install -y python3 git python3-pip
• sudo update-alternatives --install /usr/bin/python python /usr/bin/python2.7 1
• sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.7 2
• sudo update-alternatives --config python

Of course, change the version numbers if a newer version of Python is distributed.

Update Your Board and Python

Run the standard updates:

sudo apt update

sudo apt upgrade

Choose UTF-8 for character set if prompted

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

Install libgpiod

libgpiod is what we use for gpio toggling. Fortunately it's available for the DragonBoard 410c. You can install it with the following command:

sudo apt install libgpiod2 python3-libgpiod gpiod

sudo apt install libgpiod2 python3-libgpiod gpiod

After installation, you should be able to import gpiod from within Python 3:

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, unfortunately by default the SPI interface is disabled!

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

The UART1 Serial Console on the DragonBoard 410c is connected to /dev/ttyMSM0. The UART1 GPIO Serial Port is connected to /dev/ttyMSM1.

Install Python Libraries

Now you're ready to install all the Python support.

Run the following command to install wheel and flask:

sudo pip3 install wheel flask

Next, 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),  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:

import board
import digitalio
import busio

print("Hello blinka!")

# Try to great a Digital input
pin = digitalio.DigitalInOut(board.GPIO_A)
print("Digital IO ok!")

# Try to create an I2C device
i2c = busio.I2C(board.SCL, board.SDA)
print("I2C ok!")

# Try to create an SPI device
spi = busio.SPI(board.SCLK, board.MOSI, board.MISO)
print("SPI ok!")

print("done!")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import board
import digitalio
import busio

print("Hello blinka!")

# Try to great a Digital input
pin = digitalio.DigitalInOut(board.GPIO_A)
print("Digital IO ok!")

# Try to create an I2C device
i2c = busio.I2C(board.SCL, board.SDA)
print("I2C ok!")

# Try to create an SPI device
spi = busio.SPI(board.SCLK, board.MOSI, board.MISO)
print("SPI ok!")

print("done!")

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 DragonBoard410c. 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 it's not an IR LED (you can't see those) and a 470 to 2.2K resistor

Some tactile buttons or switches:

Because the DragonBoard 410c uses 1.8V logic levels, you will need a logic level converter to interface with most peripherals.

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

Wiring

• Connect the DragonBoard Ground pin to the blue ground rail on the breadboard
• Connect the DragonBoard +5V pin to the red 5V rail on the breadboard.
• Connect the DragonBoard +1.8V pin to the LV pin on the Logic Level Converter
• Connect the HV pin on the Logic Level Converter to the 5V rail
• Connect the Ground pin on the Logic Level Converter to the blue ground rail on the breadboard 
• Connect one side of the tactile switch to the B1 pin on the Logic Level Converter
• Connect a ~10K pull up resistor from B1 to the 5V rail
• Connect the other side of the tactile switch to the ground rail
• Connect the longer/positive pin of the LED to the B2 pin on the Logic Level Converter
• 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
• Connect the DragonBoard GPIO_B pin (GPIO 12) to the A1 pin on the Logic Level Converter
• Connect the DragonBoard GPIO_A pin (GPIO 36) to the A2 pin on the Logic Level Converter

Double-check you have the right wires connected to the right location, it can be tough to keep track of GPIO 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!

sudo pip3 install --upgrade adafruit_blinka

Blinky Time!

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

import time
import board
import digitalio

print("hello blinky!")

led = digitalio.DigitalInOut(board.GPIO_A)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True
    time.sleep(0.5)
    led.value = False
    time.sleep(0.5)

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import time
import board
import digitalio

print("hello blinky!")

led = digitalio.DigitalInOut(board.GPIO_A)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True
    time.sleep(0.5)
    led.value = False
    time.sleep(0.5)

Verify the LED is blinking. If not, check that it's wired to the correct Logic Level Converter channel, that the Logic Level channel is connected to GPIO_A or GPIO_36, the resistor is installed correctly, and you have a Ground wire to the DragonBoard. Also, be sure to check the Power and Ground wires to the Logic Level Converter.

Type Control-C to quit

Button It Up

Now that you have the LED working, let's add code so the LED turns on whenever the button is pressed:

import time
import board
import digitalio

print("press the button!")

led = digitalio.DigitalInOut(board.GPIO_A)
led.direction = digitalio.Direction.OUTPUT

button = digitalio.DigitalInOut(board.GPIO_B)
button.direction = digitalio.Direction.INPUT
# use an external pullup since we don't have internal PU's
#button.pull = digitalio.Pull.UP

while True:
    led.value = not button.value # light when button is pressed!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import time
import board
import digitalio

print("press the button!")

led = digitalio.DigitalInOut(board.GPIO_A)
led.direction = digitalio.Direction.OUTPUT

button = digitalio.DigitalInOut(board.GPIO_B)
button.direction = digitalio.Direction.INPUT
# use an external pullup since we don't have internal PU's
#button.pull = digitalio.Pull.UP

while True:
    led.value = not button.value # light when 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

Because the DragonBoard 410c uses 1.8V logic levels, you will need a logic level converter to interface with most peripherals.

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

Wiring

• Connect the DragonBoard Ground pin to the ground on the Logic Level Converter
• Connect the DragonBoard +5V pin to the red 5V rail on the breadboard.
• Connect the DragonBoard +1.8V pin to the LV pin on the Logic Level Converter
• Connect the HV pin on the Logic Level Converter to the 5V rail
• Connect the Vin pin on the BME280 to the red 5V rail on the breadboard 
• Connect the Ground pin on the BME280 to the ground on the Logic Level Converter
• Connect the B1 pin on the Logic Level Converter to the BME280 SCK
• Connect the B2 pin on the Logic Level Converter to the BME280 SDI
• Connect the DragonBoard I2C0 SCL to the A1 pin on the Logic Level Converter
• Connect the DragonBoard I2C0 SDA to the A2 pin on the Logic Level Converter

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

After wiring, we recommend running I2C detection with sudo i2cdetect -r -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

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

sudo 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 two examples. Here's the first one:

import time

import board
import busio
import adafruit_bme280

# Create library object using our Bus I2C port
i2c = busio.I2C(board.SCLK, board.SDA)
bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c)

# OR create library object using our Bus SPI port
#spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
#bme_cs = digitalio.DigitalInOut(board.D10)
#bme280 = adafruit_bme280.Adafruit_BME280_SPI(spi, bme_cs)

# change this to match the location's pressure (hPa) at sea level
bme280.sea_level_pressure = 1013.25

while True:
    print("\nTemperature: %0.1f C" % bme280.temperature)
    print("Humidity: %0.1f %%" % bme280.humidity)
    print("Pressure: %0.1f hPa" % bme280.pressure)
    print("Altitude = %0.2f meters" % bme280.altitude)
    time.sleep(2)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import time

import board
import busio
import adafruit_bme280

# Create library object using our Bus I2C port
i2c = busio.I2C(board.SCLK, board.SDA)
bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c)

# OR create library object using our Bus SPI port
#spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
#bme_cs = digitalio.DigitalInOut(board.D10)
#bme280 = adafruit_bme280.Adafruit_BME280_SPI(spi, bme_cs)

# change this to match the location's pressure (hPa) at sea level
bme280.sea_level_pressure = 1013.25

while True:
    print("\nTemperature: %0.1f C" % bme280.temperature)
    print("Humidity: %0.1f %%" % bme280.humidity)
    print("Pressure: %0.1f hPa" % bme280.pressure)
    print("Altitude = %0.2f meters" % bme280.altitude)
    time.sleep(2)

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

Then in your command line run

sudo python3 bme280_simpletest.py

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

Here's the second example:

"""
Example showing how the BME280 library can be used to set the various
parameters supported by the sensor.
Refer to the BME280 datasheet to understand what these parameters do
"""
import time

import board
import busio
import adafruit_bme280

# Create library object using our Bus I2C port
i2c = busio.I2C(board.SCLK, board.SDA)
bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c)

# OR create library object using our Bus SPI port
#spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
#bme_cs = digitalio.DigitalInOut(board.D10)
#bme280 = adafruit_bme280.Adafruit_BME280_SPI(spi, bme_cs)

# change this to match the location's pressure (hPa) at sea level
bme280.sea_level_pressure = 1013.25
bme280.mode = adafruit_bme280.MODE_NORMAL
bme280.standby_period = adafruit_bme280.STANDBY_TC_500
bme280.iir_filter = adafruit_bme280.IIR_FILTER_X16
bme280.overscan_pressure = adafruit_bme280.OVERSCAN_X16
bme280.overscan_humidity = adafruit_bme280.OVERSCAN_X1
bme280.overscan_temperature = adafruit_bme280.OVERSCAN_X2
#The sensor will need a moment to gather inital readings
time.sleep(1)

while True:
    print("\nTemperature: %0.1f C" % bme280.temperature)
    print("Humidity: %0.1f %%" % bme280.humidity)
    print("Pressure: %0.1f hPa" % bme280.pressure)
    print("Altitude = %0.2f meters" % bme280.altitude)
    time.sleep(2)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

"""
Example showing how the BME280 library can be used to set the various
parameters supported by the sensor.
Refer to the BME280 datasheet to understand what these parameters do
"""
import time

import board
import busio
import adafruit_bme280

# Create library object using our Bus I2C port
i2c = busio.I2C(board.SCLK, board.SDA)
bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c)

# OR create library object using our Bus SPI port
#spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
#bme_cs = digitalio.DigitalInOut(board.D10)
#bme280 = adafruit_bme280.Adafruit_BME280_SPI(spi, bme_cs)

# change this to match the location's pressure (hPa) at sea level
bme280.sea_level_pressure = 1013.25
bme280.mode = adafruit_bme280.MODE_NORMAL
bme280.standby_period = adafruit_bme280.STANDBY_TC_500
bme280.iir_filter = adafruit_bme280.IIR_FILTER_X16
bme280.overscan_pressure = adafruit_bme280.OVERSCAN_X16
bme280.overscan_humidity = adafruit_bme280.OVERSCAN_X1
bme280.overscan_temperature = adafruit_bme280.OVERSCAN_X2
#The sensor will need a moment to gather inital readings
time.sleep(1)

while True:
    print("\nTemperature: %0.1f C" % bme280.temperature)
    print("Humidity: %0.1f %%" % bme280.humidity)
    print("Pressure: %0.1f hPa" % bme280.pressure)
    print("Altitude = %0.2f meters" % bme280.altitude)
    time.sleep(2)

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

Then in your command line run

sudo python3 bme280_normal_mode.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 DragonBoard 410c, there's only one CS pin available for the hardware SPI pins - SPI_CS - 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, let's wire up an SPI MAX31855 thermocouple sensor, this particular device doesn't have a MOSI pin so we'll not connect it.

Because the DragonBoard 410c uses 1.8V logic levels, you will need a logic level converter to interface with most peripherals.

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

Wiring

• Connect the DragonBoard Ground pin to the blue ground rail on the breadboard
• Connect the DragonBoard +5V pin to the red 5V rail on the breadboard.
• Connect the DragonBoard +1.8V pin to the LV pin on the Logic Level Converter
• Connect the HV pin on the Logic Level Converter to the MAX3185 3Vo
• Connect the Ground pin on the Logic Level Converter to the blue ground rail on the breadboard 
• Connect the Vin pin on the MAX31855 to the red 5V rail on the breadboard 
• Connect the Ground pin on the MAX31855 to the blue ground rail on the breadboard 
• Connect the B1 pin on the Logic Level Converter to the MAX31855 DO
• Connect the B2 pin on the Logic Level Converter to the MAX31855 CS
• Connect the B3 pin on the Logic Level Converter to the MAX31855 CLK
• Connect the DragonBoard SPI MISO to the A1 pin on the Logic Level Converter
• Connect the DragonBoard GPIO 12 to the A2 pin on the Logic Level Converter
• Connect the DragonBoard SPI CLK to the A3 pin on the Logic Level Converter

Double-check you have the right wires connected to the right location, it can be tough to keep track of Header 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

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

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

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time

import board
import digitalio

import adafruit_max31855

spi = board.SPI()
cs = digitalio.DigitalInOut(board.D5)

max31855 = adafruit_max31855.MAX31855(spi, cs)
while True:
    tempC = max31855.temperature
    tempF = tempC * 9 / 5 + 32
    print(f"Temperature: {tempC} C {tempF} F ")
    time.sleep(2.0)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time

import board
import digitalio

import adafruit_max31855

spi = board.SPI()
cs = digitalio.DigitalInOut(board.D5)

max31855 = adafruit_max31855.MAX31855(spi, cs)
while True:
    tempC = max31855.temperature
    tempF = tempC * 9 / 5 + 32
    print(f"Temperature: {tempC} C {tempF} F ")
    time.sleep(2.0)

Save this code to your DragonBoard 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.GPIO_12)

Then in your command line run

sudo 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 DragonBoard. 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!

There is also a GPS module with integrated serial available which works like the GPS breakout connected to the USB to TTL Serial cable.

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 DragonBoard you can use the built in UART on the RX/TX pins. Unlike the Raspberry Pi, the DragonBoard isn't using the RX/TX pins for a console, those are on a different UART peripheral, so you should be good to go!

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

Wire the GPS as follows:

• Connect the DragonBoard Ground pin to the blue ground rail on the breadboard
• Connect the DragonBoard +5V pin to the red 5V rail on the breadboard.
• Connect the DragonBoard +1.8V pin to the LV pin on the Logic Level Converter
• Connect the HV pin on the Logic Level Converter to the red 5V rail
• Connect the Ground pin on the Logic Level Converter to the blue ground rail on the breadboard 
• Connect the Vin pin on the GPS to the red 5V rail on the breadboard 
• Connect the Ground pin on the GPS to the blue ground rail on the breadboard 
• Connect the B1 pin on the Logic Level Converter to the GPS RX pin
• Connect the B2 pin on the Logic Level Converter to the GPS TX pin
• Connect the DragonBoard UART0 TX to the A1 pin on the Logic Level Converter
• Connect the DragonBoard UART0 RX to the A2 pin on the Logic Level Converter

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

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

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

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

# Simple GPS module demonstration.
# Will print NMEA sentences received from the GPS, great for testing connection
# Uses the GPS to send some commands, then reads directly from the GPS
import time

import board
import busio

import adafruit_gps

# Create a serial connection for the GPS connection using default speed and
# a slightly higher timeout (GPS modules typically update once a second).
# These are the defaults you should use for the GPS FeatherWing.
# For other boards set RX = GPS module TX, and TX = GPS module RX pins.
uart = busio.UART(board.TX, board.RX, baudrate=9600, timeout=10)

# for a computer, use the pyserial library for uart access
# import serial
# uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=10)

# If using I2C, we'll create an I2C interface to talk to using default pins
# i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller

# Create a GPS module instance.
gps = adafruit_gps.GPS(uart)  # Use UART/pyserial
# gps = adafruit_gps.GPS_GtopI2C(i2c)  # Use I2C interface

# Initialize the GPS module by changing what data it sends and at what rate.
# These are NMEA extensions for PMTK_314_SET_NMEA_OUTPUT and
# PMTK_220_SET_NMEA_UPDATERATE but you can send anything from here to adjust
# the GPS module behavior:
#   https://cdn-shop.adafruit.com/datasheets/PMTK_A11.pdf

# Turn on the basic GGA and RMC info (what you typically want)
gps.send_command(b"PMTK314,0,1,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0")
# Turn on just minimum info (RMC only, location):
# gps.send_command(b'PMTK314,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0')
# Turn off everything:
# gps.send_command(b'PMTK314,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0')
# Tuen on everything (not all of it is parsed!)
# gps.send_command(b'PMTK314,1,1,1,1,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0')

# Set update rate to once a second (1hz) which is what you typically want.
gps.send_command(b"PMTK220,1000")
# Or decrease to once every two seconds by doubling the millisecond value.
# Be sure to also increase your UART timeout above!
# gps.send_command(b'PMTK220,2000')
# You can also speed up the rate, but don't go too fast or else you can lose
# data during parsing.  This would be twice a second (2hz, 500ms delay):
# gps.send_command(b'PMTK220,500')

# Main loop runs forever printing data as it comes in
timestamp = time.monotonic()
while True:
    data = gps.read(32)  # read up to 32 bytes
    # print(data)  # this is a bytearray type

    if data is not None:
        # convert bytearray to string
        data_string = "".join([chr(b) for b in data])
        print(data_string, end="")

    if time.monotonic() - timestamp > 5:
        # every 5 seconds...
        gps.send_command(b"PMTK605")  # request firmware version
        timestamp = time.monotonic()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

# Simple GPS module demonstration.
# Will print NMEA sentences received from the GPS, great for testing connection
# Uses the GPS to send some commands, then reads directly from the GPS
import time

import board
import busio

import adafruit_gps

# Create a serial connection for the GPS connection using default speed and
# a slightly higher timeout (GPS modules typically update once a second).
# These are the defaults you should use for the GPS FeatherWing.
# For other boards set RX = GPS module TX, and TX = GPS module RX pins.
uart = busio.UART(board.TX, board.RX, baudrate=9600, timeout=10)

# for a computer, use the pyserial library for uart access
# import serial
# uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=10)

# If using I2C, we'll create an I2C interface to talk to using default pins
# i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller

# Create a GPS module instance.
gps = adafruit_gps.GPS(uart)  # Use UART/pyserial
# gps = adafruit_gps.GPS_GtopI2C(i2c)  # Use I2C interface

# Initialize the GPS module by changing what data it sends and at what rate.
# These are NMEA extensions for PMTK_314_SET_NMEA_OUTPUT and
# PMTK_220_SET_NMEA_UPDATERATE but you can send anything from here to adjust
# the GPS module behavior:
#   https://cdn-shop.adafruit.com/datasheets/PMTK_A11.pdf

# Turn on the basic GGA and RMC info (what you typically want)
gps.send_command(b"PMTK314,0,1,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0")
# Turn on just minimum info (RMC only, location):
# gps.send_command(b'PMTK314,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0')
# Turn off everything:
# gps.send_command(b'PMTK314,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0')
# Tuen on everything (not all of it is parsed!)
# gps.send_command(b'PMTK314,1,1,1,1,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0')

# Set update rate to once a second (1hz) which is what you typically want.
gps.send_command(b"PMTK220,1000")
# Or decrease to once every two seconds by doubling the millisecond value.
# Be sure to also increase your UART timeout above!
# gps.send_command(b'PMTK220,2000')
# You can also speed up the rate, but don't go too fast or else you can lose
# data during parsing.  This would be twice a second (2hz, 500ms delay):
# gps.send_command(b'PMTK220,500')

# Main loop runs forever printing data as it comes in
timestamp = time.monotonic()
while True:
    data = gps.read(32)  # read up to 32 bytes
    # print(data)  # this is a bytearray type

    if data is not None:
        # convert bytearray to string
        data_string = "".join([chr(b) for b in data])
        print(data_string, end="")

    if time.monotonic() - timestamp > 5:
        # every 5 seconds...
        gps.send_command(b"PMTK605")  # request firmware version
        timestamp = time.monotonic()

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 DragonBoard, the device name is /dev/ttyMSM1.

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:

# Define RX and TX pins for the board's serial port connected to the GPS.
# These are the defaults you should use for the GPS FeatherWing.
# For other boards set RX = GPS module TX, and TX = GPS module RX pins.
#RX = board.RX
#TX = board.TX

# Create a serial connection for the GPS connection using default speed and
# a slightly higher timeout (GPS modules typically update once a second).
#uart = busio.UART(TX, RX, baudrate=9600, timeout=3000)

# for a computer, use the pyserial library for uart access
import serial
uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=3000)

1
2
3
4
5
6
7
8
9
10
11
12
13

# Define RX and TX pins for the board's serial port connected to the GPS.
# These are the defaults you should use for the GPS FeatherWing.
# For other boards set RX = GPS module TX, and TX = GPS module RX pins.
#RX = board.RX
#TX = board.TX

# Create a serial connection for the GPS connection using default speed and
# a slightly higher timeout (GPS modules typically update once a second).
#uart = busio.UART(TX, RX, baudrate=9600, timeout=3000)

# for a computer, use the pyserial library for uart access
import serial
uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=3000)

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!