Creature MQTT is the bridge between my creature network and Home Assistant. It connects to the Creature Server’s WebSocket, picks up all the real-time events flowing through the system, and republishes them as MQTT topics that Home Assistant can consume.
Like the Creature Agent, it’s part of the shared Swift package in the creature-console repo on GitHub.
Why MQTT?
Home Assistant has great MQTT support, and I wanted creature data to show up alongside all of my other home automation sensors. Now I can see board temperatures, motor current draw, active animations, and system health right in my Home Assistant dashboards. I can also use creature state as triggers for automations — for example, knowing when a creature is idle vs actively playing an animation.
What Gets Published
Pretty much everything the server knows about. The bridge handles over 14 different event types:
- Board sensor data (temperature, voltage)
- Motor sensor data (current draw, position)
- Creature activity state (idle, playing, streaming)
- Active animation and playlist information
- System counters and health metrics
- Server log events and watchdog warnings
Topics are published as scalar values, not JSON blobs. So instead of one big JSON payload, you get clean topics like creatures/beaky/sensors/board/temperature_f. This makes it much easier to work with in Home Assistant since each value maps directly to a sensor entity.
Smarts
It’s not just a dumb relay. The bridge resolves creature UUIDs to friendly names (so topics use “beaky” instead of a UUID), caches animation titles, and deduplicates unchanged values so the MQTT broker isn’t flooded with redundant publishes. If the connection drops, it reconnects automatically with exponential backoff.
There’s also filtering built in — you can use --hide and --only flags to control which event types get published, which is helpful for debugging or if you only care about certain data.
This is one of those pieces that isn’t flashy on its own, but it’s the glue that makes everything else possible. The Creature Agent can react to events because creature state is visible in Home Assistant, and that visibility comes from this bridge. It’s a small tool that punches way above its weight.