Smart Home

Overview

Melian controls smart home devices from two ecosystems: Govee and Wiz. Both use UDP for fast LAN-based control without cloud latency. Govee additionally supports a cloud REST API as fallback for devices that lack LAN capability (such as the H5179 hygrometer). Device registries are persisted as JSON files so discovered devices survive restarts.

Govee

Interfaces

export interface GoveeDevice {
  id: string;
  ip: string;
  sku: string;
  type: "light" | "sensor";
  name: string;
  room: string;
  reachable: boolean;
  lanCapable: boolean;
}

export interface GoveeControlParams {
  state?: boolean;
  brightness?: number;           // 0–100
  color?: { r: number; g: number; b: number };
  colorTemp?: number;            // Kelvin
}

Tools

Tool	Parameters	Description
`govee_discover`	-	Broadcast UDP discovery and return found devices
`govee_register_device`	`id: string`, `name: string`, `room: string`	Add a device to the persistent registry
`govee_list_devices`	-	List all registered Govee devices
`govee_control`	`device: string`, `state?: boolean`, `brightness?: number`, `color?: {r,g,b}`, `colorTemp?: number`	Send a control command to a device (LAN or cloud fallback)
`govee_read_sensor`	`device: string`	Read sensor data (temperature, humidity) from a device

API Endpoints

Method	Path	Description
`GET`	`/govee/devices`	List registered devices
`POST`	`/govee/devices/:id/control`	Send control params to a device
`GET`	`/govee/devices/:id/sensor`	Read sensor data (temperature, humidity)
`POST`	`/govee/discover`	Trigger a UDP discovery sweep

Wiz

Interfaces

export interface WizDevice {
  id: string;
  mac: string;
  ip: string;
  name: string;
  room: string;
  module: string;
  firmware: string;
  reachable: boolean;
}

export interface WizControlParams {
  state?: boolean;
  brightness?: number;    // 0–100
  colorTemp?: number;     // Kelvin
}

Tools

Tool	Parameters	Description
`wiz_discover`	-	Broadcast UDP discovery and return found devices
`wiz_register_device`	`mac: string`, `name: string`, `room: string`	Add a device to the persistent registry
`wiz_list_devices`	-	List all registered Wiz devices
`wiz_control`	`device: string`, `state?: boolean`, `brightness?: number`, `colorTemp?: number`	Send a control command to a device

API Endpoints

Method	Path	Description
`GET`	`/wiz/devices`	List registered devices
`POST`	`/wiz/devices/:id/control`	Send control params to a device
`POST`	`/wiz/discover`	Trigger a UDP discovery sweep

Architecture

Both integrations follow the same pattern: a UDP broadcast discovers devices on the local network, the operator registers them with a name and room, and commands are sent directly to the device IP over UDP. The registry JSON is written to disk on every change.

For Govee devices without LAN support (lanCapable: false), the control path falls back to the Govee cloud REST API using configured API credentials. Sensor polling for the H5179 hygrometer always uses the cloud path since it does not expose a LAN control interface.

Smart home devices integrate with the job system. The night-time-lights job, for example, runs on a schedule and dims all lights in specified rooms at bedtime.