MQTT

Using MQTT on Inkplate 6 MOTION allows sending and receiving messages over the network using the lightweight MQTT protocol, commonly used for IoT applications. The following sections explain how to connect to an MQTT broker, subscribe to topics, and send or receive messages.

Connecting and subscribing to a topic

To establish an MQTT connection, first initialize the MQTT library with mqtt.begin(), set the MQTT server using mqtt.setServer(), and attempt to connect with mqtt.connect(). Once connected, subscribe to a topic using mqtt.subscribe().

⚠️

Make sure the Inkplate 6 MOTION is connected to a Wi-Fi network before attempting to use MQTT.

// Initialize the MQTT library and set the internal buffer for RX messages
mqtt.begin(48);

// Set the MQTT broker information
mqtt.setServer("test.mosquitto.org", 1883);

// Attempt to connect to the MQTT broker
inkplate.print("Connecting to the MQTT broker...");
inkplate.partialUpdate(true);
if (!mqtt.connect())
{
    inkplate.println("Connect failed!");
    inkplate.partialUpdate(false);

    // Stop execution if the connection fails
    while (1);
}
inkplate.println("Connected!");
inkplate.partialUpdate(true);

// Subscribe to a topic
inkplate.print("Subscribing to ");
inkplate.print("solderedTest/solderedDasduino");
inkplate.print(" topic...");
inkplate.partialUpdate(true);
if (!mqtt.subscribe((char *)"solderedTest/solderedDasduino"))
{
    inkplate.print("failed!");
    inkplate.partialUpdate(false);

    // Stop execution if subscription fails
    while (1);
}
inkplate.println("Subscribed!\r\n");
inkplate.partialUpdate(true);

mqtt.begin()

Initializes the MQTT library and allocates memory for incoming messages.

Returns: Returns true if memory allocation was successful, false otherwise.

Function parameters:

Type	Name	Description
`uint16_t`	`bufferSize`	Size of the allocated buffer (in bytes) for storing incoming MQTT messages.

mqtt.begin()

Initializes the MQTT library using a user-defined buffer for incoming messages.

Returns: Returns true if the user-defined buffer was accepted, false otherwise.

Function parameters:

Type	Name	Description
`uint8_t*`	`buffer`	Pointer to a user-defined buffer for storing incoming messages.
`uint16_t`	`bufferSize`	Size of the user-defined buffer (in bytes).

mqtt.setServer()

Configures the MQTT broker's hostname/IP and port. This does not immediately establish a connection.

Returns: Returns true if the server details were set successfully, false otherwise.

Function parameters:

Type	Name	Description
`char*`	`server`	MQTT broker's domain name or IP address.
`uint16_t`	`port`	MQTT broker's port (typically 1883 for unencrypted communication).

mqtt.connect()

Attempts to establish a connection to the MQTT broker with optional authentication.

Returns: Returns true if the connection was successful, false otherwise.

Function parameters:

Type	Name	Description
`char*`	`clientId`	Optional MQTT Client ID. Use NULL if not required.
`char*`	`username`	Optional username for authentication. Use NULL if not required.
`char*`	`password`	Optional password for authentication. Use NULL if not required.

mqtt.subscribe()

Subscribes to a specified MQTT topic to receive messages.

Returns: Returns true if subscription was successful, false otherwise.

Function parameters:

Type	Name	Description
`const char*`	`topic`	The name of the topic to subscribe to.

mqtt.unsubscribe()

Unsubscribes from a specified MQTT topic to stop receiving messages.

Returns: Returns true if unsubscription was successful, false otherwise.

Function parameters:

Type	Name	Description
`char*`	`topic`	The name of the topic to unsubscribe from.

Sending and receiving messages

Once connected and subscribed, messages can be published using mqtt.publish(), and received by checking mqtt.available().

// Check if a new message is available on the subscribed topic
int mqttData = mqtt.available();
if (mqttData)
{
    inkplate.print("Topic: ");
    inkplate.print(mqtt.topic());
    inkplate.print(", Payload: ");
    
    // Read and print the received message
    for (int i = 0; i < mqttData; i++)
    {
        inkplate.print(mqtt.read());
    }
    inkplate.println();
    inkplate.partialUpdate(false);
}

// Publish a message when the WAKE button is pressed
if (checkButton(PC13, &publishBtnOldState, LOW))
{
    char message[40];
    sprintf(message, "inkplate_%lu", millis());

    inkplate.print("Publish \"");
    inkplate.print(message);
    inkplate.print("\" ");
    
    if (mqtt.publish((char *)mqttTopicTx, message, 0, true))
    {
        inkplate.println("ok");
    }
    else
    {
        inkplate.println("failed");
    }
    inkplate.partialUpdate(false);
}

mqtt.available()

Checks if a new MQTT message is available on the subscribed topic.

Returns: Returns the length of the available message in bytes, or 0 if no message is available.

mqtt.publish()

Publishes a message to a specified MQTT topic.

Returns: Returns true if the message was published successfully, false otherwise.

Function parameters:

Type	Name	Description
`char*`	`topic`	The topic to publish the message to.
`char*`	`payload`	The message content to be sent.
`uint16_t`	`length`	Length of the message. If the message is a null-terminated string, set this to 0.
`bool`	`retain`	If true, the broker retains the message for future subscribers.

mqtt.read()

Reads the next byte from the received MQTT message.

Returns: Returns the next byte of the message as an integer, or 0 if no data is available.

mqtt.read()

Reads a specified number of bytes from an incoming MQTT message into a user-defined buffer.

Returns: Returns the number of bytes actually stored in the buffer.

Function parameters:

Type	Name	Description
`uint8_t*`	`buffer`	Pointer to the buffer where the received message will be stored.
`uint16_t`	`length`	Maximum number of bytes to store in the buffer.

mqtt.disconnect()

Disconnects from the MQTT broker and cleans up resources.

Returns: Returns true if disconnection was successful, false otherwise.

mqtt.connected()

Checks if the Inkplate is currently connected to an MQTT broker.

Returns: Returns true if connected, false otherwise.

mqtt.reconnect()

Enables or disables automatic reconnection in case of a dropped connection.

Returns:

Function parameters:

Type	Name	Description
`uint8_t`	`mode`	Set to 1 to enable automatic reconnect, 0 to disable it.

mqtt.topic()

Retrieves the topic of the most recently received MQTT message.

Returns: Returns a pointer to the string containing the topic name.

mqtt.setQoS()

Sets the Quality of Service (QoS) level for MQTT message delivery.

Returns:

Function parameters:

Type	Name	Description
`int`	`qos`	QoS level: 0 (at most once), 1 (at least once), or 2 (exactly once).

mqtt.loop()

Checks for new incoming MQTT messages and processes them. This function should be called frequently.

Returns:

Full example

For a complete MQTT implementation, including connecting, subscribing, publishing, and receiving messages, see the full example:

Inkplate_6_Motion_WiFi_MQTT.ino

Full example on how to init, subscribe, unsubscribe, transmit and recieve data via MQTT

Connecting and subscribing to a topic​

mqtt.begin()

mqtt.begin()

mqtt.setServer()

mqtt.connect()

mqtt.subscribe()

mqtt.unsubscribe()

Sending and receiving messages​

mqtt.available()

mqtt.publish()

mqtt.read()

mqtt.read()

mqtt.disconnect()

mqtt.connected()

mqtt.reconnect()

mqtt.topic()

mqtt.setQoS()

mqtt.loop()

Full example​

Inkplate_6_Motion_WiFi_MQTT.ino

Connecting and subscribing to a topic

Sending and receiving messages

Full example