RPi.GPIO2 1.0
Functional and Technical Specification
Revision 3

This document specifies the functional requirements and and technical implementation of RPi.GPIO2. Upon completion and ratification by our group, our development and quality engineering efforts will follow from this document. We will consider this document the upstream authority with respect to our implementation and as such all future changes shall be first specified here and subsequently integrated into our codebase.

This document specifies the requirements for version 1.0 of RPi.GPIO2. We may release minor versions in the form of 0.x that partially satisfy this spec. This document does not specify features that extend the RPi.GPIO interface¹¹1With the exception of channel_valid_or_die(), the addition of which is basically negligible, in fact, we discourage extensions to the existing API in version 1.0 unless absolutely necessary.

We begin with a discussion of the problem and our proposed solution. Then, we define first the high-level functional requirements for version 1.0 and then what each API function should do and not do. Finally, we give a high-level description of the data structures and algorithms used to implement the system.

A glossary of terminology and shortand used in this document can be found in table 1.

RPi.GPIO.add_event_callback(channel, callback)

Add a callback function to a channel previously setup for event detection by add_event_detect(). When an event is detected by the library, callback will be called after all previously registered callback functions are called first.

parameters:

1. channel — GPIO channel

2. callback — 0-ary callable python object

exceptions:

• RuntimeError — Channel not previously setup with add_event_detect since last Reset

• TypeError — Parameter callback not callable

• ValueError — Invalid channel

Enable detection of edge events for some GPIO channel.

parameters:

1. channel — GPIO channel

2. edge — any one of RISING, FALLING, or BOTH to specify types of events to detect

3. callback (optional) — 0-ary callable python object

   Default value: No callback function added

4. bouncetime (optional) — Cooldown time in milliseconds for callbacks

   Default value: No bouncetime enforced

exceptions:

• TypeError — Parameter callback not callable

• ValueError — Invalid channel, edge is not one of RISING, FALLING, or BOTH, or a negative bouncetime is specified

Validate channel using the current numbering mode.

If the channel is valid, the function returns with no effect. If the channel is invalid, a ValueError exception is raised.

See getmode()/setmode() in section 4.1 for more information about numbering modes.

parameters:

1. channel — GPIO channel

exceptions:

• ValueError — Invalid channel

Cleans up library state. Resets all GPIO lines that have been used by this program to INPUT with neither PUD_UP or PUD_DOWN set nor event detection enabled on the line. When called with no arguments, this function targets every channel, otherwise, it targets only the channels specified. Subsequent to the actions of cleanup() on a channel, one must pass it to setup() to use it again.

This function is automatically invoked with no parameters upon terminaton of a python interpreter using this module.

parameters:

1. channel (optional) — individual GPIO channel or list/tuple of GPIO channels

   Default value: All channels

exceptions:

• ValueError — Invalid channel

Returns True if an edge has occurred on a given GPIO at the time of call. Otherwise, returns False. This function does not block and will always return False unless add_event_detect() is called on channel first.

parameters:

1. channel — GPIO channel

exceptions:

• ValueError — Invalid channel

Get the numbering mode in use for GPIO channels. Returns one of BOARD, BCM or None

exceptions:

• RuntimeError — Module was not imported correctly

Get the GPIO function constant corresponding to channel. Returns one of IN, OUT, PWM, SERIAL, I2C, or SPI.

parameters:

1. channel — GPIO channel

exceptions:

• ValueError — Invalid channel

Get the current value of the GPIO line specified by channel. Returns one of HIGH=1 or LOW=0. Direction of channel must be one of INPUT or OUTPUT.

parameters:

1. channel — GPIO channel

exceptions:

• ValueError — Invalid channel

• RuntimeError — direction of channel not one of INPUT or OUTPUT

Set the value of an individual GPIO channel or a list/tuple of GPIO channels with an individual value or a list/tuple of values respectively. One may specify multiple channels and a single value for each channel to be set to the same value.

parameters:

1. channel — Individual GPIO channel or list/tuple of GPIO channels

