MQTT Port is publish-subscribe-based messaging protocol.
Overview
MQTT (Message Queue Telemetry Transport) is an ISO standard (ISO/IEC PRF 20922) publish-subscribe-based messaging protocol. It works on top of the TCP/IP protocol. The publisher sends (PUBLISH) messages to the subscriber through the broker. The subscriber needs to keep the connection with the broker by TCP session while the publisher can disconnect the session with the broker after sending a message. Once the broker receives a message with a specific topic the message is sent to subscribers that already registered with the topic. A subscriber can register with more than one topic. There can be many or no subscribers which registered with a specific topic. The exchange of MQTT messages supports QoS (Quality of Service).
Features
The MQTT Port module has the following key features:
- Publish message
- Subscribe message
- QoS
Configuration
Build Time Configurations for rm_mqtt_port_w
The following build time configurations are defined in fsp_cfg/rm_mqtt_port_w_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. |
| Watchdog Service Support |
| Disabled | Enable when using the Watchdog Service. |
Configurations for Networking > MQTT Port (rm_mqtt_port_w)
This module can be added to the Stacks tab via New Stack > Networking > MQTT Port (rm_mqtt_port_w).
| Configuration | Options | Default | Description |
| Certificates |
| MQTT Certificates Header File | Must be a valid C symbol | | Name of header file that will contain certificates (macros). User must create header file if this field is populated. |
| Root CA | Must be a valid C symbol | ROOT_CA | Links to user-defined macro of the same name for Root CA which user must define in application header. |
| Client Certificate | Must be a valid C symbol | CLIENT_CERT | Links to user-defined macro of the same name for client certificate which user must define in application header. |
| Private Key | Must be a valid C symbol | PRIVATE_KEY | Links to user-defined macro of the same name for private key which user must define in application header. |
| ALPN |
| ALPN 1 | Manual Entry | | Select Application Layer Protocol Negotiations (ALPNs) |
| ALPN 2 | Manual Entry | | Select Application Layer Protocol Negotiations (ALPNs) |
| ALPN 3 | Manual Entry | | Select Application Layer Protocol Negotiations (ALPNs) |
| Interrupts |
| Callback | Must be a valid C symbol | mqtt_client0_callback | A user callback function. This callback function must be provided. It is called from the MQTT Receive function to process subscribed MQTT messages. |
| Name | Name must be a valid C symbol | g_mqtt_client0 | Module name. |
| Use MQTT protocol v3.1.1 |
| Enabled | |
| MQTT Receive Maximum Timeout (ms) | Timeout must be an integer greater than 0 and less than 65535 | 1000 | Timeout for the MQTT Receive function to check the buffer for incoming MQTT messages in milliseconds. |
| MQTT Transit Maximum Timeout (ms) | Timeout must be an integer greater than 0 and less than 65535 | 1000 | Timeout for publishing MQTT messages in milliseconds. |
| Clean Session |
| Enabled | |
| Keep Alive (s) | Must be an integer greater than 0 and less than 65535 | 60 | MQTT ping period to check if connection is still active. |
| Client Identifier | Manual Entry | | |
| Host Name (or IP address) | Manual Entry | | |
| MQTT Port | Must be an integer greater than 0 and less than 65535 | 8883 | |
| MQTT User Name | Must be a valid C symbol | | |
| MQTT Password | Must be a valid C symbol | | |
| Last Will Topic | Manual Entry | | Topic for MQTT Last Will message. |
| Last Will Message | Manual Entry | | Payload for MQTT Last Will message. |
| Server Name Indication (SNI) | Manual Entry | | |
| Last Will QoS |
| 0 | Quality-of-Service for MQTT Last Will message. |
| TLS Cipher Suites | Refer to the RAFW Configuration tool for available options. | 0U | Select TLS Cipher Suites |
Clock Configuration
This module has no required clock configurations.
Pin Configuration
This module does not use I/O pins.
Usage Notes
Refer to WIFI (rm_wifi).
- This module is not a standalone module - ensure that the WiFi module APIs are invoked first to configure the RAFW 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 (rm_wifi).
- 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 the rm-mqtt-port in an application.
{
do
{
} while (conn_cb_flag == 0);
#ifndef MQTT_NVRAM_ENABLE
char qos_level[4];
sprintf((char *)&qos_level, "%d", subTopics[0].qos);
const char * message_sub_topic[100] = {"mqtt_client", "sub", (char *)subTopics[0].p_topic_filter, (char *)&qos_level};
mqtt_err = rm_mqtt_client_cmd_mqtt_client(&g_rm_mqtt_client_instance, 4, message_sub_topic);
#endif
do
{
} while (subscribe_cb_flag == 0);
do
{
} while (msg_cb_flag == 0);
return FSP_SUCCESS;
}
◆ mqtt_client_sub_info_t
| struct mqtt_client_sub_info_t |
MQTT SUBSCRIBE packet parameters
| Data Fields |
|
mqtt_client_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_client_pub_info_t
| struct mqtt_client_pub_info_t |
MQTT PUBLISH packet parameters
| Data Fields |
|
mqtt_client_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_client_callback_context_t
| struct mqtt_client_callback_context_t |
MQTT callback context structure to be passed to user callback
◆ mqtt_client_callback_args_t
| struct mqtt_client_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_client_cfg_t
◆ mqtt_client_instance_ctrl_t
| struct mqtt_client_instance_ctrl_t |
MQTT_CLIENT private control block. DO NOT MODIFY.
| Data Fields |
|
uint32_t |
open |
Flag to indicate if MQTT has been opened. |
|
bool |
is_mqtt_connected |
Flag to track MQTT connection status. |
|
mqtt_client_cfg_t const * |
p_cfg |
Pointer to p_cfg for MQTT. |
◆ mqtt_client_qos_t
MQTT Quality-of-service (QoS) levels
| Enumerator |
|---|
| MQTT_CLIENT_QOS_0 | Delivery at most once.
|
| MQTT_CLIENT_QOS_1 | Delivery at least once.
|
| MQTT_CLIENT_QOS_2 | Delivery exactly once.
|
◆ mqtt_client_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.
|
◆ mqtt_client_callback_event_t
◆ RM_MQTT_CLIENT_Open()
Initialize the 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_CLIENT_Disconnect()
Disconnect from 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_CLIENT_Connect()
Configure and connect the 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_CLIENT_Publish()
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. |
| FSP_ERR_OUT_OF_MEMORY | Memory allocation error. |
◆ RM_MQTT_CLIENT_Subscribe()
Subscribe to 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_CLIENT_UnSubscribe()
Unsubscribe from 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_CLIENT_Receive()
Receive data subscribed to 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_CLIENT_Close()
Close the 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. |