The ESP-AT MQTT library project
A simple wrapper to the MQTT functionality found in the ESP-AT interpreter
Public Member Functions | Private Attributes | List of all members
EspATMQTT Class Reference

EspAT MQTT EspATMQTT class definition. More...

#include <EspATMQTT.h>

Collaboration diagram for EspATMQTT:
Collaboration graph
[legend]

Public Member Functions

 EspATMQTT (HardwareSerial *=&ESP_SERIAL_PORT)
 The module constructor allows you to select what serial port that should be used to communicate with the ESP-AT module. More...
 
mqtt_status_t begin ()
 The begin method initializes the system before usage. More...
 
mqtt_status_t userConfig (uint32_t linkID, mqtt_scheme_t scheme, const char *clientID, const char *userName="", const char *password="", uint32_t certKeyID=0, uint32_t caID=0, const char *path="")
 Setup the connection scheme and how to connect to the server/broker. More...
 
mqtt_status_t userConfig (uint32_t linkID, mqtt_scheme_t scheme, char *clientID, const char *userName="", const char *password="", uint32_t certKeyID=0, uint32_t caID=0, const char *path="")
 Setup the connection scheme and how to connect to the server/broker. More...
 
mqtt_status_t userConfig (uint32_t linkID, mqtt_scheme_t scheme, char *clientID, char *userName, char *password, uint32_t certKeyID=0, uint32_t caID=0, const char *path="")
 Setup the connection scheme and how to connect to the server/broker. More...
 
mqtt_status_t connect (uint32_t linkID, const char *host, uint32_t port=1883, uint32_t reconnect=0, uint32_t timeout=5000, connected_cb_t cb=NULL)
 Connects to the specified server/broker with the previously defined transport scheme. More...
 
mqtt_status_t setClientID (uint32_t linkID, const char *clientID)
 Sets a new client ID for the connection. More...
 
mqtt_status_t setClientID (uint32_t linkID, char *clientID)
 Sets a new client ID for the connection. More...
 
mqtt_status_t setUsername (uint32_t linkID, const char *username)
 Sets the username used in authenticating the client with the broker. More...
 
mqtt_status_t setUsername (uint32_t linkID, char *username)
 Sets the username used in authenticating the client with the broker. More...
 
mqtt_status_t setPassword (uint32_t linkID, const char *password)
 Sets the password used in authenticating the client with the broker. More...
 
mqtt_status_t setPassword (uint32_t linkID, char *password)
 Sets the password used in authenticating the client with the broker. More...
 
mqtt_status_t connectionConfig (uint32_t linkID, uint32_t keepalive, uint32_t disable_clean_session, const char *lwt_topic, const char *lwt_message, uint32_t lwt_qos=0, uint32_t lwt_retain=0)
 Sets the configuration of the current MQTT connection. More...
 
mqtt_status_t setALPN (uint32_t linkID, const char *alpn1=NULL, const char *alpn2=NULL, const char *alpn3=NULL, const char *alpn4=NULL, const char *alpn5=NULL)
 This function sets the ALPN (Application Layer Protocol Negotiation) of the link. More...
 
mqtt_status_t pubString (uint32_t linkID, const char *topic, const char *data, uint32_t qos=0, uint32_t retain=0)
 Publish a string to a specified topic. More...
 
mqtt_status_t pubString (uint32_t linkID, const char *topic, char *data, uint32_t qos=0, uint32_t retain=0)
 Publish a string to a specified topic. More...
 
mqtt_status_t pubRaw (uint32_t linkID, const char *topic, const char *data, uint32_t qos=0, uint32_t retain=0)
 Publish raw data to a specified topic. More...
 
mqtt_status_t pubRaw (uint32_t linkID, const char *topic, char *data, uint32_t qos=0, uint32_t retain=0)
 Publish raw data to a specified topic. More...
 
mqtt_status_t subscribeTopic (subscription_cb_t cb, uint32_t linkID, const char *topic, uint32_t qos=0)
 Subscribe to messages from a specific topic. More...
 
