Functions
fsp_err_t	RM_MQTT_DA16XXX_Open (mqtt_onchip_da16xxx_instance_ctrl_t p_ctrl, mqtt_onchip_da16xxx_cfg_t const const p_cfg)

fsp_err_t	RM_MQTT_DA16XXX_Disconnect (mqtt_onchip_da16xxx_instance_ctrl_t *p_ctrl)

fsp_err_t	RM_MQTT_DA16XXX_Connect (mqtt_onchip_da16xxx_instance_ctrl_t *p_ctrl, uint32_t timeout_ms)

fsp_err_t	RM_MQTT_DA16XXX_Publish (mqtt_onchip_da16xxx_instance_ctrl_t p_ctrl, mqtt_onchip_da16xxx_pub_info_t const p_pub_info)

fsp_err_t	RM_MQTT_DA16XXX_Subscribe (mqtt_onchip_da16xxx_instance_ctrl_t p_ctrl, mqtt_onchip_da16xxx_sub_info_t const p_sub_info, size_t subscription_count)

fsp_err_t	RM_MQTT_DA16XXX_UnSubscribe (mqtt_onchip_da16xxx_instance_ctrl_t p_ctrl, mqtt_onchip_da16xxx_sub_info_t const p_sub_info)

fsp_err_t	RM_MQTT_DA16XXX_Receive (mqtt_onchip_da16xxx_instance_ctrl_t p_ctrl, mqtt_onchip_da16xxx_cfg_t const const p_cfg)

fsp_err_t	RM_MQTT_DA16XXX_Close (mqtt_onchip_da16xxx_instance_ctrl_t *p_ctrl)

Detailed Description

MQTT client implementation using the DA16XXX WiFi module on RA MCUs.

Overview

This Middleware module supplies an implementation for the MQTT Client on the DA16XXX module. The network stack is run on the DA16XXX and this module inherits and extends the core functionality from the DA16XXX WiFi driver. The DA16XXX MQTT module only supports FreeRTOS currently (Microsoft Azure support expected in future release).

The DA16XXX module supports the following modules:

DA16200
DA16600

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

Features

The MQTT Onchip da16xxx Middleware driver supplies these features:

Supports connect/disconnect to an MQTT broker via hostname, port, and user credentials
Supports unsecure and secure connection via TLS encryption
Supports the MQTT subscribe/publish model for multiple topics
Supports other optional configurations such as MQTT v3.1.1, Quality-of-service (QoS) level, TLS cipher suites, and ALPNs

Configuration

Build Time Configurations for rm_mqtt_onchip_da16xxx

The following build time configurations are defined in fsp_cfg/rm_mqtt_onchip_da16xxx_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
Size of MQTT RX buffer	Must be an integer greater than 0	512	Size in bytes of the MQTT buffer used for receiving subscribed data. Must be an integer greater than 0.
Size of MQTT TX buffer	Must be an integer greater than 200 and less than 2064	512	Size in bytes of the MQTT buffer used for sending commands and publishing data. Maximum publishing length is 2063 bytes

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

Note: This module provides the basic configurations in the FSP Configurator required to connect to an MQTT broker such as credential information (user, password, client key, etc.), publish/subscribe topics, and optional configurations as required. The user can then copy these configurations to a new structure if they want to connect to a new endpoint/make changes to the configurations dynamically.

Interrupt Configuration

Refer to UART (r_sci_uart). R_SCI_UART_Open() is called by WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

Clock Configuration

Refer to UART (r_sci_uart).

Pin Configuration

Refer to UART (r_sci_uart). R_SCI_UART_Open() is called by WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx)

Usage Notes

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

This module is not a standalone module - ensure that the WiFi module APIs are invoked first to configure the DA16XXX module and connect to an Access Point before using the MQTT module where the default buffer size for incoming TLS is 6KB and outgoing TLS is 4KB.
When the user intends to use secure TLS in their application, they need to provide certificates (root certificate authority, client certificate, and private key) in a header file
The user must provide certificate macro names in the FSP Configurator properties, as well as the name of the header file (to link the module, certificates, and header together)
If the user provides these credentials in the Configurator, they must create a new header file in their /src/ folder with the same name as they provided in the Configurator properties. When the code is generated, a build error will occur if the header file is not created
If only using username and password, these fields can be left blank (default), and a header file does not need to be created

