gus.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file gus.h
5 *
6 * @brief Goodix UART 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_GUS Goodix UART Service (GUS)
46 * @{
47 * @brief Definitions and prototypes for the GUS interface.
48 *
49 * @details The Goodix UART Service is a customized GATT-based service with Tx, Rx and Flow Control
50 * characteristics. The application uses the service to send and receive data to and
51 * from the peer. The application data is sent to the peer as Handle Value Notification,
52 * and the data received from the peer is transmitted with GATT Write Command.
53 *
54 * After \ref gus_init_t variable is initialized , the application must call \ref gus_service_init()
55 * to add the Goodix Uart Service and Rx, Tx, Flow Control characteristics to the BLE Stack
56 * database. The application can send the data to the peer with \ref gus_tx_data_send() after
57 * \ref GUS_EVT_TX_PORT_OPENED received. The application should copy the received data to its own buffer
58 * when handling \ref GUS_EVT_RX_DATA_RECEIVED.
59 */
60
61 #ifndef __GUS_H__
62 #define __GUS_H__
63
64 #include "gr_includes.h"
65 #include "custom_config.h"
66
67 /**
68 * @defgroup GUS_MACRO Defines
69 * @{
70 */
71 #define GUS_CONNECTION_MAX 10 /**< Maximum number of Goodix UART Service connections. */
72 #define GUS_MAX_DATA_LEN 247 /**< Maximum length of application data packet which is transmitted via GUS. */
73 #define GUS_FLOW_CTRL_LEN 1 /**< Maximum length of ble flow control data packet which is transmitted via GUS. */
74 #define GUS_SERVICE_UUID 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
75 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x02, 0xED, 0xA6 /**< The UUID of Goodix UART Service for setting advertising data. */
76 /** @} */
77
78 /**
79 * @defgroup GUS_ENUM Enumerations
80 * @{
81 */
82 /**@brief Goodix UART Service event types. */
83 typedef enum
84 {
85 GUS_EVT_INVALID, /**< Invalid GUS event. */
86 GUS_EVT_RX_DATA_RECEIVED, /**< The data from the peer has been received. */
87 GUS_EVT_TX_DATA_SENT, /**< The data from the application has been sent, and the service is ready to accept new data from the application. */
88 GUS_EVT_TX_PORT_OPENED, /**< Tx port has been opened. */
89 GUS_EVT_TX_PORT_CLOSED, /**< Tx port has been closed. */
90 GUS_EVT_FLOW_CTRL_ENABLE, /**< GUS flow control been enabled. */
91 GUS_EVT_FLOW_CTRL_DISABLE, /**< GUS flow control been disabled. */
92 GUS_EVT_TX_FLOW_OFF, /**< Tx flow off control request. */
93 GUS_EVT_TX_FLOW_ON, /**< Tx flow on control request. */
94 } gus_evt_type_t;
95
96 /**@brief Flow control state for GUS service. */
97 enum gus_flow_ctrl_state
98 {
99 GUS_FLOW_CTRL_STATE_OFF = 0, /**< Indicate that GUS can not receive data from peer. */
100 GUS_FLOW_CTRL_STATE_ON /**< Indicate that GUS can receive data from peer. */
101 };
102 /**@brief Underlying type used for the GUS flow control state. */
103 typedef uint8_t gus_flow_ctrl_state_t;
104 /** @} */
105
106 /**
107 * @defgroup GUS_STRUCT Structures
108 * @{
109 */
110 /**@brief Goodix UART Service event. */
111 typedef struct
112 {
113 gus_evt_type_t evt_type; /**< The GUS event. */
114 uint8_t conn_idx; /**< The index of the connection for the data transmission. */
115 uint8_t *p_data; /**< Pointer to the buffer within received data. */
116 uint16_t length; /**< Length of received data. */
117 } gus_evt_t;
118 /** @} */
119
120 /**
121 * @addtogroup GUS_TYPEDEF Typedefs
122 * @{
123 */
124 /**@brief Goodix UART Service event handler type. */
125 typedef void (*gus_evt_handler_t)(gus_evt_t *p_evt);
126 /** @} */
127
128 /**
129 * @addtogroup GUS_STRUCT Structures
130 * @{
131 */
132 /**@brief Goodix UART Service init stucture. This contains all option and data needed for initialization of the service. */
133 typedef struct
134 {
135 gus_evt_handler_t evt_handler; /**< Goodix UART Service event handler which must be provided by the application to send and receive the data. */
136 } gus_init_t;
137 /** @} */
138
139 /**
140 * @defgroup GUS_FUNCTION Functions
141 * @{
142 */
143 /**
144 *****************************************************************************************
145 * @brief Initialize a Goodix UART Service instance and add in the database.
146 *
147 * @param[in] p_gus_init: Pointer to Goodix UART Service initialization variables.
148 *
149 * @return Result of service initialization.
150 *****************************************************************************************
151 */
152 sdk_err_t gus_service_init(gus_init_t *p_gus_init);
153
154 /**
155 *****************************************************************************************
156 * @brief Send data to peer device.
157 *
158 * @param[in] conn_idx: Index of the connection.
159 * @param[in] p_data: Pointer to sent data.
160 * @param[in] length: Length of sent data.
161 *
162 * @return Result of sending data.
163 *****************************************************************************************
164 */
165 sdk_err_t gus_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
166
167 /**
168 *****************************************************************************************
169 * @brief Send GUS Rx flow control state to peer device
170 *
171 * @return Result of sending GUS Rx flow control state.
172 *****************************************************************************************
173 */
174 sdk_err_t gus_rx_flow_ctrl_set(uint8_t conn_idx, gus_flow_ctrl_state_t flow_ctrl);
175
176 /**
177 *****************************************************************************************
178 * @brief Provide the interface for other modules to obtain the gus service start handle .
179 *
180 * @return The gus service start handle.
181 *****************************************************************************************
182 */
183 uint16_t gus_service_start_handle_get(void);
184 /** @} */
185
186 #endif
187 /** @} */
188 /** @} */
gus_init_t
Goodix UART Service init stucture.
Definition: gus.h:134
GUS_EVT_TX_FLOW_OFF
@ GUS_EVT_TX_FLOW_OFF
Tx flow off control request.
Definition: gus.h:92
GUS_EVT_TX_DATA_SENT
@ GUS_EVT_TX_DATA_SENT
The data from the application has been sent, and the service is ready to accept new data from the app...
Definition: gus.h:87
gus_rx_flow_ctrl_set
sdk_err_t gus_rx_flow_ctrl_set(uint8_t conn_idx, gus_flow_ctrl_state_t flow_ctrl)
Send GUS Rx flow control state to peer device.
GUS_EVT_TX_PORT_OPENED
@ GUS_EVT_TX_PORT_OPENED
Tx port has been opened.
Definition: gus.h:88
gus_evt_handler_t
void(* gus_evt_handler_t)(gus_evt_t *p_evt)
Goodix UART Service event handler type.
Definition: gus.h:125
gus_init_t::evt_handler
gus_evt_handler_t evt_handler
Goodix UART Service event handler which must be provided by the application to send and receive the d...
Definition: gus.h:135
gr_includes.h
Include Files API.
gus_flow_ctrl_state_t
uint8_t gus_flow_ctrl_state_t
Underlying type used for the GUS flow control state.
Definition: gus.h:103
GUS_EVT_FLOW_CTRL_ENABLE
@ GUS_EVT_FLOW_CTRL_ENABLE
GUS flow control been enabled.
Definition: gus.h:90
gus_service_start_handle_get
uint16_t gus_service_start_handle_get(void)
Provide the interface for other modules to obtain the gus service start handle .
GUS_EVT_RX_DATA_RECEIVED
@ GUS_EVT_RX_DATA_RECEIVED
The data from the peer has been received.
Definition: gus.h:86
GUS_EVT_TX_PORT_CLOSED
@ GUS_EVT_TX_PORT_CLOSED
Tx port has been closed.
Definition: gus.h:89
gus_evt_type_t
gus_evt_type_t
Goodix UART Service event types.
Definition: gus.h:84
GUS_FLOW_CTRL_STATE_ON
@ GUS_FLOW_CTRL_STATE_ON
Indicate that GUS can receive data from peer.
Definition: gus.h:100
gus_evt_t::length
uint16_t length
Length of received data.
Definition: gus.h:116
GUS_EVT_INVALID
@ GUS_EVT_INVALID
Invalid GUS event.
Definition: gus.h:85
gus_service_init
sdk_err_t gus_service_init(gus_init_t *p_gus_init)
Initialize a Goodix UART Service instance and add in the database.
GUS_EVT_TX_FLOW_ON
@ GUS_EVT_TX_FLOW_ON
Tx flow on control request.
Definition: gus.h:93
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
gus_evt_t::evt_type
gus_evt_type_t evt_type
The GUS event.
Definition: gus.h:113
GUS_FLOW_CTRL_STATE_OFF
@ GUS_FLOW_CTRL_STATE_OFF
Indicate that GUS can not receive data from peer.
Definition: gus.h:99
gus_evt_t
Goodix UART Service event.
Definition: gus.h:112
gus_flow_ctrl_state
gus_flow_ctrl_state
Flow control state for GUS service.
Definition: gus.h:98
gus_evt_t::conn_idx
uint8_t conn_idx
The index of the connection for the data transmission.
Definition: gus.h:114
GUS_EVT_FLOW_CTRL_DISABLE
@ GUS_EVT_FLOW_CTRL_DISABLE
GUS flow control been disabled.
Definition: gus.h:91
gus_tx_data_send
sdk_err_t gus_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to peer device.
gus_evt_t::p_data
uint8_t * p_data
Pointer to the buffer within received data.
Definition: gus.h:115