diff --git a/source/_integrations/withings.markdown b/source/_integrations/withings.markdown index b51901c4c86..55803de8940 100644 --- a/source/_integrations/withings.markdown +++ b/source/_integrations/withings.markdown @@ -14,7 +14,9 @@ ha_domain: withings The `withings` sensor platform consumes data from various health products produced by [Withings](https://www.withings.com). -## Setup +## Setup (Simple) + +For simplicity, these instructions assume your installation uses Home Assistant Cloud. ### Step 1 - Create a Withings Account @@ -25,41 +27,66 @@ Values for your account: - Logo: Any reasonable picture will do. - Description: Personal app for collecting my data. - Contact Email: Your email address -- Callback Uri: `https://your-domain-name/auth/external/callback` - Withings will check if this URL is accessible (HTTP HEAD) upon submitting the form. If you are using the Home Assistant Cloud, this URL will look like `https://YOUR_NABU_CASA_ID.ui.nabu.casa/auth/external/callback`. +- Callback Uri: `https://YOUR_NABU_CASA_ID.ui.nabu.casa/auth/external/callback`. - Company: Home Assistant Once saved, the "Client Id" and "Consumer Secret" fields will be populated. You will need these in the next step. ### Step 2 - Configure Home Assistant -```yaml -# Example configuration.yaml entry -withings: - client_id: CLIENT_ID - client_secret: CONSUMER_SECRET - profiles: - - USER_PROFILE_NAME -``` +- Add the Withings configuration YAML. + ```yaml + # Example configuration.yaml entry + withings: + client_id: CLIENT_ID + client_secret: CONSUMER_SECRET + profiles: + - USER_PROFILE_NAME + ``` + Withings supports multiple profiles per account. Each profile has a person's name to help distinguish whose data you're looking at. While the profile provided here can be arbitrary, it is recommended you use the same name from the Withings profile. This will make it easier to distinguish whose data you're looking at. +- Confirm your YAML configuration is valid by using the `Check Config` tool (see note). + - Note: In order for "Check Configuration" to be visible, you must enable "Advanced Mode" on your user profile. The "Check Configuration" tool can be found by clicking "Configuration" from the sidebar (cog icon) and then clicking "Server Control". +- Restart Home Assistant. -Withings supports multiple profiles per account. Each profile has a person's name to help distinguish whose data you're looking at. While the profile provided here can be arbitrary, it is recommended you use the same name from the Withings profile. This will make it easier to distinguish whose data you're looking at. ### Step 3 - Authorize Home Assistant -- Confirm your YAML configuration is valid by using the `Check Config` tool (see note). - - Note: In order for "Check Configuration" to be visible, you must enable "Advanced Mode" on your user profile. The "Check Configuration" tool can be found by clicking "Configuration" from the sidebar (cog icon) and then clicking "Server Control". -- Restart Home Assistant. -- Go to the integrations page. -- Add a Withings integration. This will open a new tab/window on the withings site. -- On the Withings site, choose the profile of the data you want to sync. -- Authorize the application. Your browser will redirect you to the redirect uri you provided during account setup. - - Note: If you get a browser error saying the site is inaccessible, you can modify the - `http://domain` portion of the URL to something you know is accessible, locally or publicly. For example, `http://localhost:8123`. - This occurs when the base URL provided by Home Assistant to Withings is not accessible to the outside world. - Changing the domain will not affect how data is synchronized. -- Once authorized, the tab/window will close and the integration page will prompt to select a profile. Select the profile you chose while on the withings site. +- Add the Withings integration. +- Once authorized, the tab/window will close and the integration page will prompt to select a profile. Select the profile you chose while on the Withings site. - Note: It's important you select the same profile from the previous step. Choosing a different one will result in Home Assistant displaying the wrong data. - Data will synchronize immediately and update every 5 minutes. +## Setup (Advanced) +For advanced users who are NOT using Home Assistant Cloud. This is not intended to be a complete step-by-step guide. + +### Requirements + +Withings will validate (with HTTP HEAD) these requirements each time you save your Withings developer account. When these checks fail, the Withings UI is not always clear about why. + +- Home Assistant (For create/update of Withings developer account): + - Publicly accessible. + - Running on a fully qualified domain name. + - Running over HTTPS signed by a globally recognized Certificate Authority. Let's Encrypt will work. +- Home Assistant (For adding the integration) + - Home Assistant's `external_url` needs to be set to match the `redirect uri` provided for your Withings account. + +### Steps + +- Create a developer account with the same steps from the instructions above. + - The `redirect uri` should look like `https:///auth/external/callback`. +- Configure Home Assistant's URL. This guarantees Withings will receive the proper redirect_uri. When adding the integration, Withings will throw an error if this is not setup correctly. + ```yaml + homeassistant: + external_url: https:// + ``` +- Configure the Withings integration in your configuration YAML (see above). +- Add the integration (see above). + - The following only applied if you chose to close off Home Assistant from the public after setting up your Withings account. + After authorizing finishing authorization, your browser will redirect back to `https:///auth/external/callback`. Since that is no longer public, + your browser will return an error saying it could not connect. You can get around this by modifying the URL (in the browser) + to point to your local address of Home Assistant. So your browser's URL looked like `https:///auth/external/callback` + but now change it to something like `https://192.168.1.11:8123/auth/external/callback`. + ## Configuration ```yaml @@ -87,7 +114,7 @@ profiles: ## Bonus: Template Sensors to Convert Kilograms to Pounds -In a text editor, replace ```USER_PROFILE_NAME``` in the template sensors below with your withings User Profile Name defined in the Withings integration configuration. +In a text editor, replace ```USER_PROFILE_NAME``` in the template sensors below with your Withings User Profile Name defined in the Withings integration configuration. {% raw %}