Adafruit Beaglebone IO Python API¶

The Adafruit Beaglebone IO API enables access to the Beaglebone’s GPIO, PWM, ADC, UART, SPI and eQEP hardware modules from Python programs.

`ADC` — A/D Converter input interface¶

This module enables reading analog input values from the analog to digital converter (ADC) on the TI AM3358 SoC on the BeagleBone.

Example:

import Adafruit_BBIO.ADC as ADC

ADC.setup()

# The read method returns normalized values from 0 to 1.0
value = ADC.read("P9_40")

# The read_raw returns non-normalized values from 0 to 4095
value = ADC.read_raw("P9_40")

Adafruit_BBIO.ADC.setup_adc()¶: Setup and start the ADC hardware.

Adafruit_BBIO.ADC.setup_read(channel)¶

Read the normalized analog value for the channel.

Parameters:	channel (str) – GPIO channel to read the value from (e.g. “P8_16”).
Returns:	normalized value reading from 0.0 to 1.0
Return type:	float

Adafruit_BBIO.ADC.setup_read_raw(channel)¶

Read the raw analog value for the channel.

Note:	Kernels older than 4.1.x returned a raw value range 0 - 1800 based on the reference voltage of 1.8 V.
Parameters:	channel (str) – GPIO channel to read the value from (e.g. “P8_16”).
Returns:	raw value reading from 0 to 4095 (12 bits).
Return type:	float

`Encoder` — Quadrature Encoder interface (eQEP)¶

Quadrature Encoder Pulse interface.

This module enables access to the enhanced Quadrature Encoder Pulse (eQEP) channels, which can be used to seamlessly interface with rotary encoder hardware.

The channel identifiers are available as module variables eQEP0, eQEP1, eQEP2 and eQEP2b.

Channel	Pin A	Pin B	Notes
eQEP0	P9.27	P9.92
eQEP1	P8.33	P8.35	Only available with video disabled
eQEP2	P8.11	P8.12	Only available with eQEP2b unused (same channel)
eQEP2b	P8.41	P8.42	Only available with video disabled and eQEP2 unused

Example

To use the module, you can connect a rotary encoder to your Beaglebone and then simply instantiate the RotaryEncoder class to read its position:

from Adafruit_BBIO.Encoder import RotaryEncoder, eQEP2

# Instantiate the class to access channel eQEP2, and initialize
# that channel
myEncoder = RotaryEncoder(eQEP2)

# Get the current position
cur_position = myEncoder.position

# Set the current position
next_position = 15
myEncoder.position = next_position

# Reset position to 0
myEncoder.zero()

# Change mode to relative (default is absolute)
# You can use setAbsolute() to change back to absolute
# Absolute: the position starts at zero and is incremented or
#           decremented by the encoder's movement
# Relative: the position is reset when the unit timer overflows.
myEncoder.setRelative()

# Read the current mode (0: absolute, 1: relative)
# Mode can also be set as a property
mode = myEncoder.mode

# Get the current frequency of update in Hz
freq = myEncoder.frequency

# Set the update frequency to 1 kHz
myEncoder.frequency = 1000

# Disable the eQEP channel
myEncoder.disable()

# Check if the channel is enabled
# The 'enabled' property is read-only
# Use the enable() and disable() methods to
# safely enable or disable the module
isEnabled = myEncoder.enabled

class Adafruit_BBIO.Encoder.RotaryEncoder(eqep_num)¶

Rotary encoder class abstraction to control a given QEP channel.

Parameters:	eqep_num (int) – determines which eQEP pins are set up. Allowed values: EQEP0, EQEP1, EQEP2 or EQEP2b, based on which pins the physical rotary encoder is connected to.

disable()¶: Turns the eQEP hardware OFF

enable()¶: Turns the eQEP hardware ON

setAbsolute()¶: Sets the eQEP mode as Absolute: The position starts at zero and is incremented or decremented by the encoder’s movement

