MQTT With lwIP and the NXP FRDM-K64F

In the area of IoT, one obvious need is to have a way to send and receive data with an Internet protocol. MQTT (or Message Queue Telemetry Transport) is exactly like that: a lightweight Machine-to-Machine communication protocol. With the MQTT protocol, a microcontroller (or ‘client’) can send data and/or subscribe to data. For example, to Adafruit.IO:

Adafruit MQTT IO Feed

In this article, I show the basic steps to get MQTT running on the NXP FRDM-K64F board using MCUXpresso, lwIP, and MQTT. lwIP is a small and open source TCP/IP stack in wide used. To keep things very simple in this first post, I’m using it in bare-metal (no RTOS) mode with no encryption/security. The principle applies to any IDE/toolchain, as long there is an lwIP port available for your board and IDE/toolchain. I’m using the MCUXpresso IDE, as it nicely integrates with the MCUXpresso SDK, which includes an lwIP port for the FRDM-K64F.

I’m using the following software and tools:

1. MCUXpresso IDE v10.0.0 b344
2. MCUXpresso SDK for FRDM-K64F v2.2.0
3. lwIP v2.0.0

MQTT

MQTT is a very cool connectivity protocol on top of TCP/IP with a subscribe/publish messaging transport. If you don’t know MQTT, then I recommend a bit of reading:

• MQTT.org website and overview: http://mqtt.org/
• Adafruit article about MQTT: https://learn.adafruit.com/mqtt-adafruit-io-and-you?view=all#why-mqtt
• Excellent MQTT article series over at HiveMQ: http://www.hivemq.com/blog/how-to-get-started-with-mqtt
• HiveMQ MQTT essentials: http://www.hivemq.com/blog/mqtt-essentials-part-1-introducing-mqtt

To use MQTT, I need a server or ‘broker’. Eclipse hosts the Mosquitto project, which is probably one of the most used MQTT brokers. You should be able to find plenty of tutorials about installing Mosquitto on Linux, Raspberry Pi, or even Windows.

Having a local broker is great for starting an MQTT project, as you can easily debug it and get things up and running with a local broker, and then you can switch to a broker/provider on the Internet. I have used this tutorial to install Mosquitto on Windows 10.

Running Mosquitto on Windows

Adafruit.io Broker

I love stuff from Adafruit! And they host a very useful MQTT broker.

To send and receive data, I have to use a user name with a password (the AIO key below). If using the MQTT port 1883, information is sent in clear text which is definitely not something I want. Instead, port 8883 with TLS v1.2 shall be used! In this tutorial, I’m assuming a local broker is behind a firewall, so using port 1883 is ok (but only in this case!).

Adafruit IO Settings

It is very useful to have a client tool installed on the host machine. Have a read at http://www.hivemq.com/blog/seven-best-mqtt-client-tools and choose one. I am using the MQTT.fx (http://www.jensd.de/apps/mqttfx/) utility, which has a nice GUI to monitor the broker status:

MQTT.fx Broker Status

To use MQTT.fx with Adafruit.io, see https://cdn-learn.adafruit.com/downloads/pdf/desktop-mqtt-client-for-adafruit-io.pdf.

Creating lwIP Projects

I started my MQTT project from one of the lwIP example projects that come with the MCUXpresso SDK:

Import SDK Examples

And then I used the bare metal ‘ping’ example as the base:

The example project used in this article is on GitHub.

From the ‘sources’ folder of that project, you need:

• mqtt.h: interface to mqtt.c
• mqtt.c: MQTT implementation on top of lwIP
• mqtt_opts.h: configuration header file

lwIP Initialization

The following code is a standard (bare metal) lwIP initialization:

1. Initialize board pins and clocks
2. Initialize timer for lwIP (time_init())
3. Configure network interface addresses (own (static) address, netmask, and gateway)
4. lwIP initialization (lwIP_init())

