CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-gpiozero

A simple interface to GPIO devices with Raspberry Pi

—

Pending
Overview
Eval results
Files

composite-devices.mddocs/

Composite Devices

Pre-built configurations for commercial GPIO boards, LED collections, and robotic platforms. Composite devices combine multiple individual devices into cohesive units with simplified control interfaces.

Base Classes

CompositeDevice

Base class for devices composed of multiple sub-devices.

class CompositeDevice(Device):
    def __init__(self, *, pin_factory=None):
        """
        Base class for composite devices.
        
        Parameters:
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    def close(self):
        """Close the device and all sub-devices."""

    @property
    def closed(self) -> bool:
        """Returns True if device is closed."""

    @property
    def value(self) -> tuple:
        """Tuple of all sub-device values."""

    @value.setter
    def value(self, values): ...

CompositeOutputDevice

Base class for composite output devices.

class CompositeOutputDevice(ValuesMixin, SourceMixin, CompositeDevice):
    def __init__(self, *, initial_value=False, pin_factory=None):
        """
        Base class for composite output devices.
        
        Parameters:
        - initial_value: Initial state for all outputs
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    def on(self):
        """Turn on all outputs."""

    def off(self):
        """Turn off all outputs."""

    def toggle(self):
        """Toggle all outputs."""

    def pulse(self, fade_in_time: float = 1, fade_out_time: float = 1, n: int = None, background: bool = True):
        """Pulse all outputs."""

    def blink(self, on_time: float = 1, off_time: float = 1, n: int = None, background: bool = True):
        """Blink all outputs."""

    @property
    def is_active(self) -> bool:
        """Returns True if any output is active."""

LED Collections

LEDBoard

Collection of LEDs indexed by name.

class LEDBoard(CompositeOutputDevice):
    def __init__(self, **named_pins):
        """
        Collection of LEDs with named access.
        
        Parameters:
        - **named_pins: Named pin assignments (e.g., red=17, green=18, blue=19)
        """

    def __getitem__(self, key) -> LED:
        """Access LED by name."""

    def __setitem__(self, key, value):
        """Set LED state by name."""

    @property
    def leds(self) -> dict:
        """Dictionary of all LEDs by name."""

LEDBarGraph

Bar graph representation using multiple LEDs.

class LEDBarGraph(LEDBoard):
    def __init__(self, *pins, pwm=False, active_high=True, initial_value=0, pin_factory=None):
        """
        LED bar graph for displaying values.
        
        Parameters:
        - *pins: Pin numbers for LEDs (in order from low to high)
        - pwm: bool - True for PWM LEDs, False for simple LEDs
        - active_high: bool - True if LEDs are on when pins are HIGH
        - initial_value: float - Initial value to display (0.0-1.0)
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    @property
    def value(self) -> float:
        """Current bar graph value (0.0-1.0)."""

    @value.setter
    def value(self, value: float): ...

    @property
    def lit_count(self) -> int:
        """Number of currently lit LEDs."""

LEDCharDisplay

7-segment character display.

class LEDCharDisplay(CompositeOutputDevice):
    def __init__(self, a, b, c, d, e, f, g, *, dp=None, active_high=True, initial_value=' ', pin_factory=None):
        """
        7-segment character display.
        
        Parameters:
        - a, b, c, d, e, f, g: Pin numbers for segments
        - dp: Pin number for decimal point (optional)
        - active_high: bool - True if segments are on when pins are HIGH
        - initial_value: str - Initial character to display
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    @property
    def char(self) -> str:
        """Current displayed character."""

    @char.setter
    def char(self, value: str): ...

    def display_hex(self, value: int):
        """Display hexadecimal digit (0-F)."""

    def display_decimal(self, value: int):
        """Display decimal digit (0-9)."""

LEDMultiCharDisplay

Multi-character 7-segment display.

