ags.h
Go to the documentation of this file.
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 "gr_includes.h"
61 #include "custom_config.h"
62 #include <stdint.h>
63 #include <stdbool.h>
64 
65 /**
66  * @defgroup AGS_MACRO Defines
67  * @{
68  */
69 #define AGS_SERVICE_UUID 0xFB, 0x34, 0x9B, 0x5F, 0x80, 0x00, 0x00, 0x80,\
70  0x00, 0x10, 0x00, 0x00, 0x03, 0xFE, 0x00, 0x00 /**< The UUID of Alexa Gadget Service for setting advertising data. */
71 
72 #define AGS_HEADER_FIRST_RES 0x00 /**< Reserved value of header in the first packet. */
73 
74 #define AGS_HEADER_ACK_RES_1 0x00 /**< The first reserved value of header in the ACK packet. */
75 #define AGS_HEADER_ACK_PAYLOAD_LEN 0x02 /**< Length of the ACK packet, in bytes. */
76 #define AGS_HEADER_ACK_RES_2 0x01 /**< The second reserved value of header in the ACK packet. */
77 
78 #define AGS_TX_VAL_LEN_MAX 244 /**< Maximum length of TX Characteristic value. */
79 #define AGS_RX_VAL_LEN_MAX 244 /**< Maximum length of RX Characteristic value. */
80 
81 /**
82  * @defgroup AGS_ADV_TYPE Advertising type
83  * @{
84  * @brief The advertisiment type.
85  * Bit 0 : Pairing or reconnection mode, 0 - reconnection mode, 1 - pairing mode;
86  * Bit 1 : Classic Bluetooth discoverability;
87  * Bit 2~7 : Reserved for future use, set to 0x00.
88  */
89 #define AGS_PAIR_ADV_FLAG 0x01 /**< The Pairing advertisiment flag. */
90 #define AGS_RECONNECT_ADV_FLAG 0x00 /**< The reconnecting advertisiment flag. */
91 /** @} */
92 
93 #define AGS_CONNECTION_MAX 10 /**< Maximum number of AGS connections. */
94 
95 /**
96  * @defgroup AGS_CHAR_MASK Characteristics Mask
97  * @{
98  * @brief Bit masks for the initialization of \ref ags_init_t.char_mask.
99  */
100 #define AGS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in AGS. */
101 #define AGS_CHAR_FULL 0x003f /**< Bit mask of the full characteristic. */
102 /** @} */
103 /** @} */
104 
105 /**
106  * @defgroup AGS_ENUM Enumerations
107  * @{
108  */
109 /**@brief Alexa Gadget Service Stream ID.
110  * At any time, there is only one control stream, one Alexa stream, and one OTA stream.
111  * Each packet belongs to one of these streams, which is specified in the stream ID field of the packet's header.
112  * See Gadgets documentation for details:
113  * https://developer.amazon.com/en-US/docs/alexa/alexa-gadgets-toolkit/packet-ble.html#streams
114  */
115 typedef enum
116 {
117  AGS_CONTROL_STREAM_ID, /**< Control stream ID, used to communicate. */
118  AGS_ALEXA_STREAM_ID = 0x06, /**< Alexa stream ID, used to send directives and events. */
119  AGS_OTA_STREAM_ID = 0x02, /**< OTA stream ID, used to update the gadget's firmware. */
121 
122 /**@brief Alexa Gadget Service transaction type.
123  * It indicate where the packet is within the transaction. The transaction type and
124  * protocol of a single transaction are defined by the first packet of the transaction.
125  */
126 typedef enum
127 {
128  AGS_TRANSACTION_TYPE_FIRST, /**< First packet of a transaction, or the only packet in a single-packet transaction. */
129  AGS_TRANSACTION_TYPE_CONT, /**< Continuation packet of a transaction. */
130  AGS_TRANSACTION_TYPE_LAST, /**< Last packet of a transaction. */
131  AGS_TRANSACTION_TYPE_CTRL, /**< Control packet. Currently, the only type of control packet is the ACK packet. */
133 
134 /**@brief Alexa Gadget Service ACK Flag.
135  */
136 typedef enum
137 {
138  AGS_ACK_NACK, /**< The gadget doesn't need to send an ACK packet in response to the last packet of the
139  transaction unless another packet in the transaction has this bit set to 1. */
140  AGS_ACK_ACK, /**< The gadget must send an ACK packet in response to the last packet of the transaction. */
142 
143 /**@brief Alexa Gadget Service Length extender.
144  */
145 typedef enum
146 {
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 
151 
152 /**@brief Alexa Gadget Service result code.
153  */
154 typedef enum
155 {
156  AGS_RES_CODE_SUCCESS, /**< The message was valid and acted on (if applicable) successfully. */
157  AGS_RES_CODE_UNKNOWN, /**< The message was valid but rusulted in a failure or error. */
158  AGS_RES_CODE_UNSUPPORTED = 0x03, /**< The message was invalid because it contained a command or other field that
159  was not supported by the receiver. */
161 
162 /**@brief Alexa Gadget Service event type.*/
163 typedef enum
164 {
165  AGS_EVT_INVALID, /**< Indicate that invalid event. */
166  AGS_EVT_ECHO_RX_DATA_SENT, /**< Indicate that the gadget has been sent the data to an Echo device. */
167  AGS_EVT_ECHO_TX_DATA_RECEIVED, /**< Indicate that the gadget has been received the data from an Echo device. */
168  AGS_EVT_ECHO_RX_NOTI_ENABLE, /**< Indicate that the Rx notification has been enabled. */
169  AGS_EVT_ECHO_RX_NOTI_DISABLE, /**< Indicate that the Rx notification has been disabled. */
171 /** @} */
172 
173 /**
174  * @defgroup AGS_STRUCT Structures
175  * @{
176  */
177 /**@brief Alexa Gadget Service base part of data packet header. */
178 typedef struct
179 {
180  uint8_t trxn_id :4; /**< The transaction ID. */
181  uint8_t stream_id :4; /**< The stream ID. @ref ags_header_stream_id_t */
182  uint8_t length_ext :1; /**< Length extender. It indicates the length of the payload field. @ref ags_header_length_ext_t */
183  uint8_t ack_flag :1; /**< Acknowledgement(ACK) flag. @ref ags_header_ack_flag_t */
184  uint8_t trxn_type :2; /**< Transaction type. @ref ags_header_trxn_type_t */
185  uint8_t sequ_num :4; /**< Sequence number. Since this is four bits long, it supports
186  inplace sequencing of up to 16 packet at a given point in time.
187  Sequence numbers can rool over.*/
189 
190 /**@brief Alexa Gadget Service header in first packet. */
191 typedef struct
192 {
193  ags_header_base_t header_base; /**< Header base. */
194  uint8_t reserved; /**< Reserved. This is only present in the first packet of the transaction. */
195  uint8_t total_trxn_length[2]; /**< Total transaction length. This is only present in the first packet of the transaction. */
196  uint8_t payload_length; /**< Payload Length. */
198 
199 /**@brief Alexa Gadget Service extended version of header in first packet. */
200 typedef struct
201 {
202  ags_header_base_t header_base; /**< Header base. */
203  uint8_t reserved; /**< Reserved. This is only present in the first packet of the transaction. */
204  uint8_t total_trxn_length[2]; /**< Total transaction length. This is only present in the first packet of the transaction. */
205  uint8_t payload_length[2]; /**< Payload Length. */
207 
208 /**@brief Alexa Gadget Service header in subsequent packets. */
209 typedef struct
210 {
211  ags_header_base_t header_base; /**< Header base. */
212  uint8_t payload_length; /**< Payload Length. */
214 
215 /**@brief Alexa Gadget Service extended version of header in subsequent packets. */
216 typedef struct
217 {
218  ags_header_base_t header_base; /**< Header base. */
219  uint8_t payload_length[2]; /**< Payload Length. */
221 
222 /**@brief Alexa Gadget Service ACK packet. */
223 typedef struct
224 {
225  ags_header_base_t header_base; /**< Header base. */
226  uint8_t reserved_1; /**< Reserved. */
227  uint8_t payload_length; /**< Length of the ACK packet. */
228  uint8_t reserved_2; /**< Reserved. */
229  uint8_t result_code; /**< A result code, which depends on whether this is an ACK or a NACK. @ref ags_header_ack_flag_t */
231 
232 /**@brief Alexa Gadget Service gadget stream enviorenment variable. */
233 typedef struct
234 {
235  ags_header_stream_id_t stream_id; /**< The stream ID. */
236  uint8_t is_active; /**< Whether the stream is active. */
237  uint8_t ack_flag; /**< Whether need to return ACK packet. */
238  uint8_t trxn_id; /**< The transaction ID of the packet that requested the ACK packet. */
239  uint16_t total_length; /**< Total stream length. */
240  uint16_t received_length; /**< Received stream length. */
242 
243 /**@brief Alexa Gadget Service event. */
244 typedef struct
245 {
246  ags_evt_type_t evt_type; /**< The AGS event type. */
247  uint8_t conn_idx; /**< The index of the connection. */
248  const uint8_t *p_data; /**< Pointer to event data. */
249  uint16_t length; /**< Length of event data. */
250 } ags_evt_t;
251 /** @} */
252 
253 /**
254  * @defgroup AGS_TYPEDEF Typedefs
255  * @{
256  */
257 /**@brief Alexa Gadget Service event handler type.*/
258 typedef void (*ags_evt_handler_t)(ags_evt_t *p_evt);
259 
260 /**@brief Alexa Gadget Service stream callback.*/
261 typedef bool (*ags_stream_cb_t)(uint8_t conn_idx, const uint8_t *const p_data, uint16_t length, uint8_t still_receiving);
262 /** @} */
263 
264 /**
265  * @defgroup AGS_STRUCT Structures
266  * @{
267  */
268 /**@brief Alexa Gadget Service init stucture. This contains all option and data needed for initialization of the service. */
269 typedef struct
270 {
271  ags_evt_handler_t evt_handler; /**< Alexa Gadget Service event handler. */
272  ags_stream_cb_t ags_control_stream_cb; /**< Callback for incoming control streams. */
273  ags_stream_cb_t ags_alexa_stream_cb; /**< Callback for incoming Alexa streams. */
274  uint16_t char_mask; /**< Initial mask of supported characteristics, and configured with \ref AGS_CHAR_MASK. */
275 } ags_init_t;
276 /** @} */
277 
278 /**
279  * @defgroup AGS_FUNCTION Functions
280  * @{
281  */
282 /**
283  *****************************************************************************************
284  * @brief Initialize a Alexa Gadget Service instance and add in the DB.
285  *
286  * @param[in] p_ags_init: Pointer to ags_init_t Service initialization variable
287  *
288  * @return Result of service initialization.
289  *****************************************************************************************
290  */
292 
293 /**
294  *****************************************************************************************
295  * @brief Send data to the Echo device in stream format.
296  *
297  * @param[in] conn_idx: Connnection index.
298  * @param[in] stream_id: Stream ID, @ref ags_header_stream_id_t.
299  * @param[in] p_data: Pointer to the data to be sent.
300  * @param[in] length: Length of data.
301  *
302  * @return Result of sending data.
303  *****************************************************************************************
304  */
305 sdk_err_t ags_stream_send(uint8_t conn_idx, uint8_t stream_id, void *p_data, uint16_t length);
306 
307 /**
308  *****************************************************************************************
309  * @brief Send data to the Echo device in non-stream format.
310  *
311  * @param[in] conn_idx: Connnection index.
312  * @param[in] p_data: Pointer to the data to be sent.
313  * @param[in] length: Length of data.
314  *
315  * @return Result of sending data.
316  *****************************************************************************************
317  */
318 sdk_err_t ags_non_stream_send(uint8_t conn_idx, void *p_data, uint16_t length);
319 /** @} */
320 
321 #endif
322 /** @} */
323 /** @} */
324 
ags_evt_t::evt_type
ags_evt_type_t evt_type
Definition: ags.h:246
ags_header_base_t::stream_id
uint8_t stream_id
Definition: ags.h:181
ags_stream_cb_t
bool(* ags_stream_cb_t)(uint8_t conn_idx, const uint8_t *const p_data, uint16_t length, uint8_t still_receiving)
Alexa Gadget Service stream callback.
Definition: ags.h:261
ags_init_t::evt_handler
ags_evt_handler_t evt_handler
Definition: ags.h:271
ags_header_first_ext_t
Alexa Gadget Service extended version of header in first packet.
Definition: ags.h:201
AGS_RES_CODE_UNKNOWN
@ AGS_RES_CODE_UNKNOWN
Definition: ags.h:157
ags_header_first_t
Alexa Gadget Service header in first packet.
Definition: ags.h:192
ags_evt_t::conn_idx
uint8_t conn_idx
Definition: ags.h:247
AGS_TRANSACTION_TYPE_FIRST
@ AGS_TRANSACTION_TYPE_FIRST
Definition: ags.h:128
ags_header_subs_ext_t
Alexa Gadget Service extended version of header in subsequent packets.
Definition: ags.h:217
AGS_EVT_ECHO_RX_NOTI_DISABLE
@ AGS_EVT_ECHO_RX_NOTI_DISABLE
Definition: ags.h:169
ags_header_base_t::sequ_num
uint8_t sequ_num
Definition: ags.h:185
AGS_ACK_ACK
@ AGS_ACK_ACK
Definition: ags.h:140
gr_includes.h
Include Files API.
ags_init_t::ags_alexa_stream_cb
ags_stream_cb_t ags_alexa_stream_cb
Definition: ags.h:273
ags_evt_type_t
ags_evt_type_t
Alexa Gadget Service event type.
Definition: ags.h:164
ags_header_length_ext_t
ags_header_length_ext_t
Alexa Gadget Service Length extender.
Definition: ags.h:146
AGS_CONTROL_STREAM_ID
@ AGS_CONTROL_STREAM_ID
Definition: ags.h:117
AGS_RES_CODE_SUCCESS
@ AGS_RES_CODE_SUCCESS
Definition: ags.h:156
ags_ack_packet_t::header_base
ags_header_base_t header_base
Definition: ags.h:225
ags_header_trxn_type_t
ags_header_trxn_type_t
Alexa Gadget Service transaction type. It indicate where the packet is within the transaction....
Definition: ags.h:127
ags_stream_env_t::is_active
uint8_t is_active
Definition: ags.h:236
AGS_TRANSACTION_TYPE_LAST
@ AGS_TRANSACTION_TYPE_LAST
Definition: ags.h:130
ags_header_ack_flag_t
ags_header_ack_flag_t
Alexa Gadget Service ACK Flag.
Definition: ags.h:137
ags_evt_t::p_data
const uint8_t * p_data
Definition: ags.h:248
AGS_LEN_EXT_EXT
@ AGS_LEN_EXT_EXT
Definition: ags.h:148
ags_ack_packet_t::reserved_2
uint8_t reserved_2
Definition: ags.h:228
ags_init_t::ags_control_stream_cb
ags_stream_cb_t ags_control_stream_cb
Definition: ags.h:272
AGS_EVT_ECHO_RX_DATA_SENT
@ AGS_EVT_ECHO_RX_DATA_SENT
Definition: ags.h:166
ags_header_first_ext_t::reserved
uint8_t reserved
Definition: ags.h:203
ags_header_subs_t::header_base
ags_header_base_t header_base
Definition: ags.h:211
ags_header_base_t::length_ext
uint8_t length_ext
Definition: ags.h:182
ags_stream_env_t::total_length
uint16_t total_length
Definition: ags.h:239
ags_evt_handler_t
void(* ags_evt_handler_t)(ags_evt_t *p_evt)
Alexa Gadget Service event handler type.
Definition: ags.h:258
ags_stream_env_t::stream_id
ags_header_stream_id_t stream_id
Definition: ags.h:235
ags_evt_t
Alexa Gadget Service event.
Definition: ags.h:245
ags_ack_packet_t::payload_length
uint8_t payload_length
Definition: ags.h:227
ags_header_first_ext_t::header_base
ags_header_base_t header_base
Definition: ags.h:202
AGS_TRANSACTION_TYPE_CTRL
@ AGS_TRANSACTION_TYPE_CTRL
Definition: ags.h:131
AGS_EVT_ECHO_RX_NOTI_ENABLE
@ AGS_EVT_ECHO_RX_NOTI_ENABLE
Definition: ags.h:168
ags_non_stream_send
sdk_err_t ags_non_stream_send(uint8_t conn_idx, void *p_data, uint16_t length)
Send data to the Echo device in non-stream format.
ags_header_base_t
Alexa Gadget Service base part of data packet header.
Definition: ags.h:179
AGS_OTA_STREAM_ID
@ AGS_OTA_STREAM_ID
Definition: ags.h:119
ags_evt_t::length
uint16_t length
Definition: ags.h:249
AGS_TRANSACTION_TYPE_CONT
@ AGS_TRANSACTION_TYPE_CONT
Definition: ags.h:129
ags_header_subs_ext_t::header_base
ags_header_base_t header_base
Definition: ags.h:218
ags_ack_packet_t::reserved_1
uint8_t reserved_1
Definition: ags.h:226
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
ags_ack_packet_t
Alexa Gadget Service ACK packet.
Definition: ags.h:224
AGS_EVT_INVALID
@ AGS_EVT_INVALID
Definition: ags.h:165
ags_stream_env_t::ack_flag
uint8_t ack_flag
Definition: ags.h:237
ags_header_base_t::ack_flag
uint8_t ack_flag
Definition: ags.h:183
ags_service_init
sdk_err_t ags_service_init(ags_init_t *p_ags_init)
Initialize a Alexa Gadget Service instance and add in the DB.
ags_header_stream_id_t
ags_header_stream_id_t
Alexa Gadget Service Stream ID. At any time, there is only one control stream, one Alexa stream,...
Definition: ags.h:116
ags_stream_send
sdk_err_t ags_stream_send(uint8_t conn_idx, uint8_t stream_id, void *p_data, uint16_t length)
Send data to the Echo device in stream format.
AGS_ALEXA_STREAM_ID
@ AGS_ALEXA_STREAM_ID
Definition: ags.h:118
AGS_EVT_ECHO_TX_DATA_RECEIVED
@ AGS_EVT_ECHO_TX_DATA_RECEIVED
Definition: ags.h:167
ags_header_first_t::reserved
uint8_t reserved
Definition: ags.h:194
AGS_ACK_NACK
@ AGS_ACK_NACK
Definition: ags.h:138
AGS_LEN_EXT_NO_EXT
@ AGS_LEN_EXT_NO_EXT
Definition: ags.h:147
ags_stream_env_t::trxn_id
uint8_t trxn_id
Definition: ags.h:238
ags_stream_env_t::received_length
uint16_t received_length
Definition: ags.h:240
ags_init_t::char_mask
uint16_t char_mask
Definition: ags.h:274
ags_header_base_t::trxn_id
uint8_t trxn_id
Definition: ags.h:180
ags_init_t
Alexa Gadget Service init stucture. This contains all option and data needed for initialization of th...
Definition: ags.h:270
ags_header_subs_t
Alexa Gadget Service header in subsequent packets.
Definition: ags.h:210
ags_header_subs_t::payload_length
uint8_t payload_length
Definition: ags.h:212
ags_header_first_t::payload_length
uint8_t payload_length
Definition: ags.h:196
ags_header_base_t::trxn_type
uint8_t trxn_type
Definition: ags.h:184
AGS_RES_CODE_UNSUPPORTED
@ AGS_RES_CODE_UNSUPPORTED
Definition: ags.h:158
ags_header_first_t::header_base
ags_header_base_t header_base
Definition: ags.h:193
ags_stream_env_t
Alexa Gadget Service gadget stream enviorenment variable.
Definition: ags.h:234
ags_header_result_code_t
ags_header_result_code_t
Alexa Gadget Service result code.
Definition: ags.h:155
ags_ack_packet_t::result_code
uint8_t result_code
Definition: ags.h:229