Cayenne MQTT API

group LWESP_APP_CAYENNE_API

MQTT client API for Cayenne.

Defines

LWESP_CAYENNE_API_VERSION: Cayenne API version in string.

LWESP_CAYENNE_HOST: Cayenne host server.

LWESP_CAYENNE_PORT: Cayenne port number.

LWESP_CAYENNE_BUFF_TX_LEN: MQTT default TX buffer len.

LWESP_CAYENNE_BUFF_RX_LEN: MQTT default RX buffer len.

LWESP_CAYENNE_BUFF_TX_COUNT: Size of TX messages queue size, waiting to be sent to server.

LWESP_CAYENNE_NO_CHANNEL: No channel macro

LWESP_CAYENNE_ALL_CHANNELS: All channels macro

Typedefs

typedef lwespr_t (*lwesp_cayenne_evt_fn)(struct lwesp_cayenne *c, lwesp_cayenne_evt_t *evt)

Cayenne event callback function.

Param c: [in] Cayenne handle
Param evt: [in] Event handle
Return: lwespOK on success, member of lwespr_t otherwise

Enums

enum lwesp_cayenne_topic_t

List of possible cayenne topics.

Values:

enumerator LWESP_CAYENNE_TOPIC_DATA: Data topic

enumerator LWESP_CAYENNE_TOPIC_COMMAND: Command topic

enumerator LWESP_CAYENNE_TOPIC_CONFIG

enumerator LWESP_CAYENNE_TOPIC_RESPONSE

enumerator LWESP_CAYENNE_TOPIC_SYS_MODEL

enumerator LWESP_CAYENNE_TOPIC_SYS_VERSION

enumerator LWESP_CAYENNE_TOPIC_SYS_CPU_MODEL

enumerator LWESP_CAYENNE_TOPIC_SYS_CPU_SPEED

enumerator LWESP_CAYENNE_TOPIC_DIGITAL

enumerator LWESP_CAYENNE_TOPIC_DIGITAL_COMMAND

enumerator LWESP_CAYENNE_TOPIC_DIGITAL_CONFIG

enumerator LWESP_CAYENNE_TOPIC_ANALOG

enumerator LWESP_CAYENNE_TOPIC_ANALOG_COMMAND

enumerator LWESP_CAYENNE_TOPIC_ANALOG_CONFIG

enumerator LWESP_CAYENNE_TOPIC_END: Last entry

enum lwesp_cayenne_resp_t

Cayenne response types.

Values:

enumerator LWESP_CAYENNE_RESP_OK: Response OK

enumerator LWESP_CAYENNE_RESP_ERROR: Response error

enum lwesp_cayenne_evt_type_t

Cayenne events.

Values:

enumerator LWESP_CAYENNE_EVT_CONNECT: Connect to Cayenne event

enumerator LWESP_CAYENNE_EVT_DISCONNECT: Disconnect from Cayenne event

enumerator LWESP_CAYENNE_EVT_DATA: Data received event

enum lwesp_cayenne_data_type_unit_t

Values:

enumerator LWESP_CAYENNE_DATA_TYPE_END_UNIT_END: Final end value

enum lwesp_cayenne_data_format_t

List of different data types, used for library purpose to store data values, before these are uploaded to cayenne cloud.

Values:

enumerator LWESP_CAYENNE_DATA_FORMAT_UINT32: Unsigned integer data type, 32-bit width

enumerator LWESP_CAYENNE_DATA_FORMAT_INT32: Integer data type, 32-bit width

enumerator LWESP_CAYENNE_DATA_FORMAT_FLOAT: Float data type

enumerator LWESP_CAYENNE_DATA_FORMAT_DOUBLE: Double data type

enumerator LWESP_CAYENNE_DATA_FORMAT_STRING: Double data type

enumerator LWESP_CAYENNE_DATA_FORMAT_END: End value indicator

Functions

lwespr_t lwesp_cayenne_init(void)

Initialize cayenne module. Call this only once in the application lifetime.

Returns: lwespOK on success, member of lwespr_t otherwise

lwespr_t lwesp_cayenne_create(lwesp_cayenne_t *c, const lwesp_mqtt_client_info_t *client_info, lwesp_cayenne_evt_fn evt_fn)

Create new instance of cayenne MQTT connection.

Note

Each call to this functions starts new thread for async receive processing. Function will block until thread is created and successfully started

Parameters

c – [in] Cayenne handle object
client_info – [in] MQTT client info with username, password and client ID. This is used for read-only purpose and can be reused by different clients
evt_fn – [in] Event function to send information to user upon different activity

Returns

lwespOK on success, member of lwespr_t otherwise

lwespr_t lwesp_cayenne_connect(lwesp_cayenne_t *c)

Try to connect to Cayenne server over asynchronous MQTT module Function does not block until connected, rather it only starts the connection to server.

