API Reference

The API of rpi-lgpio (naturally) follows that of rpi-gpio (aka RPi.GPIO) as closely as possible. As such the following is simply a re-iteration of that API.

Initialization

RPi.GPIO.setmode(new_mode)

Set up the numbering mode to use for the pins on the board. The options for new_mode are:

• BOARD - Use Raspberry Pi board numbers

• BCM - Use Broadcom GPIO 00..nn numbers

If a numbering mode has already been set, and new_mode is not the same as the result of getmode(), a ValueError is raised.

Parameters:

new_mode (int) – The new numbering mode to apply

RPi.GPIO.getmode()

Get the numbering mode used for the pins on the board. Returns BOARD, BCM or None.

RPi.GPIO.setup(chanlist, direction, pull_up_down=20, initial=None)

Set up a GPIO channel or iterable of channels with a direction and (optionally, for inputs) pull/up down control, or (optionally, for outputs) and initial state.

The GPIOs to affect are listed in chanlist which may be any iterable. The direction is either IN or OUT.

If direction is IN, then pull_up_down may specify one of the values PUD_UP to set the internal pull-up resistor, PUD_DOWN to set the internal pull-down resistor, or the default PUD_OFF which disables the internal pulls.

If direction is OUT, then initial may specify zero or one to indicate the initial state of the output.

Parameters:

• chanlist (list or tuple or int) – The list of GPIO channels to setup

• direction (int) – Whether the channels should act as inputs or outputs

• pull_up_down (int or None) – The internal pull resistor (if any) to enable for inputs

• initial (bool or int or None) – The initial state of an output

RPi.GPIO.cleanup(chanlist=None)

Reset the specified GPIO channels (or all channels if none are specified) to INPUT with no pull-up / pull-down and no event detection.

Parameters:

chanlist (list or tuple or int or None) – The channel, or channels to clean up

Pin Usage

RPi.GPIO.input(channel)

Input from a GPIO channel. Returns 1 or 0.

This can also be called on a GPIO output, in which case the value returned will be the last state set on the GPIO.

Parameters:

channel (int) – The board pin number or BCM number depending on setmode()

RPi.GPIO.output(channel, value)

Output to a GPIO channel or list of channels. The value can be the integer LOW or HIGH, or a list of integers.

If a list of channels is specified, with a single integer for the value then it is applied to all channels. Otherwise, the length of the two lists must match.

Parameters:

• channel (list or tuple or int) – The GPIO channel, or list of GPIO channels to output to

• value (list or tuple or int) – The value, or list of values to output

Edge Detection

RPi.GPIO.wait_for_edge(channel, edge, bouncetime=None, timeout=None)

Wait for an edge on the specified channel. Returns channel or None if timeout elapses before the specified edge occurs.

Note

Debounce works significantly differently in rpi-lgpio than it does in rpi-gpio; please see Debounce for more information on the differences.

Parameters:

• channel (int) – The board pin number or BCM number depending on setmode() to watch for changes

• edge (int) – One of the constants RISING, FALLING, or BOTH

• bouncetime (int or None) – Time (in ms) used to debounce signals

• timeout (int or None) – Maximum time (in ms) to wait for the edge

RPi.GPIO.add_event_detect(channel, edge, callback=None, bouncetime=None)

Start background edge detection on the specified GPIO channel.

If callback is specified, it must be a callable that will be executed when the specified edge is seen on the GPIO channel. The callable must accept a single parameter: the channel on which the edge was detected.

Note

Debounce works significantly differently in rpi-lgpio than it does in rpi-gpio; please see Debounce for more information on the differences.

Parameters:

• channel (int) – The board pin number or BCM number depending on setmode() to watch for changes

• edge (int) – One of the constants RISING, FALLING, or BOTH

• callback (callable or None) – The callback to run when an edge is detected; must take a single integer parameter of the channel on which the edge was detected

• bouncetime (int or None) – Time (in ms) used to debounce signals

RPi.GPIO.add_event_callback(channel, callback)

Add a callback to the specified GPIO channel which must already have been set for background edge detection with add_event_detect().

Parameters:

• channel (int) – The board pin number or BCM number depending on setmode() to watch for changes

• callback – The callback to run when an edge is detected; must take a single integer parameter of the channel on which the edge was detected

