gpio¶

GPIO abstraction for Raspberry Pi pin control.

This module provides a thin, simplified abstraction layer over the RPi.GPIO library for use across Oizom hardware drivers. It exposes helpers for pin configuration, digital read/write, cleanup, and selection of channels on the on-board I2C multiplexer.

A small in-process registry (_pin_modes) tracks the most recently applied direction ("in" / "out") per BCM pin so that callers can invoke read() or set() without an explicit prior setup() call; the appropriate direction will be configured lazily on first use.

Example

Configure a pin and toggle its output level:

>>> from drivers.gpio import gpio
>>> gpio.setup(17, gpio.OUT)
>>> gpio.set(17, True)
>>> gpio.read(4)
True

Note

The module initializes RPi.GPIO in BCM numbering mode (GPIO.setmode(GPIO.BCM)) at import time. Use setmode() to switch to GPIO.BOARD numbering if a different scheme is required, but be aware that all pin numbers throughout this module are assumed to be BCM.
Internal pull-up / pull-down resistors are disabled by default for inputs. Pass pullup=True or pullup=False to setup() to explicitly engage the SoC’s internal pull resistor.
Runtime warnings emitted by RPi.GPIO are silenced at import time via GPIO.setwarnings(False); re-enable them with setwarnings() during debugging if needed.

See also

RPi.GPIO: Underlying low-level GPIO driver wrapped by this module.

Attributes¶

`HIGH`
`IN`
`LOW`
`OUT`
`_pin_modes`
`basic_logger`
`context_logger`

Functions¶

`cleanup`(→ None)	Release GPIO resources held by this process.
`input`(→ bool)	Read the logic level of a GPIO pin (alias for `read()`).
`mode`(→ str \| None)	Return the last-configured direction for a pin, if any.
`output`(→ None)	Drive a GPIO pin HIGH or LOW (alias for `set()`).
`read`(→ bool)	Read the current logic level of a GPIO pin.
`select_I2C`(→ None)	Select a channel on the Oizom I2C multiplexer.
`set`(→ None)	Drive a GPIO pin HIGH or LOW, auto-configuring it as output if needed.
`setmode`(→ None)	Select the pin numbering scheme used by `RPi.GPIO`.
`setup`(→ None)	Configure a GPIO pin as input or output.
`setwarnings`(→ None)	Enable or disable runtime warnings emitted by `RPi.GPIO`.

Module Contents¶

gpio.cleanup(pin: int | None = None, assert_exists: bool = False) → None¶

Release GPIO resources held by this process.

Wraps RPi.GPIO.cleanup() and synchronizes the local _pin_modes registry by either clearing it entirely (when pin is None) or removing a single entry.

Parameters:

pin (int | None) – BCM GPIO pin number to release, or None to release all pins configured through this process. Defaults to None.
assert_exists (bool) – Reserved flag retained for API compatibility with prior versions; it is not consulted by the current implementation. Defaults to False.

Returns:

This function performs hardware cleanup and returns nothing.

Return type:

None

Raises:

Exception – Any exception raised by RPi.GPIO is caught and logged as a warning via the context logger; nothing is re-raised.

Example

Release a single pin or perform a global teardown at exit:

>>> cleanup(17)
>>> cleanup()

Note

Calling cleanup() with no arguments resets every pin previously configured in this process to a safe input state. It does not affect pins held by other processes. It is good practice to invoke this from an atexit handler or signal handler in long-running applications.

See also

RPi.GPIO.cleanup()

gpio.input(pin: int) → bool¶

Read the logic level of a GPIO pin (alias for read()).

This thin wrapper exists so that callers familiar with the RPi.GPIO API (GPIO.input) can use the same name when operating through this module.

Parameters:: pin (int) – BCM GPIO pin number to sample.
Returns:: True when the pin is at logic HIGH, False when it is at logic LOW. Propagates the return value of read().
Return type:: bool
Raises:: Exception – Any exception raised by RPi.GPIO is caught and logged inside read(); nothing is re-raised here.

Example

Drop-in replacement for GPIO.input:

>>> level = input(17)

Note

This function shadows the Python built-in input(). Inside modules that need both, alias the import (for example, from drivers.gpio import gpio and use gpio.input).

See also

read() RPi.GPIO.input()

gpio.mode(pin: int) → str | None¶

Return the last-configured direction for a pin, if any.