int main(void) {
    struct netif fsl_netif0;
    ip4_addr_t fsl_netif0_ipaddr, fsl_netif0_netmask, fsl_netif0_gw;

    SYSMPU_Type * base = SYSMPU;
    BOARD_InitPins();
    BOARD_BootClockRUN();
    BOARD_InitDebugConsole();
    /* Disable SYSMPU. */
    base - > CESR &= ~SYSMPU_CESR_VLD_MASK;

    time_init();

    IP4_ADDR( & fsl_netif0_ipaddr, configIP_ADDR0, configIP_ADDR1, configIP_ADDR2, configIP_ADDR3);
    IP4_ADDR( & fsl_netif0_netmask, configNET_MASK0, configNET_MASK1, configNET_MASK2, configNET_MASK3);
    IP4_ADDR( & fsl_netif0_gw, configGW_ADDR0, configGW_ADDR1, configGW_ADDR2, configGW_ADDR3);

    lwip_init();

    netif_add( & fsl_netif0, & fsl_netif0_ipaddr, & fsl_netif0_netmask, & fsl_netif0_gw, NULL, ethernetif_init, ethernet_input);
    netif_set_default( & fsl_netif0);
    netif_set_up( & fsl_netif0);

    PRINTF("\r\n************************************************\r\n");
    PRINTF(" MQTT Bare Metal example\r\n");
    PRINTF("************************************************\r\n");
    PRINTF(" IPv4 Address : %u.%u.%u.%u\r\n", ((u8_t * ) & fsl_netif0_ipaddr)[0], ((u8_t * ) & fsl_netif0_ipaddr)[1],
        ((u8_t * ) & fsl_netif0_ipaddr)[2], ((u8_t * ) & fsl_netif0_ipaddr)[3]);
    PRINTF(" IPv4 Subnet mask : %u.%u.%u.%u\r\n", ((u8_t * ) & fsl_netif0_netmask)[0], ((u8_t * ) & fsl_netif0_netmask)[1],
        ((u8_t * ) & fsl_netif0_netmask)[2], ((u8_t * ) & fsl_netif0_netmask)[3]);
    PRINTF(" IPv4 Gateway : %u.%u.%u.%u\r\n", ((u8_t * ) & fsl_netif0_gw)[0], ((u8_t * ) & fsl_netif0_gw)[1],
        ((u8_t * ) & fsl_netif0_gw)[2], ((u8_t * ) & fsl_netif0_gw)[3]);
    PRINTF("************************************************\r\n");

    DoMQTT( & fsl_netif0);
    for (;;) {}
    return 0;
}

The MQTT application logic is implemented in the DoMQTT() function.

Connect to the MQTT Broker

The following code shows how to connect with lwIP to the MQTT broker, adopted from the lwIP 2.0.2 code.

The address of the mqtt_client_t structure is passed from the caller:

mqtt_client_t mqtt_client;
mqtt_do_connect(&mqtt_client);

Which calls mqtt_do_connect():

static void mqtt_do_connect(mqtt_client_t * client) {
    ip4_addr_t broker_ipaddr;
    struct mqtt_connect_client_info_t ci;
    err_t err;

    IP4_ADDR( & broker_ipaddr, configBroker_ADDR0, configBroker_ADDR1, configBroker_ADDR2, configBroker_ADDR3);

    /* Setup an empty client info structure */
    memset( & ci, 0, sizeof(ci));

    /* Minimal amount of information required is client identifier, so set it here */
    ci.client_id = configMQTT_CLIENT_NAME;
    ci.client_user = configMQTT_CLIENT_USER;
    ci.client_pass = configMQTT_CLIENT_PWD;

    /* Initiate client and connect to server, if this fails immediately an error code is returned
      otherwise mqtt_connection_cb will be called with connection result after attempting
      to establish a connection with the server.
      For now MQTT version 3.1.1 is always used */
    err = mqtt_client_connect(client, & broker_ipaddr, MQTT_PORT, mqtt_connection_cb, 0, & ci);

    /* For now just print the result code if something goes wrong */
    if (err != ERR_OK) {
        printf("mqtt_connect return %d\n", err);
    }
}

The example above uses a static client address. The client information structure is filled with a client name, a password, and user name (both can be NULL), and then it connects to the broker with a connection callback (mqtt_connection_cb).

Connection Callback

In the connection callback, if the connection gets accepted, it sets up three callbacks: one for the incoming publish callback (mqtt_incoming_publish_cb()), one for incoming data (mqtt_incoming_data_cb()), and one for subscription requests (mqtt_sub_request()):

static void mqtt_connection_cb(mqtt_client_t * client, void * arg, mqtt_connection_status_t status) {
    err_t err;

    if (status == MQTT_CONNECT_ACCEPTED) {
        printf("mqtt_connection_cb: Successfully connected\n");

        /* Setup callback for incoming publish requests */
        mqtt_set_inpub_callback(client, mqtt_incoming_publish_cb, mqtt_incoming_data_cb, arg);

        /* Subscribe to a topic named "subtopic" with QoS level 1, call mqtt_sub_request_cb with result */
        err = mqtt_subscribe(client, "subtopic", 1, mqtt_sub_request_cb, arg);

        if (err != ERR_OK) {
            printf("mqtt_subscribe return: %d\n", err);
        }
    } else {
        printf("mqtt_connection_cb: Disconnected, reason: %d\n", status);

        /* Its more nice to be connected, so try to reconnect */
        mqtt_do_connect(client);
    }
}

