MQTT Integration Setup Guide
Complete reference for MQTT topics, payloads, and retained messages for the Haptique RS90 remote control system.
The Haptique RS90 uses MQTT with Retained Messages for seamless integration with home automation systems. The remote automatically reports its configuration and state when it connects to the broker—no "Get" commands are needed. Simply subscribe to the topics below, and the broker will deliver current data immediately.
Retained messages persist on the broker. When you subscribe to a topic, you instantly receive the last published value—perfect for device state and configuration data.
1. Device ID (Auto-Reported)
🆔 Remote Device Identifier
The RS90 automatically publishes its unique device ID when connecting to the broker. When the remote first connects to MQTT, it publishes the following topics with device information:
How to Find Your Remote ID
To get your unique RemoteID for use in MQTT topics:
- Open the Haptique Config app on your mobile device.
- Tap the settings icon in the top right corner.
- Find "Connected Haptique" section.
- Look for devices starting with
#cantata-xxx. - Tap on your device entry to view details.
- Copy your unique ID (format: e1c9215be8afe4d2).
If your device ID is e1c9215be8afe4d2, your topics would be:
Haptique/e1c9215be8afe4d2/status
Haptique/e1c9215be8afe4d2/device/list
2. System Status (Auto-Reported)
📡 Connection Status
The remote automatically updates this topic when it connects or disconnects. This uses MQTT's Last Will & Testament (LWT) feature.
The broker automatically sets this to "offline" if the remote loses connection unexpectedly (via LWT).
3. Resource Discovery (Auto-Reported)
The remote publishes its complete configuration to these topics upon connection. All data is retained and immediately available to new subscribers.
📋 Device List
A list of all devices configured on the remote.
🎬 Macro List
A list of all macros configured on the remote.
⌨️ Device Commands
Retrieve the list of available commands for a specific device by subscribing to this topic. The remote publishes the command list as a retained message.
Subscribe to this topic and the remote will automatically send you the retained JSON array of all available commands for that device.
4. Control Topics
Publish to these topics to trigger macros and send device commands to your remote.
🎮 Trigger Macro
Publish to this topic to activate a macro's ON or OFF sequence on the remote.
Payloads are lowercase: use "on" and "off" (not "ON" or "OFF").
📱 Trigger Device Command
Publish to this topic to send a specific command to a device.
Common commands: POWER, VOL_UP, VOL_DOWN, MUTE, PLAY, PAUSE, CH_UP, CH_DOWN
5. Monitoring Topics
🔋 Battery Level
To request battery level, publish to the battery/status topic (without payload). The remote will respond with the battery percentage on the battery_level topic.
1. Publish to Haptique/{RemoteID}/battery/status (no payload needed)
2. Subscribe to Haptique/{RemoteID}/battery_level to receive the percentage value
⌨️ Physical Key Events
The remote automatically reports physical button presses in real-time. No request needed—just subscribe to receive events.
This topic is automatically published whenever any physical button is pressed on the remote. Perfect for monitoring remote usage and creating custom automations based on button presses.
Practical Examples
💡 Example Usage Scenarios
Example 1: Turn On "Movie Night" Macro
Publish this message to trigger your macro:
Example 2: Send POWER Command to Living Room TV
Publish this message to control your device:
Example 3: Monitor Connection Status
Subscribe to receive automatic status updates:
Example 4: Get Device List on Connection
Subscribe to receive the retained device list:
Example 5: Request Battery Level
Step 1 - Publish request (no payload):
Step 2 - Subscribe to receive response:
Example 6: Button Presses
Subscribe to receive automatic button press events:
🏠 Home Automation Integration
The Haptique RS90 works seamlessly with popular automation platforms:
- Home Assistant: Create automations based on time, sensors, or device states. Use MQTT auto-discovery for easy setup.
- Node-RED: Build complex flows combining MQTT messages with other smart home devices.
- OpenHAB: Control entertainment systems alongside other smart home devices through a unified interface.
- IFTTT/Webhooks: Create conditional triggers that bridge cloud services with your local automation.
- Custom Scripts: Use Python (paho-mqtt), JavaScript (MQTT.js), or any MQTT client library for custom solutions.
Best Practices
✓ Implementation Tips
- Subscribe Once: Thanks to retained messages, you only need to subscribe when your client starts. The broker delivers current values immediately.
- Monitor Status: Always subscribe to the status topic to detect connection issues.
- Use Wildcards: Subscribe to
Haptique/+/statusto monitor all remotes, orHaptique/{RemoteID}/#for all topics from one remote. - QoS Levels: Use QoS 1 for control commands to ensure delivery. QoS 0 is fine for monitoring.
- Keep Topic Names: Device and macro names are case-sensitive. Use exact names as shown in device/macro lists.
Troubleshooting
? No Retained Messages Received
- Verify your MQTT broker supports retained messages (most do by default).
- Check that the remote has successfully connected (monitor status topic).
- Ensure your client is subscribed before the remote publishes (though retained messages should still arrive).
- Use an MQTT client like MQTT Explorer to verify messages are on the broker.
? Commands Not Working
- Verify exact topic structure with correct RemoteID, device name, and macro name.
- Check payload format (lowercase "on"/"off" for macros, exact command names for devices).
- Ensure the remote status shows "online".
- Confirm device/macro names match exactly (case-sensitive).
- Use MQTT Explorer to monitor topic activity and verify message delivery.
? Intermittent Connection
- Check Wi-Fi signal strength at the remote's location.
- Verify broker configuration allows persistent connections.
- Increase broker keepalive timeout settings.
- Review broker logs for disconnection reasons.
- Ensure broker has sufficient resources (memory, CPU).
Visit https://support.haptique.io for integration examples, automation templates, Home Assistant blueprints, and technical support.
