Package: goveelights
govee_lightsThis 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 contactingGovee Support.OverviewThis package provides three (3) objects the user will need to be concerned withy:GoveeDeviceGoveeClientGoveeHubThe 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.DependenciesPython 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 KeyGovee API compatible device(s)UsageBelow 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 productIn order to use this as a standalone product (not part of a service such as Home Assistant) you can refer to theUsagesection above.Creating a GoveeClient ObjectThe user will need to create an instance of theGoveeClientclass, this will require an API key, provided by Govee Support.fromgoveelightsimportGoveeClient,GoveeHub,GoveeDeviceapi_key=#Whatever your API key is, as a string.client=GoveeClient(api_key)After this the user will need to instantiate aGoveeHubobject, passing theGoveeClientobject as a parameter.  Once the hub has been created, the user will need to call theget_devicesmethod in order to automatically generateGoveeDeviceobjects.Creating a GoveeHub Objecthub=GoveeHub(GoveeDevice,client)hub.get_devices()Theget_devicesmethod 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 thedevicesproperty, which holds a .fordevice_idinhub.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 ObjectsOnce 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_stateset_brightnessset_colorset_color_tempBefore 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 eachGoveeDeviceobject 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 offhub.set_power_state(livingroom_light_id,GOVEE_STATE_OFF)# Turn the bedroom light onhub.set_power_state(bedroom_light_id,GOVEE_STATE_ON)# Turn the kitchen light onhub.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 brightnesshub.set_brightness(livingroom_light_id,GOVEE_BRIGHTNESS_MAX/2)# Set the bedroom light to minimum brightnesshub.set_brightness(bedroom_light_id,GOVEE_BRIGHTNESS_MIN)# Set the kitchen light to full brightnesshub.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 bluehub.set_color(livingroom_light_id,b=GOVEE_COLOR_MAX)# Set the bedroom light to purplehub.set_color(bedroom_light_id,r=GOVEE_COLOR_MAX,b=GOVEE_COLOR_MAX)# Set the kitchen light to tealhub.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.turnbrightnesscolorcolorTemUsing as a Home Assistant integrationThis section will be filled in when I figure it out.Package ClassesBelow here we have a breakdown of the different classes available within this package. This will contain more technical information.GoveeDeviceAGoveeDeviceobject will identify a set of properties which identify the methods a given device supports.Static PropertiesStatic properties are the properties ofGoveeDeviceobjects 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.devicemodeldevice_namecontrollableretrievablesupported_commandscolor_temp_rangeThedeviceproperty 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.Themodelproperty is the name of the model of the device.Thedevice_nameproperty is the name of the device as configured within Govee's service.Thecontrollableproperty indicates whether the device is capable of receiving commands which result in some change of state to the device.Theretrievableproperty indicates whether the user is able to poll the state of the device.Thesupported_commandsproperty indicates which of the four (4) device commands the device supports.Thecolor_temp_rangeproperty indicates the supported range of color temperatures which can be used to set the color of light.State PropertiesState properties are the properties ofGoveeDeviceobjects which may change over time and/or are controllable by the user. These properties have predefined values which they may assume.onlinepower_statebrightnesscolorcolor_tempTheonlineproperty may assume the values listed belowGOVEE_STATE_ONGOVEE_STATE_OFFThepower_stateproperty may assume the values listed belowGOVEE_ONLINE_TRUEGOVEE_ONLINE_FALSEThebrightnessproperty may assume the value of anyintbetween the valuesGOVEE_BRIGHTNESS_MINandGOVEE_BRIGHTNESS_MAX(inclusive).Thecolorproperty is an instance of aColorobject. This object represents the 3-byte RGB value of a color.Thecolor_tempproperty is an integer within the (inclusive) range defined by thecolor_temp_rangeproperty.Public MethodsThe methods here are available for use outside the class itself.__init__update_statusThe__init__method requires the user pass aGoveeHubobject and adictcontaining device information, as provided by theGoveeHub.GoveeClientAGoveeClientobject is used to facilitate communication between aGoveeHubobject and the Govee API itself. A user must provide a valid Govee API Key in order to instantiate and utilize the object.TheGoveeClientobject offers the ability to submitGETandPUTrequests to the API.GoveeClient PropertiesThe onlyGoveeClientproperty that exists isapi_key. This holds the API key the user includes in API requests and is used to validate the request itself.Public MethodsA user is able to submit requests to the Govee API by using either of the methods below.get_dataput_dataTheget_datamethod 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.Theput_datamethod includes the parameters listed above, as well as the one listed below.req_payload- The JSON data to be included in the request.GoveeHubAGoveeHubobject is used to facilitate communication between the user,GoveeClientobjects, andGoveeDeviceobjects. SinceThis will create the hub object the user will use to interact with theGoveeDeviceobjects which represent the physical Govee devices.GoveeHub PropertiesThe GoveeHub offers the properties listed below.devicesclientThedevicesproperty is a list ofGoveeDeviceobjects which are associated with the user's account.Theclientproperty is aGoveeClientobject. This serves as the client the hub will rely on for communication with the Govee API.Public MethodsThe GoveeHub offers the public methods listed below.get_devicesget_device_stateset_power_stateset_brightnessset_colorset_color_tempTheget_devicesmethod is used to retrieve information for all Govee devices from the Govee API and creates aGoveeDeviceobject for each device. The devices are automatically added to thedevicesproperty.Theget_device_statemethod is used to retrieve the current state of a specificGoveeDeviceobject.Theset_power_statemethod is used to turn aGoveeDeviceobject on or off.Theset_brightnessmethod is used to control the brightness of aGoveeDeviceobject.Theset_colormethod is used to set the color of light output by aGoveeDeviceobject.Theset_color_tempmethod is used to set the color of light output by aGoveeDeviceobjectAutomated TestingThe test cases are located in thetestsdirectory and are sorted based on whether they're unit, functional, or integration based tests.Additional Comments[^1]:Color Temperatureis used to determine the color of light aGoveeDevicewill 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.