ths.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file ths.h
5 *
6 * @brief Throughput 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_THS Throughput Service (THS)
46 * @{
47 * @brief Definitions and prototypes for the THS interface.
48 *
49 * @details The Throughput Service is a customized GATT-based service with Settings, Toggle,
50 * Tx and Rx characteristics. The developer uses the service to test throughput.
51 * The data is sent to the peer as Handle Value Notification, and the data received
52 * from the peer is transmitted with GATT Write Command.
53 *
54 * The peer writes Toggle characteristic to command the application starting/stopping
55 * throughput. The application calls \ref ths_data_send() to send data to the peer.
56 * The application handles \ref THS_EVT_DATA_RECEIVED in \ref ths_init_t.evt_handler()
57 * to get the data received from the peer. The application uses ths_settings_notify() to
58 * request the change of the parameters related with throughput, including CI, MTU, PDU and PHY.
59 */
60
61 #ifndef _THS_H_
62 #define _THS_H_
63
64 #include "gr_includes.h"
65 #include "custom_config.h"
66 #include <stdint.h>
67
68 /**
69 * @defgroup THS_MACRO Defines
70 * @{
71 */
72 #define THS_CONNECTION_MAX 10 /**< Maximum number of Throughput Service connections. */
73 #define THS_MAX_DATA_LEN 512 /**< Maximum length of the value of Rx or Tx characteristic. */
74 #define THS_SERVICE_UUID 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
75 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x03, 0xED, 0xA6 /**< The UUID of Throughput Service for setting advertising data. */
76 /** @} */
77
78 /**
79 * @defgroup THS_ENUM Enumerations
80 * @{
81 */
82 /**@brief Throughput data transport mode. */
83 typedef enum
84 {
85 THS_SLAVE_NOTIFY_MODE, /**< Only allow device notify. */
86 THS_MASTER_WRITE_MODE, /**< Only allow peer writes. */
87 THS_DOUBLE_MODE, /**< Allow device notify and peer writes at the same time. */
88 } ths_transport_mode_t;
89
90 /**@brief Throughput Service event type. */
91 typedef enum
92 {
93 THS_EVT_INVALID, /**< Invalid THS event type. */
94 THS_EVT_DATA_RECEIVED, /**< The data from the peer has been received. The application gets the data in \ref ths_evt_t.p_data. */
95 THS_EVT_DATA_SENT, /**< The data from the application has been sent, and the service is ready to accept new data from the application. */
96 THS_EVT_SETTINGS_CHANGED, /**< The settings parameters, like MTU, PHY, have been changed by the peer. */
97 THS_EVT_TOGGLE_SET, /**< The toggle state has been set by the peer. */
98 } ths_evt_type_t;
99
100 /**@brief Throughput toggle state of sending the data. */
101 enum ths_toggle_state_t
102 {
103 THS_TOGGLE_STATE_OFF, /**< Sending data is disabled. */
104 THS_TOGGLE_STATE_ON, /**< Sending data is enabled. */
105 };
106
107 /**@brief Throughput service settings types. */
108 typedef enum
109 {
110 THS_SETTINGS_TYPE_CI, /**< BLE Connection Interval parameter. */
111 THS_SETTINGS_TYPE_MTU, /**< MTU Size. */
112 THS_SETTINGS_TYPE_PDU, /**< PDU Size. */
113 THS_SETTINGS_TYPE_PHY, /**< Radio Phy mode, 1M, 2M, Encoded. */
114 THS_SETTINGS_TYPE_TRANS_MODE, /**< Data transmission mode. */
115 THS_SETTINGS_TYPE_TX_POWER, /**< Connect Tx power. */
116 THS_SETTINGS_TYPE_RANGING_PARAM,
117 }ths_settings_type_t;
118 /** @} */
119
120 /**
121 * @defgroup THS_STRUCT Structures
122 * @{
123 */
124 /**@brief Throughput Service event. */
125 typedef struct
126 {
127 ths_evt_type_t evt_type; /**< The THS event type. */
128 ths_settings_type_t setting_type; /**< The THS parameter set type. */
129 uint8_t conn_idx; /**< The index of the connection for the data transmission. */
130 uint8_t *p_data; /**< Pointer to the received data. */
131 uint16_t length; /**< Length of received data. */
132 } ths_evt_t;
133 /** @} */
134
135 /**
136 * @defgroup THS_TYPEDEF Typedefs
137 * @{
138 */
139 /**@brief Throughput Service event handler type. */
140 typedef void (*ths_evt_handler_t)(ths_evt_t *p_evt);
141 /** @} */
142
143 /**
144 * @addtogroup THS_STRUCT Structures
145 * @{
146 */
147 /**@brief Throughput Service init stucture. This contains all option and data needed for initialization of the service. */
148 typedef struct
149 {
150 ths_evt_handler_t evt_handler; /**< Throughput Service event handler which must be provided by the application to send and receive the data and the settings change. */
151 ths_transport_mode_t transport_mode; /**< The transport mode of a device. */
152 } ths_init_t;
153 /** @} */
154
155 /**
156 * @defgroup THS_FUNCTION Functions
157 * @{
158 */
159 /**
160 *****************************************************************************************
161 * @brief Initialize a Throughput Service instance and add in the DB.
162 *
163 * @param[in] p_ths_init: Throughput Service initialization variable
164 *
165 * @return Result of service initialization.
166 *****************************************************************************************
167 */
168 sdk_err_t ths_service_init(ths_init_t *p_ths_init);
169
170 /**
171 *****************************************************************************************
172 * @brief Send data to peer device
173 *
174 * @param[in] conn_idx: Connection index
175 * @param[in] p_data: The Pointer of sent value
176 * @param[in] length: The Length of sent value
177 *
178 * @return Result of notify and indicate value
179 *****************************************************************************************
180 */
181 sdk_err_t ths_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
182
183 /**
184 *****************************************************************************************
185 * @brief Notify the peer device of the change of settings.
186 *
187 * @param[in] conn_idx: Connection index.
188 * @param[in] p_settings: Pointer to the value of new settings.
189 * @param[in] length: The Length of the value of new settings.
190 *
191 * @return Result of notify and indicate value
192 *****************************************************************************************
193 */
194 sdk_err_t ths_settings_notify(uint8_t conn_idx, uint8_t *p_settings, uint16_t length);
195
196 /**
197 *****************************************************************************************
198 * @brief Get current transport mode of device.
199 *
200 * @return Current transport mode.
201 *****************************************************************************************
202 */
203 ths_transport_mode_t ths_transport_mode_get(void);
204 /** @} */
205
206 #endif
207 /** @} */
208 /** @} */
ths_data_send
sdk_err_t ths_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to peer device.
THS_EVT_DATA_RECEIVED
@ THS_EVT_DATA_RECEIVED
The data from the peer has been received.
Definition: ths.h:94
ths_evt_t::length
uint16_t length
Length of received data.
Definition: ths.h:131
ths_service_init
sdk_err_t ths_service_init(ths_init_t *p_ths_init)
Initialize a Throughput Service instance and add in the DB.
THS_SETTINGS_TYPE_CI
@ THS_SETTINGS_TYPE_CI
BLE Connection Interval parameter.
Definition: ths.h:110
THS_TOGGLE_STATE_ON
@ THS_TOGGLE_STATE_ON
Sending data is enabled.
Definition: ths.h:104
ths_init_t::evt_handler
ths_evt_handler_t evt_handler
Throughput Service event handler which must be provided by the application to send and receive the da...
Definition: ths.h:150
ths_evt_type_t
ths_evt_type_t
Throughput Service event type.
Definition: ths.h:92
THS_TOGGLE_STATE_OFF
@ THS_TOGGLE_STATE_OFF
Sending data is disabled.
Definition: ths.h:103
THS_SETTINGS_TYPE_MTU
@ THS_SETTINGS_TYPE_MTU
MTU Size.
Definition: ths.h:111
ths_evt_t::evt_type
ths_evt_type_t evt_type
The THS event type.
Definition: ths.h:127
gr_includes.h
Include Files API.
THS_EVT_TOGGLE_SET
@ THS_EVT_TOGGLE_SET
The toggle state has been set by the peer.
Definition: ths.h:97
ths_transport_mode_t
ths_transport_mode_t
Throughput data transport mode.
Definition: ths.h:84
THS_SLAVE_NOTIFY_MODE
@ THS_SLAVE_NOTIFY_MODE
Only allow device notify.
Definition: ths.h:85
ths_init_t::transport_mode
ths_transport_mode_t transport_mode
The transport mode of a device.
Definition: ths.h:151
THS_EVT_INVALID
@ THS_EVT_INVALID
Invalid THS event type.
Definition: ths.h:93
THS_SETTINGS_TYPE_RANGING_PARAM
@ THS_SETTINGS_TYPE_RANGING_PARAM
Definition: ths.h:116
ths_settings_type_t
ths_settings_type_t
Throughput service settings types.
Definition: ths.h:109
ths_evt_t::setting_type
ths_settings_type_t setting_type
The THS parameter set type.
Definition: ths.h:128
THS_MASTER_WRITE_MODE
@ THS_MASTER_WRITE_MODE
Only allow peer writes.
Definition: ths.h:86
THS_EVT_SETTINGS_CHANGED
@ THS_EVT_SETTINGS_CHANGED
The settings parameters, like MTU, PHY, have been changed by the peer.
Definition: ths.h:96
ths_evt_t::conn_idx
uint8_t conn_idx
The index of the connection for the data transmission.
Definition: ths.h:129
THS_SETTINGS_TYPE_PHY
@ THS_SETTINGS_TYPE_PHY
Radio Phy mode, 1M, 2M, Encoded.
Definition: ths.h:113
THS_DOUBLE_MODE
@ THS_DOUBLE_MODE
Allow device notify and peer writes at the same time.
Definition: ths.h:87
ths_evt_t
Throughput Service event.
Definition: ths.h:126
ths_evt_t::p_data
uint8_t * p_data
Pointer to the received data.
Definition: ths.h:130
ths_transport_mode_get
ths_transport_mode_t ths_transport_mode_get(void)
Get current transport mode of device.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
ths_toggle_state_t
ths_toggle_state_t
Throughput toggle state of sending the data.
Definition: ths.h:102
ths_init_t
Throughput Service init stucture.
Definition: ths.h:149
ths_settings_notify
sdk_err_t ths_settings_notify(uint8_t conn_idx, uint8_t *p_settings, uint16_t length)
Notify the peer device of the change of settings.
THS_SETTINGS_TYPE_TX_POWER
@ THS_SETTINGS_TYPE_TX_POWER
Connect Tx power.
Definition: ths.h:115
THS_SETTINGS_TYPE_TRANS_MODE
@ THS_SETTINGS_TYPE_TRANS_MODE
Data transmission mode.
Definition: ths.h:114
THS_EVT_DATA_SENT
@ THS_EVT_DATA_SENT
The data from the application has been sent, and the service is ready to accept new data from the app...
Definition: ths.h:95
ths_evt_handler_t
void(* ths_evt_handler_t)(ths_evt_t *p_evt)
Throughput Service event handler type.
Definition: ths.h:140
THS_SETTINGS_TYPE_PDU
@ THS_SETTINGS_TYPE_PDU
PDU Size.
Definition: ths.h:112