wiz

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

README

wiz

A Go client for the local UDP API of WiZ lights and plugs; not affiliated with the owner of the WiZ brand.

Go Reference test Go

Requests with resends, light state and system configuration, module classes and built-in scenes, broadcast discovery, and push registration with the pushes the devices send. No cloud account, no cgo. The only dependency outside the standard library is lanbcast (Apache-2.0, standard library only).

Features

Feature Status
getPilot, setPilot (state, dimming, r/g/b, c/w, temp, sceneId, speed), getSystemConfig, getPower yes; other methods can be sent with Request
Discovery (the discovery form of registration sent to a broadcast address; the limited broadcast also goes to each LAN's directed broadcast) yes
Push registration, syncPilot and firstBeat pushes, acknowledgement yes
Module classes colour (RGB), tunable white, dimmable white, plug; fans and fan lights are reported as unknown
Scenes the built-in scene numbers with their app names, per class
Wi-Fi setup of new devices, firmware update, WiZ Pro, the cloud API no

The vendor does not publish the local API; there is no standard to cite. The behaviour follows public descriptions of it (see PROVENANCE.md).

Choosing a WiZ client

Compared from each library's source at the versions named, in October 2026; pywizlight is in Python and listed for reference. Check the projects themselves before relying on a row.

this module achetronic/wizgo v0.1.0 Dadido3/D3iot wiz driver (2022 commit) ctrox/gowiz (2021 commit) pywizlight 0.6.6 (Python)
Licence Apache-2.0 Apache-2.0 MIT MIT MIT
Last release or commit v0.x, 2026 tag 2023-09-19, last commit 2026-06-30 2022-11-23 2021-11-24 2026-08-05
Timeout on a request yes, context.Context no (the read blocks) yes yes yes
Resends a lost request yes, with a growing gap no yes, 10 retries by default no yes, up to 6 sends
Discovery by broadcast yes, limited and every LAN's directed broadcast no no no yes
Push registration yes sends the request no no yes
Receives syncPilot pushes yes (ServePush) no no no yes
Class from the module name, scenes per class yes yes class for three listed products, colour set in CIE XYZ (one bulb measured); a scene list without classes no yes
Fans reported as unknown no no no yes
Dependencies outside the standard library lanbcast golang.org/x/exp the D3iot module (gonum, a screenshot package) go.uber.org/zap Python

Pick this module to find, control and follow WiZ devices from a Go service: it is the only Go client found that discovers lights and receives their pushes. Pick D3iot's driver when you want colours given in CIE XYZ on the bulb it has measured. Use pywizlight in Python or Home Assistant, and for fans.

Install

go get github.com/cB-Sigma/wiz@latest

Requires Go 1.22 or later.

Quick start

Find the lights on the LAN, read each one's module and switch it to a scene (from Example in example_test.go; it needs lights on the LAN, so it is compiled but not run):

ctx := context.Background()

// The MAC is the one this client reports as its own.
found, err := wiz.Discover(ctx, "255.255.255.255:38899", "02aabbccddee", time.Second)
if err != nil {
	return err
}
for mac, addr := range found {
	raw, err := wiz.Request(ctx, addr, wiz.MethodGetSystemConfig, nil, 3*time.Second)
	if err != nil {
		continue
	}
	cfg, _ := wiz.ParseSystemConfig(raw)
	class, _ := wiz.ClassOf(cfg.ModuleName)
	fmt.Println(mac, cfg.ModuleName, "is", class)

	if id, _ := wiz.SceneID("warm white"); wiz.HasScene(class, id) {
		_, err := wiz.Request(ctx, addr, wiz.MethodSetPilot, map[string]any{"sceneId": id}, 3*time.Second)
		fmt.Println("scene set:", err == nil)
	}
}

Telling a device's class from its module name (ExampleClassOf, run by go test):

for _, m := range []string{"ESP01_SHRGB1C_31", "ESP05_SHDW9_01", "ESP10_SOCKET_06", "ESP03_FANDIMS_01"} {
	c, ok := wiz.ClassOf(m)
	fmt.Println(m, c, ok)
}
// Output:
// ESP01_SHRGB1C_31 rgb true
// ESP05_SHDW9_01 dw true
// ESP10_SOCKET_06 socket true
// ESP03_FANDIMS_01 unknown false

Pushes: open a UDP socket on port 38900, Register each device from it (again every 20 seconds or so), and run ServePush on it. Follow a device's address with PushedAddr, never with a push's source port: lights push from a port of their own.

Documentation

pkg.go.dev/github.com/cB-Sigma/wiz

Package What it does
wiz (module root) Request (one method, resent with a growing gap until the timeout), Pilot/ParsePilot, SystemConfig/ParseSystemConfig, ClassOf, Scenes/SceneID/SceneName/ScenesFor/HasScene, Discover, Register, ServePush, PushedAddr, LocalIPFor

Testing

go test -race ./...

The library's tests use a small fake light on the loopback interface. Discovery, registration and pushes against the full simulator are tested in wiz-sim.

Tests carry // Covers: SIG-... comments. These are requirement IDs of the compliance report of SigmaM2M, the oneM2M platform this module was written for; they have no meaning outside it.

Interop tested against

The automated tests run against a fake light and the simulator in wiz-sim, both written from the same descriptions as the client; that is not independent.

Checked by hand against a real WiZ colour bulb on a home LAN (October 2026, through SigmaM2M): colour, dimming at 20% and 100%, off and on, and scene selection. Discovery, pushes, tunable-white and dimmable-white bulbs and plugs have not been checked against real devices.

  • wiz-sim: simulated WiZ lights and a plug, as a Go package for tests and as a command.
  • lanbcast: the LAN broadcast helper used by Discover.

Status

v0.x; the API may change before v1.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

Licence

Apache-2.0 (LICENSE). Copyright Abhinav Gautam. NOTICE lists the projects whose public descriptions supplied the protocol facts. WiZ is a trademark of its owner; the name is used only to say which devices this module talks to.

Documentation

Overview

Package wiz speaks the local UDP API of WiZ Wi-Fi lights and plugs: JSON requests to port 38899 of the device with resends (Request), the light state (Pilot) and system configuration, the module classes (colour, tunable white, dimmable white, plug) and built-in scenes, broadcast discovery (Discover), and push registration with the pushes devices send to port 38900 (Register, ServePush, PushedAddr). It needs no cloud account.

The local API is not published by its vendor; this package follows the behaviour public clients describe (see PROVENANCE.md). Simulated devices for tests are in the separate module github.com/cB-Sigma/wiz-sim.

Example

Find the lights, read one and switch it to a scene. It needs lights on the LAN, so it is not run; github.com/cB-Sigma/wiz-sim runs the same steps against simulated lights.

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/cB-Sigma/wiz"
)

