MQTT Client API

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

MQTT API application example code
  1/*
  2 * MQTT client API example with GSM device.
  3 *
  4 * Once device is connected to network,
  5 * it will try to connect to mosquitto test server and start the MQTT.
  6 *
  7 * If successfully connected, it will publish data to "lwgsm_mqtt_topic" topic every x seconds.
  8 *
  9 * To check if data are sent, you can use mqtt-spy PC software to inspect
 10 * test.mosquitto.org server and subscribe to publishing topic
 11 */
 12
 13#include "lwgsm/apps/lwgsm_mqtt_client_api.h"
 14#include "mqtt_client_api.h"
 15#include "lwgsm/lwgsm_mem.h"
 16#include "lwgsm/lwgsm_network_api.h"
 17
 18/**
 19 * \brief           Connection information for MQTT CONNECT packet
 20 */
 21static const lwgsm_mqtt_client_info_t
 22mqtt_client_info = {
 23    .keep_alive = 10,
 24
 25    /* Server login data */
 26    .user = "8a215f70-a644-11e8-ac49-e932ed599553",
 27    .pass = "26aa943f702e5e780f015cd048a91e8fb54cca28",
 28
 29    /* Device identifier address */
 30    .id = "2c3573a0-0176-11e9-a056-c5cffe7f75f9",
 31};
 32
 33/**
 34 * \brief           Memory for temporary topic
 35 */
 36static char
 37mqtt_topic_str[256];
 38
 39/**
 40 * \brief           Generate random number and write it to string
 41 * \param[out]      str: Output string with new number
 42 */
 43void
 44generate_random(char* str) {
 45    static uint32_t random_beg = 0x8916;
 46    random_beg = random_beg * 0x00123455 + 0x85654321;
 47    sprintf(str, "%u", (unsigned)((random_beg >> 8) & 0xFFFF));
 48}
 49
 50/**
 51 * \brief           MQTT client API thread
 52 */
 53void
 54mqtt_client_api_thread(void const* arg) {
 55    lwgsm_mqtt_client_api_p client;
 56    lwgsm_mqtt_conn_status_t conn_status;
 57    lwgsm_mqtt_client_api_buf_p buf;
 58    lwgsmr_t res;
 59    char random_str[10];
 60
 61    LWGSM_UNUSED(arg);
 62
 63    /* Request network attach */
 64    while (lwgsm_network_request_attach() != lwgsmOK) {
 65        lwgsm_delay(1000);
 66    }
 67
 68    /* Create new MQTT API */
 69    if ((client = lwgsm_mqtt_client_api_new(256, 128)) == NULL) {
 70        goto terminate;
 71    }
 72
 73    while (1) {
 74        /* Make a connection */
 75        printf("Joining MQTT server\r\n");
 76
 77        /* Try to join */
 78        conn_status = lwgsm_mqtt_client_api_connect(client, "mqtt.mydevices.com", 1883, &mqtt_client_info);
 79        if (conn_status == LWGSM_MQTT_CONN_STATUS_ACCEPTED) {
 80            printf("Connected and accepted!\r\n");
 81            printf("Client is ready to subscribe and publish to new messages\r\n");
 82        } else {
 83            printf("Connect API response: %d\r\n", (int)conn_status);
 84            lwgsm_delay(5000);
 85            continue;
 86        }
 87
 88        /* Subscribe to topics */
 89        sprintf(mqtt_topic_str, "v1/%s/things/%s/cmd/#", mqtt_client_info.user, mqtt_client_info.id);
 90        if (lwgsm_mqtt_client_api_subscribe(client, mqtt_topic_str, LWGSM_MQTT_QOS_AT_LEAST_ONCE) == lwgsmOK) {
 91            printf("Subscribed to topic\r\n");
 92        } else {
 93            printf("Problem subscribing to topic!\r\n");
 94        }
 95
 96        while (1) {
 97            /* Receive MQTT packet with timeout */
 98            if ((res = lwgsm_mqtt_client_api_receive(client, &buf, 5000)) == lwgsmOK) {
 99                if (buf != NULL) {
100                    printf("Publish received!\r\n");
101                    printf("Topic: %s, payload: %s\r\n", buf->topic, buf->payload);
102                    lwgsm_mqtt_client_api_buf_free(buf);
103                    buf = NULL;
104                }
105            } else if (res == lwgsmCLOSED) {
106                printf("MQTT connection closed!\r\n");
107                break;
108            } else if (res == lwgsmTIMEOUT) {
109                printf("Timeout on MQTT receive function. Manually publishing.\r\n");
110
111                /* Publish data on channel 1 */
112                generate_random(random_str);
113                sprintf(mqtt_topic_str, "v1/%s/things/%s/data/1", mqtt_client_info.user, mqtt_client_info.id);
114                lwgsm_mqtt_client_api_publish(client, mqtt_topic_str, random_str, strlen(random_str), LWGSM_MQTT_QOS_AT_LEAST_ONCE, 0);
115            }
116        }
117        goto terminate;
118    }
119
120terminate:
121    lwgsm_mqtt_client_api_delete(client);
122    lwgsm_network_request_detach();
123    printf("MQTT client thread terminate\r\n");
124    lwgsm_sys_thread_terminate(NULL);
125}
group LWGSM_APP_MQTT_CLIENT_API

