Demo application for using the AT&T IoT Starter Kit Powered by AWS.
Dependencies: SDFileSystem
Fork of ATT_AWS_IoT_demo by
IoT Starter Kit Powered by AWS Demo
This program demonstrates the AT&T IoT Starter Kit sending data directly into AWS IoT. It's explained and used in the Getting Started with the IoT Starter Kit Powered by AWS on starterkit.att.com.
What's required
- AT&T IoT LTE Add-on (also known as the Cellular Shield)
- NXP K64F - for programming
- microSD card - used to store your AWS security credentials
- AWS account
- Python, locally installed
If you don't already have an IoT Starter Kit, you can purchase a kit here. The IoT Starter Kit Powered by AWS includes the LTE cellular shield, K64F, and a microSD card.
Diff: AWS_openssl/aws_iot_src/protocol/mqtt/aws_iot_mqtt_interface.h
- Revision:
- 15:6f2798e45099
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/AWS_openssl/aws_iot_src/protocol/mqtt/aws_iot_mqtt_interface.h Thu Dec 01 18:05:38 2016 +0000 @@ -0,0 +1,328 @@ +/* + * Copyright 2010-2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * @file aws_iot_mqtt_interface.h + * @brief Interface definition for MQTT client. + */ + +#ifndef AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_ +#define AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_ + +#include "stddef.h" +#include "stdbool.h" +#include "stdint.h" +#include "aws_iot_error.h" + +/** + * @brief MQTT Version Type + * + * Defining an MQTT version type. + * + */ +typedef enum { + MQTT_3_1 = 3, ///< MQTT 3.1 (protocol message byte = 3) + MQTT_3_1_1 = 4 ///< MQTT 3.1.1 (protocol message byte = 4) +} MQTT_Ver_t; + +/** + * @brief Quality of Service Type + * + * Defining a QoS type. + * @note QoS 2 is \b NOT supported by the AWS IoT Service at the time of this SDK release. + * + */ +typedef enum { + QOS_0, ///< QoS 0 = at most once delivery + QOS_1, ///< QoS 1 = at least once delivery + QOS_2 ///< QoS 2 is NOT supported +} QoSLevel; + +/** + * @brief Last Will and Testament Definition + * + * Defining a type for LWT parameters. + * @note Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release. + * + */ +typedef struct { + const char *pTopicName; ///< LWT Topic + const char *pMessage; ///< Message to be delivered as LWT + bool isRetained; ///< NOT supported + QoSLevel qos; ///< QoS of LWT message +} MQTTwillOptions; +extern const MQTTwillOptions MQTTwillOptionsDefault; + +/** + * @brief Disconnect Callback Handler Type + * + * Defining a TYPE for definition of disconnect callback function pointers. + * + */ +typedef void (*iot_disconnect_handler)(void); + +/** + * @brief MQTT Connection Parameters + * + * Defining a type for MQTT connection parameters. Passed into client when establishing a connection. + * + */ +typedef struct { + uint8_t enableAutoReconnect; ///< Set to true to enable auto reconnect + char *pHostURL; ///< Pointer to a string defining the endpoint for the MQTT service + uint16_t port; ///< MQTT service listening port + char *pRootCALocation; ///< Pointer to a string defining the Root CA file (full file, not path) + char *pDeviceCertLocation; ///< Pointer to a string defining the device identity certificate file (full file, not path) + char *pDevicePrivateKeyLocation; ///< Pointer to a string defining the device private key file (full file, not path) + char *pClientID; ///< Pointer to a string defining the MQTT client ID (this needs to be unique \b per \b device across your AWS account) + char *pUserName; ///< Not used in the AWS IoT Service + char *pPassword; ///< Not used in the AWS IoT Service + MQTT_Ver_t MQTTVersion; ///< Desired MQTT version used during connection + uint16_t KeepAliveInterval_sec; ///< MQTT keep alive interval in seconds. Defines inactivity time allowed before determining the connection has been lost. + bool isCleansession; ///< MQTT clean session. True = this session is to be treated as clean. Previous server state is cleared and no stated is retained from this connection. + bool isWillMsgPresent; ///< Is there a LWT associated with this connection? + MQTTwillOptions will; ///< MQTT LWT parameters. + uint32_t mqttCommandTimeout_ms; ///< Timeout for MQTT blocking calls. In milliseconds. + uint32_t tlsHandshakeTimeout_ms; ///< TLS handshake timeout. In milliseconds. + bool isSSLHostnameVerify; ///< Client should perform server certificate hostname validation. + iot_disconnect_handler disconnectHandler; ///< Callback to be invoked upon connection loss. +} MQTTConnectParams; +extern const MQTTConnectParams MQTTConnectParamsDefault; + +/** + * @brief MQTT Message Parameters + * + * Defines a type for properties of MQTT messages including topic, payload an QoS. + * + */ +typedef struct { + QoSLevel qos; ///< Message Quality of Service + bool isRetained; ///< Retained messages are \b NOT supported by the AWS IoT Service at the time of this SDK release. + bool isDuplicate; ///< Is this message a duplicate QoS > 0 message? Handled automatically by the MQTT client. + uint16_t id; ///< Message sequence identifier. Handled automatically by the MQTT client. + void *pPayload; ///< Pointer to MQTT message payload (bytes). + uint32_t PayloadLen; ///< Length of MQTT payload. +} MQTTMessageParams; +extern const MQTTMessageParams MQTTMessageParamsDefault; +/** + * @brief MQTT Callback Function Parameters + * + * Defines a type for parameters returned to the user upon receipt of a publish message on a subscribed topic. + * + */ +typedef struct { + char *pTopicName; ///< Pointer to the topic string on which the message was delivered. In the case of a wildcard subscription this is the actual topic, not the wildcard filter. + uint16_t TopicNameLen; ///< Length of the topic string. + MQTTMessageParams MessageParams; ///< Message parameters structure. +} MQTTCallbackParams; +extern const MQTTCallbackParams MQTTCallbackParamsDefault; + +/** + * @brief MQTT Callback Function + * + * Defines a type for the function pointer which stores the message callback function. + * A pointer to the desired callback function to be invoked upon receipt of a message on a subscribed toipc. + * Supplied upon subscribing to a topic. + * + */ +typedef int32_t (*iot_message_handler)(MQTTCallbackParams params); + +/** + * @brief MQTT Subscription Parameters + * + * Defines the parameters needed when subscribing to an MQTT topic. + * + */ +typedef struct { + char *pTopic; ///< Pointer to the string defining the desired subscription topic. + QoSLevel qos; ///< Quality of service of the subscription. + iot_message_handler mHandler; ///< Callback to be invoked upon receipt of a message on the subscribed topic. +} MQTTSubscribeParams; +extern const MQTTSubscribeParams MQTTSubscribeParamsDefault; + +/** + * @brief MQTT Publish Parameters + * + * Defines a type for parameters supplied when publishing an MQTT message. + * + */ +typedef struct { + char *pTopic; ///< Pointer to the string defining the desired publishing topic. + MQTTMessageParams MessageParams; ///< Parameters defining the message to be published. +} MQTTPublishParams; +extern const MQTTPublishParams MQTTPublishParamsDefault; + +/** + * @brief MQTT Connection Function + * + * Called to establish an MQTT connection with the AWS IoT Service + * + * @param pParams Pointer to MQTT connection parameters + * @return An IoT Error Type defining successful/failed connection + */ +IoT_Error_t aws_iot_mqtt_connect(MQTTConnectParams *pParams); + +/** + * @brief Publish an MQTT message on a topic + * + * Called to publish an MQTT message on a topic. + * @note Call is blocking. In the case of a QoS 0 message the function returns + * after the message was successfully passed to the TLS layer. In the case of QoS 1 + * the function returns after the receipt of the PUBACK control packet. + * + * @param pParams Pointer to MQTT publish parameters + * @return An IoT Error Type defining successful/failed publish + */ +IoT_Error_t aws_iot_mqtt_publish(MQTTPublishParams *pParams); + +/** + * @brief Subscribe to an MQTT topic. + * + * Called to send a subscribe message to the broker requesting a subscription + * to an MQTT topic. + * @note Call is blocking. The call returns after the receipt of the SUBACK control packet. + * + * @param pParams Pointer to MQTT subscribe parameters + * @return An IoT Error Type defining successful/failed subscription + */ +IoT_Error_t aws_iot_mqtt_subscribe(MQTTSubscribeParams *pParams); + +/** + * @brief Unsubscribe to an MQTT topic. + * + * Called to send an usubscribe message to the broker requesting removal of a subscription + * to an MQTT topic. + * @note Call is blocking. The call returns after the receipt of the UNSUBACK control packet. + * + * @param pTopic Pointer to the requested topic string. Ensure the string is null terminated + * @return An IoT Error Type defining successful/failed unsubscription + */ +IoT_Error_t aws_iot_mqtt_unsubscribe(char *pTopic); + +/** + * @brief MQTT Manual Re-Connection Function + * + * Called to establish an MQTT connection with the AWS IoT Service + * using parameters from the last time a connection was attempted + * Use after disconnect to start the reconnect process manually + * Makes only one reconnect attempt + * + * @return An IoT Error Type defining successful/failed connection + */ +IoT_Error_t aws_iot_mqtt_attempt_reconnect(void); + +/** + * @brief Disconnect an MQTT Connection + * + * Called to send a disconnect message to the broker. + * + * @return An IoT Error Type defining successful/failed send of the disconnect control packet. + */ +IoT_Error_t aws_iot_mqtt_disconnect(void); + +/** + * @brief Yield to the MQTT client + * + * Called to yield the current thread to the underlying MQTT client. This time is used by + * the MQTT client to manage PING requests to monitor the health of the TCP connection as + * well as periodically check the socket receive buffer for subscribe messages. Yield() + * must be called at a rate faster than the keepalive interval. It must also be called + * at a rate faster than the incoming message rate as this is the only way the client receives + * processing time to manage incoming messages. + * + * @param timeout Maximum number of milliseconds to pass thread execution to the client. + * @return An IoT Error Type defining successful/failed client processing. + * If this call results in an error it is likely the MQTT connection has dropped. + * iot_is_mqtt_connected can be called to confirm. + */ +IoT_Error_t aws_iot_mqtt_yield(int timeout); + +/** + * @brief Is the MQTT client currently connected? + * + * Called to determine if the MQTT client is currently connected. Used to support logic + * in the device application around reconnecting and managing offline state. + * + * @return true = connected, false = not currently connected + */ +bool aws_iot_is_mqtt_connected(void); + +/** + * @brief Is the MQTT client set to reconnect automatically? + * + * Called to determine if the MQTT client is set to reconnect automatically. + * Used to support logic in the device application around reconnecting + * + * @return true = enabled, false = disabled + */ +bool aws_iot_is_autoreconnect_enabled(void); + +/** + * @brief Enable or Disable AutoReconnect on Network Disconnect + * + * Called to enable or disabled the auto reconnect features provided with the SDK + * + * @param value set to true for enabling and false for disabling + * + * @return IoT_Error_t Type defining successful/failed API call + */ +IoT_Error_t aws_iot_mqtt_autoreconnect_set_status(bool value); + +typedef IoT_Error_t (*pConnectFunc_t)(MQTTConnectParams *pParams); +typedef IoT_Error_t (*pPublishFunc_t)(MQTTPublishParams *pParams); +typedef IoT_Error_t (*pSubscribeFunc_t)(MQTTSubscribeParams *pParams); +typedef IoT_Error_t (*pUnsubscribeFunc_t)(char *pTopic); +typedef IoT_Error_t (*pDisconnectFunc_t)(void); +typedef IoT_Error_t (*pYieldFunc_t)(int timeout); +typedef bool (*pIsConnectedFunc_t)(void); +typedef bool (*pIsAutoReconnectEnabledFunc_t)(void); +typedef IoT_Error_t (*pReconnectFunc_t)(); +typedef IoT_Error_t (*pSetAutoReconnectStatusFunc_t)(bool); +/** + * @brief MQTT Client Type Definition + * + * Defines a structure of function pointers, each implementing a corresponding iot_mqtt_* + * function. In this way any MQTT client which implements the iot_mqtt_* interface + * can be swapped in under the MQTT/Shadow layer. + * + */ +typedef struct{ + pConnectFunc_t connect; ///< function implementing the iot_mqtt_connect function + pPublishFunc_t publish; ///< function implementing the iot_mqtt_publish function + pSubscribeFunc_t subscribe; ///< function implementing the iot_mqtt_subscribe function + pUnsubscribeFunc_t unsubscribe; ///< function implementing the iot_mqtt_unsubscribe function + pDisconnectFunc_t disconnect; ///< function implementing the iot_mqtt_disconnect function + pYieldFunc_t yield; ///< function implementing the iot_mqtt_yield function + pIsConnectedFunc_t isConnected; ///< function implementing the iot_is_mqtt_connected function + pReconnectFunc_t reconnect; ///< function implementing the iot_mqtt_reconnect function + pIsAutoReconnectEnabledFunc_t isAutoReconnectEnabled; ///< function implementing the iot_is_autoreconnect_enabled function + pSetAutoReconnectStatusFunc_t setAutoReconnectStatus; ///< function implementing the iot_mqtt_autoreconnect_set_status function +}MQTTClient_t; + + +/** + * @brief Set the MQTT client + * + * This function provides a way to pass in an MQTT client implementation to the + * AWS IoT MQTT wrapper layer. This is done through function pointers to the + * interface functions. + * + */ +void aws_iot_mqtt_init(MQTTClient_t *pClient); + + +#endif /* AWS_IOT_SDK_SRC_IOT_MQTT_INTERFACE_H_ */ + +