mqtt_status_t subscribeTopic (subscription_cb_t cb, uint32_t linkID, char *topic, uint32_t qos=0)
 Subscribe to messages from a specific topic. More...
 
mqtt_status_t unSubscribeTopic (uint32_t linkID, const char *topic)
 Unsubscribe from messages with a specific topic. More...
 
mqtt_status_t unSubscribeTopic (uint32_t linkID, char *topic)
 Unsubscribe from messages with a specific topic. More...
 
mqtt_status_t close (uint32_t linkID)
 Close (all) conection/s with the specified link ID. More...
 
mqtt_status_t enableNTPTime (bool enable, validDateTime_cb_t cb, uint32_t timezone, const char *ts1=NULL, const char *ts2=NULL, const char *ts3=NULL)
 Enables the internal NTP Time client. More...
 
mqtt_status_t getNTPTime (char **time)
 Get the current time from the ESP-AT internal NTP Client. More...
 
bool isConnected ()
 Checks to see if the mqtt client is connected and returns true if it is. More...
 
void process ()
 The process method must be placed in the main loop in order to process MQTT events that are reported by the ESP-AT device. More...
 

Private Attributes

AT_Classat
 
subscription_cb_t subscription_cb
 
validDateTime_cb_t validDateTime_cb
 
mqtt_connectType_t connType
 
connected_cb_t connected_cb
 
int topicSubscriptions
 
bool connected
 
bool ntpTimeValid
 
char buff [MQTT_BUFFER_SIZE]
 

Detailed Description

EspAT MQTT EspATMQTT class definition.

Constructor & Destructor Documentation

◆ EspATMQTT()

EspATMQTT::EspATMQTT ( HardwareSerial *  serial = &ESP_SERIAL_PORT)

The module constructor allows you to select what serial port that should be used to communicate with the ESP-AT module.

Parameters
-serial The serial port that is connected to the ESP-AT module.

Member Function Documentation

◆ begin()

mqtt_status_t EspATMQTT::begin ( )

The begin method initializes the system before usage.

It must be called before running any other methods of this library.

Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ close()

mqtt_status_t EspATMQTT::close ( uint32_t  linkID)

Close (all) conection/s with the specified link ID.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ connect()

mqtt_status_t EspATMQTT::connect ( uint32_t  linkID,
const char *  host,
uint32_t  port = 1883,
uint32_t  reconnect = 0,
uint32_t  timeout = 5000,
connected_cb_t  cb = NULL 
)

Connects to the specified server/broker with the previously defined transport scheme.

If an active connection is established within the specified timeout it reports ESP_AT_SUB_CMD_CONN_SYNCH back but if a timeout occured before an active connection could be made it reports ESP_AT_SUB_CMD_CONN_ASYNCH and the caller needs to either check the connection with isConnected() or setup a callback function that will be called when the connection is made active

Tip: Specifying a very short timout (~50mS) will in most cases cause the method to return with ESP_AT_SUB_CMD_CONN_ASYNCH and a callback will later be called when the connection is established. This can be used to your advantage if you do not want to let the system hang while waiting for a connection to be made. As an example, connecting to AWS can take several seconds which would potentially lock your system all that time. One downside with this is that the calling application will need to keep track of the callback and possibly generate an error condition if it doesn't arrive within a specified time.
The later can be avoided by actually specifying a very large timeout, maybe 10 seconds or more, and try to force a synchronous connection. In that case a timeout condition can be detected when ESP_AT_SUB_CMD_CONN_ASYNCH is returned.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-host The host name of the MQTT broker. This can be specified as an IP address or a URL. Maximum length of this string is 128 bytes.
[in]-port The port where the broker will listen to requests. The default port is 1883 which is the default for a mosquitto server.
[in]-reconnect Used to tell the ESP-AT device to automaticall reconnect id a connection is lost.
  • 0 = Do not reconnect.
  • 1 = Automatically reconnect when a connection is lost.