setRelative()¶: Sets the eQEP mode as Relative: The position is reset when the unit timer overflows.

zero()¶: Resets the current position to 0

enabled¶

bool: True if the eQEP channel is enabled, False otherwise.

Type:	Returns the enabled status of the module
Type:	Returns

frequency¶: Sets the frequency in Hz at which the driver reports new positions.

mode¶

Returns the mode the eQEP hardware is in.

Returns:	0 if the eQEP channel is configured in absolute mode, 1 if configured in relative mode.
Return type:	int

position¶: Returns the current position of the encoder. In absolute mode, this attribute represents the current position of the encoder. In relative mode, this attribute represents the position of the encoder at the last unit timer overflow.

Adafruit_BBIO.Encoder.eQEP0 = 0¶: eQEP0 channel identifier, pin A– P9.92, pin B– P9.27 on Beaglebone Black.

Adafruit_BBIO.Encoder.eQEP1 = 1¶: eQEP1 channel identifier, pin A– P9.35, pin B– P9.33 on Beaglebone Black.

Adafruit_BBIO.Encoder.eQEP2 = 2¶: eQEP2 channel identifier, pin A– P8.12, pin B– P8.11 on Beaglebone Black. Note that there is only one eQEP2 module. This is one alternative set of pins where it is exposed, which is mutually-exclusive with eQEP2b

Adafruit_BBIO.Encoder.eQEP2b = 3¶: eQEP2(b) channel identifier, pin A– P8.41, pin B– P8.42 on Beaglebone Black. Note that there is only one eQEP2 module. This is one alternative set of pins where it is exposed, which is mutually-exclusive with eQEP2

`GPIO` — General Purpose I/O interface¶

This module provides access and control of pins set up as General Purpose I/O (GPIO).

Note

You need to be part of the gpio group of the OS running on the Beaglebone to be able to run GPIO code as a non-root user. The default user created upon the Debian image installation should already be part of the group. Otherwise, you can use sudo usermod -a -G gpio userName to add userName to the group.

Note

When coding with this module, you will be using pin names for better readability. As such, you can specify them in the header 8 or 9 form (e.g. “P8_16”) or in pin name form (e.g. “GPIO1_14”). For easy reference, you can use the Beaglebone pin names table

Note

On-board LEDs (USR0-USR3) are handled by LED class driver rather than the GPIO pin driver.

They have a different path in the /sys/ filesystem.

Setup the pin for output and write GPIO.HIGH or GPIO.LOW

Example:

# Use the config-pin command line tool to set a pin's function to GPIO
# Then you can control it with the GPIO module from Python
config-pin P9_14 gpio

import Adafruit_BBIO.GPIO as GPIO

# Set up pins as inputs or outputs
GPIO.setup("P8_13", GPIO.IN)
GPIO.setup("P8_14", GPIO.OUT)
GPIO.setup("GPIO0_26", GPIO.OUT)  # Alternative: use actual pin names

# Write a logic high or logic low
GPIO.output("P8_14", GPIO.HIGH)  # You can also write '1' instead
GPIO.output("P8_14", GPIO.LOW)   # You can also write '0' instead


# Blinking onboard led example
import Adafruit_BBIO.GPIO as GPIO
import time

for i in range(4):
    GPIO.setup("USR%d" % i, GPIO.OUT)

while True:
    for i in range(4):
        GPIO.output("USR%d" % i, GPIO.HIGH)
        time.sleep(1)
    for i in range(4):
        GPIO.output("USR%d" % i, GPIO.LOW)
        time.sleep(1)

Adafruit_BBIO.GPIO.setup(channel, direction[, pull_up_down=GPIO.PUD_OFF, initial=None, delay=0])¶

Set up the given GPIO channel, its direction and (optional) pull/up down control

Parameters:

