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)
}
}
}
Output:
Index ¶
- Constants
- Variables
- func AnswerAddr(from *net.UDPAddr) string
- func Discover(ctx context.Context, broadcast, phoneMAC string, wait time.Duration) (map[string]string, error)
- func HasScene(c Class, id int) bool
- func LocalIPFor(dev *net.UDPAddr) string
- func NormaliseMAC(s string) string
- func PushedAddr(from *net.UDPAddr, prev string) string
- func Register(conn *net.UDPConn, dev *net.UDPAddr, phoneMAC, phoneIP string) error
- func RegistrationParams(phoneMAC, phoneIP string, register bool) map[string]any
- func Request(ctx context.Context, addr, method string, params map[string]any, ...) (json.RawMessage, error)
- func SceneID(name string) (int, bool)
- func SceneName(id int) string
- func ScenesFor(c Class) []string
- func ServePush(conn *net.UDPConn, phoneMAC string, handle func(Push)) error
- func WithPort(addr string, port int) string
- type Class
- type Message
- type Pilot
- type Push
- type Scene
- type SystemConfig
Examples ¶
Constants ¶
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.
const ( MethodGetPilot = "getPilot" MethodSetPilot = "setPilot" MethodGetSystemConfig = "getSystemConfig" MethodGetPower = "getPower" MethodRegistration = "registration" MethodSyncPilot = "syncPilot" MethodFirstBeat = "firstBeat" )
Methods of the local API used here.
Variables ¶
var ErrDevice = errors.New("the device refused the request")
ErrDevice is wrapped by errors the device returned.
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 ¶
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 LocalIPFor ¶
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 ¶
NormaliseMAC lower-cases a MAC address and drops separators; "" when it is not 12 hexadecimal digits.
func PushedAddr ¶
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 ¶
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 ¶
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 ¶
SceneID finds a scene by name (case, spaces and hyphens ignored, so "wake up" is Wake-up) or by its number.
func SceneName ¶
SceneName returns a scene's name; "" for 0 (no scene) and an unknown ID as "scene <id>".
func ServePush ¶
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.
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 ¶
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.
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 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).