@constructorfleet/ultimate-govee NPM

Ultimate Govee

Description

Provides command and control interface for interacting with Govee via Bluetooth LE, AWS IoT Core, LAN (TODO), and Govee OpenAPI Developer Platform (TODO).

If a device type is known, it will be categorized and have type-specific device states. Supported types so far:

Purifiers
Humidifiers
RGB Lights (Bulbs, Strips, etc.)
RGBIC Lights (Bulbs, Strips, Glide, etc.)
Air Quality Monitors
Hygrometers
Ice Makers

Control Channels

The primary control channel is AWS IoT Core - this is a Pub/Sub system that works with any WiFi-enabled device (and soon any device behind a disributed gateway). If you have a bluetooth adapter, you can enable the BLE control channel to control those directly; however, if you try to enable this and do not have a bluetooth adapter - it will cause the library to crash.

This works on OSX and Linux system. Have not tested Windows.

Devices

Devices are composed of various states, some allow you to change them while others are informational only. Each state keeps a history for the previous 5 state values and if it's a controllable state you can set it to one of them by invoking the previousState method, which accepts a value between 0 and 5 (0 means set it to the current state, 1 the previous state, all the way to 5 being the 5th previous state). This allows for automations like "When motion: set RGBICLightDevice's wholecolor state to white and brightness state to 100%; On motion clear return to the previous brightness and previous light effect"

const device: RGBICLight;
onMotion() {
  device.wholeColor().setState({red: 255, green: 255, blue: 255});
  device.brightness().setState(100);
}
onMotionClear() {
  device.ligthEffect().previousState(1);
  device.brightness().previousState(1);
}

States

isActive - Whether the device is "active", i.e. the Purifier is running
batteryLevel - The remaining battery level as a percentage (if device is battery powered)
brightness - The brighness (as percentage) for the device (in the case of RGBICLights, this is the entire device)
colorRGB - Color of a light, for bulb and strips this is for the device itself
colorTemp - The color temperature for the light (2000K - 9000K)
connected - This should indicate whether the device is online, however it's not consistent
controlLock - Locks or unlocks the physical controls on the device
displaySchedule - Sets when the display on the device is to be illuminated
filterExpired - Flag indicating the device's filter is needing replaced
filterLife - The remaining life of the device's filter (as a percentage), not all devices report this
humidity - An object containing the valid relative humidity range, current reading, calibration settings and raw value
lightEffect - Contains the list of valid light effects for the device, you can control the state via the effect name or the numeric code
mode - The active mode of the device, this state is meaningless without a specific device implementation
nightLight - Control the night light feature of the device, if the device has one
power - Whether the device is on or off, this is similar to
isActive but applies primarily to switch and light devices
temperature - An object containing the valid temperature range, current reading, calibration settings and raw value
timer- Allows interacting with the device's timer feature (setting the start and end for operation)
waterShortage - Flag indicating the device is out of water.

Humidifiers

mistLevel - The amount of mist the humidifier is emitting
targetHumidity - If paired with Hygrometer or one is integrated, sets the relative humidity at which the device will pause activity
uvc - Some humidifiers offer a UVC sterilization feature, set this to true to enable sanitization
manualMode - Simple mode where you can control the mistLevel directly

customMode - Set three mist levels and their durations, once the first is completed it starts the second, the third can be indefinite or a finite duration

autoMode - Humidifier will operate automatically until the target humidity is reached

Ice Makers

nuggetSize - Set the size of the ice cubes
makingIce - Analogous to isActive, starts or stops the ice production
iceMakerStatus - The status of the device: washing, idle, making ice, etc.
scheduledStart - Allows you to set a time in the future to start ice production
basketFull - Flag indicating the basket is full and needs to be emptied.

Purifier

fanSpeed - Reported as a percentage, indicates how much the purifier is working. Some devices only allow 3 speeds, some 4.
manualMode - Control the fan speed directly
customMode - Set three speed settigns and their durations, once the first is complete it starts the second, the third can be indefinite or a finite duration
autoMode - If paird with an air quality monitor or has one integrated, will purify the air until the air quality measurement is below the threshold

Air Quality Monitor

pm25 - the PPM measurements of particles in the air
humdidity - the measured ambient relative humidity
temprature - the measured ambient temperature

Hygrometer

humidity - the measured ambient relative humidity
temperature - the measure ambient temperature
batteryLevel - Remaining battery level of the device

Presence Sensor

presence-mmWave - mmWave sensor detected, distance in centimeters and duration
presence-biological - IR sensor detected, distance in centimters and duration
enablePresence - Flags for enabling the sensors
detectionSettings - Configure the detection distance, report detection duration and duration before absence

RGB Lights

micMode - Makes the device sound reactive, various settings can be applied to this mode such as sensitivity, colors and intensity
colorMode - The color of the light
brightness - The brightness of the light
colorTemp - The color temperature of the light

RGBIC LIghts

micMode - set the device to be audio reactive, you can change the colors, intensity, how the colors change (chase, pulse, etc)
wholeColorMode - controls the color of the entire device
segmentedColorMode - controls color and brightness of the individual light segments
lightEffect - activates one of the numerous light effects defined by govee (the application automatically retrieves this list)
advancedColorMod - This allows for you to create DIY light effects (this is not implemented yet)

Installing the library

npm install --save @constructorfleet/ultimate-govee

Running the library

NOTE All options for this module are optional, but at least one control channel must be enabled to interact with devices

First, import the UltimateGoveeModule:

@Module({
  import: [UltimateGoveeModule.forRootAsync({
    persist: {
      rootDirectory: 'path/to/persistent/storage', // Path to persistent storage, as of now, it writs a lot for debugging
    },
    auth: {
      refreshMargin: 5000 // Number of milliseconds before token expires to reauthenticate with Govee
    },
    channels: {
      ble: {
        enabled: true, // Whether to enable the BLE control channel (if you do not have BLE adapter, this MUST be false)
        deviceIds: [ // List of IDs for devices to command and control - these are not the BLE address!
          "00:11:22:33:44:55:66:77:88"
        ]
      },
      iot: {
        enabled: true, // Whether to enable the AWS IoT Core control channel
      }
    }
  })]
  ...
})
export class AppModule {}

Then, inject the UltimateGoveeService:

@Injectable()
export class AppService {
  constructor(private readonly govee: UltimateGoveeService, ...) {}
}

Subscribe to device discovery events:

this.govee.deviceDiscovered.subscribe((device: Device) => {
  // Get the device value of all states
  console.dir(device.currentState);
  // Get a specific device state
  device.state(FanSpeedStateName);

  // Issue a command to the device state
  device.state('mistLevel').setState(4);
  device.state('scheduledStart').setState({
    enabled: true,
    startHour: 14,
    startMinute: 30,
  });
});

Connect using the user's credentials:

this.govee.connect(username, password);

Test

nest test

Future Work

- Configure control channels on initialization and during runtime.
~~- Configurable controllers.~~
- Specify devices to listen for.
- Device overrides.
- LAN control channel.
- Govee OpenAPI control channel.
- Tool for facilitating device support.

Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.