AWS MQTT

This module provides the AWS MQTT integration documentation.

Overview

The AWS MQTT library can connect to either AWS or a third party MQTT broker such as Mosquitto. The documentation for the library can be found at the following link: coreMQTT.

Features

• MQTT connections over TLS to an AWS IoT Endpoint or Mosquitto server

Configuration

Memory Usage

The AWS CoreMQTT library relies heavily on dynamic memory allocation for thread/task creation as well as other uses. Depending on the configuration it may be required to provide as much as 110k heap. To decrease this it is recommended to tweak the thread stack configuration values based on usage. Notable values are:

FreeRTOS Thread

• General|Minimal Stack Size

FreeRTOS Plus TCP

• Stack size in words (not bytes)

Usage Notes

• A transport interface is required to use the CoreMQTT library (https://www.freertos.org/network-interface.html).
• For FSP, a transport interface over MbedTLS is provided. This transport interface can connect to RA ethernet, WiFi, and cellular modules via sockets wrappers for each module.
• TLS_FreeRTOS_Connect should be used before calling any CoreMQTT APIs. See the example for more information.
• Not all MQTT servers support maintaining a TLS session after a MQTT disconnect. TLS_FreeRTOS_Disconnect and TLS_FreeRTOS_Connect should be called to establish a new TLS session before attempting to reconnect with CoreMQTT APIs if the server does not support TLS session resumption.

Limitations

• aws_clientcredential.h and aws_clientcredential_keys.h need to be added manually.
• MbedTLS must be initialized and key provisioning must be done before starting a secure connection.

Examples

Connection example using MbedTLS/PKCS11 Transport Interface

#define EXAMPLE_PDN_CONTEXT_NUMBER         (1)
#define EXAMPLE_TIMEOUT_MS                 (5000)
#define EXAMPLE_DISABLE_SNI                (false)
#define EXAMPLE_MQTT_HOST                  ("mqtt_host_server")
#define EXAMPLE_MQTT_HOST_PORT             (8883)
#define EXAMPLE_MQTT_SEND_TIMEOUT          (5000)
#define EXAMPLE_MQTT_RECEIVE_TIMEOUT       (5000)
#define EXAMPLE_MQTT_TOPIC                 ("example_topic")
#define EXAMPLE_MQTT_CLIENT_IDENTIFIER     ("client_id")
#define EXAMPLE_MQTT_KEEP_ALIVE_SECONDS    (60)
#define EXAMPLE_MQTT_PAYLOAD               ("helloworld")

struct NetworkContext
{
    TlsTransportParams_t * pParams;
};

static const char SERVER_CERTIFICATE_PEM[] =
    "-----BEGIN CERTIFICATE-----\n"
    "MIIDazCCAlOgAwIBAgIURabL79ayIywQv0y8SPnbZ1FYDRIwDQYJKoZIhvcNAQEL\n"
    "BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\n"
    "GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0xOTA5MTEyMTIyMjZaFw0yMDA5\n"
    "MTAyMTIyMjZaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw\n"
    "HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwggEiMA0GCSqGSIb3DQEB\n"
    "AQUAA4IBDwAwggEKAoIBAQDSA3h+5sT58FHgnovnQzsVHQ0H/3TsnEKwVzyBwTQl\n"
    "s4PbG6VXCWyyJWjdJ4XMH1oU8gAlxauFbwOO98Aquei4K3Pi/ynKNBeX4VJcLyE5\n"
    "Azq7nRIIwt4+OoZ5kV7v8JIoLY5i+Ktn3zq1t0y1ZmK6Uk/rRPonb+Kx7wQPx7jq\n"
    "ZIZGda+CgF6ZedidPcABuggqD1y3U2gLiRPoBhe9nN2hG60rRp7vhbWMF0pzTDXu\n"
    "BKF7XSTbhYz3pl6NeOCLh5E3t8x908Ui5W1zDN3iOysrcwQFtCiGTvzNtxSfli1+\n"
    "PugIt9Q2vlYmuz5qI+juxHftJSXO86M5SV7exqUOXP9RAgMBAAGjUzBRMB0GA1Ud\n"
    "DgQWBBQG8VNJEJUjpTKMjmrOY3XApNp5lDAfBgNVHSMEGDAWgBQG8VNJEJUjpTKM\n"
    "jmrOY3XApNp5lDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQAt\n"
    "CabfjsYUnG8tt3/GDdhjsuG+SfeQe11S73pZi3+L616bPH5MNUv+LkgR/1AFEqt5\n"
    "WadKVTgzW5Ork1t7CfkYwrOHbyhyaaDPzERjMCfCcl8lQluBy6vE/lEb0hWq6XlO\n"
    "f6+8i+VKxWkSIXs2ZQqqYSOTTzAjHSsiiuE5WsC00ErvCvnC7uD6+3Y7W1uQRkFZ\n"
    "uSd9AN1ixPvAFi69FF/ymlJv6vII5GXOVDrIwdr50bMNuezMEx6qMNDADRH8iEaL\n"
    "JaSgfklczGiI1i7MPD4JTtsXOgKwxcBDAa0zQDVA5uBGEIOhva3m5X70N4iO7W0V\n"
    "eEhZekKeg3Fl3t/CXi8l\n"
    "-----END CERTIFICATE-----";

#define keyCLIENT_CERTIFICATE_PEM                                        \
    "-----BEGIN CERTIFICATE-----\n"                                      \
    "MIIDETCCAfkCFHwd2yn8zn5qB2ChYUT9Mvbi9Xp1MA0GCSqGSIb3DQEBCwUAMEUx\n" \
    "CzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRl\n" \
    "cm5ldCBXaWRnaXRzIFB0eSBMdGQwHhcNMTkwOTExMjEyMjU0WhcNMjAwOTEwMjEy\n" \
    "MjU0WjBFMQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UE\n" \
    "CgwYSW50ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOC\n" \
    "AQ8AMIIBCgKCAQEAo8oThJXSMDo41oL7HTpC4TX8NalBvnkFw30Av67dl/oZDjVA\n" \
    "iXPnZkhVppLnj++0/Oed0M7UwNUO2nurQt6yTYrvW7E8ZPjAlC7ueJcGYZhOaVv2\n" \
    "bhSmigjFQru2lw5odSuYy5+22CCgxft58nrRCo5Bk+GwWgZmcrxe/BzutRHQ7X4x\n" \
    "dYJhyhBOi2R1Kt8XsbuWilfgfkVhhkVklFeKqiypdQM6cnPWo/G4DyW34jOXzzEM\n" \
    "FLWvQOQLCKUZOgjJBnFdbx8oOOwMkYCChbV7gqPE6cw0Zy26CvlLQiINyonLPbNT\n" \
    "c64sS/ZBGPZFOPJmb4tG2nipYgZ1hO/r++jCbwIDAQABMA0GCSqGSIb3DQEBCwUA\n" \
    "A4IBAQCdqq59ubdRY9EiV3bleKXeqG7+8HgBHdm0X9dgq10nD37p00YLyuZLE9NM\n" \
    "066G/VcflGrx/Nzw+/UuI7/UuBbBS/3ppHRnsZqBIl8nnr/ULrFQy8z3vKtL1q3C\n" \
    "DxabjPONlPO2keJeTTA71N/RCEMwJoa8i0XKXGdu/hQo6x4n+Gq73fEiGCl99xsc\n" \
    "4tIO4yPS4lv+uXBzEUzoEy0CLIkiDesnT5lLeCyPmUNoU89HU95IusZT7kygCHHd\n" \
    "72am1ic3X8PKc268KT3ilr3VMhK67C+iIIkfrM5AiU+oOIRrIHSC/p0RigJg3rXA\n" \
    "GBIRHvt+OYF9fDeG7U4QDJNCfGW+\n"                                     \
    "-----END CERTIFICATE-----"

#define keyCLIENT_PRIVATE_KEY_PEM                                        \
    "-----BEGIN RSA PRIVATE KEY-----\n"                                  \
    "MIIEowIBAAKCAQEAo8oThJXSMDo41oL7HTpC4TX8NalBvnkFw30Av67dl/oZDjVA\n" \
    "iXPnZkhVppLnj++0/Oed0M7UwNUO2nurQt6yTYrvW7E8ZPjAlC7ueJcGYZhOaVv2\n" \
    "bhSmigjFQru2lw5odSuYy5+22CCgxft58nrRCo5Bk+GwWgZmcrxe/BzutRHQ7X4x\n" \
    "dYJhyhBOi2R1Kt8XsbuWilfgfkVhhkVklFeKqiypdQM6cnPWo/G4DyW34jOXzzEM\n" \
    "FLWvQOQLCKUZOgjJBnFdbx8oOOwMkYCChbV7gqPE6cw0Zy26CvlLQiINyonLPbNT\n" \
    "c64sS/ZBGPZFOPJmb4tG2nipYgZ1hO/r++jCbwIDAQABAoIBAQCGR2hC/ZVJhqIM\n" \
    "c2uuJZKpElpIIBBPOObZwwS3IYR4UUjzVgMn7UbbmxflLXD8lzfZU4YVp0vTH5lC\n" \
    "07qvYuXpHqtnj+GEok837VYCtUY9AuHeDM/2paV3awNV15E1PFG1Jd3pqnH7tJw6\n" \
    "VBZBDiGNNt1agN/UnoSlMfvpU0r8VGPXCBNxe3JY5QyBJPI1wF4LcxRI+eYmr7Ja\n" \
    "/cjn97DZotgz4B7gUNu8XIEkUOTwPabZINY1zcLWiXTMA+8qTniPVk653h14Xqt4\n" \
    "4o4D4YCTpwJcmxSV1m21/6+uyuXr9SIKAE+Ys2cYLA46x+rwLaW5fUoQ5hHa0Ytb\n" \
    "RYJ4SrtBAoGBANWtwlE69N0hq5xDPckSbNGubIeG8P4mBhGkJxIqYoqugGLMDiGX\n" \
    "4bltrjr2TPWaxTo3pPavLJiBMIsENA5KU+c/r0jLkxgEp9MIVJrtNgkCiDQqogBG\n" \
    "j4IJL2iQwXoLCqk2tx/dh9Mww+7SETE7EPNrv4UrYaGN5AEvpf5W+NHPAoGBAMQ6\n" \
    "wVa0Mx1PlA4enY2rfE3WXP8bzjleSOwR75JXqG2WbPC0/cszwbyPWOEqRpBZfvD/\n" \
    "QFkKx06xp1C09XwiQanr2gDucYXHeEKg/9iuJV1UkMQp95ojlhtSXdRZV7/l4pmN\n" \
    "fpB2vcAptX/4gY4tDrWMO08JNnRjE7duC+rmmk1hAoGAS4L0QLCNB/h2JOq+Uuhn\n" \
    "/FGfmOVfFPFrA6D3DbxcxpWUWVWzSLvb0SOphryzxbfEKyau7V5KbDp7ZSU/IC20\n" \
    "KOygjSEkAkDi7fjrrTRW/Cgg6g6G4YIOBO4qCtHdDbwJMHNdk6096qw5EZS67qLp\n" \
    "Apz5OZ5zChySjri/+HnTxJECgYBysGSP6IJ3fytplTtAshnU5JU2BWpi3ViBoXoE\n" \
    "bndilajWhvJO8dEqBB5OfAcCF0y6TnWtlT8oH21LHnjcNKlsRw0Dvllbd1oylybx\n" \
    "3da41dRG0sCEtoflMB7nHdDLt/DZDnoKtVvyFG6gfP47utn+Ahgn+Zp6K+46J3eP\n" \
    "s3g8AQKBgE/PJiaF8pbBXaZOuwRRA9GOMSbDIF6+jBYTYp4L9wk4+LZArKtyI+4k\n" \
    "Md2DUvHwMC+ddOtKqjYnLm+V5cSbvu7aPvBZtwxghzTUDcf7EvnA3V/bQBh3R0z7\n" \
    "pVsxTyGRmBSeLdbUWACUbX9LXdpudarPAJ59daWmP3mBEVmWdzUw\n"             \
    "-----END RSA PRIVATE KEY-----"

/* Callback to handle MQTT events, user should add their own processing */
static void prvEventCallback(MQTTContext_t          * pxMQTTContext,
                             MQTTPacketInfo_t       * pxPacketInfo,
                             MQTTDeserializedInfo_t * pxDeserializedInfo);

static void prvEventCallback (MQTTContext_t          * pxMQTTContext,
                              MQTTPacketInfo_t       * pxPacketInfo,
                              MQTTDeserializedInfo_t * pxDeserializedInfo)
{
    FSP_PARAMETER_NOT_USED(pxMQTTContext);
    FSP_PARAMETER_NOT_USED(pxPacketInfo);
    FSP_PARAMETER_NOT_USED(pxDeserializedInfo);
}

/* Callback to get current time */
static uint32_t prvGetTimeMs(void);

static uint32_t prvGetTimeMs (void)
{
    TickType_t xTickCount = 0;
    uint32_t   ulTimeMs   = 0UL;

    /* Get the current tick count. */
    xTickCount = xTaskGetTickCount();

    /* Convert the ticks to milliseconds. */
    ulTimeMs = (uint32_t) xTickCount * (1000U / configTICK_RATE_HZ); // NOLINT(readability-magic-numbers)

    return ulTimeMs;
}

NetworkContext_t networkContext;

void rm_aws_transport_interface_port_basic_example (void)
{
    ProvisioningParams_t params;
    NetworkCredentials_t credentials;
    TransportInterface_t transport;
    MQTTContext_t        mqtt_context;
    TlsTransportParams_t transport_params;
    static uint8_t       buffer[1024]; // NOLINT(readability-magic-numbers)
    MQTTFixedBuffer_t    networkBuffer;
    MQTTConnectInfo_t    connectInfo;
    MQTTPublishInfo_t    lwtInfo;
    bool                 session_present;

    /* Open little FS flash and format in order to store keys */
    assert(FSP_SUCCESS == RM_LITTLEFS_FLASH_Open(g_rm_littlefs0.p_ctrl, g_rm_littlefs0.p_cfg));
    assert(0 == lfs_format(&g_rm_littlefs0_lfs, &g_rm_littlefs0_lfs_cfg));
    assert(0 == lfs_mount(&g_rm_littlefs0_lfs, &g_rm_littlefs0_lfs_cfg));

    /* Initialize the crypto hardware acceleration. */
    mbedtls_platform_setup(NULL);

    /* Write the keys into a secure region in data flash. */
    params.pucClientCertificate      = (uint8_t *) keyCLIENT_CERTIFICATE_PEM;
    params.ulClientCertificateLength = sizeof(keyCLIENT_CERTIFICATE_PEM);
    params.pucClientPrivateKey       = (uint8_t *) keyCLIENT_PRIVATE_KEY_PEM;
    params.ulClientPrivateKeyLength  = sizeof(keyCLIENT_PRIVATE_KEY_PEM);
    params.pucJITPCertificate        = NULL;
    params.ulJITPCertificateLength   = 0;
    vAlternateKeyProvisioning(&params);

    /* Initialize network context */
    networkContext.pParams = &transport_params;

    /* Setup network credentials */
    credentials.pAlpnProtos      = NULL;
    credentials.disableSni       = EXAMPLE_DISABLE_SNI;
    credentials.pRootCa          = (const unsigned char *) SERVER_CERTIFICATE_PEM;
    credentials.rootCaSize       = sizeof(SERVER_CERTIFICATE_PEM);
    credentials.pUserName        = NULL;
    credentials.userNameSize     = 0;
    credentials.pPassword        = NULL;
    credentials.passwordSize     = 0;
    credentials.pClientCertLabel = pkcs11configLABEL_DEVICE_CERTIFICATE_FOR_TLS;
    credentials.pPrivateKeyLabel = pkcs11configLABEL_DEVICE_PRIVATE_KEY_FOR_TLS;

    /* Set transport interface */
    transport.pNetworkContext = &networkContext;
    transport.recv            = TLS_FreeRTOS_recv;
    transport.send            = TLS_FreeRTOS_send;

    /* Connect to a MQTT host */
    TLS_FreeRTOS_Connect(&networkContext,
                         EXAMPLE_MQTT_HOST,
                         EXAMPLE_MQTT_HOST_PORT,
                         &credentials,
                         EXAMPLE_MQTT_RECEIVE_TIMEOUT,
                         EXAMPLE_MQTT_SEND_TIMEOUT);

    /* Fill the values for network buffer. */
    networkBuffer.pBuffer = buffer;
    networkBuffer.size    = 1024;      // NOLINT

    /* Initialize MQTT */
    assert(MQTTSuccess == MQTT_Init(&mqtt_context, &transport, prvGetTimeMs, prvEventCallback, &networkBuffer));

    /* Set connection info for MQTT session */
    connectInfo.cleanSession           = true;
    connectInfo.clientIdentifierLength = sizeof(EXAMPLE_MQTT_CLIENT_IDENTIFIER) - 1;
    connectInfo.pClientIdentifier      = EXAMPLE_MQTT_CLIENT_IDENTIFIER;
    connectInfo.keepAliveSeconds       = EXAMPLE_MQTT_KEEP_ALIVE_SECONDS;
    connectInfo.pUserName              = NULL;
    connectInfo.userNameLength         = 0U;
    connectInfo.pPassword              = NULL;
    connectInfo.passwordLength         = 0U;

    /* LWT Info. */
    lwtInfo.pTopicName      = EXAMPLE_MQTT_TOPIC;
    lwtInfo.topicNameLength = sizeof(EXAMPLE_MQTT_TOPIC) - 1;
    lwtInfo.pPayload        = EXAMPLE_MQTT_PAYLOAD;
    lwtInfo.payloadLength   = strlen(EXAMPLE_MQTT_PAYLOAD);
    lwtInfo.qos             = MQTTQoS0;
    lwtInfo.dup             = false;
    lwtInfo.retain          = false;

    /* Send MQTT CONNECT packet to broker. */
    assert(MQTTSuccess == MQTT_Connect(&mqtt_context, &connectInfo, &lwtInfo, 20000, &session_present));
}