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. */
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. */
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. */
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. */
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  */
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  */
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
Definition: ths_c.h:120
THS_C_EVT_PARAM_SET_SUCCESS
@ THS_C_EVT_PARAM_SET_SUCCESS
Definition: ths_c.h:125
ths_c_evt_t::length
uint16_t length
Definition: ths_c.h:153
ths_c_evt_t::conn_idx
uint8_t conn_idx
Definition: ths_c.h:150
ths_c_handles_t::ths_srvc_start_handle
uint16_t ths_srvc_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
Definition: ths_c.h:151
THS_C_EVT_TOGGLE_SET_SUCCESS
@ THS_C_EVT_TOGGLE_SET_SUCCESS
Definition: ths_c.h:121
THS_C_SETTINGS_TYPE_TX_POWER
@ THS_C_SETTINGS_TYPE_TX_POWER
Definition: ths_c.h:109
THS_C_SETTINGS_TYPE_MTU
@ THS_C_SETTINGS_TYPE_MTU
Definition: ths_c.h:105
THS_C_SETTINGS_TYPE_TRANS_MODE
@ THS_C_SETTINGS_TYPE_TRANS_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
Definition: ths_c.h:116
THS_C_EVT_DISCOVERY_COMPLETE
@ THS_C_EVT_DISCOVERY_COMPLETE
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
Definition: ths_c.h:124
ths_c_handles_t::ths_rx_handle
uint16_t ths_rx_handle
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
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
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
Definition: ths_c.h:138
ths_c_handles_t::ths_tx_cccd_handle
uint16_t ths_tx_cccd_handle
Definition: ths_c.h:140
ths_c_evt_t::p_data
uint8_t * p_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
Definition: ths_c.h:143
ths_c_handles_t::ths_toggle_handle
uint16_t ths_toggle_handle
Definition: ths_c.h:144
THS_C_EVT_THRP_DATA_RECEIVE
@ THS_C_EVT_THRP_DATA_RECEIVE
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
Definition: ths_c.h:107
THS_C_EVT_DISCOVERY_FAIL
@ THS_C_EVT_DISCOVERY_FAIL
Definition: ths_c.h:118
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
THS_C_SETTINGS_TYPE_PDU
@ THS_C_SETTINGS_TYPE_PDU
Definition: ths_c.h:106
THS_C_DOUBLE_MODE
@ THS_C_DOUBLE_MODE
Definition: ths_c.h:98
THS_C_MASTER_WRITE_MODE
@ THS_C_MASTER_WRITE_MODE
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
Definition: ths_c.h:139
THS_C_EVT_WRITE_OP_ERR
@ THS_C_EVT_WRITE_OP_ERR
Definition: ths_c.h:126
THS_C_SETTINGS_TYPE_CI
@ THS_C_SETTINGS_TYPE_CI
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
Definition: ths_c.h:119