func main() {
	ctx := context.Background()

	// The MAC is the one this client reports as its own.
	found, err := wiz.Discover(ctx, "255.255.255.255:38899", "02aabbccddee", time.Second)
	if err != nil {
		fmt.Println(err)
		return
	}
	for mac, addr := range found {
		raw, err := wiz.Request(ctx, addr, wiz.MethodGetSystemConfig, nil, 3*time.Second)
		if err != nil {
			fmt.Println(mac, err)
			continue
		}
		cfg, _ := wiz.ParseSystemConfig(raw)
		class, _ := wiz.ClassOf(cfg.ModuleName)
		fmt.Println(mac, cfg.ModuleName, "is", class)

		if id, _ := wiz.SceneID("warm white"); wiz.HasScene(class, id) {
			_, err := wiz.Request(ctx, addr, wiz.MethodSetPilot, map[string]any{"sceneId": id}, 3*time.Second)
			fmt.Println("scene set:", err == nil)
		}
	}
}

Index

Examples

Constants

View Source
const (
	DevicePort = 38899
	PushPort   = 38900
)

The WiZ local API: JSON objects in single UDP datagrams to port 38899 of the device, answered from that port. Pushes (syncPilot, firstBeat) go to port 38900 of the registered phone address.

View Source
const (
	MethodGetPilot        = "getPilot"
	MethodSetPilot        = "setPilot"
	MethodGetSystemConfig = "getSystemConfig"
	MethodGetPower        = "getPower"
	MethodRegistration    = "registration"
	MethodSyncPilot       = "syncPilot"
	MethodFirstBeat       = "firstBeat"
)

Methods of the local API used here.

Variables

View Source
var ErrDevice = errors.New("the device refused the request")