2. value — Individual value or list/tuple of values that are one of LOW=0 or HIGH=1

exceptions:

• ValueError — Invalid channel(s) or invalid values(s)

• RuntimeError — Number of channels specified differs from number of values provided or the GPIO channel has not been setup as an output

Disable and clean up edge event detection configured on a particular GPIO channel. This removes all callback functions saved for that channel.

parameters:

1. channel — GPIO channel

exceptions:

• ValueError — Invalid channel

Set up numbering mode to use for channels. Mode is one of BOARD or BCM, where BOARD specifies use of Raspberry Pi board numbers and BCM specifies use of Broadcom GPIO 00..nn numbers

parameters:

1. mode — One of BOARD or BCM

exceptions:

• ValueError — Invalid mode or setmode() already called once since last call to Reset

• RuntimeError — Module was not imported correctly

Set up an individual GPIO channel or list/tuple of GPIO channels given a direction and (optionally) a bias (e.g. PUD_UP/PUD_DOWN)

1. channel — GPIO channel

2. direction — One of IN or OUT

3. pull_up_down (optional) — Either the default value PUD_OFF or one of PUD_UP, PUD_DOWN, or PUD_DISABLE

4. initial (optional) — Initial channel value (only allowed for output)

exceptions:

• ValueError — Invalid channel(s), direction not one of IN or OUT, bias specified for OUT direction, initial pin value specified for IN direction

• RuntimeError — Module was not imported correctly

Enable or disable warning messages. Use True to enable and False to disable.

parameters:

1. value — A boolean

exceptions:

• RuntimeError — Module was not imported correctly

[BLOCKS] Wait for an edge event of type edge to take place on channel. Disables python’s Global Interpreter Lock while blocking. A negative timeout value will cause the program to block indefinitely waiting for an edge event. A timeout value of zero will prevent the program from blocking entirely.

If an event is detected and none of the following hold true:

1. If provided a bouncetime, the difference between the current time and the time at which this event previously occurred is less than the bouncetime

2. This function, line_event_wait has never been called before on this channel

3. The time at which this event last occurred is later than the current time ²²2Yeah I don’t really understand this one either, for more information refer to The RPi.GPIO 0.7.0 Source Code, source/event_gpio.c:579[3].

Then, the 0-ary callable objects stored in the list _State.lines[channel].callbacks will be serially invoked. If one subsequently invokes event_detected(channel), the event detected by this function will not be reported.

Returns channel if any event is detected, otherwise returns None.

parameters:

1. channel — GPIO channel

2. edge — any one of RISING, FALLING, or BOTH to specify types of events to wait for

3. bouncetime (optional) — Cooldown time in milliseconds for callbacks

   Default value: No bouncetime enforced

4. timeout (optional) — time in milliseconds to wait before quitting

   Default value: The call will block indefinitely

exceptions:

• ValueError — Invalid channel, invalid edge, non-positive bouncetime, or non-positive timeout specified

RPi.GPIO.PWM is a Pulse-width Modulation (PwM) class. Object methods follow.

Change the duty cycle of the PwM channel to dutycycle

parameters:

1. dutycycle — percentage of pulse period to output high voltage

exceptions:

• ValueError — Invalid duty cycle

Change the frequency the PwM channel to frequency

parameters:

1. frequency — pulse periodicity in hz

exceptions:

• ValueError — Invalid frequency value

Initialize a new PwM object. Commonly invoked via:

RPi.GPIO.PWM(channel, frequency)

parameters:

1. channel — GPIO channel

2. frequency — A positive float value

exceptions:

• ValueError — Invalid frequency value

• RuntimeError — PwM already setup on channel

Start software PwM on the channel specified in __init__.

parameters:

1. dutycycle — A value between 0.0 and 100.0

exceptions:

• ValueError — Invalid duty cycle

Stop software PwM on the channel specified in __init__.

Some constant representing BCM chip numbering mode, the numbering of the channels according to the Broadcom specification

Some constant representing BOARD chip numbering mode, the numbering of the channels according to the Raspberry Pi specification

