Embedded MQTT client#

Functions#

int32_t
rsi_emb_mqtt_client_init(int8_t *server_ip, uint32_t server_port, uint32_t client_port, uint16_t flags, uint16_t keep_alive_interval, int8_t *clientid, int8_t *username, int8_t *password)

Create MQTT objects. TCP level connection happens in this API. This is a blocking API.

int32_t
rsi_emb_mqtt_connect(uint8_t mqtt_flags, int8_t *will_topic, uint16_t will_message_len, int8_t *will_message)

Connect to MQTT Server/Broker. MQTT level connection happens in this API. This is a blocking API.

int32_t
rsi_emb_mqtt_publish(int8_t *topic, rsi_mqtt_pubmsg_t *publish_msg)

Publish the given message on the topic specified. This is a blocking API.

int32_t
rsi_emb_mqtt_subscribe(uint8_t qos, int8_t *topic)

Subscribe to the topic specified. Thus, MQTT client will receive any data that is published on this topic. This is a blocking API.

int32_t

Unsubscribe to the topic specified.Thus, MQTT client will not receive any data published on this topic. This is a blocking API.

int32_t

Disconnect the client from MQTT Server/Broker. TCP and MQTT level disconnection take place here. This is a blocking API.

int32_t

Delete MQTT clients profile configuration. TCP level disconnection happens here, if required. This is a blocking API.

int32_t
rsi_emb_mqtt_register_call_back(uint32_t callback_id, void(*call_back_handler_ptr)(uint16_t status, uint8_t *buffer, const uint32_t length))

Register callbacks for MQTT Asynchronous messages. This is a non-blocking API.

int32_t
rsi_cal_mqtt_packet_len(int32_t rem_len)

Calculate length of MQTT packet. This is a non-blocking API.

Function Documentation#

rsi_emb_mqtt_client_init#

int32_t rsi_emb_mqtt_client_init (int8_t *server_ip, uint32_t server_port, uint32_t client_port, uint16_t flags, uint16_t keep_alive_interval, int8_t *clientid, int8_t *username, int8_t *password)

Create MQTT objects. TCP level connection happens in this API. This is a blocking API.

Parameters
[in]server_ip

- MQTT client keep alive interval

[in]server_port

- Client ID of MQTT client which should be unique for different clients.

[in]client_port

- User name of the MQTT client which is a credential for logging to MQTT server as an authentication

[in]flags

- Password of the MQTT client which is also credential for MQTT server as an authentication

N/Akeep_alive_interval
N/Aclientid
N/Ausername
N/Apassword

Flags

Description

BIT(0) - Clean Session

1 - Enable clean session for clearing the historic data

0 - Disable clean session

BIT(1) - SSL flag

1 - SSL Enable

0 - SSL Disable

BIT(2) - Server IP version

1 - IPV6

0 - IPV4

Returns

  • 0 - Success

  • Negative Value - Failure (Possible Error Codes - 0xfffffffe, 0xfffffffd, 0xfffffffc, 0xfffffffb, 0xffffffe0)

Note

  • RSI_EMB_MQTT_KEEPALIVE_RETRIES - Configures the MQTT Keep-alive retries in case the MQTT Ping response is not received from the MQTT broker within the command acknowledgement time (35 seconds) during the MQTT Keep-alive process.

  • which can be configured in rsi_wlan_config.h.

  • In this case the device notifies AT+RSI_MQTT_KA_TIMEOUT to the host.The MQTT Keep Alive retries happen every 35 seconds until MQTT Ping response is received for MQTT Ping request or until all the MQTT Keep Alive retries elapse.

  • This is an optional parameter. If not configured, the default value is 0. In this case, device will not perform MQTT Keep Alive retries, however the MQTT Keep Alive process keeps happening (until MQTT connection is terminated) every Keep Alive Time period configured by the host.

  • Precondition - rsi_config_ipaddress() API needs to be called before this API.

  • Refer to Error Codes for the description of above error codes.


Definition at line 58 of file network/protocols/rsi_emb_mqtt_client.c

