1 /** 2 ***************************************************************************************** 3 * 4 * @file ags.h 5 * 6 * @brief Alexa Gadgets Service API. 7 * 8 ***************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 ***************************************************************************************** 36 */ 37 38 /** 39 * @addtogroup BLE_SRV BLE Services 40 * @{ 41 * @brief Definitions and prototypes for the BLE Service interface. 42 */ 43 44 /** 45 * @defgroup BLE_SDK_AGS Alexa Gadget Service (AGS) 46 * @{ 47 * @brief Definitions and prototypes for the AGS interface. 48 * 49 * @details The Alexa Gadget (AG) Service is defined by Amazon. It can connect a Alexa gadget with an Echo 50 * device. This module implements the Alexa Gadget Service with TX and RX characteristics. 51 * 52 * After \ref ags_init_t variable is initialized, the application must call \ref ags_service_init() 53 * to add the Alexa Gadget Service and TX, RX characteristics to the BLE Stack database according to 54 * \ref ags_init_t.char_mask. 55 */ 56 57 #ifndef __AGS_H__ 58 #define __AGS_H__ 59 60 #include <stdint.h> 61 #include <stdbool.h> 62 #include "gr55xx_sys.h" 63 #include "custom_config.h" 64 65 /** 66 * @defgroup AGS_MACRO Defines 67 * @{ 68 */ 69 /**< The UUID of Alexa Gadget Service for setting advertising data. */ 70 #define AGS_SERVICE_UUID 0xFB, 0x34, 0x9B, 0x5F, 0x80, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, 0x00, \ 71 0x03, 0xFE, 0x00, 0x00 72 73 #define AGS_HEADER_FIRST_RES 0x00 /**< Reserved value of header in the first packet. */ 74 75 #define AGS_HEADER_ACK_RES_1 0x00 /**< The first reserved value of header in the ACK packet. */ 76 #define AGS_HEADER_ACK_PAYLOAD_LEN 0x02 /**< Length of the ACK packet, in bytes. */ 77 #define AGS_HEADER_ACK_RES_2 0x01 /**< The second reserved value of header in the ACK packet. */ 78 79 #define AGS_TX_VAL_LEN_MAX 244 /**< Maximum length of TX Characteristic value. */ 80 #define AGS_RX_VAL_LEN_MAX 244 /**< Maximum length of RX Characteristic value. */ 81 82 /** 83 * @defgroup AGS_ADV_TYPE Advertising type 84 * @{ 85 * @brief The advertisiment type. 86 * Bit 0 : Pairing or reconnection mode, 0 - reconnection mode, 1 - pairing mode; 87 * Bit 1 : Classic Bluetooth discoverability; 88 * Bit 2~7 : Reserved for future use, set to 0x00. 89 */ 90 #define AGS_PAIR_ADV_FLAG 0x01 /**< The Pairing advertisiment flag. */ 91 #define AGS_RECONNECT_ADV_FLAG 0x00 /**< The reconnecting advertisiment flag. */ 92 /** @} */ 93 94 #define AGS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 95 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of AGS connections. */ 96 97 /** 98 * @defgroup AGS_CHAR_MASK Characteristics Mask 99 * @{ 100 * @brief Bit masks for the initialization of \ref ags_init_t.char_mask. 101 */ 102 #define AGS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in AGS. */ 103 #define AGS_CHAR_FULL 0x003f /**< Bit mask of the full characteristic. */ 104 /** @} */ 105 /** @} */ 106 107 /** 108 * @defgroup AGS_ENUM Enumerations 109 * @{ 110 */ 111 /**@brief Alexa Gadget Service Stream ID. 112 * At any time, there is only one control stream, one Alexa stream, and one OTA stream. 113 * Each packet belongs to one of these streams, which is specified in the stream ID field of the packet's header. 114 * See Gadgets documentation for details: 115 * https://developer.amazon.com/en-US/docs/alexa/alexa-gadgets-toolkit/packet-ble.html#streams 116 */ 117 typedef enum { 118 AGS_CONTROL_STREAM_ID, /**< Control stream ID, used to communicate. */ 119 AGS_ALEXA_STREAM_ID = 0x06, /**< Alexa stream ID, used to send directives and events. */ 120 AGS_OTA_STREAM_ID = 0x02, /**< OTA stream ID, used to update the gadget's firmware. */ 121 } ags_header_stream_id_t; 122 123 /**@brief Alexa Gadget Service transaction type. 124 * It indicate where the packet is within the transaction. The transaction type and 125 * protocol of a single transaction are defined by the first packet of the transaction. 126 */ 127 typedef enum { 128 AGS_TRANSACTION_TYPE_FIRST, /**< First packet of a transaction, 129 or the only packet in a single-packet transaction. */ 130 AGS_TRANSACTION_TYPE_CONT, /**< Continuation packet of a transaction. */ 131 AGS_TRANSACTION_TYPE_LAST, /**< Last packet of a transaction. */ 132 AGS_TRANSACTION_TYPE_CTRL, /**< Control packet. Currently, \ 133 the only type of control packet is the ACK packet. */ 134 } ags_header_trxn_type_t; 135 136 /**@brief Alexa Gadget Service ACK Flag. 137 */ 138 typedef enum { 139 AGS_ACK_NACK, /**< The gadget doesn't need to send an ACK packet in response to the last packet of the 140 transaction unless another packet in the transaction has this bit set to 1. */ 141 AGS_ACK_ACK, /**< The gadget must send an ACK packet in response to the last packet of the transaction. */ 142 } ags_header_ack_flag_t; 143 144 /**@brief Alexa Gadget Service Length extender. 145 */ 146 typedef enum { 147 AGS_LEN_EXT_NO_EXT, /**< The packet's payload is 8 bits. */ 148 AGS_LEN_EXT_EXT, /**< The packet's payload is 16 bits. */ 149 } ags_header_length_ext_t; 150 151 /**@brief Alexa Gadget Service result code. 152 */ 153 typedef enum { 154 AGS_RES_CODE_SUCCESS, /**< The message was valid and acted on (if applicable) successfully. */ 155 AGS_RES_CODE_UNKNOWN, /**< The message was valid but rusulted in a failure or error. */ 156 AGS_RES_CODE_UNSUPPORTED = 0x03, /**< The message was invalid because it contained a command or other field that 157 was not supported by the receiver. */ 158 } ags_header_result_code_t; 159 160 /**@brief Alexa Gadget Service event type.*/ 161 typedef enum { 162 AGS_EVT_INVALID, /**< Indicate that invalid event. */ 163 AGS_EVT_ECHO_RX_DATA_SENT, /**< Indicate that the gadget has been sent the data to an Echo device. */ 164 AGS_EVT_ECHO_TX_DATA_RECEIVED, /**< Indicate that the gadget has been received the data from an Echo device. */ 165 AGS_EVT_ECHO_RX_NOTI_ENABLE, /**< Indicate that the Rx notification has been enabled. */ 166 AGS_EVT_ECHO_RX_NOTI_DISABLE, /**< Indicate that the Rx notification has been disabled. */ 167 } ags_evt_type_t; 168 /** @} */ 169 170 /** 171 * @defgroup AGS_STRUCT Structures 172 * @{ 173 */ 174 /**@brief Alexa Gadget Service base part of data packet header. */ 175 typedef struct { 176 uint8_t trxn_id : 4; /**< The transaction ID. */ 177 uint8_t stream_id : 4; /**< The stream ID. @ref ags_header_stream_id_t */ 178 uint8_t length_ext : 1; /**< Length extender. It indicates the length of the payload field. \ 179 @ref ags_header_length_ext_t */ 180 uint8_t ack_flag : 1; /**< Acknowledgement(ACK) flag. @ref ags_header_ack_flag_t */ 181 uint8_t trxn_type : 2; /**< Transaction type. @ref ags_header_trxn_type_t */ 182 uint8_t sequ_num : 4; /**< Sequence number. Since this is four bits long, it supports 183 inplace sequencing of up to 16 packet at a given point in time. 184 Sequence numbers can rool over. */ 185 } ags_header_base_t; 186 187 /**@brief Alexa Gadget Service header in first packet. */ 188 typedef struct { 189 ags_header_base_t header_base; /**< Header base. */ 190 uint8_t reserved; /**< Reserved. This is only present in the first packet of the transaction. */ 191 uint8_t 192 total_trxn_length[2]; /**< Total transaction length. This is only present in the first packet of the transaction. */ 193 uint8_t payload_length; /**< Payload Length. */ 194 } ags_header_first_t; 195 196 /**@brief Alexa Gadget Service extended version of header in first packet. */ 197 typedef struct { 198 ags_header_base_t header_base; /**< Header base. */ 199 uint8_t reserved; /**< Reserved. This is only present in the first packet of the transaction. */ 200 uint8_t 201 total_trxn_length[2]; /**< Total transaction length. This is only present in the first packet of the transaction. */ 202 uint8_t payload_length[2]; /**< Payload Length. */ 203 } ags_header_first_ext_t; 204 205 /**@brief Alexa Gadget Service header in subsequent packets. */ 206 typedef struct { 207 ags_header_base_t header_base; /**< Header base. */ 208 uint8_t payload_length; /**< Payload Length. */ 209 } ags_header_subs_t; 210 211 /**@brief Alexa Gadget Service extended version of header in subsequent packets. */ 212 typedef struct { 213 ags_header_base_t header_base; /**< Header base. */ 214 uint8_t payload_length[2]; /**< Payload Length. */ 215 } ags_header_subs_ext_t; 216 217 /**@brief Alexa Gadget Service ACK packet. */ 218 typedef struct { 219 ags_header_base_t header_base; /**< Header base. */ 220 uint8_t reserved_1; /**< Reserved. */ 221 uint8_t payload_length; /**< Length of the ACK packet. */ 222 uint8_t reserved_2; /**< Reserved. */ 223 uint8_t 224 result_code; /**< A result code, which depends on whether this is an ACK or a NACK. @ref ags_header_ack_flag_t */ 225 } ags_ack_packet_t; 226 227 /**@brief Alexa Gadget Service gadget stream enviorenment variable. */ 228 typedef struct { 229 ags_header_stream_id_t stream_id; /**< The stream ID. */ 230 uint8_t is_active; /**< Whether the stream is active. */ 231 uint8_t ack_flag; /**< Whether need to return ACK packet. */ 232 uint8_t trxn_id; /**< The transaction ID of the packet that requested the ACK packet. */ 233 uint16_t total_length; /**< Total stream length. */ 234 uint16_t received_length; /**< Received stream length. */ 235 } ags_stream_env_t; 236 237 /**@brief Alexa Gadget Service event. */ 238 typedef struct { 239 ags_evt_type_t evt_type; /**< The AGS event type. */ 240 uint8_t conn_idx; /**< The index of the connection. */ 241 const uint8_t *p_data; /**< Pointer to event data. */ 242 uint16_t length; /**< Length of event data. */ 243 } ags_evt_t; 244 /** @} */ 245 246 /** 247 * @defgroup AGS_TYPEDEF Typedefs 248 * @{ 249 */ 250 /**@brief Alexa Gadget Service event handler type.*/ 251 typedef void (*ags_evt_handler_t)(ags_evt_t *p_evt); 252 253 /**@brief Alexa Gadget Service stream callback.*/ 254 typedef bool (*ags_stream_cb_t)(uint8_t conn_idx, const uint8_t *const p_data, uint16_t length, 255 uint8_t still_receiving); 256 /** @} */ 257 258 /** 259 * @defgroup AGS_STRUCT Structures 260 * @{ 261 */ 262 /**@brief Alexa Gadget Service init stucture. 263 * This contains all option and data needed for initialization of the service. */ 264 typedef struct { 265 ags_evt_handler_t evt_handler; /**< Alexa Gadget Service event handler. */ 266 ags_stream_cb_t ags_control_stream_cb; /**< Callback for incoming control streams. */ 267 ags_stream_cb_t ags_alexa_stream_cb; /**< Callback for incoming Alexa streams. */ 268 uint16_t 269 char_mask; /**< Initial mask of supported characteristics, and configured with \ref AGS_CHAR_MASK. */ 270 } ags_init_t; 271 /** @} */ 272 273 /** 274 * @defgroup AGS_FUNCTION Functions 275 * @{ 276 */ 277 /** 278 ***************************************************************************************** 279 * @brief Initialize a Alexa Gadget Service instance and add in the DB. 280 * 281 * @param[in] p_ags_init: Pointer to ags_init_t Service initialization variable 282 * 283 * @return Result of service initialization. 284 ***************************************************************************************** 285 */ 286 sdk_err_t ags_service_init(ags_init_t *p_ags_init); 287 288 /** 289 ***************************************************************************************** 290 * @brief Send data to the Echo device in stream format. 291 * 292 * @param[in] conn_idx: Connnection index. 293 * @param[in] stream_id: Stream ID, @ref ags_header_stream_id_t. 294 * @param[in] p_data: Pointer to the data to be sent. 295 * @param[in] length: Length of data. 296 * 297 * @return Result of sending data. 298 ***************************************************************************************** 299 */ 300 sdk_err_t ags_stream_send(uint8_t conn_idx, uint8_t stream_id, uint8_t *p_data, uint16_t length); 301 302 /** 303 ***************************************************************************************** 304 * @brief Send data to the Echo device in non-stream format. 305 * 306 * @param[in] conn_idx: Connnection index. 307 * @param[in] p_data: Pointer to the data to be sent. 308 * @param[in] length: Length of data. 309 * 310 * @return Result of sending data. 311 ***************************************************************************************** 312 */ 313 sdk_err_t ags_non_stream_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length); 314 /** @} */ 315 316 #endif 317 /** @} */ 318 /** @} */ 319 320