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