wizctl #

Control your Philips WiZ smart lights via CLI or an App.

Why? #

The official Philips app is laggy and is available only for mobile. This package enables controlling wiz devices from all supported platforms (MacOS, Windows, Linux, iOS, Android) via CLI or an app.

Features #

• Discovery - Find lights by UDP broadcast, or by asking each address on your subnet directly when broadcast doesn't reach them
• Control - On/off, brightness, RGB color, color temperature, scenes
• Groups - Control multiple lights in parallel
• 36 Scenes - All built-in WiZ scenes with speed control
• Bulb Type Detection - Auto-detect RGB, Tunable White, Dimmable, Socket, Fan

Installation #

Add to your pubspec.yaml:

dependencies:
  wizctl: ^1.0.0

Or install via command line:

dart pub add wizctl

Quick Start #

import 'package:wizctl/wizctl.dart';

void main() async {
  // Discover lights
  final lights = await WizDiscovery.discover();
  print('Found ${lights.length} lights');

  // Control a light
  final light = WizLight('192.168.1.100');
  await light.turnOn();
  await light.setBrightness(75);
  await light.setColor(255, 100, 50);
  await light.setScene(WizScene.cozy);
  
  // Get state
  final state = await light.getState();
  print('Brightness: ${state.dimming}%');
}

Control Examples #

// Basic
await light.turnOn();
await light.turnOff();
await light.setBrightness(75);

// Color
await light.setColor(255, 100, 50);
await light.setTemperature(3000);

// Scenes with speed
await light.setScene(WizScene.ocean, speed: 150);

// Combined settings
await light.send(
  ControlSignal(
    state: true, // Light state: on/off
    dimming: 80,
    r: 255,
    g: 100,
    b: 50,
  ),
);

Group Control #

final lights = [
  WizLight('192.168.1.100'),
  WizLight('192.168.1.101'),
];

await WizGroup.turnOn(lights);
await WizGroup.setScene(lights, WizScene.cozy);
await WizGroup.setColor(lights, 255, 100, 50);

Bulb Type Detection #

final config = await light.getSystemConfig();
print('Type: ${config.bulbClass?.displayName}'); // "RGB", "Tunable White", etc.

if (config.supportsColor) {
  await light.setColor(255, 0, 0);
}

When discovery finds nothing #

Discovery broadcasts a registration message and waits for lights to answer. On some networks the lights never answer it, even though they reply to unicast instantly — access points can filter broadcast to wireless clients, and Wi-Fi power save on the bulb means broadcast frames only arrive on the access point's DTIM schedule. No broadcast-based tool can find lights in that state.

discover asks the lights already in your config directly first — that is quick and reliable — and falls back to a unicast subnet sweep when it needs to look for lights it has not seen before. --scan skips the shortcut and sweeps:

wizctl discover --scan
wizctl discover --scan --subnet 192.168.1   # a subnet other than yours

final lights = await WizDiscovery.scanSubnet(subnet: '192.168.1');

The scan assumes a /24 and probes each address twice, since the first datagram to a host is dropped while the OS resolves its MAC address.

Note that the IP shown in the WiZ app can be stale: the app controls lights through Philips' cloud, so it keeps working even when the light is unreachable on your local network. Your router's DHCP client list is the reliable source.

Retry Configuration #

For unreliable networks, you can customize retry behavior:

// Discovery with custom retry strategy
final lights = await WizDiscovery.discover(
  timeout: Duration(seconds: 10),
  retry: RetryConfig.fixed(
    count: 5,
    interval: Duration(seconds: 1),
  ),
);

// Or use exponential backoff (default)
final lights = await WizDiscovery.discover(
  retry: RetryConfig.exponential(
    count: 5,
    initialInterval: Duration(milliseconds: 500),
    maxInterval: Duration(seconds: 3),
  ),
);

// Protocol requests also support retry config
// (uses exponential backoff by default)

Debugging #

// Enable logging to see UDP packets
WizLogger.enable(WizLogLevel.debug);
await light.turnOn(); // Now shows packets

CLI #

# Install
dart pub global activate wizctl

# Help
wizctl --help

# Discover and save lights
wizctl discover --save

# If nothing is found, scan the subnet one address at a time
wizctl discover --scan

# ...or point it at a different subnet
wizctl discover --scan --subnet 192.168.1

# Set alias (use flags for names with spaces)
wizctl alias --ip 192.168.1.100 -n "Living Room"

# Control (use -t/--target to specify light)
wizctl on -t "Living Room"
wizctl brightness -t "Living Room" -b 75
wizctl color -t "Living Room" -c 255,100,50
wizctl temp -t Kitchen -k 4000
wizctl scene -t "Living Room" -s cozy

# Groups
wizctl group add -n all -l "Living Room,Bedroom"
wizctl off -t all

# Debug mode
wizctl --debug status -t 192.168.1.100

CLI Commands #

Scenes #

Scenes can be dynamic or static. Dynamic scenes support speed control.

CLI: wizctl scenes | Dart: WizScene.values

Inspiration #

This is inspired by pywizlight by sbidy

License #

MIT