BlackBone

BlackBone is a fork of boneIO (boneIO-eu/app_bbb), maintained by SmartHome Wrocław. It adds features that were missing in the original project, developed for and proven in real client installations.

smarthome-wroclaw is not affiliated with, endorsed by, or officially connected to the original boneIO authors. BlackBone is released under the same GNU GPLv3 license as upstream.

Use at your own risk. BlackBone is provided "as is", without warranty of any kind. smarthome-wroclaw accepts no liability for any damage or loss resulting from the use of this software.

Example usage

boneio run -dd -c config.yaml

Installation

sudo apt install -y libopenjp2-7-dev python3-venv libjpeg-dev docker-compose docker.io fonts-dejavu-core fonts-dejavu-extra libffi-dev libfreetype-dev libtiff6 libxcb1 mosquitto
mkdir ~/boneio
python3 -m venv ~/boneio/venv
source ~/boneio/venv/bin/activate
pip3 install --upgrade blackbone
cp ~/venv/lib/python3.13/site-packages/boneio/example_config/*.yaml ~/boneio/

Edit config.yaml

Start app

source ~/boneio/venv/bin/activate
boneio run -c ~/boneio/config.yaml -dd

sed -i 's/^- id:/- name:/' *.yaml

Upgrading an existing controller to BlackBone

Already have a controller running the original boneIO app? SSH into it and run the BlackBone installer:

ssh <user>@<controller-ip>
curl -fsSL https://raw.githubusercontent.com/smarthome-wroclaw/blackbone/main/install.sh | bash

The installer is interactive: it auto-detects your existing virtual environment, offers to back up your current configuration and installed app before touching anything, installs BlackBone, and restarts the boneio service. Your existing config files are left in place.

Controllers running a pre-0.1 BlackBone build

BlackBone restarted its version numbering at 0.1.0, below the 1.x line inherited from boneIO. A controller still running an early BlackBone build (for example 1.6.0.dev1) therefore never sees newer releases under System → Software Update: pip treats 0.1.x as a downgrade. Upgrade such a controller once over SSH:

"$HOME/boneio/venv/bin/pip" install --force-reinstall blackbone
sudo systemctl restart boneio

From then on in-app updates work normally.

Returning to the original boneIO app

The migration is reversible. The safest option is to restore the application backup created by the BlackBone installer. This returns the app to the exact version installed before migration.

SSH into the controller and set the paths below. The examples use the default locations. If the installer reported different paths, use those instead. Replace the timestamp in BACKUP_DIR with the directory created during migration.

VENV_DIR="$HOME/boneio/venv"
BACKUP_DIR="$HOME/boneio/backups/blackbone_migration_YYYYMMDD_HHMMSS"
APP_BACKUP="$(find "$BACKUP_DIR" -maxdepth 1 -type f -name 'stock_black_app_*.tar.gz' -print -quit)"
test -n "$APP_BACKUP" || { echo "Application backup not found"; exit 1; }

sudo systemctl stop boneio
"$VENV_DIR/bin/pip" uninstall --yes blackbone
tar -C "$VENV_DIR" -xzf "$APP_BACKUP"

The installer does not change your YAML configuration. If you changed it after migration and also want to restore the old configuration, inspect and extract its backup before starting the service. Extraction overwrites YAML files with their backed-up copies.

CONFIG_BACKUP="$(find "$BACKUP_DIR" -maxdepth 1 -type f -name 'configuration_*.tar.gz' -print -quit)"
test -n "$CONFIG_BACKUP" || { echo "Configuration backup not found"; exit 1; }
tar -tzf "$CONFIG_BACKUP"
tar -C "$(dirname "$VENV_DIR")" -xzf "$CONFIG_BACKUP"

Verify the restored package, then start the service:

"$VENV_DIR/bin/python" -c 'from importlib.metadata import version; print(version("boneio"))'
"$VENV_DIR/bin/pip" check
sudo systemctl start boneio
sudo systemctl is-active boneio

If you did not create an application backup, reinstall the latest official boneIO release from PyPI instead:

VENV_DIR="$HOME/boneio/venv"
sudo systemctl stop boneio
"$VENV_DIR/bin/pip" uninstall --yes blackbone
"$VENV_DIR/bin/pip" install --upgrade --force-reinstall boneio
sudo systemctl start boneio
sudo systemctl is-active boneio

To install a specific official release, use boneio==VERSION instead of boneio. Review the official boneIO releases and update instructions before choosing a version.

Contributing

Found a bug or have a feature you'd like to see? Issues and pull requests are welcome at smarthome-wroclaw/blackbone.

Polski

BlackBone to fork boneIO (boneIO-eu/app_bbb), utrzymywany przez SmartHome Wrocław. Dodaje funkcje, których brakowało w oryginalnym projekcie, wypracowane i sprawdzone w realnych instalacjach u klientów.

smarthome-wroclaw nie jest powiązane z autorami oryginalnej aplikacji boneIO ani przez nich wspierane. BlackBone jest wydawane na tej samej licencji GNU GPLv3 co projekt źródłowy.

Używasz na własną odpowiedzialność. BlackBone jest dostarczane w stanie „tak jak jest", bez żadnych gwarancji. smarthome-wroclaw nie ponosi odpowiedzialności za jakiekolwiek szkody lub straty wynikające z użytkowania tego oprogramowania.

Przykład użycia

boneio run -dd -c config.yaml

Instalacja

sudo apt install -y libopenjp2-7-dev python3-venv libjpeg-dev docker-compose docker.io fonts-dejavu-core fonts-dejavu-extra libffi-dev libfreetype-dev libtiff6 libxcb1 mosquitto
mkdir ~/boneio
python3 -m venv ~/boneio/venv
source ~/boneio/venv/bin/activate
pip3 install --upgrade blackbone
cp ~/venv/lib/python3.13/site-packages/boneio/example_config/*.yaml ~/boneio/

Edytuj config.yaml

Uruchomienie aplikacji

source ~/boneio/venv/bin/activate
boneio run -c ~/boneio/config.yaml -dd

sed -i 's/^- id:/- name:/' *.yaml

Aktualizacja istniejącego sterownika do BlackBone

Masz już sterownik z zainstalowaną oryginalną aplikacją boneIO? Połącz się z nim przez SSH i uruchom instalator BlackBone:

ssh <user>@<adres-sterownika>
curl -fsSL https://raw.githubusercontent.com/smarthome-wroclaw/blackbone/main/install.sh | bash

Instalator działa interaktywnie: sam wykrywa istniejące środowisko wirtualne, proponuje kopię zapasową aktualnej konfiguracji i zainstalowanej aplikacji zanim cokolwiek zmieni, instaluje BlackBone i restartuje usługę boneio. Istniejące pliki konfiguracyjne pozostają nietknięte.

Sterowniki z buildem BlackBone sprzed 0.1

BlackBone zaczyna numerację wersji od 0.1.0, czyli poniżej linii 1.x odziedziczonej po boneIO. Sterownik z wczesnym buildem BlackBone (na przykład 1.6.0.dev1) nigdy nie zobaczy więc nowszych wydań w System → Aktualizacja oprogramowania — pip traktuje 0.1.x jako cofnięcie wersji. Taki sterownik podnieś jednorazowo przez SSH:

"$HOME/boneio/venv/bin/pip" install --force-reinstall blackbone
sudo systemctl restart boneio

Od tego momentu aktualizacje z poziomu aplikacji działają normalnie.

Powrót do oryginalnej aplikacji boneIO

Migrację można cofnąć. Najbezpieczniej przywrócić kopię aplikacji utworzoną przez instalator BlackBone. Pozwala to wrócić dokładnie do wersji zainstalowanej przed migracją.

Połącz się ze sterownikiem przez SSH i ustaw poniższe ścieżki. Przykład używa domyślnych lokalizacji. Jeżeli instalator wyświetlił inne ścieżki, użyj ich. W BACKUP_DIR zastąp znacznik czasu nazwą katalogu utworzonego podczas migracji.

VENV_DIR="$HOME/boneio/venv"
BACKUP_DIR="$HOME/boneio/backups/blackbone_migration_YYYYMMDD_HHMMSS"
APP_BACKUP="$(find "$BACKUP_DIR" -maxdepth 1 -type f -name 'stock_black_app_*.tar.gz' -print -quit)"
test -n "$APP_BACKUP" || { echo "Nie znaleziono kopii aplikacji"; exit 1; }

sudo systemctl stop boneio
"$VENV_DIR/bin/pip" uninstall --yes blackbone
tar -C "$VENV_DIR" -xzf "$APP_BACKUP"

Instalator nie zmienia konfiguracji YAML. Jeśli konfiguracja została zmieniona po migracji i chcesz również przywrócić jej starszą wersję, sprawdź i rozpakuj kopię przed uruchomieniem usługi. Rozpakowanie nadpisze pliki YAML ich kopiami zapasowymi.

CONFIG_BACKUP="$(find "$BACKUP_DIR" -maxdepth 1 -type f -name 'configuration_*.tar.gz' -print -quit)"
test -n "$CONFIG_BACKUP" || { echo "Nie znaleziono kopii konfiguracji"; exit 1; }
tar -tzf "$CONFIG_BACKUP"
tar -C "$(dirname "$VENV_DIR")" -xzf "$CONFIG_BACKUP"

Sprawdź przywrócony pakiet, a następnie uruchom usługę:

"$VENV_DIR/bin/python" -c 'from importlib.metadata import version; print(version("boneio"))'
"$VENV_DIR/bin/pip" check
sudo systemctl start boneio
sudo systemctl is-active boneio

Jeżeli kopia aplikacji nie została utworzona, zainstaluj najnowsze oficjalne wydanie boneIO z PyPI:

VENV_DIR="$HOME/boneio/venv"
sudo systemctl stop boneio
"$VENV_DIR/bin/pip" uninstall --yes blackbone
"$VENV_DIR/bin/pip" install --upgrade --force-reinstall boneio
sudo systemctl start boneio
sudo systemctl is-active boneio

Aby zainstalować wybrane oficjalne wydanie, użyj boneio==WERSJA zamiast boneio. Przed wyborem wersji sprawdź oficjalne wydania boneIO oraz instrukcję aktualizacji.

Kontrybuowanie

Znalazłeś błąd albo masz pomysł na funkcję? Zgłoszenia (issues) i pull requesty są mile widziane w repozytorium smarthome-wroclaw/blackbone.