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. */
95 
96 /**@brief Flow control state for GUS service. */
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  */
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  */
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  */
184 /** @} */
185 
186 #endif
187 /** @} */
188 /** @} */
gus_init_t
Goodix UART Service init stucture. This contains all option and data needed for initialization of the...
Definition: gus.h:134
GUS_EVT_TX_FLOW_OFF
@ GUS_EVT_TX_FLOW_OFF
Definition: gus.h:92
GUS_EVT_TX_DATA_SENT
@ GUS_EVT_TX_DATA_SENT
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
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
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
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
Definition: gus.h:86
GUS_EVT_TX_PORT_CLOSED
@ GUS_EVT_TX_PORT_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
Definition: gus.h:100
gus_evt_t::length
uint16_t length
Definition: gus.h:116
GUS_EVT_INVALID
@ GUS_EVT_INVALID
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
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
Definition: gus.h:113
GUS_FLOW_CTRL_STATE_OFF
@ GUS_FLOW_CTRL_STATE_OFF
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
Definition: gus.h:114
GUS_EVT_FLOW_CTRL_DISABLE
@ GUS_EVT_FLOW_CTRL_DISABLE
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
Definition: gus.h:115