Govee Local API

Please note that scene and segment support is still very experimental.

See SUPPORTED_DEVICES.md for the full list of known device models and their capabilities.

Requirements

• Python >= 3.11
• Govee Local API enabled. Refer to https://app-h5.govee.com/user-manual/wlan-guide

Installation

From your terminal, run

pip install govee-local-api

or

python3 -m pip install govee-local-api

Usage

Basic Usage

import asyncio
from govee_local_api import GoveeController

async def main():
    # Simple single-interface setup
    controller = GoveeController()

    # Discover devices
    devices = await controller.scan_devices()

    # Control a device
    if devices:
        device = devices[0]
        await device.turn_on()
        await device.set_brightness(80)
        await device.set_color(255, 0, 0)  # Red

asyncio.run(main())

Multi-Interface Setup

For complex network environments with multiple interfaces:

# Multiple listening addresses (basic)
controller = GoveeController(
    listening_addresses=["192.168.1.100", "10.0.0.100", "172.16.1.100"]
)

Tolerating a failed bind (require_all=False)

By default start() requires every configured address to bind; a single failure (EADDRNOTAVAIL for a stale address, EADDRINUSE, an interface that went down) closes any endpoint already opened and re-raises, so the controller is left unbound.

Since 3.1.0 you can opt in to keeping whatever binds successfully:

controller = GoveeController(
    listening_addresses=["192.168.1.100/24", "10.0.0.100/8", "172.16.1.100/16"]
)
await controller.start(require_all=False)

for address, error in controller.bind_failures:
    logging.warning("Not listening on %s: %s", address, error)
print("Live on", controller.listening_addresses)

• start() raises only if no address binds. The raised exception is the original OSError (errno preserved; an EADDRINUSE is preferred when several differ), never a wrapper type, so errno-based handling keeps working.
• bind_failures lists (address, OSError) pairs for the most recent start() only and is reset on every call. Partial success is also logged at warning level.
• The configured address set is never pruned: a later start() retries every address, so a caller can recover an adapter that has come back by simply calling start() again.

Network Mask Configuration

For precise subnet-aware device routing (recommended for enterprise/VLAN environments), embed the network mask directly in the address using CIDR or netmask notation:

# Precise subnet matching with embedded network masks
controller = GoveeController(
    listening_addresses=[
        "192.168.1.100/24",             # Main LAN (CIDR)
        "192.168.10.100/255.255.255.0", # IoT VLAN (dotted netmask)
        "10.0.0.100/8"                  # Management network
    ]
)

Supported Network Mask Formats

• CIDR Notation: 192.168.1.100/24, 10.0.0.100/8, etc.
• Dotted Decimal: 192.168.1.100/255.255.255.0, etc.
• No mask: 192.168.1.100 (uses heuristic subnet matching)
• Wildcard: 0.0.0.0 (listens on all interfaces, no subnet matching)

Advanced Features

Device Discovery and Control

async def discover_and_control():
    controller = GoveeController(
        listening_addresses=["192.168.1.100/24", "192.168.10.100/24"]
    )

    # Scan for devices across all networks
    devices = await controller.scan_devices()

    # Filter devices by network
    main_lan_devices = [d for d in devices if d.ip.startswith("192.168.1.")]
    iot_vlan_devices = [d for d in devices if d.ip.startswith("192.168.10.")]

    # Control devices on specific networks
    for device in main_lan_devices:
        await device.turn_on()
        await device.set_brightness(50)

    for device in iot_vlan_devices:
        await device.turn_off()

Direct Device Control

# Control device by IP address (uses intelligent transport selection)
await controller.control_device("192.168.1.100", turn_on=True)
await controller.control_device("192.168.1.100", brightness=75)
await controller.control_device("192.168.1.100", color_rgb=(0, 255, 0))

Documentation

• Supported Devices - Auto-generated list of known device models and their capabilities
• Network Mask Configuration Guide - Comprehensive guide for multi-network setups
• API Reference - Full API documentation

Use Cases

• Home Networks: Simple single-interface setup
• Small Office: Multi-interface with heuristic matching
• Enterprise/VLAN: Network mask configuration for precise routing
• IoT Deployments: Isolated network segments with dedicated interfaces
• Multi-Building: Physically separated networks with same IP ranges