ErrDevice is wrapped by errors the device returned.

View Source
var Scenes = []Scene{
	{1, "Ocean"}, {2, "Romance"}, {3, "Sunset"}, {4, "Party"}, {5, "Fireplace"}, {6, "Cozy"},
	{7, "Forest"}, {8, "Pastel colors"}, {9, "Wake-up"}, {10, "Bedtime"}, {11, "Warm white"},
	{12, "Daylight"}, {13, "Cool white"}, {14, "Night light"}, {15, "Focus"}, {16, "Relax"},
	{17, "True colors"}, {18, "TV time"}, {19, "Plantgrowth"}, {20, "Spring"}, {21, "Summer"},
	{22, "Fall"}, {23, "Deep dive"}, {24, "Jungle"}, {25, "Mojito"}, {26, "Club"}, {27, "Christmas"},
	{28, "Halloween"}, {29, "Candlelight"}, {30, "Golden white"}, {31, "Pulse"}, {32, "Steampunk"},
	{33, "Diwali"}, {34, "White"}, {35, "Alarm"}, {36, "Snowy sky"}, {40, "Dim-to-warm"}, {1000, "Rhythm"},
}

Scenes are the built-in scene IDs of the WiZ local API with their names as the WiZ app shows them.

Functions

func AnswerAddr

func AnswerAddr(from *net.UDPAddr) string

AnswerAddr is a device's API address (host:port) taken from an answer to a request or to discovery: devices answer from their API port.

func Discover

func Discover(ctx context.Context, broadcast, phoneMAC string, wait time.Duration) (map[string]string, error)

Discover sends the discovery form of a registration to broadcast (host:port; "255.255.255.255:38899" also goes to the directed broadcast address of every LAN interface) three times, a second apart, and collects the answers until wait has passed or ctx ends. It returns each device's API address by normalised MAC.

func HasScene

func HasScene(c Class, id int) bool

HasScene reports whether a class of light offers the scene.

func LocalIPFor

func LocalIPFor(dev *net.UDPAddr) string

LocalIPFor returns the local IPv4 address the route to dev uses: the address to register when none is configured. "" when there is no route.

func NormaliseMAC

func NormaliseMAC(s string) string

NormaliseMAC lower-cases a MAC address and drops separators; "" when it is not 12 hexadecimal digits.

func PushedAddr

func PushedAddr(from *net.UDPAddr, prev string) string

PushedAddr is a device's API address after a push from it. A light pushes from a port of its own, not from its API port, so only the IP is taken from the push (which keeps a changed DHCP lease current); the port stays the one in prev, the address the device was known at, or 38899 when prev has none. Taking the push's source port instead would send later requests to a port nothing listens on.

func Register

func Register(conn *net.UDPConn, dev *net.UDPAddr, phoneMAC, phoneIP string) error

Register asks the device at dev to push its state changes (syncPilot) and power-ups (firstBeat) to phoneIP, port 38900. It is sent from conn, the socket the pushes are read from, so the device's answer reaches that socket too. Devices forget a registration after a while; send it again every 20 seconds or so.

func RegistrationParams

func RegistrationParams(phoneMAC, phoneIP string, register bool) map[string]any

RegistrationParams are the params of a registration: phoneMac (12 hexadecimal digits), phoneIp (where pushes go) and register (true asks for pushes; false is the discovery form).

func Request

func Request(ctx context.Context, addr, method string, params map[string]any, timeout time.Duration) (json.RawMessage, error)

Request sends a message to a device and waits for the answer with the same method, resending with a growing gap (0.75 s, doubling, at most 3 s) until timeout: UDP loses datagrams and a bulb on busy Wi-Fi misses some.

func SceneID

func SceneID(name string) (int, bool)

SceneID finds a scene by name (case, spaces and hyphens ignored, so "wake up" is Wake-up) or by its number.

func SceneName

func SceneName(id int) string

SceneName returns a scene's name; "" for 0 (no scene) and an unknown ID as "scene <id>".

func ScenesFor

func ScenesFor(c Class) []string

ScenesFor lists the scene names a class of light offers.

func ServePush

func ServePush(conn *net.UDPConn, phoneMAC string, handle func(Push)) error

