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:

• MQTT_PINGRESP_TIMEOUT_MS
  
• MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT

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

• LogError
• LogWarn
• LogInfo
• LogDebug

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
  );

• Transport Send: A function to send bytes over a network.

  int32_t (* TransportSend_t )(
      NetworkContext_t * pNetworkContext, const void * pBuffer, size_t bytesToSend
  );

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.