Limitations

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

Ensure that DA16XXX SDK version v3.2.6 or later is being used, where the default buffer size for incoming TLS is 6KB and outgoing TLS is 4KB. Using earlier versions may result in failure to connect to an MQTT broker with TLS (unless buffer size settings are altered manually)
For publish/subscribe topics, a separate QoS level cannot be set per topic - only one QoS level can be set which applies to all messages
Currently the module only supports unsecured MQTT with username/password or secure MQTT/TLS with certificates (root CA, client certificate, and private key). The module does not accept username/password with certificates.

Examples

Basic Example

This is a basic example of minimal use of MQTT Middleware in an application.

void mqtt_onchip_basic_example (void)
{
    WIFIReturnCode_t wifi_err;
    fsp_err_t        mqtt_err;
    /* Setup Access Point connection parameters */
    WIFINetworkParams_t net_params =
    {
        .ucChannel                  = 0,
        .xPassword.xWPA.cPassphrase = WIFI_PWD,
        .ucSSID                     = WIFI_SSID,
        .xPassword.xWPA.ucLength = sizeof(WIFI_PWD),
        .ucSSIDLength            = sizeof(WIFI_SSID),
        .xSecurity               = eWiFiSecurityWPA2,
    };
    /* Open connection to the Wifi Module */
    wifi_err = WIFI_On();
    assert(eWiFiSuccess == wifi_err);
    /* Connect to the Access Point */
    wifi_err = WIFI_ConnectAP(&net_params);
    assert(eWiFiSuccess == wifi_err);
    /* Initialize the MQTT Client connection */
    mqtt_err = RM_MQTT_DA16XXX_Open(&g_rm_mqtt_onchip_da16xxx_instance, &g_mqtt_onchip_da16xxx_cfg);
    assert(FSP_SUCCESS == mqtt_err);
    /* Subscribe to MQTT topics to be received */
    mqtt_err = RM_MQTT_DA16XXX_Subscribe(&g_rm_mqtt_onchip_da16xxx_instance, subTopics, 1);
    assert(FSP_SUCCESS == mqtt_err);
    /* Connect to the MQTT Broker */
    mqtt_err = RM_MQTT_DA16XXX_Connect(&g_rm_mqtt_onchip_da16xxx_instance, CONNECT_TIMEOUT);
    assert(FSP_SUCCESS == mqtt_err);
    /* Publish data to the MQTT Broker */
    mqtt_err = RM_MQTT_DA16XXX_Publish(&g_rm_mqtt_onchip_da16xxx_instance, &pubTopics[0]);
    assert(FSP_SUCCESS == mqtt_err);
    /* Loop to receive data from the MQTT Broker */
    do
    {
        RM_MQTT_DA16XXX_Receive(&g_rm_mqtt_onchip_da16xxx_instance, &g_mqtt_onchip_da16xxx_cfg);
        R_BSP_SoftwareDelay(CONNECT_TIMEOUT, BSP_DELAY_UNITS_MILLISECONDS);
    } while (cb_flag == 0);
    /* Disconnect from the MQTT Broker */
    mqtt_err = RM_MQTT_DA16XXX_Disconnect(&g_rm_mqtt_onchip_da16xxx_instance);
    assert(FSP_SUCCESS == mqtt_err);
    /* Close the MQTT Client module */
    mqtt_err = RM_MQTT_DA16XXX_Close(&g_rm_mqtt_onchip_da16xxx_instance);
    assert(FSP_SUCCESS == mqtt_err);
}

Data Structures
struct	mqtt_onchip_da16xxx_sub_info_t

struct	mqtt_onchip_da16xxx_pub_info_t

struct	mqtt_onchip_da16xxx_callback_args_t

struct	mqtt_onchip_da16xxx_cfg_t

struct	mqtt_onchip_da16xxx_instance_ctrl_t

Macros
#define	MQTT_ONCHIP_DA16XXX_MAX_ALPN
	Maximum number of ALPNs supported by DA16XXX.

#define	MQTT_ONCHIP_DA16XXX_MAX_SNI_LEN
	Maximum length of SNI supported by DA16XXX.

