Network devices

Network RGB devices (Philips Hue, Nanoleaf, WLED, and Govee) connect over your local network rather than USB. Hypercolor handles discovery, pairing, and high-frequency streaming entirely on the LAN; no cloud services are required for any of the four built-in network drivers.

🔗How discovery works

Hypercolor uses three complementary methods to find network devices. All three run in parallel during a single scan.

mDNS (zero-configuration) is the primary path. Each driver listens for its vendor-specific service type on the local network. When a compatible device announces itself, Hypercolor receives the advertisement, optionally enriches it with a device-info HTTP probe, and adds the device to the registry.

mDNS only works when devices and the Hypercolor host share a broadcast domain. VLANs, AP isolation, and some router firmware block it — see mDNS troubleshooting below.

Known-IP probing is the escape hatch when mDNS is blocked. You can supply a static list of IP addresses for each driver in the Hypercolor config file. The daemon probes those addresses directly on startup and during every scan, bypassing mDNS entirely. See each vendor’s setup page for the exact config keys.

Manual target scoping lets you tell a scan which drivers to run. By default a scan covers all enabled drivers. Naming specific targets narrows the scope:

# scan only WLED and Hue, 20-second window
hypercolor devices discover --target wled --target hue --timeout 20

The --target flag accepts any driver module ID (wled, hue, nanoleaf, govee) and the built-in local transport IDs (usb, smbus). You can mix them freely. Omitting --target runs everything.

The --timeout value is in seconds and defaults to 10. The daemon clamps it between 0.1 s and 60 s regardless of what you pass.

🔗REST API

POST /api/v1/devices/discover triggers the same scan programmatically.

{
  "targets": ["wled", "nanoleaf"],
  "timeout_ms": 15000,
  "wait": true
}

All three fields are optional. When wait is false (the default), the endpoint returns immediately with a scan_id and "status": "scanning". Set wait: true to block until the scan completes and receive the full result in the response body.

🔗Device fingerprinting and IP changes

Network devices are fingerprinted on stable hardware identity rather than their current IP address:

• WLED — MAC address (net:<mac>)
• Govee — MAC address (net:govee:<mac>)
• Hue — Bridge ID
• Nanoleaf — device serial key

A DHCP address change does not lose pairing or rename the device in Hypercolor’s registry. Only a factory reset or key regeneration on the device side requires re-pairing.

🔗Pairing and credentials

Some network drivers require an explicit pairing step before Hypercolor can send lighting data. The daemon stores credentials encrypted and loads them automatically on startup — you pair once per device.

To pair a device that was discovered but is not yet streaming:

hypercolor devices pair "<device name or ID>"

hypercolor devices list shows each device’s state. A device stuck in discovered is waiting for credentials. A connected device is actively streaming.

🔗mDNS troubleshooting

When hypercolor devices discover returns nothing, the most common causes on a LAN are:

AP isolation / client isolation blocks multicast and mDNS between wireless clients and the Hypercolor host. Disable it for the VLAN that contains your RGB devices, or check your access point’s “wireless isolation” setting.

Separate VLANs or subnets prevent mDNS from crossing the network boundary without a proxy. Either place the Hypercolor host and RGB devices on the same subnet, or configure mDNS reflection via avahi-daemon --reflector or a router-level mDNS proxy.

systemd-resolved stub resolver can conflict with avahi-daemon. Check whether mDNS is enabled on the relevant interface:

resolvectl status

Look for MulticastDNS: yes on the interface your RGB devices are on. If it shows no, you may need to set MulticastDNS=yes in /etc/systemd/resolved.conf or in the per-interface .network configuration.

The known-IP fallback bypasses all of these. Consult each vendor’s dedicated page for the exact config keys to set static addresses.

If you want to disable mDNS globally in Hypercolor while keeping known-IP probing active, set discovery.mdns_enabled = false in your Hypercolor config.

See also: network discovery troubleshooting for deeper diagnostic steps and log targets.

🔗Per-vendor setup

Each network driver has its own pairing flow, streaming protocol, supported device SKUs, and common failure modes. Start with the vendor page for your hardware.

• Philips Hue — mDNS and N-UPnP discovery, link-button pairing (30-second window), Entertainment API DTLS streaming on UDP port 2100.
• Nanoleaf — mDNS discovery, power-button token pairing (hold 5–7 s), UDP External Control on port 60222.
• WLED — mDNS discovery, no authentication required, DDP streaming on port 4048 by default, or E1.31/sACN for multi-controller setups.
• Govee — proprietary UDP multicast discovery, LAN control must be enabled per-device in the Govee Home app, optional Developer API key for cloud fallback.

For devices that don’t have a native Hypercolor driver, the OpenRGB fallback bridge can control them through a user-managed OpenRGB server on TCP port 6742.

🔗Devices on the same host machine

If the Hypercolor daemon and the RGB device software both run on the same machine, they may fight over the same network socket or claim the same control channel. This is uncommon for LAN devices (each speaks to a dedicated IP) but worth knowing: only one application should be issuing streaming data to any given device at a time. Mixed control produces undefined color output.

For USB devices on the same machine, see conflicting software.