MQTT

Homecast publishes real-time device state to MQTT and accepts commands. Compatible with Home Assistant, Node-RED, and any MQTT client.

Connecting

Setting	Value
Host	mqtt.homecast.cloud
Port	8883 (TLS) or 1883
Username	(leave blank)
Password	Your API access token (hc_...)

Create an access token in Settings → API Access, or in the MQTT Browser → Connection Details.

Example

# Subscribe to all topics
mosquitto_sub -h mqtt.homecast.cloud -p 8883 \
  --cafile /etc/ssl/cert.pem \
  -u "" -P "hc_your_token_here" \
  -t "homecast/#" -v

# Turn off a light
mosquitto_pub -h mqtt.homecast.cloud -p 8883 \
  --cafile /etc/ssl/cert.pem \
  -u "" -P "hc_your_token_here" \
  -t "homecast/my-home-a1b2/living-room-c3d4/desk-lamp-e5f6/set" \
  -m '{"on": false}'

Topics

Follows the Zigbee2MQTT convention: the base topic is the device state, /set is for commands.

Device state

homecast/{home}/{room}/{accessory}

Retained JSON with all characteristics, sorted alphabetically:

{"brightness": 80, "color_temp": 200, "on": true}

Device commands

homecast/{home}/{room}/{accessory}/set

Publish a JSON object with the characteristics to change:

{"on": false}
{"brightness": 50, "color_temp": 300}

Availability

homecast/{home}/{room}/{accessory}/availability

Retained string: "online" or "offline".

Service groups

Groups control multiple devices at once (e.g., "All Kitchen Lights"):

homecast/{home}/{room}/{group}              # group state
homecast/{home}/{room}/{group}/set          # control all devices in group
homecast/{home}/{room}/{group}/members      # JSON array of member slugs

Scenes

homecast/{home}/scene/{scene}/execute

Publish any payload to trigger the scene.

Home status

homecast/{home}/status

Retained: "online" or "offline". Updated via MQTT Last Will and Testament.

Home Assistant auto-discovery

homeassistant/{component}/homecast_{id}/config

Retained JSON with HA discovery payload. Published automatically when MQTT is enabled. Devices appear in Home Assistant without manual configuration.

Slugs

Topic segments use the format {name}-{first 4 hex of UUID}:

• county-hall-2d10 (home)
• kitchen-dfee (room)
• desk-lamp-e5f6 (accessory)
• kitchen-lights-182f (service group)

Slugs are stable — renaming a device in HomeKit doesn't change the slug.

Editions

Feature	Community	Cloud
Custom MQTT brokers	Connect Mac app to your broker	Store in DB, cloud bridge connects
Homecast Broker (mqtt.homecast.cloud)	Not available	Per-home toggle in Settings
MQTT Browser	At homecast.cloud/mqtt	Also at mqtt.homecast.cloud
HA auto-discovery	Published by Mac app	Published by cloud bridge
Service group support	Via Mac app	Via cloud bridge

MQTT Browser

Browse live device state and publish commands at mqtt.homecast.cloud or homecast.cloud/mqtt.

Features:

• Auto-connects with your Homecast session
• Filter by home and room
• Visual controls: toggles for booleans, sliders for brightness/color
• Raw JSON editor for advanced use
• Publish history
• Service group support with member list
• Connection details dialog with access token management

Enabling MQTT

1. Go to Settings → Account → enable Developer Mode
2. Go to Settings → Homes → click your home
3. Toggle Homecast Broker on
4. (Optional) Add custom brokers below

Characteristic names

MQTT uses simplified names for HomeKit characteristics:

MQTT name	HomeKit characteristic
on	Power state
brightness	Brightness (0–100)
color_temp	Color temperature (50–500)
hue	Hue (0–360)
saturation	Saturation (0–100)
current_temp	Current temperature
heat_target	Heating threshold
cool_target	Cooling threshold
position	Current position (blinds, 0–100)
target	Target position
locked	Lock state
lock_target	Lock target
motion	Motion detected
contact	Contact sensor state
speed	Fan rotation speed
volume	Speaker volume
mute	Mute state
battery	Battery level
active	Active state
alarm_state	Security system state
alarm_target	Security system target