dss.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file dss.h
5 *
6 * @brief Device Synchronize 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_DSS Device Synchronize Service (DSS)
46 * @{
47 * @brief Definitions and prototypes for the DSS interface.
48 *
49 * @details The Device Synchronize Service is set for timing synchronization of device group,
50 * which can accept commands such as device role and timing synchronization. In addition,
51 * related information of device timing synchronization can be got through DSS.
52 *
53 * After dss_init_t variable is initialized, the application should call
54 * \ref dss_service_init() to add a Device Synchronize Service and the characteristics
55 * to the BLE Stack database.
56 *
57 */
58
59 #ifndef __DSS_H__
60 #define __DSS_H__
61
62 #include "gr55xx_sys.h"
63 #include "custom_config.h"
64 #include <stdint.h>
65
66 /**
67 * @defgroup DSS_MACRO Defines
68 * @{
69 */
70 #define DSS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
71 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of DSS connections. */
72 #define DSS_ROLE_VALUE_LEN 1 /**< Length of Role characteristic value. */
73 #define DSS_EVT_CNT_VALUE_LEN 4 /**< Length of Event Count characteristic value. */
74 #define DSS_EVT_PERIOD_VALUE_LEN 2 /**< Length of Event Period characteristic value. */
75 #define DSS_STATUS_VALUE_LEN 1 /**< Length of Status characteristic value. */
76 #define DSS_CTRL_PT_VALUE_LEN 7 /**< Length of Control Point characteristic value. */
77 #define DSS_CTRL_PT_RSP_VAL_LEN 3 /**< Length of Control Point Response characteristic value. */
78
79 #define DSS_SYNC_DEV_MAX_NUM 5 /**< Maximun num of Source Sync Device. */
80 #define DSS_CFG_ADV_IDX 0 /**< DSS Config Advertising Index. */
81 #define DSS_SYNC_ADV_IDX 1 /**< DSS Sync Advertising Index. */
82 /** @} */
83
84 /**
85 * @defgroup DSS_ENUM Enumerations
86 * @{
87 */
88 /**@brief Device Synchronize Service roles. */
89 typedef enum
90 {
91 DSS_ROLE_SYNC_INVALID, /**< Device synchronize invalid role. */
92 DSS_ROLE_SYNC_SOURCE, /**< Device synchronize source role (Create synchronize source and distribute). */
93 DSS_ROLE_SYNC_DEVICE, /**< Device synchronize deivce role. */
94 } dss_role_t;
95
96 /**@brief Device Synchronize Service status. */
97 typedef enum
98 {
99 DSS_STATUS_CFG_READY, /**< Device is ready for config, */
100 DSS_STATUS_IN_ADV, /**< Device is in advertising. */
101 DSS_STATUS_IN_SCAN, /**< Device is in scanning. */
102 DSS_STATUS_IN_INITIATING /**< Device is in initiating. */
103 } dss_staus_t;
104
105 /**@brief Device Synchronize Service control point OP IDs. */
106 typedef enum
107 {
108 DSS_OP_ID_INVALID, /**< Invalid op id. */
109 DSS_OP_ID_ROLE_SET, /**< Set role op id.*/
110 DSS_OP_ID_SYNC_SRC_CREATE, /**< Create synchronize source op id. */
111 DSS_OP_ID_SYNC, /**< Synchronize self or peer op id. */
112 DSS_OP_ID_CANCEL_SYNC, /**< Cancel Synchronization op id. */
113 DSS_OP_ID_LP_ENTER, /**< Enter low power mode(Stop all ble activity). */
114 DSS_OP_ID_SYNC_DESTROY, /**< Destroy sync. */
115 DSS_OP_ID_RSP = 0xff /**< Response op id. */
116 } dss_op_id_t;
117
118 /**@brief Device Synchronize Service control point response IDs. */
119 typedef enum
120 {
121 DSS_RSP_ID_SUCCESS, /**< Success. */
122 DSS_RSP_ID_UNSUPPORT, /**< Unsupport op. */
123 DSS_RSP_ID_DISALLOWED, /**< Disallowed op. */
124 DSS_RSP_ID_STATUS_ERR, /**< Status error. */
125 DSS_RSP_ID_PARAM_ERR, /**< Parameter error. */
126 DSS_RSP_ID_ROLE_ERR, /**< Role error. */
127 DSS_RSP_ID_NO_HANDLER, /**< No handler for op. */
128 DSS_RSP_ID_ADV_START_FAIL, /**< Advertising start fail. */
129 DSS_RSP_ID_ADV_TIMEOUT, /**< Advertising start timeout. */
130 DSS_RSP_ID_SCAN_START_FAIL, /**< Scan start fail. */
131 DSS_RSP_ID_SCAN_TIMEOUT, /**< Scan start timeout. */
132 DSS_RSP_ID_CONN_EST_FAIL, /**< Connection establish fail. */
133 DSS_RSP_ID_CREATE_SRC_FAIL, /**< Create source fail. */
134 DSS_RSP_ID_DISTR_SRC_FAIL, /**< Distribute source fail. */
135 DSS_RSP_ID_DESTROY_SRC_FAIL, /**< Destroy source fail. */
136 DSS_RSP_ID_ENTER_LP_FAIL, /**< Enter Low Power Mode fail. */
137 DSS_RSP_ID_CANCEL_SYNC_FAIL, /**< Cancel Synchronization fail. */
138 } dss_rsp_id_t;
139
140
141 /**@brief Device Synchronize Service event types. */
142 typedef enum
143 {
144 DSS_EVT_INVALID, /**< Invalid event. */
145 DSS_EVT_SOURCE_ROLE_SET, /**< Source Role set event. */
146 DSS_EVT_DEVICE_ROLE_SET, /**< Device Role set event. */
147 DSS_EVT_SYNC_SRC_CREATE, /**< Sync source create event. */
148 DSS_EVT_SYNC_DESTROY, /**< Destroy sync event. */
149 DSS_EVT_SYNC_OCCUR, /**< Sync occur event. */
150 DSS_EVT_SYNC_SELF_OR_PEER, /**< Synchronize self or peer event. */
151 DSS_EVT_SYNC_CANCEL, /**< Cancel Synchronization event. */
152 DSS_EVT_LP_ENTER, /**< Enter low power event. */
153 } dss_evt_type_t;
154 /** @} */
155
156 /**
157 * @defgroup DSS_STRUCTURES Structures
158 * @{
159 */
160 /**@brief Device Synchronize Service Synchronize event. */
161 typedef struct
162 {
163 dss_evt_type_t evt_type; /**< Event type. */
164 uint8_t conn_idx; /**< Connect index. */
165 uint32_t sync_cnt; /**< Synchronize count. */
166 uint8_t sync_dev_num; /**< Synchronize Device num. */
167 bool is_enter_lp_mode; /**< In Low Power Mode flag. */
168 } dss_evt_t;
169 /** @} */
170
171 /**
172 * @defgroup DSS_TYPEDEFS Typedefs
173 * @{
174 */
175 /**@brief Device Synchronize Service event handler type. */
176 typedef void (*dss_evt_handler_t)(dss_evt_t *p_evt);
177 /** @} */
178
179
180 /**
181 * @defgroup DIS_FUNCTION Functions
182 * @{
183 */
184 /**
185 *****************************************************************************************
186 * @brief Initialize a Device Synchronize Service instance and add in the database.
187 *
188 * @param[in] evt_handler: DSS event handler.
189 *
190 * @return Result of service initialization.
191 *****************************************************************************************
192 */
193 sdk_err_t dss_service_init(dss_evt_handler_t evt_handler);
194
195 /**
196 *****************************************************************************************
197 * @brief Send Control Point Response.
198 *
199 * @param[in] conn_idx: Connection index.
200 * @param[in] evt_type: Event type.
201 * @param[in] rsp_id: Response ID.
202 *
203 * @return Result of send.
204 *****************************************************************************************
205 */
206 sdk_err_t dss_sync_op_result_send(uint8_t conn_idx, dss_evt_type_t evt_type, dss_rsp_id_t rsp_id);
207
208 /**
209 *****************************************************************************************
210 * @brief Distribute sync source to peer.
211 *
212 * @param[in] conn_idx: Connection index.
213 *****************************************************************************************
214 */
215 void dss_sync_src_distribute(uint8_t conn_idx);
216
217 /**
218 *****************************************************************************************
219 * @brief Set dss status.
220 *
221 * @param[in] conn_idx: Connection index.
222 * @param[in] status: Dss status.
223 *****************************************************************************************
224 */
225 void dss_set_status(uint8_t conn_idx, dss_staus_t status);
226
227 /**
228 *****************************************************************************************
229 * @brief Set Sync params.
230 *
231 * @param[in] conn_idx: Connection index.
232 * @param[in] is_auto_enter_lp: Auto enter low power mode flag.
233 * @param[in] is_auto_calib_drift: Auto calibration drift flag.
234 *****************************************************************************************
235 */
236 void dss_set_sync_params(uint8_t conn_idx, bool is_auto_enter_lp, bool is_auto_calib_drift);
237
238 /**
239 *****************************************************************************************
240 * @brief Set Device whether in low power mode.
241 *
242 * @param[in] conn_idx: Connection index.
243 * @param[in] is_in_lp_mode: Is Device in low power mode.
244 *****************************************************************************************
245 */
246 void dss_set_lp_mode(uint8_t conn_idx, bool is_in_lp_mode);
247 /** @} */
248
249 #endif
250 /** @} */
251 /** @} */
dss_rsp_id_t
dss_rsp_id_t
Device Synchronize Service control point response IDs.
Definition: dss.h:120
DSS_RSP_ID_SCAN_START_FAIL
@ DSS_RSP_ID_SCAN_START_FAIL
Scan start fail.
Definition: dss.h:130
dss_set_sync_params
void dss_set_sync_params(uint8_t conn_idx, bool is_auto_enter_lp, bool is_auto_calib_drift)
Set Sync params.
dss_role_t
dss_role_t
Device Synchronize Service roles.
Definition: dss.h:90
DSS_RSP_ID_ADV_TIMEOUT
@ DSS_RSP_ID_ADV_TIMEOUT
Advertising start timeout.
Definition: dss.h:129
DSS_EVT_SOURCE_ROLE_SET
@ DSS_EVT_SOURCE_ROLE_SET
Source Role set event.
Definition: dss.h:145
DSS_OP_ID_CANCEL_SYNC
@ DSS_OP_ID_CANCEL_SYNC
Cancel Synchronization op id.
Definition: dss.h:112
DSS_ROLE_SYNC_SOURCE
@ DSS_ROLE_SYNC_SOURCE
Device synchronize source role (Create synchronize source and distribute).
Definition: dss.h:92
DSS_RSP_ID_ROLE_ERR
@ DSS_RSP_ID_ROLE_ERR
Role error.
Definition: dss.h:126
DSS_EVT_SYNC_SRC_CREATE
@ DSS_EVT_SYNC_SRC_CREATE
Sync source create event.
Definition: dss.h:147
gr55xx_sys.h
GR55XX System API.
DSS_ROLE_SYNC_DEVICE
@ DSS_ROLE_SYNC_DEVICE
Device synchronize deivce role.
Definition: dss.h:93
dss_evt_t::evt_type
dss_evt_type_t evt_type
Event type.
Definition: dss.h:163
dss_sync_op_result_send
sdk_err_t dss_sync_op_result_send(uint8_t conn_idx, dss_evt_type_t evt_type, dss_rsp_id_t rsp_id)
Send Control Point Response.
DSS_RSP_ID_DISALLOWED
@ DSS_RSP_ID_DISALLOWED
Disallowed op.
Definition: dss.h:123
DSS_RSP_ID_STATUS_ERR
@ DSS_RSP_ID_STATUS_ERR
Status error.
Definition: dss.h:124
dss_evt_handler_t
void(* dss_evt_handler_t)(dss_evt_t *p_evt)
Device Synchronize Service event handler type.
Definition: dss.h:176
DSS_EVT_SYNC_CANCEL
@ DSS_EVT_SYNC_CANCEL
Cancel Synchronization event.
Definition: dss.h:151
dss_evt_t::is_enter_lp_mode
bool is_enter_lp_mode
In Low Power Mode flag.
Definition: dss.h:167
DSS_RSP_ID_ENTER_LP_FAIL
@ DSS_RSP_ID_ENTER_LP_FAIL
Enter Low Power Mode fail.
Definition: dss.h:136
DSS_STATUS_IN_INITIATING
@ DSS_STATUS_IN_INITIATING
Device is in initiating.
Definition: dss.h:102
DSS_EVT_SYNC_DESTROY
@ DSS_EVT_SYNC_DESTROY
Destroy sync event.
Definition: dss.h:148
DSS_OP_ID_SYNC_DESTROY
@ DSS_OP_ID_SYNC_DESTROY
Destroy sync.
Definition: dss.h:114
dss_evt_t::conn_idx
uint8_t conn_idx
Connect index.
Definition: dss.h:164
dss_op_id_t
dss_op_id_t
Device Synchronize Service control point OP IDs.
Definition: dss.h:107
dss_evt_t
Device Synchronize Service Synchronize event.
Definition: dss.h:162
DSS_RSP_ID_ADV_START_FAIL
@ DSS_RSP_ID_ADV_START_FAIL
Advertising start fail.
Definition: dss.h:128
DSS_OP_ID_RSP
@ DSS_OP_ID_RSP
Response op id.
Definition: dss.h:115
dss_staus_t
dss_staus_t
Device Synchronize Service status.
Definition: dss.h:98
dss_service_init
sdk_err_t dss_service_init(dss_evt_handler_t evt_handler)
Initialize a Device Synchronize Service instance and add in the database.
dss_evt_t::sync_dev_num
uint8_t sync_dev_num
Synchronize Device num.
Definition: dss.h:166
DSS_RSP_ID_NO_HANDLER
@ DSS_RSP_ID_NO_HANDLER
No handler for op.
Definition: dss.h:127
DSS_STATUS_IN_SCAN
@ DSS_STATUS_IN_SCAN
Device is in scanning.
Definition: dss.h:101
DSS_EVT_LP_ENTER
@ DSS_EVT_LP_ENTER
Enter low power event.
Definition: dss.h:152
DSS_EVT_DEVICE_ROLE_SET
@ DSS_EVT_DEVICE_ROLE_SET
Device Role set event.
Definition: dss.h:146
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
DSS_OP_ID_ROLE_SET
@ DSS_OP_ID_ROLE_SET
Set role op id.
Definition: dss.h:109
DSS_ROLE_SYNC_INVALID
@ DSS_ROLE_SYNC_INVALID
Device synchronize invalid role.
Definition: dss.h:91
dss_set_lp_mode
void dss_set_lp_mode(uint8_t conn_idx, bool is_in_lp_mode)
Set Device whether in low power mode.
DSS_RSP_ID_PARAM_ERR
@ DSS_RSP_ID_PARAM_ERR
Parameter error.
Definition: dss.h:125
DSS_RSP_ID_SCAN_TIMEOUT
@ DSS_RSP_ID_SCAN_TIMEOUT
Scan start timeout.
Definition: dss.h:131
dss_set_status
void dss_set_status(uint8_t conn_idx, dss_staus_t status)
Set dss status.
DSS_STATUS_IN_ADV
@ DSS_STATUS_IN_ADV
Device is in advertising.
Definition: dss.h:100
DSS_RSP_ID_CONN_EST_FAIL
@ DSS_RSP_ID_CONN_EST_FAIL
Connection establish fail.
Definition: dss.h:132
DSS_OP_ID_SYNC_SRC_CREATE
@ DSS_OP_ID_SYNC_SRC_CREATE
Create synchronize source op id.
Definition: dss.h:110
DSS_EVT_INVALID
@ DSS_EVT_INVALID
Invalid event.
Definition: dss.h:144
DSS_RSP_ID_CREATE_SRC_FAIL
@ DSS_RSP_ID_CREATE_SRC_FAIL
Create source fail.
Definition: dss.h:133
DSS_STATUS_CFG_READY
@ DSS_STATUS_CFG_READY
Device is ready for config,.
Definition: dss.h:99
DSS_OP_ID_LP_ENTER
@ DSS_OP_ID_LP_ENTER
Enter low power mode(Stop all ble activity).
Definition: dss.h:113
DSS_EVT_SYNC_SELF_OR_PEER
@ DSS_EVT_SYNC_SELF_OR_PEER
Synchronize self or peer event.
Definition: dss.h:150
dss_sync_src_distribute
void dss_sync_src_distribute(uint8_t conn_idx)
Distribute sync source to peer.
DSS_EVT_SYNC_OCCUR
@ DSS_EVT_SYNC_OCCUR
Sync occur event.
Definition: dss.h:149
dss_evt_type_t
dss_evt_type_t
Device Synchronize Service event types.
Definition: dss.h:143
DSS_OP_ID_SYNC
@ DSS_OP_ID_SYNC
Synchronize self or peer op id.
Definition: dss.h:111
DSS_RSP_ID_SUCCESS
@ DSS_RSP_ID_SUCCESS
Success.
Definition: dss.h:121
DSS_RSP_ID_DESTROY_SRC_FAIL
@ DSS_RSP_ID_DESTROY_SRC_FAIL
Destroy source fail.
Definition: dss.h:135
DSS_RSP_ID_DISTR_SRC_FAIL
@ DSS_RSP_ID_DISTR_SRC_FAIL
Distribute source fail.
Definition: dss.h:134
DSS_OP_ID_INVALID
@ DSS_OP_ID_INVALID
Invalid op id.
Definition: dss.h:108
DSS_RSP_ID_UNSUPPORT
@ DSS_RSP_ID_UNSUPPORT
Unsupport op.
Definition: dss.h:122
dss_evt_t::sync_cnt
uint32_t sync_cnt
Synchronize count.
Definition: dss.h:165
DSS_RSP_ID_CANCEL_SYNC_FAIL
@ DSS_RSP_ID_CANCEL_SYNC_FAIL
Cancel Synchronization fail.
Definition: dss.h:137