1 /** 2 **************************************************************************************** 3 * 4 * @file rtus.h 5 * 6 * @brief Reference Time Update 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_RTUS Reference Time Update Service (RTUS) 46 * @{ 47 * @brief Reference Time Update Service module. 48 * 49 * @details The Reference Time Update Service shall expose the Time Update Control Point 50 * characteristic and the Time Update State characteristic. 51 * 52 * After \ref rtus_init_t variable is intialized, the application must call \ref rtus_service_init() 53 * to add Reference Time Update Service and Time Update Control Point and Time Update State 54 * characteristics to the BLE Stack database. 55 */ 56 57 #ifndef __RTUS_H__ 58 #define __RTUS_H__ 59 60 #include <stdint.h> 61 #include <stdbool.h> 62 #include "gr55xx_sys.h" 63 #include "custom_config.h" 64 65 /** 66 * @defgroup RTUS_MACRO Defines 67 * @{ 68 */ 69 #define RTUS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 70 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of RTUS connections. */ 71 #define RTUS_CTRL_PT_VAL_LEN 1 /**< Length of Time Update Control Point value. */ 72 #define RTUS_UPDATE_STATE_VAL_LEN 2 /**< Length of Time Update State value. */ 73 #define RTUS_CHAR_FULL 0x1f /**< Bit mask for mandatory characteristic in RTUS. */ 74 /** @} */ 75 76 /** 77 * @defgroup RTUS_ENUM Enumerations 78 * @{ 79 */ 80 /**@brief RTUS Time Update Control Point. */ 81 typedef enum { 82 RTUS_CTRL_PT_GET_UPDATE = 0x01, /**< Get reference update. */ 83 RTUS_CTRL_PT_CANCEL_UPDATE, /**< Cancel reference update. */ 84 } rtus_ctrl_pt_t; 85 86 /**@brief RTUS Current State. */ 87 typedef enum { 88 RTUS_CUR_STATE_IDLE, /**< Idle update state. */ 89 RTUS_CUR_STATE_PENDING, /**< Update pending state. */ 90 } rtus_cur_state_t; 91 92 /**@brief RTUS Time Update Result. */ 93 typedef enum { 94 RTUS_UPDATE_RESULT_SCCESSFUL, /**< Time update successful. */ 95 RTUS_UPDATE_RESULT_CANCELED, /**< Time update canceled. */ 96 RTUS_UPDATE_RESULT_NO_CONN_TO_REF, /**< No Connection To Reference. */ 97 RTUS_UPDATE_RESULT_REP_ERROR, /**< Reference responded with an error. */ 98 RTUS_UPDATE_RESULT_TIMEOUT, /**< Update timeout. */ 99 RTUS_UPDATE_RESULT_NO_ATTEMPTED, /**< Update not attempted after reset. */ 100 } rtus_update_result_t; 101 102 /**@brief RTUS Event type. */ 103 typedef enum { 104 RTUS_EVT_INVALID, /**< Invalid event. */ 105 RTUS_EVT_GET_UPDATE, /**< Get reference update. */ 106 RTUS_EVT_CANCEL_UPDATE, /**< Cancel reference update. */ 107 } rtus_evt_type_t; 108 /** @} */ 109 110 /** 111 * @defgroup RTUS_STRUCT Structures 112 * @{ 113 */ 114 /**@brief RTUS Time Update State. */ 115 typedef struct { 116 rtus_cur_state_t cur_state; /**< RTUS Current State. */ 117 rtus_update_result_t update_result; /**< Time Update Result. */ 118 } rtus_update_state_t; 119 120 /**@brief RTUS Event data. */ 121 typedef struct { 122 uint8_t conn_idx; /**< The index of the connection. */ 123 rtus_evt_type_t evt_type; /**< RTUS event type. */ 124 } rtus_evt_t; 125 /** @} */ 126 127 /** 128 * @defgroup RTUS_TYPEDEF Typedefs 129 * @{ 130 */ 131 /**@brief Reference Time Update Service event handler type. */ 132 typedef void (*rtus_evt_handler_t)(rtus_evt_t *p_evt); 133 /** @} */ 134 135 /** 136 * @defgroup RTUS_STRUCT Structures 137 * @{ 138 */ 139 /**@brief Reference Time Update Service init structure. 140 * This contains all option and data needed for initialization of the service. */ 141 typedef struct { 142 rtus_evt_handler_t evt_handler; /**< Reference Time Update Service event handler. */ 143 uint16_t char_mask; /**< Initial mask of supported characteristics. */ 144 } rtus_init_t; 145 /** @} */ 146 147 /** 148 * @defgroup RTUS_FUNCTION Functions 149 * @{ 150 */ 151 /** 152 ***************************************************************************************** 153 * @brief Initialize a RTUS instance and add in the DB. 154 * 155 * @param[in] p_rtus_init: Pointer to RTUS Service initialization variable. 156 * 157 * @return Result of service initialization. 158 ***************************************************************************************** 159 */ 160 sdk_err_t rtus_service_init(rtus_init_t *p_rtus_init); 161 162 /** 163 ***************************************************************************************** 164 * @brief Set state of reference time update . 165 * 166 * @param[in] cur_state: Current state of the reference time update . 167 ***************************************************************************************** 168 */ 169 void rtus_current_state_set(rtus_cur_state_t cur_state); 170 171 /** 172 ***************************************************************************************** 173 * @brief Set result of reference time update . 174 * 175 * @param[in] update_result: Resultof the reference time update . 176 ***************************************************************************************** 177 */ 178 void rtus_update_result_set(rtus_update_result_t update_result); 179 /** @} */ 180 181 #endif 182 /** @} */ 183 /** @} */ 184 185