ServePush reads pushes from conn until conn is closed and calls handle for each, in order. A syncPilot is acknowledged to its sender as phoneMAC before handle runs; datagrams that are not pushes (answers to requests sent from conn, for example) are skipped. It returns the read error that ended it.

func WithPort

func WithPort(addr string, port int) string

WithPort adds the default port to an address without one.

Types

type Class

type Class string

Class is what a WiZ module can do, told from its module name.

const (
	ClassRGB     Class = "rgb"    // colour, tunable white, dimming, scenes
	ClassTW      Class = "tw"     // tunable white, dimming, scenes
	ClassDW      Class = "dw"     // dimming, a few scenes
	ClassSocket  Class = "socket" // on and off, power where reported
	ClassUnknown Class = "unknown"
)

The classes. The module name's second underscore-separated segment carries the class ("ESP01_SHRGB1C_31": RGB; "ESP56_SHTW3_01": tunable white; "ESP05_SHDW9_01": dimmable white; "ESP10_SOCKET_06": plug).

func ClassOf

func ClassOf(module string) (c Class, ok bool)

ClassOf tells the class of a module name. ok is false for a module the package does not know (fans, a form it cannot read).

Example
package main

import (
	"fmt"

	"github.com/cB-Sigma/wiz"
)

func main() {
	for _, m := range []string{"ESP01_SHRGB1C_31", "ESP05_SHDW9_01", "ESP10_SOCKET_06", "ESP03_FANDIMS_01"} {
		c, ok := wiz.ClassOf(m)
		fmt.Println(m, c, ok)
	}
}
Output:
ESP01_SHRGB1C_31 rgb true
ESP05_SHDW9_01 dw true
ESP10_SOCKET_06 socket true
ESP03_FANDIMS_01 unknown false

type Message

type Message struct {
	Method string          `json:"method"`
	Env    string          `json:"env,omitempty"`
	ID     any             `json:"id,omitempty"`
	Params map[string]any  `json:"params,omitempty"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  *struct {
		Code    int    `json:"code"`
		Message string `json:"message"`
	} `json:"error,omitempty"`
}

Message is one datagram of the local API.

type Pilot

type Pilot struct {
	MAC     string   `json:"mac,omitempty"`
	State   *bool    `json:"state,omitempty"`
	Dimming *float64 `json:"dimming,omitempty"`
	R       *float64 `json:"r,omitempty"`
	G       *float64 `json:"g,omitempty"`
	B       *float64 `json:"b,omitempty"`
	C       *float64 `json:"c,omitempty"`
	W       *float64 `json:"w,omitempty"`
	Temp    *float64 `json:"temp,omitempty"`
	SceneID *float64 `json:"sceneId,omitempty"`
	Speed   *float64 `json:"speed,omitempty"`
	// Raw is every key as sent.
	Raw map[string]any `json:"-"`
}

Pilot is the light state of getPilot, setPilot and syncPilot. Fields the device leaves out stay nil.

func ParsePilot

func ParsePilot(b []byte) (Pilot, error)

ParsePilot reads a pilot object.

type Push

type Push struct {
	// Method is MethodSyncPilot or MethodFirstBeat.
	Method string
	// MAC is the device's MAC address, normalised; "" when the push did not
	// carry a valid one.
	MAC string
	// Pilot is the state a syncPilot carries.
	Pilot Pilot
	// From is the datagram's source. A device pushes from a port of its
	// own, not from its API port: use PushedAddr to follow its address.
	From *net.UDPAddr
}

Push is one datagram a device pushed to the registered address.

type Scene

type Scene struct {
	ID   int
	Name string
}

Scene is a built-in scene (light mode) of WiZ lights.

type SystemConfig

type SystemConfig struct {
	MAC        string `json:"mac"`
	ModuleName string `json:"moduleName"`
	FwVersion  string `json:"fwVersion"`
	TypeID     *int   `json:"typeId,omitempty"`
	HomeID     *int   `json:"homeId,omitempty"`
	RoomID     *int   `json:"roomId,omitempty"`
}

SystemConfig is the part of a getSystemConfig answer this package reads.

func ParseSystemConfig

func ParseSystemConfig(b []byte) (SystemConfig, error)

ParseSystemConfig reads a getSystemConfig result; MAC is normalised ("" when it is not a MAC address).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL