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