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. */
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). */
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. */
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. */
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. */
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. */
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. */
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. */
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. */
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  */
250 
251 /**
252  *****************************************************************************************
253  * @brief Get exact time for user.
254  *
255  * @param[out] p_exact_time: Pointer to exact time.
256  *****************************************************************************************
257  */
259 
260 /**
261  *****************************************************************************************
262  * @brief Update exact time.
263  *
264  * @param[in] p_exact_time: Pointer to exact time.
265  *****************************************************************************************
266  */
268 
269 /**
270  *****************************************************************************************
271  * @brief Adjust current time.
272  *
273  * @param[in] p_adj_info: Pointer to adjust information.
274  *****************************************************************************************
275  */
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