coreMQTT v2.1.1
MQTT 3.1.1 Client Library
Porting Guide

Guide for porting MQTT to a new platform.

A port to a new platform must provide the following components:

  1. Configuration Macros
  2. Transport Interface
  3. Time Function

Configuration Macros

Settings that must be set as macros in the config header core_mqtt_config.h, or passed in as compiler options.

Note
If a custom configuration header core_mqtt_config.h is not provided, then the MQTT_DO_NOT_USE_CUSTOM_CONFIG macro must be defined.
See also
Configurations

The following macros can be configured for the managed MQTT library:

In addition, the following logging macros are used throughout the library:

Transport Interface

The MQTT library relies on an underlying transport interface API that must be implemented in order to send and receive packets on a network.

See also
Transport Interface

The transport interface API used by MQTT is defined in transport_interface.h. A port must implement functions corresponding to the following functions pointers:

  • Transport Receive: A function to receive bytes from a network.
    int32_t (* TransportRecv_t )(
    NetworkContext_t * pNetworkContext, void * pBuffer, size_t bytesToRecv
    );
    int32_t(* TransportRecv_t)(NetworkContext_t *pNetworkContext, void *pBuffer, size_t bytesToRecv)
    Transport interface for receiving data on the network.
    Definition: transport_interface.h:221
    struct NetworkContext NetworkContext_t
    The NetworkContext is an incomplete type. An implementation of this interface must define struct Netw...
    Definition: transport_interface.h:191
  • Transport Send: A function to send bytes over a network.
    int32_t (* TransportSend_t )(
    NetworkContext_t * pNetworkContext, const void * pBuffer, size_t bytesToSend
    );
    int32_t(* TransportSend_t)(NetworkContext_t *pNetworkContext, const void *pBuffer, size_t bytesToSend)
    Transport interface for sending data over the network.
    Definition: transport_interface.h:243

The above two functions take in a pointer to a NetworkContext_t, the typename of a struct NetworkContext. The NetworkContext struct must also be defined by the port, and ought to contain any information necessary to send and receive data with the TransportSend_t and TransportRecv_t implementations, respectively:

struct NetworkContext {
// Fields necessary for the transport implementations, e.g. a TCP socket descriptor.
};

Time Function

The MQTT library relies on a function to generate millisecond timestamps, for the purpose of calculating durations and timeouts, as well as maintaining the keep-alive mechanism of the MQTT protocol.

See also
MQTTGetCurrentTimeFunc_t

Platforms must supply a function capable of generating 32 bit timestamps of millisecond resolution. These timestamps need not correspond with any real world clock; the only requirement is that the difference between two timestamps must be an accurate representation of the duration between them, in milliseconds.

Note
Should the platform be incapable of providing millisecond timestamps, the port may instead provide a function that always returns 0, or a strictly non-decreasing sequence. In this case, the timeout values in all library calls to MQTT_Connect, MQTT_ProcessLoop, or MQTT_ReceiveLoop MUST be set to 0, resulting in loop functions running for a single iteration, and MQTT_Connect relying on MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT to receive the CONNACK packet.