cts.h
Go to the documentation of this file.
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 "gr55xx_sys.h"
61 #include "custom_config.h"
62 #include "ble_prf_utils.h"
63 #include <stdint.h>
64 #include <stdbool.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 that is optional. */
90 #define CTS_CHAR_REF_TIME_INFO_SUP 0xc0 /**< Bit mask for Reference Time Information characteristic that is optional. */
91 #define CTS_CHAR_FULL 0xff /**< Bit mask of the full characteristic. */
92 /** @} */
93
94 /**
95 * @defgroup CTS_ADJ_REASON Current Time Adjust Reason
96 * @{
97 * @brief Current Time Service Adjust Reason.
98 */
99 #define CTS_AR_NO_CHANGE (0x00 << 0) /**< No change for current time. */
100 #define CTS_AR_MAUAL_TIME_UPDATE (0x01 << 0) /**< Manual time update. */
101 #define CTS_AR_EXT_REF_TIME_UPDATE (0x01 << 1) /**< External reference time update. */
102 #define CTS_AR_TIME_ZONE_CHANGE (0x01 << 2) /**< Change of time zone. */
103 #define CTS_AR_DST_CHANGE (0x01 << 3) /**< Change of DST (daylight savings time). */
104 /** @} */
105 /** @} */
106
107
108 /**
109 * @defgroup CTS_ENUM Enumerations
110 * @{
111 */
112 /**@brief Current Time Day of week. */
113 typedef enum
114 {
115 CTS_WEEK_UNKNOWN_DAY, /**< Day of week is not known. */
116 CTS_WEEK_MONDAY, /**< Monday. */
117 CTS_WEEK_TUSEDAY, /**< Tuesday. */
118 CTS_WEEK_WEDNESDAY, /**< Wednesday. */
119 CTS_WEEK_THURSDAT, /**< Thursday. */
120 CTS_WEEK_FRIDAY, /**< Friday. */
121 CTS_WEEK_SATURDAY, /**< Saturday. */
122 CTS_WEEK_SUNDAY /**< Sunday. */
123 } cts_week_day_t;
124
125 /**@brief Local time information:Daylight Saving Time Offset. */
126 typedef enum
127 {
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 {
137 CTS_REF_TIME_SRC_UNKNOWN, /**< Unknown. */
138 CTS_REF_TIME_SRC_NET_TIME_PROTOCOL, /**< Network Time Protocol. */
139 CTS_REF_TIME_SRC_GPS, /**< GPS. */
140 CTS_REF_TIME_SRC_RADIO_TIME_SIGNAL, /**< Radio Time Signal. */
141 CTS_REF_TIME_SRC_MANUAL, /**< Manual. */
142 CTS_REF_TIME_SRC_ATOMIC_CLOCK, /**< Atomic Clock. */
143 CTS_REF_TIME_SRC_CELLUAR_NET, /**< Cellular Network. */
144 } cts_ref_time_source_t;
145
146 /**@brief Current Time Service event type. */
147 typedef enum
148 {
149 CTS_EVT_INVALID = 0x00, /**< Invalid event. */
150 CTS_EVT_CUR_TIME_NOTIFICATION_ENABLED, /**< Current Time Notification is enabled. */
151 CTS_EVT_CUR_TIME_NOTIFICATION_DISABLED, /**< Current Time Notification is disabled. */
152 CTS_EVT_CUR_TIME_SET_BY_PEER, /**< Current Time has been set by peer. */
153 CTS_EVT_LOC_TIME_INFO_SET_BY_PEER, /**< Local Time information has been set by peer. */
154 } cts_evt_type_t;
155 /** @} */
156
157 /**
158 * @defgroup CTS_STRUCT Structures
159 * @{
160 */
161 /**@brief CTS Exact Time 256. */
162 typedef struct
163 {
164 prf_date_time_t date_time; /**< Date Time. */
165 uint8_t day_of_week; /**< Day of Week. */
166 uint8_t fractions_256; /**< 1/256th of a second. */
167 } cts_exact_time_256_t;
168
169 /**@brief CTS Current Time value. */
170 typedef struct
171 {
172 cts_exact_time_256_t day_date_time; /**< Exact Time 256. */
173 uint8_t adjust_reason; /**< Adjust Reason. */
174 } cts_cur_time_t;
175
176 /**@brief CTS Local Time Information. */
177 typedef struct
178 {
179 int8_t time_zone; /**< Time Zone, Offset from UTC in number of 15-minute increments. */
180 cts_dst_offset_t dst_offset; /**< Daylight Saving Time Offset. */
181 } cts_loc_time_info_t;
182
183 /**@brief CTS Reference Time Information. */
184 typedef struct
185 {
186 cts_ref_time_source_t source; /**< Time Source. */
187 uint8_t accuracy; /**< Accuracy of time information. */
188 uint8_t days_since_update; /**< Days Since Update. */
189 uint8_t hours_since_update; /**< Hours Since Update. */
190 } cts_ref_time_info_t;
191
192 /**@brief CTS Adjust information. */
193 typedef struct
194 {
195 uint8_t adjust_reason; /**< Adjust Reason. */
196 cts_exact_time_256_t day_date_time; /**< Exact Time 256. */
197 cts_loc_time_info_t loc_time_info; /**< Local Time information. */
198 cts_ref_time_info_t ref_time_info; /**< Reference Time information. */
199 } cts_adj_info_t;
200
201 /**@brief Current Time Service event. */
202 typedef struct
203 {
204 uint8_t conn_idx; /**< The index of the connection. */
205 cts_evt_type_t evt_type; /**< The CTS event type. */
206 const uint8_t *p_data; /**< Pointer to event data. */
207 uint16_t length; /**< Length of event data. */
208 cts_cur_time_t cur_time; /**< Curren time set by peer. */
209 cts_loc_time_info_t loc_time_info; /**< Local time information set by peer. */
210 } cts_evt_t;
211 /** @} */
212
213 /**
214 * @defgroup CTS_TYPEDEF Typedefs
215 * @{
216 */
217 /**@brief Current Time Service event handler type. */
218 typedef void (*cts_evt_handler_t)(cts_evt_t *p_evt);
219 /** @} */
220
221 /**
222 * @defgroup CTS_STRUCT Structures
223 * @{
224 */
225 /**@brief Current Time Service init structure. This contains all option and data needed for initialization of the service. */
226 typedef struct
227 {
228 cts_evt_handler_t evt_handler; /**< Current Time Service event handler. */
229 uint16_t char_mask; /**< Initial mask of supported characteristics, and configured with \ref CTS_CHAR_MASK. */
230 cts_cur_time_t cur_time; /**< Current Time. */
231 cts_loc_time_info_t loc_time_info; /**< Local Time information. */
232 cts_ref_time_info_t ref_time_info; /**< Reference Time information. */
233 } cts_init_t;
234 /** @} */
235
236 /**
237 * @defgroup CTS_FUNCTION Functions
238 * @{
239 */
240 /**
241 *****************************************************************************************
242 * @brief Initialize a Current Time Service instance and add in the DB.
243 *
244 * @param[in] p_cts_init: Pointer to CTS Service initialization variable.
245 *
246 * @return Result of service initialization.
247 *****************************************************************************************
248 */
249 sdk_err_t cts_service_init(cts_init_t *p_cts_init);
250
251 /**
252 *****************************************************************************************
253 * @brief Get exact time for user.
254 *
255 * @param[out] p_exact_time: Pointer to exact time.
256 *****************************************************************************************
257 */
258 void cts_exact_time_get(cts_exact_time_256_t *p_exact_time);
259
260 /**
261 *****************************************************************************************
262 * @brief Update exact time.
263 *
264 * @param[in] p_exact_time: Pointer to exact time.
265 *****************************************************************************************
266 */
267 void cts_exact_time_update(cts_exact_time_256_t *p_exact_time);
268
269 /**
270 *****************************************************************************************
271 * @brief Adjust current time.
272 *
273 * @param[in] p_adj_info: Pointer to adjust information.
274 *****************************************************************************************
275 */
276 void cts_cur_time_adjust(cts_adj_info_t *p_adj_info);
277
278 /**
279 *****************************************************************************************
280 * @brief Send Current Time if its notification has been enabled.
281 *
282 * @param[in] conn_idx: Connnection index.
283 * @param[in] p_cur_time: Pointer to current time.
284 *
285 * @return Result of notify value
286 *****************************************************************************************
287 */
288 sdk_err_t cts_cur_time_send(uint8_t conn_idx, cts_cur_time_t *p_cur_time);
289 /** @} */
290
291 #endif
292 /** @} */
293 /** @} */
294
cts_evt_t::evt_type
cts_evt_type_t evt_type
The CTS event type.
Definition: cts.h:205
cts_ref_time_info_t::days_since_update
uint8_t days_since_update
Days Since Update.
Definition: cts.h:188
CTS_DST_OFFSET_DOUB_DAYLIGHT_TIME
@ CTS_DST_OFFSET_DOUB_DAYLIGHT_TIME
Double Daylight Time (+2h).
Definition: cts.h:131
cts_adj_info_t::ref_time_info
cts_ref_time_info_t ref_time_info
Reference Time information.
Definition: cts.h:198
cts_cur_time_t
CTS Current Time value.
Definition: cts.h:171
cts_adj_info_t::loc_time_info
cts_loc_time_info_t loc_time_info
Local Time information.
Definition: cts.h:197
CTS_EVT_CUR_TIME_SET_BY_PEER
@ CTS_EVT_CUR_TIME_SET_BY_PEER
Current Time has been set by peer.
Definition: cts.h:152
CTS_REF_TIME_SRC_MANUAL
@ CTS_REF_TIME_SRC_MANUAL
Manual.
Definition: cts.h:141
cts_exact_time_256_t::day_of_week
uint8_t day_of_week
Day of Week.
Definition: cts.h:165
cts_evt_t::length
uint16_t length
Length of event data.
Definition: cts.h:207
CTS_WEEK_UNKNOWN_DAY
@ CTS_WEEK_UNKNOWN_DAY
Day of week is not known.
Definition: cts.h:115
cts_loc_time_info_t::dst_offset
cts_dst_offset_t dst_offset
Daylight Saving Time Offset.
Definition: cts.h:180
CTS_EVT_LOC_TIME_INFO_SET_BY_PEER
@ CTS_EVT_LOC_TIME_INFO_SET_BY_PEER
Local Time information has been set by peer.
Definition: cts.h:153
cts_init_t::evt_handler
cts_evt_handler_t evt_handler
Current Time Service event handler.
Definition: cts.h:228
CTS_DST_OFFSET_HALF_HOUR
@ CTS_DST_OFFSET_HALF_HOUR
Half An Hour Daylight Time (+0.5h).
Definition: cts.h:129
CTS_WEEK_SUNDAY
@ CTS_WEEK_SUNDAY
Sunday.
Definition: cts.h:122
CTS_REF_TIME_SRC_ATOMIC_CLOCK
@ CTS_REF_TIME_SRC_ATOMIC_CLOCK
Atomic Clock.
Definition: cts.h:142
CTS_DST_OFFSET_STANDAR_TIME
@ CTS_DST_OFFSET_STANDAR_TIME
Standard Time.
Definition: cts.h:128
gr55xx_sys.h
GR55XX System API.
cts_ref_time_info_t
CTS Reference Time Information.
Definition: cts.h:185
CTS_WEEK_WEDNESDAY
@ CTS_WEEK_WEDNESDAY
Wednesday.
Definition: cts.h:118
CTS_REF_TIME_SRC_UNKNOWN
@ CTS_REF_TIME_SRC_UNKNOWN
Unknown.
Definition: cts.h:137
CTS_REF_TIME_SRC_RADIO_TIME_SIGNAL
@ CTS_REF_TIME_SRC_RADIO_TIME_SIGNAL
Radio Time Signal.
Definition: cts.h:140
CTS_REF_TIME_SRC_CELLUAR_NET
@ CTS_REF_TIME_SRC_CELLUAR_NET
Cellular Network.
Definition: cts.h:143
CTS_EVT_CUR_TIME_NOTIFICATION_DISABLED
@ CTS_EVT_CUR_TIME_NOTIFICATION_DISABLED
Current Time Notification is disabled.
Definition: cts.h:151
CTS_DST_OFFSET_DAYLIGHT_TIME
@ CTS_DST_OFFSET_DAYLIGHT_TIME
Daylight Time (+1h).
Definition: cts.h:130
cts_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: cts.h:204
cts_loc_time_info_t::time_zone
int8_t time_zone
Time Zone, Offset from UTC in number of 15-minute increments.
Definition: cts.h:179
CTS_EVT_INVALID
@ CTS_EVT_INVALID
Invalid event.
Definition: cts.h:149
cts_evt_t::p_data
const uint8_t * p_data
Pointer to event data.
Definition: cts.h:206
cts_exact_time_256_t::date_time
prf_date_time_t date_time
Date Time.
Definition: cts.h:164
cts_exact_time_256_t
CTS Exact Time 256.
Definition: cts.h:163
cts_exact_time_256_t::fractions_256
uint8_t fractions_256
1/256th of a second.
Definition: cts.h:166
cts_init_t::loc_time_info
cts_loc_time_info_t loc_time_info
Local Time information.
Definition: cts.h:231
cts_evt_type_t
cts_evt_type_t
Current Time Service event type.
Definition: cts.h:148
cts_dst_offset_t
cts_dst_offset_t
Local time information:Daylight Saving Time Offset.
Definition: cts.h:127
CTS_REF_TIME_SRC_GPS
@ CTS_REF_TIME_SRC_GPS
GPS.
Definition: cts.h:139
cts_service_init
sdk_err_t cts_service_init(cts_init_t *p_cts_init)
Initialize a Current Time Service instance and add in the DB.
cts_init_t::ref_time_info
cts_ref_time_info_t ref_time_info
Reference Time information.
Definition: cts.h:232
cts_cur_time_send
sdk_err_t cts_cur_time_send(uint8_t conn_idx, cts_cur_time_t *p_cur_time)
Send Current Time if its notification has been enabled.
cts_loc_time_info_t
CTS Local Time Information.
Definition: cts.h:178
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
CTS_REF_TIME_SRC_NET_TIME_PROTOCOL
@ CTS_REF_TIME_SRC_NET_TIME_PROTOCOL
Network Time Protocol.
Definition: cts.h:138
cts_exact_time_get
void cts_exact_time_get(cts_exact_time_256_t *p_exact_time)
Get exact time for user.
cts_init_t::cur_time
cts_cur_time_t cur_time
Current Time.
Definition: cts.h:230
prf_date_time_t
The date and time structure.
Definition: ble_prf_types.h:101
CTS_EVT_CUR_TIME_NOTIFICATION_ENABLED
@ CTS_EVT_CUR_TIME_NOTIFICATION_ENABLED
Current Time Notification is enabled.
Definition: cts.h:150
cts_evt_handler_t
void(* cts_evt_handler_t)(cts_evt_t *p_evt)
Current Time Service event handler type.
Definition: cts.h:218
cts_adj_info_t::day_date_time
cts_exact_time_256_t day_date_time
Exact Time 256.
Definition: cts.h:196
CTS_WEEK_TUSEDAY
@ CTS_WEEK_TUSEDAY
Tuesday.
Definition: cts.h:117
cts_init_t
Current Time Service init structure.
Definition: cts.h:227
cts_exact_time_update
void cts_exact_time_update(cts_exact_time_256_t *p_exact_time)
Update exact time.
cts_ref_time_source_t
cts_ref_time_source_t
Reference time information:Time Source.
Definition: cts.h:136
cts_ref_time_info_t::hours_since_update
uint8_t hours_since_update
Hours Since Update.
Definition: cts.h:189
cts_ref_time_info_t::source
cts_ref_time_source_t source
Time Source.
Definition: cts.h:186
CTS_WEEK_SATURDAY
@ CTS_WEEK_SATURDAY
Saturday.
Definition: cts.h:121
cts_evt_t::cur_time
cts_cur_time_t cur_time
Curren time set by peer.
Definition: cts.h:208
cts_cur_time_adjust
void cts_cur_time_adjust(cts_adj_info_t *p_adj_info)
Adjust current time.
CTS_WEEK_THURSDAT
@ CTS_WEEK_THURSDAT
Thursday.
Definition: cts.h:119
cts_week_day_t
cts_week_day_t
Current Time Day of week.
Definition: cts.h:114
cts_init_t::char_mask
uint16_t char_mask
Initial mask of supported characteristics, and configured with Characteristics Mask.
Definition: cts.h:229
cts_ref_time_info_t::accuracy
uint8_t accuracy
Accuracy of time information.
Definition: cts.h:187
CTS_WEEK_FRIDAY
@ CTS_WEEK_FRIDAY
Friday.
Definition: cts.h:120
ble_prf_utils.h
Profile/Service Utilities API.
cts_cur_time_t::adjust_reason
uint8_t adjust_reason
Adjust Reason.
Definition: cts.h:173
cts_cur_time_t::day_date_time
cts_exact_time_256_t day_date_time
Exact Time 256.
Definition: cts.h:172
cts_adj_info_t
CTS Adjust information.
Definition: cts.h:194
cts_evt_t::loc_time_info
cts_loc_time_info_t loc_time_info
Local time information set by peer.
Definition: cts.h:209
cts_adj_info_t::adjust_reason
uint8_t adjust_reason
Adjust Reason.
Definition: cts.h:195
cts_evt_t
Current Time Service event.
Definition: cts.h:203
CTS_WEEK_MONDAY
@ CTS_WEEK_MONDAY
Monday.
Definition: cts.h:116