Gadget Skills Catalog
Relevant source files
The following files were used as context for generating this wiki page:
The Gadget Skills Catalog contains community-sourced instructions that enable Muse Gadgets to interact with third-party devices and services. These skills allow Muse to control displays, sensors, actuators, and smart home appliances through a local network tunnel.
Sources: README.md:32-35, skills/README.md:1-3
Overview of Gadget Skills
Gadget skills are Markdown-based documents that define how Muse should discover, authenticate, and interact with specific hardware. These skills are not official integrations but community-contributed recipes. Users can implement these by providing a link to the GitHub repository in a Muse chat or by pasting the contents of a SKILL.md file directly.
Each skill typically includes:
- YAML Metadata: Defines the skill name and description.
- Identification logic: Instructions for finding the device on the network.
- Workflow: Step-by-step procedures for interaction.
- Limits: Constraints and safety rules for the specific integration.
Sources: skills/README.md:5-13, skills/gadget-esphome-devices/SKILL.md:1-7
Integration Architecture
The following diagram illustrates how Muse interacts with third-party devices using the local network tunnel and defined skills.
This diagram shows the relationship between the Muse cloud, the local Home Link tunnel, and the skill execution on a local device.
Sources: README.md:50-54, skills/gadget-esphome-devices/SKILL.md:14-16
Supported Device Categories
The catalog currently includes skills for several ecosystem types and communication protocols.
ESPHome Devices
This skill controls entities exposed by ESPHome firmware. It uses either a native TCP API or a web-based HTTP API.
- API Client: Uses the
aioesphomeapiclient for native connections. - Discovery: Relies on service metadata to confirm firmware versions and enabled interfaces.
- Functions: Supports reading sensors and calling commands for switches, lights, or covers.
Sources: skills/gadget-esphome-devices/SKILL.md:1-5, skills/gadget-esphome-devices/SKILL.md:18-28
Google Cast
The Google Cast skill manages media playback and receiver control. It acts as a shared procedure for other device skills that utilize the Cast protocol.
- Protocol: Uses PyChromecast via the Home Link network.
- Endpoints: Connects to the device's IPv4 address and advertised port (typically 8009).
- Operations: Includes volume control, playback (pause, resume, seek, stop), and media loading.
Sources: skills/gadget-google-cast/SKILL.md:1-12, skills/gadget-google-cast/SKILL.md:34-40
Smart Plugs (Meross)
This skill interacts with Meross smart plugs using a signed local HTTP interface.
- Authentication: Requires a device UUID and a local key for signing requests.
- Endpoints: Interacts with the
/configendpoint of the device. - Logic: Sends signed JSON envelopes to toggle relay states and inspect appliance abilities.
Sources: skills/gadget-meross-smart-plugs/SKILL.md:1-12, skills/gadget-meross-smart-plugs/SKILL.md:18-24
Skill Components Comparison
| Skill Name | Protocol | Primary Interface | Authentication Required |
|---|---|---|---|
gadget-esphome-devices | Native API / HTTP | aioesphomeapi | Encryption Key / Web Auth |
gadget-google-cast | Cast v2 | PyChromecast | None (Local) |
gadget-meross-smart-plugs | HTTP | Signed JSON Envelope | UUID + Local Key |
Sources: skills/gadget-esphome-devices/SKILL.md:1-3, skills/gadget-google-cast/SKILL.md:1-5, skills/gadget-meross-smart-plugs/SKILL.md:1-3
Interaction Workflow
Skills follow a standardized progression to ensure safe and accurate device control.
- Identification: Match discovered network services (e.g.,
_googlecast._tcp) to specific device models. - Prerequisite Check: Ensure the device is provisioned and the Home Link tunnel is active.
- Status Reading: Read current state (e.g.,
Appliance.System.Allfor Meross orcast.statusfor Google Cast) before sending commands. - Action Execution: Convert user requests into specific API calls based on advertised entity capabilities.
- Verification: Read the state back after an action to confirm success.
Sources: skills/gadget-esphome-devices/SKILL.md:18-35, skills/gadget-google-cast/SKILL.md:34-45, skills/gadget-meross-smart-plugs/SKILL.md:18-27
Safety and Limits
Every skill operates under strict constraints to prevent unauthorized or unsafe actions:
- Physical Safety: Skills must follow shared physical-action safety rules found in project documentation.
- No Cloud Dependency: Most skills prioritize local control over cloud-based account or key acquisition.
- No Arbitrary Scripts: Skills generally prohibit executing arbitrary device scripts or network reconfigurations.
- Verification Requirement: Commands like toggles or movement should not be retried until the first outcome is verified.
Sources: skills/gadget-esphome-devices/SKILL.md:38-42, skills/gadget-google-cast/SKILL.md:58-65, skills/gadget-meross-smart-plugs/SKILL.md:30-33
The Gadget Skills Catalog provides a framework for extending Muse's capabilities to a wide variety of local hardware, leveraging standard protocols and community knowledge while maintaining a focus on local execution.