| Name | ubo-app JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | None |
| Summary | Ubo main app, running on device initialization. A platform for running other apps. |
| upload_time | 2025-02-25 02:08:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.12,>=3.11 |
| license | Apache-2.0 |
| keywords |
home assistance
raspberry pi
rpi
ubo
ubo-pod
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# đ Ubo App
[!PyPI version](https://img.shields.io/pypi/v/ubo-app.svg)](https://pypi.python.org/pypi/ubo-app)
[](https://github.com/ubopod/ubo-app/LICENSE)
[](https://pypi.python.org/pypi/ubo-app)
[](https://github.com/ubopod/ubo-app/actions)
[](https://codecov.io/gh/ubopod/ubo-app)
## đ Overview
Ubo App is a Python application for managing Raspberry Pi utilities and Ubo-specific features.
Example screenshots:
## đ§ Disclaimer
Be aware that at the moment, Ubo app sends crash reports to Sentry. Soon we will limit this to beta versions only.
## âī¸ Notable Features
- Headless WiFi on-boarding with QR code
- Easy headless remote access with SSH and VS Code tunnel
- Install and run Docker apps headlessly
- Access and control basic RPi utilities and settings
- gRPC API for remote control - find sample clients [here](https://github.com/ubopod/ubo-grpc-clients)
## đ Requirements
Ubo app is developed to run on Raspberry Pi 4 and 5. The experience is optimized around Ubo Pod which offers
- a minimal LCD display and GUI with a keypad
- stereo microphone and speakers,
- camera
- LED ring
- sensors
The app functions even if some of these hardware elements are not provided, however some of the features that rely on these hardware components may not function. For example, WiFi onboarding with QR code requires a camera onboard.
## đĻ Installation
### Pre-packaged image
Ubo Pod ships with a pre-flashed MicroSD card that has the app installed on it by default.
If you don't have it, or you just want to set up a fresh device, then:
1. download one of the images from the release section
1. Use Raspberry Pi Images and choose `custom image` to provide the download image file.
1. Write to the image
1. Use the image to boot your Ubo Pod or Raspberry Pi
This is the fastest, easiest, and recommended way to get started with Ubo App.
### Install on existing OS
If you want to install the image on an existing operating system, then read on. Otherwise, skip this section.
---
â ī¸ **Executing scripts directly from the internet with root privileges poses a significant security risk. It's generally a good practice to ensure you understand the script's content before running it. You can check the content of this particular script [here](https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh) before running it.**
---
To install ubo, run this command in a terminal shell:
```bash
curl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\
| sudo bash
```
If you want to install docker service and configure ubo to be able to use it run this:
```bash
curl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\
| sudo WITH_DOCKER=true bash
```
To allow the installer to install the latest alpha version of ubo run this:
```bash
curl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\
| sudo ALPHA=true bash
# or
curl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\
| sudo ALPHA=true WITH_DOCKER=true bash
```
Note that as part of the installation process, these debian packages are installed:
- accountsservice
- dhcpcd
- dnsmasq
- git
- hostapd
- i2c-tools
- libasound2-dev
- libcap-dev
- libegl1
- libgl1
- libmtdev1
- libzbar0
- python3-alsaaudio
- python3-apt
- python3-dev
- python3-gpiozero
- python3-libcamera
- python3-picamera2
- python3-pip
- python3-virtualenv
- rpi-lgpio
Also be aware that ubo-app only installs in `/opt/ubo` and it is not customizable
at the moment.
## đ¤ Contributing
Contributions following Python best practices are welcome.
### âšī¸ī¸ Conventions
- Use `UBO_` prefix for environment variables.
- Use `ubo:` prefix for notification ids used in ubo core and `<service_name>:` prefix for notification ids used in services.
- Use `ubo:` prefix for icon ids used in ubo core and `<service_name>:` prefix for icon ids used in services.
### Development
#### Setting up the development environment
To set up the development environment, you need to [have `uv` installed](https://docs.astral.sh/uv/).
First, clone the repository (you need to have [git-lfs installed](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)):
```bash
git clone https://github.com/ubopod/ubo_app.git
git lfs install
git lfs pull
```
Then, navigate to the project directory and install the dependencies:
```bash
uv sync --dev
```
Now you can run the app with:
```bash
HEADLESS_KIVY_DEBUG=true uv run ubo
```
#### Run the app on the physical device
Add `ubo-development-pod` host in your ssh config at `~/.ssh/config`:
```plaintext
Host ubo-development-pod
HostName <ubopod IP here>
User pi
```
â ī¸*Note: You may want to add the ssh public key to the device's authorized keys (`~/.ssh/authorized_keys`) so that you don't need to enter the password each time you ssh into the device. If you decide to use password instead, you need to reset the password for Pi user first using the GUI on the device by going to Hamburger Menu -> Settings -> System -> Users and select pi user*
Then you need to run this command once to set up the pod for development:
```bash
uv run poe device:deploy:complete
```
After that, you can deploy the app to the device with:
```bash
uv run poe device:deploy
```
To run the app on the device, you can use either of these commands:
```bash
uv run poe device:deploy:restart # gracefully restart the app with systemctl
uv run poe device:deploy:kill # kill the process, which will be restarted by systemd if the service is not stopped
```
#### Running tests on desktop
Easiest way to run tests is to use the provided `Dockerfile`s. To run the tests in a container, you first need to create the development images by running:
```bash
uv run poe build-docker-images
```
Then you can run the tests with:
```bash
docker run --rm -it --name ubo-app-test -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv ubo-app-test
```
You can add arguments to the `pytest` command to run specific tests like this:
```bash
docker run --rm -it --name ubo-app-test -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv ubo-app-test -- <pytest-args>
```
For example, to run only the tests in the `tests/integration/test_core.py` file, you can run:
```bash
docker run --rm -it -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv -v uvo-app-dev-uv-local:/root/.local/share/uv -v ubo-app-dev-uv-venv:/ubo-app/.venv ubo-app-test
```
To pass it command line options add a double-dash before the options:
```bash
docker run --rm -it -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv -v uvo-app-dev-uv-local:/root/.local/share/uv -v ubo-app-dev-uv-venv:/ubo-app/.venv ubo-app-test -- -svv --make-screenshots --override-store-snapshots --override-window-snapshots
```
You can also run the tests in your local environment by running:
```bash
uv run poe test
```
â ī¸**Note:** When running the tests in your local environment, the window snapshots produced by tests may mismatch the expected snapshots. This is because the snapshots are taken with a certain DPI and some environments may have different DPI settings. For example, we are aware that the snapshots taken in macOS have different DPI settings. If you encounter this issue, you should run the tests in a Docker container as described above.
#### Running tests on the device
You need to install dependencies with this command once:
```bash
uv run poe device:test:deps
```
Then you can use the following command each time you want to run the tests:
```bash
uv run poe device:test
```
#### Running linter
To run the linter run the following command:
```bash
uv run poe lint
```
To automatically fix the linting issues run:
```bash
uv run poe lint --fix
```
#### Running type checker
To run the type checker run the following command:
```bash
uv run poe type-check
```
#### QR code
In development environment, the camera is probably not working, as it is relying on `picamera2`, so it may become challenging to test the flows relying on QR code input.
To address this, the camera module, in not-RPi environments, will try reading from `/tmp/qrcode_input.txt` and `/tmp/qrcode_input.png` too. So, whenever you encounter a QR code input, you can write the content of the QR code in the text file path or put the qrcode image itself in the image file path and the application will read it from there and continue the flow.
Alternatively you may be able to provide the input in the web-ui (needs refresh at the moment) or provide it by `InputProvideAction` in grpc channel.
## đ 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": null,
"name": "ubo-app",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.11",
"maintainer_email": "Sassan Haradji <me@sassanh.com>",
"keywords": "home assistance, raspberry pi, rpi, ubo, ubo-pod",
"author": null,
"author_email": "Sassan Haradji <me@sassanh.com>",
"download_url": "https://files.pythonhosted.org/packages/db/14/d67cb6d12ac704c54a94061d30a0cc27e24530ec5feca18fa415ee140645/ubo_app-1.2.0.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 Ubo App\n\n[!PyPI version](https://img.shields.io/pypi/v/ubo-app.svg)](https://pypi.python.org/pypi/ubo-app)\n[](https://github.com/ubopod/ubo-app/LICENSE)\n[](https://pypi.python.org/pypi/ubo-app)\n[](https://github.com/ubopod/ubo-app/actions)\n[](https://codecov.io/gh/ubopod/ubo-app)\n\n## \ud83c\udf1f Overview\n\nUbo App is a Python application for managing Raspberry Pi utilities and Ubo-specific features.\n\n\n\nExample screenshots:\n\n\n\n## \ud83d\udea7 Disclaimer\n\nBe aware that at the moment, Ubo app sends crash reports to Sentry. Soon we will limit this to beta versions only.\n\n## \u2699\ufe0f Notable Features\n\n- Headless WiFi on-boarding with QR code\n- Easy headless remote access with SSH and VS Code tunnel\n- Install and run Docker apps headlessly\n- Access and control basic RPi utilities and settings\n- gRPC API for remote control - find sample clients [here](https://github.com/ubopod/ubo-grpc-clients)\n\n## \ud83d\udccb Requirements\n\nUbo app is developed to run on Raspberry Pi 4 and 5. The experience is optimized around Ubo Pod which offers\n\n- a minimal LCD display and GUI with a keypad\n- stereo microphone and speakers,\n- camera\n- LED ring\n- sensors\n\nThe app functions even if some of these hardware elements are not provided, however some of the features that rely on these hardware components may not function. For example, WiFi onboarding with QR code requires a camera onboard.\n\n## \ud83d\udce6 Installation\n\n### Pre-packaged image\n\nUbo Pod ships with a pre-flashed MicroSD card that has the app installed on it by default.\n\nIf you don't have it, or you just want to set up a fresh device, then:\n\n1. download one of the images from the release section\n1. Use Raspberry Pi Images and choose `custom image` to provide the download image file.\n1. Write to the image\n1. Use the image to boot your Ubo Pod or Raspberry Pi\n\nThis is the fastest, easiest, and recommended way to get started with Ubo App.\n\n### Install on existing OS\n\nIf you want to install the image on an existing operating system, then read on. Otherwise, skip this section.\n\n---\n\n\u26a0\ufe0f **Executing scripts directly from the internet with root privileges poses a significant security risk. It's generally a good practice to ensure you understand the script's content before running it. You can check the content of this particular script [here](https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh) before running it.**\n\n---\n\nTo install ubo, run this command in a terminal shell:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\\\n | sudo bash\n```\n\nIf you want to install docker service and configure ubo to be able to use it run this:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\\\n | sudo WITH_DOCKER=true bash\n```\n\nTo allow the installer to install the latest alpha version of ubo run this:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\\\n | sudo ALPHA=true bash\n# or\ncurl -sSL https://raw.githubusercontent.com/ubopod/ubo-app/main/ubo_app/system/install.sh\\\n | sudo ALPHA=true WITH_DOCKER=true bash\n```\n\nNote that as part of the installation process, these debian packages are installed:\n\n- accountsservice\n- dhcpcd\n- dnsmasq\n- git\n- hostapd\n- i2c-tools\n- libasound2-dev\n- libcap-dev\n- libegl1\n- libgl1\n- libmtdev1\n- libzbar0\n- python3-alsaaudio\n- python3-apt\n- python3-dev\n- python3-gpiozero\n- python3-libcamera\n- python3-picamera2\n- python3-pip\n- python3-virtualenv\n- rpi-lgpio\n\nAlso be aware that ubo-app only installs in `/opt/ubo` and it is not customizable\nat the moment.\n\n## \ud83e\udd1d Contributing\n\nContributions following Python best practices are welcome.\n\n### \u2139\ufe0f\ufe0f Conventions\n\n- Use `UBO_` prefix for environment variables.\n- Use `ubo:` prefix for notification ids used in ubo core and `<service_name>:` prefix for notification ids used in services.\n- Use `ubo:` prefix for icon ids used in ubo core and `<service_name>:` prefix for icon ids used in services.\n\n### Development\n\n#### Setting up the development environment\n\nTo set up the development environment, you need to [have `uv` installed](https://docs.astral.sh/uv/).\n\nFirst, clone the repository (you need to have [git-lfs installed](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)):\n\n```bash\ngit clone https://github.com/ubopod/ubo_app.git\ngit lfs install\ngit lfs pull\n```\n\nThen, navigate to the project directory and install the dependencies:\n\n```bash\nuv sync --dev\n```\n\nNow you can run the app with:\n\n```bash\nHEADLESS_KIVY_DEBUG=true uv run ubo\n```\n\n#### Run the app on the physical device\n\nAdd `ubo-development-pod` host in your ssh config at `~/.ssh/config`:\n\n```plaintext\nHost ubo-development-pod\n HostName <ubopod IP here>\n User pi\n```\n\n\u26a0\ufe0f*Note: You may want to add the ssh public key to the device's authorized keys (`~/.ssh/authorized_keys`) so that you don't need to enter the password each time you ssh into the device. If you decide to use password instead, you need to reset the password for Pi user first using the GUI on the device by going to Hamburger Menu -> Settings -> System -> Users and select pi user*\n\nThen you need to run this command once to set up the pod for development:\n\n```bash\nuv run poe device:deploy:complete\n```\n\nAfter that, you can deploy the app to the device with:\n\n```bash\nuv run poe device:deploy\n```\n\nTo run the app on the device, you can use either of these commands:\n\n```bash\nuv run poe device:deploy:restart # gracefully restart the app with systemctl\nuv run poe device:deploy:kill # kill the process, which will be restarted by systemd if the service is not stopped\n```\n\n#### Running tests on desktop\n\nEasiest way to run tests is to use the provided `Dockerfile`s. To run the tests in a container, you first need to create the development images by running:\n\n```bash\nuv run poe build-docker-images\n```\n\nThen you can run the tests with:\n\n```bash\ndocker run --rm -it --name ubo-app-test -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv ubo-app-test\n```\n\nYou can add arguments to the `pytest` command to run specific tests like this:\n\n```bash\ndocker run --rm -it --name ubo-app-test -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv ubo-app-test -- <pytest-args>\n```\n\nFor example, to run only the tests in the `tests/integration/test_core.py` file, you can run:\n\n```bash\ndocker run --rm -it -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv -v uvo-app-dev-uv-local:/root/.local/share/uv -v ubo-app-dev-uv-venv:/ubo-app/.venv ubo-app-test\n```\n\nTo pass it command line options add a double-dash before the options:\n\n```bash\ndocker run --rm -it -v .:/ubo-app -v ubo-app-dev-uv-cache:/root/.cache/uv -v uvo-app-dev-uv-local:/root/.local/share/uv -v ubo-app-dev-uv-venv:/ubo-app/.venv ubo-app-test -- -svv --make-screenshots --override-store-snapshots --override-window-snapshots\n```\n\nYou can also run the tests in your local environment by running:\n\n```bash\nuv run poe test\n```\n\n\u26a0\ufe0f**Note:** When running the tests in your local environment, the window snapshots produced by tests may mismatch the expected snapshots. This is because the snapshots are taken with a certain DPI and some environments may have different DPI settings. For example, we are aware that the snapshots taken in macOS have different DPI settings. If you encounter this issue, you should run the tests in a Docker container as described above.\n\n#### Running tests on the device\n\nYou need to install dependencies with this command once:\n\n```bash\nuv run poe device:test:deps\n```\n\nThen you can use the following command each time you want to run the tests:\n\n```bash\nuv run poe device:test\n```\n\n#### Running linter\n\nTo run the linter run the following command:\n\n```bash\nuv run poe lint\n```\n\nTo automatically fix the linting issues run:\n\n```bash\nuv run poe lint --fix\n```\n\n#### Running type checker\n\nTo run the type checker run the following command:\n\n```bash\nuv run poe type-check\n```\n\n#### QR code\n\nIn development environment, the camera is probably not working, as it is relying on `picamera2`, so it may become challenging to test the flows relying on QR code input.\n\nTo address this, the camera module, in not-RPi environments, will try reading from `/tmp/qrcode_input.txt` and `/tmp/qrcode_input.png` too. So, whenever you encounter a QR code input, you can write the content of the QR code in the text file path or put the qrcode image itself in the image file path and the application will read it from there and continue the flow.\n\nAlternatively you may be able to provide the input in the web-ui (needs refresh at the moment) or provide it by `InputProvideAction` in grpc channel.\n\n## \ud83d\udd12 License\n\nThis project is released under the Apache-2.0 License. See the [LICENSE](./LICENSE) file for more details.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Ubo main app, running on device initialization. A platform for running other apps.",
"version": "1.2.0",
"project_urls": null,
"split_keywords": [
"home assistance",
" raspberry pi",
" rpi",
" ubo",
" ubo-pod"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "71eb13d7ba9f1e7ce3842cfc8b56d569d940c0c0c79dcc4f9eeedc6a6ff0dede",
"md5": "97b0a6155c6502e0b9bc9fdb3ac1e78f",
"sha256": "434939c8c19139bfa67fb5e53908bb7ce4d27b9bc3b15636c26bb19c83769da7"
},
"downloads": -1,
"filename": "ubo_app-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "97b0a6155c6502e0b9bc9fdb3ac1e78f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.11",
"size": 58772187,
"upload_time": "2025-02-25T02:08:37",
"upload_time_iso_8601": "2025-02-25T02:08:37.736248Z",
"url": "https://files.pythonhosted.org/packages/71/eb/13d7ba9f1e7ce3842cfc8b56d569d940c0c0c79dcc4f9eeedc6a6ff0dede/ubo_app-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "db14d67cb6d12ac704c54a94061d30a0cc27e24530ec5feca18fa415ee140645",
"md5": "8c208e22a1df73133c21f696fd8fcf15",
"sha256": "d19a9fdf2e519bee44d2c6370926c293e8bf775b8bde4f3c3a8c338bd59e727f"
},
"downloads": -1,
"filename": "ubo_app-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "8c208e22a1df73133c21f696fd8fcf15",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.11",
"size": 58688125,
"upload_time": "2025-02-25T02:08:48",
"upload_time_iso_8601": "2025-02-25T02:08:48.006748Z",
"url": "https://files.pythonhosted.org/packages/db/14/d67cb6d12ac704c54a94061d30a0cc27e24530ec5feca18fa415ee140645/ubo_app-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-25 02:08:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ubo-app"
}
