ths_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file ths_c.h
5 *
6 * @brief Throughput Client 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 */
42
43 /**
44 * @defgroup BLE_SDK_THS_C Throughput Service Client (THS_C)
45 * @{
46 * @brief THS Client Interface module.
47 *
48 * @details The Throughput Service Client contains the APIs and types, which can be used by the
49 * application to perform scanning, connection and discovery of Throughput Service at peer and
50 * interact with it.
51 *
52 * The application must provide to register, then call \ref ths_client_init(). After the module can
53 * send setting parameters and throughput data to peer, it will notify application.
54 * It includes only Throughput Service notify data, only Throughput Service Client write data
55 * and both send data test mode \ref ths_c_transport_mode_t.
56 */
57
58 #ifndef __THS_C_H__
59 #define __THS_C_H__
60
61 #include "ble_prf_types.h"
62 #include "gr55xx_sys.h"
63 #include "custom_config.h"
64 #include <stdint.h>
65 #include <stdbool.h>
66
67 /**
68 * @defgroup THS_C_MACRO Defines
69 * @{
70 */
71 /**
72 * @defgroup THS_UUID THS UUIDs
73 * @{
74 * @brief THS service and characteristcs UUID.
75 */
76 #define THS_C_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
77 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of THS Client connections. */
78 #define THS_SVC_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
79 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x03, 0xED, 0xA6} /**< UUID of THS Service. */
80 #define THS_TX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
81 0x0A, 0x46, 0x44, 0xD3, 0x02, 0x03, 0xED, 0xA6} /**< UUID of THS Tx Characteristic. */
82 #define THS_RX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
83 0x0A, 0x46, 0x44, 0xD3, 0x03, 0x03, 0xED, 0xA6} /**< UUID of THS Rx Characteristic. */
84 #define THS_SETTING_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
85 0x0A, 0x46, 0x44, 0xD3, 0x04, 0x03, 0xED, 0xA6} /**< UUID of THS Setting Characteristic. */
86 #define THS_TOGGLE_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
87 0x0A, 0x46, 0x44, 0xD3, 0x05, 0x03, 0xED, 0xA6} /**< UUID of THS Toggle Characteristic. */
88 /** @} */
89 /** @} */
90
91 /**
92 * @defgroup THS_C_ENUM Enumerations
93 * @{
94 */
95 /**@brief Throughput Service Client data transport mode. */
96 typedef enum
97 {
98 THS_C_SLAVE_NOTIFY_MODE, /** The device recieves data from the peer via notify. */
99 THS_C_MASTER_WRITE_MODE, /** The device writes data to the peer. */
100 THS_C_DOUBLE_MODE, /** The device recieve data from the peer via notify and write data to the peer at the same time. */
101 } ths_c_transport_mode_t;
102
103 /**@brief Throughput service settings types. */
104 typedef enum
105 {
106 THS_C_SETTINGS_TYPE_CI, /**< BLE Connection Interval parameter. */
107 THS_C_SETTINGS_TYPE_MTU, /**< MTU Size. */
108 THS_C_SETTINGS_TYPE_PDU, /**< PDU Size. */
109 THS_C_SETTINGS_TYPE_PHY, /**< Radio Phy mode, 1M, 2M, Encoded. */
110 THS_C_SETTINGS_TYPE_TRANS_MODE, /**< Data transmission mode. */
111 THS_C_SETTINGS_TYPE_TX_POWER, /**< Connect Tx power. */
112 } ths_c_settings_type_t;
113
114 /**@brief Throughput Service Client event type. */
115 typedef enum
116 {
117 THS_C_EVT_INVALID, /**< THS Client invalid event. */
118 THS_C_EVT_DISCOVERY_COMPLETE, /**< THS Client has found THS service and its characteristics. */
119 THS_C_EVT_DISCOVERY_FAIL, /**< THS Client found THS service failed because of invalid operation or no found at the peer. */
120 THS_C_EVT_TX_NTF_SET_SUCCESS, /**< THS Client has set peer Tx notify. */
121 THS_C_EVT_SETTING_NTF_SET_SUCCESS, /**< THS Client has set peer Settings notify. */
122 THS_C_EVT_TOGGLE_SET_SUCCESS, /**< THS Client has set toggle no. */
123 THS_C_EVT_SETTING_RSP_RECEIVE, /**< THS CLient has received response of parameter set. */
124 THS_C_EVT_THRP_DATA_RECEIVE, /**< THS Client has received throughput data from peer. */
125 THS_C_EVT_TX_SUCCESS, /**< THS Client has sent something to a peer successfully. */
126 THS_C_EVT_PARAM_SET_SUCCESS, /**< THS Client has set parameter for connection and transport mode. */
127 THS_C_EVT_WRITE_OP_ERR, /**< Error occured when THS Client writen to peer. */
128 } ths_c_evt_type_t;
129 /** @} */
130
131 /**
132 * @defgroup THS_C_STRUCT Structures
133 * @{
134 */
135 /**@brief Handles on the connected peer device needed to interact with it. */
136 typedef struct
137 {
138 uint16_t ths_srvc_start_handle; /**< THS Service start handle. */
139 uint16_t ths_srvc_end_handle; /**< THS Service end handle. */
140 uint16_t ths_tx_handle; /**< THS Tx characteristic handle which has been got from peer. */
141 uint16_t ths_tx_cccd_handle; /**< THS Tx characteristic CCCD handle which has been got from peer. */
142 uint16_t ths_rx_handle; /**< THS Rx characteristic handle which has been got from peer. */
143 uint16_t ths_setting_handle; /**< THS setting characteristic handle which has been got from peer. */
144 uint16_t ths_setting_cccd_handle; /**< THS setting characteristic CCCD handle which has been got from peer. */
145 uint16_t ths_toggle_handle; /**< THS toggle characteristic handle which has been got from peer. */
146 } ths_c_handles_t;
147
148 /**@brief Throughput Service Client event. */
149 typedef struct
150 {
151 uint8_t conn_idx; /**< The connection index. */
152 ths_c_evt_type_t evt_type; /**< THS client event type. */
153 uint8_t *p_data; /**< Pointer to event data. */
154 uint16_t length; /**< Length of event data. */
155 } ths_c_evt_t;
156 /** @} */
157
158 /**
159 * @defgroup THS_C_TYPEDEF Typedefs
160 * @{
161 */
162 /**@brief Throughput Service Client event handler type. */
163 typedef void (*ths_c_evt_handler_t)(ths_c_evt_t *p_evt);
164 /** @} */
165
166 /**
167 * @defgroup THS_C_FUNCTION Functions
168 * @{
169 */
170 /**
171 *****************************************************************************************
172 * @brief Register THS Client event handler.
173 *
174 * @param[in] evt_handler: Throughput Service Client event handler.
175 *
176 * @return Result of initialization.
177 *****************************************************************************************
178 */
179 sdk_err_t ths_client_init(ths_c_evt_handler_t evt_handler);
180
181 /**
182 *****************************************************************************************
183 * @brief Discovery THS on peer.
184 *
185 * @param[in] conn_idx: Index of connection.
186 *
187 * @return Operation result.
188 *****************************************************************************************
189 */
190 sdk_err_t ths_c_disc_srvc_start(uint8_t conn_idx);
191
192 /**
193 *****************************************************************************************
194 * @brief Enable or disable peer THS Tx characteristic notify.
195 *
196 * @param[in] conn_idx: Connection index.
197 * @param[in] is_enable: Enable or disable THS Tx notify.
198 *
199 * @return Operation result.
200 *****************************************************************************************
201 */
202 sdk_err_t ths_c_tx_notify_set(uint8_t conn_idx, bool is_enable);
203
204 /**
205 *****************************************************************************************
206 * @brief Enable or disable peer THS setting characteristic notify.
207 *
208 * @param[in] conn_idx: Connection index.
209 * @param[in] is_enable: Enable or disable THS setting notify.
210 *
211 * @return Operation result.
212 *****************************************************************************************
213 */
214 sdk_err_t ths_c_setting_notify_set(uint8_t conn_idx, bool is_enable);
215
216 /**
217 *****************************************************************************************
218 * @brief Send communication parameter to peer.
219 *
220 * @param[in] conn_idx: Connection index.
221 * @param[in] p_data: Pointer to communication parameter data need sent.
222 * @param[in] length: Length of communication parameter data need sent.
223 *
224 * @return Operation result.
225 *****************************************************************************************
226 */
227 sdk_err_t ths_c_comm_param_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
228
229 /**
230 *****************************************************************************************
231 * @brief Set Throughput service toggle state of sending the data.
232 *
233 * @param[in] conn_idx: Connection index.
234 * @param[in] is_enable: Enable or disable toggle.
235 *
236 * @return Operation result.
237 *****************************************************************************************
238 */
239 sdk_err_t ths_c_toggle_set(uint8_t conn_idx, bool is_enable);
240
241 /**
242 *****************************************************************************************
243 * @brief Send data to peer.
244 *
245 * @param[in] conn_idx: Connection index.
246 * @param[in] p_data: Pointer to data need sent.
247 * @param[in] length: Length of data need sent.
248 *
249 * @return Operation result.
250 *****************************************************************************************
251 */
252 sdk_err_t ths_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
253 /** @} */
254 #endif
255 /** @} */
256 /** @} */
THS_C_EVT_SETTING_NTF_SET_SUCCESS
@ THS_C_EVT_SETTING_NTF_SET_SUCCESS
THS Client has set peer Settings notify.
Definition: ths_c.h:121
THS_C_EVT_PARAM_SET_SUCCESS
@ THS_C_EVT_PARAM_SET_SUCCESS
THS Client has set parameter for connection and transport mode.
Definition: ths_c.h:126
ths_c_evt_t::length
uint16_t length
Length of event data.
Definition: ths_c.h:154
ths_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: ths_c.h:151
ths_c_handles_t::ths_srvc_start_handle
uint16_t ths_srvc_start_handle
THS Service start handle.
Definition: ths_c.h:138
THS_C_SLAVE_NOTIFY_MODE
@ THS_C_SLAVE_NOTIFY_MODE
Definition: ths_c.h:98
ths_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: ths_c.h:137
ths_c_evt_t::evt_type
ths_c_evt_type_t evt_type
THS client event type.
Definition: ths_c.h:152
THS_C_EVT_TOGGLE_SET_SUCCESS
@ THS_C_EVT_TOGGLE_SET_SUCCESS
THS Client has set toggle no.
Definition: ths_c.h:122
THS_C_SETTINGS_TYPE_TX_POWER
@ THS_C_SETTINGS_TYPE_TX_POWER
Connect Tx power.
Definition: ths_c.h:111
THS_C_SETTINGS_TYPE_MTU
@ THS_C_SETTINGS_TYPE_MTU
MTU Size.
Definition: ths_c.h:107
THS_C_SETTINGS_TYPE_TRANS_MODE
@ THS_C_SETTINGS_TYPE_TRANS_MODE
Data transmission mode.
Definition: ths_c.h:110
ths_c_setting_notify_set
sdk_err_t ths_c_setting_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer THS setting characteristic notify.
THS_C_EVT_INVALID
@ THS_C_EVT_INVALID
THS Client invalid event.
Definition: ths_c.h:117
THS_C_EVT_DISCOVERY_COMPLETE
@ THS_C_EVT_DISCOVERY_COMPLETE
THS Client has found THS service and its characteristics.
Definition: ths_c.h:118
ths_c_evt_handler_t
void(* ths_c_evt_handler_t)(ths_c_evt_t *p_evt)
Throughput Service Client event handler type.
Definition: ths_c.h:163
gr55xx_sys.h
GR55XX System API.
THS_C_EVT_TX_SUCCESS
@ THS_C_EVT_TX_SUCCESS
THS Client has sent something to a peer successfully.
Definition: ths_c.h:125
ths_c_handles_t::ths_rx_handle
uint16_t ths_rx_handle
THS Rx characteristic handle which has been got from peer.
Definition: ths_c.h:142
THS_C_EVT_SETTING_RSP_RECEIVE
@ THS_C_EVT_SETTING_RSP_RECEIVE
THS CLient has received response of parameter set.
Definition: ths_c.h:123
ths_c_evt_t
Throughput Service Client event.
Definition: ths_c.h:150
ths_c_handles_t::ths_setting_handle
uint16_t ths_setting_handle
THS setting characteristic handle which has been got from peer.
Definition: ths_c.h:143
ths_client_init
sdk_err_t ths_client_init(ths_c_evt_handler_t evt_handler)
Register THS Client event handler.
ths_c_handles_t::ths_srvc_end_handle
uint16_t ths_srvc_end_handle
THS Service end handle.
Definition: ths_c.h:139
ths_c_handles_t::ths_tx_cccd_handle
uint16_t ths_tx_cccd_handle
THS Tx characteristic CCCD handle which has been got from peer.
Definition: ths_c.h:141
ths_c_evt_t::p_data
uint8_t * p_data
Pointer to event data.
Definition: ths_c.h:153
ths_c_evt_type_t
ths_c_evt_type_t
Throughput Service Client event type.
Definition: ths_c.h:116
ths_c_handles_t::ths_setting_cccd_handle
uint16_t ths_setting_cccd_handle
THS setting characteristic CCCD handle which has been got from peer.
Definition: ths_c.h:144
ths_c_handles_t::ths_toggle_handle
uint16_t ths_toggle_handle
THS toggle characteristic handle which has been got from peer.
Definition: ths_c.h:145
THS_C_EVT_THRP_DATA_RECEIVE
@ THS_C_EVT_THRP_DATA_RECEIVE
THS Client has received throughput data from peer.
Definition: ths_c.h:124
ble_prf_types.h
Profile/Service Common Types.
ths_c_comm_param_send
sdk_err_t ths_c_comm_param_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send communication parameter to peer.
THS_C_SETTINGS_TYPE_PHY
@ THS_C_SETTINGS_TYPE_PHY
Radio Phy mode, 1M, 2M, Encoded.
Definition: ths_c.h:109
THS_C_EVT_DISCOVERY_FAIL
@ THS_C_EVT_DISCOVERY_FAIL
THS Client found THS service failed because of invalid operation or no found at the peer.
Definition: ths_c.h:119
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
THS_C_SETTINGS_TYPE_PDU
@ THS_C_SETTINGS_TYPE_PDU
PDU Size.
Definition: ths_c.h:108
THS_C_DOUBLE_MODE
@ THS_C_DOUBLE_MODE
The device writes data to the peer.
Definition: ths_c.h:100
THS_C_MASTER_WRITE_MODE
@ THS_C_MASTER_WRITE_MODE
The device recieves data from the peer via notify.
Definition: ths_c.h:99
ths_c_disc_srvc_start
sdk_err_t ths_c_disc_srvc_start(uint8_t conn_idx)
Discovery THS on peer.
ths_c_transport_mode_t
ths_c_transport_mode_t
Throughput Service Client data transport mode.
Definition: ths_c.h:97
ths_c_toggle_set
sdk_err_t ths_c_toggle_set(uint8_t conn_idx, bool is_enable)
Set Throughput service toggle state of sending the data.
ths_c_handles_t::ths_tx_handle
uint16_t ths_tx_handle
THS Tx characteristic handle which has been got from peer.
Definition: ths_c.h:140
THS_C_EVT_WRITE_OP_ERR
@ THS_C_EVT_WRITE_OP_ERR
Error occured when THS Client writen to peer.
Definition: ths_c.h:127
THS_C_SETTINGS_TYPE_CI
@ THS_C_SETTINGS_TYPE_CI
BLE Connection Interval parameter.
Definition: ths_c.h:106
ths_c_tx_data_send
sdk_err_t ths_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to peer.
ths_c_tx_notify_set
sdk_err_t ths_c_tx_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer THS Tx characteristic notify.
ths_c_settings_type_t
ths_c_settings_type_t
Throughput service settings types.
Definition: ths_c.h:105
THS_C_EVT_TX_NTF_SET_SUCCESS
@ THS_C_EVT_TX_NTF_SET_SUCCESS
THS Client has set peer Tx notify.
Definition: ths_c.h:120