Some constant representing edge event detection of both rising edge and falling edge events

Some constant representing falling edge event detection only

Some constant representing that a GPIO channel is capable of supporting hardware PwM

Some nonzero constant representing a high-power state on a GPIO channel. Can be used to specify active state of a channel.

Some constant representing that a GPIO channel is capable of supporting the i2c protocol

Some constant representing the input direction of a GPIO channel

A constant zero representing a low-power state on a GPIO channel. Can be used to specify active state of a channel.

Some constant representing the output direction of a GPIO channel

Some constant representing the explicit choice to disable pull-up or pull-down resistors.

Some constant representing a pull-down resistor on a GPIO channel.

Some constant representing the lack of a pull-up or pull-down resistor on a GPIO channel.

Some constant representing a pull-up resistor on a GPIO channel.

Some constant representing rising edge event detection only

A dictionary of the following key/value pair structure:

• “MANUFACTURER”: Board manufacturer

• “P1_REVISION”: Secondary revision number

• “PROCESSOR”: CPU information

• “RAM”: Total system RAM

• “REVISION”: Primary revision number

• “TYPE”: Board model name string

The major version of this Raspberry Pi device.

Some constant representing that a GPIO channel is capable of supporting the serial protocol

Some constant representing that a GPIO channel is capable of supporting the spi protocol

Some constant representing unknown information

The version of this library.

What follows are a few functions that may be useful for debugging this library.

Cleanup and re-initialize the library as if it was just imported.

Enable or disable verbose debug messages. Use True to enable and False to disable.

parameters:

1. value — A boolean

exceptions:

• RuntimeError — Module was not imported correctly

We aim to translate RPi.GPIO API calls to their libgpiod equivalents. In general, the way this library modulates the user’s request for an RPi.GPIO action is through a shared state object containing a python gpiod.Chip object and a list of the 54 gpio.Line objects. The user makes calls to our API functions which handle input validation and these functions make calls to our internal interface functions, those modifying the Chip object being prefixed by chip_ and those modifying Line objects being prefixed by line_. These internal interface functions modularize the library by separating API call validation from internal state changes and associated locking.

As much as possible, we try to transparently manipulate channel state as specified by the RPi.GPIO source code, but due to a lack of exact correspondence, we introduce line mode constants that represent the states that a particular GPIO channel can be in. We specify the meaning of these constants below.

Software Pulse-width Modulation is implemented on top of the core API. We essentially make repeated calls to GPIO.output(channel) corresponding appropriately to the period and duty cycle.

Event detection is done by running a poll thread using python’s built-in threading class, threading.Thread. Since multiple active threads may try to write to the library state, we implement mutual exclusion for critical sections on a per-GPIO channel basis, with each gpiod.Line object having an associated lock of type threading.lock. These locks are intended to be used via the begin_critical_section(channel, msg) and end_critical_section(channel, msg) interface primitives. Some internal interface functions have locking and non-locking versions. This is indicated via a _lock suffix appended to the function identifier.

The top-level container for the internal state of the library. Intended to be accessed at the class level as a global shared state as if one were accessing a C struct at global scope.

One of UNKNOWN, BCM, or BOARD. Represents the current line numbering mode.

Default value: UNKNOWN

Either True or False. Determines whether warning messages are printed to stdout or suppressed.

Default value: True

Either True or False. Determines whether debug messages unique to this library are printed to stdout or suppressed.

Default value: False

The instance of class gpiod.Chip containing the GPIO channels provided by the RPi.GPIO API.

Default value: gpiod.Chip("gpiochip0")

A list of the channels on which events have recently occurred. Will be invariantly empty until event detection is setup on one or more channels.

Default value: Empty List

A list of _Line objects corresponding to each GPIO channel. _Line objects are internal to this library and contain corresponding gpiod.Line objects and associated data.

Default value: [_Line(channel) for channel in range(chip_get_num_lines())]

The internal representation of a GPIO line corresponding to a particular GPIO channel.

Initialize a new _Line object. Invoked by Reset.

parameters:

1. channel — GPIO channel