class LEDMultiCharDisplay(CompositeOutputDevice):
    def __init__(self, *chars, active_high=True, initial_value=' ', pin_factory=None):
        """
        Multi-character 7-segment display.
        
        Parameters:
        - *chars: LEDCharDisplay objects for each digit position
        - active_high: bool - True if segments are on when pins are HIGH
        - initial_value: str - Initial text to display
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    @property
    def text(self) -> str:
        """Current displayed text."""

    @text.setter
    def text(self, value: str): ...

    def display_int(self, value: int):
        """Display integer value."""

    def display_float(self, value: float, decimal_places: int = 1):
        """Display floating point value."""

Robot Classes

Robot

Generic two-wheeled robot with differential drive.

class Robot(CompositeDevice, SourceMixin):
    def __init__(self, left=None, right=None, *, pwm=True, pin_factory=None):
        """
        Two-wheeled robot with differential drive.
        
        Parameters:
        - left: Motor pins for left wheel (forward, backward) or Motor object
        - right: Motor pins for right wheel (forward, backward) or Motor object  
        - pwm: bool - True for PWM speed control
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    def forward(self, speed: float = 1):
        """Move forward at specified speed (0.0-1.0)."""

    def backward(self, speed: float = 1):
        """Move backward at specified speed (0.0-1.0)."""

    def left(self, speed: float = 1):
        """Turn left at specified speed."""

    def right(self, speed: float = 1):
        """Turn right at specified speed."""

    def stop(self):
        """Stop all movement."""

    def reverse(self):
        """Reverse current movement direction."""

    @property
    def value(self) -> tuple:
        """Current movement as (left_speed, right_speed) tuple."""

    @value.setter
    def value(self, speeds: tuple): ...

    @property
    def is_active(self) -> bool:
        """Returns True if either motor is active."""

    @property
    def left_motor(self) -> Motor:
        """Left motor object."""

    @property
    def right_motor(self) -> Motor:  
        """Right motor object."""

CamJamKitRobot

Robot configuration for CamJam EduKit #3.

class CamJamKitRobot(Robot):
    def __init__(self, *, pwm=True, pin_factory=None):
        """
        CamJam EduKit robot with predefined pin configuration.
        
        Parameters:
        - pwm: bool - True for PWM speed control
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

RyanteckRobot

Robot configuration for Ryanteck MCB robot.

class RyanteckRobot(Robot):
    def __init__(self, *, pwm=True, pin_factory=None):
        """
        Ryanteck MCB robot with predefined pin configuration.
        
        Parameters:
        - pwm: bool - True for PWM speed control
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

PololuDRV8835Robot

Robot using Pololu DRV8835 motor controller.

class PololuDRV8835Robot(Robot):
    def __init__(self, *, pwm=True, pin_factory=None):
        """
        Pololu DRV8835 robot with predefined pin configuration.
        
        Parameters:
        - pwm: bool - True for PWM speed control
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

Commercial GPIO Boards

TrafficLights

Generic traffic light board (red, amber, green).

class TrafficLights(CompositeOutputDevice):
    def __init__(self, red=None, amber=None, green=None, *, pwm=False, initial_value=False, pin_factory=None):
        """
        Traffic light control board.
        
        Parameters:
        - red: int or str - Red LED pin
        - amber: int or str - Amber LED pin  
        - green: int or str - Green LED pin
        - pwm: bool - True for PWM LEDs
        - initial_value: Initial state
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    @property
    def red(self) -> LED:
        """Red LED."""

    @property
    def amber(self) -> LED:
        """Amber LED."""

    @property
    def green(self) -> LED:
        """Green LED."""

    def red_on(self):
        """Turn on red light, turn off others."""

    def amber_on(self):
        """Turn on amber light, turn off others."""

    def green_on(self):
        """Turn on green light, turn off others."""

PiTraffic

Low Voltage Labs PiTraffic board with fixed pins.

