The Keep Connect device interacts with an MQTT broker for remote communication and control. This guide explains how to send and receive messages with the device using MQTT, how to control the device, and how to read status updates.
In the enable MQTT settings screen, you will see several fields that must be configured to establish MQTT communication:
- MQTT Host URL: This is the URL of the MQTT broker or server that your Keep Connect device will connect to.
- MQTT Client Name: A unique identifier for your Keep Connect device, used to distinguish it in the MQTT network.
- MQTT Username: The username required to authenticate your connection to the MQTT broker, if applicable.
- MQTT Password: The corresponding password used to securely connect to the MQTT broker.
- MQTT Port: This is typically set to the default MQTT port (1883), but can be adjusted based on the requirements of your broker or server configuration.
Once these settings are properly configured, your device will be connected to the MQTT broker, allowing for various actions such as force-sending heartbeat signals, rebooting the device, and more.
MQTT Integration Guide for Keep Connect Device #
Topics Structure #
- Publish topic: Users publish commands to control the device to the topic:
- MAC_WITHOUT_COLONS/in
Example: For a device with MAC address AA:BB:CC:DD:EE:FF, publish messages to AABBCCDDEEFF/in.
- Subscribe topic: Users subscribe to this topic to receive status updates from the device:
- MAC_WITHOUT_COLONS/out
Example: For a device with MAC address AA:BB:CC:DD:EE:FF, subscribe to AABBCCDDEEFF/out.
Message Structure #
- Incoming Messages (Commands): The device expects predefined commands in the message payload published to the MAC_WITHOUT_COLONS/in topic. Supported commands include:
- “on”: Turn the relay (and connected device) on.
- “off”: Turn the relay off.
- “reboot”: Reboot the Keep Connect device
- “cycle”: Power cycle the Router/Network device.
- “heartbeat”: Force the device to check for new settings.
- “status”: Request current status information.
Example of Publishing Commands #
mosquitto_pub -h <broker_address> -t “AABBCCDDEEFF/in” -m “on”
Status Response (JSON Format) #
The device publishes its status in JSON format to the MAC_WITHOUT_COLONS/out topic. After publishing a status request command (“status”), or after any state change (e.g., turning the device on/off), the status will be published.
Status Response Example:
{
“mac”: “AA:BB:CC:DD:EE:FF”,
“state”: “1”,
“power”: “5.4”,
“voltage”: “120.0”,
“current”: “0.2”,
“uptime”: “1234567”
}
Field Descriptions:
- mac: The MAC address of the device.
- state: The relay state. “1” for ON and “0” for OFF.
- power: Power consumption in watts.
- voltage: Voltage in volts.
- current: Current in amperes.
- uptime: The uptime of the device in seconds.
Sample Output for "ON" and "OFF" States Using a WebSocket Client #
OFF State
ON State
"reboot": Perform a Keep Device Restart #
The “reboot” topic will command the device to reboot itself without power cycling the router or other connected devices.
This function can be particularly useful in refreshing the Keep Connect device, especially if there’s a need to restart from the top of a complex, customized monitoring pipeline. Additionally, it can help reinitialize the device’s connection to the Wi-Fi network for isolated or specific reasons.
It’s important to note that Keep Connect typically handles reconnections automatically and operates continuously to ensure your network stays online without requiring manual intervention. However, this reboot command is available for customers who may have unique needs or wish to manually refresh the device’s internal code for any reason.
"cycle": Perform a Power Cycle #
The “cycle” topic commands Keep Connect to perform a power cycle on the connected router or any device plugged into it.
This command mirrors the functionality of the “Trigger Power Cycle” feature in the Keep Connect App. When you publish the “cycle” topic via your MQTT broker, it sends an instruction to the Keep Connect Cloud Server. Once Keep Connect sends its regular heartbeat to the server, it will download the power cycle instruction and execute it.
Please note, this feature relies on your network being online. If your network is experiencing an internet or power outage, Keep Connect will automatically follow its pre-programmed code loop to restore the network once the issue is resolved, without the need for manual intervention.
"heartbeat": Device Sends Immediate heartbeat #
The “heartbeat” topic instructs Keep Connect to immediately send a heartbeat signal to the cloud server. This forces the device to check for any new settings or instructions, such as updates to its configuration or queued commands (e.g., power cycles or reboots).
Typically, Keep Connect sends heartbeats at fixed intervals of every 5 minutes as part of its normal operation, but the “heartbeat” topic can be used if you need the device to quickly pull any new settings or updates from the server, without waiting for the next scheduled heartbeat.
"status": Request Current Status Information #
The “status” topic is used to request the current status information from Keep Connect. Once this topic is published, the device will send its current status every 5 seconds for up to 1 minute. After the 1-minute timeout, the status updates will automatically stop. This is helpful for getting real-time information about the device’s operational state, such as network connection or monitoring status, without waiting for the regular heartbeat intervals.
