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.

dutchie027 / govee-api Goto Github PK

govee-api's Introduction