mlmr.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file mlmr.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 "gr55xx_sys.h"
65 #include "custom_config.h"
66
67 /**
68 * @defgroup GUS_MACRO Defines
69 * @{
70 */
71 #define GUS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
72 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Goodix UART Service connections. */
73 #define FLOW_ON 0x01 /**< Indicate that GUS can receive data from peer. */
74 #define FLOW_OFF 0x00 /**< Indicate that GUS can not receive data from peer. */
75 #define GUS_MAX_DATA_LEN 247 /**< Maximum length of application data packet which is transmitted via GUS. */
76 #define GUS_FLOW_CTRL_LEN 1 /**< Maximum length of ble flow control data packet which is transmitted via GUS. */
77 #define GUS_SERVICE_UUID 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
78 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x02, 0xED, 0xA6 /**< The UUID of Goodix UART Service for setting advertising data. */
79 /** @} */
80
81 /**
82 * @defgroup GUS_ENUM Enumerations
83 * @{
84 */
85 /**@brief Goodix UART Service event types. */
86 typedef enum
87 {
88 GUS_EVT_INVALID, /**< Invalid GUS event. */
89 GUS_EVT_RX_DATA_RECEIVED, /**< The data from the peer has been received. */
90 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. */
91 GUS_EVT_TX_PORT_OPENED, /**< Tx port has been opened. */
92 GUS_EVT_TX_PORT_CLOSED, /**< Tx port has been closed. */
93 GUS_EVT_FLOW_CTRL_ENABLE, /**< GUS flow control been enabled. */
94 GUS_EVT_FLOW_CTRL_DISABLE, /**< GUS flow control been disabled. */
95 GUS_EVT_TX_FLOW_OFF, /**< Tx flow off control request. */
96 GUS_EVT_TX_FLOW_ON, /**< Tx flow on control request. */
97 } gus_evt_type_t;
98 /** @} */
99
100 /**
101 * @defgroup GUS_STRUCT Structures
102 * @{
103 */
104 /**@brief Goodix UART Service event. */
105 typedef struct
106 {
107 gus_evt_type_t evt_type; /**< The GUS event. */
108 uint8_t conn_idx; /**< The index of the connection for the data transmission. */
109 uint8_t *p_data; /**< Pointer to the buffer within received data. */
110 uint16_t length; /**< Length of received data. */
111 } gus_evt_t;
112 /** @} */
113
114 /**
115 * @defgroup GUS_TYPEDEF Typedefs
116 * @{
117 */
118 /**@brief Goodix UART Service event handler type. */
119 typedef void (*gus_evt_handler_t)(gus_evt_t *p_evt);
120 /** @} */
121
122 /**
123 * @addtogroup GUS_STRUCT Structures
124 * @{
125 */
126 /**@brief Goodix UART Service init stucture. This contains all option and data needed for initialization of the service. */
127 typedef struct
128 {
129 gus_evt_handler_t evt_handler; /**< Goodix UART Service event handler which must be provided by the application to send and receive the data. */
130 } gus_init_t;
131 /** @} */
132
133 /**
134 * @defgroup GUS_FUNCTION Functions
135 * @{
136 */
137 /**
138 *****************************************************************************************
139 * @brief Initialize a Goodix UART Service instance and add in the database.
140 *
141 * @param[in] p_gus_init: Pointer to Goodix UART Service initialization variables.
142 *
143 * @return Result of service initialization.
144 *****************************************************************************************
145 */
146 sdk_err_t gus_service_init(gus_init_t *p_gus_init);
147
148 /**
149 *****************************************************************************************
150 * @brief Send data to peer device.
151 *
152 * @param[in] conn_idx: Index of the connection.
153 * @param[in] p_data: Pointer to sent data.
154 * @param[in] length: Length of sent data.
155 *
156 * @return Result of sending data.
157 *****************************************************************************************
158 */
159 sdk_err_t gus_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
160
161 /**
162 *****************************************************************************************
163 * @brief Send GUS Rx flow control state to peer device
164 *
165 * @param[in] conn_idx: Index of the connection.
166 * @param[in] flow_ctrl: GUS Rx flow control state
167 *
168 * @return Result of sending GUS Rx flow control state.
169 *****************************************************************************************
170 */
171 sdk_err_t gus_rx_flow_ctrl_set(uint8_t conn_idx, uint8_t flow_ctrl);
172 /** @} */
173
174 #endif
175 /** @} */
176 /** @} */
gus_init_t
Goodix UART Service init stucture.
Definition: gus.h:128
GUS_EVT_TX_FLOW_OFF
@ GUS_EVT_TX_FLOW_OFF
Tx flow off control request.
Definition: mlmr.h:95
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: mlmr.h:90
GUS_EVT_TX_PORT_OPENED
@ GUS_EVT_TX_PORT_OPENED
Tx port has been opened.
Definition: mlmr.h:91
gus_evt_handler_t
void(* gus_evt_handler_t)(gus_evt_t *p_evt)
Goodix UART Service event handler type.
Definition: mlmr.h:119
gr55xx_sys.h
GR55XX System API.
GUS_EVT_FLOW_CTRL_ENABLE
@ GUS_EVT_FLOW_CTRL_ENABLE
GUS flow control been enabled.
Definition: mlmr.h:93
GUS_EVT_RX_DATA_RECEIVED
@ GUS_EVT_RX_DATA_RECEIVED
The data from the peer has been received.
Definition: mlmr.h:89
GUS_EVT_TX_PORT_CLOSED
@ GUS_EVT_TX_PORT_CLOSED
Tx port has been closed.
Definition: mlmr.h:92
gus_evt_type_t
gus_evt_type_t
Goodix UART Service event types.
Definition: mlmr.h:87
GUS_EVT_INVALID
@ GUS_EVT_INVALID
Invalid GUS event.
Definition: mlmr.h:88
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: mlmr.h:96
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
gus_rx_flow_ctrl_set
sdk_err_t gus_rx_flow_ctrl_set(uint8_t conn_idx, uint8_t flow_ctrl)
Send GUS Rx flow control state to peer device.
gus_evt_t
Goodix UART Service event.
Definition: gus.h:106
GUS_EVT_FLOW_CTRL_DISABLE
@ GUS_EVT_FLOW_CTRL_DISABLE
GUS flow control been disabled.
Definition: mlmr.h:94
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.