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 "gr55xx_sys.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 < CFG_MAX_CONNECTIONS ?\
94  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of AGS connections. */
95 
96 /**
97  * @defgroup AGS_CHAR_MASK Characteristics Mask
98  * @{
99  * @brief Bit masks for the initialization of \ref ags_init_t.char_mask.
100  */
101 #define AGS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in AGS. */
102 #define AGS_CHAR_FULL 0x003f /**< Bit mask of the full characteristic. */
103 /** @} */
104 /** @} */
105 
106 /**
107  * @defgroup AGS_ENUM Enumerations
108  * @{
109  */
110 /**@brief Alexa Gadget Service Stream ID.
111  * At any time, there is only one control stream, one Alexa stream, and one OTA stream.
112  * Each packet belongs to one of these streams, which is specified in the stream ID field of the packet's header.
113  * See Gadgets documentation for details:
114  * https://developer.amazon.com/en-US/docs/alexa/alexa-gadgets-toolkit/packet-ble.html#streams
115  */
116 typedef enum
117 {
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. */
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 {
129  AGS_TRANSACTION_TYPE_FIRST, /**< First packet of a transaction, 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, the only type of control packet is the ACK packet. */
134 
135 /**@brief Alexa Gadget Service ACK Flag.
136  */
137 typedef enum
138 {
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. */
143 
144 /**@brief Alexa Gadget Service Length extender.
145  */
146 typedef enum
147 {
148  AGS_LEN_EXT_NO_EXT, /**< The packet's payload is 8 bits. */
149  AGS_LEN_EXT_EXT, /**< The packet's payload is 16 bits. */
150 
152 
153 /**@brief Alexa Gadget Service result code.
154  */
155 typedef enum
156 {
157  AGS_RES_CODE_SUCCESS, /**< The message was valid and acted on (if applicable) successfully. */
158  AGS_RES_CODE_UNKNOWN, /**< The message was valid but rusulted in a failure or error. */
159  AGS_RES_CODE_UNSUPPORTED = 0x03, /**< The message was invalid because it contained a command or other field that
160  was not supported by the receiver. */
162 
163 /**@brief Alexa Gadget Service event type.*/
164 typedef enum
165 {
166  AGS_EVT_INVALID, /**< Indicate that invalid event. */
167  AGS_EVT_ECHO_RX_DATA_SENT, /**< Indicate that the gadget has been sent the data to an Echo device. */
168  AGS_EVT_ECHO_TX_DATA_RECEIVED, /**< Indicate that the gadget has been received the data from an Echo device. */
169  AGS_EVT_ECHO_RX_NOTI_ENABLE, /**< Indicate that the Rx notification has been enabled. */
170  AGS_EVT_ECHO_RX_NOTI_DISABLE, /**< Indicate that the Rx notification has been disabled. */
172 /** @} */
173 
174 /**
175  * @defgroup AGS_STRUCT Structures
176  * @{
177  */
178 /**@brief Alexa Gadget Service base part of data packet header. */
179 typedef struct
180 {
181  uint8_t trxn_id :4; /**< The transaction ID. */
182  uint8_t stream_id :4; /**< The stream ID. @ref ags_header_stream_id_t */
183  uint8_t length_ext :1; /**< Length extender. It indicates the length of the payload field. @ref ags_header_length_ext_t */
184  uint8_t ack_flag :1; /**< Acknowledgement(ACK) flag. @ref ags_header_ack_flag_t */
185  uint8_t trxn_type :2; /**< Transaction type. @ref ags_header_trxn_type_t */
186  uint8_t sequ_num :4; /**< Sequence number. Since this is four bits long, it supports
187  inplace sequencing of up to 16 packet at a given point in time.
188  Sequence numbers can rool over.*/
190 
191 /**@brief Alexa Gadget Service header in first packet. */
192 typedef struct
193 {
194  ags_header_base_t header_base; /**< Header base. */
195  uint8_t reserved; /**< Reserved. This is only present in the first packet of the transaction. */
196  uint8_t total_trxn_length[2]; /**< Total transaction length. This is only present in the first packet of the transaction. */
197  uint8_t payload_length; /**< Payload Length. */
199 
200 /**@brief Alexa Gadget Service extended version of header in first packet. */
201 typedef struct
202 {
203  ags_header_base_t header_base; /**< Header base. */
204  uint8_t reserved; /**< Reserved. This is only present in the first packet of the transaction. */
205  uint8_t total_trxn_length[2]; /**< Total transaction length. This is only present in the first packet of the transaction. */
206  uint8_t payload_length[2]; /**< Payload Length. */
208 
209 /**@brief Alexa Gadget Service header in subsequent packets. */
210 typedef struct
211 {
212  ags_header_base_t header_base; /**< Header base. */
213  uint8_t payload_length; /**< Payload Length. */
215 
216 /**@brief Alexa Gadget Service extended version of header in subsequent packets. */
217 typedef struct
218 {
219  ags_header_base_t header_base; /**< Header base. */
220  uint8_t payload_length[2]; /**< Payload Length. */
222 
223 /**@brief Alexa Gadget Service ACK packet. */
224 typedef struct
225 {
226  ags_header_base_t header_base; /**< Header base. */
227  uint8_t reserved_1; /**< Reserved. */
228  uint8_t payload_length; /**< Length of the ACK packet. */
229  uint8_t reserved_2; /**< Reserved. */
230  uint8_t result_code; /**< A result code, which depends on whether this is an ACK or a NACK. @ref ags_header_ack_flag_t */
232 
233 /**@brief Alexa Gadget Service gadget stream enviorenment variable. */
234 typedef struct
235 {
236  ags_header_stream_id_t stream_id; /**< The stream ID. */
237  uint8_t is_active; /**< Whether the stream is active. */
238  uint8_t ack_flag; /**< Whether need to return ACK packet. */
239  uint8_t trxn_id; /**< The transaction ID of the packet that requested the ACK packet. */
240  uint16_t total_length; /**< Total stream length. */
241  uint16_t received_length; /**< Received stream length. */
243 
244 /**@brief Alexa Gadget Service event. */
245 typedef struct
246 {
247  ags_evt_type_t evt_type; /**< The AGS event type. */
248  uint8_t conn_idx; /**< The index of the connection. */
249  const uint8_t *p_data; /**< Pointer to event data. */
250  uint16_t length; /**< Length of event data. */
251 } ags_evt_t;
252 /** @} */
253 
254 /**
255  * @defgroup AGS_TYPEDEF Typedefs
256  * @{
257  */
258 /**@brief Alexa Gadget Service event handler type.*/
259 typedef void (*ags_evt_handler_t)(ags_evt_t *p_evt);
260 
261 /**@brief Alexa Gadget Service stream callback.*/
262 typedef bool (*ags_stream_cb_t)(uint8_t conn_idx, const uint8_t *const p_data, uint16_t length, uint8_t still_receiving);
263 /** @} */
264 
265 /**
266  * @defgroup AGS_STRUCT Structures
267  * @{
268  */
269 /**@brief Alexa Gadget Service init stucture. This contains all option and data needed for initialization of the service. */
270 typedef struct
271 {
272  ags_evt_handler_t evt_handler; /**< Alexa Gadget Service event handler. */
273  ags_stream_cb_t ags_control_stream_cb; /**< Callback for incoming control streams. */
274  ags_stream_cb_t ags_alexa_stream_cb; /**< Callback for incoming Alexa streams. */
275  uint16_t char_mask; /**< Initial mask of supported characteristics, and configured with \ref AGS_CHAR_MASK. */
276 } ags_init_t;
277 /** @} */
278 
279 /**
280  * @defgroup AGS_FUNCTION Functions
281  * @{
282  */
283 /**
284  *****************************************************************************************
285  * @brief Initialize a Alexa Gadget Service instance and add in the DB.
286  *
287  * @param[in] p_ags_init: Pointer to ags_init_t Service initialization variable
288  *
289  * @return Result of service initialization.
290  *****************************************************************************************
291  */
293 
294 /**
295  *****************************************************************************************
296  * @brief Send data to the Echo device in stream format.
297  *
298  * @param[in] conn_idx: Connnection index.
299  * @param[in] stream_id: Stream ID, @ref ags_header_stream_id_t.
300  * @param[in] p_data: Pointer to the data to be sent.
301  * @param[in] length: Length of data.
302  *
303  * @return Result of sending data.
304  *****************************************************************************************
305  */
306 sdk_err_t ags_stream_send(uint8_t conn_idx, uint8_t stream_id, void *p_data, uint16_t length);
307 
308 /**
309  *****************************************************************************************
310  * @brief Send data to the Echo device in non-stream format.
311  *
312  * @param[in] conn_idx: Connnection index.
313  * @param[in] p_data: Pointer to the data to be sent.
314  * @param[in] length: Length of data.
315  *
316  * @return Result of sending data.
317  *****************************************************************************************
318  */
319 sdk_err_t ags_non_stream_send(uint8_t conn_idx, void *p_data, uint16_t length);
320 /** @} */
321 
322 #endif
323 /** @} */
324 /** @} */
325 
ags_evt_t::evt_type
ags_evt_type_t evt_type
The AGS event type.
Definition: ags.h:247
ags_header_base_t::stream_id
uint8_t stream_id
The stream ID.
Definition: ags.h:182
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:262
ags_init_t::evt_handler
ags_evt_handler_t evt_handler
Alexa Gadget Service event handler.
Definition: ags.h:272
ags_header_first_ext_t
Alexa Gadget Service extended version of header in first packet.
Definition: ags.h:202
AGS_RES_CODE_UNKNOWN
@ AGS_RES_CODE_UNKNOWN
The message was valid but rusulted in a failure or error.
Definition: ags.h:158
ags_header_first_t
Alexa Gadget Service header in first packet.
Definition: ags.h:193
ags_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: ags.h:248
AGS_TRANSACTION_TYPE_FIRST
@ AGS_TRANSACTION_TYPE_FIRST
First packet of a transaction, or the only packet in a single-packet transaction.
Definition: ags.h:129
ags_header_subs_ext_t
Alexa Gadget Service extended version of header in subsequent packets.
Definition: ags.h:218
AGS_EVT_ECHO_RX_NOTI_DISABLE
@ AGS_EVT_ECHO_RX_NOTI_DISABLE
Indicate that the Rx notification has been disabled.
Definition: ags.h:170
ags_header_base_t::sequ_num
uint8_t sequ_num
Sequence number.
Definition: ags.h:186
AGS_ACK_ACK
@ AGS_ACK_ACK
The gadget must send an ACK packet in response to the last packet of the transaction.
Definition: ags.h:141
ags_init_t::ags_alexa_stream_cb
ags_stream_cb_t ags_alexa_stream_cb
Callback for incoming Alexa streams.
Definition: ags.h:274
ags_evt_type_t
ags_evt_type_t
Alexa Gadget Service event type.
Definition: ags.h:165
gr55xx_sys.h
GR55XX System API.
ags_header_length_ext_t
ags_header_length_ext_t
Alexa Gadget Service Length extender.
Definition: ags.h:147
AGS_CONTROL_STREAM_ID
@ AGS_CONTROL_STREAM_ID
Control stream ID, used to communicate.
Definition: ags.h:118
AGS_RES_CODE_SUCCESS
@ AGS_RES_CODE_SUCCESS
The message was valid and acted on (if applicable) successfully.
Definition: ags.h:157
ags_ack_packet_t::header_base
ags_header_base_t header_base
Header base.
Definition: ags.h:226
ags_header_trxn_type_t
ags_header_trxn_type_t
Alexa Gadget Service transaction type.
Definition: ags.h:128
ags_stream_env_t::is_active
uint8_t is_active
Whether the stream is active.
Definition: ags.h:237
AGS_TRANSACTION_TYPE_LAST
@ AGS_TRANSACTION_TYPE_LAST
Last packet of a transaction.
Definition: ags.h:131
ags_header_ack_flag_t
ags_header_ack_flag_t
Alexa Gadget Service ACK Flag.
Definition: ags.h:138
ags_evt_t::p_data
const uint8_t * p_data
Pointer to event data.
Definition: ags.h:249
AGS_LEN_EXT_EXT
@ AGS_LEN_EXT_EXT
The packet's payload is 16 bits.
Definition: ags.h:149
ags_ack_packet_t::reserved_2
uint8_t reserved_2
Reserved.
Definition: ags.h:229
ags_init_t::ags_control_stream_cb
ags_stream_cb_t ags_control_stream_cb
Callback for incoming control streams.
Definition: ags.h:273
AGS_EVT_ECHO_RX_DATA_SENT
@ AGS_EVT_ECHO_RX_DATA_SENT
Indicate that the gadget has been sent the data to an Echo device.
Definition: ags.h:167
ags_header_first_ext_t::reserved
uint8_t reserved
Reserved.
Definition: ags.h:204
ags_header_subs_t::header_base
ags_header_base_t header_base
Header base.
Definition: ags.h:212
ags_header_base_t::length_ext
uint8_t length_ext
Length extender.
Definition: ags.h:183
ags_stream_env_t::total_length
uint16_t total_length
Total stream length.
Definition: ags.h:240
ags_evt_handler_t
void(* ags_evt_handler_t)(ags_evt_t *p_evt)
Alexa Gadget Service event handler type.
Definition: ags.h:259
ags_stream_env_t::stream_id
ags_header_stream_id_t stream_id
The stream ID.
Definition: ags.h:236
ags_evt_t
Alexa Gadget Service event.
Definition: ags.h:246
ags_ack_packet_t::payload_length
uint8_t payload_length
Length of the ACK packet.
Definition: ags.h:228
ags_header_first_ext_t::header_base
ags_header_base_t header_base
Header base.
Definition: ags.h:203
AGS_TRANSACTION_TYPE_CTRL
@ AGS_TRANSACTION_TYPE_CTRL
Control packet.
Definition: ags.h:132
AGS_EVT_ECHO_RX_NOTI_ENABLE
@ AGS_EVT_ECHO_RX_NOTI_ENABLE
Indicate that the Rx notification has been enabled.
Definition: ags.h:169
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:180
AGS_OTA_STREAM_ID
@ AGS_OTA_STREAM_ID
OTA stream ID, used to update the gadget's firmware.
Definition: ags.h:120
ags_evt_t::length
uint16_t length
Length of event data.
Definition: ags.h:250
AGS_TRANSACTION_TYPE_CONT
@ AGS_TRANSACTION_TYPE_CONT
Continuation packet of a transaction.
Definition: ags.h:130
ags_header_subs_ext_t::header_base
ags_header_base_t header_base
Header base.
Definition: ags.h:219
ags_ack_packet_t::reserved_1
uint8_t reserved_1
Reserved.
Definition: ags.h:227
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
ags_ack_packet_t
Alexa Gadget Service ACK packet.
Definition: ags.h:225
AGS_EVT_INVALID
@ AGS_EVT_INVALID
Indicate that invalid event.
Definition: ags.h:166
ags_stream_env_t::ack_flag
uint8_t ack_flag
Whether need to return ACK packet.
Definition: ags.h:238
ags_header_base_t::ack_flag
uint8_t ack_flag
Acknowledgement(ACK) flag.
Definition: ags.h:184
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.
Definition: ags.h:117
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
Alexa stream ID, used to send directives and events.
Definition: ags.h:119
AGS_EVT_ECHO_TX_DATA_RECEIVED
@ AGS_EVT_ECHO_TX_DATA_RECEIVED
Indicate that the gadget has been received the data from an Echo device.
Definition: ags.h:168
ags_header_first_t::reserved
uint8_t reserved
Reserved.
Definition: ags.h:195
AGS_ACK_NACK
@ AGS_ACK_NACK
The gadget doesn't need to send an ACK packet in response to the last packet of the transaction unles...
Definition: ags.h:139
AGS_LEN_EXT_NO_EXT
@ AGS_LEN_EXT_NO_EXT
The packet's payload is 8 bits.
Definition: ags.h:148
ags_stream_env_t::trxn_id
uint8_t trxn_id
The transaction ID of the packet that requested the ACK packet.
Definition: ags.h:239
ags_stream_env_t::received_length
uint16_t received_length
Received stream length.
Definition: ags.h:241
ags_init_t::char_mask
uint16_t char_mask
Initial mask of supported characteristics, and configured with Characteristics Mask.
Definition: ags.h:275
ags_header_base_t::trxn_id
uint8_t trxn_id
The transaction ID.
Definition: ags.h:181
ags_init_t
Alexa Gadget Service init stucture.
Definition: ags.h:271
ags_header_subs_t
Alexa Gadget Service header in subsequent packets.
Definition: ags.h:211
ags_header_subs_t::payload_length
uint8_t payload_length
Payload Length.
Definition: ags.h:213
ags_header_first_t::payload_length
uint8_t payload_length
Payload Length.
Definition: ags.h:197
ags_header_base_t::trxn_type
uint8_t trxn_type
Transaction type.
Definition: ags.h:185
AGS_RES_CODE_UNSUPPORTED
@ AGS_RES_CODE_UNSUPPORTED
The message was invalid because it contained a command or other field that was not supported by the r...
Definition: ags.h:159
ags_header_first_t::header_base
ags_header_base_t header_base
Header base.
Definition: ags.h:194
ags_stream_env_t
Alexa Gadget Service gadget stream enviorenment variable.
Definition: ags.h:235
ags_header_result_code_t
ags_header_result_code_t
Alexa Gadget Service result code.
Definition: ags.h:156
ags_ack_packet_t::result_code
uint8_t result_code
A result code, which depends on whether this is an ACK or a NACK.
Definition: ags.h:230