Yeelight (LAN)

GEM controls Yeelight Wi-Fi bulbs and lamps (Color, White, LED Strip 1S, Bedside Lamp 2, Ceiling Light, etc.) directly over the LAN, bypassing the Xiaomi cloud. One GEM device row represents one bulb.

Prerequisites

• The bulb is set up in the Yeelight app or the Mi Home app and joined to the same Wi-Fi network as the GEM controller.
• LAN Control is enabled on the bulb. Open the bulb in the Yeelight app → Settings (gear icon) → toggle LAN Control ON. The setting persists; you only need to do it once per device. Without this, TCP port 55443 is closed and GEM cannot connect.
• A reserved DHCP lease (or static IP) for the bulb. Yeelight devices do not advertise mDNS by default, and the GEM device row stores an IP — not a host name.

Setup

1. In the Yeelight or Mi Home app, enable LAN Control on the bulb.
2. Find the bulb's IP in your router's DHCP table (or in the Yeelight app bulb info panel) and reserve the lease.
3. In GEM admin → Devices → Add Device, pick driver yeelight_lan. Enter the bulb's IP. Leave the port at the default 55443.
4. Save and enable. The driver will:
   • Open a TCP socket on 55443.
   • Issue get_prop for power, bright, ct, rgb, hue, sat, and color_mode.
   • Surface those as device attributes (power_state, level, color_temp, rgb_hex, hue, saturation, color_mode).
   • Subscribe to push notifications — Yeelight sends a {"method":"props", ...} line whenever any of those properties change, and the driver folds them into device attributes without polling.

Attribute reference

Device

Attribute	Required	Description
ip	yes	LAN IP of the bulb. Reserve a DHCP lease so it does not change.
port	no	TCP port. Hardcoded to 55443 on the bulb — only change for a TCP proxy.
transition_ms	no	Default crossfade for power, brightness, CT and color changes. Yeelight accepts 30..30 000 ms; under 30 the bulb falls back to "sudden". Default 500.
status_interval	no	Belt-and-suspenders poll cadence in ms. Default 60 000 (props notifications cover the common case).
request_timeout	no	Per-request timeout in ms. Default 5 000.

The bulb also writes state into these attributes on connect and on every props notification: power_state, state, level, color_temp, rgb_hex, hue, saturation, color_mode.

Zone address format

This driver does not use zones — one device row = one bulb. Leave zone.address blank if the bulb is wired into a zone for macro/UI purposes; the driver dispatches commands without an address.

Command reference

Command	Args	Effect
on / off	–	set_power on/off with the default transition.
toggle	–	Native toggle method on the bulb.
set_level	level (1..100)	set_bright. Note: bright=0 is silently rejected by the bulb — use off.
set_ct	ct (1700..6500 K)	set_ct_abx. Clamped to the protocol range; the bulb rejects values outside its supported window.
set_rgb	rgb (ff8800 hex or 0..16777215 decimal)	set_rgb. White-only bulbs reject this silently.
set_hsv	hue (0..359), sat (0..100)	set_hsv.
set_default	–	Save the current state as the bulb's power-on default.
get_status	–	Refresh power/bright/ct/rgb/hue/sat/color_mode.
raw_command	method, params (JSON array string)	Send any Yeelight method directly, e.g. start_cf, set_music, set_scene.

What's not yet supported

• Color flow (start_cf / stop_cf). Reachable via raw_command — pass the flow expression as the second element of the params array.
• Scenes (set_scene). Reachable via raw_command.
• Music mode (set_music). The protocol opens a back-channel TCP listener on the GEM controller so the bulb connects in the reverse direction, allowing >60 cmd/min without rate-limit. Not wired up here yet; large lighting installs that need it should wire it via a custom subclass.
• Background light on dual-LED ceiling fixtures (bg_set_power, bg_set_bright, etc.). Reachable via raw_command.
• Discovery via SSDP multicast on UDP 1982. GEM expects an IP in the device row; SSDP-based auto-add is out of scope.

Troubleshooting

• Socket connect refused or times out. LAN Control is off on the bulb. Open the Yeelight or Mi Home app → bulb → Settings → LAN Control → ON.
• set_rgb has no effect on a white-only bulb. White-only Yeelights silently reject RGB writes. Use set_bright and set_ct instead.
• client quota exceeded from the bulb. Caller is firing more than ~60 commands per minute. Either slow the caller (e.g., merge level changes through a debounce in your macro), or open music mode via set_music and dispatch over that channel.
• State stops updating after using the Yeelight app. The app can sometimes hold the LAN port open in a way that masks props notifications. Power-cycle the bulb; the driver auto-reconnects.
• Bulb was factory-reset and now ignores GEM. Factory reset clears LAN Control. Pair the bulb again in the app and re-enable LAN Control.