ble_lcp.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file ble_lcp.h
5 *
6 * @brief LCP SDK 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
40 * @{
41 * @brief Definitions and prototypes for the BLE SDK interface.
42 */
43
44 /**
45 * @addtogroup BLE_LCP Light Communication Protocol (LCP)
46 * @{
47 * @brief Definitions and prototypes for the LCP interface.
48 */
49
50 #ifndef _LCP_SDK_H_
51 #define _LCP_SDK_H_
52
53 /**@addtogroup BLE_LCP_TYPEDEFS Typedefs
54 * @{
55 */
56 /**@brief RX handler callback function. */
57 typedef uint16_t (*rx_handler_cb_t) (uint8_t header, uint8_t length, uint8_t *p_payload);
58 typedef void (*rx_done_cb_t) (uint8_t type);
59 typedef void (*tx_done_cb_t) (void);
60 /** @} */
61
62 /**@addtogroup BLE_LCP_ENUMERATIONS Enumerations
63 * @{
64 */
65 enum LCP_RATE
66 {
67 LCP_RATE_1MBPS = 0,
68 LCP_RATE_2MBPS,
69 };
70
71 /**@brief Protocol Mode. */
72 enum PROTOCOL_MODE
73 {
74 BLE_ADV = 0, /**< BLE ADV mode. */
75 BLE_SCAN = 1, /**< BLE SCAN mode. */
76 LCP_TRX_MODE_SW_TX = 2, /*TX by software, just once */
77 LCP_TRX_MODE_SW_RX = 3, /*RX by software, just once */
78 LCP_TRX_MODE_TIMER_TX = 4, /*TX by timer with specified period, will stop when the timer stop */
79 LCP_TRX_MODE_TIMER_RX = 5, /*TX by timer with specified period, will stop when the timer stop */
80 };
81 /** @} */
82
83 /**@addtogroup BLE_LCP_STRUCTURES Structures
84 * @{ */
85 /**@brief LCP Parameter. */
86 typedef struct
87 {
88 uint8_t trx_mode; /**< Set protocol mode, see @ref PROTOCOL_MODE. */
89 int8_t txpwr_dbm; /**< The value of the tx power(range: -20-7), uint: dBm. */
90 uint32_t freq_mhz; /**< The value of the frequency(range: 2360-2520), uint: MHz. */
91 uint32_t access_address; /**< The value of the access address. */
92 uint32_t crc_init; /**< The initial value of the crc. */
93 uint32_t rx_window_size_us;
94 uint8_t rate; /**< LCP_RATE_1MBPS or LCP_RATE_2MBPS*/
95
96 bool whiten_en;
97 bool b_disable_rx_oneshot_mode; /**< should be false in timer trigger mode, support oneshot mode only*/
98
99 /**< Define the lcp timer. Valid while trx_mode=TRX_MODE_TIMER_TX/RX only */
100 uint32_t trx_timer_period_us;
101 /**< Define the trigger time of lcp, valid while trx_mode=TRX_MODE_TIMER_TX/RX only. Should < trx_timer_period_us.
102 Suggest to be a little smaller than trx_timer_period_us, such as trx_timer_period_us - 100us*/
103 uint32_t trx_timer_trigger_trx_time_us;
104 tx_done_cb_t tx_done_cb;
105 rx_done_cb_t rx_done_cb;
106 rx_handler_cb_t rx_handler_cb; /**< The callback function of rx. */
107 } gdx_lcp_config_t;
108 /** @} */
109
110 /** @addtogroup BLE_LCP_FUNCTIONS Functions
111 * @{
112 */
113 /**
114 ****************************************************************************************
115 * @brief Initialize LCP.
116 *
117 * @param[in] gdx_lcp_config: Configure the parameter of LCP, @ref gdx_lcp_config_t.
118 *
119 * @retval ::SDK_SUCCESS: The LCP parameter is successfully configured.
120 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
121 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
122 ****************************************************************************************
123 */
124 uint16_t gdx_lcp_init(gdx_lcp_config_t *gdx_lcp_config);
125
126 /**
127 ****************************************************************************************
128 * @brief Deinitialize LCP.
129 *
130 * @retval ::SDK_SUCCESS: The LCP is successfully Deinitialized.
131 ****************************************************************************************
132 */
133 void gdx_lcp_deinit(void);
134 void gdx_lcp_timer_binding(bool b_dual_timer, uint8_t timer_id);
135
136 /**
137 ****************************************************************************************
138 * @brief Set the tx power of LCP.
139 *
140 * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm.
141 *
142 * @retval ::SDK_SUCCESS: Operation is Success.
143 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
144 ****************************************************************************************
145 */
146 uint16_t gdx_lcp_tx_power_set(int8_t txpwr_dbm);
147
148 /**
149 ****************************************************************************************
150 * @brief Get the tx power of LCP.
151 *
152 * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm.
153 *
154 * @retval ::SDK_SUCCESS: Operation is Success.
155 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
156 ****************************************************************************************
157 */
158 uint16_t gdx_lcp_tx_power_get(int8_t *txpwr_dbm);
159
160 /**
161 ****************************************************************************************
162 * @brief Set the channel of LCP.
163 *
164 * @param[in] freq_mhz: The value of the frequency, Range: 2360MHz to 2520MHz. 2M per step
165 *
166 * @retval ::SDK_SUCCESS: Operation is Success.
167 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
168 ****************************************************************************************
169 */
170 uint16_t gdx_lcp_channel_set(uint32_t freq_mhz);
171
172 /**
173 ****************************************************************************************
174 * @brief Get the channel of LCP.
175 *
176 * @param[in] freq_mhz: The value of the frequency, Range: 2360MHz to 2520MHz.
177 *
178 * @retval ::SDK_SUCCESS: Operation is Success.
179 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
180 ****************************************************************************************
181 */
182 uint16_t gdx_lcp_channel_get(uint32_t *freq_mhz);
183
184 /**
185 ****************************************************************************************
186 * @brief Set lcp access address
187 *
188 * @retval ::SDK_SUCCESS: Operation is Success.
189 ****************************************************************************************
190 */
191 uint16_t gdx_lcp_access_address_set(uint32_t access_address);
192
193 /**
194 ****************************************************************************************
195 * @brief Get lcp rssi
196 *
197 * @return Rssi value.
198 ****************************************************************************************
199 */
200 int8_t gdx_lcp_rssi_get(void);
201
202 /**
203 ****************************************************************************************
204 * @brief Set LCP rx windows size.
205 *
206 * @param[in] time_us: the windows size of rx.
207 *
208 * @retval ::SDK_SUCCESS: Operation is Success.
209 ****************************************************************************************
210 */
211 void gdx_lcp_rx_window_size_set(uint32_t time_us);
212
213
214 /**
215 ****************************************************************************************
216 * @brief Rx oneshot mode enable or disable.
217 *
218 * @param[in] enable: enable oneshot or disable oneshot.
219 ****************************************************************************************
220 */
221 void gdx_lcp_rx_oneshot_mode_set(bool enable);
222
223 /**
224 ****************************************************************************************
225 * @brief Auto TXRX mode enable or disable.
226 *
227 * @param[in] enable: enable auto txrx or disable txrx to sw tx rx.
228 ****************************************************************************************
229 */
230 void gdx_lcp_auto_txrx_mode_set(bool enable);
231
232 /**
233 ****************************************************************************************
234 * @brief Transmmit a packet.
235 *
236 * @param[in] header: The header of the packet.
237 * @param[in] length: The length of the packet payload.
238 * @param[in] p_payload: The pointer of the packet payload.
239 *
240 * @retval ::SDK_SUCCESS: Operation is Success.
241 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
242 ****************************************************************************************
243 */
244 uint16_t gdx_lcp_data_tx(uint8_t header, uint8_t length, uint8_t *p_payload);
245
246 /**
247 ****************************************************************************************
248 * @brief Start receiving packets
249 *
250 * @retval ::SDK_SUCCESS: Operation is Success.
251 ****************************************************************************************
252 */
253 uint16_t gdx_lcp_rx_start(void);
254 uint16_t gdx_lcp_whitening_seed_set(uint8_t whitening_seed);
255
256 /**
257 ****************************************************************************************
258 * @brief Stop receiving packets
259 *
260 * @retval ::SDK_SUCCESS: Operation is Success.
261 ****************************************************************************************
262 */
263 uint16_t gdx_lcp_rx_stop(void);
264
265 void gdx_lcp_t2r_turn_around_time_adjust(uint8_t added_us);
266 void gdx_lcp_r2t_turn_around_time_adjust(uint8_t added_us);
267
268 /** @} */
269
270 #endif
271
272 /** @} */
273 /** @} */
gdx_lcp_rx_window_size_set
void gdx_lcp_rx_window_size_set(uint32_t time_us)
Set LCP rx windows size.
gdx_lcp_channel_get
uint16_t gdx_lcp_channel_get(uint32_t *freq_mhz)
Get the channel of LCP.
LCP_TRX_MODE_SW_TX
@ LCP_TRX_MODE_SW_TX
Definition: ble_lcp.h:76
gdx_lcp_r2t_turn_around_time_adjust
void gdx_lcp_r2t_turn_around_time_adjust(uint8_t added_us)
gdx_lcp_init
uint16_t gdx_lcp_init(gdx_lcp_config_t *gdx_lcp_config)
Initialize LCP.
gdx_lcp_config_t::trx_timer_trigger_trx_time_us
uint32_t trx_timer_trigger_trx_time_us
Definition: ble_lcp.h:103
gdx_lcp_config_t::rx_window_size_us
uint32_t rx_window_size_us
Definition: ble_lcp.h:93
PROTOCOL_MODE
PROTOCOL_MODE
Protocol Mode.
Definition: ble_lcp.h:73
gdx_lcp_config_t::access_address
uint32_t access_address
Definition: ble_lcp.h:91
gdx_lcp_config_t::rx_done_cb
rx_done_cb_t rx_done_cb
Definition: ble_lcp.h:105
gdx_lcp_rssi_get
int8_t gdx_lcp_rssi_get(void)
Get lcp rssi.
gdx_lcp_deinit
void gdx_lcp_deinit(void)
Deinitialize LCP.
gdx_lcp_config_t
LCP Parameter.
Definition: ble_lcp.h:87
gdx_lcp_timer_binding
void gdx_lcp_timer_binding(bool b_dual_timer, uint8_t timer_id)
gdx_lcp_config_t::rate
uint8_t rate
Definition: ble_lcp.h:94
LCP_RATE_2MBPS
@ LCP_RATE_2MBPS
Definition: ble_lcp.h:68
LCP_TRX_MODE_SW_RX
@ LCP_TRX_MODE_SW_RX
Definition: ble_lcp.h:77
LCP_RATE
LCP_RATE
Definition: ble_lcp.h:66
gdx_lcp_tx_power_set
uint16_t gdx_lcp_tx_power_set(int8_t txpwr_dbm)
Set the tx power of LCP.
gdx_lcp_rx_stop
uint16_t gdx_lcp_rx_stop(void)
Stop receiving packets.
LCP_RATE_1MBPS
@ LCP_RATE_1MBPS
Definition: ble_lcp.h:67
LCP_TRX_MODE_TIMER_RX
@ LCP_TRX_MODE_TIMER_RX
Definition: ble_lcp.h:79
gdx_lcp_data_tx
uint16_t gdx_lcp_data_tx(uint8_t header, uint8_t length, uint8_t *p_payload)
Transmmit a packet.
rx_handler_cb_t
uint16_t(* rx_handler_cb_t)(uint8_t header, uint8_t length, uint8_t *p_payload)
RX handler callback function.
Definition: ble_lcp.h:57
gdx_lcp_tx_power_get
uint16_t gdx_lcp_tx_power_get(int8_t *txpwr_dbm)
Get the tx power of LCP.
gdx_lcp_channel_set
uint16_t gdx_lcp_channel_set(uint32_t freq_mhz)
Set the channel of LCP.
gdx_lcp_rx_start
uint16_t gdx_lcp_rx_start(void)
Start receiving packets.
gdx_lcp_config_t::b_disable_rx_oneshot_mode
bool b_disable_rx_oneshot_mode
Definition: ble_lcp.h:97
gdx_lcp_config_t::whiten_en
bool whiten_en
Definition: ble_lcp.h:96
gdx_lcp_config_t::trx_mode
uint8_t trx_mode
Definition: ble_lcp.h:88
gdx_lcp_config_t::crc_init
uint32_t crc_init
Definition: ble_lcp.h:92
gdx_lcp_access_address_set
uint16_t gdx_lcp_access_address_set(uint32_t access_address)
Set lcp access address.
gdx_lcp_config_t::rx_handler_cb
rx_handler_cb_t rx_handler_cb
Definition: ble_lcp.h:106
gdx_lcp_auto_txrx_mode_set
void gdx_lcp_auto_txrx_mode_set(bool enable)
Auto TXRX mode enable or disable.
BLE_ADV
@ BLE_ADV
Definition: ble_lcp.h:74
LCP_TRX_MODE_TIMER_TX
@ LCP_TRX_MODE_TIMER_TX
Definition: ble_lcp.h:78
rx_done_cb_t
void(* rx_done_cb_t)(uint8_t type)
Definition: ble_lcp.h:58
tx_done_cb_t
void(* tx_done_cb_t)(void)
Definition: ble_lcp.h:59
gdx_lcp_config_t::txpwr_dbm
int8_t txpwr_dbm
Definition: ble_lcp.h:89
gdx_lcp_rx_oneshot_mode_set
void gdx_lcp_rx_oneshot_mode_set(bool enable)
Rx oneshot mode enable or disable.
BLE_SCAN
@ BLE_SCAN
Definition: ble_lcp.h:75
gdx_lcp_config_t::freq_mhz
uint32_t freq_mhz
Definition: ble_lcp.h:90
gdx_lcp_t2r_turn_around_time_adjust
void gdx_lcp_t2r_turn_around_time_adjust(uint8_t added_us)
gdx_lcp_whitening_seed_set
uint16_t gdx_lcp_whitening_seed_set(uint8_t whitening_seed)
gdx_lcp_config_t::tx_done_cb
tx_done_cb_t tx_done_cb
Definition: ble_lcp.h:104
gdx_lcp_config_t::trx_timer_period_us
uint32_t trx_timer_period_us
Definition: ble_lcp.h:100