#define	MQTT_ONCHIP_DA16XXX_TLS_CIPHER_SUITE_MAX
	Maximum number of TLS cipher suites supported by DA16XXX.

#define	MQTT_ONCHIP_DA16XXX_TLS_CIPHER_MAX_CNT
	Maximum number of TLS cipher suites supported by DA16XXX.

#define	MQTT_ONCHIP_DA16XXX_MAX_TOPIC_LEN
	Maximum total length for topics supported by DA16XXX.

#define	MQTT_ONCHIP_DA16XXX_MAX_PUBMSG_LEN
	Maximum total length for message supported by DA16XXX.

#define	MQTT_ONCHIP_DA16XXX_MAX_PUBTOPICMSG_LEN
	Maximum total length for message + topic supported by DA16XXX.

#define	MQTT_ONCHIP_DA16XXX_SUBTOPIC_MAX_CNT
	Maximum number of subscription topics allowed.

Enumerations
enum	mqtt_onchip_da16xxx_qos_t

enum	mqtt_onchip_da16xxx_tls_cipher_suites_t

Data Structure Documentation

◆ mqtt_onchip_da16xxx_sub_info_t

struct mqtt_onchip_da16xxx_sub_info_t

MQTT SUBSCRIBE packet parameters

Data Fields
mqtt_onchip_da16xxx_qos_t	qos	Quality of Service for subscription.
const char *	p_topic_filter	Topic filter to subscribe to.
uint16_t	topic_filter_length	Length of subscription topic filter.

◆ mqtt_onchip_da16xxx_pub_info_t

struct mqtt_onchip_da16xxx_pub_info_t

MQTT PUBLISH packet parameters

Data Fields
mqtt_onchip_da16xxx_qos_t	qos	Quality of Service for subscription.
const char *	p_topic_name	Topic name on which the message is published.
uint16_t	topic_name_Length	Length of topic name.
const char *	p_payload	Message payload.
uint32_t	payload_length	Message payload length.

◆ mqtt_onchip_da16xxx_callback_args_t

struct mqtt_onchip_da16xxx_callback_args_t

MQTT Packet info structure to be passed to user callback

Data Fields
uint8_t *	p_data	Payload received from subscribed MQTT topic.
const char *	p_topic	Topic to which the message payload belongs to.
uint32_t	data_length	Length of the MQTT payload.
void const *	p_context	Placeholder for user data.

◆ mqtt_onchip_da16xxx_cfg_t

struct mqtt_onchip_da16xxx_cfg_t

MQTT Configuration

Data Fields
const uint8_t	use_mqtt_v311
	Flag to use MQTT v3.1.1.

const uint16_t	rx_timeout
	MQTT Rx timeout in milliseconds.

const uint16_t	tx_timeout
	MQTT Tx timeout in milliseconds.

void(*	p_callback )(mqtt_onchip_da16xxx_callback_args_t *p_args)
	Location of user callback.

void const *	p_context
	Placeholder for user data. Passed to the user callback in mqtt_onchip_da16xxx_callback_args_t.

uint8_t	clean_session
	Whether to establish a new, clean session or resume a previous session.

uint8_t	alpn_count
	ALPN Protocols count. Max value is 3.

const char *	p_alpns [MQTT_ONCHIP_DA16XXX_MAX_ALPN]
	ALPN Protocols.

uint8_t	tls_cipher_count
	TLS Cipher suites count. Max value is 17.

uint16_t	keep_alive_seconds
	MQTT keep alive period.

const char *	p_client_identifier
	MQTT Client identifier. Must be unique per client.

uint16_t	client_identifier_length
	Length of the client identifier.

const char *	p_host_name
	MQTT endpoint host name.

const uint16_t	mqtt_port
	MQTT Port number.

const char *	p_mqtt_user_name
	MQTT user name. Set to NULL if not used.

uint16_t	user_name_length
	Length of MQTT user name. Set to 0 if not used.

const char *	p_mqtt_password
	MQTT password. Set to NULL if not used.

uint16_t	password_length
	Length of MQTT password. Set to 0 if not used.

const char *	p_root_ca
	String representing a trusted server root certificate.

uint32_t	root_ca_size
	Size associated with root CA Certificate.

const char *	p_client_cert
	String representing a Client certificate.

uint32_t	client_cert_size
	Size associated with Client certificate.