[in]-timeout The caller can specify a connection timeout value here. The default timeout is 2 seconds.
The method will initially try to connect synchronously, i.e return with an active connection. If a timeout occurs during the connection process it will initialize a call back function (if specified) which is called by the process() command when a connection is established.
[in]-cb This is the callback function that shall be called by the process() method when a connection is made assuming the connect() method reported ESP_AT_SUB_CMD_CONN_ASYNCH back.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ connectionConfig()

mqtt_status_t EspATMQTT::connectionConfig ( uint32_t  linkID,
uint32_t  keepalive,
uint32_t  disable_clean_session,
const char *  lwt_topic,
const char *  lwt_message,
uint32_t  lwt_qos = 0,
uint32_t  lwt_retain = 0 
)

Sets the configuration of the current MQTT connection.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-keepalive Timeout of MQTT ping. Unit: second. Range [0,7200].
The default value is 0, which will be force-changed to 120 s.
[in]-disable_clean_session Sets the MQTT clean session propery.
For more details about this parameter we recommend reading the section Clean Session in MQTT Version 3.1.1.
  • 0: enable clean session.
  • 1: disable clean session.
[in]-lwt_topic Sets the topic of the last will and testament message. Maximum number of characters allowed for this topic is 128.
[in]-lwt_message Sets the last will and testament message. Maximum length of the message is 64 characters.
[in]-lwt_qos Sets the Quality of Service plan for the last will and testament message. Can be set to 0, 1 or and the default setting is 0.
[in]-lwt_retain Sets the retain parameter of the last will and testament message. Can be set to 0 or 1 and the default setting is 0.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ enableNTPTime()

mqtt_status_t EspATMQTT::enableNTPTime ( bool  enable,
validDateTime_cb_t  cb,
uint32_t  timezone,
const char *  ts1 = NULL,
const char *  ts2 = NULL,
const char *  ts3 = NULL 
)

Enables the internal NTP Time client.

Up to 3 different time servers can be specified to support quick multi regional time resolution. If no external time servers are specified on of the following time servers will be used instead:

  • “cn.ntp.org.cn”
  • “ntp.sjtu.edu.cn”
  • “us.pool.ntp.org”

When using a secure connection mechanism (TLS) the NTP client can be used to acquire the current date and time which is required by the TLS protocol. When the time has been acquired from a time server a call back is generated and the connection to the mqtt server can be made.