channel (str) – GPIO channel to set up (e.g. “P8_16”).
direction (int) – GPIO channel direction (GPIO.IN or GPIO.OUT).
pull_up_down (int) – pull-up/pull-down resistor configuration (GPIO.PUD_OFF, GPIO.PUD_UP or GPIO.PUD_DOWN).
initial (int) – initial value for an output channel (GPIO.LOW/GPIO.HIGH).
delay (int) – time in milliseconds to wait after exporting the GPIO pin.

Adafruit_BBIO.GPIO.cleanup()¶

Clean up by resetting all GPIO channels that have been used by the application to IN with no pullup/pulldown and no event detection.

Note:	It’s recommended that you call this function upon exiting your application.

Adafruit_BBIO.GPIO.output(channel, value)¶

Set the given output channel to the given digital value.

Parameters:	channel (str) – GPIO channel to output the value to (e.g. “P8_16”). value (int or bool) – value to set the output to– 0/1 or False/True or `GPIO.LOW`/`GPIO.HIGH`.

Adafruit_BBIO.GPIO.input(channel)¶

Get the given input channel’s digital value.

Parameters:	channel (str) – GPIO channel to read the value from (e.g. “P8_16”).
Returns:	Channel value–– 0 or 1.
Return type:	int

Adafruit_BBIO.GPIO.add_event_detect(channel, edge[, callback=None, bouncetime=0])¶

Enable edge detection events for the given GPIO channel.

Parameters:	channel (str) – GPIO channel to detect events from (e.g. “P8_16”). edge (int) – edge to detect–– `GPIO.RISING`, `GPIO.FALLING` or `GPIO.BOTH` callback (func) – a function to call once the event has been detected. bouncetime (int) – switch bounce timeout in ms for the callback.

Adafruit_BBIO.GPIO.remove_event_detect(channel)¶

Remove edge detection for the given GPIO channel.

Parameters:	channel (str) – GPIO channel to remove event detection from (e.g. “P8_16”).

Adafruit_BBIO.GPIO.event_detected(channel)¶

Checks if an edge event has occured on a given GPIO.

Note:	You need to enable edge detection using `add_event_detect()` first.
Parameters:	channel (str) – GPIO channel to check for event detection for (e.g. “P8_16”).
Returns:	True if an edge has occured on a given GPIO, False otherwise
Return type:	bool

Adafruit_BBIO.GPIO.add_event_callback(channel, callback[, bouncetime=0])¶

Add a callback for an event already defined using add_event_detect()

Parameters:	channel (str) – GPIO channel to add a callback to (e.g. “P8_16”). callback (func) – a function to call once the event has been detected. bouncetime (int) – switch bounce timeout in ms for the callback.

Adafruit_BBIO.GPIO.wait_for_edge(channel, edge[, timeout=-1])¶

Wait for an edge on the given channel.

Parameters:	channel (str) – GPIO channel to wait on (e.g. “P8_16”). edge (int) – edge to detect–– `GPIO.RISING`, `GPIO.FALLING` or `GPIO.BOTH` timeout (int) – time to wait for an edge, in milliseconds. -1 will wait forever.

Adafruit_BBIO.GPIO.gpio_function(channel)¶

Return the current GPIO function (IN, IN, ALT0) of the given pin.

Warning:	Currently only returning the direction of the pin (input or output) is supported.
Parameters:	channel (str) – GPIO pin to query the status of.
Returns:	0 if `IN`, 1 if `OUT`
Return type:	int

Adafruit_BBIO.GPIO.setwarnings(gpio_warnings)¶

Enable or disable GPIO warning messages.

Warning:	Currently enabling or disabling warnings has no effect.
Parameters:	gpio_warnings (int) – 0–– disable warnings; 1–– enable warnings

Adafruit_BBIO.GPIO.ALT0¶: Pin mode– alternate function 0.

Adafruit_BBIO.GPIO.BOTH¶: Edge detection– detect both edges.

