DeviceJockey Interfaces

MQTT Client 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 an MQTT 3.1.1 client over TCP. Commands publish messages to topics. Events subscribe to topics and react to configured payloads by updating Items or executing commands through Remote Options.

Publish

Send commands through the broker.

DeviceJockey → Broker → Subscriber

A Command publishes a UTF-8 text or JSON payload to its configured topic.

Topic: Identifies where the message is published
Used by: MQTT Value and MQTT Range commands

Receive state from other clients.

Publisher → Broker → DeviceJockey

An Event subscribes to its topic filter and evaluates each received 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.

Prepare the broker

Make sure the broker is reachable and collect its address, port, and required credentials.

Add an MQTT Client to the Scene

Enter the broker host and port, a unique Client ID, and any authentication or TLS settings required by the broker.

Configure the Items

Add MQTT Commands to Items that should publish messages. Add MQTT Events to Items that should react to subscribed topics and payloads.

Connection settings

Identify the broker and this client.

Host

Enter the IP address or host name of the MQTT broker.

Port

Use the broker port. Common defaults are 1883 without TLS and 8883 with TLS.

Client ID

Give this connection an ID that is unique among clients connected to the broker.

Authentication

Enable authentication and enter the username and password when required by the broker.

Keep Alive

Set the maximum idle interval. DeviceJockey sends PING requests so both sides can detect a lost connection.

Clean Session

Enable it for a fresh session. Disable it when the broker should retain subscriptions and eligible missed messages for this Client ID.

Last Will

Let the broker publish a configured message if DeviceJockey disconnects unexpectedly. Configure the Last Will →

Publish · Commands →

Send text or JSON payloads.

Each command defines a topic, payload, QoS, and Retain setting. To use a Swap in a topic, Text payload, or JSON payload, insert it as \(swapname). DeviceJockey replaces the expression with the current Swap value before publishing the message.Learn about Swaps →

MQTT Value

Publish a configured text or JSON payload when the Command is performed.

MQTT Range

Map the Item's value between a configured minimum and maximum, then insert the result into text or the selected JSON attribute.

For text payloads: Use ${value} as a placeholder. A Slider at 50% can therefore turn level=${value} into level=50.

For JSON payloads: Enter the name of the value-holding attribute, such as level, in Dynamic Value Attribute. DeviceJockey replaces that attribute's value.

← Subscribe · Events

Let an incoming MQTT message control an Item.

An MQTT Event waits for a message on its configured topic. When a message arrives, DeviceJockey checks the payload. If the configured conditions are met, the Event reacts and controls the selected Item.

A message arrives

The broker delivers a message on a topic to which the Event subscribes.

The Event checks it

The topic must match first. DeviceJockey then compares the configured text or JSON with the incoming payload. For JSON, only the configured attributes must match; additional attributes are allowed so unrelated data does not prevent the Event from reacting.

The Item reacts

If the check succeeds, the Event performs its action on the Item or applies the received value.

MQTT Value

Use this when one particular message should make the Event react.

Text: The Event reacts only when the complete incoming text matches. Spaces and line breaks at the beginning and end are ignored.

JSON: The Event reacts when the configured attributes exist in the incoming JSON and their values match. Additional attributes are ignored, keeping the Event reliable when the publisher includes unrelated data.

MQTT Range

Use this when the message contains a changing number that should control a Slider or another ranged Item.

Text: The fixed text around ${value} must match. DeviceJockey reads the content at the placeholder position as the value.

JSON: The configured attributes must match, except for Dynamic Value Attribute. DeviceJockey reads that attribute as the value. Additional attributes are ignored, so unrelated data does not prevent the Event from reacting.

Mode	Configured Event	Incoming Payload	Result
Text	`power=on`	`power=on`	Item reacts
Text	`power=on`	`Power=on`	No reaction
JSON	`{"power":true}`	`{"power":true,"device":"slider-1"}`	Item reacts
JSON	`{"power":true}`	`{"power":false,"device":"slider-1"}`	No reaction

Mode	Configured Event	Incoming Payload	Result
Text	`level=${value}`	`level=75`	Slider receives 75
Text	`level=${value}`	`brightness=75`	No reaction
JSON	`{"power":true,"level":0}` Dynamic: `level`	`{"power":true,"level":75,"device":"slider-1"}`	Slider receives 75
JSON	`{"power":true,"level":0}` Dynamic: `level`	`{"power":false,"level":75,"device":"slider-1"}`	No reaction

MQTT Label

Extract the configured text placeholder or JSON attribute and display its value in the Item's label.

MQTT Enable / Disable

Enable or protect supported Item interaction when the topic and payload match.

Message editor

Compose MQTT payloads as text or JSON.

The message editor is used for MQTT Commands and Events as well as the Last Will message. Choose the entry type before entering the payload so DeviceJockey can offer the appropriate editing and matching functions.

Text

Send fixed text or insert an Item value.

Use MQTT Value for a message that is always the same. Use MQTT Range when part of the message should come from the Item, for example the current position of a Slider.