Parameters
[in]-enable Enable or disable the NTP client. A "0" in this parameter will disable the client completely and a "1" is required if the NTP client should be enabled.
[in]-cb A pointer to a callback method that is called when a valid date and time has been acquired from an NTP server. If this is NULL, no call back will be made and the caller has to examine the time to determine when a valid date/time has been acquired.
[in]-timezone This parameter support the following two formats:
  • Value range -12 to 14. It marks most of the time zones by offset from Coordinated Universal Time (UTC) in whole hours (UTC–12:00 to UTC+14:00).
  • The second format is UTC offset. The UTC offset specifies the time value you must add to the UTC time to get a local time value. It has a syntax like [+|-][hh]mm. This is negative if the local time zone is on the west of the Prime Meridian and positive if it is on the east. The hour(hh) must be between -12 and 14, and the minute(mm) between 0 and 59. For example, if you want to set the timezone to New Zealand (Chatham Islands) which is in UTC+12:45, you should set the parameter to 1245. Please refer to UTC offset wiki (https://en.wikipedia.org/wiki/Time_zone#List_of_UTC_offsets) for more information.
[in]-ts1 - ts3 Time server URL's, for instance "time.google.com" or "0.pool.ntp.org"
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ getNTPTime()

mqtt_status_t EspATMQTT::getNTPTime ( char **  time)

Get the current time from the ESP-AT internal NTP Client.

Parameters
[out]-time The current time as reported by the ESP-AT internal NTP client. If the NTP client has not been enabled an error will be returned. The time is reported back as a character string (An Example: "Tue Oct 19 17:47:56 2021") and the caller need to decode it.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ isConnected()

bool EspATMQTT::isConnected ( )

Checks to see if the mqtt client is connected and returns true if it is.

Returns
- true or false depending on the current connection status.

◆ process()

void EspATMQTT::process ( )

The process method must be placed in the main loop in order to process MQTT events that are reported by the ESP-AT device.

If not present the library will not function as expected.

◆ pubRaw() [1/2]

mqtt_status_t EspATMQTT::pubRaw ( uint32_t  linkID,
const char *  topic,
char *  data,
uint32_t  qos = 0,
uint32_t  retain = 0 
)

Publish raw data to a specified topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic where the message shold be published.
[in]-message The message that should be published to the specified topic. Must be a '\0' terminated string.
[in]-qos The Quality of Service value that should be used for this message.
The following values are recognized:
  • 0 - At most once:
    The minimal QoS level is zero. This service level guarantees a best-effort delivery. There is no guarantee of delivery. The recipient does not acknowledge receipt of the message and the message is not stored and re-transmitted by the sender. QoS level 0 is often called “fire and forget” and provides the same guarantee as the underlying TCP protocol.
  • 1 - At least once:
    QoS level 1 guarantees that a message is delivered at least one time to the receiver. The sender stores the message until it gets a PUBACK packet from the receiver that acknowledges receipt of the message. It is possible for a message to be sent or delivered multiple times.
  • 2 - Exactly once:
    QoS 2 is the highest level of service in MQTT. This level guarantees that each message is received only once by the intended recipients. QoS 2 is the safest and slowest quality of service level.
[in]-retain A retained message is a normal MQTT message with the retained flag set to true (= 1). The broker stores the last retained message and the corresponding QoS for that topic. See mqtt_retain_e for more details.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ pubRaw() [2/2]

mqtt_status_t EspATMQTT::pubRaw ( uint32_t  linkID,
const char *  topic,
const char *  data,
uint32_t  qos = 0,
uint32_t  retain = 0 
)

Publish raw data to a specified topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic where the message shold be published.
[in]-message The message that should be published to the specified topic. Must be a '\0' terminated string.
[in]-qos The Quality of Service value that should be used for this message.
The following values are recognized:
  • 0 - At most once:
    The minimal QoS level is zero. This service level guarantees a best-effort delivery. There is no guarantee of delivery. The recipient does not acknowledge receipt of the message and the message is not stored and re-transmitted by the sender. QoS level 0 is often called “fire and forget” and provides the same guarantee as the underlying TCP protocol.
  • 1 - At least once:
    QoS level 1 guarantees that a message is delivered at least one time to the receiver. The sender stores the message until it gets a PUBACK packet from the receiver that acknowledges receipt of the message. It is possible for a message to be sent or delivered multiple times.
  • 2 - Exactly once:
    QoS 2 is the highest level of service in MQTT. This level guarantees that each message is received only once by the intended recipients. QoS 2 is the safest and slowest quality of service level.
[in]-retain A retained message is a normal MQTT message with the retained flag set to true (= 1). The broker stores the last retained message and the corresponding QoS for that topic. See mqtt_retain_e for more details.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ pubString() [1/2]

mqtt_status_t EspATMQTT::pubString ( uint32_t  linkID,
const char *  topic,
char *  data,
uint32_t  qos = 0,
uint32_t  retain = 0 
)

Publish a string to a specified topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic where the message shold be published.
[in]-message The message that should be published to the specified topic.
[in]-qos The Quality of Service value that should be used for this message.
The following values are recognized:
  • 0 - At most once:
    The minimal QoS level is zero. This service level guarantees a best-effort delivery. There is no guarantee of delivery. The recipient does not acknowledge receipt of the message and the message is not stored and re-transmitted by the sender. QoS level 0 is often called “fire and forget” and provides the same guarantee as the underlying TCP protocol.
  • 1 - At least once:
    QoS level 1 guarantees that a message is delivered at least one time to the receiver. The sender stores the message until it gets a PUBACK packet from the receiver that acknowledges receipt of the message. It is possible for a message to be sent or delivered multiple times.
  • 2 - Exactly once:
    QoS 2 is the highest level of service in MQTT. This level guarantees that each message is received only once by the intended recipients. QoS 2 is the safest and slowest quality of service level.
[in]-retain A retained message is a normal MQTT message with the retained flag set to true (= 1). The broker stores the last retained message and the corresponding QoS for that topic. See mqtt_retain_e for more details.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ pubString() [2/2]

mqtt_status_t EspATMQTT::pubString ( uint32_t  linkID,
const char *  topic,
const char *  data,
uint32_t  qos = 0,
uint32_t  retain = 0 
)

Publish a string to a specified topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic where the message shold be published.
[in]-message The message that should be published to the specified topic.
[in]-qos The Quality of Service value that should be used for this message.
The following values are recognized:
  • 0 - At most once:
    The minimal QoS level is zero. This service level guarantees a best-effort delivery. There is no guarantee of delivery. The recipient does not acknowledge receipt of the message and the message is not stored and re-transmitted by the sender. QoS level 0 is often called “fire and forget” and provides the same guarantee as the underlying TCP protocol.
  • 1 - At least once:
    QoS level 1 guarantees that a message is delivered at least one time to the receiver. The sender stores the message until it gets a PUBACK packet from the receiver that acknowledges receipt of the message. It is possible for a message to be sent or delivered multiple times.
  • 2 - Exactly once:
    QoS 2 is the highest level of service in MQTT. This level guarantees that each message is received only once by the intended recipients. QoS 2 is the safest and slowest quality of service level.
[in]-retain A retained message is a normal MQTT message with the retained flag set to true (= 1). The broker stores the last retained message and the corresponding QoS for that topic. See mqtt_retain_e for more details.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ setALPN()

mqtt_status_t EspATMQTT::setALPN ( uint32_t  linkID,
const char *  alpn1 = NULL,
const char *  alpn2 = NULL,
const char *  alpn3 = NULL,
const char *  alpn4 = NULL,
const char *  alpn5 = NULL 
)

This function sets the ALPN (Application Layer Protocol Negotiation) of the link.

Up to 5 different protocols can be specified in one command. If no protocol is specified the ESP-AT stack will clear out all active ALPNs.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-alpn1-alpn5 ALPN specifier. For instance Amazon uses "x-amzn-mqtt-ca".
Other service providers will be using different protocol names and the user need to change this accordingly.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ setClientID() [1/2]

mqtt_status_t EspATMQTT::setClientID ( uint32_t  linkID,
char *  clientID 
)

Sets a new client ID for the connection.

This method must be called after performing a userConfig but before connecting to the broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-clientID A string that uniquely identifies the client to the broker. In the current version of the ESP-AT fw there is a limitation of 256 characters for the entire AT command which means that you can only have a clientID here of up to 236 characters.
If you need all 256 characters that is supported you need to set this in the userConfig command.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ setClientID() [2/2]

mqtt_status_t EspATMQTT::setClientID ( uint32_t  linkID,
const char *  clientID 
)

Sets a new client ID for the connection.

This method must be called after performing a userConfig but before connecting to the broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-clientID A string that uniquely identifies the client to the broker. In the current version of the ESP-AT fw there is a limitation of 256 characters for the entire AT command which means that you can only have a clientID here of up to 236 characters.
If you need all 256 characters that is supported you need to set this in the userConfig command.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ setPassword() [1/2]

mqtt_status_t EspATMQTT::setPassword ( uint32_t  linkID,
char *  password 
)

Sets the password used in authenticating the client with the broker.

This method must be called after performing a userConfig but before connecting to the broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-password A string that holds the password used for the authentication. In the current version of the ESP-AT fw there is a limitation of 256 characters for the entire AT command which means that you can only have a clientID here of up to 236 characters.
If you need all 256 characters that is supported you need to set this in the userConfig command.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ setPassword() [2/2]

mqtt_status_t EspATMQTT::setPassword ( uint32_t  linkID,
const char *  password 
)

Sets the password used in authenticating the client with the broker.

This method must be called after performing a userConfig but before connecting to the broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-password A string that holds the password used for the authentication. In the current version of the ESP-AT fw there is a limitation of 256 characters for the entire AT command which means that you can only have a clientID here of up to 236 characters.
If you need all 256 characters that is supported you need to set this in the userConfig command.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ setUsername() [1/2]

mqtt_status_t EspATMQTT::setUsername ( uint32_t  linkID,
char *  username 
)

Sets the username used in authenticating the client with the broker.

This method must be called after performing a userConfig but before connecting to the broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-username A string that holds the username used for the authentication. In the current version of the ESP-AT fw there is a limitation of 256 characters for the entire AT command which means that you can only have a clientID here of up to 236 characters.
If you need all 256 characters that is supported you need to set this in the userConfig command.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ setUsername() [2/2]

mqtt_status_t EspATMQTT::setUsername ( uint32_t  linkID,
const char *  username 
)

Sets the username used in authenticating the client with the broker.

This method must be called after performing a userConfig but before connecting to the broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-username A string that holds the username used for the authentication. In the current version of the ESP-AT fw there is a limitation of 256 characters for the entire AT command which means that you can only have a clientID here of up to 236 characters.
If you need all 256 characters that is supported you need to set this in the userConfig command.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ subscribeTopic() [1/2]

mqtt_status_t EspATMQTT::subscribeTopic ( subscription_cb_t  cb,
uint32_t  linkID,
char *  topic,
uint32_t  qos = 0 
)

Subscribe to messages from a specific topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic for which we are listening to.
[in]-qos The Quality of Service value that should be used for this message.
The following values are recognized:
  • 0 - At most once:
    The minimal QoS level is zero. This service level guarantees a best-effort delivery. There is no guarantee of delivery. The recipient does not acknowledge receipt of the message and the message is not stored and re-transmitted by the sender. QoS level 0 is often called “fire and forget” and provides the same guarantee as the underlying TCP protocol.
  • 1 - At least once:
    QoS level 1 guarantees that a message is delivered at least one time to the receiver. The sender stores the message until it gets a PUBACK packet from the receiver that acknowledges receipt of the message. It is possible for a message to be sent or delivered multiple times.
  • 2 - Exactly once:
    QoS 2 is the highest level of service in MQTT. This level guarantees that each message is received only once by the intended recipients. QoS 2 is the safest and slowest quality of service level.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ subscribeTopic() [2/2]

mqtt_status_t EspATMQTT::subscribeTopic ( subscription_cb_t  cb,
uint32_t  linkID,
const char *  topic,
uint32_t  qos = 0 
)

Subscribe to messages from a specific topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic for which we are listening to.
[in]-qos The Quality of Service value that should be used for this message.
The following values are recognized:
  • 0 - At most once:
    The minimal QoS level is zero. This service level guarantees a best-effort delivery. There is no guarantee of delivery. The recipient does not acknowledge receipt of the message and the message is not stored and re-transmitted by the sender. QoS level 0 is often called “fire and forget” and provides the same guarantee as the underlying TCP protocol.
  • 1 - At least once:
    QoS level 1 guarantees that a message is delivered at least one time to the receiver. The sender stores the message until it gets a PUBACK packet from the receiver that acknowledges receipt of the message. It is possible for a message to be sent or delivered multiple times.
  • 2 - Exactly once:
    QoS 2 is the highest level of service in MQTT. This level guarantees that each message is received only once by the intended recipients. QoS 2 is the safest and slowest quality of service level.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ unSubscribeTopic() [1/2]

mqtt_status_t EspATMQTT::unSubscribeTopic ( uint32_t  linkID,
char *  topic 
)

Unsubscribe from messages with a specific topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic that should be unsubscribed from.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ unSubscribeTopic() [2/2]

mqtt_status_t EspATMQTT::unSubscribeTopic ( uint32_t  linkID,
const char *  topic 
)

Unsubscribe from messages with a specific topic.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-topic The topic that should be unsubscribed from.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ userConfig() [1/3]

mqtt_status_t EspATMQTT::userConfig ( uint32_t  linkID,
mqtt_scheme_t  scheme,
char *  clientID,
char *  userName,
char *  password,
uint32_t  certKeyID = 0,
uint32_t  caID = 0,
const char *  path = "" 
)

Setup the connection scheme and how to connect to the server/broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-scheme Specifies what security scheme that ius used when connecting to the broker. See mqtt_scheme_e for more details.
[in]-clientID The client ID is a string identifier that uniquely identifies the client.
Maximum length is 256 characters.
[in]-userName The user name is used to login to the requested broker.
Maxmium length of this is 64 characters.
[in]-password The password is used to login to the requested broker.
Maxmium length of this is 64 characters.
[in]-certKeyID This is an index to the client certificate key. With the current ESP-AT firmware (V2.4.0.0) this only supports one key with index 0.
Future versions may support more than one client certificate so this can change and the API fully supports this.
[in]-caID This is an index to the CA root certificate. With the current ESP-AT firmware (V2.4.0.0) this only supports one key with index 0.
Future versions may support more than one client certificate so this can change and the API fully supports this.
[in]-path At this point we don't know exactly what this parameter is for. It might be a preparation to support cert/key/ca in the file system but ther is no information about this from Espressif.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ userConfig() [2/3]

mqtt_status_t EspATMQTT::userConfig ( uint32_t  linkID,
mqtt_scheme_t  scheme,
char *  clientID,
const char *  userName = "",
const char *  password = "",
uint32_t  certKeyID = 0,
uint32_t  caID = 0,
const char *  path = "" 
)

Setup the connection scheme and how to connect to the server/broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-scheme Specifies what security scheme that ius used when connecting to the broker. See mqtt_scheme_e for more details.
[in]-clientID The client ID is a string identifier that uniquely identifies the client.
Maximum length is 256 characters.
[in]-userName The user name is used to login to the requested broker.
Maxmium length of this is 64 characters.
[in]-password The password is used to login to the requested broker.
Maxmium length of this is 64 characters.
[in]-certKeyID This is an index to the client certificate key. With the current ESP-AT firmware (V2.4.0.0) this only supports one key with index 0.
Future versions may support more than one client certificate so this can change and the API fully supports this.
[in]-caID This is an index to the CA root certificate. With the current ESP-AT firmware (V2.4.0.0) this only supports one key with index 0.
Future versions may support more than one client certificate so this can change and the API fully supports this.
[in]-path At this point we don't know exactly what this parameter is for. It might be a preparation to support cert/key/ca in the file system but ther is no information about this from Espressif.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

◆ userConfig() [3/3]

mqtt_status_t EspATMQTT::userConfig ( uint32_t  linkID,
mqtt_scheme_t  scheme,
const char *  clientID,
const char *  userName = "",
const char *  password = "",
uint32_t  certKeyID = 0,
uint32_t  caID = 0,
const char *  path = "" 
)

Setup the connection scheme and how to connect to the server/broker.

Parameters
[in]-linkID The link ID used for this connection. Only linkID 0 is currently supported by the ESP-AT stack.
Using the library DEFAULT_LINK_ID will make it easy to migrate if this changes in the future.
[in]-scheme Specifies what security scheme that ius used when connecting to the broker. See mqtt_scheme_e for more details.
[in]-clientID The client ID is a string identifier that uniquely identifies the client.
Maximum length is 256 characters.
[in]-userName The user name is used to login to the requested broker.
Maxmium length of this is 64 characters.
[in]-password The password is used to login to the requested broker.
Maxmium length of this is 64 characters.
[in]-certKeyID This is an index to the client certificate key. With the current ESP-AT firmware (V2.4.0.0) this only supports one key with index 0.
Future versions may support more than one client certificate so this can change and the API fully supports this.
[in]-caID This is an index to the CA root certificate. With the current ESP-AT firmware (V2.4.0.0) this only supports one key with index 0.
Future versions may support more than one client certificate so this can change and the API fully supports this.
[in]-path At this point we don't know exactly what this parameter is for. It might be a preparation to support cert/key/ca in the file system but ther is no information about this from Espressif.
Returns
- The status of the operation, See mqtt_error_e and status_code_e for more information.

The documentation for this class was generated from the following files: