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  */
66 {
69 };
70 
71 /**@brief 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  uint32_t trx_timer_period_us; // while trx_mode=TRX_MODE_TIMER_TX/RX only
100  uint32_t trx_timer_trigger_trx_time_us; // while trx_mode=TRX_MODE_TIMER_TX/RX only, should < trx_timer_period_us
103  rx_handler_cb_t rx_handler_cb; /**< The callback function of rx. */
105 /** @} */
106 
107 /** @addtogroup BLE_LCP_FUNCTIONS Functions
108  * @{
109  */
110 /**
111  ****************************************************************************************
112  * @brief Initialize LCP.
113  *
114  * @param[in] gdx_lcp_config: Configure the parameter of LCP, @ref gdx_lcp_config_t.
115  *
116  * @retval ::SDK_SUCCESS: The LCP parameter is successfully configured.
117  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
118  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
119  ****************************************************************************************
120  */
121 uint16_t gdx_lcp_init(gdx_lcp_config_t *gdx_lcp_config);
122 
123 /**
124  ****************************************************************************************
125  * @brief Deinitialize LCP.
126  *
127  * @retval ::SDK_SUCCESS: The LCP is successfully Deinitialized.
128  ****************************************************************************************
129  */
130 void gdx_lcp_deinit(void);
131 void gdx_lcp_timer_binding(bool b_dual_timer, uint8_t timer_id);
132 
133 /**
134  ****************************************************************************************
135  * @brief Set the tx power of LCP.
136  *
137  * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm.
138  *
139  * @retval ::SDK_SUCCESS: Operation is Success.
140  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
141  ****************************************************************************************
142  */
143 uint16_t gdx_lcp_tx_power_set(int8_t txpwr_dbm);
144 
145 /**
146  ****************************************************************************************
147  * @brief Get the tx power of LCP.
148  *
149  * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm.
150  *
151  * @retval ::SDK_SUCCESS: Operation is Success.
152  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
153  ****************************************************************************************
154  */
155 uint16_t gdx_lcp_tx_power_get(int8_t *txpwr_dbm);
156 
157 /**
158  ****************************************************************************************
159  * @brief Set the channel of LCP.
160  *
161  * @param[in] freq_mhz: The value of the frequency, Range: 2360MHz to 2520MHz. 2M per step
162  *
163  * @retval ::SDK_SUCCESS: Operation is Success.
164  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
165  ****************************************************************************************
166  */
167 uint16_t gdx_lcp_channel_set(uint32_t freq_mhz);
168 
169 /**
170  ****************************************************************************************
171  * @brief Get the channel of LCP.
172  *
173  * @param[in] freq_mhz: The value of the frequency, Range: 2360MHz to 2520MHz.
174  *
175  * @retval ::SDK_SUCCESS: Operation is Success.
176  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
177  ****************************************************************************************
178  */
179 uint16_t gdx_lcp_channel_get(uint32_t *freq_mhz);
180 
181 /**
182  ****************************************************************************************
183  * @brief Set LCP rx windows size.
184  *
185  * @param[in] time_us: the windows size of rx.
186  *
187  * @retval ::SDK_SUCCESS: Operation is Success.
188  ****************************************************************************************
189  */
190 void gdx_lcp_rx_window_size_set(uint32_t time_us);
191 
192 
193 /**
194  ****************************************************************************************
195  * @brief Rx oneshot mode enable or disable.
196  *
197  * @param[in] enable: enable oneshot or disable oneshot.
198  ****************************************************************************************
199  */
200 void gdx_lcp_rx_oneshot_mode_set(bool enable);
201 
202 /**
203  ****************************************************************************************
204  * @brief Auto TXRX mode enable or disable.
205  *
206  * @param[in] enable: enable auto txrx or disable txrx to sw tx rx.
207  ****************************************************************************************
208  */
209 void gdx_lcp_auto_txrx_mode_set(bool enable);
210 
211 /**
212  ****************************************************************************************
213  * @brief Transmmit a packet.
214  *
215  * @param[in] header: The header of the packet.
216  * @param[in] length: The length of the packet payload.
217  * @param[in] p_payload: The pointer of the packet payload.
218  *
219  * @retval ::SDK_SUCCESS: Operation is Success.
220  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
221  ****************************************************************************************
222  */
223 uint16_t gdx_lcp_data_tx(uint8_t header, uint8_t length, uint8_t *p_payload);
224 
225 /**
226  ****************************************************************************************
227  * @brief Start receiving packets
228  *
229  * @retval ::SDK_SUCCESS: Operation is Success.
230  ****************************************************************************************
231  */
232 uint16_t gdx_lcp_rx_start(void);
233 uint16_t gdx_lcp_whitening_seed_set(uint8_t whitening_seed);
234 
235 /**
236  ****************************************************************************************
237  * @brief Stop receiving packets
238  *
239  * @retval ::SDK_SUCCESS: Operation is Success.
240  ****************************************************************************************
241  */
242 uint16_t gdx_lcp_rx_stop(void);
243 
244 void gdx_lcp_t2r_turn_around_time_adjust(uint8_t added_us);
245 void gdx_lcp_r2t_turn_around_time_adjust(uint8_t added_us);
246 
247 /** @} */
248 
249 #endif
250 
251 /** @} */
252 /** @} */
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:100
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:102
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_config_t::rx_handler_cb
rx_handler_cb_t rx_handler_cb
Definition: ble_lcp.h:103
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:101
gdx_lcp_config_t::trx_timer_period_us
uint32_t trx_timer_period_us
Definition: ble_lcp.h:99