gus_c.h
Go to the documentation of this file.
1 /**
2  *****************************************************************************************
3  *
4  * @file gus_c.h
5  *
6  * @brief Header file - Goodix UART Service Client
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_GUS_C Goodix UART Service Client (GUS_C)
46  * @{
47  * @brief Goodix UART Service Client module.
48  *
49  * @details The Goodix Uart Service Client contains the APIs and types, which can be used by the
50  * application to perform scanning, connection and discover Goodix Uart Service at
51  * peer and interact with it.
52  *
53  * The application must provide an event handler, then call \ref gus_client_init(). After the
54  * module can send and receive BLE data, application can call \ref gus_c_tx_data_send() to
55  * send data to peer, and receive data from peer \ref GUS_C_EVT_PEER_DATA_RECEIVE,
56  * meanwhile update its received BLE data state \ref gus_c_rx_flow_ctrl_set() to peer.
57  */
58 
59 #ifndef __GUS_C_H__
60 #define __GUS_C_H__
61 
62 #include "ble_prf_types.h"
63 #include "gr55xx_sys.h"
64 #include "custom_config.h"
65 #include <stdint.h>
66 #include <stdbool.h>
67 
68 /**
69  * @defgroup GUS_C_MACRO Defines
70  * @{
71  */
72 #define GUS_C_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
73  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of GUS Client connections. */
74 #define FLOW_ON 0x01 /**< Indicate that GUS Client can receive data from peer. */
75 #define FLOW_OFF 0x00 /**< Indicate that GUS Client can not receive data from peer. */
76 
77 /**
78  * @defgroup GUS_UUID Service and Characteristics UUID
79  * @{
80  */
81 #define GUS_SVC_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
82  0x0A, 0x46, 0x44, 0xD3, 0x01, 0x02, 0xED, 0xA6} /**< UUID of GUS Service. */
83 #define GUS_TX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
84  0x0A, 0x46, 0x44, 0xD3, 0x02, 0x02, 0xED, 0xA6} /**< UUID of GUS Tx characterisitc. */
85 #define GUS_RX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
86  0x0A, 0x46, 0x44, 0xD3, 0x03, 0x02, 0xED, 0xA6} /**< UUID of GUS Rx characterisitc. */
87 #define GUS_FLOW_CTRL_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
88  0x0A, 0x46, 0x44, 0xD3, 0x04, 0x02, 0xED, 0xA6} /**< UUID of GUS Flow Control characterisitc. */
89 /** @} */
90 /** @} */
91 
92 /**
93  * @defgroup GUS_C_ENUM Enumerations
94  * @{
95  */
96 /**@brief Goodix UART Service Client event type. */
97 typedef enum
98 {
99  GUS_C_EVT_INVALID, /**< Invalid GUS Client event. */
100  GUS_C_EVT_DISCOVERY_COMPLETE, /**< GUS Client has found service and its characteristics at peer. */
101  GUS_C_EVT_DISCOVERY_FAIL, /**< GUS Client found THS service failed because of invalid operation or no found at peer. */
102  GUS_C_EVT_TX_NTF_SET_SUCCESS, /**< GUS Client has set peer Tx notify. */
103  GUS_C_EVT_FLOW_CTRL_NTF_SET_SUCCESS, /**< GUS Client has set peer ble flow control notify. */
104  GUS_C_EVT_PEER_DATA_RECEIVE, /**< GUS Client has received something from peer. */
105  GUS_C_EVT_TX_CPLT, /**< GUS Client has sent something to peer successfully. */
106  GUS_C_EVT_TX_FLOW_OFF, /**< GUS Client has received Tx flow off control request from peer. */
107  GUS_C_EVT_TX_FLOW_ON, /**< GUS Client has received Tx flow on control request from peer. */
108  GUS_C_EVT_RX_FLOW_UPDATE_CPLT, /**< GUS CLient has updated flow control to peer completely. */
109  GUS_C_EVT_WRITE_OP_ERR, /**< Error occured when GUS Client wrote to peer. */
111 /** @} */
112 
113 /**
114  * @defgroup GUS_C_STRUCT Structures
115  * @{
116  */
117 /**@brief Handles on the connected peer device needed to interact with it. */
118 typedef struct
119 {
120  uint16_t gus_srvc_start_handle; /**< GUS Service start handle. */
121  uint16_t gus_srvc_end_handle; /**< GUS Service end handle. */
122  uint16_t gus_tx_handle; /**< Handle of GUS Tx characteristic as provided by a discovery. */
123  uint16_t gus_tx_cccd_handle; /**< Handle of CCCD of GUS Tx characteristic as provided by a discovery. */
124  uint16_t gus_rx_handle; /**< Handle of GUS Rx characteristic as provided by a discovery. */
125  uint16_t gus_flow_ctrl_handle; /**< Handle of GUS Flow Control characteristic as provided by a discovery. */
126  uint16_t gus_flow_ctrl_cccd_handle; /**< Handle of CCCD of GUS Flow Control characteristic as provided by a discovery. */
128 
129 /**@brief Goodix UART Service Client event. */
130 typedef struct
131 {
132  uint8_t conn_idx; /**< Connection index. */
133  gus_c_evt_type_t evt_type; /**< GUS Client event type. */
134  uint16_t length; /**< Length of event data. */
135  uint8_t *p_data; /**< Pointer to event data. */
136 } gus_c_evt_t;
137 /** @} */
138 
139 /**
140  * @defgroup GUS_C_TYPEDEF Typedefs
141  * @{
142  */
143 /**@brief Goodix UART Service Client event handler type. */
144 typedef void (* gus_c_evt_handler_t)(gus_c_evt_t *p_evt);
145 /** @} */
146 
147 /**
148  * @defgroup GUS_C_FUNCTION Functions
149  * @{
150  */
151 /**
152  *****************************************************************************************
153  * @brief Register GUS Client event handler.
154  *
155  * @param[in] evt_handler: Goodix UART Service Client event handler.
156  *
157  * @return Result of initialization.
158  *****************************************************************************************
159  */
161 
162 /**
163  *****************************************************************************************
164  * @brief Discovery GUS on peer.
165  *
166  * @param[in] conn_idx: Index of connection.
167  *
168  * @return Operation result.
169  *****************************************************************************************
170  */
172 
173 /**
174  *****************************************************************************************
175  * @brief Enable or disable peer GUS Tx characteristic notify.
176  *
177  * @param[in] conn_idx: Connection index.
178  * @param[in] is_enable: Enable or disable ths Tx notify.
179  *
180  * @return Operation result.
181  *****************************************************************************************
182  */
183 sdk_err_t gus_c_tx_notify_set(uint8_t conn_idx, bool is_enable);
184 
185 /**
186  *****************************************************************************************
187  * @brief Enable or disable peer device GUS flow control notify.
188  *
189  * @param[in] conn_idx: Connection index.
190  * @param[in] is_enable: Enable or disable ths Tx notify.
191  *
192  * @return Operation result.
193  *****************************************************************************************
194  */
195 sdk_err_t gus_c_flow_ctrl_notify_set(uint8_t conn_idx, bool is_enable);
196 
197 /**
198  *****************************************************************************************
199  * @brief Send data to the server.
200  *
201  * @param[in] conn_idx: Connection index.
202  * @param[in] p_data: Pointer to data need sent.
203  * @param[in] length: Length of data need sent.
204  *
205  * @return Operation result.
206  *****************************************************************************************
207  */
208 sdk_err_t gus_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
209 
210 /**
211  *****************************************************************************************
212  * @brief Send GUS Client Rx flow control state to peer device
213  *
214  * @param[in] conn_idx: Connection index.
215  * @param[in] flow_ctrl: GUS client Rx flow control state.
216  *
217  * @return Result of sending gus_c Rx flow control state.
218  *****************************************************************************************
219  */
220 sdk_err_t gus_c_rx_flow_ctrl_set(uint8_t conn_idx, uint8_t flow_ctrl);
221 /** @} */
222 #endif
223 /** @} */
224 /** @} */
225 
GUS_C_EVT_TX_FLOW_OFF
@ GUS_C_EVT_TX_FLOW_OFF
GUS Client has received Tx flow off control request from peer.
Definition: gus_c.h:106
GUS_C_EVT_DISCOVERY_FAIL
@ GUS_C_EVT_DISCOVERY_FAIL
GUS Client found THS service failed because of invalid operation or no found at peer.
Definition: gus_c.h:101
GUS_C_EVT_TX_FLOW_ON
@ GUS_C_EVT_TX_FLOW_ON
GUS Client has received Tx flow on control request from peer.
Definition: gus_c.h:107
gus_c_evt_t::conn_idx
uint8_t conn_idx
Connection index.
Definition: gus_c.h:132
GUS_C_EVT_DISCOVERY_COMPLETE
@ GUS_C_EVT_DISCOVERY_COMPLETE
GUS Client has found service and its characteristics at peer.
Definition: gus_c.h:100
gus_c_handles_t::gus_srvc_end_handle
uint16_t gus_srvc_end_handle
GUS Service end handle.
Definition: gus_c.h:121
gr55xx_sys.h
GR55XX System API.
GUS_C_EVT_PEER_DATA_RECEIVE
@ GUS_C_EVT_PEER_DATA_RECEIVE
GUS Client has received something from peer.
Definition: gus_c.h:104
gus_c_handles_t::gus_rx_handle
uint16_t gus_rx_handle
Handle of GUS Rx characteristic as provided by a discovery.
Definition: gus_c.h:124
gus_c_evt_t::length
uint16_t length
Length of event data.
Definition: gus_c.h:134
GUS_C_EVT_TX_CPLT
@ GUS_C_EVT_TX_CPLT
GUS Client has sent something to peer successfully.
Definition: gus_c.h:105
gus_c_handles_t::gus_flow_ctrl_cccd_handle
uint16_t gus_flow_ctrl_cccd_handle
Handle of CCCD of GUS Flow Control characteristic as provided by a discovery.
Definition: gus_c.h:126
gus_c_handles_t::gus_tx_handle
uint16_t gus_tx_handle
Handle of GUS Tx characteristic as provided by a discovery.
Definition: gus_c.h:122
gus_c_evt_t::p_data
uint8_t * p_data
Pointer to event data.
Definition: gus_c.h:135
gus_c_tx_data_send
sdk_err_t gus_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to the server.
GUS_C_EVT_INVALID
@ GUS_C_EVT_INVALID
Invalid GUS Client event.
Definition: gus_c.h:99
gus_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: gus_c.h:119
gus_c_disc_srvc_start
sdk_err_t gus_c_disc_srvc_start(uint8_t conn_idx)
Discovery GUS on peer.
GUS_C_EVT_WRITE_OP_ERR
@ GUS_C_EVT_WRITE_OP_ERR
Error occured when GUS Client wrote to peer.
Definition: gus_c.h:109
gus_c_evt_type_t
gus_c_evt_type_t
Goodix UART Service Client event type.
Definition: gus_c.h:98
GUS_C_EVT_RX_FLOW_UPDATE_CPLT
@ GUS_C_EVT_RX_FLOW_UPDATE_CPLT
GUS CLient has updated flow control to peer completely.
Definition: gus_c.h:108
ble_prf_types.h
Profile/Service Common Types.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
gus_c_handles_t::gus_tx_cccd_handle
uint16_t gus_tx_cccd_handle
Handle of CCCD of GUS Tx characteristic as provided by a discovery.
Definition: gus_c.h:123
gus_c_handles_t::gus_flow_ctrl_handle
uint16_t gus_flow_ctrl_handle
Handle of GUS Flow Control characteristic as provided by a discovery.
Definition: gus_c.h:125
gus_c_evt_t
Goodix UART Service Client event.
Definition: gus_c.h:131
gus_c_evt_t::evt_type
gus_c_evt_type_t evt_type
GUS Client event type.
Definition: gus_c.h:133
gus_c_handles_t::gus_srvc_start_handle
uint16_t gus_srvc_start_handle
GUS Service start handle.
Definition: gus_c.h:120
gus_c_tx_notify_set
sdk_err_t gus_c_tx_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer GUS Tx characteristic notify.
gus_client_init
sdk_err_t gus_client_init(gus_c_evt_handler_t evt_handler)
Register GUS Client event handler.
GUS_C_EVT_FLOW_CTRL_NTF_SET_SUCCESS
@ GUS_C_EVT_FLOW_CTRL_NTF_SET_SUCCESS
GUS Client has set peer ble flow control notify.
Definition: gus_c.h:103
gus_c_evt_handler_t
void(* gus_c_evt_handler_t)(gus_c_evt_t *p_evt)
Goodix UART Service Client event handler type.
Definition: gus_c.h:144
gus_c_rx_flow_ctrl_set
sdk_err_t gus_c_rx_flow_ctrl_set(uint8_t conn_idx, uint8_t flow_ctrl)
Send GUS Client Rx flow control state to peer device.
GUS_C_EVT_TX_NTF_SET_SUCCESS
@ GUS_C_EVT_TX_NTF_SET_SUCCESS
GUS Client has set peer Tx notify.
Definition: gus_c.h:102
gus_c_flow_ctrl_notify_set
sdk_err_t gus_c_flow_ctrl_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer device GUS flow control notify.