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 "gr_includes.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 /**< Maximum number of GUS Client connections. */
73 
74 /**
75  * @defgroup GUS_UUID Service and Characteristics UUID
76  * @{
77  */
78 #define GUS_SVC_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
79  0x0A, 0x46, 0x44, 0xD3, 0x01, 0x02, 0xED, 0xA6} /**< UUID of GUS Service. */
80 #define GUS_TX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
81  0x0A, 0x46, 0x44, 0xD3, 0x02, 0x02, 0xED, 0xA6} /**< UUID of GUS Tx characterisitc. */
82 #define GUS_RX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
83  0x0A, 0x46, 0x44, 0xD3, 0x03, 0x02, 0xED, 0xA6} /**< UUID of GUS Rx characterisitc. */
84 #define GUS_FLOW_CTRL_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
85  0x0A, 0x46, 0x44, 0xD3, 0x04, 0x02, 0xED, 0xA6} /**< UUID of GUS Flow Control characterisitc. */
86 /** @} */
87 /** @} */
88 
89 /**
90  * @defgroup GUS_C_ENUM Enumerations
91  * @{
92  */
93 /**@brief Goodix UART Service Client event type. */
94 typedef enum
95 {
96  GUS_C_EVT_INVALID, /**< Invalid GUS Client event. */
97  GUS_C_EVT_DISCOVERY_COMPLETE, /**< GUS Client has found service and its characteristics at peer. */
98  GUS_C_EVT_DISCOVERY_FAIL, /**< GUS Client found THS service failed because of invalid operation or no found at peer. */
99  GUS_C_EVT_TX_NTF_SET_SUCCESS, /**< GUS Client has set peer Tx notify. */
100  GUS_C_EVT_FLOW_CTRL_NTF_SET_SUCCESS, /**< GUS Client has set peer ble flow control notify. */
101  GUS_C_EVT_PEER_DATA_RECEIVE, /**< GUS Client has received something from peer. */
102  GUS_C_EVT_TX_CPLT, /**< GUS Client has sent something to peer successfully. */
103  GUS_C_EVT_TX_FLOW_OFF, /**< GUS Client has received Tx flow off control request from peer. */
104  GUS_C_EVT_TX_FLOW_ON, /**< GUS Client has received Tx flow on control request from peer. */
105  GUS_C_EVT_RX_FLOW_UPDATE_CPLT, /**< GUS CLient has updated flow control to peer completely. */
106  GUS_C_EVT_WRITE_OP_ERR, /**< Error occured when GUS Client wrote to peer. */
108 
109 /**@brief Flow control state for GUS Client service. */
111 {
112  GUS_C_FLOW_CTRL_STATE_OFF = 0, /**< Indicate that GUS Client can not receive data from peer. */
113  GUS_C_FLOW_CTRL_STATE_ON /**< Indicate that GUS Client can receive data from peer. */
114 };
115 /**@brief Underlying type used for the GUS Client flow control state. */
116 typedef uint8_t gus_c_flow_ctrl_state_t;
117 /** @} */
118 
119 /**
120  * @defgroup GUS_C_STRUCT Structures
121  * @{
122  */
123 /**@brief Handles on the connected peer device needed to interact with it. */
124 typedef struct
125 {
126  uint16_t gus_srvc_start_handle; /**< GUS Service start handle. */
127  uint16_t gus_srvc_end_handle; /**< GUS Service end handle. */
128  uint16_t gus_tx_handle; /**< Handle of GUS Tx characteristic as provided by a discovery. */
129  uint16_t gus_tx_cccd_handle; /**< Handle of CCCD of GUS Tx characteristic as provided by a discovery. */
130  uint16_t gus_rx_handle; /**< Handle of GUS Rx characteristic as provided by a discovery. */
131  uint16_t gus_flow_ctrl_handle; /**< Handle of GUS Flow Control characteristic as provided by a discovery. */
132  uint16_t gus_flow_ctrl_cccd_handle; /**< Handle of CCCD of GUS Flow Control characteristic as provided by a discovery. */
134 
135 /**@brief Goodix UART Service Client event. */
136 typedef struct
137 {
138  uint8_t conn_idx; /**< Connection index. */
139  gus_c_evt_type_t evt_type; /**< GUS Client event type. */
140  uint16_t length; /**< Length of event data. */
141  uint8_t *p_data; /**< Pointer to event data. */
142 } gus_c_evt_t;
143 /** @} */
144 
145 /**
146  * @defgroup GUS_C_TYPEDEF Typedefs
147  * @{
148  */
149 /**@brief Goodix UART Service Client event handler type. */
150 typedef void (* gus_c_evt_handler_t)(gus_c_evt_t *p_evt);
151 /** @} */
152 
153 /**
154  * @defgroup GUS_C_FUNCTION Functions
155  * @{
156  */
157 /**
158  *****************************************************************************************
159  * @brief Register GUS Client event handler.
160  *
161  * @param[in] evt_handler: Goodix UART Service Client event handler.
162  *
163  * @return Result of initialization.
164  *****************************************************************************************
165  */
167 
168 /**
169  *****************************************************************************************
170  * @brief Discovery GUS on peer.
171  *
172  * @param[in] conn_idx: Index of connection.
173  *
174  * @return Operation result.
175  *****************************************************************************************
176  */
178 
179 /**
180  *****************************************************************************************
181  * @brief Enable or disable peer GUS Tx characteristic notify.
182  *
183  * @param[in] conn_idx: Connection index.
184  * @param[in] is_enable: Enable or disable ths Tx notify.
185  *
186  * @return Operation result.
187  *****************************************************************************************
188  */
189 sdk_err_t gus_c_tx_notify_set(uint8_t conn_idx, bool is_enable);
190 
191 /**
192  *****************************************************************************************
193  * @brief Enable or disable peer device GUS flow control notify.
194  *
195  * @param[in] conn_idx: Connection index.
196  * @param[in] is_enable: Enable or disable ths Tx notify.
197  *
198  * @return Operation result.
199  *****************************************************************************************
200  */
201 sdk_err_t gus_c_flow_ctrl_notify_set(uint8_t conn_idx, bool is_enable);
202 
203 /**
204  *****************************************************************************************
205  * @brief Send data to the server.
206  *
207  * @param[in] conn_idx: Connection index.
208  * @param[in] p_data: Pointer to data need sent.
209  * @param[in] length: Length of data need sent.
210  *
211  * @return Operation result.
212  *****************************************************************************************
213  */
214 sdk_err_t gus_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
215 
216 /**
217  *****************************************************************************************
218  * @brief Send GUS Client Rx flow control state to peer device
219  *
220  * @param[in] conn_idx: Connection index.
221  * @param[in] flow_ctrl: GUS client Rx flow control state.
222  *
223  * @return Result of sending gus_c Rx flow control state.
224  *****************************************************************************************
225  */
227 /** @} */
228 #endif
229 /** @} */
230 /** @} */
231 
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:103
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:98
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:104
GUS_C_FLOW_CTRL_STATE_OFF
@ GUS_C_FLOW_CTRL_STATE_OFF
Indicate that GUS Client can not receive data from peer.
Definition: gus_c.h:112
gus_c_evt_t::p_data
uint8_t * p_data
Pointer to event data.
Definition: gus_c.h:141
gus_c_rx_flow_ctrl_set
sdk_err_t gus_c_rx_flow_ctrl_set(uint8_t conn_idx, gus_c_flow_ctrl_state_t flow_ctrl)
Send GUS Client Rx flow control state to peer device.
gus_c_evt_t::conn_idx
uint8_t conn_idx
Connection index.
Definition: gus_c.h:138
GUS_C_EVT_DISCOVERY_COMPLETE
@ GUS_C_EVT_DISCOVERY_COMPLETE
GUS Client has found service and its characteristics at peer.
Definition: gus_c.h:97
gus_c_handles_t::gus_srvc_end_handle
uint16_t gus_srvc_end_handle
GUS Service end handle.
Definition: gus_c.h:127
gr_includes.h
Include Files API.
GUS_C_EVT_PEER_DATA_RECEIVE
@ GUS_C_EVT_PEER_DATA_RECEIVE
GUS Client has received something from peer.
Definition: gus_c.h:101
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:130
gus_c_evt_t::length
uint16_t length
Length of event data.
Definition: gus_c.h:140
GUS_C_EVT_TX_CPLT
@ GUS_C_EVT_TX_CPLT
GUS Client has sent something to peer successfully.
Definition: gus_c.h:102
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:132
gus_c_flow_ctrl_state_t
uint8_t gus_c_flow_ctrl_state_t
Underlying type used for the GUS Client flow control state.
Definition: gus_c.h:116
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:128
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:96
gus_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: gus_c.h:125
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:106
gus_c_evt_type_t
gus_c_evt_type_t
Goodix UART Service Client event type.
Definition: gus_c.h:95
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:105
ble_prf_types.h
Profile/Service Common Types.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
GUS_C_FLOW_CTRL_STATE_ON
@ GUS_C_FLOW_CTRL_STATE_ON
Indicate that GUS Client can receive data from peer.
Definition: gus_c.h:113
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:129
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:131
gus_c_evt_t
Goodix UART Service Client event.
Definition: gus_c.h:137
gus_c_evt_t::evt_type
gus_c_evt_type_t evt_type
GUS Client event type.
Definition: gus_c.h:139
gus_c_handles_t::gus_srvc_start_handle
uint16_t gus_srvc_start_handle
GUS Service start handle.
Definition: gus_c.h:126
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_c_flow_ctrl_state
gus_c_flow_ctrl_state
Flow control state for GUS Client service.
Definition: gus_c.h:111
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:100
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:150
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:99
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.