Adafruit_BBIO.GPIO.FALLING¶: Edge detection– detect falling edge.

Adafruit_BBIO.GPIO.HIGH¶: Pin status– logic low.

Adafruit_BBIO.GPIO.IN¶: Pin mode– input.

Adafruit_BBIO.GPIO.LOW¶: Pin status– logic low.

Adafruit_BBIO.GPIO.OUT¶: Pin mode– output.

Adafruit_BBIO.GPIO.PUD_OFF¶: Pull-up/pull-down resistor type– no pull-up/pull-down.

Adafruit_BBIO.GPIO.PUD_DOWN¶: Pull-up/pull-down resistor type– pull-down.

Adafruit_BBIO.GPIO.PUD_UP¶: Pull-up/pull-down resistor type– pull-up.

Adafruit_BBIO.GPIO.RISING¶: Edge detection– detect rising edge.

Adafruit_BBIO.GPIO.VERSION¶: GPIO module version. Currently unused.

`PWM` — Pulse Width Modulation interface¶

Enables access to the Pulse Width Modulation (PWM) module, to easily and accurately generate a PWM output signal of a given duty cycle and frequency.

Note

You need to be part of the pwm group of the OS running on the Beaglebone to be able to run PWM code as a non-root user. The default user created upon the Debian image installation should already be part of the group. Otherwise, you can use sudo usermod -a -G pwm userName to add userName to the group.

Adafruit_BBIO.PWM.start(channel, duty_cycle[, frequency=2000, polarity=0])¶

Set up and start the given PWM channel.

Parameters:

channel (str) – PWM channel. It can be specified in the form of of ‘P8_10’, or ‘EHRPWM2A’.
duty_cycle (int) – PWM duty cycle. It must have a value from 0 to 100.
frequency (int) – PWM frequency, in Hz. It must be greater than 0.
polarity (int) – defines whether the value for duty_cycle affects the rising edge or the falling edge of the waveform. Allowed values – 0 (rising edge, default) or 1 (falling edge).

Adafruit_BBIO.PWM.stop(channel)¶

Stop the given PWM channel.

Parameters:	channel (str) – PWM channel. It can be specified in the form of of ‘P8_10’, or ‘EHRPWM2A’.

Adafruit_BBIO.PWM.set_duty_cycle(channel, duty_cycle)¶

Change the duty cycle of the given PWM channel.

Note:	You must have started the PWM channel with `start()` once, before changing the duty cycle.
Parameters:	channel (str) – PWM channel. It can be specified in the form of of ‘P8_10’, or ‘EHRPWM2A’. duty_cycle (int) – PWM duty cycle. It must have a value from 0 to 100.

Adafruit_BBIO.PWM.set_frequency(channel, frequency)¶

Change the frequency of the given PWM channel.

Note:	You must have started the PWM channel with `start()` once, before changing the frequency.
Parameters:	channel (str) – PWM channel. It can be specified in the form of of ‘P8_10’, or ‘EHRPWM2A’. frequency (int) – PWM frequency. It must be greater than 0.

Adafruit_BBIO.PWM.cleanup()¶: Clean up by resetting all GPIO channels that have been used by this program to INPUT, with no pullup/pulldown and no event detection.

`SPI` — Serial Peripheral Interface¶

This module defines an object type that allows Serial Peripheral Interface (SPI) bus transactions on hosts running the Linux kernel. The host kernel must have SPI support and SPI device interface support.

Because the SPI device interface is opened R/W, users of this module usually must have root permissions or be members of a group with granted access rights.

Pins used for SPI0 and SPI1¶

PORT	CS0	DO	DI	SCLK
SPI0	P9_17	P9_21	P9_18	P9_22
SPI1	P9_28	P9_29	P9_30	P9_31

Example:

import Adafruit_BBIO.SPI as SPI

from Adafruit_BBIO.SPI import SPI
# spi = SPI(bus, device) #/dev/spidev<bus>.<device>