[LOCK REQUIRED] Start a new thread on this channel to either poll for events or do pulse-width modulation. Returns True if a thread is sucessfully started and False otherwise.

parameters:

1. target_type — one of either _line_thread_poll or _line_thread_pwm to specify thread type

2. args — a tuple of arguments to pass to the entry point for the new thread

[LOCK REQUIRED] Stop the thread running on this channel if one exists.

[LOCK REQUIRED] Reset the internal state of the object to initial state. Kills the channel’s poll thread if one is running. Clears the list of callbacks. Sets line mode to _line_mode_none.

Request for libgpiod to execute the syscall to get permissions to access self.channel.

parameters:

1. mode — the desired libgpiod mode

2. flags — flags specified configuration (e.g. pull up/pull down resistors)

The GPIO channel corresponding to this line.

Default value: An integer passed to __init__ via Reset(). See _State.lines in section 5.2.

The gpiod.Line object corresponding to this channel

Default value: gpiod.Chip.get_line(self.channel)

The current line mode of the GPIO channel. See section 5.7 for more on line modes.

Default value: _line_mode_none

A locking primitive of type threading.Lock.

Used internally by the locking interface primitives begin_critical_section(channel, msg) and end_critical_section(channel, msg).

Default value: threading.Lock()

An entry of type _LineThread used to represent a poll thread that checks for edge events on a pin.

Default value: None

A list of callable objects that are sequentially invoked upon edge event detection on self.channel.

Default value: Empty List

A timestamp (from time.time()) of the last edge event detected on that channel. Used to enforce bounce timeout for callbacks on a channel.

Default value: None

A subclass of threading.Thread with basic stopability.

Create a new instance of this class on channel that will call target(*args) when the line thread is started via line_start_poll or line_start_pwm

parameters:

1. channel — GPIO channel

2. target_type — one of either _line_thread_poll or _line_thread_pwm to specify thread type

3. args — arguments that will be passed to target at invocation

[LOCK REQUIRED] Stop a _LineThread’s thread by setting the stop event and joining the thread until completion. The lock is dropped temporarily during the call to join() to allow the thread to finish its last iteration.

This section defines the internal interface functions used to implement operations at the gpiod.Chip level and validation of channel numbers. External exposure of these functions is undefined behavior.

Validate channel using the current numbering mode. See getmode()/setmode() in section 4.1 for more information about numbering modes.

parameters:

1. channel — GPIO channel

exceptions:

• ValueError — Invalid channel in current numbering mode

Close the file descriptor associated with the internal gpiod.Chip object and remove references to the object from _State. The former name will always attempt these operations. The latter name will perform these operations only if _State.chip is not None. Internally, we only call the latter except from the latter itself.

[LOCKS ALL CHANNELS] Acquire a lock on every channel and then call chip_close_if_open().

Returns the number of GPIO lines on the chip. Used to initialize the list of _Line objects held by _State. See section 5.2 for more information.

Initialize the gpiod.Chip object held by _State.chip. The former name performs these operations directly. The latter name performs these operations only if _State.chip is not None.

exceptions:

• PermissionError — Unable to open file “/dev/gpiochip0”, perhaps because script was not run as root.

Returns the truth value of whether the chip has been initialized. True if yes, False if no.

This section defines the internal interface functions used to implement operations at the gpiod.Line level. External exposure of these functions is undefined behavior.

[LOCKS channel] Append a callable function to the list of callable python objects stored in _State.lines[channel].callbacks. Upon the next edge event detected on this channel, callback will be invoked after the other callback functions are invoked.

parameters:

1. channel — GPIO channel

2. callback — A 0-ary callable object

[LOCKS channel] Execute the main loop of a poll thread while the thread has not been killed. Guaranteed to drop the lock for at least ten milliseconds per iteration.

parameters:

1. channel — GPIO channel

2. bouncetime — cooldown time in milliseconds for invoking the callback functions

3. timeout — time in milliseconds to wait per loop before giving up

