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