Smart Plugs, Lighting & Appliances
Relevant source files
The following files were used as context for generating this wiki page:
The Muse Gadget SDK supports a wide variety of smart home hardware through local network protocols. These devices include smart plugs with power metering, lighting systems (bridges and individual lights), and household appliances. Integration relies on Muse Home Link to facilitate local communication between the Muse gadget and the target device without requiring cloud dependencies for runtime operations.
Integration is achieved through "skills," which define the specific identification, authentication, and communication workflows for each device family. These skills ensure that Muse can read device status, execute switching commands, and monitor sensor data like energy consumption or light levels while adhering to safety rules for physical actuators.
Sources: skills/README.md, skills/CATALOG.md, skills/gadget-shelly-plugs/SKILL.md:12-14
Smart Plugs and Power Metering
Smart plugs in the Muse ecosystem provide relay switching and energy monitoring. Support covers major vendors like Shelly, TP-Link Kasa, and Meross. Each vendor requires specific local API implementations, such as RPC over HTTP or signed local HTTP requests.
Supported Plug Features
| Vendor | Model/Series | Key Capabilities | Protocol |
|---|---|---|---|
| Shelly | Gen 4 Plugs | Relay switching, power/energy measurements, auto-off timers. | RPC over HTTP |
| TP-Link | Kasa EP25 | Authenticated switching, energy readings, LED control, auto-off. | SMART local protocol |
| Meross | Various | Local relay switching with signed requests. | Signed Local HTTP |
Sources: skills/gadget-shelly-plugs/SKILL.md:1-6, skills/gadget-tplink-kasa-ep25/SKILL.md:1-6, skills/gadget-meross-smart-plugs/SKILL.md:1-6
Shelly Gen 4 Workflow
Shelly Gen 4 devices utilize a local RPC API. The workflow involves identifying the device via Shelly.GetDeviceInfo and managing the relay through Switch.Set commands.
The diagram shows the standard RPC sequence for querying and controlling a Shelly plug.
Sources: skills/gadget-shelly-plugs/SKILL.md:20-30
Lighting Systems and Bridges
Lighting control is handled either through direct device APIs or gateway bridges that manage multiple Zigbee or proprietary radio nodes.
Philips Hue Bridges
Philips Hue integration focuses on the CLIP v2 API supported by BSB002 bridges. It allows for control of individual lights, rooms, zones, and the recall of pre-defined scenes.
- Authentication: Requires a local application key obtained through physical button pairing.
- Resources: Managed via
/clip/v2/resource/lightand/clip/v2/resource/scene. - Capabilities: Includes on/off, dimming (percentage), and color temperature (mirek_schema).
Sources: skills/gadget-philips-hue-bridges/SKILL.md:12-30
Lutron Smart Bridges
Lutron bridges (Caséta) are controlled via HAP (HomeKit Accessory Protocol) or LEAP.
- HAP Pairing: Uses an eight-digit setup code. If the bridge is already paired with Apple Home, Muse requires independent authorization.
- LEAP Protocol: Uses a separate physical pairing flow with client certificates and private keys.
- Actuators: Supports both lighting and motorized shades.
Sources: skills/gadget-lutron-smart-bridges/SKILL.md:12-35
Gateway and Firmware Integration
Muse can interact with broad device ecosystems through gateways like Zigbee2MQTT or custom firmware like ESPHome.
Zigbee2MQTT
This skill leverages an existing MQTT broker to communicate with Zigbee devices. Muse subscribes to bridge topics to discover device definitions and their "exposes" bitmask, which determines if a property is readable, writable, or queryable.
This flowchart illustrates the access control logic derived from Zigbee2MQTT device definitions.
Sources: skills/gadget-zigbee2mqtt-gateways/SKILL.md:19-30
ESPHome Devices
Muse interacts with ESPHome via the Native TCP API (using aioesphomeapi) or the built-in Web Server API. Identification depends on firmware service metadata and entity enumeration.
- Entities: Sensors, switches, lights, and covers.
- Authentication: Requires the native API encryption key or web credentials.
- Feedback: Muse distinguishes between optimistic target states and measured feedback from physical sensors.
Sources: skills/gadget-esphome-devices/SKILL.md:12-32
Safety and Networking Rules
All smart home skills must adhere to the core Home Link safety guidelines when performing physical actions:
- Identity Confirmation: Metadata like
_http._tcphostnames or UUIDs must be used to match devices; vendor labels alone are insufficient. - Load Identification: You must identify what is plugged into a smart plug (e.g., medical equipment, heaters) before performing switching.
- Authentication: Credentials must be stored in secure, approved storage. Do not pass passwords in plain-text command strings.
- No Toggles for Retries: Do not use "toggle" commands as a retry for failed explicit ON/OFF requests.
Sources: skills/gadget-shelly-plugs/SKILL.md:16-19, skills/gadget-esphome-devices/SKILL.md:18-20, skills/gadget-meross-smart-plugs/SKILL.md:12-16
Summary
The Smart Plugs, Lighting & Appliances module provides a robust framework for local home automation. By leveraging vendor-specific local protocols—ranging from MQTT for Zigbee2MQTT to encrypted HAP for Lutron—Muse maintains control within the local network. The use of specific "skills" ensures that authentication and safety boundaries are respected while providing Muse with real-time feedback on device energy usage and operational state.