-
Notifications
You must be signed in to change notification settings - Fork 1
HowToInstall
-
Preparation
This add-on sends SwitchBot device information to the Home Assistant's MQTT integration, enabling operation.
-
Install MQTT Broker
First, Install the MQTT broker.
The recommended setup method is to use the Mosquitto MQTT broker add-on.
-
Configure MQTT Integration
Follow the instructions on this page to set up which broker the MQTT integration exchanges information with.
-
-
Adding add-on Repository and Installing add-on
-
Add the public repository of add-on image from the button below.
-
If the above button does not work, follow the steps below to add the repository.
- Navigate to add-on store in the Home Assistant UI (Supervisor in the left menu, then Add-on Store on the top tab)
- Select the three vertical dots in the upper right-hand corner and select repositories
- In the Manage add-on repositories screen enter the URL for
https://github.com/hsakoh/ha-addon
and click add - 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.
-
-
Add-on Configuration
-
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 hostnameMqtt: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
. -
-
SwitchBot API Key & Secret
-
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. -
-
Webhook
-
Disable
WebhookService: UseWebhook: false UseNgrok: true NgrokAuthToken: <Configuration required only when using Webhook with ngrok> HostUrl: <Configuration required only when using Webhook without ngrok>
-
Via Ngrok (Recommended)
- Sign up for an ngrok account.
- Copy your ngrok authtoken from your ngrok dashboard.
WebhookService: UseWebhook: true UseNgrok: true NgrokAuthToken: _________________ngrokauthtoken__________________ HostUrl: <Configuration required only when using Webhook without ngrok>
-
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. -
-
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, NoneMessageRetain: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. - AutoStartServices
-
-
Start the add-on, open the Ingress page, and proceed to the device settings.
This add-on supports integration with Ngrok for webhook reception.
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.
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.
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.
-
Container image
Add-on images are published on GitHub Container Registry and DockerHub.
-
GitHub Container Registry
-
DockerHub
-
-
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
.
- Expose port
This procedure assumes a Windows environment with .NET 8 SDK installed. While it is possible to build on Linux, Adjust the scripts accordingly.
-
Execute ./_compile_self/dotnet_publish.ps1 at the root of the repository.
-
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 onaarch64
andarmv7
.
- It has been confirmed to work not only on
- Open the solution file in Visual Studio and execute the application.
- Configure the app setting to appsettings.Development_Example.json, and then rename it to
appsettings.Development.json
.
This procedure assumes a Windows environment with .NET 8 SDK installed. While it is possible to build on Linux, Adjust the scripts accordingly.
- Execute ./_compile_self/dotnet_publish.ps1 at the root of the repository.
- Place the contents of the _compile_self folder into
HA-OS /addons/switchbot-mqtt
. - Check for updates on the Home Assistant add-on page and install add-on.
- Place the contents of both the src folder and _build_on_haos folder into
HA-OS /addons/switchbot-mqtt
. - If the HA-OS machine is resource-limited, this method might lead to extended downtime while building (installing) processes occur. Not recommended.
- Check for updates on the Home Assistant add-on page and install add-on.