[first: LOCK REQUIRED, second: LOCKS channel] Wait for an edge event of type previously specified in edge event detection setup. Calls gpiod.Line.event_wait(). Returns the channel number if an event occurred and returns None otherwise.

parameters:

1. channel — GPIO channel

2. bouncetime — cooldown time in milliseconds for invoking the callback functions

3. timeout — time in milliseconds to wait per loop before giving up

4. track — Boolean value, the truth of which determines whether the event will subsequently be reported by RPi.GPIO.event_detected(channel).

Returns gpiod.Line.active_state(channel).

parameters:

1. channel — GPIO channel

Returns gpiod.Line.bias(channel).

parameters:

1. channel — GPIO channel

Returns a bitwise-and of all return values of functions that get libgpiod request flags.

parameters:

1. channel — GPIO channel

Returns _State.lines[channel].mode

parameters:

1. channel — GPIO channel

Returns some string such that no other call to this function with a different value of channel will produce this string.

parameters:

1. channel — GPIO channel

Calls gpiod.Line.get_value() on channel.

parameters:

1. channel — GPIO channel

This functions returns a Boolean that represents the authority on whether a channel is in use by this library. A channel is defined to be active if it has line mode other than _line_mode_none.

parameters:

1. channel — GPIO channel

Returns True if a GPIO.PWM object has been created on channel, otherwise returns False.

parameters:

1. channel — GPIO channel

2. dutycycle — percentage of pulse period to output high voltage

[first: LOCK REQUIRED, second: LOCKS channel] Stos poll thread running on channel by calling _PollThread.kill(). Remove the reference to that _PollThread object from the parent _Line. Do not return until the operation is complete.

parameters:

1. channel — GPIO channel

[LOCKS channel] Kick off a new poll thread from the main thread. Creates and starts new _PollThread. Adds any specified callbacks to _State.lines[channel].callbacks.

parameters:

1. channel — GPIO channel

2. edge — any one of RISING, FALLING, or BOTH to specify types of events poll for

3. callback — A 0-ary callable object

4. bouncetime — cooldown time in milliseconds for invoking the callback functions

[first: LOCK REQUIRED, second: LOCKS channel] Set the dutycycle value for pulse-width modulation.

parameters:

1. channel — GPIO channel

2. dutycycle — percentage of pulse period to output high voltage

[LOCKS channel] Set the pulse frequency value for pulse-width modulation.

parameters:

1. channel — GPIO channel

2. frequency — pulse periodicity in hz

[LOCKS channel] Start pulse-with modulation on channel. Returns true if successful and false otherwise.

parameters:

1. channel — GPIO channel

2. dutycycle — percentage of pulse period to output high voltage

Stop a pulse-width modulation running on channel if it exists.

parameters:

1. channel — GPIO channel

[LOCKS channel] Set the flags on channel to flags via gpiod.Line.set_flags(). Used to set line bias and line active_state.

parameters:

1. channel — GPIO channel

2. flags — the new flags value to set

parameters:

1. channel — GPIO channel

2. mode — A valid line mode. See section 5.7.

3. flags (optional) — the new flags value to set.

   Default value: $0$

Calls gpiod.Line.set_value(value) on channel.

parameters:

1. channel — GPIO channel

2. value — new value for GPIO channel

Return the value _State.lines[channel].thread.killswitch.is_set(). Used by a line thread when it considers suicide.

parameters:

1. channel — GPIO channel

The following constants are internal to the library and their external exposure is undefined. The reason for the distinction between “Values” and “Events” mode types is that the underlying ioctl(2) syscalls made by libgpiod actually request different access permissions for that GPIO channel depending on this choice.

The default line mode. This line is not accessible and should not be used in this mode.

Values input mode. This line is setup to get the value of the pin as input.

Values output mode. This line is setup to set the value of the pin as output.

Events mode for rising edge events.

Events mode for rising edge events.

Events mode for both rising and falling edge events. Detects all events.

Events as-is mode. As of yet undefined.

A thread type to represent the lack of a thread

A thread type that will poll for events on a channel

A thread type that will execute software pulse-width modulation on a channel