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(port_name, name='button')[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.

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

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()
...

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.

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

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.

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.

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

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.

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

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.

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

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.

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

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.

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()¶

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.

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

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

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.