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. */
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. */
99 
100 /**@brief Throughput toggle state of sending the data. */
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. */
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  */
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  */
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