Skip to content

HowToInstall

Jump to bottom
hsakoh edited this page May 30, 2026 · 13 revisions

How to install add-on

Install add-on to Home Assistant OS (Recommended)

  1. Preparation

    This add-on sends SwitchBot device information to the Home Assistant's MQTT integration, enabling operation.

    1. Install MQTT Broker

      First, Install the MQTT broker.

      The recommended setup method is to use the Mosquitto MQTT broker add-on.

    2. Configure MQTT Integration

      Follow the instructions on this page to set up which broker the MQTT integration exchanges information with.

  2. Adding add-on Repository and Installing add-on

    • Add the public repository of add-on image from the button below.

      Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.

      • If the above button does not work, follow the steps below to add the repository.

        1. Navigate to add-on store in the Home Assistant UI (Supervisor in the left menu, then Add-on Store on the top tab)
        2. Select the three vertical dots in the upper right-hand corner and select repositories
        3. In the Manage add-on repositories screen enter the URL for https://github.com/hsakoh/ha-addon and click add
        4. After adding the repository scroll to the bottom of the list of addons or use search to find the addon

    • Select add-on and install it.

  3. Add-on Configuration

    1. MQTT Broker

      • If you simply introduced the Mosquitto MQTT broker add-on, it works with the default values.

        This is because it can receive the information necessary for connection from the Supervisor API of Home Assistant OS.

        Mqtt:
  AutoConfig: true
  Host: ""
  Port: 1883
  Id: ""
  Pw: ""
  Tls: false

      • If you have introduced the Mosquitto MQTT broker add-on with a changed configuration, or if you are using another broker, enter the values.

        Mqtt:
  AutoConfig: false
  Host: 192.168.0.100
  Port: 1883
  Id: mqtt-user
  Pw: mqtt-user-password
  Tls: false
      Setting Key Default Value Description
      Mqtt:AutoConfig true For users of the default Home Assistant Mosquitto integration, connection details can be detected via the Home Assistant Supervisor API. Therefore, this value should be set to true
      Mqtt:Host - MQTT Broker
      Specify the hostname
      Mqtt:Port 1883 Specify the port number.
      Mqtt:Id - If authentication is required, specify the ID
      Mqtt:Pw - If authentication is required, specify the PW.
      Mqtt:Tls false If TLS connection is required, set to true.

    2. SwitchBot API Key & Secret

      1. Obtain and configure the token and secret according to the SwitchBotApi documentation.

        SwitchBot:
  ApiBaseUrl: https://api.switch-bot.com/v1.1/
  ApiKey: >-
    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
  ApiSecret: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
      Setting Key Default Value Description
      SwitchBot:ApiBaseUrl https://api.switch-bot.com/v1.1/ API Base URL
      SwitchBot:ApiKey - Obtain and configure the open token according to the SwitchBotApi documentation.The token is 96 characters long.
      SwitchBot:ApiSecret - Obtain and configure the secret key according to the SwitchBotApi documentation.The secret is 32 characters long.

    3. Webhook

      1. Disabled

        WebhookService:
  TunnelMode: Disabled

      2. Via Ngrok (account required)

        1. Sign up for an ngrok account.
        2. Copy your ngrok authtoken from your ngrok dashboard.
        WebhookService:
  TunnelMode: Ngrok
  NgrokAuthToken: _________________ngrokauthtoken__________________

      3. Via TryCloudflare / Quick Tunnel (no account needed)

        WebhookService:
  TunnelMode: TryCloudflare

      4. Via Cloudflare Zero Trust tunnel (fixed URL, account required)

        1. Create a tunnel in the Cloudflare Zero Trust dashboard and obtain the tunnel token.
        2. In the dashboard, go to Networks > Connectors > Create a tunnel.
        3. Select Cloudflared.
        4. Enter any tunnel name you like, then record the eyJ... token included in the shown startup command.
        5. Configure the public hostname by choosing the subdomain and domain you want to use.
        6. In the service settings, set Type to HTTP and URL to 127.0.0.1:8098, then complete the setup.
        WebhookService:
  TunnelMode: CloudflareZeroTrust
  CloudflareTunnelToken: _________________cloudflaretunneltoken__________________
  HostUrl: https://your-fixed-domain.example.com

      5. Direct (Home Assistant OS directly receives)

        WebhookService:
  TunnelMode: HostUrl
  HostUrl: http://<internet-reachable-hostname-of-homeassistant>:8098
      Setting Key Default Value Description
      WebhookService:TunnelMode TryCloudflare Select webhook reception mode. One of: Disabled, HostUrl, Ngrok, TryCloudflare, CloudflareZeroTrust.
      WebhookService:NgrokAuthToken - Required when TunnelMode is Ngrok. Set the Ngrok authentication token.
      WebhookService:HostUrl - Required when TunnelMode is HostUrl. Also required for CloudflareZeroTrust (the fixed public URL configured in the Cloudflare dashboard).
      WebhookService:CloudflareTunnelToken - Required when TunnelMode is CloudflareZeroTrust. Obtain from the Cloudflare Zero Trust dashboard.

    4. Others

      • AutoStartServices
        • After rebooting the Home Assistant OS or upgrading add-on version, the service will start automatically.
        • We recommend enabling this after configuring the device and confirming that it works without any problems.
      • LogLevel
        • If trouble occurs, set the log level to Trace, check the log, and create an Issue on Github.
      • EnforceDeviceTypes
        • There are rare cases where devices, such as new ones, do not include the device type in their API responses. In such cases, you can specify a device type to be forcibly recognized based on the device ID.
      EnforceDeviceTypes:
    - DeviceId: <K10+ DeviceId>
    DeviceType: Robot Vacuum Cleaner S1
    - DeviceId: <Hub Mini2 DeviceId>
    DeviceType: Hub Mini
