Skip to content

HowToInstall

hsakoh edited this page Dec 16, 2024 · 6 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 will work 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 can 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. Disable

        WebhookService:
          UseWebhook: false
          UseNgrok: true
          NgrokAuthToken: <Configuration required only when using Webhook with ngrok>
          HostUrl: <Configuration required only when using Webhook without ngrok>
      2. Via Ngrok (Recommended)

        1. Sign up for an ngrok account.
        2. Copy your ngrok authtoken from your ngrok dashboard.
        WebhookService:
          UseWebhook: true
          UseNgrok: true
          NgrokAuthToken: _________________ngrokauthtoken__________________
          HostUrl: <Configuration required only when using Webhook without ngrok>
      3. Without Ngrok(Home Assistant OS directly receives)

        WebhookService:
          UseWebhook: true
          UseNgrok: false
          NgrokAuthToken: <Configuration required only when using Webhook with ngrok>
          HostUrl: http://<your public ip address>:8098
      Setting Key Default Value Description
      WebhookService:UseWebhook true If receiving Webhooks, set to true.
      WebhookService:UseNgrok true If using Ngrok for Webhook reception, set to true.
      WebhookService:NgrokAuthToken - If using Ngrok, set up the Ngrok authentication token.
      WebhookService:HostUrl - This must be configured if Ngrok is not used. See details below.
    4. Others

      • AutoStartServices
        • After rebooting the Home Assistant OS or upgrading add-on version, the service will start automatically.
        • It is recommended to enable 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
      AutoStartServices: true
      LogLevel: Trace
      Setting Key Default Value Description
      AutoStartServices false If various internal services should start automatically when add-on is started, set to true.
      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.
      For more details, refer to Using Retained Config Messages.
      MessageRetain:State false To enable retention for MQTT state messages, set to true.
      For more details, refer to Using Retained State Messages.
      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" column of this CSV.
  4. Start the add-on, open the Ingress page, and proceed to the device settings.

Differences in Webhook Reception Methods

This add-on supports integration with Ngrok for webhook reception.

Via Ngrok (Recommended)

When configured, add-on will internally download and install Ngrok, establish a session with Ngrok via outbound connections, and enable the capability to receive webhooks from SwitchBot by waiting for incoming connections.

There is no need to open a port towards the internet.

Before using Ngrok, carefully read its terms of use, sign up, obtain an authentication token, and configure it within add-on.

During the startup of the internal service for webhooks, Ngrok will be launched if configured, and the URL will be registered for the webhook using the SwitchBot API.

Without Ngrok(Home Assistant OS directly receives)

To enable webhooks without using Ngrok, configure your environment so that add-on's port 8098 can be accessed from the internet.

Add-on itself will listen for requests at http://<your home assistant private ip address>:8098/webhook.

Configure the URL in the settings, including the protocol, hostname, and port that are reachable from the internet in your environment, excluding /webhook.

During the startup of the internal service for webhooks, use the SwitchBot API to register this URL for the webhook.

Advanced Add-on Installation Method

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

As long as you have an environment where .NET 8'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. Refer to _docker-compose/docker-compose.yaml for instructions on running the image.Key points are as follows.

    • 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 8 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 8 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.