goveelights 0.1.2

A small package to interact with the Govee API.

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.

---

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.

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

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 .

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.

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

# 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.

# 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.

# 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.

# 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 GoveeClientobject 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 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.