Looks up the pin in the module-private _pin_modes registry, which is populated by setup() (called either directly by the user or implicitly by set() / read()).

Parameters:: pin (int) – BCM GPIO pin number to query.
Returns:: IN ("in") or OUT ("out") if the pin has been configured through this module, otherwise None.
Return type:: str | None
Raises:: None – This is a pure dictionary lookup and does not raise.

Example

Inspect whether a pin has been configured yet:

>>> mode(17)
'out'
>>> mode(99)

Note

The registry is local to this module. Pins configured by other libraries acting on RPi.GPIO directly will not appear here even though they may be live on the SoC.

gpio.output(pin: int, value: bool) → None¶

Drive a GPIO pin HIGH or LOW (alias for set()).

This thin wrapper exists so that callers familiar with the RPi.GPIO API (GPIO.output) can use the same name when operating through this module.

Parameters:

pin (int) – BCM GPIO pin number to drive.
value (bool) – Logical level to apply. True drives the pin HIGH, False drives it LOW.

Returns:

This function delegates to set() and returns nothing.

Return type:

None

Raises:

Exception – Any exception raised by RPi.GPIO is caught and logged inside set(); nothing is re-raised here.

Example

Drop-in replacement for GPIO.output:

>>> output(17, True)

Note

Auto-configures the pin as output via setup() if it has not been seen before. Pin numbers must be BCM.

See also

set() RPi.GPIO.output()

gpio.read(pin: int) → bool¶

Read the current logic level of a GPIO pin.

If the pin has not yet been configured as an input in the local _pin_modes registry, setup() is invoked first with mode=IN (and no pull resistor) before sampling.

Parameters:: pin (int) – BCM GPIO pin number to sample.
Returns:: True when the pin is at logic HIGH, False when it is at logic LOW. If sampling fails the function returns None implicitly after logging the error.
Return type:: bool
Raises:: Exception – Any exception raised by RPi.GPIO is caught and logged via the context logger; nothing is re-raised.

Example

Sample a button connected to pin 4 with the internal pull-up engaged elsewhere:

>>> pressed = not read(4)

Note

Without an external or internal pull resistor, a floating input pin will return non-deterministic values. Call setup() explicitly with the desired pullup argument before relying on read() for noisy or unconnected lines.

See also

input(): Identically-behaving alias retained for API symmetry.

RPi.GPIO.input()

gpio.select_I2C(pn: int = 24, ch: int = -1) → None¶

Select a channel on the Oizom I2C multiplexer.

The Oizom hardware uses a 4-channel I2C mux whose two address-select lines are wired to BCM GPIO 24 and 25. This function maps either a sensor part-number (pn) or an explicit channel index (ch) to the appropriate two-bit address and drives the lines through set(). A 100 ms settling delay follows the switch so that downstream smbus transactions see a stable bus.

Channel mapping (GPIO24, GPIO25):

Channel 0 -> (0, 0): part numbers 0, 18, 23, 24, 29, 53, 54
Channel 1 -> (1, 0): part numbers 1, 32, 33, 34, 35, 36, 38, 39
Channel 2 -> (0, 1): part numbers 2, 25, 26, 27, 28
Channel 3 -> (1, 1): part numbers 3, 4

Parameters:

pn (int) – Sensor part-number used to look up the channel. Defaults to 24 (channel 0). Ignored when ch is not -1.
ch (int) – Optional explicit channel index that overrides the pn lookup when set to a value other than -1. Pass one of 0, 1, 2 or 3. Defaults to -1 (no override).

Returns:

This function performs side effects on the GPIO bus and returns nothing.

Return type:

None

Raises:

Exception – Any exception raised by RPi.GPIO or by the inner calls to set() is caught and logged via the context logger; nothing is re-raised.

Example

Switch the mux to channel 2 before reading sensor 25:

>>> select_I2C(25)
>>> select_I2C(ch=2)

Note

The 100 ms time.sleep(0.1) after switching is empirically tuned for the Oizom mux and matches what other drivers in this repository expect; do not shorten it without retesting the full sensor stack.
If pn does not match any known mapping and ch is left at its default, the address lines are not changed and the mux remains on its current channel; only the settling delay is incurred.
GPIO 24 and 25 are reserved for this mux and should not be re-used by other drivers.

See also

set() RPi.GPIO.output()

gpio.set(pin: int, value: bool) → None¶

Drive a GPIO pin HIGH or LOW, auto-configuring it as output if needed.

