README.md

Govee PHP API

A simple PHP package that allows you to control Govee Smart Lights using their API.

Requirements

• PHP >7.2

Installation

You can install the package using the Composer package manager. You can install it by running this command in your project root:

composer require dutchie027/govee

Basic Usage

Instantiate the client

To use any of the Govee API functions, you first need a connection reference. The connection refrence can then be fed to either the Lights library or the Plugs library, or even both if you have both Govee Lights and Plugs.

// Ensure we have the composer libraries
require_once ('vendor/autoload.php');

// Instantiate with defaults
$govee = new dutchie027\govee\Connect("GOVEE-API-KEY");

// Instantiate without defaults, this allows you to change things
// like log location, directory, the tag and possible future settings.
$settings = [
  'log_dir' => '/tmp',
  'log_name' => 'govee-api',
  'log_tag' => 'mylights',
  'log_level' => 'error'
];

$govee = new dutchie027\govee\Connect("GOVEE-API-KEY", $settings);

Settings

The default settings are fine, however you might want to override the defaults or use your own.NOTE: All settings are optional and you don't need to provide any.

Field	Type	Description	Default Value
log_dir	string	The directory where the log file is stored	sys_get_temp_dir()
log_name	string	The name of the log file that is created in log_dir. If you don't put .log at the end, it will append it	6 random characters + time() + .log
log_tag	string	If you share this log file with other applications, this is the tag used in the log file	govee
log_level	string	The level of logging the application will do. This must be either debug, info, notice, warning, critical or error. If it is not one of those values it will fail to the default	warning

Connect (Core) Functions

Get Device Count

print $govee->getDeviceCount();

Get An Array of All Devices

$array = $govee->getDeviceList();

Example Return Array

Array
(
    [0] => Array
        (
            [device] => 46:F1:CC:F6:FC:65:FF:AA
            [model] => H6159
            [deviceName] => Office-Color
            [controllable] => 1
            [retrievable] => 1
            [supportCmds] => Array
                (
                    [0] => turn
                    [1] => brightness
                    [2] => color
                    [3] => colorTem
                )

        )

)

Get An Array of All Callable MAC Addresses

$macArray = $govee->getDeviceMACArray();

MAC Return Array

Array
(
    [0] => A9:E9:0A:04:AD:CD:12:34
    [1] => FA:8F:50:B2:AD:A7:00:12
    [2] => E0:94:41:AC:62:13:56:78
)

Get An Array of All Device Names

$nameArray = $govee->getDeviceNameArray();

Device Name Return Array

Array
(
    [0] => My-Living-Room
    [1] => Hallway
    [2] => Fire-House
)

Get the location of the log file

print $govee->getLogLocation();

Example Return String

/tmp/2Zo46b.1607566740.log

Lights Functions

Controlling Lights

To control lights, you first need to make a connection and then reference the connection

// Ensure we have the composer libraries
require_once ('vendor/autoload.php');

// Instantiate with defaults
$govee = new dutchie027\govee\Connect("GOVEE-API-KEY");

Once you've got a reference to the lights, it will preload all of the MAC Address(es) and name(s) of the devices.

Turning A Light ON

To turn a light on, simply feed it the MAC address or the name of the light.

$govee->lights()->turnOn("AC:14:A3:D5:E6:C4:3D:AE");

or

$govee->lights()->turnOn("Office-Wall");

Turning A Light OFF

Like turning a light on, to turn a light off, simply feed the MAC address or the name of the light.

$govee->lights()->turnOff("AC:14:A3:D5:E6:C4:3D:AE");

or

$govee->lights()->turnOff("Office-Wall");

Adjusting BRIGHTNESS of A Light

To adjust the brigthness, simply give the name or MAC and the brightness, an INT between 0 and 100.

$govee->lights()->setBrightness("AC:14:A3:D5:E6:C4:3D:AE", 75);

or

$govee->lights()->setBrightness("Office-Wall", 75);

Changing the COLOR of A Light

To adjust the color, simply give the name or MAC and the brightness and then feed the R, G, B colors you'd like the device to set itself to. NOTE the values for Red, Green and Blue must be between 0 and 255.

$govee->lights()->setColor("AC:14:A3:D5:E6:C4:3D:AE", 255, 255, 0);

or

$govee->lights()->setBrightness("Office-Wall", 255, 0, 0);

Changing the TEMPERATURE of A Light

To adjust the temperature, simply give the name or MAC and the name and then feed the temperature. NOTE Temperature must be an INT between 2000 and 9000.

$govee->lights()->setTemp("AC:14:A3:D5:E6:C4:3D:AE", 5000);

or

$govee->lights()->setTemp("Office-Wall", 5000);

Get the STATE of A Light

To get all of the details about a light, simply feed getDeviceState the name or the MAC address. You'll get a JSON return you can then either read or feed to json_decode and turn in to an array to use/read.

$govee->lights()->getDeviceState("AC:14:A3:D5:E6:C4:3D:AE");

or

$govee->lights()->getDeviceState("Office-Wall");

{
  "data": {
    "device": "AC:14:A3:D5:E6:C4:3D:AE",
    "model": "Office-Wall",
    "properties": [
      {
        "online": true
      },
      {
        "powerState": "on"
      },
      {
        "brightness": 100
      },
      {
        "color": {
          "r": 255,
          "b": 0,
          "g": 255
        }
      }
    ]
  }
}

Plugs Functions

Turn On A Plug

$govee->plugs()->turnOn("AC:14:A3:D5:E6:C4:3D:AE");

or

$govee->plugs()->turnOn("Office-Wall");

Turn Off A Plug

$govee->plugs()->turnOff("AC:14:A3:D5:E6:C4:3D:AE");

or

$govee->plugs()->turnOff("Office-Wall");

Contributing

If you're having problems, spot a bug, or have a feature suggestion, file an issue. If you want, feel free to fork the package and make a pull request. This is a work in progresss as I get more info and the Govee API grows.