MessageRetain: 
  Entity: true
  State: false
ImageFetch:
  MaxRetries: 25
  RetryIntervalMs: 1000
DeviceStatePersistence: false
AutoStartServices: true
ExitOnServiceFailure: false
LogLevel: Trace
      Setting Key Default Value Description
      AutoStartServices false If various internal services should start automatically when add-on is started, set to true.
      ExitOnServiceFailure false When enabled, the application exits if any internal service (MQTT, Polling, or Webhook) enters a failed state. This allows the Home Assistant Supervisor's watchdog to automatically restart the add-on and recover from transient failures.
      DeviceStatePersistence false When enabled, the last device state is persisted and continuously sent to the state topic.
      This helps reduce the duration during which MQTT sensors are in an "unknown" state after restarting Home Assistant.
      Specifically, it reduces the occurrence of warning logs in the MQTT integration in scenarios such as when a webhook is not triggered after a restart. (This also applies when webhooks are received without polling.)
      The downside is that persisting the state involves writing to the file system each time a state notification is made.
      LogLevel Trace Set the log level. Specify one of the following values:
      Trace, Debug, Information, Warning, Error, Critical, None
      MessageRetain:Entity true To enable retention for MQTT configuration messages, set to true.
      See Using Retained Config Messages for more details.
      MessageRetain:State false To enable retention for MQTT state messages, set to true.
      See Using Retained State Messages for more details.
      ImageFetch:MaxRetries 25 Maximum number of retry attempts when fetching a device image (e.g., camera snapshot) from a presigned URL returns a 404 response.
      ImageFetch:RetryIntervalMs 1000 Interval in milliseconds between image fetch retry attempts.
      EnforceDeviceTypes[]:DeviceId - There are rare cases where devices, such as new ones, do not include the device type in their responses. In such cases, you can specify a device type to be forcibly recognized based on the device ID.
      EnforceDeviceTypes[]:DeviceType - Use the value found in the "ApiDeviceTypeString" field of this JSON files.

  4. Start the add-on, open the Ingress page, and continue to the device settings.

Differences in Webhook Reception Methods

This add-on supports the following five modes for webhook reception, configurable via WebhookService:TunnelMode.

Disabled

Webhook reception is turned off. Only polling will be used for device state updates.

HostUrl

Configure your environment so that add-on's port 8098 is reachable from the internet. Set HostUrl to the publicly accessible base URL (excluding /webhook).