RPi.GPIO.event_detected(channel)

Returns True if an edge has occurred on the specified channel since the last query of the channel (if any). Querying this will also reset the internal edge detected flag for this channel.

The channel must previously have had edge detection enabled with add_event_detect().

Parameters:

channel (int) – The board pin number or BCM number depending on setmode()

Miscellaneous

RPi.GPIO.gpio_function(channel)

Return the current GPIO function (IN, OUT, HARD_PWM, SERIAL, I2C, SPI) for the specified channel.

Note

This function will only return IN or OUT under rpi-lgpio as the underlying kernel device cannot report the alt-mode of GPIO pins.

Parameters:

channel (int) – The board pin number or BCM number depending on setmode()

RPi.GPIO.setwarnings(value)

Enable or disable warning messages. These are mostly produced when calling setup() or cleanup() to change channel modes.

PWM

class RPi.GPIO.PWM(channel, frequency)

Initializes and controls software-based PWM (Pulse Width Modulation) on the specified channel at frequency (in Hz).

Call start() and stop() to generate and stop the actual output respectively. ChangeFrequency() and ChangeDutyCycle() can also be used to control the output.

Note

Letting the PWM object go out of scope (and be garbage collected) will implicitly stop the PWM.

ChangeDutyCycle(dc)

Changes the duty cycle (percentage of the time that the pin is “on”) to dc.

ChangeFrequency(frequency)

Changes the frequency of rising edges output by the pin.

start(dc)

Starts outputting a wave on the assigned pin with a duty-cycle (which must be between 0 and 100) given by dc.

Parameters:

dc (float) – The duty-cycle (the percentage of time the pin is “on”)

stop()

Stops outputting a wave on the assigned pin, and sets the pin’s state to off.

Constants

RPi.GPIO.RPI_INFO

A dictionary that provides information about the model of Raspberry Pi that the library is loaded onto. Includes the following keys:

P1_REVISION

The revision of the P1 header. 0 indicates no P1 header (typical on the compute module range), 1 and 2 vary on the oldest Raspberry Pi models, and 3 is the typical 40-pin header present on all modern Raspberry Pis.

REVISION

The hex board revision code as a str.

TYPE

The name of the Pi model, e.g. “Pi 4 Model B”

MANUFACTURER

The name of the board manufacturer, e.g. “Sony UK”

PROCESSOR

The name of the SoC used on the board, e.g. “BCM2711”

RAM

The amount of RAM installed on the board, e.g. “4GB”

The board revision can be overridden with the RPI_LGPIO_REVISION environment variable; see Pi Revision for further details.

RPi.GPIO.RPI_REVISION

The same as the P1_REVISION key in RPI_INFO

RPi.GPIO.BOARD

Indicates to setmode() that physical board numbering is requested

RPi.GPIO.BCM

Indicates to setmode() that GPIO numbering is requested

RPi.GPIO.PUD_OFF

Used with setup() to disable internal pull resistors on an input

RPi.GPIO.PUD_DOWN

Used with setup() to enable the internal pull-down resistor on an input

RPi.GPIO.PUD_UP

Used with setup() to enable the internal pull-up resistor on an input

RPi.GPIO.OUT

Used with setup() to set a GPIO to an output, and gpio_function() to report a GPIO is an output

RPi.GPIO.IN

Used with setup() to set a GPIO to an input, and gpio_function() to report a GPIO is an input

RPi.GPIO.HARD_PWM

RPi.GPIO.SERIAL

RPi.GPIO.I2C

RPi.GPIO.SPI

Used with gpio_function() to indicate “alternate” modes of certain GPIO pins.

Note

In rpi-lgpio these values will never be returned as the kernel device cannot report if pins are in alternate modes.

RPi.GPIO.LOW = 0

Used with output() to turn an output GPIO off

RPi.GPIO.HIGH = 1

Used with output() to turn an output GPIO on

RPi.GPIO.RISING

Used with wait_for_edge() and add_event_detect() to specify that rising edges only should be sampled

RPi.GPIO.FALLING

Used with wait_for_edge() and add_event_detect() to specify that falling edges only should be sampled

RPi.GPIO.BOTH

Used with wait_for_edge() and add_event_detect() to specify that all edges should be sampled