escs.h
Go to the documentation of this file.
1 /**
2  *****************************************************************************************
3  *
4  * @file escs.h
5  *
6  * @brief Eddystone Configuration 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  * @addtogroup BLE_SRV BLE Services
39  * @{
40  * @brief Definitions and prototypes for the BLE Service interface.
41  */
42 /**
43  * @defgroup BLE_SDK_ESCS BLE Eddystone Configuration Service (ESCS)
44  * @{
45  * @brief Eddystone Configuration Service module.
46  */
47 #ifndef _ESCS_H_
48 #define _ESCS_H_
49 #include "es_app_config.h"
50 #include "es.h"
51 #include "ble_prf_types.h"
52 #include "ble_sdk_error.h"
53 #include "es_utility.h"
54 #include "es_nvds.h"
55 #include "es_gatts_read_write.h"
56 #include <stdbool.h>
57 #include <stdint.h>
58 
59 /**
60  * @defgroup ESCS_ENUM Enumerations
61  * @{
62  */
63 /** @brief ESCS Service Attributes Indexes. */
64 enum escs_attr_idx_t
65 {
66  ESEC_IDX_SVC,
67  ESCS_BROADCAST_CAP_RD_CHAR,
68  ESCS_BROADCAST_CAP_RD_VALUE,
69  ESCS_ACTIVE_SLOT_RW_CHAR,
70  ESCS_ACTIVE_SLOT_RW_VALUE,
71  ESCS_ADV_INTERVAL_RW_CHAR,
72  ESCS_ADV_INTERVAL_RW_VALUE,
73  ESCS_RADIO_TX_PWR_RW_CHAR,
74  ESCS_RADIO_TX_PWR_RW_VALUE,
75  ESCS_ADV_TX_PWR_RW_CHAR,
76  ESCS_ADV_TX_PWR_RW_VALUE,
77  ESCS_LOCK_STATE_RW_CHAR,
78  ESCS_LOCK_STATE_RW_VALUE,
79  ESCS_UNLOCK_RW_CHAR,
80  ESCS_UNLOCK_RW_VALUE,
81  ESCS_PUBLIC_ECDH_KEY_RD_CHAR,
82  ESCS_PUBLIC_ECDH_KEY_RD_VALUE,
83  ESCS_EID_ID_KEY_RD_CHAR,
84  ESCS_EID_ID_KEY_RD_VALUE,
85  ESCS_RW_ADV_SLOT_RW_CHAR,
86  ESCS_RW_ADV_SLOT_RW_VALUE,
87  ESCS_FACTORY_RESET_SET_CHAR,
88  ESCS_FACTORY_RESET_SET_VALUE,
89  ESCS_REMAIN_CONNECTABLE_RW_CHAR,
90  ESCS_REMAIN_CONNECTABLE_RW_VALUE,
91  ESCSS_IDX_NB,
92 };
93 /** @} */
94 
95 /**
96  * @defgroup ESCS_STRUCT Structures
97  * @{
98  */
99 /** @} */
100 /**@brief Structure for storing a slot key. */
101 typedef struct
102 {
103  uint8_t security_key[ESCS_LOCK_CODE_WRITE_LENGTH]; /**< security key.*/
104  uint8_t k_scaler; /**< K rotation scaler.*/
105 } slot_lock_code_t;
106 
107 /**@brief Structure for storing EID slot key. */
108 typedef struct
109 {
110  uint8_t pub_ecdh_key[ESCS_ECDH_KEY_SIZE]; /**< public ecdh key.*/
111  uint8_t k_scaler; /**< K rotation scaler.*/
112 } escs_eid_t;
113 
114 /**@brief EddyStone Configuration Service environment variable. */
115 typedef struct
116 {
117  uint8_t active_slot_no; /**< curret active slot number.*/
118  uint8_t lock_state; /**< beacon lock state.*/
119  uint16_t adv_interval; /**< advertising interval.*/
120  int8_t slot_tx_power[APP_MAX_ADV_SLOTS]; /**< radio tx power.*/
121  int8_t adv_tx_power; /**< advertised tx Power.*/
122  bool remain_connectable; /**< whether to remain connectable.*/
123  slot_lock_code_t beacon_lock_code; /**< beacon lock code.*/
124 #if(APP_IS_EID_SUPPORTED)
125  escs_eid_t eid_slot_data[APP_MAX_ADV_SLOTS];
126 #endif //APP_IS_EID_SUPPORTED
127 }ble_escs_init_params_t;
128 
129 /**
130  * @defgroup ESCE_FUNCTION Functions
131  * @{
132  */
133 /**
134  *****************************************************************************************
135  * @brief get eddystone remain connectable state
136  *
137  * @retval true beacon connectable function is on.
138  * @retval false beacon connectable function is off.
139  *
140  *****************************************************************************************
141  */
142 bool es_adv_remain_connectable_get(void);
143 
144 /**
145  *****************************************************************************************
146  * @brief set eddystone remain connectable state
147  *
148  * @param[in] remain_connectable: turn on or off beacon connectable function.
149  *
150  *****************************************************************************************
151  */
152 void es_adv_remain_connectable_set(bool remain_connectable);
153 
154 /**
155  *****************************************************************************************
156  * @brief get public ecdh key
157  *
158  * @param[out] p_ecdh_key_buf: pointer to key buffer.
159  *
160  *****************************************************************************************
161  */
162 void es_public_ecdh_key_get (uint8_t* p_ecdh_key_buf);
163 
164 /**
165  *****************************************************************************************
166  * @brief set public ecdh key
167  *
168  * @param[in] p_ecdh_key_buf: pointer of key buffer to set.
169  *
170  *****************************************************************************************
171  */
172 void es_public_ecdh_key_set (uint8_t* p_ecdh_key_buf);
173 
174 /**
175  *****************************************************************************************
176  * @brief set security key for slot
177  *
178  * @param[in] p_security_key: pointer to setting key data.
179  * @param[in] is_eid_write: true if the key for EID slot.
180  *
181  *****************************************************************************************
182  */
183 void es_security_key_set(uint8_t* p_security_key,bool is_eid_write);
184 
185 /**
186  *****************************************************************************************
187  * @brief to konw if a beacon has EID slot
188  *
189  * @return true if has EID slot.
190  *
191  *****************************************************************************************
192  */
193 bool es_beacon_has_eid_adv(void);
194 
195 /**
196  *****************************************************************************************
197  * @brief set number of the actived slot
198  *
199  * @param[in] slot_no: the number to be set to actived slot.
200  *
201  *****************************************************************************************
202  */
203 void es_active_slot_number_set (uint8_t slot_no);
204 
205 /**
206  *****************************************************************************************
207  * @brief get number of the actived slot
208  *
209  * @return slot number of the actived slot.
210  *
211  *****************************************************************************************
212  */
213 uint8_t es_active_slot_number_get (void);
214 
215 /**
216  *****************************************************************************************
217  * @brief to know if the actived slot is a n EID slot
218  *
219  *****************************************************************************************
220  */
221 bool is_active_slot_eid(void);
222 
223 /**
224  *****************************************************************************************
225  * @brief lock a beacon
226  *
227  *****************************************************************************************
228  */
229 void set_beacon_locked(void);
230 
231 /**
232  *****************************************************************************************
233  * @brief unlock a beacon
234  *
235  *****************************************************************************************
236  */
237 void set_beacon_unlocked(void);
238 
239 /**
240  *****************************************************************************************
241  * @brief get the radio tx power
242  *
243  * @return tx power(dBm).
244  *
245  *****************************************************************************************
246  */
247 int8_t es_adv_tx_power_get(void);
248 
249 /**
250  *****************************************************************************************
251  * @brief set the radio tx power
252  *
253  * @param[in] adv_tx_power: tx power(dBm) to set.
254  *
255  *****************************************************************************************
256  */
257 void es_adv_tx_power_set(int8_t adv_tx_power);
258 
259 /**
260  *****************************************************************************************
261  * @brief get advertised tx power of a slot
262  *
263  * @return advertised tx power(dBm).
264  *
265  *****************************************************************************************
266  */
267 int8_t es_slot_tx_power_get(void);
268 
269 /**
270  *****************************************************************************************
271  * @brief set advertised tx power of a slot
272  *
273  * @param[in] tx_power: advertised tx power(dBm).
274  *
275  *****************************************************************************************
276  */
277 void es_slot_tx_power_set(int8_t tx_power);
278 
279 /**
280  *****************************************************************************************
281  * @brief get advertising interval for slot
282  *
283  * @return advertising interval(mS).
284  *
285  *****************************************************************************************
286  */
287 uint16_t es_adv_interval_get(void);
288 
289 /**
290  *****************************************************************************************
291  * @brief set advertising interval for slot
292  *
293  * @param[in] adv_interval: advertising interval(mS).
294  *
295  *****************************************************************************************
296  */
297 void es_adv_interval_set (uint16_t adv_interval);
298 
299 /**
300  *****************************************************************************************
301  * @brief Initialize Eddystone Configuration Service,and data for the service.
302  *
303  * @param[in] p_escs_init: pointer to a initializing data structure.
304  *
305  *****************************************************************************************
306  */
307 sdk_err_t esec_service_init(ble_escs_init_params_t *p_escs_init);
308 /** @} */
309 
310 #endif
311 /** @} */
312 /** @} */
es_beacon_has_eid_adv
bool es_beacon_has_eid_adv(void)
to konw if a beacon has EID slot
ble_escs_init_params_t::beacon_lock_code
slot_lock_code_t beacon_lock_code
beacon lock code.
Definition: escs.h:123
ble_escs_init_params_t::remain_connectable
bool remain_connectable
whether to remain connectable.
Definition: escs.h:122
es_slot_tx_power_get
int8_t es_slot_tx_power_get(void)
get advertised tx power of a slot
ble_escs_init_params_t::active_slot_no
uint8_t active_slot_no
curret active slot number.
Definition: escs.h:117
es_adv_interval_get
uint16_t es_adv_interval_get(void)
get advertising interval for slot
escs_eid_t
Structure for storing EID slot key.
Definition: escs.h:109
es_active_slot_number_set
void es_active_slot_number_set(uint8_t slot_no)
set number of the actived slot
slot_lock_code_t::k_scaler
uint8_t k_scaler
K rotation scaler.
Definition: escs.h:104
es_public_ecdh_key_get
void es_public_ecdh_key_get(uint8_t *p_ecdh_key_buf)
get public ecdh key
ble_escs_init_params_t::adv_interval
uint16_t adv_interval
advertising interval.
Definition: escs.h:119
es_adv_tx_power_get
int8_t es_adv_tx_power_get(void)
get the radio tx power
esec_service_init
sdk_err_t esec_service_init(ble_escs_init_params_t *p_escs_init)
Initialize Eddystone Configuration Service,and data for the service.
es_adv_remain_connectable_set
void es_adv_remain_connectable_set(bool remain_connectable)
set eddystone remain connectable state
ble_prf_types.h
Profile/Service Common Types.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
escs_attr_idx_t
escs_attr_idx_t
ESCS Service Attributes Indexes.
Definition: escs.h:65
es_slot_tx_power_set
void es_slot_tx_power_set(int8_t tx_power)
set advertised tx power of a slot
ble_escs_init_params_t::lock_state
uint8_t lock_state
beacon lock state.
Definition: escs.h:118
set_beacon_unlocked
void set_beacon_unlocked(void)
unlock a beacon
es_public_ecdh_key_set
void es_public_ecdh_key_set(uint8_t *p_ecdh_key_buf)
set public ecdh key
escs_eid_t::k_scaler
uint8_t k_scaler
K rotation scaler.
Definition: escs.h:111
es_security_key_set
void es_security_key_set(uint8_t *p_security_key, bool is_eid_write)
set security key for slot
es_active_slot_number_get
uint8_t es_active_slot_number_get(void)
get number of the actived slot
ble_escs_init_params_t::adv_tx_power
int8_t adv_tx_power
advertised tx Power.
Definition: escs.h:121
es_adv_remain_connectable_get
bool es_adv_remain_connectable_get(void)
get eddystone remain connectable state
set_beacon_locked
void set_beacon_locked(void)
lock a beacon
slot_lock_code_t
Structure for storing a slot key.
Definition: escs.h:102
es_adv_interval_set
void es_adv_interval_set(uint16_t adv_interval)
set advertising interval for slot
ble_escs_init_params_t
EddyStone Configuration Service environment variable.
Definition: escs.h:116
is_active_slot_eid
bool is_active_slot_eid(void)
to know if the actived slot is a n EID slot
es_adv_tx_power_set
void es_adv_tx_power_set(int8_t adv_tx_power)
set the radio tx power