libregpio

libregpio is a python module that aims to provide basic, straight-forward GPIO input/output operations for Libre Computer “Le Potato” using gpiod

Note

This is an enthusiast project. It is not an official Libre Computer’s package.

Installation

Before installation it is required to have gpiod installed on your board.

$sudo apt install gpiod

This module is not yet available to install via pip.

Source code: https://github.com/c0t088/libregpio

Importing the module

To import the libregpio module:

import libregpio as GPIO

This way allows you to refer to it as GPIO for the rest of your program.

PIN Reference

This module is designed to work with the 40-pin chip of Libre Computer AML-S905X-CC “LePotato”.

Note

Please, see Libre Computer’s GPIO Headers Reference for full functions documentation: https://docs.google.com/spreadsheets/d/1U3z0Gb8HUEfCIMkvqzmhMpJfzRqjPXq7mFLC-hvbKlE/edit#gid=0

To access GPIO pins with this module, a class instance needs to be created. The pins are referred to by their GPIO name.

This is an example of an IN (input) class instance set to use ‘GPIOX_4’ pin:

import libregpio as GPIO

 a_pin = GPIO.IN('GPIOX_4')

How to use

As noted in the previous section, GPIO pins are handled as class instances based on their intended use. Here we will run through some code examples.

Note

Please, take notice that the cleanup() method is used at the end of every example. This is recommended to avoid leaving any pins on a high state after the end of your program.

IN Class examples

This section contains examples on how to use GPIO pins as inputs.

Read a current GPIO value

In this example we create an instance of the libregpio.IN class and call the input method to read the pin value:

import libregpio as GPIO

# set pin GPIOX_12 to be used as an input
pin = GPIO.IN('GPIOX_12')

# read pin value
value = pin.input()

# print read value
print(value)

GPIO.cleanup()

Pull up and Pull down resistors

When using a pin as an input it may be at a floating state, sending unreliable values. To prevent this, the bias parameter can be used in the input method to set pull-up or pull-down resistors.

This is the same example as above, but setting a pull-down bias:

import libregpio as GPIO

# set pin GPIOX_12 to be used as an input
pin = GPIO.IN('GPIOX_12')

# read pin value with a pull-down resistor
value = pin.input(bias='pull-down')

# print read value
print(value)

GPIO.cleanup()

Wait for an edge event

In some applications you may want your program to wait for a falling-edge or rising-edge event. For this, you can use the wait_for_edge method.

In this example we are using a PIR motion sensor connected to the GPIOX_12 pin. The program waits for a rising-edge event before printing the corresponding value:

import libregpio as GPIO

# set pin GPIOX_12 to be used as an input
pin = GPIO.IN('GPIOX_12')

# wait for a rising-edge event. Bias is set to pull-down
value = pin.wait_for_edge(bias='pull-down', edge='rising')

# print event value
print(value)

GPIO.cleanup()

Note

You can use the num_events parameter if you want to wait for more than one event occurrence.

OUT Class examples

In this section, we will turn an LED on for three seconds using the different methods of the libregpio.OUT class.

output method

import libregpio as GPIO
from time import sleep

# set pin GPIOX_5 to be used as an output
led = GPIO.OUT('GPIOX_5')

# send a 1 value and return it to 0 after 3 seconds
led.output(1)
sleep(3)
led.output(0)

GPIO.cleanup()

high and low methods

import libregpio as GPIO
from time import sleep

# set pin GPIOX_5 to be used as an output
led = GPIO.OUT('GPIOX_5')

# set the pin output to high and return to low after 3 seconds
led.high()
sleep(3)
led.low()

GPIO.cleanup()

toggle method

import libregpio as GPIO
from time import sleep

# set pin GPIOX_5 to be used as an output
led = GPIO.OUT('GPIOX_5')

# set the pin output to high and return to low after 3 seconds
led.toggle()
sleep(3)
led.toggle()

GPIO.cleanup()

API documentation

Warning

Although this module contains a PWM class, it is not currently working properly. Be aware that using this class and its methods can lead to unexpected results.

class libregpio.IN(pin)

Bases: object

This is a class representantion of a GPIO pin to be used as an input.

Parameters:: pin (str) – GPIO pin name (i.e. GPIOX_4)

