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