MQTT Client API

MQTT Client API provides sequential API built on top of MQTT Client.

MQTT API application example code
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
/*
 * MQTT client API example with ESP device.
 *
 * Once device is connected to network,
 * it will try to connect to mosquitto test server and start the MQTT.
 *
 * If successfully connected, it will publish data to "esp_mqtt_topic" topic every x seconds.
 *
 * To check if data are sent, you can use mqtt-spy PC software to inspect
 * test.mosquitto.org server and subscribe to publishing topic
 */

#include "esp/apps/esp_mqtt_client_api.h"
#include "mqtt_client_api.h"
#include "esp/esp_mem.h"

/**
 * \brief           Connection information for MQTT CONNECT packet
 */
static const esp_mqtt_client_info_t
mqtt_client_info = {
    .keep_alive = 10,

    /* Server login data */
    .user = "8a215f70-a644-11e8-ac49-e932ed599553",
    .pass = "26aa943f702e5e780f015cd048a91e8fb54cca28",

    /* Device identifier address */
    .id = "869f5a20-af9c-11e9-b01f-db5cf74e7fb7",
};

/**
 * \brief           Memory for temporary topic
 */
static char
mqtt_topic_str[256];

/**
 * \brief           Generate random number and write it to string
 * \param[out]      str: Output string with new number
 */
void
generate_random(char* str) {
    static uint32_t random_beg = 0x8916;
    random_beg = random_beg * 0x00123455 + 0x85654321;
    sprintf(str, "%u", (unsigned)((random_beg >> 8) & 0xFFFF));
}

/**
 * \brief           MQTT client API thread
 */
void
mqtt_client_api_thread(void const* arg) {
    esp_mqtt_client_api_p client;
    esp_mqtt_conn_status_t conn_status;
    esp_mqtt_client_api_buf_p buf;
    espr_t res;
    char random_str[10];

    /* Create new MQTT API */
    client = esp_mqtt_client_api_new(256, 128);
    if (client == NULL) {
        goto terminate;
    }

    while (1) {
        /* Make a connection */
        printf("Joining MQTT server\r\n");

        /* Try to join */
        conn_status = esp_mqtt_client_api_connect(client, "mqtt.mydevices.com", 1883, &mqtt_client_info);
        if (conn_status == ESP_MQTT_CONN_STATUS_ACCEPTED) {
            printf("Connected and accepted!\r\n");
            printf("Client is ready to subscribe and publish to new messages\r\n");
        } else {
            printf("Connect API response: %d\r\n", (int)conn_status);
            esp_delay(5000);
            continue;
        }

        /* Subscribe to topics */
        sprintf(mqtt_topic_str, "v1/%s/things/%s/cmd/#", mqtt_client_info.user, mqtt_client_info.id);
        if (esp_mqtt_client_api_subscribe(client, mqtt_topic_str, ESP_MQTT_QOS_AT_LEAST_ONCE) == espOK) {
            printf("Subscribed to topic\r\n");
        } else {
            printf("Problem subscribing to topic!\r\n");
        }

        while (1) {
            /* Receive MQTT packet with 1000ms timeout */
            res = esp_mqtt_client_api_receive(client, &buf, 5000);
            if (res == espOK) {
                if (buf != NULL) {
                    printf("Publish received!\r\n");
                    printf("Topic: %s, payload: %s\r\n", buf->topic, buf->payload);
                    esp_mqtt_client_api_buf_free(buf);
                    buf = NULL;
                }
            } else if (res == espCLOSED) {
                printf("MQTT connection closed!\r\n");
                break;
            } else if (res == espTIMEOUT) {
                printf("Timeout on MQTT receive function. Manually publishing.\r\n");

                /* Publish data on channel 1 */
                generate_random(random_str);
                sprintf(mqtt_topic_str, "v1/%s/things/%s/data/1", mqtt_client_info.user, mqtt_client_info.id);
                esp_mqtt_client_api_publish(client, mqtt_topic_str, random_str, strlen(random_str), ESP_MQTT_QOS_AT_LEAST_ONCE, 0);
            }
        }
        //goto terminate;
    }

terminate: 
    esp_mqtt_client_api_delete(client);
    printf("MQTT client thread terminate\r\n");
    esp_sys_thread_terminate(NULL);
}
group ESP_APP_MQTT_CLIENT_API

