Skip to content

Installation

dkwolf1 edited this page Nov 22, 2026 · 4 revisions

Installation

Requirements

  • Home Assistant 2025.12 or newer
  • Local network access from Home Assistant to the main Deco
  • Access to the Deco's local web administration page
  • The Deco owner account password
  • Username admin

Manager accounts are intended for the mobile app and do not authenticate against the local web API used by this integration.

Marketplace or HACS

Add the repository below as a custom integration repository under Settings > Marketplace (Home Assistant 2026.11 and newer) or HACS > Integrations (older versions). Install the integration, then restart Home Assistant.

Repository URL:

https://github.com/dkwolf1/ha-deco

Manual installation

  1. Open the Home Assistant configuration directory containing configuration.yaml.

  2. Create custom_components if it does not exist.

  3. Copy the complete custom_components/tplink_deco directory from the release into:

    <config>/custom_components/tplink_deco
    
  4. Confirm that this file exists:

    <config>/custom_components/tplink_deco/manifest.json
    
  5. Restart Home Assistant completely.

Do not copy only __init__.py, and do not create an extra nested directory such as custom_components/tplink_deco/tplink_deco.

Switching from the original repository

  1. Create a Home Assistant backup and note your existing Deco entity IDs.
  2. Add dkwolf1/ha-deco as a custom repository. If Marketplace or HACS reports that the same integration is already installed, remove the old download through Marketplace or HACS before installing from the new source. Do not delete the configured integration under Devices & services.
  3. Install the latest stable ha-deco release, then fully restart Home Assistant. Both repositories use the same custom_components/tplink_deco directory; do not manage it from both repositories.
  4. Verify the installed version, repository, existing devices and entities, and polling. Restore the backup if the migration does not work as expected.

Add the integration

  1. Open Settings > Devices & services.

  2. Select Add integration.

  3. Search for TP-Link Deco.

  4. Enter the local web address of the main Deco, for example:

    http://192.168.68.1
    

    or:

    https://192.168.68.1
    
  5. Leave the username as admin.

  6. Enter the Deco owner password.

  7. Disable Verify SSL certificate is valid when the browser warns that the Deco certificate is self-signed.

  8. Submit the form.

Recommended account arrangement

Using the owner account in the Deco app or browser can invalidate the integration's active session. A stable arrangement is:

  • reserve the owner credentials for Home Assistant;
  • create a separate manager account for normal use of the Deco mobile app;
  • remain signed out of owner sessions while diagnosing authentication problems.

Integration does not appear after installation

Check all of the following:

  • Home Assistant was fully restarted, not only reloaded;
  • the directory is exactly custom_components/tplink_deco;
  • manifest.json is directly inside that directory;
  • the downloaded integration version is current;
  • Marketplace or HACS does not show a pending restart or update;
  • the Home Assistant log does not contain an import or requirements error.

For manual installations, compare the version in manifest.json with the release you intended to install.

Updating an existing installation

Back up Home Assistant before updating. Use the current stable release unless a maintainer asks you to test a specific prerelease.

  • For Marketplace/HACS, install the update and fully restart Home Assistant.
  • For manual updates, back up the old integration folder and replace all files with the complete folder from the same release, including new Python modules and translations. Fully restart Home Assistant afterward.
  • Do not delete the configured integration, its devices, or registry files merely to update the code.
  • Verify the loaded version on the integration page. A reload alone does not replace already-imported Python modules.

v3.15.0 preserves existing configuration entries and migrates the polling switch's old unique ID to an entry-specific ID while preserving its entity ID. Existing automations should continue to use the same switch. Syslog forwarding remains off until explicitly enabled.

Historical beta releases remain available for reference. Use the latest stable ha-deco release for normal use.