Add-on listens at http://<your home assistant private ip address>:8098/webhook and registers that URL with SwitchBot Cloud on startup.

Via Ngrok

When configured, add-on internally downloads and installs Ngrok, establishes a session via outbound connections, and enables webhook reception without opening an inbound port.

Before using Ngrok, read its terms of use, sign up, obtain an authentication token, and configure NgrokAuthToken.

Via TryCloudflare / Quick Tunnel

Uses Cloudflare TryCloudflare (Quick Tunnel) — no Cloudflare account or pre-configuration is needed. A random temporary https://xxxxx.trycloudflare.com URL is issued automatically at each startup.

Before using it, review Cloudflare's terms, privacy policy, and related legal notice.

No inbound port needs to be opened. The URL changes every time the add-on restarts.

Powered by CloudflaredKit.

Via Cloudflare Zero Trust Tunnel

Uses a permanent Cloudflare Zero Trust tunnel with a fixed URL configured in the Cloudflare dashboard.

  1. In the Cloudflare Zero Trust dashboard, go to Networks > Connectors and select Create a tunnel.
  2. Select Cloudflared.
  3. Enter any tunnel name you like, then copy the eyJ... token included in the startup command.
  4. Configure the public hostname by choosing the subdomain and domain you want to use.
  5. In the service settings, set Type to HTTP and URL to 127.0.0.1:8098, then complete the setup.
  6. Set CloudflareTunnelToken to the obtained token.
  7. Set HostUrl to the fixed public URL you configured in the Cloudflare dashboard (used to register with SwitchBot Cloud).

No inbound port needs to be opened, and the URL is stable across restarts.

Powered by CloudflaredKit.

Advanced Add-on Installation Method

Add-on is created as a .NET 10 Blazor Web App.

As long as you have an environment where .NET 10's Blazor Web App operates, you can basically run it anywhere.

Running as an independent Docker container

  1. Container image

    Add-on images are published on GitHub Container Registry and DockerHub.

  2. See _docker-compose/docker-compose.yaml for instructions on running the image. Key points:

    • Expose port 8099 for WebUI.
    • Expose port 8098 if you need to receive webhooks.
    • Mount the /data volume.
    • Configure add-on using options_Example.json as a reference, rename it to options.json, and place it directly under the mounted /data.

The procedure for building the app yourself and building add-on image

This procedure assumes a Windows environment with .NET 10 SDK installed. While it is possible to build on Linux, Adjust the scripts accordingly.

  1. Execute ./_compile_self/dotnet_publish.ps1 at the root of the repository.

  2. Build the Docker image using the following command.

    docker build `
"./_compile_self" `
--build-arg BUILD_FROM="ghcr.io/home-assistant/amd64-base:latest" `
--build-arg BUILD_ARCH="amd64" `
--progress=plain `
--label org.opencontainers.image.source=https://github.com/hsakoh/switchbot-mqtt
    • It has been confirmed to work not only on amd64 but also on aarch64 and armv7.

Running on Windows OS as a BlazorWebApp (for developers/debugging)

  1. Open the solution file in Visual Studio and execute the application.
  2. Configure the app setting to appsettings.Development_Example.json, and then rename it to appsettings.Development.json.

Pre-Compiling and Publishing the .NET App, then Building the Docker Image on HA-OS

This procedure assumes a Windows environment with .NET 10 SDK installed. While it is possible to build on Linux, Adjust the scripts accordingly.

  1. Execute ./_compile_self/dotnet_publish.ps1 at the root of the repository.
  2. Place the contents of the _compile_self folder into HA-OS /addons/switchbot-mqtt.
  3. Check for updates on the Home Assistant add-on page and install add-on.

Compiling and Publishing the .NET App while Building the Docker Image on HA-OS

  1. Place the contents of both the src folder and _build_on_haos folder into HA-OS /addons/switchbot-mqtt.
  2. If the HA-OS machine is resource-limited, this method might lead to extended downtime while building (installing) processes occur. Not recommended.
  3. Check for updates on the Home Assistant add-on page and install add-on.

Clone this wiki locally