Sequential, single thread MQTT client API.

Typedefs

typedef struct esp_mqtt_client_api_buf *esp_mqtt_client_api_buf_p

Pointer to esp_mqtt_client_api_buf_t structure.

Functions

esp_mqtt_client_api_p esp_mqtt_client_api_new(size_t tx_buff_len, size_t rx_buff_len)

Create new MQTT client API.

Return

Client handle on success, NULL otherwise

Parameters
  • [in] tx_buff_len: Maximal TX buffer for maximal packet length

  • [in] rx_buff_len: Maximal RX buffer

void esp_mqtt_client_api_delete(esp_mqtt_client_api_p client)

Delete client from memory.

Parameters
  • [in] client: MQTT API client handle

esp_mqtt_conn_status_t esp_mqtt_client_api_connect(esp_mqtt_client_api_p client, const char *host, esp_port_t port, const esp_mqtt_client_info_t *info)

Connect to MQTT broker.

Return

ESP_MQTT_CONN_STATUS_ACCEPTED on success, member of esp_mqtt_conn_status_t otherwise

Parameters
  • [in] client: MQTT API client handle

  • [in] host: TCP host

  • [in] port: TCP port

  • [in] info: MQTT client info

espr_t esp_mqtt_client_api_close(esp_mqtt_client_api_p client)

Close MQTT connection.

Return

espOK on success, member of espr_t otherwise

Parameters
  • [in] client: MQTT API client handle

espr_t esp_mqtt_client_api_subscribe(esp_mqtt_client_api_p client, const char *topic, esp_mqtt_qos_t qos)

Subscribe to topic.

Return

espOK on success, member of espr_t otherwise

Parameters
  • [in] client: MQTT API client handle

  • [in] topic: Topic to subscribe on

  • [in] qos: Quality of service. This parameter can be a value of esp_mqtt_qos_t

espr_t esp_mqtt_client_api_unsubscribe(esp_mqtt_client_api_p client, const char *topic)

Unsubscribe from topic.

Return

espOK on success, member of espr_t otherwise

Parameters
  • [in] client: MQTT API client handle

  • [in] topic: Topic to unsubscribe from

espr_t esp_mqtt_client_api_publish(esp_mqtt_client_api_p client, const char *topic, const void *data, size_t btw, esp_mqtt_qos_t qos, uint8_t retain)

Publish new packet to MQTT network.

Return

espOK on success, member of espr_t otherwise

Parameters
  • [in] client: MQTT API client handle

  • [in] topic: Topic to publish on

  • [in] data: Data to send

  • [in] btw: Number of bytes to send for data parameter

  • [in] qos: Quality of service. This parameter can be a value of esp_mqtt_qos_t

  • [in] retain: Set to 1 for retain flag, 0 otherwise

uint8_t esp_mqtt_client_api_is_connected(esp_mqtt_client_api_p client)

Check if client MQTT connection is active.

Return

1 on success, 0 otherwise

Parameters
  • [in] client: MQTT API client handle

espr_t esp_mqtt_client_api_receive(esp_mqtt_client_api_p client, esp_mqtt_client_api_buf_p *p, uint32_t timeout)

Receive next packet in specific timeout time.

Note

This function can be called from separate thread than the rest of API function, which allows you to handle receive data separated with custom timeout

Return

espOK on success, espCLOSED if MQTT is closed, espTIMEOUT on timeout

Parameters
  • [in] client: MQTT API client handle

  • [in] p: Pointer to output buffer

  • [in] timeout: Maximal time to wait before function returns timeout

void esp_mqtt_client_api_buf_free(esp_mqtt_client_api_buf_p p)

Free buffer memory after usage.

Parameters
  • [in] p: Buffer to free

struct esp_mqtt_client_api_buf_t
#include <esp_mqtt_client_api.h>

MQTT API RX buffer.

Public Members

char *topic

Topic data

size_t topic_len

Topic length

uint8_t *payload

Payload data

size_t payload_len

Payload length

esp_mqtt_qos_t qos

Quality of service