Skip to content

wiz2mqtt

License: MIT Python cosalette

WiZ smart bulb control over MQTT for openHAB and Home Assistant

wiz2mqtt turns one or more WiZ bulbs into MQTT entities with low-latency, push-driven state publication and partial JSON command handling. Each configured bulb gets its own retained state topic, command topic, and availability signal.

  • Getting Started

    Install wiz2mqtt and see your first MQTT messages.

    Get started

  • Configuration

    All settings — environment variables, .env files, and CLI flags.

    Configure

  • MQTT Topics

    Topic reference with payload schemas, directions, and retain flags.

    Topics

Features

  • Per-bulb command topic with partial JSON updates (state, brightness, color, color_temp, effect)
  • Push-driven state publication via local triggers, with a 60-second heartbeat as the liveness floor
  • Retained MQTT state payloads shaped for Home Assistant and openHAB
  • Runtime Home Assistant MQTT discovery (app.discovery()) — one device per bulb with light, effect-speed number, and power sensor entities
  • Offline openHAB Generic MQTT Thing + Items generation (cosalette schema openhab)
  • Optional bare-hex MAC verification on first successful bulb contact
  • Config-file bulb inventory (wiz2mqtt.toml) with environment overrides

Deployment Model

Item Notes
Bulbs One or more WiZ bulbs reachable on the local network
Identity Configure a stable name, IPv4 ip, and optional bare-hex mac
MQTT Inherits cosalette MQTT settings; default topic prefix is wiz2mqtt
Freshness Push updates publish immediately; the heartbeat probes bulbs that have gone silent