diff --git a/README.md b/README.md index 9e60706..03cd181 100644 --- a/README.md +++ b/README.md @@ -561,9 +561,10 @@ climate: name: "Living Room Heating" # Configure with REST commands ``` -The ["tado-local"](https://github.com/array81/tado-local) Home Assistant custom component is build to work with TadoLocal. +The ["tado-local"](https://github.com/array81/tado-local) Home Assistant custom component is build to work with TadoLocal Server. + +**Full documentation**: See [`home-assistant/README.md`](home-assistant/README.md) for installing TadoLocal Server as App and advanced configuration. -**Contributions welcome!** If you'd like to build a native Home Assistant integration or HACS addon, we'd be happy to review PRs. ### Other Platforms diff --git a/home-assistant/Dockerfile b/home-assistant/Dockerfile index 86026fd..b57c19b 100644 --- a/home-assistant/Dockerfile +++ b/home-assistant/Dockerfile @@ -3,7 +3,12 @@ FROM $BUILD_FROM RUN apk add git py3-pip WORKDIR /usr/src/app -RUN git clone https://github.com/ampscm/TadoLocal.git +# Clone repo metadata, but only check out the todal-local and cfg files to save time and space +RUN git clone --depth 1 --filter=blob:none --sparse https://github.com/AmpScm/TadoLocal.git \ + && cd TadoLocal \ + && git sparse-checkout init --no-cone \ + && git sparse-checkout set tado_local requirements.txt setup.py pyenv.cfg pyproject.toml + WORKDIR /usr/src/app/TadoLocal RUN python -m venv my-venv RUN my-venv/bin/pip install -e . diff --git a/home-assistant/README.md b/home-assistant/README.md index 9a0c985..64e27c4 100644 --- a/home-assistant/README.md +++ b/home-assistant/README.md @@ -1,13 +1,181 @@ -To install this as a Home Assistant add-on, you need to do the following: -- SSH or SFTP into your HA filesystem. -- Under the /addons directory, create a directory named tado-local -- Copy alle the files from the home-assistant folder in this project under the 'tado-local' directory +# TadoLocal Server – Home Assistant App (Add-on) -Then follow the steps that are described on https://developers.home-assistant.io/docs/add-ons/tutorial under 'Installing and testing your add-on'. +![Home Assistant](https://img.shields.io/badge/Home%20Assistant-App-blue) +![Architecture](https://img.shields.io/badge/Architecture-amd64%20%7C%20armhf%20%7C%20armv7-orange) +![License](https://img.shields.io/github/license/AmpScm/TadoLocal) -Before starting, set the IP-address and pincode of the Tado Bridge. See the generic documentation of TadoLocal for more information. +This app runs the **TadoLocal Server** inside Home Assistant, allowing **local communication with Tado devices without relying on the cloud**. -When you start the addon for the first time, check the logs. The logs will display an URL that you need to authenticatie at Tado. +The app exposes a local API that can be used by the **TadoLocal Home Assistant custom integration**. + +--- +# Installation +## Quick Install + +Install the add-on directly into Home Assistant: + +[![Add repository to Home Assistant](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FAmpScm%2FTadoLocal) + +Steps: + +1. Click the button above +2. Click **Open Link** +3. Click **+ Add** +4. Click **Close** +5. Search for **TadoLocal Server** and click on it +6. Click **Install** +7. Follow the [Configuration](#configuration) section **before starting** + +--- + +## Manual Installation + +If you prefer installing manually: + +1. SSH or SFTP into your Home Assistant filesystem +2. Navigate to: + +``` +/addons +``` + +3. Create the directory: + +``` +/addons/tado-local-server +``` + +4. Copy **all files from the `home-assistant` folder** of this repository into that directory. + +Ensure `run.sh` is saved in **Unix format (LF)** and not **Windows format (CRLF)**. + +Example structure: + +``` +/addons/ +└── tado-local-server/ + ├── config.yaml + ├── Dockerfile + ├── run.sh + ├── README.md + ├── icon.png + ├── logo.png + └── translations/ + ├── en.yaml + └── nl.yaml +``` + +5. Restart Home Assistant or reload add-ons. + +Then follow the Home Assistant developer documentation: + +https://developers.home-assistant.io/docs/add-ons/tutorial + +--- + +# Configuration +## Setup Tado Internet Bridge + +Before starting the add-on, configure the following options: + +| Option | Description | +|------|------| +| **Bridge IP** | IP address of your Tado Bridge | +| **Bridge PIN** | HomeKit PIN code of the Tado Bridge | +| **Keep database private** | Determines where the `tado-local.db` file is stored | + +--- + +## Database Location + +If **Keep database private = false** + +The database will be copied to: + +``` +/config/.storage/tado-local.db +``` + +This makes the database accessible from Home Assistant via: + +- Samba +- Terminal +- SSH + +If **Keep database private = true** + +The database stays inside the container: + +``` +/data/tado-local.db +``` + + +## Accessories + +Some devices require **separate pairing sessions**, for example: + +- **Tado Smart AC Control V3+** + +You can add these accessories in the configuration using the **Add** button and providing: + +- Accessory IP address +- HomeKit PIN code + + +--- +# Running TadoLocal Server +## First Startup + +When starting the add-on for the first time: + +1. Open the **Log** tab of the TadoLocal Server add-on +2. A URL will appear that you must open to authenticate with Tado. + +Alternatively: + +1. Click **Open Web UI** on the TadoLocal Server App page +2. The **TadoLocal Web GUI** will open +3. Click **Authenticate** in the Web GUI. (center top) + +--- + +## After Authentication + +After successful authentication: + +- The logs will confirm authentication +- The **TadoLocal services will start** +- The **zones will appear** in the Web GUI + +--- + +# Home Assistant Integration (Devices & Services) + +After the add-on is running successfully, install the **TadoLocal custom integration**: + +https://github.com/array81/tado-local + +Follow the instructions in that repository. + +When configuring the integration, use: `localhost` as the IP address and the configured port (default **4407**). + +--- + +# Updating + +The TadoServer Python code is downloaded directly from GitHub. + +When a new version becomes available, simply click **Rebuild** on the TadoLocal Server add-on page. + +--- + +# Troubleshooting + +If something does not work: + +1. Check the **add-on logs** +2. Verify the **Bridge IP and PIN** +3. Ensure Home Assistant can reach the Tado Bridge -When you have successfully authenticated at Tado, check the logs again. It will confirm the authentication and that the TadoLocal services will start running. diff --git a/home-assistant/config.yaml b/home-assistant/config.yaml index 0efa6c5..401406f 100644 --- a/home-assistant/config.yaml +++ b/home-assistant/config.yaml @@ -1,18 +1,31 @@ name: "TadoLocal Server" description: "TadoLocal Server, based on AmpScm/TadoLocal" -version: "0.1.0" +version: "1.1.1" slug: "tado-local-server" url: "https://github.com/AmpScm/TadoLocal" init: false +webui: "http://[HOST]:[PORT:4407]" arch: - amd64 - armhf - armv7 ports: 4407/tcp: 4407 +map: + - type: homeassistant_config + read_only: false + path: /homeassistant_config options: bridge_ip: "1.2.3.4" bridge_pin: "123-45-678" + keep_db_private: true + log_level: info + accessories: [] schema: bridge_ip: str - bridge_pin: str + bridge_pin: str + keep_db_private: bool + log_level: list(debug|info) + accessories: + - ip: str + pin: str diff --git a/home-assistant/icon.png b/home-assistant/icon.png new file mode 100644 index 0000000..a56014e Binary files /dev/null and b/home-assistant/icon.png differ diff --git a/home-assistant/logo.png b/home-assistant/logo.png new file mode 100644 index 0000000..b1ef98c Binary files /dev/null and b/home-assistant/logo.png differ diff --git a/home-assistant/run.sh b/home-assistant/run.sh index 6282ac2..2b77e2f 100644 --- a/home-assistant/run.sh +++ b/home-assistant/run.sh @@ -1,13 +1,55 @@ #!/usr/bin/with-contenv bashio echo "Tado-local server starting.." CONFIG_PSTH=/data/options.json +ARGS="" # Get the variables from HA BRIDGE_IP="$(bashio::config 'bridge_ip')" -echo "Bridge IP is $BRIDGE_IP" BRIDGE_PIN="$(bashio::config 'bridge_pin')" -echo "Bridge pin is $BRIDGE_PIN" +echo "Bridge:" +echo " IP is $BRIDGE_IP" +echo " pin is $BRIDGE_PIN" +ARGS="${ARGS} --bridge-ip ${BRIDGE_IP} --pin ${BRIDGE_PIN}" + +# Check if log_level is set to debug or trace +LOG_LEVEL="$(bashio::config 'log_level')" +if [ "$LOG_LEVEL" = "debug" ]; then + echo "INFO: Enabling verbose logging for log_level=${LOG_LEVEL}" + ARGS="${ARGS} --verbose" +fi + +# Determine where to store the database based on the keep_db_private option +LOCAL_DB="$(bashio::config 'keep_db_private')" +if [ "$LOCAL_DB" = true ]; then + echo "INFO: keep_db_private is true, using /data/tado-local.db (not accessible outside the container)" + ARGS="${ARGS} --state /data/tado-local.db" +else + echo "INFO: keep_db_private is false, using /homeassistant_config/.storage/tado-local.db (accessible outside the container)" + ARGS="${ARGS} --state /homeassistant_config/.storage/tado-local.db" + if [ -f "/data/tado-local.db" ]; then + # Forward compatibility: if the old database location exists, move it to the new location and use it. + echo "*** WARNING: DB found at /data/tado-local.db. move to new location and use it. ***" + echo "--- mv /data/tado-local.db /homeassistant_config/.storage/tado-local.db" + mv /data/tado-local.db /homeassistant_config/.storage/tado-local.db + fi +fi + +# Get the number of accessories configured in HA +ACCESSORY_COUNT="$(bashio::config 'accessories|length' || echo 0)" +echo "Accessories found: ${ACCESSORY_COUNT}" + +# Loop through the accessories and build the arguments for tado-local server +for ((i=0; i +