Skip to content

Updated README.md #232

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

Open
snoorkwashanging wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Updated README.md #232

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
46 changes: 23 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ The Govee integration allows you to control and monitor lights and switches usin

## Installation

* The installation is done inside [HACS](https://hacs.xyz/) (Home Assistant Community Store). If you don't have HACS, you must install it before adding this integration. [Installation instructions here.](https://hacs.xyz/docs/setup/download)
* The installation is done inside [HACS](https://hacs.xyz/) (Home Assistant Community Store). If you don't have HACS, you must install it before adding this integration. [Installation instructions here.](https://hacs.xyz/docs/use/download/download/)
* Once HACS is installed, navigate to the 'Integrations' tab in HACS and search for the 'Govee' integration there. Click "Download this repository in HACS". On the next screen, select "Download". Once fully downloaded, restart HomeAssistant.
* In the sidebar, click 'Configuration', then 'Devices & Services'. Click the + icon to add "Govee" to your Home Assistant installation. An API key
is required, you need to obtain it in the 'Govee Home' app on your mobile device. This can be done from the Account Page (Far right icon at the bottom) > Settings (top right icon) > About Us > Apply for API Key. The key will be sent to your account email.
is required; you need to obtain it in the 'Govee Home' app on your mobile device. This can be done from the Account Page (Far right icon at the bottom) > Settings (top right icon) > About Us > Apply for API Key. The key will be sent to your account email.

## Sponsor

Expand All @@ -23,7 +23,7 @@ We think so. It is used often, and the support thread is active.

![usage statistics per version](https://raw.githubusercontent.com/LaggAt/actions/main/output/goveestats_installations.png)

Usage Data is taken from Home Assistant analytics, and plotted over time by us. You need to enable analytics if you want to show here.
Usage Data is taken from Home Assistant analytics and plotted over time by us. You need to enable analytics if you want to show here.

## Is there an issue right now?

Expand All @@ -33,32 +33,32 @@ This graph uses the same library to do simple checks. If you see round dots on t

## Pulling or assuming state

Some devices do not support pulling state. In this case we assume the state on your last input.
Some devices do not support pulling state. In this case, we assume the state of your last input.
For others, we assume the state just after controlling the light, but will otherwise request it from the cloud API.

## DISABLING state updates for specific attributes

You shouldn't use this feature in normal operation, but if something is broke e.g. on Govee API you could help yourself and others on the forum with a little tweak.
You shouldn't use this feature in normal operation, but if something is broken, e.g., on the Govee API, you could help yourself and others on the forum with a little tweak.

Not all attribute updates can be disabled, but most can. Fiddling here could also lead to other misbehavours, but it could help with some issues.
Not all attribute updates can be disabled, but most can. Fiddling here could also lead to other misbehaviours, but could help with some issues.

Let's talk about an example:

### What if power_state isn't correctly returned from API?
### What if power_state isn't correctly returned from the API?

We can have state from two sources: 'API' and 'HISTORY'. History for example means, when we turn on a light we already guess the state will be on, so we set a history state of on before we get data from the API. In the default configuration you could also see this, as it shows two buttons until the final state from API arrives.
We can have state from two sources: 'API' and 'HISTORY'. History, for example, means that when we turn on a light, we already guess the state will be on, so we set a history state of on before we get data from the API. In the default configuration, you could also see this, as it shows two buttons until the final state from the API arrives.

![two-button-state](https://community-assets.home-assistant.io/original/3X/d/7/d7d2ee09520672e7671fdeed5bb461fcfaab8493.png)

So let's say we have an issue, that the ON/OFF state from API is wrong, we always get OFF. (This happended, and this is why I developed that feature). If we disable the power state we get from API we could work around this, and thats exactly what we do:
So let's say we have an issue, that the ON/OFF state from the API is wrong, we always get OFF. (This happened, and this is why I developed that feature.) If we disable the power state we get from the API, we could work around this, and that's exactly what we do:

1. 'API' or 'History': state from which source do we want to disable? In our example the API state is wrong, as we could see in logs, so we choose 'API'
2. Look up the attribute you want to disable in GoveeDevice data class. Don't worry, you don't need to understand any of the code here. [Here is that data class (click)](https://github.com/LaggAt/python-govee-api/blob/master/govee_api_laggat/govee_dtos.py). In our Example we will find 'power_state'
3. Next, in Home Assistant we open Configuration - Integrations and click on the options on the Govee integration. Here is an example how this config option could look:
1. 'API' or 'History': state from which source do we want to disable? In our example, the API state is wrong, as we can see in the logs, so we choose 'API'
2. Look up the attribute you want to disable in the GoveeDevice data class. Don't worry; you don't need to understand any of the code here. [Here is that data class (click)](https://github.com/LaggAt/python-govee-api/blob/master/govee_api_laggat/govee_dtos.py). In our example, we will find 'power_state'
3. Next, in Home Assistant, we open Configuration - Integrations and click on the options on the Govee integration. Here is an example of how this config option could look:

![DISABLE state updates option](https://community-assets.home-assistant.io/original/3X/6/c/6cffe0de8b100ef4efc0e460482ff659b8f9444c.png)

4. With the information from 1. and 2. we could write a string disabling power_state from API. This will do the trick for our case:
4. With the information from 1. and 2., we could write a string disabling power_state from the API. This will do the trick for our case:
```
API:power_state
```
Expand All @@ -70,13 +70,13 @@ API:online;HISTORY:online

[If you fix an issue like that, consider helping other users on the forum thread (click).](https://community.home-assistant.io/t/govee-integration/228516/438?u=laggat)

ALWAYS REMEMBER: this should always be a temporarly workaround, if you use it in daily business you should probably request a feature or bug fix :)
ALWAYS REMEMBER: this should always be a temporary workaround, if you use it in daily business, you should probably request a feature or bug fix :)

To remind you disabling it asap, this wil log a warning on every update.
To remind you, disabling it asap, this will log a warning on every update.

## What is config/govee_learning.yaml

Usually you don't have to do anything here - just in case something feels wrong read on:
Usually, you don't have to do anything here - just in case something feels wrong, read on:

```
40:83:FF:FF:FF:FF:FF:FF:
Expand All @@ -89,9 +89,9 @@ Usually you don't have to do anything here - just in case something feels wrong
Different Govee devices use different settings. These will be learned by the used library, or can be configured by you.

* set_brightness_max: is autolearned, defines the range to set the brightness to 0-100 or 0-254.
* get_brightness_max: is autolearned, defines the range how to interpet brightness state (also 0-100 or 0-254).
* before_set_brightness_turn_on: Configurable by you, default false. When true, if the device is off and you set the brightness > 0 the device is turned on first, then after a second the brightness is set. Some device don't turn on with the set brightness command.
* config_offline_is_off: Configurable by you, default false. This is useful if your device is e.g. powered by a TV's USB port, where when the TV is off, the LED is also off. Usually we stay in the state we know, this changes this to OFF state when the device disconnects.
* get_brightness_max: is autolearned, defines the range of how to interpret brightness state (also 0-100 or 0-254).
* before_set_brightness_turn_on: Configurable by you, default false. When true, if the device is off and you set the brightness > 0, the device is turned on first, then after a second, the brightness is set. Some devices don't turn on with the set brightness command.
* config_offline_is_off: Configurable by you, default false. This is useful if your device is, for example, powered by a TV's USB port, where, when the TV is off, the LED is also off. Usually, we stay in the state we know, but this changes to the OFF state when the device disconnects.

## Support

Expand All @@ -109,11 +109,11 @@ logger:
govee_api_laggat: debug
```

Then in Settings - Logs click on “full logs” button and add them to the bug report after removing personal data.
Then, in Settings - Logs, click on the “full logs” button and add them to the bug report after removing personal data.

## Caveats

You can set a poll interval, but don't set it too low as the API has a limit of 60 requests per minute, and each device needs one request per state pull and control action.
If you have more than one lamp use a higher interval. Govee wants to implement a single request for all devices in 2021.
You can set a poll interval, but don't set it too low, as the API has a limit of 60 requests per minute, and each device needs one request per state pull and control action.
If you have more than one lamp, use a higher interval. Govee wants to implement a single request for all devices in 2021.

Once the integration is active, you will see all your registered devices, and may control on/off, brightness, color temperature and color.
Once the integration is active, you will see all your registered devices, and may control on/off, brightness, color temperature, and color.