power=on

The fixed message above is sent exactly as entered. The step-by-step example below explains how to include a Slider value.

JSON

Send a fixed object or change one value.

MQTT Value sends the entered JSON unchanged. MQTT Range can change the value of one selected attribute before sending it.

{
  "level": 0,
  "power": true
}

To send the Slider value, enter level in Dynamic Value Attribute. If the Slider value is 50, DeviceJockey changes "level": 0 to "level": 50.

Add MQTT Range.

Add the Command to a Slider or another Item that supplies a range value.

Select Text.

Choose Text in the message editor.

Write the message around the value.

Enter the fixed part of the payload, for example level=, and place the cursor directly after it.

Insert the placeholder.

Tap Insert Placeholder above the Dynamic Value Attribute field. DeviceJockey inserts ${value} at the cursor and also enters it in the field.

Check both entries.

The message editor now contains level=${value}. Dynamic Value Attribute contains ${value}.

Set Minimum and Maximum.

These values define the number produced across the Item's range. For example, use 0 at the bottom of the Slider and 100 at the top.

Move the Slider.

If the Slider is at 50%, DeviceJockey calculates the value 50.

Publish the completed payload.

DeviceJockey replaces ${value} with 50 and publishes level=50.

Insert a Slider value into text

Insert Placeholder adds the value marker to the text and to Dynamic Value Attribute.

Add MQTT Range.

Add the Command to the Slider or another Item that supplies a range value.

Select JSON.

Choose JSON in the message editor.

Enter a valid JSON object.

For example, enter {"power":true,"level":0}. The value 0 makes the example valid JSON; it is not a placeholder.

Choose the value-holding attribute.

Enter level in Dynamic Value Attribute. You can also select level in the editor and choose Attribute from the edit menu.

Set Minimum and Maximum.

For example, use 0 and 100 to map the full Slider range.

Move the Slider.

If the Slider is at 50%, DeviceJockey calculates the value 50.

Publish the updated JSON.

DeviceJockey finds the level attribute, replaces its value, and publishes {"level":50,"power":true}. The other attributes keep their configured values.

Select a dynamic JSON attribute

The level attribute identifies the JSON value that DeviceJockey replaces with the current Slider value.

Use an unambiguous JSON attribute name.

DeviceJockey searches the object for the configured name. If the same attribute name occurs more than once, it may not identify the value you intended.

Editor controls

Tools for writing and reusing messages.

These controls belong to the message editor. They help you enter, check, reuse, and adjust payloads without changing what the MQTT message means.

Symbol bar

Insert JSON punctuation, operators, and the values true, false, and null without changing the keyboard.

Format and validate

In JSON mode, tap the brush to parse and format the object. A checkmark confirms valid JSON; an error explains where parsing failed.

Undo and text size

Undo recent edits and adjust the monospaced editor font. Smart quotes, autocorrection, and automatic capitalization are disabled.

Message history

Tap History to recall the next saved message. Press and hold it to open the list and select an earlier entry.

Copy JSON

Use Copy JSON and Paste JSON in the edit menu to transfer a complete JSON message between editors in DeviceJockey.

Delivery and retained state

Choose how the broker handles each message.

QoS 0 · At most once

Send without an MQTT acknowledgement. This has the lowest overhead but no MQTT-level delivery confirmation.

QoS 1 · At least once

Wait for an acknowledgement and retry when necessary. The receiver may see a duplicate.

QoS 2 · Exactly once

Use the full acknowledgement exchange for exactly-once delivery with the highest overhead.

Retain

Ask the broker to keep the published message as the current value for future 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.

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.

Topic and message

Define where the availability message is published and which payload it contains.

QoS

Choose the delivery level the broker should use for the Last Will message.

Retain

Retain the Last Will when new subscribers should immediately see the disconnected state.

Secure connections

Match the TLS requirements of the broker.

DeviceJockey can require a minimum of TLS 1.2 or TLS 1.3. The appropriate trust mode depends on the certificate setup of your broker. Client identity import is available for mutual TLS authentication.

System Trust

Validate the broker with certificates trusted by iOS.

Custom certificate authority

Add an imported CA certificate as a trust anchor for the broker connection.

Pinned certificate

Require the system-trusted certificate chain to contain the imported broker certificate.

Pinned public key

Require the system-trusted certificate chain to contain the imported public key.

Client identity

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 filters

Subscribe to one topic or a hierarchy.

Topics are case-sensitive and cannot be empty or contain spaces in DeviceJockey. MQTT Events can subscribe to an exact topic or use MQTT wildcards in their topic filter.

Exact topic

studio/lights/key/state receives only that topic.

+ · One level

studio/lights/+/state receives the state topic for any one light name at that level.

# · Remaining levels

studio/lights/# receives every topic below the lights hierarchy.

Separate command topics from confirmed state.

For example, publish requests to studio/lights/key/command and subscribe to studio/lights/key/state.

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 it contains the values that should make the Event react.

Review TLS.

Check the minimum TLS version, trust mode, certificate, and optional client identity.