const char *	p_client_private_key
	String representing Client Private Key.

uint32_t	private_key_size
	Size associated with Client Private Key.

const char *	p_will_topic
	String representing Will Topic.

const char *	p_will_msg
	String representing Will Message.

const char *	p_sni_name
	Server Name Indication.

mqtt_onchip_da16xxx_qos_t	will_qos_level
	Will Topic QoS level.

mqtt_onchip_da16xxx_tls_cipher_suites_t	p_tls_cipher_suites [MQTT_ONCHIP_DA16XXX_TLS_CIPHER_MAX_CNT]
	TLS Cipher suites supported.

◆ mqtt_onchip_da16xxx_instance_ctrl_t

struct mqtt_onchip_da16xxx_instance_ctrl_t

MQTT_ONCHIP_DA16XXX private control block. DO NOT MODIFY.

Data Fields
uint8_t	cmd_tx_buff[MQTT_ONCHIP_DA16XXX_CFG_CMD_TX_BUF_SIZE]	Command send buffer.
uint8_t	cmd_rx_buff[MQTT_ONCHIP_DA16XXX_CFG_CMD_RX_BUF_SIZE]	Command receive buffer.
uint32_t	open	Flag to indicate if MQTT has been opened.
bool	is_mqtt_connected	Flag to track MQTT connection status.
mqtt_onchip_da16xxx_cfg_t const *	p_cfg	Pointer to p_cfg for MQTT.

Enumeration Type Documentation

◆ mqtt_onchip_da16xxx_qos_t

enum mqtt_onchip_da16xxx_qos_t

MQTT Quality-of-service (QoS) levels

Enumerator
MQTT_ONCHIP_DA16XXX_QOS_0	Delivery at most once.
MQTT_ONCHIP_DA16XXX_QOS_1	Delivery at least once.
MQTT_ONCHIP_DA16XXX_QOS_2	Delivery exactly once.

◆ mqtt_onchip_da16xxx_tls_cipher_suites_t

enum mqtt_onchip_da16xxx_tls_cipher_suites_t

MQTT TLS Cipher Suites

Enumerator
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA protocol.
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA protocol.
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 protocol.
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 protocol.
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 protocol.
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 protocol.
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA protocol.
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA protocol.
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 protocol.
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 protocol.
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 protocol.
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 protocol.

Function Documentation

◆ RM_MQTT_DA16XXX_Open()

fsp_err_t RM_MQTT_DA16XXX_Open	(	mqtt_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		mqtt_onchip_da16xxx_cfg_t const *const	p_cfg
	)

Initialize the DA16XXX on-chip MQTT Client service.

Parameters

[in]	p_ctrl	Pointer to MQTT Client instance control structure.
[in]	p_cfg	Pointer to MQTT Client configuration structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	The p_cfg instance is NULL.
FSP_ERR_INVALID_ARGUMENT	Data size is too large or NULL.
FSP_ERR_ALREADY_OPEN	The instance has already been opened.

◆ RM_MQTT_DA16XXX_Disconnect()

fsp_err_t RM_MQTT_DA16XXX_Disconnect ( mqtt_onchip_da16xxx_instance_ctrl_t * p_ctrl )

Disconnect from DA16XXX MQTT Client service.

Parameters

[in] p_ctrl Pointer to MQTT Client instance control structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	The p_ctrl instance is NULL.
FSP_ERR_NOT_OPEN	The instance has not been opened or the client is not connected.

◆ RM_MQTT_DA16XXX_Connect()

fsp_err_t RM_MQTT_DA16XXX_Connect	(	mqtt_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		uint32_t	timeout_ms
	)

Configure and connect the DA16XXX MQTT Client service.

Parameters

[in]	p_ctrl	Pointer to MQTT Client instance control structure.
[in]	timeout_ms	Timeout in milliseconds.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	The p_ctrl is NULL.
FSP_ERR_NOT_OPEN	The instance has not been opened.
FSP_ERR_IN_USE	The MQTT client is already connected.
FSP_ERR_INVALID_DATA	Response does not contain Connect status.

◆ RM_MQTT_DA16XXX_Publish()

fsp_err_t RM_MQTT_DA16XXX_Publish	(	mqtt_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		mqtt_onchip_da16xxx_pub_info_t *const	p_pub_info
	)