Parameters: c – [in] Cayenne handle object
Returns: lwespOK on success, member of lwespr_t otherwise

lwespr_t lwesp_cayenne_publish_ex(lwesp_cayenne_t *c, const lwesp_cayenne_tx_msg_t *tx_msg)

Publish data to Cayenne cloud (extended mode), with sensor info or actuator data. It writes data to TX message buffer and later tries to start transmission from it. If transmission is not succesful, it will re-try from the poll event.

Parameters

c – [in] Cayenne handle object
tx_msg – [in] Pointer to data object to transmit

Returns

lwespOK on success, member of lwespr_t otherwise

lwespr_t lwesp_cayenne_publish_response(lwesp_cayenne_t *c, lwesp_cayenne_msg_t *msg, lwesp_cayenne_resp_t resp, const char *message)

Publish response message to command received from cloud.

Parameters

c – [in] Cayenne handle
msg – [in] Received message with command topic
resp – [in] Response type, either OK or ERROR. Member of lwesp_cayenne_resp_t enumeration
message – [in] Message text in case of error to be displayed to Cayenne dashboard

Returns

lwespOK on success, member of lwespr_t otherwise

struct lwesp_cayenne_key_value_t

#include <lwesp_cayenne.h>

Key/Value pair structure.

Public Members

const char *key: Key string

size_t key_len: Length of key string in units of bytes

const char *value: Value string

size_t value_len: Length of value string in units of bytes

struct lwesp_cayenne_tx_msg_t

#include <lwesp_cayenne.h>

TX message structure to be sent to cloud.

Public Members

lwesp_cayenne_topic_t topic: Topic to publish to

uint16_t channel: Channel to publish to

lwesp_cayenne_data_type_unit_t data_type_unit: Data unit and its respective type for Cayenne dashboard. It provides necessary value type (light, temperature, sensor, switch, etc) and its respective value type (celsius, percentage, …). This is used to automatically detect widget type on Cayenne dashboard. Set it to LWESP_CAYENNE_DATA_TYPE_END_UNIT_END to send plain text from data field

lwesp_cayenne_data_format_t data_format: Data format used for union data storage. It is used for library internal-purpose only and defines used data union member to use as valid data unit

uint32_t u32: Unsigned 32-bit integer type, used with LWESP_CAYENNE_DATA_FORMAT_UINT32 format

int32_t i32: Signed 32-bit integer type, used with LWESP_CAYENNE_DATA_FORMAT_INT32 format

float flt: Single-precision floating point type, used with LWESP_CAYENNE_DATA_FORMAT_FLOAT format

double dbl: Double-precision floating point type, used with LWESP_CAYENNE_DATA_FORMAT_DOUBLE format

const char *str: String data type. It is only a pointer to string and does not provide any storage, used with LWESP_CAYENNE_DATA_FORMAT_STRING format

union lwesp_cayenne_tx_msg_t::[anonymous] data: Data union structure

struct lwesp_cayenne_msg_t

#include <lwesp_cayenne.h>

Cayenne RX message structure.

Public Members

lwesp_cayenne_topic_t topic: Topic used for the received message

uint16_t channel: Message channel, optional, based on topic type

const char *seq: Random sequence string when RX message is command from server. Used to be able to send effective reply back to server

lwesp_cayenne_key_value_t values[2]: Key/Value pair of values

size_t values_count: Count of valid pairs in values member

struct lwesp_cayenne_evt_t

#include <lwesp_cayenne.h>

Cayenne event.

Public Members

lwesp_cayenne_evt_type_t type: Event type

lwesp_cayenne_msg_t *msg: Pointer to data message

struct lwesp_cayenne_evt_t::[anonymous]::[anonymous] data: Data event, used with LWESP_CAYENNE_EVT_DATA event

union lwesp_cayenne_evt_t::[anonymous] evt: Event union

struct lwesp_cayenne_t

#include <lwesp_cayenne.h>

Cayenne handle.

Public Members

struct lwesp_cayenne *next: Next object on a list

lwesp_mqtt_client_p mqtt_client: MQTT client object

const lwesp_mqtt_client_info_t *info_c: MQTT client info structure

lwesp_cayenne_msg_t msg: Received data message currently being processed

size_t client_buff_tx_len: MQTT client raw buffer length for TX data. Set to LWESP_CAYENNE_BUFF_TX_LEN if not defined by user

size_t client_buff_rx_len: MQTT client raw buffer length for RX data. Set to LWESP_CAYENNE_BUFF_RX_LEN if not defined by user

lwesp_buff_t tx_buff: TX data buffer handle

size_t tx_buff_count: Size of queue for TX messages. Set to LWESP_CAYENNE_BUFF_TX_COUNT if not defined by user

lwesp_cayenne_evt_t evt: Event handle object

lwesp_cayenne_evt_fn evt_fn: Event callback function