Sequential, single thread MQTT client API.

Typedefs

typedef struct lwgsm_mqtt_client_api_buf *lwgsm_mqtt_client_api_buf_p

Pointer to lwgsm_mqtt_client_api_buf_t structure.

Functions

lwgsm_mqtt_client_api_p lwgsm_mqtt_client_api_new(size_t tx_buff_len, size_t rx_buff_len)

Create new MQTT client API.

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

  • rx_buff_len[in] Maximal RX buffer

Returns

Client handle on success, NULL otherwise

void lwgsm_mqtt_client_api_delete(lwgsm_mqtt_client_api_p client)

Delete client from memory.

Parameters

client[in] MQTT API client handle

lwgsm_mqtt_conn_status_t lwgsm_mqtt_client_api_connect(lwgsm_mqtt_client_api_p client, const char *host, lwgsm_port_t port, const lwgsm_mqtt_client_info_t *info)

Connect to MQTT broker.

Parameters
  • client[in] MQTT API client handle

  • host[in] TCP host

  • port[in] TCP port

  • info[in] MQTT client info

Returns

LWGSM_MQTT_CONN_STATUS_ACCEPTED on success, member of lwgsm_mqtt_conn_status_t otherwise

lwgsmr_t lwgsm_mqtt_client_api_close(lwgsm_mqtt_client_api_p client)

Close MQTT connection.

Parameters

client[in] MQTT API client handle

Returns

lwgsmOK on success, member of lwgsmr_t otherwise

lwgsmr_t lwgsm_mqtt_client_api_subscribe(lwgsm_mqtt_client_api_p client, const char *topic, lwgsm_mqtt_qos_t qos)

Subscribe to topic.

Parameters
  • client[in] MQTT API client handle

  • topic[in] Topic to subscribe on

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

Returns

lwgsmOK on success, member of lwgsmr_t otherwise

lwgsmr_t lwgsm_mqtt_client_api_unsubscribe(lwgsm_mqtt_client_api_p client, const char *topic)

Unsubscribe from topic.

Parameters
  • client[in] MQTT API client handle

  • topic[in] Topic to unsubscribe from

Returns

lwgsmOK on success, member of lwgsmr_t otherwise

lwgsmr_t lwgsm_mqtt_client_api_publish(lwgsm_mqtt_client_api_p client, const char *topic, const void *data, size_t btw, lwgsm_mqtt_qos_t qos, uint8_t retain)

Publish new packet to MQTT network.

Parameters
  • client[in] MQTT API client handle

  • topic[in] Topic to publish on

  • data[in] Data to send

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

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

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

Returns

lwgsmOK on success, member of lwgsmr_t otherwise

uint8_t lwgsm_mqtt_client_api_is_connected(lwgsm_mqtt_client_api_p client)

Check if client MQTT connection is active.

Parameters

client[in] MQTT API client handle

Returns

1 on success, 0 otherwise

lwgsmr_t lwgsm_mqtt_client_api_receive(lwgsm_mqtt_client_api_p client, lwgsm_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

Parameters
  • client[in] MQTT API client handle

  • p[in] Pointer to output buffer

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

Returns

lwgsmOK on success, lwgsmCLOSED if MQTT is closed, lwgsmTIMEOUT on timeout

void lwgsm_mqtt_client_api_buf_free(lwgsm_mqtt_client_api_buf_p p)

Free buffer memory after usage.

Parameters

p[in] Buffer to free

struct lwgsm_mqtt_client_api_buf_t
#include <lwgsm_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

lwgsm_mqtt_qos_t qos

Quality of service