rsi_emb_mqtt_connect#

int32_t rsi_emb_mqtt_connect (uint8_t mqtt_flags, int8_t *will_topic, uint16_t will_message_len, int8_t *will_message)

Connect to MQTT Server/Broker. MQTT level connection happens in this API. This is a blocking API.

Parameters
[in]mqtt_flags

- Network flags. Each bit in the flag has its own significance

Flags

Description

BIT(6) - pwdFlag

1 - Enable pwdFlag

0 - Disable pwdFlag

BIT(7) - usrFlag

1 - Enable usrFlag

0 - Disable usrFlag

[in]will_topic

- Will topic that the MQTT client wants the MQTT Server to publish when disconnected unexpectedly.

[in]will_message_len

- Length of will message

[in]will_message

- Will message issued by the MQTT Server for a broken client.

Returns

  • 0 - Success

  • Negative Value - Failure (Possible Error Codes - 0xfffffffd, 0xfffffffc, 0xfffffffb, 0xffffffe0)

Note

  • Precondition - rsi_emb_mqtt_client_init() API needs to be called before this API.

  • will_topic and will_message are not supported and should be NULL.

  • For connecting Embedded MQTT over SSL : Enable TCP_IP_FEAT_SSL in Opermode parameters as here #define RSI_TCP_IP_FEATURE_BIT_MAP (TCP_IP_FEAT_DHCPV4_CLIENT | TCP_IP_FEAT_SSL | TCP_IP_FEAT_DNS_CLIENT). Load the related SSL Certificates in the module using rsi_wlan_set_certificate() API.

  • Refer to Error Codes for the description of above error codes.

  • Length of the topic Length should not exceed 200 bytes excluding NULL termination character.


Definition at line 240 of file network/protocols/rsi_emb_mqtt_client.c

rsi_emb_mqtt_publish#

int32_t rsi_emb_mqtt_publish (int8_t *topic, rsi_mqtt_pubmsg_t *publish_msg)

Publish the given message on the topic specified. This is a blocking API.

Parameters
[in]topic

- Topic string on which MQTT client wants to publish data

[in]publish_msg

- Publish message

Returns

  • 0 - Success

  • Negative Value - Failure (Possible Error Codes - 0xfffffffe, 0xfffffffd, 0xfffffffc, 0xfffffffb, 0xffffffe0)

Note

  • Precondition - rsi_emb_mqtt_connect() API needs to be called before this API.

  • Refer to Error Codes for the description of above error codes.

  • Length of the topic Length should not exceed 200 bytes excluding NULL termination character.


Definition at line 341 of file network/protocols/rsi_emb_mqtt_client.c

rsi_emb_mqtt_subscribe#

int32_t rsi_emb_mqtt_subscribe (uint8_t qos, int8_t *topic)

Subscribe to the topic specified. Thus, MQTT client will receive any data that is published on this topic. This is a blocking API.

Parameters
[in]qos

- Quality of service of message at MQTT protocol level. Valid values are 0, 1, 2.

[in]topic

- Topic string on which MQTT client wants to subscribe.

Returns

  • 0 - Success

  • Negative Value - Failure (Possible Error Codes - 0xfffffffe, 0xfffffffd, 0xfffffffc, 0xfffffffb, 0xffffffe0)

Note

  • Precondition - rsi_emb_mqtt_connect() API needs to be called before this API.

  • Refer to Error Codes for the description of above error codes.

  • Length of the topic Length should not exceed 200 bytes excluding NULL termination character.


Definition at line 472 of file network/protocols/rsi_emb_mqtt_client.c

rsi_emb_mqtt_unsubscribe#

int32_t rsi_emb_mqtt_unsubscribe (int8_t *topic)

Unsubscribe to the topic specified.Thus, MQTT client will not receive any data published on this topic. This is a blocking API.

Parameters
[in]topic

- Topic string to which MQTT client wants to unsubscribe.

Returns

  • 0 - Success

  • Negative Value - Failure (Possible Error Codes - 0xfffffffe, 0xfffffffd, 0xfffffffc, 0xfffffffb, 0xffffffe0)

