Skip to content

Update SmartThings setup instructions #12967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
frenck merged 2 commits into from
Apr 15, 2020
Merged

Update SmartThings setup instructions #12967

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
42fb31d
Update instructions
andrewsayre Apr 14, 2020
aaf9c14
Tweaks
andrewsayre Apr 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 58 additions & 50 deletions source/_integrations/smartthings.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Smartthings
description: Instructions on setting up Samsung SmartThings within Home Assistant.
title: SmartThings
description: Instructions on setting up SmartThings within Home Assistant.
featured: true
ha_category:
- Hub
Expand All @@ -21,74 +21,63 @@ ha_codeowners:
ha_domain: smartthings
---

Samsung SmartThings is integrated into Home Assistant through the SmartThings Cloud API. The SmartThings integration is the main integration to integrate all SmartThings related platforms. The basic features of this integration include:
SmartThings is integrated into Home Assistant through the SmartThings Cloud API. The features of this integration include:

1. Controlling SmartThings devices with pushed state updates from SmartThings.
2. Entities automatically added, removed, or updated when changed in SmartThings (upon Home Assistant restart).
3. Support for multiple SmartThings accounts and locations, each represented as a unique integration in the front-end configuration.
4. No brokers, bridges, or additional dependencies.
1. Controlling SmartThings devices as Home Assistant entities ([see platforms for supported devices and capabilities](#platforms)).
1. Entities automatically synchronized upon restart of Home Assistant when changed in SmartThings.
1. Support for multiple SmartThings accounts and locations with each represented as an integration instance in Home Assistant.
1. No brokers, bridges, or additional dependencies.

See it in action, with a step-by-step setup guide, thanks to a fan! (v0.87 featured):
## Prerequisites

<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/QZHlhQ7fqrA" frameborder="0" allowfullscreen></iframe>
</div>

## Basic requirements

The SmartThings integration utilizes a webhook to receive push updates from the SmartThings cloud through either a cloudhook or an internet accessible webhook based on whether Home Assistant Cloud is configured and logged in with a non-expired subscription (this is not configurable at this time).

### Cloudhook via Nabu Casa
1. A SmartThings [personal access token](https://account.smartthings.com/tokens).
1. An internet accessible incoming webhook or active Home Assistant Cloud subscription.

If you are using Home Assistant Cloud (Nabu Casa) the integration will create a cloudhook automatically. This greatly simplifies the basic requirements and does not require Home Assistant to be exposed to the internet. **If you have previously setup the integration prior to meeting the requirements for a cloudhook or prior to v0.90.0, you must remove all prior integrations and run through the configuration again.**

1. A [personal access token](https://account.smartthings.com/tokens) tied to a Samsung or SmartThings account (see below for instructions).
2. Home Assistant Cloud is configured and logged-in with a non-expired subscription.

### Webhook
### Personal Access Token (PAT)

1. A [personal access token](https://account.smartthings.com/tokens) tied to a Samsung or SmartThings account (see below for instructions).
2. Home Assistant setup for [remote access](/docs/configuration/remote/) via a domain name secured with SSL. *Self-signed SSL certificates are not supported by the SmartThings Cloud API.*
3. [`base_url` of the HTTP integration](/integrations/http#base_url) set the URL that Home Assistant is available on the internet. SmartThings requires the `base_url` and Home Assistant to use the standard HTTPS port (443).

## Setup instructions

### Create personal access token
The PAT is used to create a Home Assistant SmartApp in your SmartThings account during setup of the integration.

1. Log into the [personal access tokens page](https://account.smartthings.com/tokens) and click '[Generate new token](https://account.smartthings.com/tokens/new)'
2. Enter a token name (can be whatever you want), for example, 'Home Assistant' and select the following authorized scopes:
1. Enter a token name (can be whatever you want), for example, 'Home Assistant' and select the following authorized scopes:
- Devices (all)
- Installed Apps (all)
- Locations (all)
- Apps (all)
- Schedules (all)
- Scenes (all)
3. Click 'Generate token'. When the token is displayed, copy and save it somewhere safe (such as your keystore) as you will not be able to retrieve it again.
1. Click 'Generate token'. When the token is displayed copy and save it somewhere safe (such as your keystore) as you will not be able to retrieve it again.

### Configure Home Assistant
### Webhook

<div class='note info'>
This integration requires an internet accessible incoming webhook to receive push updates from SmartThings. The preferred approach is to subscribe to [Home Assistant Cloud (Nabu Casa)](https://www.nabucasa.com/) and the integration will configure and use a cloudhook automatically. Alternatively, you will have to configure and setup a internet accessible webhook in Home Assistant as described below:

The SmartThings integration is configured exclusively through the front-end. Manual setup through `configuration.yaml` is not available at this time.
1. Setup [remote access](/docs/configuration/remote/) via a domain name secured with SSL. *Self-signed SSL certificates are not supported by the SmartThings Cloud API.*
1. Set [`base_url` of the HTTP integration](/integrations/http#base_url) to the URL that Home Assistant is available on the internet (this must start with `https://`).

</div>
## Setup instructions

After completing the prerequisite steps above you are ready to setup the integration! See [troubleshooting](#troubleshooting) if you are having issues setting up the integration.

1. From the Home Assistant front-end, navigate to 'Configuration' then 'Integrations'. Under 'Set up a new integration' locate 'SmartThings' and click 'Configure'.
2. Enter the personal access token created above and click 'Submit'
3. When prompted, install the SmartApp:
1. Open the SmartThings Classic mobile app. Navigate to 'Automation' and select the 'SmartApps' tab.
2. Click 'Add a SmartApp', scroll to the bottom, and select 'My Apps', then choose 'Home Assistant'.
3. Optionally change the display name and press 'Done'
4. Authorize the app by pressing 'Allow'
4. Return to Home Assistant and click 'Submit'.
1. From Home Assistant, navigate to 'Configuration' then 'Integrations'. Click the plus icon and type/select 'SmartThings'.
1. Confirm the callback URL is correct. If using Home Assistant Cloud it will start with `https://hooks.nabuca.casa`. If the URL is not correct, update your Home Assistant configuration, restart, and try again.
1. Enter your Personal Access Token.
1. Select the SmartThings Location to add to Home Assistant.
1. On the window that opens:
1. Login with your SmartThings account (if not already logged in).
1. Optionally change the display name and click 'Done' on the upper right of the screen.
1. Authorize the integration by clicking 'Allow' on the bottom right of the screen.
1. Click 'Close Window' or close it manually if necessary.
1. Back in Home Assistant click 'Finish'.

<div class='note info'>

Advanced: If you have multiple locations in SmartThings, each can be integrated into Home Assistant. Follow the steps above, then for each subsequent location, install the SmartApp and it will automatically add to Home Assistant. This can be completed during step 3 (install SmartApp) above or at any time after that.
If you want to integrate additional SmartThings accounts or locations, repeat the steps above.

</div>

See the [troubleshooting](#troubleshooting) if you are having issues setting up the integration.
## Removal instructions

To remove the integration from Home Assistant, select the instance from the Home Assistant Integrations page and click the trash icon on the upper right corner. Alternatively, you can remove the SmartApp from the location within the SmartThings application. If the Home Assistant instance that setup the integration is no longer running or functioning, you will need to use this [utility to remove the orphaned SmartApps in your SmartThings account](https://pypi.org/project/hass-smartthings-remove/).

## Events

Expand Down Expand Up @@ -291,12 +280,31 @@ The SmartThings Switch platform lets you control devices that have the [`switch`

### Setup

Perform the following steps if you receive one of the following error messages while attempting to setup the integration (this does not apply when integrated through Home Assistant Cloud):
#### Aborted: Home Assistant is not configured correctly to receive updates from SmartThings

This error message occurs when you do not have an active Home Assistant Cloud (Nabu Casa) subscription and the `base_url` is not configured correctly (it must start with `https`). Update your Home Assistant configuration per the prerequisites above, restart, and try again.

#### Error: The token must be in the UID/GUID format

The personal access token does not match the expected format. Make sure you are copying the entire token and that there are no extraneous characters (such as trailing whitespace) and try again.

#### Error: The token is invalid or no longer authorized

The personal access token entered is not valid or has been deleted. Create a new token per the instructions in the prerequisites and try again.

#### Error: The token does not have the required OAuth scopes

The personal access token entered is valid but does not have the required scopes as outlined in the prerequisites. Create a new token per the instructions in the prerequisites and try again.

#### Error: SmartThings could not validate the webhook URL

SmartThings was unable to reach your Home Assistant instance using the webhook URL. Enable debug logging to see the specific issue and follow the webhook troubleshooting checklist below.

#### Aborted: There are no available SmartThings Locations

- "SmartThings could not validate the endpoint configured in base_url. Please review the integration requirements."
- "Unable to setup the SmartApp. Please try again."
This error message occurs when all of the SmartThings locations under the account linked to the personal access token are already setup in Home Assistant. Ensure you are using the correct personal access token or create an additional location in SmartThings to integrate and try again.

#### Checklist
#### Webhook Troubleshooting Checklist

1. Ensure `base_url` is properly set to the _external address_ that Home Assistant is available to the internet. SmartThings must be able to reach this address.
1. Validate there are no problems with your certificate or SSL configuration by using an online checker, such as [https://www.digicert.com/help/](https://www.digicert.com/help/).
Expand Down