# /dev/spidev0.0
spi = SPI(0, 0)
print(spi.xfer2([32, 11, 110, 22, 220]))
spi.close()

# /dev/spidev0.1
spi = SPI(0, 1)
print(spi.xfer2([32, 11, 110, 22, 220]))
spi.close()

# /dev/spidev1.0
spi = SPI(1, 0)
print(spi.xfer2([32, 11, 110, 22, 220]))
spi.close()

# /dev/spidev1.1
spi = SPI(1, 1)
print(spi.xfer2([32, 11, 110, 22, 220]))
spi.close()

class Adafruit_BBIO.SPI.SPI(bus, client)¶

Parameters:	bus – bus number. client – client device number.
Returns:	a new SPI object, optionally connected to the specified SPI device interface.
Return type:	`SPI`

bpw¶: Bits per word.

cshigh¶: Chip Select (CS or Slave Select, SS) active high.

loop¶: Loopback configuration.

lsbfirst¶: Least Significant Bit (LSB) first.

mode¶: SPI mode as two bit pattern of Clock Polarity and Phase [CPOL|CPHA]; min– 0b00 = 0, max– 0b11 = 3.

msh¶: Maximum speed in Hz.

threewire¶: SI/SO signals are shared.

open(bus, device)¶

Connects the object to the specified SPI device. open(X, Y) will open /dev/spidev-X.Y

Parameters:	bus (int) – bus number device (str) – device number

close()¶: Disconnects the object from the interface.

readbytes(len)¶

Read the specified length of bytes from the SPI device.

Parameters:	len (int) – length of bytes to read, 1024 maximum.
Returns:	values read
Return type:	list[int]

writebytes(values)¶

Write bytes to the SPI device.

Parameters:	values (list[int]) – list of values to write, with a maximum length of 1024.

xfer(values[, delay=0])¶

Perform an SPI transaction of values. Slave Select (SS or CS) will be released and reactivated between blocks.

Parameters:	values (list[int]) – list of values to transfer, with a maximum length of 1024. delay – delay in microseconds between blocks.
Returns:	values transferred
Return type:	list[int]

xfer2(values)¶

Perform an SPI transaction of values. Slave Select (SS or CS) will be held active between blocks.

Parameters:	values (list[int]) – list of values to transfer, with a maximum length of 1024.
Returns:	values transferred
Return type:	list[int]

`UART` — UART communications interface¶

UART functionality of a BeagleBone using Python. Generally used to set up and grant access to a given UART device, which will then be accessed by other software or modules (e.g. pyserial):

sudo pip install pyserial

Example:

import Adafruit_BBIO.UART as UART
import serial

UART.setup("UART1")

with serial.Serial(port = "/dev/ttyO1", baudrate=9600) as ser:
    print("Serial is open!")
    ser.write(b"Hello World!")

Adafruit_BBIO.UART.setup_uart(channel)¶

Set up and start the UART channel. This function will effectively export the given UART so that it can be accessed by other software that controls its serial lines.

Parameters:	channel (str) – UART channel to set up. One of “UART1”, “UART2”, “UART4” or “UART5”

Adafruit_BBIO.UART.cleanup()¶: Cleans up the UART.

Adafruit Beaglebone IO Python API¶

ADC — A/D Converter input interface¶

Encoder — Quadrature Encoder interface (eQEP)¶

GPIO — General Purpose I/O interface¶

PWM — Pulse Width Modulation interface¶

SPI — Serial Peripheral Interface¶

Pins used for SPI0 and SPI1¶

UART — UART communications interface¶

Indices and tables¶

`ADC` — A/D Converter input interface¶

`Encoder` — Quadrature Encoder interface (eQEP)¶

`GPIO` — General Purpose I/O interface¶

`PWM` — Pulse Width Modulation interface¶

`SPI` — Serial Peripheral Interface¶

`UART` — UART communications interface¶