Below are example implementation of the three callbacks:

/* The idea is to demultiplex topic and create some reference to be used in data callbacks
 Example here uses a global variable, better would be to use a member in arg
 If RAM and CPU budget allows it, the easiest implementation might be to just take a copy of
 the topic string and use it in mqtt_incoming_data_cb
*/
static int inpub_id;
static void mqtt_incoming_publish_cb(void * arg,
    const char * topic, u32_t tot_len) {
    printf("Incoming publish at topic %s with total length %u\n", topic, (unsigned int) tot_len);

    /* Decode topic string into a user defined reference */
    if (strcmp(topic, "print_payload") == 0) {
        inpub_id = 0;
    } else if (topic[0] == 'A') {
        /* All topics starting with 'A' might be handled at the same way */
        inpub_id = 1;
    } else {
        /* For all other topics */
        inpub_id = 2;
    }
}

static void mqtt_incoming_data_cb(void * arg,
    const u8_t * data, u16_t len, u8_t flags) {
    printf("Incoming publish payload with length %d, flags %u\n", len, (unsigned int) flags);

    if (flags & MQTT_DATA_FLAG_LAST) {
        /* Last fragment of payload received (or whole part if payload fits receive buffer
        See MQTT_VAR_HEADER_BUFFER_LEN) */

        /* Call function or do action depending on reference, in this case inpub_id */
        if (inpub_id == 0) {
            /* Don't trust the publisher, check zero termination */
            if (data[len - 1] == 0) {
                printf("mqtt_incoming_data_cb: %s\n", (const char * ) data);
            }
        } else if (inpub_id == 1) {
            /* Call an 'A' function... */
        } else {
            printf("mqtt_incoming_data_cb: Ignoring payload...\n");
        }
    } else {
        /* Handle fragmented payload, store in buffer, write to file or whatever */
    }
}

static void mqtt_sub_request_cb(void * arg, err_t result) {
    /* Just print the result code here for simplicity,
    normal behaviour would be to take some action if subscribe fails like
    notifying user, retry subscribe or disconnect from server */
    printf("Subscribe result: %d\n", result);
}

Publishing Data

To publish data, below is an example function. Replace the example topic “erichs/f/test” with your own topic.

static void my_mqtt_publish(mqtt_client_t * client, void * arg) {
    const char * pub_payload = "abcd";
    err_t err;
    u8_t qos = 2; /* 0 1 or 2, see MQTT specification */
    u8_t retain = 0; /* No don't retain such crappy payload... */
    err = mqtt_publish(client, "erichs/f/test", pub_payload, strlen(pub_payload), qos, retain, mqtt_pub_request_cb, arg);
    if (err != ERR_OK) {
        printf("Publish err: %d\n", err);
    }
}

A callback (mqtt_pub_request_cb()) is provided. In my case below, I print an error code if it fails:

/* Called when publish is complete either with success or failure */
static void mqtt_pub_request_cb(void * arg, err_t result) {
    if (result != ERR_OK) {
        printf("Publish result: %d\n", result);
    }
}

Summary

With MQTT, I can publish/subscribe data on the Internet. It is lightweight, open source, and ideal for just about any IoT kind of application. But using it with the FRDM-K64F and lwIP took me a while to get things working, and I still face some issues in combination with FreeRTOS, so this is likely subject of a follow-up post. Another thing I have not covered here is the need for secure connections: Using an unencrypted MQTT port 1883 is not something to be used for sensitive data. Instead, port 8883 with SSL/TLS should be used. Yet another reason for a follow-up post, I think.

Happy MQTTing!

Links

• Example project used in this article on GitHub: https://github.com/ErichStyger/mcuoneclipse/tree/master/Examples/MCUXpresso/FRDM-K64F/FRDM-K64F_lwIP_lwIP_mqtt_bm
• NXP FRDM-K64F Board: http://www.nxp.com/products/software-and-tools/hardware-development-tools/freedom-development-boards/freedom-development-platform-for-kinetis-k64-k63-and-k24-mcus:FRDM-K64F
• MCUXpresso IDE: http://www.nxp.com/mcuxpresso/ide
• MQTT: http://mqtt.org/
• lwIP stack: https://savannah.nongnu.org/projects/lwIP/
• Installing Mosquitto on Windows: https://sivatechworld.wordpress.com/2015/06/11/step-by-step-installing-and-configuring-mosquitto-with-windows-7/
• MQTT client tool overview: http://www.hivemq.com/blog/seven-best-mqtt-client-tools