class PiTraffic(TrafficLights):
    def __init__(self, *, pwm=False, initial_value=False, pin_factory=None):
        """
        PiTraffic board with predefined pins (9, 10, 11).
        
        Parameters:
        - pwm: bool - True for PWM LEDs
        - initial_value: Initial state
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

PiStop

PiHardware PiStop traffic lights.

class PiStop(TrafficLights):
    def __init__(self, location=None, *, pwm=False, initial_value=False, pin_factory=None):
        """
        PiStop traffic lights for different GPIO locations.
        
        Parameters:
        - location: str - Board location ('A', 'B', 'C', 'D') or None for auto-detect
        - pwm: bool - True for PWM LEDs
        - initial_value: Initial state
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

LEDBoard Variants

PiLiter

Ciseco PiLiter 8-LED board.

class PiLiter(LEDBoard):
    def __init__(self, *, pwm=False, active_high=True, initial_value=False, pin_factory=None):
        """
        PiLiter 8-LED board with predefined pins.
        
        Parameters:
        - pwm: bool - True for PWM LEDs
        - active_high: bool - True if LEDs are on when pins are HIGH
        - initial_value: Initial state
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

PiHutXmasTree

Pi Hut 3D Christmas tree LED board.

class PiHutXmasTree(LEDBoard):
    def __init__(self, *, pwm=False, initial_value=False, pin_factory=None):
        """
        Pi Hut 3D Christmas tree with 24 LEDs.
        
        Parameters:
        - pwm: bool - True for PWM LEDs
        - initial_value: Initial state
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    def on(self, *, led_count: int = None):
        """Turn on LEDs (optionally specify count)."""

    def off(self):
        """Turn off all LEDs."""

Button Boards

ButtonBoard

Collection of buttons with event handling.

class ButtonBoard(CompositeDevice):
    def __init__(self, **named_pins):
        """
        Collection of buttons with named access.
        
        Parameters:
        - **named_pins: Named pin assignments for buttons
        """

    def __getitem__(self, key) -> Button:
        """Access button by name."""

    @property
    def buttons(self) -> dict:
        """Dictionary of all buttons by name."""

    @property
    def when_pressed(self) -> callable:
        """Callback for any button press."""

    @when_pressed.setter
    def when_pressed(self, value: callable): ...

    @property
    def when_released(self) -> callable:
        """Callback for any button release."""

    @when_released.setter
    def when_released(self, value: callable): ...

Specialized Boards

Energenie

Energenie power control sockets.