Publish a message for a given MQTT topic.

Parameters

[in]	p_ctrl	Pointer to MQTT Client instance control structure.
[in]	p_pub_info	MQTT Publish packet parameters.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	The p_ctrl, p_pub_info is NULL.
FSP_ERR_NOT_OPEN	The instance has not been opened or the client is not connected.
FSP_ERR_INVALID_DATA	Data size is too large.

◆ RM_MQTT_DA16XXX_Subscribe()

fsp_err_t RM_MQTT_DA16XXX_Subscribe	(	mqtt_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		mqtt_onchip_da16xxx_sub_info_t *const	p_sub_info,
		size_t	subscription_count
	)

Subscribe to DA16XXX MQTT topics.

Parameters

[in]	p_ctrl	Pointer to MQTT Client instance control structure.
[in]	p_sub_info	List of MQTT subscription info.
[in]	subscription_count	Number of topics to subscribe to.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	The p_ctrl, p_sub_info is NULL or subscription_count is 0.
FSP_ERR_NOT_OPEN	The instance has not been opened.
FSP_ERR_INVALID_DATA	Data size is too large.

◆ RM_MQTT_DA16XXX_UnSubscribe()

fsp_err_t RM_MQTT_DA16XXX_UnSubscribe	(	mqtt_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		mqtt_onchip_da16xxx_sub_info_t *const	p_sub_info
	)

Unsubscribe from DA16XXX MQTT topics.

Parameters

[in]	p_ctrl	Pointer to MQTT Client instance control structure.
[in]	p_sub_info	List of MQTT subscription info.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	The p_ctrl, p_sub_info is NULL.
FSP_ERR_NOT_OPEN	The instance has not been opened or the client is not connected.
FSP_ERR_INVALID_DATA	Data size is too large.

◆ RM_MQTT_DA16XXX_Receive()

fsp_err_t RM_MQTT_DA16XXX_Receive	(	mqtt_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		mqtt_onchip_da16xxx_cfg_t const *const	p_cfg
	)

Receive data subscribed to on DA16XXX MQTT Client service.

Parameters

[in]	p_ctrl	Pointer to MQTT Client instance control structure.
[in]	p_cfg	Pointer to MQTT Client configuration structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	The p_ctrl, p_textstring, p_ip_addr is NULL.
FSP_ERR_NOT_OPEN	The instance has not been opened or the client is not connected.
FSP_ERR_INVALID_DATA	Receive function did not receive valid publish data.

◆ RM_MQTT_DA16XXX_Close()

fsp_err_t RM_MQTT_DA16XXX_Close ( mqtt_onchip_da16xxx_instance_ctrl_t * p_ctrl )

Close the DA16XXX MQTT Client service.

Parameters

[in] p_ctrl Pointer to MQTT Client instance control structure.

Return values

FSP_ERR_NOT_OPEN	The instance has not been opened.
FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	The p_ctrl, p_textstring, p_ip_addr is NULL.

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for rm_mqtt_onchip_da16xxx

Interrupt Configuration

Clock Configuration

Pin Configuration

Usage Notes

Limitations

Examples

Basic Example

Data Structures

Macros

Enumerations

Data Structure Documentation

◆ mqtt_onchip_da16xxx_sub_info_t

◆ mqtt_onchip_da16xxx_pub_info_t

◆ mqtt_onchip_da16xxx_callback_args_t

◆ mqtt_onchip_da16xxx_cfg_t

Data Fields

◆ mqtt_onchip_da16xxx_instance_ctrl_t

Enumeration Type Documentation

◆ mqtt_onchip_da16xxx_qos_t

◆ mqtt_onchip_da16xxx_tls_cipher_suites_t

Function Documentation

◆ RM_MQTT_DA16XXX_Open()

◆ RM_MQTT_DA16XXX_Disconnect()

◆ RM_MQTT_DA16XXX_Connect()

◆ RM_MQTT_DA16XXX_Publish()

◆ RM_MQTT_DA16XXX_Subscribe()

◆ RM_MQTT_DA16XXX_UnSubscribe()

◆ RM_MQTT_DA16XXX_Receive()

◆ RM_MQTT_DA16XXX_Close()