Send commands through the broker.
DeviceJockey → Broker → Subscriber
A command publishes a text or JSON payload to its configured topic.
- Topic
- Identifies where the message is published
- Used by
- MQTT Value and MQTT Range commands
DeviceJockey Interfaces
MQTT Interface
Publish control values and use subscribed messages as feedback for your DeviceJockey panel.
Broker connection
One MQTT client publishes and subscribes.
DeviceJockey connects to an MQTT broker as a client. Commands publish messages to topics. Events subscribe to topics and use matching payloads to update items or execute commands through Remote Options.
Receive state from other clients.
Publisher → Broker → DeviceJockey
An event subscribes to its topic and evaluates each matching payload.
- Topic
- Identifies the messages the event receives
- Used by
- MQTT Value, Range, Label, Enable, and Disable events
The broker routes the messages.
DeviceJockey and the controlled system do not connect directly. Both connect to the same MQTT broker.
Setup
Connect DeviceJockey to an MQTT broker.
1
Prepare the broker
Make sure the broker is reachable and collect its address, port, and required credentials.
2
Add an MQTT Client
Add the interface to the scene that contains your MQTT controls.
3
Configure the connection
Enter the host, port, client ID, authentication, and TLS settings required by the broker.
4
Add commands and events
Configure topics and payloads for the items that should publish or receive MQTT messages.
Connection settings
Identify the broker and this client.
Enter the IP address or host name of the MQTT broker.
Use the broker port. Common defaults are 1883 without TLS and 8883 with TLS.
Give this connection an ID that is unique among clients connected to the broker.
Enable authentication and enter the username and password when required by the broker.
Set the interval used to maintain the client connection and detect a lost broker connection.
Choose whether the broker should start the connection without a previously stored MQTT session.
Commands
Publish text or JSON payloads.
Each command defines a topic, payload, QoS, and Retain setting. Swaps can be used in the topic and payload, allowing the same item to address different destinations or values in different configurations.
Publish a configured text or JSON payload when the command is executed.
Map the item position between configured minimum and maximum values and insert the result into text or JSON.
Select the MQTT delivery level required for the published message.
Ask the broker to store the message as the latest retained value for new subscribers.
Retain state messages, not every action.
A retained brightness or operating state can initialize a new subscriber. A momentary trigger usually should not be retained.
Events and feedback
Subscribe to topics and evaluate their payloads.
DeviceJockey subscribes to the topic configured in an active MQTT event. Incoming text or JSON is compared with the event definition. A dynamic value can be extracted and applied to the item.
React when the topic and payload match the configured message.
Extract a number from text or JSON and map it to the range of the item.
Extract a selected value and display it as the item label.
Allow or protect supported item interaction when the configured message matches.
The available event variants depend on the selected item and event type.
Reliable panel state
Separate commands from feedback.
A slider can publish its requested value to a command topic. A corresponding event can subscribe to a state topic and display the value confirmed by the controlled system. This also reflects changes made by another MQTT client.
Events can execute commands.
Use Remote Options when an incoming MQTT message should start one or more commands.
Learn about Remote Options →Last Will
Let the broker report an unexpected disconnect.
An MQTT Last Will message is registered with the broker during connection. If DeviceJockey loses the connection without disconnecting normally, the broker publishes that message on the configured topic.
Define where the availability message is published and which payload it contains.
Choose the delivery level the broker should use for the Last Will message.
Retain the Last Will when new subscribers should immediately see the disconnected state.
Secure connections
Match the TLS requirements of the broker.
DeviceJockey supports TLS 1.2 and TLS 1.3. The appropriate trust mode depends on the certificate setup of your broker. Client identity import is available for brokers that require mutual TLS authentication.
Validate the broker with certificates trusted by iOS.
Import the CA certificate used to sign the broker certificate.
Trust a specific broker server certificate.
Trust the public key extracted from an imported certificate.
Import a password-protected PKCS#12 identity when the broker requires mutual TLS.
Certificate mode and file must match.
The custom CA mode requires a certificate authority certificate. Certificate pinning requires the broker server certificate.
Topic structure
Use names that remain understandable.
studio/lights/key/command
studio/lights/key/state
studio/audio/master/stateA consistent distinction between command and state topics makes bidirectional panels easier to understand and prevents feedback messages from being mistaken for new commands.
Troubleshooting
If the MQTT client does not work as expected.
Check host and port.
Confirm that the broker is reachable at the configured address and that the TLS setting matches the selected port.
Verify the Client ID.
Use a unique ID. Some brokers disconnect an existing client when another client connects with the same ID.
Check authentication.
Compare the username, password, and broker access permissions.
Compare the topic.
Topic names are case-sensitive. Check every level and separator.
Inspect the payload.
Confirm whether the publisher sends text or JSON and whether its structure matches the event.
Review TLS.
Check the minimum TLS version, trust mode, certificate, and optional client identity.