Gateways & Local Hardware Bridges
Relevant source files
The following files were used as context for generating this wiki page:
Gateways and local hardware bridges interface Muse Home Link with external smart home ecosystems, protocols, and hardware families. These modules act as translation layers, allowing Muse to control devices that communicate via non-IP protocols (like Zigbee or Lutron Clear Connect) or proprietary local IP interfaces.
Local hardware bridges focus on secure, local-only communication, typically requiring physical authorization (like button presses) or local application keys to establish trust. By leveraging these bridges, Muse Gadgets can manage entire families of devices—such as lights, shades, and plugs—through a single central point of contact.
Integration Architectures
The project employs several architectural patterns to communicate with local bridges, depending on the protocol and bridge type.
Zigbee2MQTT Architecture
Zigbee2MQTT integration uses an MQTT broker as the intermediary. Muse subscribes to status topics and publishes command topics to control Zigbee devices via the bridge.
Bridge Discovery and Identification
Identification varies by bridge type, utilizing service metadata, advertised endpoints, or specific local discovery ports.
| Bridge Type | Identification Method | Primary Protocol/API |
|---|---|---|
| Zigbee2MQTT | Base topic + MQTT Broker | MQTT |
| Lutron Smart Bridge | HAP or LEAP service metadata | HAP / LEAP |
| Philips Hue | _hue._tcp advertisement | CLIP v2 (REST) |
| Tuya Wi-Fi | TCP Port 6668 | Tuya Local TCP |
| ESPHome | Firmware service metadata | Native TCP / HTTP |
Sources: skills/gadget-zigbee2mqtt-gateways/SKILL.md:7-12, skills/gadget-lutron-smart-bridges/SKILL.md:10-14, skills/gadget-philips-hue-bridges/SKILL.md:11-16, skills/gadget-tuya-wifi-devices/SKILL.md:11-16, skills/gadget-esphome-devices/SKILL.md:11-14
Authentication and Pairing
Secure pairing is required for most local hardware bridges. Muse Home Link prioritizes existing local credentials or physical authorization over cloud-based account links.
Pairing Flow (Lutron/Hue)
Bridges like Lutron and Philips Hue require a specific pairing handshake, often involving a physical button press on the hardware to authorize the new client.
Credential Requirements
- Philips Hue: Local application key obtained via bridge button.
- Lutron Smart Bridge: Eight-digit setup code (HAP) or client certificate/private key (LEAP).
- Meross/Tuya: Device UUID and existing local encryption keys.
- ESPHome: Native API encryption keys or web authentication passwords.
Sources: skills/gadget-meross-smart-plugs/SKILL.md:17-20, skills/gadget-tuya-wifi-devices/SKILL.md:18-21, skills/gadget-esphome-devices/SKILL.md:17-20
Operational Workflows
Command Execution and State Mapping
Muse Home Link follows a "Read-Map-Write-Verify" workflow when interacting with hardware bridges to ensure technical accuracy and safety.
- Read: Enumerate entities and their current state using bridge-specific endpoints (e.g.,
/clip/v2/resource/lightfor Hue ordefinition.exposesfor Zigbee2MQTT). - Map: Convert Muse-standard commands to bridge-specific datapoints (Tuya) or characteristics (Lutron HAP).
- Write: Publish/Send minimal body payloads (e.g.,
{"on":{"on":true}}). - Verify: Observe state updates; physical action success is not inferred from transport acknowledgement alone.
Sources: skills/gadget-philips-hue-bridges/SKILL.md:27-38, skills/gadget-tuya-wifi-devices/SKILL.md:24-30, skills/gadget-zigbee2mqtt-gateways/SKILL.md:20-27
Safety and Physical Action Rules
- Non-Retriability: Do not retry toggle or movement commands until an uncertain first outcome is verified.
- Unit Conversion: Convert units and ranges based on the specific entity metadata provided by the bridge.
- Authorization: Entity existence does not imply authorization for actuation; shared physical-action safety rules apply.
Sources: skills/gadget-esphome-devices/SKILL.md:28-36, skills/gadget-meross-smart-plugs/SKILL.md:31-33
Technical Limits
| Feature | Limitation |
|---|---|
| Provisioning | Skills do not perform firmware installation or network reconfiguration. |
| Discovery | No cloud discovery or fallback; strictly local network access. |
| Actuation | Trial-and-error writing to unknown datapoints is strictly prohibited. |
| Legacy Support | Round Hue BSB001 and legacy Tuya protocol versions may be unsupported. |
Sources: skills/gadget-philips-hue-bridges/SKILL.md:46-49, skills/gadget-tuya-wifi-devices/SKILL.md:36-40, skills/gadget-esphome-devices/SKILL.md:39-43
Gateways and Local Hardware Bridges provide the necessary connectivity for Muse to interact with diverse hardware ecosystems while maintaining a local-first, secure architecture. These modules ensure that Muse Home Link can safely and accurately control external devices through standardized command mapping and verification workflows.