input(bias='as-is')

Read an input value from a libregpio.IN object.

This method can read the pin input value at a given time.

Use the bias parameter to enable pull-up or pull-down modes.

Parameters:: bias (str, optional) – pull-up, pull-down, as-is, disable
Returns:: Input value read from GPIO pin (i.e. 0 or 1)
Return type:: int

wait_for_edge(bias='as-is', edge='rising', num_events=1, active_low=False)

Returns an input value when a specific edge event is detected. This method is designed to stop your program execution until an event is detected.

Parameters:

bias (str, optional) – pull-up, pull-down, as-is, disable
edge (str, optional) – Type of event to wait for (rising, falling), defaults to ‘rising’
num_events (Boolean, optional) – number of events to wait for. defaults to 1
active_low – Set pin to active-low state (True, False). defaults to False.

Returns:

1 for rising 0 for falling

Return type:

int

class libregpio.OUT(pin)

Bases: object

This is a class representantion of a GPIO pin to be used as an output.

Parameters:: pin (str) – GPIO pin name (i.e. GPIOX_4)

active_low(): Set libregpio.OUT object to active_low.

high(): Set a value of 1 to a libregpio.OUT object.

low(): Set a value of 0 to a libregpio.OUT object

output(value)

Set an output value to a libregpio.OUT object (i.e. 0 or 1).

Parameters:: value (int) – output value to be sent to GPIO pin

toggle(): Toggle output value of a GPIO pin

class libregpio.PWM(pin, duty_cycle, freq)

Bases: Thread

This is a class representantion of a GPIO pin to be used as an PWM output.

Use only with pins compatible with PWM (pulse width modulation).

Creating the class instance does not automatically sends a PWM output.

Parameters:

pin (str) – GPIO pin name (i.e. GPIOX_4)
duty_cycle (int) – duty cycle percentage
freq (float) – frequency in Hertz

change_duty_cycle(duty_cycle)

Modify the current duty cycle

Parameters:: duty_cycle (int) – duty cycle percentage

change_freq(freq)

Modify the current frequency

Parameters:: freq (float) – frequency in Hertz

pulse_loop()

This method is called by start() to loop the pulse output on a different thread

Do not call this method outside of this class.

start(duty_cycle=None)

Start the PWM output.

You can update the duty cycle when starting this method.

Parameters:: duty_cycle (int, optional) – duty cycle percentage, defaults to None

stop()

Stop the PWM output

It ‘cleans up’ the GPIO pin.

libregpio.cleanup(pins=None)

By Default, it sets all pins to 0 but you can pass a list if only specific pins need to be cleaned up.

It is recommended to use this method at the end of your program.

Parameters:: pins (iterable, optional) – list/tuple of pin or pins by name, defaults to None

libregpio.set_chip(pin_name)

Select the gpio chip corresponding to the pin. Do not call this function.

Parameters:: pin_name (str) – gpio pin name
Returns:: gpio chip
Return type:: str

Compatibility with other boards

This module is designed to work with Libre Computer’s “LePotato”. However, it can be mapped to different boards if needed, provided they are work with gpiod.

To achieve this, you need to modify the pin_mapping.py file to match your board.

# Modify this dictionary to your preffered pin names and corresponding
# linux number of said pins
PIN_NAME = {
"GPIOAO_5": 5,
"GPIOAO_4": 4,
"GPIOCLK_0": 98,
.
.
.

And you need to modify the set_chip() method in the libregpio.py file to set the corresponding chip of every pin.

def set_chip(pin_name):
# modify this code to match your board gpio chips
    chip_zero = ['GPIOAO_5','GPIOAO_4','GPIOAO_8','GPIOAO_9','TEST_N','GPIOAO_6']
    if pin_name in chip_zero:
        chip = 0
    else:
        chip = 1
    return str(chip)

GitHub

The source code is available to clone at: https://github.com/c0t088/libregpio

References

Libre Computer Header Reference: https://docs.google.com/spreadsheets/d/1U3z0Gb8HUEfCIMkvqzmhMpJfzRqjPXq7mFLC-hvbKlE/edit#gid=0

Changelog

Version	Description	Date
0.0.1	Initial Version	2022-11-06

MIT Licence

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.