goveelights 0.1.2
A small package to interact with the Govee API.
Requires Python: >=3.8
Keywords: govee,device,lights,client

# govee_lights


This repository contains a set of objects which can be used to control a Govee API v1.2 compatible device. This requires a valid API key, which can be requested by contacting [Govee Support](https://us.govee.com/pages/contact-us).

------------

## Overview

This package provides three (3) objects the user will need to be concerned withy:
1. GoveeDevice
2. GoveeClient
3. GoveeHub

The GoveeDevice class represents the physical device and contains all static and dynamic data about the device and the logic to ensure the device functions appropriately.

The GoveeClient class is used to submit HTTP requests to the Govee API. This contains the data and logic necessary to build, format, and submit requests, followed by processing the response.

The GoveeHub class contains an instance of the GoveeClient and an indefinite number of GoveeDevice instances. The hub is used to facilitate submitting API requests and managing the devices registered to the user.

This is a simple package to allow Govee API compatible devices to integrate with Home Assistant.

---

## Dependencies

* Python 3.8 (Minimum version required)
  * requests (2.0.0)
  * uuid (1.0.0)
  * json (included in Python by default)
  * re (included in Python by default)
* Govee API Key
* Govee API compatible device(s)

---

## Usage

Below here you may find steps to complete a basic set of operations which a user will be able to complete with this package. This does not fully explain the capabilities of the package, but does provide a basic idea..

---

### Using as a standalone product

In order to use this as a standalone product (not part of a service such as Home Assistant) you can refer to the **Usage** section above.

---

### Creating a GoveeClient Object

The user will need to create an instance of the `GoveeClient` class, this will require an API key, provided by Govee Support.

```python
from goveelights import GoveeClient, GoveeHub, GoveeDevice

api_key = #Whatever your API key is, as a string.
client = GoveeClient(api_key)
```

After this the user will need to instantiate a `GoveeHub` object, passing the `GoveeClient` object as a parameter.  Once the hub has been created, the user will need to call the `get_devices` method in order to automatically generate `GoveeDevice` objects.

### Creating a GoveeHub Object

```python
hub = GoveeHub(GoveeDevice, client)
hub.get_devices()
```

The `get_devices` method triggers a request to the API which returns all devices which are registered to the user's Govee account. These devices can be accessed via the `devices` property, which holds a .

```python
for device_id in hub.devices:
    print(f"{device_id} - {hub.devices[device_id]}")
```

This will print out something approximating the text below.

```
3d:62:7c:a6:a1:0b:b9:8c - <__main__.GoveeDevice object at 0x7f7b87802fa0>
59:e4:7c:a6:a1:09:42:9d - <__main__.GoveeDevice object at 0x7f7b87802fa0>
11:a3:7c:a6:a1:39:a0:47 - <__main__.GoveeDevice object at 0x7f7b87bde490>
```

### Using GoveeDevice Objects

Once the user has their desired devices, they have access to up to four (4) different methods they may use to interact with the light.
* `set_power_state`
* `set_brightness`
* `set_color`
* `set_color_temp`

Before we proceed, we'll declare a few values, for easy reference. These represent the IDs for devices, as provided by Govee. These are used to identify each `GoveeDevice` object generated by the hub.

```python
livingroom_light_id = "3d:62:7c:a6:a1:0b:b9:8c"
bedroom_light_id = "59:e4:7c:a6:a1:09:42:9d"
kitchen_light_id = "11:a3:7c:a6:a1:39:a0:47"
```

The user is able to turn a device on and off by running the commands below. These

```python
# Turn the livingroom light off
hub.set_power_state(livingroom_light_id, GOVEE_STATE_OFF)

# Turn the bedroom light on
hub.set_power_state(bedroom_light_id, GOVEE_STATE_ON)

# Turn the kitchen light on
hub.set_power_state(kitchen_light_id, GOVEE_STATE_OFF)
```

The user is able to set the brightness of a device by running the commands below.

```python

# Set the livingroom light to half brightness
hub.set_brightness(livingroom_light_id, GOVEE_BRIGHTNESS_MAX / 2)

# Set the bedroom light to minimum brightness
hub.set_brightness(bedroom_light_id, GOVEE_BRIGHTNESS_MIN)

# Set the kitchen light to full brightness
hub.set_brightness(kitchen_light_id, GOVEE_BRIGHTNESS_MAX)
```

The user is able to set the color of a device by running the commands below.

```python

# Set the livingroom light to blue
hub.set_color(livingroom_light_id, b=GOVEE_COLOR_MAX)

# Set the bedroom light to purple
hub.set_color(bedroom_light_id, r=GOVEE_COLOR_MAX, b=GOVEE_COLOR_MAX)

# Set the kitchen light to teal
hub.set_color(kitchen_light_id, r=GOVEE_COLOR_MAX / 2, g=GOVEE_COLOR_MAX / 2, b=GOVEE_COLOR_MAX / 2)
```

The user is able to set the temperature[^1] of the color of the light by running the commands below.

```python

# Set the livingroom light a yellowish (standard incandescent light)
hub.set_color_temp(livingroom_light_id, 2400)

# Set the bedroom light a cool white light (compact fluorescent)
hub.set_color_temp(bedroom_light_id, GOVEE_BRIGHTNESS_MIN)

# Set the kitchen light to a bright white light (commercial/industrial lighting)
hub.set_color_temp(kitchen_light_id, GOVEE_BRIGHTNESS_MAX)
```

All interactions with devices will be facilitated via the hub. This minimizes the amount of direct interaction with the devices the user need have.

These methods correspond to the device commands listed below. These are the commands which the Govee API recognize.
* `turn`
* `brightness`
* `color`
* `colorTem`

---

### Using as a Home Assistant integration

*This section will be filled in when I figure it out.*

---

## Package Classes

Below here we have a breakdown of the different classes available within this package. This will contain more technical information.

---

### GoveeDevice

A `GoveeDevice` object will identify a set of properties which identify the methods a given device supports.

#### Static Properties

Static properties are the properties of `GoveeDevice` objects which may not be modified once the objects have been instantiated. These are used to indicate what the device is and is not capable of.

* `device`
* `model`
* `device_name`
* `controllable`
* `retrievable`
* `supported_commands`
* `color_temp_range`

The `device` property is the unique identifier which Govee provides in order to identify individual devices. These appear to be based on the MAC address of the devices themselves.

The `model` property is the name of the model of the device.

The `device_name` property is the name of the device as configured within Govee's service.

The `controllable` property indicates whether the device is capable of receiving commands which result in some change of state to the device.

The `retrievable` property indicates whether the user is able to poll the state of the device.

The `supported_commands` property indicates which of the four (4) device commands the device supports.

The `color_temp_range` property indicates the supported range of color temperatures which can be used to set the color of light.

#### State Properties

State properties are the properties of `GoveeDevice` objects which may change over time and/or are controllable by the user. These properties have predefined values which they may assume.

* `online`
* `power_state`
* `brightness`
* `color`
* `color_temp`

The `online` property may assume the values listed below
* `GOVEE_STATE_ON`
* `GOVEE_STATE_OFF`

The `power_state` property may assume the values listed below
* `GOVEE_ONLINE_TRUE`
* `GOVEE_ONLINE_FALSE`

The `brightness` property may assume the value of any `int` between the values `GOVEE_BRIGHTNESS_MIN` and `GOVEE_BRIGHTNESS_MAX` (inclusive).

The `color` property is an instance of a `Color` object. This object represents the 3-byte RGB value of a color.

The `color_temp` property is an integer within the (inclusive) range defined by the `color_temp_range` property.

#### Public Methods

The methods here are available for use outside the class itself.

* `__init__`
* `update_status`

The `__init__` method requires the user pass a `GoveeHub` object and a `dict` containing device information, as provided by the `GoveeHub`.

---

### GoveeClient

A `GoveeClient`object is used to facilitate communication between a `GoveeHub` object and the Govee API itself. A user must provide a valid Govee API Key in order to instantiate and utilize the object.

The `GoveeClient` object offers the ability to submit `GET` and `PUT` requests to the API.

#### GoveeClient Properties

The only `GoveeClient` property that exists is `api_key`. This holds the API key the user includes in API requests and is used to validate the request itself.

#### Public Methods

A user is able to submit requests to the Govee API by using either of the methods below.
* `get_data`
* `put_data`

The `get_data` method includes the parameters listed below.
* `req_uri` - The full URI of the API service endpoint.
* `device_id` - The full device ID of the Govee device.
* `model` - The full model name of the Govee device.

The `put_data` method includes the parameters listed above, as well as the one listed below.
* `req_payload` - The JSON data to be included in the request.

---

### GoveeHub

A `GoveeHub` object is used to facilitate communication between the user, `GoveeClient` objects, and `GoveeDevice` objects. Since

This will create the hub object the user will use to interact with the `GoveeDevice` objects which represent the physical Govee devices.

#### GoveeHub Properties

The GoveeHub offers the properties listed below.

* `devices`
* `client`

The `devices` property is a list of `GoveeDevice` objects which are associated with the user's account.

The `client` property is a `GoveeClient` object. This serves as the client the hub will rely on for communication with the Govee API.

#### Public Methods

The GoveeHub offers the public methods listed below.

* `get_devices`
* `get_device_state`
* `set_power_state`
* `set_brightness`
* `set_color`
* `set_color_temp`

The `get_devices` method is used to retrieve information for all Govee devices from the Govee API and creates a `GoveeDevice` object for each device. The devices are automatically added to the `devices` property.

The `get_device_state` method is used to retrieve the current state of a specific `GoveeDevice` object.

The `set_power_state` method is used to turn a `GoveeDevice` object on or off.

The `set_brightness` method is used to control the brightness of a `GoveeDevice` object.

The `set_color` method is used to set the color of light output by a `GoveeDevice` object.

The `set_color_temp` method is used to set the color of light output by a `GoveeDevice` object

---

## Automated Testing

The test cases are located in the `tests` directory and are sorted based on whether they're unit, functional, or integration based tests.

---

## Additional Comments

[^1]: [Color Temperature](https://en.wikipedia.org/wiki/Color_temperature) is used to determine the color of light a `GoveeDevice` will will emit. Since an ideal source will emit a calculable color of light at a given temperature. Temperatures around 2800 K are a warmer yellow while temperatures closer to 8000 K are a cooler bluish.