1 /** 2 **************************************************************************************** 3 * 4 * @file cts.h 5 * 6 * @brief Current Time 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_CTS Current Time Service (CTS) 46 * @{ 47 * @brief Current Time Service module. 48 * 49 * @details The Current Time Service exposes Current Time characteristic. It optionally exposes 50 * Local Time Information characteristic and Reference Time Information characteristic. 51 * 52 * After \ref cts_init_t variable is intialized, the application must call \ref cts_service_init() 53 * to add Current Time Service and Current Time, Local Time Information and Reference Time 54 * Information characteristics to the BLE Stack database according to \ref cts_init_t.char_mask. 55 */ 56 57 #ifndef __CTS_H__ 58 #define __CTS_H__ 59 60 #include <stdint.h> 61 #include <stdbool.h> 62 #include "gr55xx_sys.h" 63 #include "custom_config.h" 64 #include "ble_prf_utils.h" 65 66 /** 67 * @defgroup CTS_MACRO Defines 68 * @{ 69 */ 70 #define CTS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 71 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of CTS connections. */ 72 #define CTS_CUR_TIME_VAL_LEN 10 /**< Length of current time value. */ 73 #define CTS_LOC_TIME_INFO_VAL_LEN 2 /**< Length of local time information value. */ 74 #define CTS_REF_TIME_INFO_VAL_LEN 4 /**< Length of reference time information value. */ 75 #define CTS_TIME_YEAR_VALID_VAL_MIN 1582 /**< Minimum value of valid year. */ 76 #define CTS_TIME_YEAR_VALID_VAL_MAX 9999 /**< Maximum value of valid year. */ 77 #define CTS_TIME_ZONE_OFFSET_MIN (-48) /**< Minimum Value of Offset from UTC. */ 78 #define CTS_TIME_ZONE_OFFSET_MAX 56 /**< Maximum Value of Offset from UTC. */ 79 #define CTS_TIME_ACCURACY_OUT_RANGE 254 /**< Accuracy out of range. */ 80 #define CTS_TIME_ACCURACT_UNKNOWN 255 /**< Accuracy Unknown. */ 81 #define CTS_ERROR_FIELDS_IGNORED 0x80 /**< The server ignored one or more fields. */ 82 83 /** 84 * @defgroup CTS_CHAR_MASK Characteristics Mask 85 * @{ 86 * @brief Bit masks for the initialization of \ref cts_init_t.char_mask. 87 */ 88 #define CTS_CHAR_MANDATORY 0x0f /**< Bit mask for mandatory characteristic in CTS. */ 89 #define CTS_CHAR_LOC_TIME_INFO_SUP 0x30 /**< Bit mask for Local Time Information characteristic \ 90 that is optional. */ 91 #define CTS_CHAR_REF_TIME_INFO_SUP 0xc0 /**< Bit mask for Reference Time Information characteristic \ 92 that is optional. */ 93 #define CTS_CHAR_FULL 0xff /**< Bit mask of the full characteristic. */ 94 /** @} */ 95 96 /** 97 * @defgroup CTS_ADJ_REASON Current Time Adjust Reason 98 * @{ 99 * @brief Current Time Service Adjust Reason. 100 */ 101 #define CTS_AR_NO_CHANGE (0x00 << 0) /**< No change for current time. */ 102 #define CTS_AR_MAUAL_TIME_UPDATE (0x01 << 0) /**< Manual time update. */ 103 #define CTS_AR_EXT_REF_TIME_UPDATE (0x01 << 1) /**< External reference time update. */ 104 #define CTS_AR_TIME_ZONE_CHANGE (0x01 << 2) /**< Change of time zone. */ 105 #define CTS_AR_DST_CHANGE (0x01 << 3) /**< Change of DST (daylight savings time). */ 106 /** @} */ 107 /** @} */ 108 109 110 /** 111 * @defgroup CTS_ENUM Enumerations 112 * @{ 113 */ 114 /**@brief Current Time Day of week. */ 115 typedef enum { 116 CTS_WEEK_UNKNOWN_DAY, /**< Day of week is not known. */ 117 CTS_WEEK_MONDAY, /**< Monday. */ 118 CTS_WEEK_TUSEDAY, /**< Tuesday. */ 119 CTS_WEEK_WEDNESDAY, /**< Wednesday. */ 120 CTS_WEEK_THURSDAT, /**< Thursday. */ 121 CTS_WEEK_FRIDAY, /**< Friday. */ 122 CTS_WEEK_SATURDAY, /**< Saturday. */ 123 CTS_WEEK_SUNDAY /**< Sunday. */ 124 } cts_week_day_t; 125 126 /**@brief Local time information:Daylight Saving Time Offset. */ 127 typedef enum { 128 CTS_DST_OFFSET_STANDAR_TIME = 0x00, /**< Standard Time. */ 129 CTS_DST_OFFSET_HALF_HOUR = 0x02, /**< Half An Hour Daylight Time (+0.5h). */ 130 CTS_DST_OFFSET_DAYLIGHT_TIME = 0x04, /**< Daylight Time (+1h). */ 131 CTS_DST_OFFSET_DOUB_DAYLIGHT_TIME = 0x08, /**< Double Daylight Time (+2h). */ 132 } cts_dst_offset_t; 133 134 /**@brief Reference time information:Time Source. */ 135 typedef enum { 136 CTS_REF_TIME_SRC_UNKNOWN, /**< Unknown. */ 137 CTS_REF_TIME_SRC_NET_TIME_PROTOCOL, /**< Network Time Protocol. */ 138 CTS_REF_TIME_SRC_GPS, /**< GPS. */ 139 CTS_REF_TIME_SRC_RADIO_TIME_SIGNAL, /**< Radio Time Signal. */ 140 CTS_REF_TIME_SRC_MANUAL, /**< Manual. */ 141 CTS_REF_TIME_SRC_ATOMIC_CLOCK, /**< Atomic Clock. */ 142 CTS_REF_TIME_SRC_CELLUAR_NET, /**< Cellular Network. */ 143 } cts_ref_time_source_t; 144 145 /**@brief Current Time Service event type. */ 146 typedef enum { 147 CTS_EVT_INVALID = 0x00, /**< Invalid event. */ 148 CTS_EVT_CUR_TIME_NOTIFICATION_ENABLED, /**< Current Time Notification is enabled. */ 149 CTS_EVT_CUR_TIME_NOTIFICATION_DISABLED, /**< Current Time Notification is disabled. */ 150 CTS_EVT_CUR_TIME_SET_BY_PEER, /**< Current Time has been set by peer. */ 151 CTS_EVT_LOC_TIME_INFO_SET_BY_PEER, /**< Local Time information has been set by peer. */ 152 } cts_evt_type_t; 153 /** @} */ 154 155 /** 156 * @defgroup CTS_STRUCT Structures 157 * @{ 158 */ 159 /**@brief CTS Exact Time 256. */ 160 typedef struct { 161 prf_date_time_t date_time; /**< Date Time. */ 162 uint8_t day_of_week; /**< Day of Week. */ 163 uint8_t fractions_256; /**< 1/256th of a second. */ 164 } cts_exact_time_256_t; 165 166 /**@brief CTS Current Time value. */ 167 typedef struct { 168 cts_exact_time_256_t day_date_time; /**< Exact Time 256. */ 169 uint8_t adjust_reason; /**< Adjust Reason. */ 170 } cts_cur_time_t; 171 172 /**@brief CTS Local Time Information. */ 173 typedef struct { 174 int8_t time_zone; /**< Time Zone, Offset from UTC in number of 15-minute increments. */ 175 cts_dst_offset_t dst_offset; /**< Daylight Saving Time Offset. */ 176 } cts_loc_time_info_t; 177 178 /**@brief CTS Reference Time Information. */ 179 typedef struct { 180 cts_ref_time_source_t source; /**< Time Source. */ 181 uint8_t accuracy; /**< Accuracy of time information. */ 182 uint8_t days_since_update; /**< Days Since Update. */ 183 uint8_t hours_since_update; /**< Hours Since Update. */ 184 } cts_ref_time_info_t; 185 186 /**@brief CTS Adjust information. */ 187 typedef struct { 188 uint8_t adjust_reason; /**< Adjust Reason. */ 189 cts_exact_time_256_t day_date_time; /**< Exact Time 256. */ 190 cts_loc_time_info_t loc_time_info; /**< Local Time information. */ 191 cts_ref_time_info_t ref_time_info; /**< Reference Time information. */ 192 } cts_adj_info_t; 193 194 /**@brief Current Time Service event. */ 195 typedef struct { 196 uint8_t conn_idx; /**< The index of the connection. */ 197 cts_evt_type_t evt_type; /**< The CTS event type. */ 198 const uint8_t *p_data; /**< Pointer to event data. */ 199 uint16_t length; /**< Length of event data. */ 200 cts_cur_time_t cur_time; /**< Curren time set by peer. */ 201 cts_loc_time_info_t loc_time_info; /**< Local time information set by peer. */ 202 } cts_evt_t; 203 /** @} */ 204 205 /** 206 * @defgroup CTS_TYPEDEF Typedefs 207 * @{ 208 */ 209 /**@brief Current Time Service event handler type. */ 210 typedef void (*cts_evt_handler_t)(cts_evt_t *p_evt); 211 /** @} */ 212 213 /** 214 * @defgroup CTS_STRUCT Structures 215 * @{ 216 */ 217 /**@brief Current Time Service init structure. 218 * This contains all option and data needed for initialization of the service. */ 219 typedef struct { 220 cts_evt_handler_t evt_handler; /**< Current Time Service event handler. */ 221 uint16_t 222 char_mask; /**< Initial mask of supported characteristics, and configured with \ref CTS_CHAR_MASK. */ 223 cts_cur_time_t cur_time; /**< Current Time. */ 224 cts_loc_time_info_t loc_time_info; /**< Local Time information. */ 225 cts_ref_time_info_t ref_time_info; /**< Reference Time information. */ 226 } cts_init_t; 227 /** @} */ 228 229 /** 230 * @defgroup CTS_FUNCTION Functions 231 * @{ 232 */ 233 /** 234 ***************************************************************************************** 235 * @brief Initialize a Current Time Service instance and add in the DB. 236 * 237 * @param[in] p_cts_init: Pointer to CTS Service initialization variable. 238 * 239 * @return Result of service initialization. 240 ***************************************************************************************** 241 */ 242 sdk_err_t cts_service_init(cts_init_t *p_cts_init); 243 244 /** 245 ***************************************************************************************** 246 * @brief Get exact time for user. 247 * 248 * @param[out] p_cts_exact_time: Pointer to exact time. 249 ***************************************************************************************** 250 */ 251 void cts_exact_time_get(cts_exact_time_256_t *p_cts_exact_time); 252 253 /** 254 ***************************************************************************************** 255 * @brief Update exact time. 256 * 257 * @param[in] p_exact_time: Pointer to exact time. 258 ***************************************************************************************** 259 */ 260 void cts_exact_time_update(cts_exact_time_256_t *p_cts_exact_time); 261 262 /** 263 ***************************************************************************************** 264 * @brief Adjust current time. 265 * 266 * @param[in] p_adj_info: Pointer to adjust information. 267 ***************************************************************************************** 268 */ 269 void cts_cur_time_adjust(cts_adj_info_t *p_adj_info); 270 271 /** 272 ***************************************************************************************** 273 * @brief Send Current Time if its notification has been enabled. 274 * 275 * @param[in] conn_idx: Connnection index. 276 * @param[in] p_cur_time: Pointer to current time. 277 * 278 * @return Result of notify value 279 ***************************************************************************************** 280 */ 281 sdk_err_t cts_cur_time_send(uint8_t conn_idx, cts_cur_time_t *p_cur_time); 282 /** @} */ 283 284 #endif 285 /** @} */ 286 /** @} */ 287 288