Skip to main content

MQTT Setup

Here is a simple scenario to help you connect your device over MQTT.

Note that the setup process is related to the MQTT system component and the communication over MQTT is described in the MQTT RPC channel page.

Step 1: Check your current connection#

Firstly, check your current connection over MQTT with the following request:

export SHELLY=10.33.55.152 # IP of your device
curl -X POST -d '{"id":1, "src":"user_1", "method":"Mqtt.GetStatus"}' http://${SHELLY}/rpc

The response must contain the property connected. If its value is true, then you are already connected over MQTT. If the value is false, proceed with the next step.

Step 2: Check your MQTT connection settings#

Now, check your current MQTT configuration through the method:

curl -X POST -d '{"id":1, "src":"user_1", "method":"Mqtt.GetConfig"}' http://${SHELLY}/rpc

In the response you can see if your connection over MQTT is enabled, as well as find information about the MQTT server set for that device, custom prefixes and security settings. However, you need to check two things here: whether the connection is enabled and whether your server is set correctly. If the answer to any of these questions is no, proceed to the next step, where we will set a new MQTT configuration.

Step 3: Set a new MQTT configuration#

The next thing to do is updating the MQTT configuration. To enable the MQTT connection and set a server simultaneously, use the following method:

curl -X POST -d '{"id":1, "src":"user_1", "method":"Mqtt.SetConfig", "params":{"config":{"enable":true, "server":"broker.hivemq.com:1883"}}}' http://${SHELLY}/rpc

This will let you connect to the public MQTT server broker.hivemq.com on port 1883. In case you want to set connection to another server, just change the value of the property server in the request above.

Note that, if in step 2 you have found out that the connection is not enabled, but the server is set properly, you can omit the part with "server":"broker.hivemq.com:1883", and vice versa - if the connection is enabled, but the server set is incorrect, you can omit "enable":true.

The response will indicate that you have to reboot your device to apply the new configuration.

Step 4: Reboot you device#

Now, reboot your Shelly:

curl -X POST -d '{"id":1, "src":"user_1", "method":"Shelly.Reboot"}' http://${SHELLY}/rpc

Wait until your device boots again. After that the new settings must be activated.

Step 5: Check if MQTT connection is working#

Lastly, let's check the status of the MQTT connection once again (as in step 1):

export SHELLY=10.33.55.152 # IP of your device
curl -X POST -d '{"id":1, "src":"user_1", "method":"Mqtt.GetStatus"}' http://${SHELLY}/rpc

If you have followed these steps properly, then the property connected in the result must have value true.

Step 6: Receive notifications over MQTT#

Now, let's see the communication over MQTT in action. For this to happen, subscribe to the MQTT topic <shelly-id>/events/rpc, where you must replace shelly-id with your device's ID. For example, shellypro4pm-f008d1d8b8b8/events/rpc:

export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellypro4pm-f008d1d8b8b8" # The <shelly-id> of your device
mosquitto_sub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/events/rpc

If you have subscribed to the topic correctly, you will start receiving notifications here.

Step 7: Subscribe for messages on connecting and disconnecting over MQTT#

Open new tab in your terminal and subscribe to the topic <shelly-id>/online:

export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellypro4pm-f008d1d8b8b8" # The <shelly-id> of your device
mosquitto_sub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/online

You will be able to receive the messages:

  • true when the device connects to the broker (for example, after reboot)
  • LWT(Last Will Testament) false in case it is forced to disconnect abruptly

Now, plug off your device. You will receive a message false indicating the device was disconnected abruptly.

Plug on the device again. Again, on the <shelly-id>/online topic you will receive a message true to notify you for the reconnection. Then, open the window where you subscribed to the topic <shelly-id>/events/rpc. There you should be able to see some new notifications regarding the reconnection of your device.

Step 8: Send request and receive response#

Here you will send a request and you will name the source of this request mynewtopic. Then the response to this request will be published on topic mynewtopic/rpc. Note that, as stated on the RPC channel page, you can choose whatever <src> you wish for your request. So, the sources user_1 and mynewtopic that you can see throughout the docs are just examples and not something unchangeable.

Now, open a terminal window and this time subscribe to the topic mynewtopic/rpc to be able to receive the response after the request is sent:

export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellypro4pm-f008d1d8b8b8" # The <shelly-id> of your device
mosquitto_sub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t mynewtopic/rpc

Then, let's send the request. In a new terminal publish the following request on the topic <shelly-id>/rpc:

export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellypro4pm-f008d1d8b8b8" # The <shelly-id> of your device
mosquitto_pub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/rpc \
-m '{"id":123, "src":"mynewtopic", "method":"Shelly.GetStatus"}'

This request invokes the method Shelly.GetStatus and, as already explained, you set the source to be mynewtopic.

After you send this request, you can look at the terminal window in which you subscribed for the topic <shelly-id>/rpc. There you should be able to see the response to the Shelly.GetStatus method.