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 <stdint.h> 65 #include "gr55xx_sys.h" 66 #include "custom_config.h" 67 68 /** 69 * @defgroup THS_MACRO Defines 70 * @{ 71 */ 72 #define THS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 73 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Throughput Service connections.*/ 74 #define THS_MAX_DATA_LEN 512 /**< Maximum length of the value of Rx or Tx characteristic. */ 75 #define THS_SERVICE_UUID 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80, \ 76 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x03, 0xED, 0xA6 /**< The UUID of Throughput Service \ 77 for setting advertising data. */ 78 /** @} */ 79 80 /** 81 * @defgroup THS_ENUM Enumerations 82 * @{ 83 */ 84 /**@brief Throughput data transport mode. */ 85 typedef enum { 86 THS_SLAVE_NOTIFY_MODE, /**< Only allow device notify. */ 87 THS_MASTER_WRITE_MODE, /**< Only allow peer writes. */ 88 THS_DOUBLE_MODE, /**< Allow device notify and peer writes at the same time. */ 89 } ths_transport_mode_t; 90 91 /**@brief Throughput Service event type. */ 92 typedef enum { 93 THS_EVT_INVALID, /**< Invalid THS event type. */ 94 THS_EVT_DATA_RECEIVED, /**< The data from the peer has been received. \ 95 The application gets the data in \ref ths_evt_t.p_data. */ 96 THS_EVT_DATA_SENT, /**< The data from the application has been sent, \ 97 and the service is ready to accept new data from the application. */ 98 THS_EVT_SETTINGS_CHANGED, /**< The settings parameters, like MTU, PHY, have been changed by the peer. */ 99 THS_EVT_TOGGLE_SET, /**< The toggle state has been set by the peer. */ 100 } ths_evt_type_t; 101 102 /**@brief Throughput toggle state of sending the data. */ 103 enum ths_toggle_state_t { 104 THS_TOGGLE_STATE_OFF, /**< Sending data is disabled. */ 105 THS_TOGGLE_STATE_ON, /**< Sending data is enabled. */ 106 }; 107 108 /**@brief Throughput service settings types. */ 109 typedef enum { 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 ths_evt_type_t evt_type; /**< The THS event type. */ 126 ths_settings_type_t setting_type; /**< The THS parameter set type. */ 127 uint8_t conn_idx; /**< The index of the connection for the data transmission. */ 128 uint8_t *p_data; /**< Pointer to the received data. */ 129 uint16_t length; /**< Length of received data. */ 130 } ths_evt_t; 131 /** @} */ 132 133 /** 134 * @defgroup THS_TYPEDEF Typedefs 135 * @{ 136 */ 137 /**@brief Throughput Service event handler type. */ 138 typedef void (*ths_evt_handler_t)(ths_evt_t *p_evt); 139 /** @} */ 140 141 /** 142 * @addtogroup THS_STRUCT Structures 143 * @{ 144 */ 145 /**@brief Throughput Service init stucture. 146 * This contains all option and data needed for initialization of the service. */ 147 typedef struct { 148 ths_evt_handler_t 149 evt_handler; /**< Throughput Service event handler which must be provided \ 150 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 /** @} */ 209