# 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>
```sh
pip install headless-kivy-pi
```
To work on a non-RPi environment, run this:
```sh
# pip:
pip install headless-kivy-pi[dev]
# poetry:
poetry --group dev headless-kivy-pi
```
## 🛠 Usage
1. 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):
```python
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,
)
```
1. Inherit the `HeadlessWidget` class for the root widget of your Kivy application.
For example:
```python
class FboFloatLayout(FloatLayout, HeadlessWidget):
pass
```
1. Run the Kivy app as you normally would.
Checkout [Ubo App](https://github.com/ubopod/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](https://python-poetry.org/) installed on your machine.
After having poetry, to install the required dependencies, run the following command
in the root directory of the project:
```sh
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](./LICENSE)
file for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/sassanh/headless-kivy-pi/",
"name": "headless-kivy-pi",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "kivy, headless, display, pytest",
"author": "Sassan Haradji",
"author_email": "sassanh@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7a/18/78c4ccd4913a351f7d7ed940a90df542e462dd164a9ee4a74e80f952f222/headless_kivy_pi-0.8.1.tar.gz",
"platform": null,
"description": "# Kivy Headless Renderer\n\nThis project uses the Kivy framework to create a headless renderer\nfor a Raspberry Pi. The renderer is specifically designed for and tested with the\nST7789 SPI display, but it should work with other SPI displays as well. The code\nutilizes the Adafruit RGB Display library to communicate with the display. The\nrenderer is optimized to not update the LCD if nothing has changed in the frame.\n\n## \ud83d\udccb Requirements\n\n- Raspberry Pi 4 or 5\n- SPI Display (tested with ST7789 module)\n\n## \ud83d\udce6 Installation\n\nYou can install it using this handle: headless-kivy-pi@git+<https://github.com/ubopod/headless-kivy-pi.git>\n\n```sh\npip install headless-kivy-pi\n```\n\nTo work on a non-RPi environment, run this:\n\n```sh\n# pip:\npip install headless-kivy-pi[dev]\n# poetry:\npoetry --group dev headless-kivy-pi\n```\n\n## \ud83d\udee0 Usage\n\n1. Call setup_headless() before inheriting the `HeadlessWidget` class for the root\n widget of your application, and provide the optional parameters as needed. For\n example (these are all default values, you only need to provide the ones you want\n to change):\n\n ```python\n setup_headless(\n min_fps=1,\n max_fps=30,\n width=240,\n height=240,\n baudrate=60000000,\n is_debug_mode=False,\n display_class=ST7789,\n double_buffering=True,\n synchronous_clock=True,\n automatic_fps=True,\n clear_at_exit=True,\n )\n ```\n\n1. Inherit the `HeadlessWidget` class for the root widget of your Kivy application.\n For example:\n\n ```python\n class FboFloatLayout(FloatLayout, HeadlessWidget):\n pass\n ```\n\n1. Run the Kivy app as you normally would.\n\nCheckout [Ubo App](https://github.com/ubopod/ubo-app) to see a sample implementation.\n\n### \u2699\ufe0f Parameters\n\nThese parameters can be set to control the behavior of headless kivy pi:\n\n#### `min_fps`\n\nMinimum frames per second for when the Kivy application is idle.\n\n#### `max_fps`\n\nMaximum frames per second for the Kivy application.\n\n#### `width`\n\nThe width of the display in pixels.\n\n#### `height`\n\nThe height of the display in pixels.\n\n#### `baudrate`\n\nThe baud rate for the display connection.\n\n#### `is_debug_mode`\n\nIf set to True, the application will print debug information, including FPS.\n\n#### `display_class`\n\nThe display class to use (default is ST7789).\n\n#### `double_buffering`\n\nIs set to `True`, it will let Kivy generate the next frame while sending the last\nframe to the display.\n\n#### `synchronous_clock`\n\nIf set to `True`, Kivy will wait for the LCD before rendering next frames. This will\ncause Headless to skip frames if they are rendered before the LCD has finished displaying\nthe previous frames. If set to False, frames will be rendered asynchronously, letting\nKivy render frames regardless of display being able to catch up or not at the expense\nof possible frame skipping.\n\n#### `automatic_fps`\n\nIf set to `True`, it will monitor the hash of the screen data, if this hash changes,\nit will increase the fps to the maximum and if the hash doesn't change for a while,\nit will drop the fps to the minimum.\n\n#### `clear_at_exit`\n\nIf set to `True`, it will clear the screen before exiting.\n\n## \ud83e\udd1d Contributing\n\nYou need to have [Poetry](https://python-poetry.org/) installed on your machine.\n\nAfter having poetry, to install the required dependencies, run the following command\nin the root directory of the project:\n\n```sh\npoetry install\n```\n\n## \u26a0\ufe0f Important Note\n\nThis project has only been tested with the ST7789 SPI display module. Other display\nmodules might not be compatible or may require changing the parameters or even modifications\nto the code.\n\n## \ud83d\udd12 License\n\nThis project is released under the Apache-2.0 License. See the [LICENSE](./LICENSE)\nfile for more details.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Headless renderer for Kivy framework",
"version": "0.8.1",
"project_urls": {
"Homepage": "https://github.com/sassanh/headless-kivy-pi/",
"Repository": "https://github.com/sassanh/headless-kivy-pi/"
},
"split_keywords": [
"kivy",
" headless",
" display",
" pytest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f340594bc1cf60047f476c2b8b49c2a4f357c32eef312a421d267706c0729f47",
"md5": "18aaab1d9751eb21f5936de1ef79071e",
"sha256": "201fdc2ed399214c9ba55be1631e0c2fe17601d98b5ef241381127ecfc05ffc7"
},
"downloads": -1,
"filename": "headless_kivy_pi-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18aaab1d9751eb21f5936de1ef79071e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 18391,
"upload_time": "2024-07-01T23:28:03",
"upload_time_iso_8601": "2024-07-01T23:28:03.711449Z",
"url": "https://files.pythonhosted.org/packages/f3/40/594bc1cf60047f476c2b8b49c2a4f357c32eef312a421d267706c0729f47/headless_kivy_pi-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7a1878c4ccd4913a351f7d7ed940a90df542e462dd164a9ee4a74e80f952f222",
"md5": "66999ce9db2d0c127170fa6c7aa3a228",
"sha256": "f847f4380342aca96411eac833f221f111928752d7bdf1f8b387a3df499737f4"
},
"downloads": -1,
"filename": "headless_kivy_pi-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "66999ce9db2d0c127170fa6c7aa3a228",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 16448,
"upload_time": "2024-07-01T23:28:06",
"upload_time_iso_8601": "2024-07-01T23:28:06.939394Z",
"url": "https://files.pythonhosted.org/packages/7a/18/78c4ccd4913a351f7d7ed940a90df542e462dd164a9ee4a74e80f952f222/headless_kivy_pi-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-01 23:28:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sassanh",
"github_project": "headless-kivy-pi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "headless-kivy-pi"
}
JSON
