Configuration

Configuration settings of the MQTT library.

Configuration settings are C pre-processor constants. They can be set with a #define in the config file (iot_config.h) or by using a compiler option such as -D in gcc. If a configuration setting is not defined, the library will use a "sensible" default value (unless otherwise noted). Because they are compile-time constants, a library must be rebuilt if a configuration setting is changed.

configpagemarker

IOT_MQTT_ENABLE_ASSERTS

Set this to 1 to perform sanity checks when using the MQTT library.

Asserts are useful for debugging, but should be disabled in production code. If this is set to 1, IotMqtt_Assert can be defined to set the assertion function; otherwise, the Iot_DefaultAssert will be used.

Possible values: 0 (asserts disabled) or 1 (asserts enabled)
Recommended values: 1 when debugging; 0 in production code.
Default value (if undefined): 0

AWS_IOT_MQTT_ENABLE_METRICS

Set this to 1 to enable anonymous metrics reporting to AWS IoT.

Metrics allow AWS IoT to prioritize engineering resources based on SDK usage. SDK name and version are reported; no personal or identifying information is reported.

Possible values: 0 (metrics reporting disabled) or 1 (metrics reporting enabled)
Recommended values: 1
Default value (if undefined): 1

Note

This setting is only in effect for MQTT connections with AWS IoT.

IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES

Set this to 1 to allow the MQTT packet serializer and deserializer functions to be overridden.

Serializer overrides allow the functions that generate and decode MQTT packets to be overridden. When this setting is 1, each connection may have different serializer and deserializer functions. This allows the MQTT library to be used as a general-purpose transport library (with limitations). Currently, this setting is used to support MQTT over Bluetooth Low-Energy on FreeRTOS. See IotMqttSerializer_t for a list of functions that can be overridden. If this setting is 1, the initialization and cleanup functions may be extended by defining _IotMqtt_InitSerializeAdditional and _IotMqtt_CleanupSerializeAdditional. These functions will be called along with the default initialization and cleanup functions. They must have the following signatures:

#include <stdbool.h>

// Returns true on success and false on failure.
bool _IotMqtt_InitSerializeAdditional( void );
void _IotMqtt_CleanupSerializeAdditional( void );

Possible values: 0 (serializer overrides disabled) or 1 (serializer overrides enabled)
Recommended values: The default value is strongly recommended.
Default value (if undefined): The default value of this setting depends on the platform. For example, when running on FreeRTOS with BLE support, this setting will be automatically enabled. Conversely, when running on Linux, this setting will be disabled.

IOT_LOG_LEVEL_MQTT

Set the log level of the MQTT library.

Log messages from the MQTT library at or below this setting will be printed.

Possible values: One of the Log levels.
Default value (if undefined): IOT_LOG_LEVEL_GLOBAL; if that is undefined, then IOT_LOG_NONE.

IOT_MQTT_RESPONSE_WAIT_MS

A "reasonable amount of time" to wait for keep-alive responses from the MQTT server.

The MQTT spec states that if a response to a keep-alive request is not received within a "reasonable amount of time", the network connection should be closed. Since the meaning of "reasonable" depends heavily on use case, the amount of time to wait for keep-alive responses is defined by this setting. This setting is also used as the amount of time to wait for a final PUBACK to a QoS 1 PUBLISH message before returning IOT_MQTT_RETRY_NO_RESPONSE. See IotMqttPublishInfo_t for a description of QoS 1 PUBLISH retries.

Possible values: Any positive integer.
Default value (if undefined): 1000

IOT_MQTT_RETRY_MS_CEILING

Controls the maximum retry interval of QoS 1 PUBLISH retransmissions.

QoS 1 PUBLISH retransmissions follow a truncated exponential backoff strategy. The interval of time between retransmissions increases exponentially until IOT_MQTT_RETRY_MS_CEILING (or the retransmission limit) is reached, then increases by IOT_MQTT_RETRY_MS_CEILING until the retransmission limit is reached.

See also

IotMqttPublishInfo_t for a detailed description of the QoS 1 PUBLISH retransmission strategy.

Possible values: Any positive integer.
Default value (if undefined): 60000

IotMqtt_Assert

Assertion function used when IOT_MQTT_ENABLE_ASSERTS is 1.

Possible values: Any function with the same signature as the standard library's assert function.
Default value (if undefined): Iot_DefaultAssert if IOT_MQTT_ENABLE_ASSERTS is 1; otherwise, nothing. If Iot_DefaultAssert is not defined when asserts are enabled, the MQTT library will fail to build.

Memory allocation

The following functions may be re-implemented for the MQTT library.

• IotMqtt_MallocConnection
  Allocate an _mqttConnection_t. This function should have the same signature as malloc.
• IotMqtt_FreeConnection
  Free an _mqttConnection_t. This function should have the same signature as free.
• IotMqtt_MallocMessage
  Allocate memory for an MQTT packet. This function should have the same signature as malloc.
• IotMqtt_FreeMessage
  Free an MQTT packet. This function should have the same signature as free.
• IotMqtt_MallocOperation
  Allocate an _mqttOperation_t. This function should have the same signature as malloc.
• IotMqtt_FreeOperation
  Free an _mqttOperation_t. This function should have the same signature as free.
• IotMqtt_MallocSubscription
  Allocate an _mqttSubscription_t. This function should have the same signature as malloc.
• IotMqtt_FreeSubscription
  Free an _mqttSubscription_t. This function should have the same signature as free.

If a custom implementation is not set for an MQTT memory allocation function, IotDefault_Malloc and Iot_DefaultFree will be used. If IotDefault_Malloc and Iot_DefaultFree are not set, the MQTT library will fail to build.

When IOT_STATIC_MEMORY_ONLY is 1, the following settings configure the number of statically-allocated buffers for MQTT.

• IOT_MQTT_CONNECTIONS
  Number of MQTT connections that may be opened. Defaults to 1 if undefined.
• IOT_MQTT_MAX_IN_PROGRESS_OPERATIONS
  Maximum number of MQTT operations that may be in-progress at any time. Defaults to 10 if undefined.
• IOT_MQTT_SUBSCRIPTIONS
  Maximum number of MQTT subscriptions at any time. Defaults to 8 if undefined.