If the pin has not yet been configured as an output in the local _pin_modes registry, setup() is invoked first with mode=OUT before the value is written.

Parameters:

pin (int) – BCM GPIO pin number to drive.
value (bool) – Logical level to apply. True drives the pin HIGH (3.3 V on the Pi), False drives it LOW (0 V).

Returns:

This function performs a side effect on hardware and returns nothing.

Return type:

None

Raises:

Exception – Any exception raised by RPi.GPIO is caught and logged via the context logger; nothing is re-raised.

Example

Drive pin 18 HIGH:

>>> set(18, True)

Note

This helper shadows the Python built-in set inside the module namespace. Importers may want to alias it (for example, from drivers.gpio import gpio and then call gpio.set(...)) to avoid the name clash. The auto-configuration behaviour assumes BCM pin numbering.

See also

output(): Identically-behaving alias retained for API symmetry.

RPi.GPIO.output()

gpio.setmode(value: int) → None¶

Select the pin numbering scheme used by RPi.GPIO.

The two supported schemes are:

GPIO.BCM – Broadcom SoC channel numbers (default for this module). Pin numbers match the chip-level GPIO names.
GPIO.BOARD – physical header pin numbers (1-40 on a standard 40-pin Pi header).

Parameters:: value (int) – One of the numbering-mode constants exposed by RPi.GPIO – GPIO.BCM or GPIO.BOARD.
Returns:: This function configures the underlying library and returns nothing.
Return type:: None
Raises:: ValueError – Raised by RPi.GPIO if the mode is invalid or conflicts with a previously-set mode in the same process.

Example

Switch the process to BOARD numbering before configuring pins:

>>> import RPi.GPIO as GPIO
>>> setmode(GPIO.BOARD)

Note

All other helpers in this module assume BCM numbering. If you call this function with GPIO.BOARD you must use header pin numbers consistently for every subsequent call. Switching modes mid-program is not supported by RPi.GPIO.

See also

RPi.GPIO.setmode()

gpio.setup(pin: int, mode: str, pullup: bool | None = None, initial: bool = False) → None¶

Configure a GPIO pin as input or output.

Delegates to RPi.GPIO.setup() and records the chosen direction in the internal _pin_modes registry so that later calls to read() or set() on the same pin can skip re-configuration.

Parameters:

pin (int) – BCM GPIO pin number to configure.
mode (str) – Direction to apply. Must be one of IN ("in") for input or OUT ("out") for output.
pullup (bool | None) – Optional pull resistor selection for inputs. True engages the internal pull-up resistor, False engages the internal pull-down resistor, and None (default) leaves the pin floating. Ignored when mode is "out".
initial (bool) – Initial output level applied when mode is "out". True drives the pin HIGH, False drives it LOW. Defaults to False (LOW).

Returns:

This function configures hardware state and returns nothing.

Return type:

None

Raises:

ValueError – If mode is neither "in" nor "out". The exception is logged via the context logger rather than propagated to the caller.

Example

Configure pin 17 as an output initially driven LOW, and pin 4 as an input with internal pull-up enabled:

>>> setup(17, OUT, initial=False)
>>> setup(4, IN, pullup=True)

Note

Pin numbers are interpreted in BCM numbering. If setmode() has been used to switch to GPIO.BOARD numbering, callers must supply BOARD pin numbers instead.

See also

RPi.GPIO.setup()

gpio.setwarnings(value: bool) → None¶

Enable or disable runtime warnings emitted by RPi.GPIO.

Forwards directly to RPi.GPIO.setwarnings(). When warnings are enabled, RPi.GPIO prints a message if a pin is being configured that was already in use by another process or was not properly cleaned up previously.

Parameters:: value (bool) – True to enable warnings, False to suppress them.
Returns:: This function configures the underlying library and returns nothing.
Return type:: None
Raises:: None – This is a thin pass-through and does not raise on its own.

Example

Re-enable warnings temporarily for debugging:

>>> setwarnings(True)

Note

At import time this module calls GPIO.setwarnings(False) to keep production logs clean. Toggling this back to True is typically only useful during development.

See also

RPi.GPIO.setwarnings()

gpio.HIGH: int = 1¶

gpio.IN: str = 'in'¶

gpio.LOW: int = 0¶

gpio.OUT: str = 'out'¶

gpio._pin_modes¶

gpio.basic_logger¶

gpio.context_logger¶