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_t;
117 /** @} */
118
119 /**
120 * @defgroup THS_STRUCT Structures
121 * @{
122 */
123 /**@brief Throughput Service event. */
124 typedef struct
125 {
126 ths_evt_type_t evt_type; /**< The THS event type. */
127 ths_settings_type_t setting_type; /**< The THS parameter set type. */
128 uint8_t conn_idx; /**< The index of the connection for the data transmission. */
129 uint8_t *p_data; /**< Pointer to the received data. */
130 uint16_t length; /**< Length of received data. */
131 } ths_evt_t;
132 /** @} */
133
134 /**
135 * @defgroup THS_TYPEDEF Typedefs
136 * @{
137 */
138 /**@brief Throughput Service event handler type. */
139 typedef void (*ths_evt_handler_t)(ths_evt_t *p_evt);
140 /** @} */
141
142 /**
143 * @addtogroup THS_STRUCT Structures
144 * @{
145 */
146 /**@brief Throughput Service init stucture. This contains all option and data needed for initialization of the service. */
147 typedef struct
148 {
149 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. */
150 ths_transport_mode_t transport_mode; /**< The transport mode of a device. */
151 } ths_init_t;
152 /** @} */
153
154 /**
155 * @defgroup THS_FUNCTION Functions
156 * @{
157 */
158 /**
159 *****************************************************************************************
160 * @brief Initialize a Throughput Service instance and add in the DB.
161 *
162 * @param[in] p_ths_init: Throughput Service initialization variable
163 *
164 * @return Result of service initialization.
165 *****************************************************************************************
166 */
167 sdk_err_t ths_service_init(ths_init_t *p_ths_init);
168
169 /**
170 *****************************************************************************************
171 * @brief Send data to peer device
172 *
173 * @param[in] conn_idx: Connection index
174 * @param[in] p_data: The Pointer of sent value
175 * @param[in] length: The Length of sent value
176 *
177 * @return Result of notify and indicate value
178 *****************************************************************************************
179 */
180 sdk_err_t ths_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
181
182 /**
183 *****************************************************************************************
184 * @brief Notify the peer device of the change of settings.
185 *
186 * @param[in] conn_idx: Connection index.
187 * @param[in] p_settings: Pointer to the value of new settings.
188 * @param[in] length: The Length of the value of new settings.
189 *
190 * @return Result of notify and indicate value
191 *****************************************************************************************
192 */
193 sdk_err_t ths_settings_notify(uint8_t conn_idx, uint8_t *p_settings, uint16_t length);
194
195 /**
196 *****************************************************************************************
197 * @brief Get current transport mode of device.
198 *
199 * @return Current transport mode.
200 *****************************************************************************************
201 */
202 ths_transport_mode_t ths_transport_mode_get(void);
203 /** @} */
204
205 #endif
206 /** @} */
207 /** @} */
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
Definition: ths.h:94
ths_evt_t::length
uint16_t length
Definition: ths.h:130
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
Definition: ths.h:110
THS_TOGGLE_STATE_ON
@ THS_TOGGLE_STATE_ON
Definition: ths.h:104
ths_init_t::evt_handler
ths_evt_handler_t evt_handler
Definition: ths.h:149
ths_evt_type_t
ths_evt_type_t
Throughput Service event type.
Definition: ths.h:92
THS_TOGGLE_STATE_OFF
@ THS_TOGGLE_STATE_OFF
Definition: ths.h:103
THS_SETTINGS_TYPE_MTU
@ THS_SETTINGS_TYPE_MTU
Definition: ths.h:111
ths_evt_t::evt_type
ths_evt_type_t evt_type
Definition: ths.h:126
gr_includes.h
Include Files API.
THS_EVT_TOGGLE_SET
@ THS_EVT_TOGGLE_SET
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
Definition: ths.h:85
ths_init_t::transport_mode
ths_transport_mode_t transport_mode
Definition: ths.h:150
THS_EVT_INVALID
@ THS_EVT_INVALID
Definition: ths.h:93
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
Definition: ths.h:127
THS_MASTER_WRITE_MODE
@ THS_MASTER_WRITE_MODE
Definition: ths.h:86
THS_EVT_SETTINGS_CHANGED
@ THS_EVT_SETTINGS_CHANGED
Definition: ths.h:96
ths_evt_t::conn_idx
uint8_t conn_idx
Definition: ths.h:128
THS_SETTINGS_TYPE_PHY
@ THS_SETTINGS_TYPE_PHY
Definition: ths.h:113
THS_DOUBLE_MODE
@ THS_DOUBLE_MODE
Definition: ths.h:87
ths_evt_t
Throughput Service event.
Definition: ths.h:125
ths_evt_t::p_data
uint8_t * p_data
Definition: ths.h:129
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. This contains all option and data needed for initialization of the ...
Definition: ths.h:148
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
Definition: ths.h:115
THS_SETTINGS_TYPE_TRANS_MODE
@ THS_SETTINGS_TYPE_TRANS_MODE
Definition: ths.h:114
THS_EVT_DATA_SENT
@ THS_EVT_DATA_SENT
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:139
THS_SETTINGS_TYPE_PDU
@ THS_SETTINGS_TYPE_PDU
Definition: ths.h:112