class Energenie(CompositeOutputDevice):
    def __init__(self, socket=None, *, initial_value=False, pin_factory=None):
        """
        Energenie power control sockets.
        
        Parameters:
        - socket: int - Socket number (1-4) or None for all
        - initial_value: Initial state
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

    def __getitem__(self, socket: int) -> OutputDevice:
        """Access socket by number."""

    def on(self, socket: int = None):
        """Turn on socket (or all if None)."""

    def off(self, socket: int = None):
        """Turn off socket (or all if None)."""

Usage Examples

LED Board Control

from gpiozero import LEDBoard
from time import sleep

# Create named LED board
leds = LEDBoard(red=2, green=3, blue=4, yellow=5)

# Individual LED control
leds.red.on()
leds.green.blink()

# Access by name
leds['blue'].on()
sleep(1)
leds['blue'].off()

# All LEDs
leds.on()
sleep(1)
leds.off()

# Sequence
for led_name in ['red', 'green', 'blue', 'yellow']:
    leds[led_name].on()
    sleep(0.5)
    leds[led_name].off()

LED Bar Graph

from gpiozero import LEDBarGraph, MCP3008
from signal import pause

# 8-LED bar graph
bar = LEDBarGraph(2, 3, 4, 5, 6, 7, 8, 9, pwm=True)
sensor = MCP3008(channel=0)

# Bar graph follows sensor reading
bar.source = sensor

pause()

Robot Control

from gpiozero import Robot
from time import sleep

# Custom robot configuration
robot = Robot(left=(7, 8), right=(9, 10))

# Basic movements
robot.forward()
sleep(2)
robot.backward()
sleep(2)
robot.left()
sleep(1)
robot.right()
sleep(1)
robot.stop()

# Speed control
robot.forward(0.5)  # Half speed
sleep(2)
robot.stop()

# Manual wheel control
robot.value = (1, 0.5)  # Left full, right half
sleep(2)
robot.value = (0, 0)    # Stop

Traffic Light Sequence

from gpiozero import TrafficLights
from time import sleep

lights = TrafficLights(red=2, amber=3, green=4)

def traffic_sequence():
    """Standard UK traffic light sequence."""
    lights.green_on()
    sleep(5)
    
    lights.amber_on()
    sleep(2)
    
    lights.red_on()
    sleep(5)
    
    # Red + Amber (UK style)
    lights.red.on()
    lights.amber.on()
    lights.green.off()
    sleep(2)

# Run sequence
while True:
    traffic_sequence()

Button Board with LEDs

from gpiozero import ButtonBoard, LEDBoard
from signal import pause

buttons = ButtonBoard(a=2, b=3, c=4, d=5)
leds = LEDBoard(red=17, green=18, blue=19, yellow=20)

# Map buttons to LEDs
buttons['a'].when_pressed = leds.red.toggle
buttons['b'].when_pressed = leds.green.toggle
buttons['c'].when_pressed = leds.blue.toggle
buttons['d'].when_pressed = leds.yellow.toggle

# Global button handler
def any_button_pressed():
    print("A button was pressed!")

buttons.when_pressed = any_button_pressed

pause()

7-Segment Display

from gpiozero import LEDCharDisplay
from time import sleep

# 7-segment display (a, b, c, d, e, f, g segments)
display = LEDCharDisplay(2, 3, 4, 5, 6, 7, 8, dp=9)

# Display digits
for digit in "0123456789":
    display.char = digit
    sleep(0.5)

# Display hex digits
for digit in "0123456789ABCDEF":
    display.char = digit
    sleep(0.3)

# Display some letters
for char in "HELLO":
    display.char = char
    sleep(0.5)

Robot with Sensors

from gpiozero import Robot, DistanceSensor, Button
from signal import pause

robot = Robot(left=(7, 8), right=(9, 10))
distance = DistanceSensor(echo=24, trigger=23, threshold_distance=0.3)
stop_button = Button(2)

def obstacle_detected():
    robot.stop()
    print("Obstacle detected! Stopping.")

def path_clear():
    robot.forward(0.5)
    print("Path clear, moving forward.")

def emergency_stop():
    robot.stop()
    print("Emergency stop!")

# Connect sensors to robot
distance.when_in_range = obstacle_detected
distance.when_out_of_range = path_clear
stop_button.when_pressed = emergency_stop

# Start moving
robot.forward(0.5)
pause()

Additional Board Classes

LEDCharFont

Font management for character displays.

class LEDCharFont(MutableMapping):
    def __init__(self, font_file):
        """
        Font for character displays.
        
        Parameters:
        - font_file: str - Path to font definition file
        """

LedBorg

LedBorg RGB LED board.

class LedBorg(RGBLED):
    def __init__(self, *, pwm=True, pin_factory=None):
        """
        LedBorg RGB LED board interface.
        
        Parameters:
        - pwm: bool - Enable PWM for color control (default: True)
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

PiLiterBarGraph

PiLiter bar graph variant.

class PiLiterBarGraph(LEDBarGraph):
    def __init__(self, *, pwm=False, initial_value=False, pin_factory=None):
        """
        PiLiter bar graph LED board.
        
        Parameters:
        - pwm: bool - Enable PWM brightness control (default: False)
        - initial_value: bool - Initial state for all LEDs
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

StatusZero

StatusZero LED board.

class StatusZero(LEDBoard):
    def __init__(self, *, pwm=False, initial_value=False, pin_factory=None):
        """
        StatusZero RGB LED board interface.
        
        Parameters:
        - pwm: bool - Enable PWM brightness control (default: False)
        - initial_value: bool - Initial state for all LEDs
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

