1 /** 2 ***************************************************************************************** 3 * 4 * @file dss.h 5 * 6 * @brief Device Synchronize 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_DSS Device Synchronize Service (DSS) 46 * @{ 47 * @brief Definitions and prototypes for the DSS interface. 48 * 49 * @details The Device Synchronize Service is set for timing synchronization of device group, 50 * which can accept commands such as device role and timing synchronization. In addition, 51 * related information of device timing synchronization can be got through DSS. 52 * 53 * After dss_init_t variable is initialized, the application should call 54 * \ref dss_service_init() to add a Device Synchronize Service and the characteristics 55 * to the BLE Stack database. 56 * 57 */ 58 59 #ifndef __DSS_H__ 60 #define __DSS_H__ 61 62 #include <stdint.h> 63 #include "gr55xx_sys.h" 64 #include "custom_config.h" 65 66 /** 67 * @defgroup DSS_MACRO Defines 68 * @{ 69 */ 70 #define DSS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 71 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of DSS connections. */ 72 #define DSS_ROLE_VALUE_LEN 1 /**< Length of Role characteristic value. */ 73 #define DSS_EVT_CNT_VALUE_LEN 4 /**< Length of Event Count characteristic value. */ 74 #define DSS_EVT_PERIOD_VALUE_LEN 2 /**< Length of Event Period characteristic value. */ 75 #define DSS_STATUS_VALUE_LEN 1 /**< Length of Status characteristic value. */ 76 #define DSS_CTRL_PT_VALUE_LEN 7 /**< Length of Control Point characteristic value. */ 77 #define DSS_CTRL_PT_RSP_VAL_LEN 3 /**< Length of Control Point Response characteristic value. */ 78 79 #define DSS_SYNC_DEV_MAX_NUM 5 /**< Maximun num of Source Sync Device. */ 80 #define DSS_CFG_ADV_IDX 0 /**< DSS Config Advertising Index. */ 81 #define DSS_SYNC_ADV_IDX 1 /**< DSS Sync Advertising Index. */ 82 /** @} */ 83 84 /** 85 * @defgroup DSS_ENUM Enumerations 86 * @{ 87 */ 88 /**@brief Device Synchronize Service roles. */ 89 typedef enum { 90 DSS_ROLE_SYNC_INVALID, /**< Device synchronize invalid role. */ 91 DSS_ROLE_SYNC_SOURCE, /**< Device synchronize source role (Create synchronize source and distribute). */ 92 DSS_ROLE_SYNC_DEVICE, /**< Device synchronize deivce role. */ 93 } dss_role_t; 94 95 /**@brief Device Synchronize Service status. */ 96 typedef enum { 97 DSS_STATUS_CFG_READY, /**< Device is ready for config, */ 98 DSS_STATUS_IN_ADV, /**< Device is in advertising. */ 99 DSS_STATUS_IN_SCAN, /**< Device is in scanning. */ 100 DSS_STATUS_IN_INITIATING /**< Device is in initiating. */ 101 } dss_staus_t; 102 103 /**@brief Device Synchronize Service control point OP IDs. */ 104 typedef enum { 105 DSS_OP_ID_INVALID, /**< Invalid op id. */ 106 DSS_OP_ID_ROLE_SET, /**< Set role op id.*/ 107 DSS_OP_ID_SYNC_SRC_CREATE, /**< Create synchronize source op id. */ 108 DSS_OP_ID_SYNC, /**< Synchronize self or peer op id. */ 109 DSS_OP_ID_CANCEL_SYNC, /**< Cancel Synchronization op id. */ 110 DSS_OP_ID_LP_ENTER, /**< Enter low power mode(Stop all ble activity). */ 111 DSS_OP_ID_SYNC_DESTROY, /**< Destroy sync. */ 112 DSS_OP_ID_RSP = 0xff /**< Response op id. */ 113 } dss_op_id_t; 114 115 /**@brief Device Synchronize Service control point response IDs. */ 116 typedef enum { 117 DSS_RSP_ID_SUCCESS, /**< Success. */ 118 DSS_RSP_ID_UNSUPPORT, /**< Unsupport op. */ 119 DSS_RSP_ID_DISALLOWED, /**< Disallowed op. */ 120 DSS_RSP_ID_STATUS_ERR, /**< Status error. */ 121 DSS_RSP_ID_PARAM_ERR, /**< Parameter error. */ 122 DSS_RSP_ID_ROLE_ERR, /**< Role error. */ 123 DSS_RSP_ID_NO_HANDLER, /**< No handler for op. */ 124 DSS_RSP_ID_ADV_START_FAIL, /**< Advertising start fail. */ 125 DSS_RSP_ID_ADV_TIMEOUT, /**< Advertising start timeout. */ 126 DSS_RSP_ID_SCAN_START_FAIL, /**< Scan start fail. */ 127 DSS_RSP_ID_SCAN_TIMEOUT, /**< Scan start timeout. */ 128 DSS_RSP_ID_CONN_EST_FAIL, /**< Connection establish fail. */ 129 DSS_RSP_ID_CREATE_SRC_FAIL, /**< Create source fail. */ 130 DSS_RSP_ID_DISTR_SRC_FAIL, /**< Distribute source fail. */ 131 DSS_RSP_ID_DESTROY_SRC_FAIL, /**< Destroy source fail. */ 132 DSS_RSP_ID_ENTER_LP_FAIL, /**< Enter Low Power Mode fail. */ 133 DSS_RSP_ID_CANCEL_SYNC_FAIL, /**< Cancel Synchronization fail. */ 134 } dss_rsp_id_t; 135 136 137 /**@brief Device Synchronize Service event types. */ 138 typedef enum { 139 DSS_EVT_INVALID, /**< Invalid event. */ 140 DSS_EVT_SOURCE_ROLE_SET, /**< Source Role set event. */ 141 DSS_EVT_DEVICE_ROLE_SET, /**< Device Role set event. */ 142 DSS_EVT_SYNC_SRC_CREATE, /**< Sync source create event. */ 143 DSS_EVT_SYNC_DESTROY, /**< Destroy sync event. */ 144 DSS_EVT_SYNC_OCCUR, /**< Sync occur event. */ 145 DSS_EVT_SYNC_SELF_OR_PEER, /**< Synchronize self or peer event. */ 146 DSS_EVT_SYNC_CANCEL, /**< Cancel Synchronization event. */ 147 DSS_EVT_LP_ENTER, /**< Enter low power event. */ 148 } dss_evt_type_t; 149 /** @} */ 150 151 /** 152 * @defgroup DSS_STRUCTURES Structures 153 * @{ 154 */ 155 /**@brief Device Synchronize Service Synchronize event. */ 156 typedef struct { 157 dss_evt_type_t evt_type; /**< Event type. */ 158 uint8_t conn_idx; /**< Connect index. */ 159 uint32_t sync_cnt; /**< Synchronize count. */ 160 uint8_t sync_dev_num; /**< Synchronize Device num. */ 161 bool is_enter_lp_mode; /**< In Low Power Mode flag. */ 162 } dss_evt_t; 163 /** @} */ 164 165 /** 166 * @defgroup DSS_TYPEDEFS Typedefs 167 * @{ 168 */ 169 /**@brief Device Synchronize Service event handler type. */ 170 typedef void (*dss_evt_handler_t)(dss_evt_t *p_evt); 171 /** @} */ 172 173 174 /** 175 * @defgroup DIS_FUNCTION Functions 176 * @{ 177 */ 178 /** 179 ***************************************************************************************** 180 * @brief Initialize a Device Synchronize Service instance and add in the database. 181 * 182 * @param[in] evt_handler: DSS event handler. 183 * 184 * @return Result of service initialization. 185 ***************************************************************************************** 186 */ 187 sdk_err_t dss_service_init(dss_evt_handler_t evt_handler); 188 189 /** 190 ***************************************************************************************** 191 * @brief Send Control Point Response. 192 * 193 * @param[in] conn_idx: Connection index. 194 * @param[in] evt_type: Event type. 195 * @param[in] rsp_id: Response ID. 196 * 197 * @return Result of send. 198 ***************************************************************************************** 199 */ 200 sdk_err_t dss_sync_op_result_send(uint8_t conn_idx, dss_evt_type_t evt_type, dss_rsp_id_t rsp_id); 201 202 /** 203 ***************************************************************************************** 204 * @brief Distribute sync source to peer. 205 * 206 * @param[in] conn_idx: Connection index. 207 ***************************************************************************************** 208 */ 209 void dss_sync_src_distribute(uint8_t conn_idx); 210 211 /** 212 ***************************************************************************************** 213 * @brief Set dss status. 214 * 215 * @param[in] conn_idx: Connection index. 216 * @param[in] status: Dss status. 217 ***************************************************************************************** 218 */ 219 void dss_set_status(uint8_t conn_idx, dss_staus_t status); 220 221 /** 222 ***************************************************************************************** 223 * @brief Set Sync params. 224 * 225 * @param[in] conn_idx: Connection index. 226 * @param[in] is_auto_enter_lp: Auto enter low power mode flag. 227 * @param[in] is_auto_calib_drift: Auto calibration drift flag. 228 ***************************************************************************************** 229 */ 230 void dss_set_sync_params(uint8_t conn_idx, bool is_auto_enter_lp, bool is_auto_calib_drift); 231 232 /** 233 ***************************************************************************************** 234 * @brief Set Device whether in low power mode. 235 * 236 * @param[in] conn_idx: Connection index. 237 * @param[in] is_in_lp_mode: Is Device in low power mode. 238 ***************************************************************************************** 239 */ 240 void dss_set_lp_mode(uint8_t conn_idx, bool is_in_lp_mode); 241 /** @} */ 242 243 #endif 244 /** @} */ 245 /** @} */ 246