api_pitop_device.rst

API - pi-top Device

Pitop

This class represents a pi-top device. Each of the on-board features of pi-tops can be accessed from this object.

Note

This class has been built with pi-top [4] in mind, as is in early development. You may notice that some features do not behave as expected on other platforms.

If you would like to help us with development, please refer to the Contributing document in this repository for information!

Here is some sample code demonstrating how the various subsystems of a pi-top [4] can be accessed and used:

.. literalinclude:: ../examples/system/pitop_overview.py

Although it is possible to access pi-top subsystems individually, it is recommended to access them via this class.

Class Reference: Pitop

.. autoclass:: pitop.Pitop
    :exclude-members: instance
    :members:

All pi-tops come with some software-controllable onboard hardware. These sections of the API make it easy to access and change the state of your pi-top hardware.

Using the Pitop object

Attaching objects and saving configuration to a file

.. literalinclude:: ../examples/system/pitop_save_configuration.py

Loading an existing configuration

.. literalinclude:: ../examples/system/pitop_load_configuration.py

pi-top Battery

This class provides a simple way to check the current onboard pi-top battery state, and handle some state change events.

This class will work with original pi-top, pi-top [3] and pi-top [4]. pi-topCEED has no onboard battery, and so will not work.

.. literalinclude:: ../examples/system/battery.py

Class Reference: pi-top Battery

.. autoclass:: pitop.battery.Battery

pi-top Display

This class provides a simple way to check the current onboard pi-top display state, and handle state change events.

This class will work with original pi-top, pi-topCEED and pi-top [3].

Note

Not compatible with pi-top [4].

pi-top [4] has no onboard display, and the official pi-top [4] FHD Display is not software-controllable.

.. literalinclude:: ../examples/system/display.py

Class Reference: pi-top Display

.. autoclass:: pitop.display.Display

pi-top [4] Miniscreen

The miniscreen of the pi-top [4] can be found on the front, comprised of an 128x64 pixel OLED screen and 4 programmable buttons.

Check out :ref:`Key Concepts: pi-top [4] Miniscreen<key_concepts:pi-top [4] Miniscreen>` for useful information about how this class works.

Using the Miniscreen's OLED Display

The OLED display is an array of pixels that can be either on or off. Unlike the pixels in a more advanced display, such as the monitor you are most likely reading this on, the display is a "1-bit monochromatic" display. Text and images can be displayed by directly manipulating the pixels.

The :class:`pitop.miniscreen.Miniscreen` class directly provides display functions for the OLED.

Displaying text

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_hello_world.py

Showing an image

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_image_file.py

Loop a GIF

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_animated_image_loop.py

Displaying an GIF once

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_animated_image_once_simple_way.py

Displaying an GIF once through frame by frame

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_animated_image_once.py

Displaying an GIF looping in background

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_animated_image_loop_in_background.py

Handling basic 2D graphics drawing and displaying

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_2d_graphics.py

Displaying a clock

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_clock.py

Display a particle-based screensaver

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_particles.py

Prim's algorithm

.. literalinclude:: ../examples/system/miniscreen/miniscreen_display_prims_algorithm.py

2-Player Pong Game

.. literalinclude:: ../examples/system/miniscreen/miniscreen_play_pong_game.py

Class Reference: pi-top [4] Miniscreen

.. autoclass:: pitop.miniscreen.Miniscreen
    :inherited-members:

Using the Miniscreen's Buttons

The miniscreen's buttons are simple, and behave in a similar way to the other button-style components in this SDK. Each miniscreen button can be queried for their "is pressed" state, and also invoke callback functions for when pressed and released.

The :class:`pitop.miniscreen.Miniscreen` class provides these buttons as properties:

>>> from pitop import Pitop
>>> pitop = Pitop()
>>> miniscreen = pitop.miniscreen
>>> miniscreen.up_button
<pitop.miniscreen.miniscreen.MiniscreenButton object at 0xb3e44e50>
>>> miniscreen.down_button
<pitop.miniscreen.miniscreen.MiniscreenButton object at 0xb3e44d30>
>>> miniscreen.select_button
<pitop.miniscreen.miniscreen.MiniscreenButton object at 0xb3e44e90>
>>> miniscreen.cancel_button
<pitop.miniscreen.miniscreen.MiniscreenButton object at 0xb3e44e70>

Here is an example demonstrating 2 ways to make use of these buttons:

.. literalinclude:: ../examples/system/miniscreen/miniscreen_buttons.py

Class Reference: pi-top [4] Miniscreen Button

.. autoclass:: pitop.miniscreen.miniscreen.MiniscreenButton