StatusBoard

Generic status board interface.

class StatusBoard(CompositeOutputDevice):
    def __init__(self, **named_pins):
        """
        Generic status board with named LED outputs.
        
        Parameters:
        - named_pins: Named GPIO pins for LEDs
        """

SnowPi

SnowPi LED board.

class SnowPi(LEDBoard):
    def __init__(self, *, pwm=False, initial_value=False, pin_factory=None):
        """
        SnowPi LED board interface with snowflake pattern.
        
        Parameters:
        - pwm: bool - Enable PWM brightness control (default: False)
        - initial_value: bool - Initial state for all LEDs
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

TrafficLightsBuzzer

Traffic lights with integrated buzzer.

class TrafficLightsBuzzer(CompositeOutputDevice):
    def __init__(self, red=None, amber=None, green=None, buzzer=None, *, pin_factory=None):
        """
        Traffic lights with buzzer for audio signals.
        
        Parameters:
        - red: int or str - GPIO pin for red LED
        - amber: int or str - GPIO pin for amber LED  
        - green: int or str - GPIO pin for green LED
        - buzzer: int or str - GPIO pin for buzzer
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

FishDish

FishDish LED board.

class FishDish(CompositeOutputDevice):
    def __init__(self, *, pwm=False, initial_value=False, pin_factory=None):
        """
        FishDish LED board with fish-shaped pattern.
        
        Parameters:
        - pwm: bool - Enable PWM brightness control (default: False)
        - initial_value: bool - Initial state for all LEDs
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

TrafficHat

Traffic HAT board.

class TrafficHat(CompositeOutputDevice):
    def __init__(self, *, pin_factory=None):
        """
        Traffic HAT board with LEDs and buzzer.
        
        Parameters:
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

TrafficpHat

Traffic pHAT board.

class TrafficpHat(TrafficLights):
    def __init__(self, *, pin_factory=None):
        """
        Traffic pHAT board with traffic light LEDs.
        
        Parameters:
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

PhaseEnableRobot

Robot using phase/enable motor control.

class PhaseEnableRobot(SourceMixin, CompositeDevice):
    def __init__(self, left=None, right=None, *, pin_factory=None):
        """
        Robot with phase/enable motor control.
        
        Parameters:
        - left: tuple - (phase_pin, enable_pin) for left motor
        - right: tuple - (phase_pin, enable_pin) for right motor
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

PumpkinPi

PumpkinPi LED board.

class PumpkinPi(LEDBoard):
    def __init__(self, *, pwm=False, initial_value=False, pin_factory=None):
        """
        PumpkinPi LED board with pumpkin-shaped pattern.
        
        Parameters:
        - pwm: bool - Enable PWM brightness control (default: False)
        - initial_value: bool - Initial state for all LEDs
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

JamHat

Jam HAT board.

class JamHat(CompositeOutputDevice):
    def __init__(self, *, pin_factory=None):
        """
        Jam HAT board with LEDs, buzzer, and button inputs.
        
        Parameters:
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

Pibrella

Pibrella board.

class Pibrella(CompositeOutputDevice):
    def __init__(self, *, pin_factory=None):
        """
        Pibrella board with LEDs, buzzer, and button inputs.
        
        Parameters:
        - pin_factory: Factory or None - Pin factory for advanced usage
        """

Install with Tessl CLI

npx tessl i tessl/pypi-gpiozero

docs

composite-devices.md

index.md

input-devices.md

output-devices.md

pin-factories.md

spi-devices.md

system-monitoring.md

tone-system.md

tools.md

tile.json