Digital Loggers


 


Using MQTT with your power switch.

 

 

Compatible Devices

This page applies to our \WiFi power control products like the Ethernet Power Controllerr, the DIN Relay IV, the high power DC Power Switch, and the Web Power Switch Pro.   These products also contain a Lua scripting language.

MQTT API

MQTT is an event-oriented protocol with a centralized publish/subscribe model, which makes it a bit awkward to use for controlling devices; however, an implementation is included due to its popularity.

MQTT client settings

General MQTT settings

EPCR5 can function as an MQTT client, so you need to have a configured MQTT broker which it could connect to; then, other MQTT clients connected to the same broker could communicate with it (multi-broker configurations are also possible but out of scope of this document). SSL and username/password authentication are supported (leave empty to disable). The default port is 8883 when SSL is enabled, and 1883 otherwise.

Setting and reporting outlet state are performed by means of MQTT messages. MQTT messages carry topic markers to identify their type. The topics are arranged in a '/'-separated hierarchy.

The 'Topic root' setting allows to prepend a common string to topics related to all outlets, e.g. to group messages related to the same controller. It is advisable that you set a different topic root for every controller that you connect to the same MQTT broker; otherwise, you'll get collisions unless you set different topic subtrees for their outlets.

Last Will and Testament functionality is included which allows the broker to notify you if the EPCR5 unexpectedly goes offline. Note that the topic of the message is not prefixed by the topic root.

MQTT outlet bindings

MQTT outlet bindings

Every outlet can be mapped to an MQTT topic subtree, which will be prefixed by the topic root and '/'; the outlet will report its state with a message with that topic if 'Allow read' is checked and honor requests to change its state if it receives a message with that topic suffixed by '/set' and 'Allow write' is checked. The quality of service determines the mode of delivery to request from the broker for messages on reporting outlet state; not all brokers may support all delivery modes; the default should be sufficient for most purposes.

Note that there is no explicit way to request the states of outlets. MQTT brokers are expected to keep track of the most recent payload of the topics.

MQTT payload formats

MQTT payload format is not defined by a standard, so we explicitly define it here. Everything that can be controlled via MQTT in EPCR5 is an outlet state, which can be ON or OFF. We encode ON as '1' (the single ASCII character '1') and OFF as '0'. For compatibility, in addition to decoding '1' as ON and '0' as OFF, we accept '\0' (the ASCII NUL character) and the strings 'off' and 'false' as OFF, and '\1' (the ASCII SOH character) and the strings 'on' and 'true' as ON. Additionally, the empty string '' is used to indicate topic erasure (on topic changes or read access revocation).

MQTT sample commands

These examples assume you have an MQTT broker at 192.168.0.5, it doesn't require authentication and you have the EPCR5 set up like shown on screenshots above.

You'll need the mosquitto MQTT client to run these samples; analogous commands should be available for other clients.

If you run the command:

mosquitto_sub -h 192.168.0.5 -C 1 -t pcr12345/outlets/0

it'll print the current state of the first outlet as known to the broker (as '0' or '1') and exit. The '-C 1' flags disable waiting for more state changes; if you run the command with them removed:

mosquitto_sub -h 192.168.0.5 -t pcr12345/outlets/0

you'll see the current state, but the program will wait for more state messages and print the states as they arrive; if you flip the outlet, you'll see output like this:

0
1
0
1

etc.

To change the state of the first outlet, use the mosquitto_pub command, e.g. to switch it on use:

mosquitto_pub -h 192.168.0.5 -t pcr12345/outlets/0/set -m 1

and to switch it off use:

mosquitto_pub -h 192.168.0.5 -t pcr12345/outlets/0/set -m 0

As mentioned above, alternate value forms, e.g.

mosquitto_pub -h 192.168.0.5 -t pcr12345/outlets/0/set -m true
mosquitto_pub -h 192.168.0.5 -t pcr12345/outlets/0/set -m on

will also work as expected.

 


  • Have a smart script or unique way to use your switch?  We'll acknowledge your contribution. engineering@digital-loggers.com