1 /** 2 ***************************************************************************************** 3 * 4 * @file thscps.h 5 * 6 * @brief Throughput Control Point 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_THSCPS Throughput Control Point Client (THSCPS) 46 * @{ 47 * @brief THS Control Point Interface module. 48 * 49 * @details The Throughput Control Point Service contains the APIs and types, which can be used by the 50 * application to perform throughput parameters set. 51 * 52 * After \ref thscps_evt_handler_t variable is initialized, the application must 53 * call \ref thscps_service_init() to add the Throughput Control Point Service and 54 * THS Control Point, THS Control Point Response characteristics to the BLE Stack database. 55 */ 56 57 #ifndef __THSCPS_H__ 58 #define __THSCPS_H__ 59 60 #include "ble_prf_types.h" 61 #include "gr55xx_sys.h" 62 #include "custom_config.h" 63 64 /** 65 * @defgroup THSCPS_MACRO Defines 66 * @{ 67 */ 68 #define THSCPS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 69 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of THSCPS connections. */ 70 #define THSCPS_CTRL_PT_VAL_LEN 20 /**< Length of the value of Control Point characteristic. */ 71 #define THSCPS_TEST_SETTING_VAL_LEN 20 /**< Length of the value of Test Setting characteristic. */ 72 #define THSCPS_TEST_INFO_VAL_LEN 20 /**< Length of the value of Test Information characteristic. */ 73 #define THSCPS_CONN_INFO_VAL_LEN 20 /**< Length of the value of Connection Information characteristic. */ 74 #define THSCPS_SERVICE_UUID 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80, 0x0A, 0x46, 0x44, 0xD3, \ 75 0x01, 0x07, 0xED, 0xA6 /**< The UUID of THS Control Point Control Point Service \ 76 for setting advertising data. */ 77 #define THSCPS_ACTION_ON 0x01 /**< Start the action. */ 78 #define THSCPS_ACTION_OFF 0x00 /**< Stop the action. */ 79 #define THSCPS_CTRL_PT_RSP_CODE 0xff /**< Response code. */ 80 /** @} */ 81 82 /** 83 * @defgroup THSCPS_ENUM Enumerations 84 * @{ 85 */ 86 /**@brief Local device GAP Role Type. */ 87 typedef enum { 88 THSCPS_TEST_ROLE_INVALID, /**< Test role: Invalid. */ 89 THSCPS_TEST_ROLE_SLAVE, /**< Test role: Slave. */ 90 THSCPS_TEST_ROLE_MASTER, /**< Test role: Master. */ 91 } thscps_test_role_t; 92 93 /** 94 * @brief Specify PHY. */ 95 typedef enum { 96 THSCPS_LEGACY_ADV_PHY, /**< Undefined LE PHY. */ 97 THSCPS_1MBPS_PHY, /**< LE 1M PHY. */ 98 THSCPS_CODED_PHY, /**< LE Coded PHY. */ 99 } thscps_adv_phy_t; 100 101 /**@brief Throughput Test State. */ 102 typedef enum { 103 THSCPS_TEST_STOP, /**< Throughput Test is not ongoing. */ 104 THSCPS_TEST_STARTED, /**< Throughput Test is ongoing. */ 105 } thscps_test_state_t; 106 107 /**@brief THS Control Point Service Control Point IDs. */ 108 typedef enum { 109 THSCPS_CTRL_PT_INVALID, /**< Invalid cmd id. */ 110 THSCPS_CTRL_PT_TEST_ROLE, /**< Test role set. */ 111 THSCPS_CTRL_PT_ADV_PARAM, /**< Advertising parameters set. */ 112 THSCPS_CTRL_PT_ADV_ACTION, /**< Advertiding action. */ 113 THSCPS_CTRL_PT_SCAN_ACTION, /**< Scan action. */ 114 THSCPS_CTRL_PT_TEST_READY, /**< Ready for test. */ 115 THSCPS_CTRL_PT_SETTING, 116 } thscps_ctrl_pt_id_t; 117 118 /**@brief Throughput service settings types. */ 119 typedef enum { 120 THSCPS_SETTINGS_TYPE_CI, /**< BLE Connection Interval parameter. */ 121 THSCPS_SETTINGS_TYPE_MTU, /**< MTU Size. */ 122 THSCPS_SETTINGS_TYPE_PDU, /**< PDU Size. */ 123 THSCPS_SETTINGS_TYPE_PHY, /**< Radio Phy mode, 1M, 2M, Encoded. */ 124 THSCPS_SETTINGS_TYPE_TRANS_MODE, /**< Data transmission mode. */ 125 THSCPS_SETTINGS_TYPE_TX_POWER, /**< Connect Tx power. */ 126 THSCPS_SETTINGS_TYPE_TOGGLE, /**< Throughput toggle state of sending the data. */ 127 } thscps_settings_type_t; 128 129 /**@brief THS Control Point Response Types. */ 130 typedef enum { 131 THSCPS_RSP_ID_SUCCESS, /**< Success. */ 132 THSCPS_RSP_ID_UNSUPPORT, /**< Failed because of unsupport command. */ 133 THSCPS_RSP_ID_STATUS_ERR, /**< Failed because of disallowed status. */ 134 THSCPS_RSP_ID_PARAM_ERR, /**< Failed because of parameter error. */ 135 THSCPS_RSP_ID_TEST_ROLE_ERR, /**< Failed becaude of Test role error. */ 136 THSCPS_RSP_ID_SDK_ERR, /**< Failed becaude of SDK error Size. */ 137 } thscps_status_rsp_t; 138 139 /**@brief THS Control Point Service Event Type. */ 140 typedef enum { 141 THSCPS_EVT_INVALID, /**< Throughput Control Point Service invalid event. */ 142 THSCPS_EVT_CTRL_PT_IND_ENABLE, /**< THS Control Point indicaiton is enabled. */ 143 THSCPS_EVT_CTRL_PT_IND_DISABLE, /**< THS Control Point indicaiton is disabled. */ 144 THSCPS_EVT_TSET_SET_NTF_ENABLE, /**< THS Test Information notification is enabled. */ 145 THSCPS_EVT_TSET_SET_NTF_DISABLE, /**< THS Test Information notification is disabled. */ 146 THSCPS_EVT_TSET_INFO_NTF_ENABLE, /**< THS Test Information notification is enabled. */ 147 THSCPS_EVT_TSET_INFO_NTF_DISABLE, /**< THS Test Information notification is disabled. */ 148 THSCPS_EVT_CONN_INFO_NTF_ENABLE, /**< THS Connection Information notification is enabled. */ 149 THSCPS_EVT_CONN_INFO_NTF_DISABLE, /**< THS Connection Information notification is disabled. */ 150 THSCPS_EVT_TEST_ROLE_SET, /**< Set Test role. */ 151 THSCPS_EVT_ADV_PRAM_SET, /**< Set advertising parameters. */ 152 THSCPS_EVT_ADV_ACTION, /**< Set advertising action. */ 153 THSCPS_EVT_SCAN_ACTION, /**< Set scan action. */ 154 THSCPS_EVT_SETTING_SET, /**< Throughput setting. */ 155 } thscps_evt_type_t; 156 /** @} */ 157 158 /** 159 * @defgroup THSCPS_STRUCT Structures 160 * @{ 161 */ 162 /**@brief THS Setting Information value. */ 163 typedef struct { 164 uint16_t length; /**< THS Setting Information length. */ 165 const uint8_t *p_data; /**< THS Setting Information data. */ 166 } thscps_setting_t; 167 168 /**@brief THS Test Information value. */ 169 typedef struct { 170 int8_t rssi; /**< RX rssi. */ 171 uint8_t right_rate; /**< RX right rate. */ 172 uint16_t instant_val; /**< Instant throughput value. */ 173 uint16_t average_val; /**< Average throughput value. */ 174 uint16_t packets_val; /**< Recieved Packects value. */ 175 } thscps_test_info_t; 176 177 /**@brief THS connect Information value. */ 178 typedef struct { 179 uint16_t ci; /**< Connect Interval. */ 180 uint16_t pdu; /**< PDU. */ 181 uint16_t mtu; /**< MTU. */ 182 uint8_t tx_phy; /**< TX PHY. */ 183 uint8_t rx_phy; /**< RX PHY. */ 184 int8_t tx_power; /**< TX Power. */ 185 uint8_t ths_mode; /**< THS Mode. */ 186 } thscps_test_conn_info_t; 187 188 /**@brief THS Control Point Advertising Parameters. */ 189 typedef struct { 190 thscps_adv_phy_t phy; /**< Specify what PHY the Controller has changed for TX/RX. */ 191 uint16_t interval; /**< Advertising interval. */ 192 uint16_t duration; /**< Advertising duration. */ 193 int8_t tx_power; /**< Advertising tx power. */ 194 } thscps_adv_param_t; 195 196 /**@brief THS Control Point Response value. */ 197 typedef struct { 198 uint8_t cmd_id; /**< Commander ID. */ 199 thscps_status_rsp_t status; /**< Status. */ 200 uint8_t conn_idx; /**< Connection of cmd set. */ 201 } thscps_rsp_val_t; 202 203 /**@brief THS Control Point Service event. */ 204 typedef struct { 205 uint8_t conn_idx; /**< The connection index. */ 206 thscps_evt_type_t evt_type; /**< THS client event type. */ 207 union { 208 uint8_t action_set; /**< Set action. */ 209 thscps_test_role_t test_role; /**< GAP role type. */ 210 thscps_adv_param_t adv_param; /**< Advertising parameters. */ 211 thscps_setting_t setting_info; /**< Setting infomation. */ 212 } param; /**< Event parameters. */ 213 } thscps_evt_t; 214 /** @} */ 215 216 /** 217 * @defgroup THSCPS_TYPEDEF Typedefs 218 * @{ 219 */ 220 /**@brief THS Control Point Service event handler type. */ 221 typedef void (*thscps_evt_handler_t)(thscps_evt_t *p_evt); 222 /** @} */ 223 224 /** 225 * @defgroup THSCPS_FUNCTION Functions 226 * @{ 227 */ 228 /** 229 ***************************************************************************************** 230 * @brief Initialize a THS Control Point Service instance and add in the DB. 231 * 232 * @param[in] evt_handler: THS Control Point Service event handler. 233 * 234 * @return Result of service initialization. 235 ***************************************************************************************** 236 */ 237 sdk_err_t thscps_service_init(thscps_evt_handler_t evt_handler); 238 239 /** 240 ***************************************************************************************** 241 * @brief Send Control Point Response if its indicaiton has been enabled. 242 * 243 * @param[in] conn_idx: Connnection index. 244 * @param[in] p_rsp_val: Pointer to Response value. 245 * 246 * @return Result of indicate value. 247 ***************************************************************************************** 248 */ 249 sdk_err_t thscps_ctrl_pt_rsp_send(uint8_t conn_idx, thscps_rsp_val_t *p_rsp_val); 250 251 /** 252 ***************************************************************************************** 253 * @brief Send Settings Response if its notification has been enabled. 254 * 255 * @param[in] conn_idx: Connnection index. 256 * @param[in] p_rsp_val: Pointer to Response value. 257 * 258 * @return Result of indicate value. 259 ***************************************************************************************** 260 */ 261 sdk_err_t thscps_test_setting_rsp_send(uint8_t conn_idx, thscps_rsp_val_t *p_rsp_val); 262 263 /** 264 ***************************************************************************************** 265 * @brief Send Throughput Test Information if its notification has been enabled. 266 * 267 * @param[in] conn_idx: Connnection index. 268 * @param[in] p_test_info: Pointer to test information value. 269 * 270 * @return Result of notify value. 271 ***************************************************************************************** 272 */ 273 sdk_err_t thscps_test_info_send(uint8_t conn_idx, thscps_test_info_t *p_test_info); 274 275 /** 276 ***************************************************************************************** 277 * @brief Send Throughput Test Connect Information if its notification has been enabled. 278 * 279 * @param[in] conn_idx: Connnection index. 280 * @param[in] p_conn_info: Pointer to connection information value. 281 * 282 * @return Result of notify value. 283 ***************************************************************************************** 284 */ 285 sdk_err_t thscps_conn_info_send(uint8_t conn_idx, thscps_test_conn_info_t *p_conn_info); 286 287 /** 288 ***************************************************************************************** 289 * @brief Set throughput state set. 290 * 291 * @param[in] test_state: Throughput Test state. 292 ***************************************************************************************** 293 */ 294 void thscps_test_state_set(thscps_test_state_t test_state); 295 /** @} */ 296 #endif 297 /** @} */ 298 /** @} */ 299