6. API - pi-top Maker Architecture (PMA) Components

The Foundation & Expansion Plates and all the parts included in the Foundation & Robotics Kit are known as the pi-top Maker Architecture (PMA).

Each PMA component has a Python class provided for it.

Check out Key Concepts: pi-top Maker Architecture for useful information to get started with using PMA.

6.1. Button

Note

This is a Digital Component which connects to a Digital Port [D0-D7].

from time import sleep

from pitop import Button

button = Button("D5")


def on_button_pressed():
    print("Pressed!")


def on_button_released():
    print("Released!")


button.when_pressed = on_button_pressed
button.when_released = on_button_released

while True:
    if button.is_pressed is True:  # When button is pressed it will return True
        print(button.value)
    sleep(1)

class pitop.pma.Button(*args, **kwargs)[source]

Encapsulates the behaviour of a push-button.

A push-button is a simple switch mechanism for controlling some aspect of a circuit.

Parameters:

port_name (str) – The ID for the port to which this component is connected
name (str) – Component name, defaults to button. Used to access this component when added to a pitop.Pitop object.

property own_state: Representation of an object state that will be used to determine the current state of an object.

close()[source]

Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.

This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.

You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.

For example, if you have a buzzer connected to port D0, but then wish to attach an LED instead:

>>> from pitop import Buzzer, LED
>>> bz = Buzzer("D0")
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED("D0")
>>> led.blink()

Device descendents can also be used as context managers using the with statement. For example:

>>> from pitop import Buzzer, LED
>>> with Buzzer("D0") as bz:
...     bz.on()
...
>>> with LED("D0") as led:
...     led.on()
...

property active_time: The length of time (in seconds) that the device has been active for. When the device is inactive, this is None.

property closed: Returns True if the device is closed (see the close() method). Once a device is closed you can no longer use any other methods or properties to control or query the device.

property config: Returns a dictionary with the set of parameters that can be used to recreate an object.

static ensure_pin_factory()

Ensures that Device.pin_factory is set appropriately.

This is called implicitly upon construction of any device, but there are some circumstances where you may need to call it manually. Specifically, when you wish to retrieve board information without constructing any devices, e.g.:

Device.ensure_pin_factory()
info = Device.pin_factory.board_info

If Device.pin_factory is not None, this function does nothing. Otherwise it will attempt to locate and initialize a default pin factory. This may raise a number of different exceptions including ImportError if no valid pin driver can be imported.

classmethod from_config(config_dict): Creates an instance of a Recreatable object with parameters in the provided dictionary.

classmethod from_file(path): Creates an instance of an object using the JSON file from the provided path.

property held_time: The length of time (in seconds) that the device has been held for. This is counted from the first execution of the when_held event rather than when the device activated, in contrast to active_time. If the device is not currently held, this is None.

property hold_repeat: If True, when_held will be executed repeatedly with hold_time seconds between each invocation.

property hold_time: The length of time (in seconds) to wait after the device is activated, until executing the when_held handler. If hold_repeat is True, this is also the length of time between invocations of when_held.

static import_class(module_name, class_name): Imports a class given a module and a class name.

property inactive_time: The length of time (in seconds) that the device has been inactive for. When the device is active, this is None.

property is_active: Returns True if the device is currently active and False otherwise. This property is usually derived from value. Unlike value, this is always a boolean.

property is_held: When True, the device has been active for at least hold_time seconds.

property is_pressed: Returns True if the device is currently active and False otherwise. This property is usually derived from value. Unlike value, this is always a boolean.

property pin: The Pin that the device is connected to. This will be None if the device has been closed (see the close() method). When dealing with GPIO pins, query pin.number to discover the GPIO pin (in BCM numbering) that the device is connected to.

property pressed_time: The length of time (in seconds) that the device has been active for. When the device is inactive, this is None.

print_config()

print_state()

property pull_up: If True, the device uses a pull-up resistor to set the GPIO pin “high” by default.

save_config(path): Stores the set of parameters to recreate an object in a JSON file.

property state: Returns a dictionary with the state of the current object and all of its children.

property value: Returns 1 if the button is currently pressed, and 0 if it is not.

property values: An infinite iterator of values read from value.

wait_for_active(timeout=None)

Pause the script until the device is activated, or the timeout is reached.

Parameters:: timeout (float or None) – Number of seconds to wait before proceeding. If this is None (the default), then wait indefinitely until the device is active.

wait_for_inactive(timeout=None)

Pause the script until the device is deactivated, or the timeout is reached.

Parameters:: timeout (float or None) – Number of seconds to wait before proceeding. If this is None (the default), then wait indefinitely until the device is inactive.

wait_for_press(timeout=None)

Pause the script until the device is activated, or the timeout is reached.

Parameters:: timeout (float or None) – Number of seconds to wait before proceeding. If this is None (the default), then wait indefinitely until the device is active.

wait_for_release(timeout=None)

Pause the script until the device is deactivated, or the timeout is reached.

Parameters:: timeout (float or None) – Number of seconds to wait before proceeding. If this is None (the default), then wait indefinitely until the device is inactive.

when_activated

The function to run when the device changes state from inactive to active.

This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that activated it will be passed as that parameter.