Note

  • Precondition - rsi_emb_mqtt_connect() API needs to be called before this API.

  • Refer to Error Codes for the description of above error codes.

  • Length of the topic Length should not exceed 200 bytes excluding NULL termination character.


Definition at line 576 of file network/protocols/rsi_emb_mqtt_client.c

rsi_emb_mqtt_disconnect#

int32_t rsi_emb_mqtt_disconnect ()

Disconnect the client from MQTT Server/Broker. TCP and MQTT level disconnection take place here. This is a blocking API.

Parameters
[in]Void

Returns

  • 0 - Success

  • Negative Value - Failure (Possible Error Codes - 0xfffffffd, 0xfffffffc, 0xfffffffb, 0xffffffe0)

Note

  • Precondition - rsi_emb_mqtt_connect() API needs to be called before this API.

  • Refer to Error Codes section for the description of the above error codes Error Codes.


Definition at line 678 of file network/protocols/rsi_emb_mqtt_client.c

rsi_emb_mqtt_destroy#

int32_t rsi_emb_mqtt_destroy ()

Delete MQTT clients profile configuration. TCP level disconnection happens here, if required. This is a blocking API.

Parameters
[in]Void

Returns

  • 0 - Success

  • Negative Value - Failure (Possible Error Codes - 0xfffffffd, 0xfffffffc, 0xfffffffb, 0xffffffe0)

Note


Definition at line 762 of file network/protocols/rsi_emb_mqtt_client.c

rsi_emb_mqtt_register_call_back#

int32_t rsi_emb_mqtt_register_call_back (uint32_t callback_id, void(*call_back_handler_ptr)(uint16_t status, uint8_t *buffer, const uint32_t length))

Register callbacks for MQTT Asynchronous messages. This is a non-blocking API.

Parameters
N/Acallback_id

If it's a Success - RSI_SUCCESS, else the possible error response codes are 0x0021, 0xFF74, 0xFF40, 0xFF87.

[in]call_back_handler_ptr

- Callback function pointer

[out]status

- Success - RSI_SUCCESS. Failure - Possible error codes are : 0x0030, 0x0036, 0x0065, 0xBBF1, 0xBBF2, 0xBBF3, 0xFFF6

[out]buffer

- Pointer to buffer which holds data

[out]length

- Length of the buffer

  • ### Prototypes of the callback functions with given callback id ###

    Callback id

    Function Description

    RSI_WLAN_NWK_EMB_MQTT_REMOTE_TERMINATE_CB

    Called to notify the remote termination of embedded MQTT socket

RSI_WLAN_NWK_EMB_MQTT_PUB_MSG_CB

Called when MQTT client receives the data which was published by other clients on the subscribed topic

RSI_WLAN_NWK_EMB_MQTT_KEEPALIVE_TIMEOUT_CB

Called when keep alive timeout has occurred

Returns

  • Status of the call_back_handler_ptr

Note

  • callback_id

    ID

    Description

    RSI_WLAN_NWK_EMB_MQTT_REMOTE_TERMINATE_CB

    If registered, this callback notifies the application of disconnection with the MQTT broker.

    RSI_WLAN_NWK_EMB_MQTT_PUB_MSG_CB

    If registered, this callback provides MQTT publish received data to the application.

    RSI_WLAN_NWK_EMB_MQTT_KEEPALIVE_TIMEOUT_CB

    If registered, this callback notifies the application of MQTT keepalive response timeout, i.e., ping response is not received within the MQTT Command ACK Timer.


Definition at line 863 of file network/protocols/rsi_emb_mqtt_client.c

rsi_cal_mqtt_packet_len#

int32_t rsi_cal_mqtt_packet_len (int32_t rem_len)

Calculate length of MQTT packet. This is a non-blocking API.

Parameters
[in]rem_len

- Length

Returns

  • Length of MQTT packet (adjusted rem_len)


Definition at line 902 of file network/protocols/rsi_emb_mqtt_client.c