Kivy Headless Renderer

This project uses the Kivy framework to create a headless renderer for a Raspberry Pi. The renderer is specifically designed for and tested with the ST7789 SPI display, but it should work with other SPI displays as well. The code utilizes the Adafruit RGB Display library to communicate with the display. The renderer is optimized to not update the LCD if nothing has changed in the frame.

📋 Requirements

Raspberry Pi 4 or 5
SPI Display (tested with ST7789 module)

📦 Installation

You can install it using this handle: headless-kivy-pi@git+https://github.com/ubopod/headless-kivy-pi.git

pip install headless-kivy-pi

To work on a non-RPi environment, run this:

# pip:
pip install headless-kivy-pi[dev]
# poetry:
poetry --group dev headless-kivy-pi

🛠 Usage

Call setup_headless() before inheriting the HeadlessWidget class for the root widget of your application, and provide the optional parameters as needed. For example (these are all default values, you only need to provide the ones you want to change):

setup_headless(
    min_fps=1,
    max_fps=30,
    width=240,
    height=240,
    baudrate=60000000,
    is_debug_mode=False,
    display_class=ST7789,
    double_buffering=True,
    synchronous_clock=True,
    automatic_fps=True,
    clear_at_exit=True,
)

Inherit the HeadlessWidget class for the root widget of your Kivy application. For example:
```
class FboFloatLayout(FloatLayout, HeadlessWidget):
    pass
```
Run the Kivy app as you normally would.

Checkout Ubo App to see a sample implementation.

⚙️ Parameters

These parameters can be set to control the behavior of headless kivy pi:

`min_fps`

Minimum frames per second for when the Kivy application is idle.

`max_fps`

Maximum frames per second for the Kivy application.

`width`

The width of the display in pixels.

`height`

The height of the display in pixels.

`baudrate`

The baud rate for the display connection.

`is_debug_mode`

If set to True, the application will print debug information, including FPS.

`display_class`

The display class to use (default is ST7789).

`double_buffering`

Is set to True, it will let Kivy generate the next frame while sending the last frame to the display.

`synchronous_clock`

If set to True, Kivy will wait for the LCD before rendering next frames. This will cause Headless to skip frames if they are rendered before the LCD has finished displaying the previous frames. If set to False, frames will be rendered asynchronously, letting Kivy render frames regardless of display being able to catch up or not at the expense of possible frame skipping.

`automatic_fps`

If set to True, it will monitor the hash of the screen data, if this hash changes, it will increase the fps to the maximum and if the hash doesn't change for a while, it will drop the fps to the minimum.

`clear_at_exit`

If set to True, it will clear the screen before exiting.

🤝 Contributing

You need to have Poetry installed on your machine.

After having poetry, to install the required dependencies, run the following command in the root directory of the project:

poetry install

⚠️ Important Note

This project has only been tested with the ST7789 SPI display module. Other display modules might not be compatible or may require changing the parameters or even modifications to the code.

🔒 License

This project is released under the Apache-2.0 License. See the LICENSE file for more details.

Metadata

Release files for headless-kivy-pi 0.8.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for headless-kivy-pi 0.8.2
File	Size	Uploaded
headless_kivy_pi-0.8.2.tar.gz	16.4 kB	Jul 2, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for headless-kivy-pi 0.8.2
File	Interpreter	ABI	Platform	Reset
headless_kivy_pi-0.8.2-py3-none-any.whl 18.3 kB Jul 2, 2024	Python 3	none	any	Details

Total release size: 34.7 kB

Release files / headless_kivy_pi-0.8.2.tar.gz

Download URL	headless_kivy_pi-0.8.2.tar.gz
Size	16.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`016ed91def7994a3fa29574398f4186ba361697fdce94e3512d702344da1f7ad`
BLAKE2b-256 checksum How to use checksums	`be10176cb310ba467ed26fafb8ba8e1f5621a747b24d4dc61f47d025494ee6b0`
Upload date	Jul 2, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/5.1.0 CPython/3.12.4`

Release files / headless_kivy_pi-0.8.2-py3-none-any.whl

Download URL	headless_kivy_pi-0.8.2-py3-none-any.whl
Size	18.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`075568a07234a544e77619a293f5481e06e8f5448956000f4eb6e20914684d15`
BLAKE2b-256 checksum How to use checksums	`88a487ad982c288b5adc20e0e0a14b131825536115c49a9ec187c26dbb64f795`
Upload date	Jul 2, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/5.1.0 CPython/3.12.4`