amiro-lld / drivers / DW1000 / v2 / decadriver / deca_device_api.h @ 22401187
History | View | Annotate | Download (83.122 KB)
1 |
/*! ----------------------------------------------------------------------------
|
---|---|
2 |
* @file deca_device_api.h
|
3 |
* @brief DW1000 API Functions
|
4 |
*
|
5 |
* @attention
|
6 |
*
|
7 |
* Copyright 2013 (c) Decawave Ltd, Dublin, Ireland.
|
8 |
*
|
9 |
* All rights reserved.
|
10 |
*
|
11 |
*/
|
12 |
|
13 |
#ifndef _DECA_DEVICE_API_H_
|
14 |
#define _DECA_DEVICE_API_H_
|
15 |
|
16 |
#ifdef __cplusplus
|
17 |
extern "C" { |
18 |
#endif
|
19 |
|
20 |
|
21 |
#ifndef uint8
|
22 |
#ifndef _DECA_UINT8_
|
23 |
#define _DECA_UINT8_
|
24 |
typedef unsigned char uint8; |
25 |
#endif
|
26 |
#endif
|
27 |
|
28 |
#ifndef uint16
|
29 |
#ifndef _DECA_UINT16_
|
30 |
#define _DECA_UINT16_
|
31 |
typedef unsigned short uint16; |
32 |
#endif
|
33 |
#endif
|
34 |
|
35 |
#ifndef uint32
|
36 |
#ifndef _DECA_UINT32_
|
37 |
#define _DECA_UINT32_
|
38 |
typedef unsigned long uint32; |
39 |
#endif
|
40 |
#endif
|
41 |
|
42 |
#ifndef int8
|
43 |
#ifndef _DECA_INT8_
|
44 |
#define _DECA_INT8_
|
45 |
typedef signed char int8; |
46 |
#endif
|
47 |
#endif
|
48 |
|
49 |
#ifndef int16
|
50 |
#ifndef _DECA_INT16_
|
51 |
#define _DECA_INT16_
|
52 |
typedef signed short int16; |
53 |
#endif
|
54 |
#endif
|
55 |
|
56 |
#ifndef int32
|
57 |
#ifndef _DECA_INT32_
|
58 |
#define _DECA_INT32_
|
59 |
typedef signed long int32; |
60 |
#endif
|
61 |
#endif
|
62 |
|
63 |
#ifndef DWT_NUM_DW_DEV
|
64 |
#define DWT_NUM_DW_DEV (1) |
65 |
#endif
|
66 |
|
67 |
#define DWT_SUCCESS (0) |
68 |
#define DWT_ERROR (-1) |
69 |
|
70 |
#define DWT_TIME_UNITS (1.0/499.2e6/128.0) //!< = 15.65e-12 s |
71 |
|
72 |
#define DWT_DEVICE_ID (0xDECA0130) //!< DW1000 MP device ID |
73 |
|
74 |
//! constants for selecting the bit rate for data TX (and RX)
|
75 |
//! These are defined for write (with just a shift) the TX_FCTRL register
|
76 |
#define DWT_BR_110K 0 //!< UWB bit rate 110 kbits/s |
77 |
#define DWT_BR_850K 1 //!< UWB bit rate 850 kbits/s |
78 |
#define DWT_BR_6M8 2 //!< UWB bit rate 6.8 Mbits/s |
79 |
|
80 |
//! constants for specifying the (Nominal) mean Pulse Repetition Frequency
|
81 |
//! These are defined for direct write (with a shift if necessary) to CHAN_CTRL and TX_FCTRL regs
|
82 |
#define DWT_PRF_16M 1 //!< UWB PRF 16 MHz |
83 |
#define DWT_PRF_64M 2 //!< UWB PRF 64 MHz |
84 |
|
85 |
//! constants for specifying Preamble Acquisition Chunk (PAC) Size in symbols
|
86 |
#define DWT_PAC8 0 //!< PAC 8 (recommended for RX of preamble length 128 and below |
87 |
#define DWT_PAC16 1 //!< PAC 16 (recommended for RX of preamble length 256 |
88 |
#define DWT_PAC32 2 //!< PAC 32 (recommended for RX of preamble length 512 |
89 |
#define DWT_PAC64 3 //!< PAC 64 (recommended for RX of preamble length 1024 and up |
90 |
|
91 |
//! constants for specifying TX Preamble length in symbols
|
92 |
//! These are defined to allow them be directly written into byte 2 of the TX_FCTRL register
|
93 |
//! (i.e. a four bit value destined for bits 20..18 but shifted left by 2 for byte alignment)
|
94 |
#define DWT_PLEN_4096 0x0C //! Standard preamble length 4096 symbols |
95 |
#define DWT_PLEN_2048 0x28 //! Non-standard preamble length 2048 symbols |
96 |
#define DWT_PLEN_1536 0x18 //! Non-standard preamble length 1536 symbols |
97 |
#define DWT_PLEN_1024 0x08 //! Standard preamble length 1024 symbols |
98 |
#define DWT_PLEN_512 0x34 //! Non-standard preamble length 512 symbols |
99 |
#define DWT_PLEN_256 0x24 //! Non-standard preamble length 256 symbols |
100 |
#define DWT_PLEN_128 0x14 //! Non-standard preamble length 128 symbols |
101 |
#define DWT_PLEN_64 0x04 //! Standard preamble length 64 symbols |
102 |
|
103 |
#define DWT_SFDTOC_DEF 0x1041 // default SFD timeout value |
104 |
|
105 |
#define DWT_PHRMODE_STD 0x0 // standard PHR mode |
106 |
#define DWT_PHRMODE_EXT 0x3 // DW proprietary extended frames PHR mode |
107 |
|
108 |
// Defined constants for "mode" bitmask parameter passed into dwt_starttx() function.
|
109 |
#define DWT_START_TX_IMMEDIATE 0 |
110 |
#define DWT_START_TX_DELAYED 1 |
111 |
#define DWT_RESPONSE_EXPECTED 2 |
112 |
|
113 |
#define DWT_START_RX_IMMEDIATE 0 |
114 |
#define DWT_START_RX_DELAYED 1 // Set up delayed RX, if "late" error triggers, then the RX will be enabled immediately |
115 |
#define DWT_IDLE_ON_DLY_ERR 2 // If delayed RX failed due to "late" error then if this |
116 |
// flag is set the RX will not be re-enabled immediately, and device will be in IDLE when function exits
|
117 |
#define DWT_NO_SYNC_PTRS 4 // Do not try to sync IC side and Host side buffer pointers when enabling RX. This is used to perform manual RX |
118 |
// re-enabling when receiving a frame in double buffer mode.
|
119 |
|
120 |
// Defined constants for "mode" bit field parameter passed to dwt_setleds() function.
|
121 |
#define DWT_LEDS_DISABLE 0x00 |
122 |
#define DWT_LEDS_ENABLE 0x01 |
123 |
#define DWT_LEDS_INIT_BLINK 0x02 |
124 |
|
125 |
// Defined constants for "lna_pa" bit field parameter passed to dwt_setlnapamode() function
|
126 |
#define DWT_LNA_PA_DISABLE 0x00 |
127 |
#define DWT_LNA_ENABLE 0x01 |
128 |
#define DWT_PA_ENABLE 0x02 |
129 |
|
130 |
//frame filtering configuration options
|
131 |
#define DWT_FF_NOTYPE_EN 0x000 // no frame types allowed (FF disabled) |
132 |
#define DWT_FF_COORD_EN 0x002 // behave as coordinator (can receive frames with no dest address (PAN ID has to match)) |
133 |
#define DWT_FF_BEACON_EN 0x004 // beacon frames allowed |
134 |
#define DWT_FF_DATA_EN 0x008 // data frames allowed |
135 |
#define DWT_FF_ACK_EN 0x010 // ack frames allowed |
136 |
#define DWT_FF_MAC_EN 0x020 // mac control frames allowed |
137 |
#define DWT_FF_RSVD_EN 0x040 // reserved frame types allowed |
138 |
|
139 |
//DW1000 interrupt events
|
140 |
#define DWT_INT_TFRS 0x00000080 // frame sent |
141 |
#define DWT_INT_LDED 0x00000400 // micro-code has finished execution |
142 |
#define DWT_INT_RFCG 0x00004000 // frame received with good CRC |
143 |
#define DWT_INT_RPHE 0x00001000 // receiver PHY header error |
144 |
#define DWT_INT_RFCE 0x00008000 // receiver CRC error |
145 |
#define DWT_INT_RFSL 0x00010000 // receiver sync loss error |
146 |
#define DWT_INT_RFTO 0x00020000 // frame wait timeout |
147 |
#define DWT_INT_RXOVRR 0x00100000 // receiver overrun |
148 |
#define DWT_INT_RXPTO 0x00200000 // preamble detect timeout |
149 |
#define DWT_INT_GPIO 0x00400000 // GPIO interrupt |
150 |
#define DWT_INT_SFDT 0x04000000 // SFD timeout |
151 |
#define DWT_INT_ARFE 0x20000000 // frame rejected (due to frame filtering configuration) |
152 |
|
153 |
|
154 |
//DW1000 SLEEP and WAKEUP configuration parameters
|
155 |
#define DWT_PRESRV_SLEEP 0x0100 // PRES_SLEEP - on wakeup preserve sleep bit |
156 |
#define DWT_LOADOPSET 0x0080 // ONW_L64P - on wakeup load operating parameter set for 64 PSR |
157 |
#define DWT_CONFIG 0x0040 // ONW_LDC - on wakeup restore (load) the saved configurations (from AON array into HIF) |
158 |
#define DWT_LOADEUI 0x0008 // ONW_LEUI - on wakeup load EUI |
159 |
#define DWT_RX_EN 0x0002 // ONW_RX - on wakeup activate reception |
160 |
#define DWT_TANDV 0x0001 // ONW_RADC - on wakeup run ADC to sample temperature and voltage sensor values |
161 |
|
162 |
#define DWT_XTAL_EN 0x10 // keep XTAL running during sleep |
163 |
#define DWT_WAKE_SLPCNT 0x8 // wake up after sleep count |
164 |
#define DWT_WAKE_CS 0x4 // wake up on chip select |
165 |
#define DWT_WAKE_WK 0x2 // wake up on WAKEUP PIN |
166 |
#define DWT_SLP_EN 0x1 // enable sleep/deep sleep functionality |
167 |
|
168 |
//DWT_DW_POWER_ON should be used when dwt_initialise is called on cold power up of DW IC
|
169 |
//When DW IC is being initialised after wake up then some of the init steps can be skipped
|
170 |
//DW1000 INIT configuration parameters
|
171 |
#define DWT_LOADNONE 0x00 // no loading of micro-code or reading of OTP values |
172 |
#define DWT_LOADUCODE 0x01 // this can be called on power up or after wake up to load ucode |
173 |
#define DWT_DW_WAKE_UP 0x02 // init after wake up - will not load ucode / ucode will not run |
174 |
#define DWT_DW_WUP_NO_UCODE 0x04 // init after wake up - ucode has not already been loaded / ucode is not used |
175 |
#define DWT_DW_WUP_RD_OTPREV 0x08 // init after wakeup - read OTP rev after wake up |
176 |
#define DWT_READ_OTP_PID 0x10 // read part ID from OTP |
177 |
#define DWT_READ_OTP_LID 0x20 // read lot ID from OTP |
178 |
#define DWT_READ_OTP_BAT 0x40 // read ref voltage from OTP |
179 |
#define DWT_READ_OTP_TMP 0x80 // read ref temperature from OTP |
180 |
|
181 |
|
182 |
//DW1000 OTP operating parameter set selection
|
183 |
#define DWT_OPSET_64LEN 0x0 |
184 |
#define DWT_OPSET_TIGHT 0x1 |
185 |
#define DWT_OPSET_DEFLT 0x2 |
186 |
|
187 |
//GPIOs
|
188 |
#define DWT_GxP0 0x00000001UL /* GPIO0 Only changed if the GxM0 mask bit has a value of 1 for the write operation*/ |
189 |
#define DWT_GxP1 0x00000002UL /* GPIO1.*/ |
190 |
#define DWT_GxP2 0x00000004UL /* GPIO2.*/ |
191 |
#define DWT_GxP3 0x00000008UL /* GPIO3.*/ |
192 |
#define DWT_GxP4 0x00000100UL /* GPIO4.*/ |
193 |
#define DWT_GxP5 0x00000200UL /* GPIO5.*/ |
194 |
#define DWT_GxP6 0x00000400UL /* GPIO6.*/ |
195 |
#define DWT_GxP7 0x00000800UL /* GPIO7.*/ |
196 |
#define DWT_GxP8 0x00010000UL /* GPIO8 */ |
197 |
|
198 |
#define DWT_GxM0 0x00000010UL /* Mask for GPIO0 */ |
199 |
#define DWT_GxM1 0x00000020UL /* Mask for GPIO1 */ |
200 |
#define DWT_GxM2 0x00000040UL /* Mask for GPIO2 */ |
201 |
#define DWT_GxM3 0x00000080UL /* Mask for GPIO3 */ |
202 |
#define DWT_GxM4 0x00001000UL /* Mask for GPIO4 */ |
203 |
#define DWT_GxM5 0x00002000UL /* Mask for GPIO5 */ |
204 |
#define DWT_GxM6 0x00004000UL /* Mask for GPIO6 */ |
205 |
#define DWT_GxM7 0x00008000UL /* Mask for GPIO7 */ |
206 |
#define DWT_GxM8 0x00100000UL /* Mask for GPIO8 */ |
207 |
|
208 |
|
209 |
// Call-back data RX frames flags
|
210 |
#define DWT_CB_DATA_RX_FLAG_RNG 0x1 // Ranging bit |
211 |
|
212 |
// TX/RX call-back data
|
213 |
typedef struct |
214 |
{ |
215 |
uint32 status; //initial value of register as ISR is entered
|
216 |
uint16 datalength; //length of frame
|
217 |
uint8 fctrl[2]; //frame control bytes |
218 |
uint8 rx_flags; //RX frame flags, see above
|
219 |
} dwt_cb_data_t; |
220 |
|
221 |
// Call-back type for all events
|
222 |
typedef void (*dwt_cb_t)(const dwt_cb_data_t *); |
223 |
|
224 |
/*! ------------------------------------------------------------------------------------------------------------------
|
225 |
* Structure typedef: dwt_config_t
|
226 |
*
|
227 |
* Structure for setting device configuration via dwt_configure() function
|
228 |
*
|
229 |
*/
|
230 |
typedef struct |
231 |
{ |
232 |
uint8 chan ; //!< channel number {1, 2, 3, 4, 5, 7 }
|
233 |
uint8 prf ; //!< Pulse Repetition Frequency {DWT_PRF_16M or DWT_PRF_64M}
|
234 |
uint8 txPreambLength ; //!< DWT_PLEN_64..DWT_PLEN_4096
|
235 |
uint8 rxPAC ; //!< Acquisition Chunk Size (Relates to RX preamble length)
|
236 |
uint8 txCode ; //!< TX preamble code
|
237 |
uint8 rxCode ; //!< RX preamble code
|
238 |
uint8 nsSFD ; //!< Boolean should we use non-standard SFD for better performance
|
239 |
uint8 dataRate ; //!< Data Rate {DWT_BR_110K, DWT_BR_850K or DWT_BR_6M8}
|
240 |
uint8 phrMode ; //!< PHR mode {0x0 - standard DWT_PHRMODE_STD, 0x3 - extended frames DWT_PHRMODE_EXT}
|
241 |
uint16 sfdTO ; //!< SFD timeout value (in symbols)
|
242 |
} dwt_config_t ; |
243 |
|
244 |
|
245 |
typedef struct |
246 |
{ |
247 |
uint8 PGdly; |
248 |
//TX POWER
|
249 |
//31:24 BOOST_0.125ms_PWR
|
250 |
//23:16 BOOST_0.25ms_PWR-TX_SHR_PWR
|
251 |
//15:8 BOOST_0.5ms_PWR-TX_PHR_PWR
|
252 |
//7:0 DEFAULT_PWR-TX_DATA_PWR
|
253 |
uint32 power; |
254 |
} |
255 |
dwt_txconfig_t ; |
256 |
|
257 |
|
258 |
typedef struct |
259 |
{ |
260 |
|
261 |
uint16 maxNoise ; // LDE max value of noise
|
262 |
uint16 firstPathAmp1 ; // Amplitude at floor(index FP) + 1
|
263 |
uint16 stdNoise ; // Standard deviation of noise
|
264 |
uint16 firstPathAmp2 ; // Amplitude at floor(index FP) + 2
|
265 |
uint16 firstPathAmp3 ; // Amplitude at floor(index FP) + 3
|
266 |
uint16 maxGrowthCIR ; // Channel Impulse Response max growth CIR
|
267 |
uint16 rxPreamCount ; // Count of preamble symbols accumulated
|
268 |
uint16 firstPath ; // First path index (10.6 bits fixed point integer)
|
269 |
}dwt_rxdiag_t ; |
270 |
|
271 |
|
272 |
typedef struct |
273 |
{ |
274 |
//all of the below are mapped to a 12-bit register in DW1000
|
275 |
uint16 PHE ; //number of received header errors
|
276 |
uint16 RSL ; //number of received frame sync loss events
|
277 |
uint16 CRCG ; //number of good CRC received frames
|
278 |
uint16 CRCB ; //number of bad CRC (CRC error) received frames
|
279 |
uint16 ARFE ; //number of address filter errors
|
280 |
uint16 OVER ; //number of receiver overflows (used in double buffer mode)
|
281 |
uint16 SFDTO ; //SFD timeouts
|
282 |
uint16 PTO ; //Preamble timeouts
|
283 |
uint16 RTO ; //RX frame wait timeouts
|
284 |
uint16 TXF ; //number of transmitted frames
|
285 |
uint16 HPW ; //half period warn
|
286 |
uint16 TXW ; //power up warn
|
287 |
|
288 |
} dwt_deviceentcnts_t ; |
289 |
|
290 |
|
291 |
/********************************************************************************************************************/
|
292 |
/* REMOVED API LIST */
|
293 |
/********************************************************************************************************************/
|
294 |
/*
|
295 |
* From version 5.0.0:
|
296 |
* - dwt_getinitxtaltrim: Replaced by the function dwt_getxtaltrim which returns current xtal trim value
|
297 |
*
|
298 |
* From version 4.0.0:
|
299 |
* - dwt_setGPIOforEXTTRX: Replaced by dwt_setlnapamode to get equivalent functionality.
|
300 |
* - dwt_setGPIOdirection: Renamed to dwt_setgpiodirection.
|
301 |
* - dwt_setGPIOvalue: Renamed to dwt_setgpiovalue.
|
302 |
* - dwt_setrxmode: Replaced by dwt_setsniffmode and dwt_setlowpowerlistening depending on the RX mode the user
|
303 |
* wants to set up.
|
304 |
* - dwt_checkoverrun: As automatic RX re-enabling is not supported anymore, this functions has become useless.
|
305 |
* - dwt_setautorxreenable: As automatic RX re-enabling is not supported anymore, this functions has become
|
306 |
* useless.
|
307 |
* - dwt_getrangebias: Range bias correction values are platform dependent and should therefore be managed at user
|
308 |
* application level.
|
309 |
* - dwt_xtaltrim: Renamed to dwt_setxtaltrim.
|
310 |
* - dwt_checkIRQ: Renamed to dwt_checkirq.
|
311 |
*
|
312 |
* From version 3.0.0:
|
313 |
* - dwt_getldotune: As LDO loading is now automatically managed by the driver, this function has become useless.
|
314 |
* - dwt_getotptxpower: TX power values and location in OTP memory are platform dependent and should therefore be
|
315 |
* managed at user application level.
|
316 |
* - dwt_readantennadelay: Antenna delay values and location in OTP memory are platform dependent and should
|
317 |
* therefore be managed at user application level.
|
318 |
* - dwt_readdignostics: Renamed to dwt_readdiagnostics.
|
319 |
*/
|
320 |
|
321 |
/********************************************************************************************************************/
|
322 |
/* API LIST */
|
323 |
/********************************************************************************************************************/
|
324 |
|
325 |
/*! ------------------------------------------------------------------------------------------------------------------
|
326 |
* @fn dwt_apiversion()
|
327 |
*
|
328 |
* @brief This function returns the version of the API as defined by DW1000_DRIVER_VERSION
|
329 |
*
|
330 |
* input parameters
|
331 |
*
|
332 |
* output parameters
|
333 |
*
|
334 |
* returns version (DW1000_DRIVER_VERSION)
|
335 |
*/
|
336 |
int32 dwt_apiversion(void);
|
337 |
|
338 |
/*! ------------------------------------------------------------------------------------------------------------------
|
339 |
* @fn dwt_setlocaldataptr()
|
340 |
*
|
341 |
* @brief This function sets the local data structure pointer to point to the element in the local array as given by the index.
|
342 |
*
|
343 |
* input parameters
|
344 |
* @param index - selects the array element to point to. Must be within the array bounds, i.e. < DWT_NUM_DW_DEV
|
345 |
*
|
346 |
* output parameters
|
347 |
*
|
348 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error
|
349 |
*/
|
350 |
int dwt_setlocaldataptr(unsigned int index); |
351 |
|
352 |
/*! ------------------------------------------------------------------------------------------------------------------
|
353 |
* @fn dwt_geticrefvolt()
|
354 |
*
|
355 |
* @brief This is used to return the read V measured @ 3.3 V value recorded in OTP address 0x8 (VBAT_ADDRESS)
|
356 |
*
|
357 |
* NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
|
358 |
*
|
359 |
* input parameters
|
360 |
*
|
361 |
* output parameters
|
362 |
*
|
363 |
* returns the 8 bit V meas value as programmed in the factory
|
364 |
*/
|
365 |
uint8 dwt_geticrefvolt(void);
|
366 |
|
367 |
/*! ------------------------------------------------------------------------------------------------------------------
|
368 |
* @fn dwt_geticreftemp()
|
369 |
*
|
370 |
* @brief This is used to return the read T measured @ 23 C value recorded in OTP address 0x9 (VTEMP_ADDRESS)
|
371 |
*
|
372 |
* NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
|
373 |
*
|
374 |
* input parameters
|
375 |
*
|
376 |
* output parameters
|
377 |
*
|
378 |
* returns the 8 bit T meas value as programmed in the factory
|
379 |
*/
|
380 |
uint8 dwt_geticreftemp(void);
|
381 |
|
382 |
/*! ------------------------------------------------------------------------------------------------------------------
|
383 |
* @fn dwt_getpartid()
|
384 |
*
|
385 |
* @brief This is used to return the read part ID (or chip ID) of the device
|
386 |
*
|
387 |
* NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value (stored in OTP).
|
388 |
*
|
389 |
* input parameters
|
390 |
*
|
391 |
* output parameters
|
392 |
*
|
393 |
* returns the 32 bit part ID (or chip ID) value as programmed in the factory
|
394 |
*/
|
395 |
uint32 dwt_getpartid(void);
|
396 |
|
397 |
/*! ------------------------------------------------------------------------------------------------------------------
|
398 |
* @fn dwt_getlotid()
|
399 |
*
|
400 |
* @brief This is used to return the read lot ID of the device
|
401 |
*
|
402 |
* NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
|
403 |
*
|
404 |
* input parameters
|
405 |
*
|
406 |
* output parameters
|
407 |
*
|
408 |
* returns the 32 bit lot ID value as programmed in the factory
|
409 |
*/
|
410 |
uint32 dwt_getlotid(void);
|
411 |
|
412 |
/*! ------------------------------------------------------------------------------------------------------------------
|
413 |
* @fn dwt_readdevid()
|
414 |
*
|
415 |
* @brief This is used to return the read device type and revision information of the DW1000 device (MP part is 0xDECA0130)
|
416 |
*
|
417 |
* input parameters
|
418 |
*
|
419 |
* output parameters
|
420 |
*
|
421 |
* returns the read value which for DW1000 is 0xDECA0130
|
422 |
*/
|
423 |
uint32 dwt_readdevid(void);
|
424 |
|
425 |
/*! ------------------------------------------------------------------------------------------------------------------
|
426 |
* @fn dwt_otprevision()
|
427 |
*
|
428 |
* @brief This is used to return the read OTP revision
|
429 |
*
|
430 |
* NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
|
431 |
*
|
432 |
* input parameters
|
433 |
*
|
434 |
* output parameters
|
435 |
*
|
436 |
* returns the read OTP revision value
|
437 |
*/
|
438 |
uint8 dwt_otprevision(void);
|
439 |
|
440 |
/*! ------------------------------------------------------------------------------------------------------------------
|
441 |
* @fn dwt_setfinegraintxseq()
|
442 |
*
|
443 |
* @brief This function enables/disables the fine grain TX sequencing (enabled by default).
|
444 |
*
|
445 |
* input parameters
|
446 |
* @param enable - 1 to enable fine grain TX sequencing, 0 to disable it.
|
447 |
*
|
448 |
* output parameters none
|
449 |
*
|
450 |
* no return value
|
451 |
*/
|
452 |
void dwt_setfinegraintxseq(int enable); |
453 |
|
454 |
/*! ------------------------------------------------------------------------------------------------------------------
|
455 |
* @fn dwt_setlnapamode()
|
456 |
*
|
457 |
* @brief This is used to enable GPIO for external LNA or PA functionality - HW dependent, consult the DW1000 User Manual.
|
458 |
* This can also be used for debug as enabling TX and RX GPIOs is quite handy to monitor DW1000's activity.
|
459 |
*
|
460 |
* NOTE: Enabling PA functionality requires that fine grain TX sequencing is deactivated. This can be done using
|
461 |
* dwt_setfinegraintxseq().
|
462 |
*
|
463 |
* input parameters
|
464 |
* @param lna_pa - bit field: bit 0 if set will enable LNA functionality,
|
465 |
* : bit 1 if set will enable PA functionality,
|
466 |
* : to disable LNA/PA set the bits to 0
|
467 |
* output parameters
|
468 |
*
|
469 |
* no return value
|
470 |
*/
|
471 |
void dwt_setlnapamode(int lna_pa); |
472 |
|
473 |
/*! ------------------------------------------------------------------------------------------------------------------
|
474 |
* @fn dwt_enablegpioclocks()
|
475 |
*
|
476 |
* @brief This is used to senable GPIO clocks. The clocks are needed to ensure correct GPIO operation
|
477 |
*
|
478 |
* input parameters
|
479 |
*
|
480 |
* output parameters
|
481 |
*
|
482 |
* no return value
|
483 |
*/
|
484 |
void dwt_enablegpioclocks(void); |
485 |
|
486 |
/*! ------------------------------------------------------------------------------------------------------------------
|
487 |
* @fn dwt_setgpiodirection()
|
488 |
*
|
489 |
* @brief This is used to set GPIO direction as an input (1) or output (0)
|
490 |
*
|
491 |
* input parameters
|
492 |
* @param gpioNum - this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
|
493 |
* @param direction - this sets the GPIO direction - see GxP0... GxP8 in the deca_regs.h file
|
494 |
*
|
495 |
* output parameters
|
496 |
*
|
497 |
* no return value
|
498 |
*/
|
499 |
void dwt_setgpiodirection(uint32 gpioNum, uint32 direction);
|
500 |
|
501 |
/*! ------------------------------------------------------------------------------------------------------------------
|
502 |
* @fn dwt_setgpiovalue()
|
503 |
*
|
504 |
* @brief This is used to set GPIO value as (1) or (0) only applies if the GPIO is configured as output
|
505 |
*
|
506 |
* input parameters
|
507 |
* @param gpioNum - this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
|
508 |
* @param value - this sets the GPIO value - see GDP0... GDP8 in the deca_regs.h file
|
509 |
*
|
510 |
* output parameters
|
511 |
*
|
512 |
* no return value
|
513 |
*/
|
514 |
void dwt_setgpiovalue(uint32 gpioNum, uint32 value);
|
515 |
|
516 |
/*! ------------------------------------------------------------------------------------------------------------------
|
517 |
* @fn dwt_getgpiovalue()
|
518 |
*
|
519 |
* @brief This is used to get GPIO value, returns (1) or (0) depending if the GPIO is high or low
|
520 |
*
|
521 |
* input parameters
|
522 |
* @param gpioNum - this is the GPIO to configure - see DWT_GxP0... DWT_GxP8
|
523 |
*
|
524 |
* output parameters
|
525 |
*
|
526 |
* return int (1 or 0)
|
527 |
*/
|
528 |
int dwt_getgpiovalue(uint32 gpioNum);
|
529 |
|
530 |
/*! ------------------------------------------------------------------------------------------------------------------
|
531 |
* @fn dwt_initialise()
|
532 |
*
|
533 |
* @brief This function initiates communications with the DW1000 transceiver
|
534 |
* and reads its DEV_ID register (address 0x00) to verify the IC is one supported
|
535 |
* by this software (e.g. DW1000 32-bit device ID value is 0xDECA0130). Then it
|
536 |
* does any initial once only device configurations needed for its use and initialises
|
537 |
* as necessary any static data items belonging to this low-level driver.
|
538 |
*
|
539 |
* This function does not need to be called after DW1000 device is woken up from DEEPSLEEP,
|
540 |
* the device will preserve register values e.g. LDO, UCODE, XTAL. However if needed this
|
541 |
* function can be called to initialise internal structure dw1000local[] if it has not been preserved
|
542 |
* (e.g. if micro was in sleep and its RAM data (containing dw1000local structure was not preserved during sleep)
|
543 |
*
|
544 |
* NOTES:
|
545 |
* 1. When DW1000 is powered on this function needs to be run before dwt_configuresleep,
|
546 |
* also the SPI frequency has to be < 3MHz
|
547 |
* 2. It reads and applies LDO tune and crystal trim values from OTP memory
|
548 |
* 3. If accurate RX timestamping is needed microcode/LDE must be loaded
|
549 |
*
|
550 |
* input parameters
|
551 |
* @param config - specifies what configuration to load
|
552 |
* DWT_LOADNONE 0x00 - do not load any values from OTP memory
|
553 |
* DWT_LOADUCODE 0x01 - load the LDE microcode from ROM - enable accurate RX timestamp
|
554 |
* DWT_DW_WAKE_UP 0x02 - just initialise dw1000local[] values (e.g. DW1000 has woken up)
|
555 |
* DWT_DW_WUP_NO_UCODE 0x04 - if microcode/LDE algorithm has not already been loaded (on power up) e.g. when LDE is not used
|
556 |
* DWT_READ_OTP_PID 0x10 - read part ID from OTP
|
557 |
* DWT_READ_OTP_LID 0x20 - read lot ID from OTP
|
558 |
* DWT_READ_OTP_BAT 0x40 - read ref voltage from OTP
|
559 |
* DWT_READ_OTP_TMP 0x80 - read ref temperature from OTP
|
560 |
* output parameters
|
561 |
*
|
562 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error
|
563 |
*/
|
564 |
int dwt_initialise(int config) ; |
565 |
|
566 |
/*! ------------------------------------------------------------------------------------------------------------------
|
567 |
* @fn dwt_configurefor64plen()
|
568 |
* - Use default OPS table should be used with following register modifications:
|
569 |
* These modifications optimise the default OPS configuration further for 64 length preamble use case
|
570 |
*
|
571 |
* NOTE: These register settings are not preserved during SLEEP/DEEPSLEEP, thus they should be programmed again after wake up
|
572 |
*
|
573 |
* input parameters
|
574 |
* @param prf
|
575 |
*
|
576 |
* output parameters
|
577 |
*
|
578 |
* no return value
|
579 |
*/
|
580 |
void dwt_configurefor64plen(int prf); |
581 |
|
582 |
/*! ------------------------------------------------------------------------------------------------------------------
|
583 |
* @fn dwt_configure()
|
584 |
*
|
585 |
* @brief This function provides the main API for the configuration of the
|
586 |
* DW1000 and this low-level driver. The input is a pointer to the data structure
|
587 |
* of type dwt_config_t that holds all the configurable items.
|
588 |
* The dwt_config_t structure shows which ones are supported
|
589 |
*
|
590 |
* input parameters
|
591 |
* @param config - pointer to the configuration structure, which contains the device configuration data.
|
592 |
*
|
593 |
* output parameters
|
594 |
*
|
595 |
* no return value
|
596 |
*/
|
597 |
void dwt_configure(dwt_config_t *config) ;
|
598 |
|
599 |
/*! ------------------------------------------------------------------------------------------------------------------
|
600 |
* @fn dwt_configuretxrf()
|
601 |
*
|
602 |
* @brief This function provides the API for the configuration of the TX spectrum
|
603 |
* including the power and pulse generator delay. The input is a pointer to the data structure
|
604 |
* of type dwt_txconfig_t that holds all the configurable items.
|
605 |
*
|
606 |
* input parameters
|
607 |
* @param config - pointer to the txrf configuration structure, which contains the tx rf config data
|
608 |
*
|
609 |
* output parameters
|
610 |
*
|
611 |
* no return value
|
612 |
*/
|
613 |
void dwt_configuretxrf(dwt_txconfig_t *config) ;
|
614 |
|
615 |
/*! ------------------------------------------------------------------------------------------------------------------
|
616 |
* @fn dwt_setrxantennadelay()
|
617 |
*
|
618 |
* @brief This API function writes the antenna delay (in time units) to RX registers
|
619 |
*
|
620 |
* input parameters:
|
621 |
* @param rxDelay - this is the total (RX) antenna delay value, which
|
622 |
* will be programmed into the RX register
|
623 |
*
|
624 |
* output parameters
|
625 |
*
|
626 |
* no return value
|
627 |
*/
|
628 |
void dwt_setrxantennadelay(uint16 antennaDly);
|
629 |
|
630 |
/*! ------------------------------------------------------------------------------------------------------------------
|
631 |
* @fn dwt_settxantennadelay()
|
632 |
*
|
633 |
* @brief This API function writes the antenna delay (in time units) to TX registers
|
634 |
*
|
635 |
* input parameters:
|
636 |
* @param txDelay - this is the total (TX) antenna delay value, which
|
637 |
* will be programmed into the TX delay register
|
638 |
*
|
639 |
* output parameters
|
640 |
*
|
641 |
* no return value
|
642 |
*/
|
643 |
void dwt_settxantennadelay(uint16 antennaDly);
|
644 |
|
645 |
/*! ------------------------------------------------------------------------------------------------------------------
|
646 |
* @fn dwt_setsmarttxpower()
|
647 |
*
|
648 |
* @brief This call enables or disables the smart TX power feature.
|
649 |
*
|
650 |
* input parameters
|
651 |
* @param enable - this enables or disables the TX smart power (1 = enable, 0 = disable)
|
652 |
*
|
653 |
* output parameters
|
654 |
*
|
655 |
* no return value
|
656 |
*/
|
657 |
void dwt_setsmarttxpower(int enable); |
658 |
|
659 |
/*! ------------------------------------------------------------------------------------------------------------------
|
660 |
* @fn dwt_writetxdata()
|
661 |
*
|
662 |
* @brief This API function writes the supplied TX data into the DW1000's
|
663 |
* TX buffer. The input parameters are the data length in bytes and a pointer
|
664 |
* to those data bytes.
|
665 |
*
|
666 |
* input parameters
|
667 |
* @param txFrameLength - This is the total frame length, including the two byte CRC.
|
668 |
* Note: this is the length of TX message (including the 2 byte CRC) - max is 1023
|
669 |
* standard PHR mode allows up to 127 bytes
|
670 |
* if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
|
671 |
* see dwt_configure function
|
672 |
* @param txFrameBytes - Pointer to the user?s buffer containing the data to send.
|
673 |
* @param txBufferOffset - This specifies an offset in the DW1000?s TX Buffer at which to start writing data.
|
674 |
*
|
675 |
* output parameters
|
676 |
*
|
677 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error
|
678 |
*/
|
679 |
int dwt_writetxdata(uint16 txFrameLength, uint8 *txFrameBytes, uint16 txBufferOffset) ;
|
680 |
|
681 |
/*! ------------------------------------------------------------------------------------------------------------------
|
682 |
* @fn dwt_writetxfctrl()
|
683 |
*
|
684 |
* @brief This API function configures the TX frame control register before the transmission of a frame
|
685 |
*
|
686 |
* input parameters:
|
687 |
* @param txFrameLength - this is the length of TX message (including the 2 byte CRC) - max is 1023
|
688 |
* NOTE: standard PHR mode allows up to 127 bytes
|
689 |
* if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
|
690 |
* see dwt_configure function
|
691 |
* @param txBufferOffset - the offset in the tx buffer to start writing the data
|
692 |
* @param ranging - 1 if this is a ranging frame, else 0
|
693 |
*
|
694 |
* output parameters
|
695 |
*
|
696 |
* no return value
|
697 |
*/
|
698 |
void dwt_writetxfctrl(uint16 txFrameLength, uint16 txBufferOffset, int ranging); |
699 |
|
700 |
/*! ------------------------------------------------------------------------------------------------------------------
|
701 |
* @fn dwt_starttx()
|
702 |
*
|
703 |
* @brief This call initiates the transmission, input parameter indicates which TX mode is used see below
|
704 |
*
|
705 |
* input parameters:
|
706 |
* @param mode - if mode = DWT_START_TX_IMMEDIATE - immediate TX (no response expected)
|
707 |
* if mode = DWT_START_TX_DELAYED - delayed TX (no response expected)
|
708 |
* if mode = DWT_START_TX_IMMEDIATE | DWT_RESPONSE_EXPECTED - immediate TX (response expected - so the receiver will be automatically turned on after TX is done)
|
709 |
* if mode = DWT_START_TX_DELAYED | DWT_RESPONSE_EXPECTED - delayed TX (response expected - so the receiver will be automatically turned on after TX is done)
|
710 |
*
|
711 |
* output parameters
|
712 |
*
|
713 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error (e.g. a delayed transmission will be cancelled if the delayed time has passed)
|
714 |
*/
|
715 |
int dwt_starttx(uint8 mode) ;
|
716 |
|
717 |
/*! ------------------------------------------------------------------------------------------------------------------
|
718 |
* @fn dwt_setdelayedtrxtime()
|
719 |
*
|
720 |
* @brief This API function configures the delayed transmit time or the delayed RX on time
|
721 |
*
|
722 |
* input parameters
|
723 |
* @param starttime - the TX/RX start time (the 32 bits should be the high 32 bits of the system time at which to send the message,
|
724 |
* or at which to turn on the receiver)
|
725 |
*
|
726 |
* output parameters none
|
727 |
*
|
728 |
* no return value
|
729 |
*/
|
730 |
void dwt_setdelayedtrxtime(uint32 starttime) ;
|
731 |
|
732 |
/*! ------------------------------------------------------------------------------------------------------------------
|
733 |
* @fn dwt_readtxtimestamp()
|
734 |
*
|
735 |
* @brief This is used to read the TX timestamp (adjusted with the programmed antenna delay)
|
736 |
*
|
737 |
* input parameters
|
738 |
* @param timestamp - a pointer to a 5-byte buffer which will store the read TX timestamp time
|
739 |
*
|
740 |
* output parameters - the timestamp buffer will contain the value after the function call
|
741 |
*
|
742 |
* no return value
|
743 |
*/
|
744 |
void dwt_readtxtimestamp(uint8 * timestamp);
|
745 |
|
746 |
/*! ------------------------------------------------------------------------------------------------------------------
|
747 |
* @fn dwt_readtxtimestamphi32()
|
748 |
*
|
749 |
* @brief This is used to read the high 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
|
750 |
*
|
751 |
* input parameters
|
752 |
*
|
753 |
* output parameters
|
754 |
*
|
755 |
* returns high 32-bits of TX timestamp
|
756 |
*/
|
757 |
uint32 dwt_readtxtimestamphi32(void);
|
758 |
|
759 |
/*! ------------------------------------------------------------------------------------------------------------------
|
760 |
* @fn dwt_readtxtimestamplo32()
|
761 |
*
|
762 |
* @brief This is used to read the low 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
|
763 |
*
|
764 |
* input parameters
|
765 |
*
|
766 |
* output parameters
|
767 |
*
|
768 |
* returns low 32-bits of TX timestamp
|
769 |
*/
|
770 |
uint32 dwt_readtxtimestamplo32(void);
|
771 |
|
772 |
/*! ------------------------------------------------------------------------------------------------------------------
|
773 |
* @fn dwt_readrxtimestamp()
|
774 |
*
|
775 |
* @brief This is used to read the RX timestamp (adjusted time of arrival)
|
776 |
*
|
777 |
* input parameters
|
778 |
* @param timestamp - a pointer to a 5-byte buffer which will store the read RX timestamp time
|
779 |
*
|
780 |
* output parameters - the timestamp buffer will contain the value after the function call
|
781 |
*
|
782 |
* no return value
|
783 |
*/
|
784 |
void dwt_readrxtimestamp(uint8 * timestamp);
|
785 |
|
786 |
/*! ------------------------------------------------------------------------------------------------------------------
|
787 |
* @fn dwt_readrxtimestamphi32()
|
788 |
*
|
789 |
* @brief This is used to read the high 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
|
790 |
*
|
791 |
* input parameters
|
792 |
*
|
793 |
* output parameters
|
794 |
*
|
795 |
* returns high 32-bits of RX timestamp
|
796 |
*/
|
797 |
uint32 dwt_readrxtimestamphi32(void);
|
798 |
|
799 |
/*! ------------------------------------------------------------------------------------------------------------------
|
800 |
* @fn dwt_readrxtimestamplo32()
|
801 |
*
|
802 |
* @brief This is used to read the low 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
|
803 |
*
|
804 |
* input parameters
|
805 |
*
|
806 |
* output parameters
|
807 |
*
|
808 |
* returns low 32-bits of RX timestamp
|
809 |
*/
|
810 |
uint32 dwt_readrxtimestamplo32(void);
|
811 |
|
812 |
/*! ------------------------------------------------------------------------------------------------------------------
|
813 |
* @fn dwt_readsystimestamphi32()
|
814 |
*
|
815 |
* @brief This is used to read the high 32-bits of the system time
|
816 |
*
|
817 |
* input parameters
|
818 |
*
|
819 |
* output parameters
|
820 |
*
|
821 |
* returns high 32-bits of system time timestamp
|
822 |
*/
|
823 |
uint32 dwt_readsystimestamphi32(void);
|
824 |
|
825 |
/*! ------------------------------------------------------------------------------------------------------------------
|
826 |
* @fn dwt_readsystime()
|
827 |
*
|
828 |
* @brief This is used to read the system time
|
829 |
*
|
830 |
* input parameters
|
831 |
* @param timestamp - a pointer to a 5-byte buffer which will store the read system time
|
832 |
*
|
833 |
* output parameters
|
834 |
* @param timestamp - the timestamp buffer will contain the value after the function call
|
835 |
*
|
836 |
* no return value
|
837 |
*/
|
838 |
void dwt_readsystime(uint8 * timestamp);
|
839 |
|
840 |
/*! ------------------------------------------------------------------------------------------------------------------
|
841 |
* @fn dwt_forcetrxoff()
|
842 |
*
|
843 |
* @brief This is used to turn off the transceiver
|
844 |
*
|
845 |
* input parameters
|
846 |
*
|
847 |
* output parameters
|
848 |
*
|
849 |
* no return value
|
850 |
*/
|
851 |
void dwt_forcetrxoff(void); |
852 |
|
853 |
/*! ------------------------------------------------------------------------------------------------------------------
|
854 |
* @fn dwt_syncrxbufptrs()
|
855 |
*
|
856 |
* @brief this function synchronizes rx buffer pointers
|
857 |
* need to make sure that the host/IC buffer pointers are aligned before starting RX
|
858 |
*
|
859 |
* input parameters:
|
860 |
*
|
861 |
* output parameters
|
862 |
*
|
863 |
* no return value
|
864 |
*/
|
865 |
void dwt_syncrxbufptrs(void); |
866 |
|
867 |
/*! ------------------------------------------------------------------------------------------------------------------
|
868 |
* @fn dwt_rxenable()
|
869 |
*
|
870 |
* @brief This call turns on the receiver, can be immediate or delayed (depending on the mode parameter). In the case of a
|
871 |
* "late" error the receiver will only be turned on if the DWT_IDLE_ON_DLY_ERR is not set.
|
872 |
* The receiver will stay turned on, listening to any messages until
|
873 |
* it either receives a good frame, an error (CRC, PHY header, Reed Solomon) or it times out (SFD, Preamble or Frame).
|
874 |
*
|
875 |
* input parameters
|
876 |
* @param mode - this can be one of the following allowed values:
|
877 |
*
|
878 |
* DWT_START_RX_IMMEDIATE 0 used to enbale receiver immediately
|
879 |
* DWT_START_RX_DELAYED 1 used to set up delayed RX, if "late" error triggers, then the RX will be enabled immediately
|
880 |
* (DWT_START_RX_DELAYED | DWT_IDLE_ON_DLY_ERR) 3 used to disable re-enabling of receiver if delayed RX failed due to "late" error
|
881 |
* (DWT_START_RX_IMMEDIATE | DWT_NO_SYNC_PTRS) 4 used to re-enable RX without trying to sync IC and host side buffer pointers, typically when
|
882 |
* performing manual RX re-enabling in double buffering mode
|
883 |
*
|
884 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error (e.g. a delayed receive enable will be too far in the future if delayed time has passed)
|
885 |
*/
|
886 |
int dwt_rxenable(int mode); |
887 |
|
888 |
/*! ------------------------------------------------------------------------------------------------------------------
|
889 |
* @fn dwt_setsniffmode()
|
890 |
*
|
891 |
* @brief enable/disable and configure SNIFF mode.
|
892 |
*
|
893 |
* SNIFF mode is a low-power reception mode where the receiver is sequenced on and off instead of being on all the time.
|
894 |
* The time spent in each state (on/off) is specified through the parameters below.
|
895 |
* See DW1000 User Manual section 4.5 "Low-Power SNIFF mode" for more details.
|
896 |
*
|
897 |
* input parameters:
|
898 |
* @param enable - 1 to enable SNIFF mode, 0 to disable. When 0, all other parameters are not taken into account.
|
899 |
* @param timeOn - duration of receiver ON phase, expressed in multiples of PAC size. The counter automatically adds 1 PAC
|
900 |
* size to the value set. Min value that can be set is 1 (i.e. an ON time of 2 PAC size), max value is 15.
|
901 |
* @param timeOff - duration of receiver OFF phase, expressed in multiples of 128/125 ?s (~1 ?s). Max value is 255.
|
902 |
*
|
903 |
* output parameters
|
904 |
*
|
905 |
* no return value
|
906 |
*/
|
907 |
void dwt_setsniffmode(int enable, uint8 timeOn, uint8 timeOff); |
908 |
|
909 |
/*! ------------------------------------------------------------------------------------------------------------------
|
910 |
* @fn dwt_setlowpowerlistening()
|
911 |
*
|
912 |
* @brief enable/disable low-power listening mode.
|
913 |
*
|
914 |
* Low-power listening is a feature whereby the DW1000 is predominantly in the SLEEP state but wakes periodically, (after
|
915 |
* this "long sleep"), for a very short time to sample the air for a preamble sequence. This preamble sampling "listening"
|
916 |
* phase is actually two reception phases separated by a "short sleep" time. See DW1000 User Manual section "Low-Power
|
917 |
* Listening" for more details.
|
918 |
*
|
919 |
* NOTE: Before enabling low-power listening, the following functions have to be called to fully configure it:
|
920 |
* - dwt_configuresleep() to configure long sleep phase. "mode" parameter should at least have DWT_PRESRV_SLEEP,
|
921 |
* DWT_CONFIG and DWT_RX_EN set and "wake" parameter should at least have both DWT_WAKE_SLPCNT and DWT_SLP_EN set.
|
922 |
* - dwt_calibratesleepcnt() and dwt_configuresleepcnt() to define the "long sleep" phase duration.
|
923 |
* - dwt_setsnoozetime() to define the "short sleep" phase duration.
|
924 |
* - dwt_setpreambledetecttimeout() to define the reception phases duration.
|
925 |
* - dwt_setinterrupt() to activate RX good frame interrupt (DWT_INT_RFCG) only.
|
926 |
* When configured, low-power listening mode can be triggered either by putting the DW1000 to sleep (using
|
927 |
* dwt_entersleep()) or by activating reception (using dwt_rxenable()).
|
928 |
*
|
929 |
* Please refer to the low-power listening examples (examples 8a/8b accompanying the API distribution on Decawave's
|
930 |
* website). They form a working example code that shows how to use low-power listening correctly.
|
931 |
*
|
932 |
* input parameters:
|
933 |
* @param enable - 1 to enable low-power listening, 0 to disable.
|
934 |
*
|
935 |
* output parameters
|
936 |
*
|
937 |
* no return value
|
938 |
*/
|
939 |
void dwt_setlowpowerlistening(int enable); |
940 |
|
941 |
/*! ------------------------------------------------------------------------------------------------------------------
|
942 |
* @fn dwt_setsnoozetime()
|
943 |
*
|
944 |
* @brief Set duration of "short sleep" phase when in low-power listening mode.
|
945 |
*
|
946 |
* input parameters:
|
947 |
* @param snooze_time - "short sleep" phase duration, expressed in multiples of 512/19.2 ?s (~26.7 ?s). The counter
|
948 |
* automatically adds 1 to the value set. The smallest working value that should be set is 1,
|
949 |
* i.e. giving a snooze time of 2 units (or ~53 ?s).
|
950 |
*
|
951 |
* output parameters
|
952 |
*
|
953 |
* no return value
|
954 |
*/
|
955 |
void dwt_setsnoozetime(uint8 snooze_time);
|
956 |
|
957 |
/*! ------------------------------------------------------------------------------------------------------------------
|
958 |
* @fn dwt_setdblrxbuffmode()
|
959 |
*
|
960 |
* @brief This call enables the double receive buffer mode
|
961 |
*
|
962 |
* input parameters
|
963 |
* @param enable - 1 to enable, 0 to disable the double buffer mode
|
964 |
*
|
965 |
* output parameters
|
966 |
*
|
967 |
* no return value
|
968 |
*/
|
969 |
void dwt_setdblrxbuffmode(int enable); |
970 |
|
971 |
/*! ------------------------------------------------------------------------------------------------------------------
|
972 |
* @fn dwt_setrxtimeout()
|
973 |
*
|
974 |
* @brief This call enables RX timeout (SY_STAT_RFTO event)
|
975 |
*
|
976 |
* input parameters
|
977 |
* @param time - how long the receiver remains on from the RX enable command
|
978 |
* The time parameter used here is in 1.0256 us (512/499.2MHz) units
|
979 |
* If set to 0 the timeout is disabled.
|
980 |
*
|
981 |
* output parameters
|
982 |
*
|
983 |
* no return value
|
984 |
*/
|
985 |
void dwt_setrxtimeout(uint16 time);
|
986 |
|
987 |
/*! ------------------------------------------------------------------------------------------------------------------
|
988 |
* @fn dwt_setpreambledetecttimeout()
|
989 |
*
|
990 |
* @brief This call enables preamble timeout (SY_STAT_RXPTO event)
|
991 |
*
|
992 |
* input parameters
|
993 |
* @param timeout - Preamble detection timeout, expressed in multiples of PAC size. The counter automatically adds 1 PAC
|
994 |
* size to the value set. Min value that can be set is 1 (i.e. a timeout of 2 PAC size).
|
995 |
*
|
996 |
* Note: value of 0 disables the preamble timeout
|
997 |
* output parameters
|
998 |
*
|
999 |
* no return value
|
1000 |
*/
|
1001 |
void dwt_setpreambledetecttimeout(uint16 timeout);
|
1002 |
|
1003 |
|
1004 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1005 |
* @fn dwt_calibratesleepcnt()
|
1006 |
*
|
1007 |
* @brief calibrates the local oscillator as its frequency can vary between 7 and 13kHz depending on temp and voltage
|
1008 |
*
|
1009 |
* NOTE: this function needs to be run before dwt_configuresleepcnt, so that we know what the counter units are
|
1010 |
*
|
1011 |
* input parameters
|
1012 |
*
|
1013 |
* output parameters
|
1014 |
*
|
1015 |
* returns the number of XTAL/2 cycles per low-power oscillator cycle. LP OSC frequency = 19.2 MHz/return value
|
1016 |
*/
|
1017 |
uint16 dwt_calibratesleepcnt(void);
|
1018 |
|
1019 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1020 |
* @fn dwt_configuresleepcnt()
|
1021 |
*
|
1022 |
* @brief sets the sleep counter to new value, this function programs the high 16-bits of the 28-bit counter
|
1023 |
*
|
1024 |
* NOTE: this function needs to be run before dwt_configuresleep, also the SPI frequency has to be < 3MHz
|
1025 |
*
|
1026 |
* input parameters
|
1027 |
* @param sleepcnt - this it value of the sleep counter to program
|
1028 |
*
|
1029 |
* output parameters
|
1030 |
*
|
1031 |
* no return value
|
1032 |
*/
|
1033 |
void dwt_configuresleepcnt(uint16 sleepcnt);
|
1034 |
|
1035 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1036 |
* @fn dwt_configuresleep()
|
1037 |
*
|
1038 |
* @brief configures the device for both DEEP_SLEEP and SLEEP modes, and on-wake mode
|
1039 |
* i.e. before entering the sleep, the device should be programmed for TX or RX, then upon "waking up" the TX/RX settings
|
1040 |
* will be preserved and the device can immediately perform the desired action TX/RX
|
1041 |
*
|
1042 |
* NOTE: e.g. Tag operation - after deep sleep, the device needs to just load the TX buffer and send the frame
|
1043 |
*
|
1044 |
*
|
1045 |
* mode: the array and LDE code (OTP/ROM) and LDO tune, and set sleep persist
|
1046 |
* DWT_PRESRV_SLEEP 0x0100 - preserve sleep
|
1047 |
* DWT_LOADOPSET 0x0080 - load operating parameter set on wakeup
|
1048 |
* DWT_CONFIG 0x0040 - download the AON array into the HIF (configuration download)
|
1049 |
* DWT_LOADEUI 0x0008
|
1050 |
* DWT_GOTORX 0x0002
|
1051 |
* DWT_TANDV 0x0001
|
1052 |
*
|
1053 |
* wake: wake up parameters
|
1054 |
* DWT_XTAL_EN 0x10 - keep XTAL running during sleep
|
1055 |
* DWT_WAKE_SLPCNT 0x8 - wake up after sleep count
|
1056 |
* DWT_WAKE_CS 0x4 - wake up on chip select
|
1057 |
* DWT_WAKE_WK 0x2 - wake up on WAKEUP PIN
|
1058 |
* DWT_SLP_EN 0x1 - enable sleep/deep sleep functionality
|
1059 |
*
|
1060 |
* input parameters
|
1061 |
* @param mode - config on-wake parameters
|
1062 |
* @param wake - config wake up parameters
|
1063 |
*
|
1064 |
* output parameters
|
1065 |
*
|
1066 |
* no return value
|
1067 |
*/
|
1068 |
void dwt_configuresleep(uint16 mode, uint8 wake);
|
1069 |
|
1070 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1071 |
* @fn dwt_entersleep()
|
1072 |
*
|
1073 |
* @brief This function puts the device into deep sleep or sleep. dwt_configuresleep() should be called first
|
1074 |
* to configure the sleep and on-wake/wake-up parameters
|
1075 |
*
|
1076 |
* input parameters
|
1077 |
*
|
1078 |
* output parameters
|
1079 |
*
|
1080 |
* no return value
|
1081 |
*/
|
1082 |
void dwt_entersleep(void); |
1083 |
|
1084 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1085 |
* @fn dwt_entersleepaftertx(int enable)
|
1086 |
*
|
1087 |
* @brief sets the auto TX to sleep bit. This means that after a frame
|
1088 |
* transmission the device will enter deep sleep mode. The dwt_configuresleep() function
|
1089 |
* needs to be called before this to configure the on-wake settings
|
1090 |
*
|
1091 |
* NOTE: the IRQ line has to be low/inactive (i.e. no pending events)
|
1092 |
*
|
1093 |
* input parameters
|
1094 |
* @param enable - 1 to configure the device to enter deep sleep after TX, 0 - disables the configuration
|
1095 |
*
|
1096 |
* output parameters
|
1097 |
*
|
1098 |
* no return value
|
1099 |
*/
|
1100 |
void dwt_entersleepaftertx(int enable); |
1101 |
|
1102 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1103 |
* @fn dwt_spicswakeup()
|
1104 |
*
|
1105 |
* @brief wake up the device from sleep mode using the SPI read,
|
1106 |
* the device will wake up on chip select line going low if the line is held low for at least 500us.
|
1107 |
* To define the length depending on the time one wants to hold
|
1108 |
* the chip select line low, use the following formula:
|
1109 |
*
|
1110 |
* length (bytes) = time (s) * byte_rate (Hz)
|
1111 |
*
|
1112 |
* where fastest byte_rate is spi_rate (Hz) / 8 if the SPI is sending the bytes back-to-back.
|
1113 |
* To save time and power, a system designer could determine byte_rate value more precisely.
|
1114 |
*
|
1115 |
* NOTE: Alternatively the device can be waken up with WAKE_UP pin if configured for that operation
|
1116 |
*
|
1117 |
* input parameters
|
1118 |
* @param buff - this is a pointer to the dummy buffer which will be used in the SPI read transaction used for the WAKE UP of the device
|
1119 |
* @param length - this is the length of the dummy buffer
|
1120 |
*
|
1121 |
* output parameters
|
1122 |
*
|
1123 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error
|
1124 |
*/
|
1125 |
int dwt_spicswakeup(uint8 *buff, uint16 length);
|
1126 |
|
1127 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1128 |
* @fn dwt_setcallbacks()
|
1129 |
*
|
1130 |
* @brief This function is used to register the different callbacks called when one of the corresponding event occurs.
|
1131 |
*
|
1132 |
* NOTE: Callbacks can be undefined (set to NULL). In this case, dwt_isr() will process the event as usual but the 'null'
|
1133 |
* callback will not be called.
|
1134 |
*
|
1135 |
* input parameters
|
1136 |
* @param cbTxDone - the pointer to the TX confirmation event callback function
|
1137 |
* @param cbRxOk - the pointer to the RX good frame event callback function
|
1138 |
* @param cbRxTo - the pointer to the RX timeout events callback function
|
1139 |
* @param cbRxErr - the pointer to the RX error events callback function
|
1140 |
*
|
1141 |
* output parameters
|
1142 |
*
|
1143 |
* no return value
|
1144 |
*/
|
1145 |
void dwt_setcallbacks(dwt_cb_t cbTxDone, dwt_cb_t cbRxOk, dwt_cb_t cbRxTo, dwt_cb_t cbRxErr);
|
1146 |
|
1147 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1148 |
* @fn dwt_checkirq()
|
1149 |
*
|
1150 |
* @brief This function checks if the IRQ line is active - this is used instead of interrupt handler
|
1151 |
*
|
1152 |
* input parameters
|
1153 |
*
|
1154 |
* output parameters
|
1155 |
*
|
1156 |
* return value is 1 if the IRQS bit is set and 0 otherwise
|
1157 |
*/
|
1158 |
uint8 dwt_checkirq(void);
|
1159 |
|
1160 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1161 |
* @fn dwt_isr()
|
1162 |
*
|
1163 |
* @brief This is the DW1000's general Interrupt Service Routine. It will process/report the following events:
|
1164 |
* - RXFCG (through cbRxOk callback)
|
1165 |
* - TXFRS (through cbTxDone callback)
|
1166 |
* - RXRFTO/RXPTO (through cbRxTo callback)
|
1167 |
* - RXPHE/RXFCE/RXRFSL/RXSFDTO/AFFREJ/LDEERR (through cbRxTo cbRxErr)
|
1168 |
* For all events, corresponding interrupts are cleared and necessary resets are performed. In addition, in the RXFCG case,
|
1169 |
* received frame information and frame control are read before calling the callback. If double buffering is activated, it
|
1170 |
* will also toggle between reception buffers once the reception callback processing has ended.
|
1171 |
*
|
1172 |
* /!\ This version of the ISR supports double buffering but does not support automatic RX re-enabling!
|
1173 |
*
|
1174 |
* NOTE: In PC based system using (Cheetah or ARM) USB to SPI converter there can be no interrupts, however we still need something
|
1175 |
* to take the place of it and operate in a polled way. In an embedded system this function should be configured to be triggered
|
1176 |
* on any of the interrupts described above.
|
1177 |
|
1178 |
* input parameters
|
1179 |
*
|
1180 |
* output parameters
|
1181 |
*
|
1182 |
* no return value
|
1183 |
*/
|
1184 |
void dwt_isr(void); |
1185 |
|
1186 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1187 |
* @fn dwt_isr_lplisten()
|
1188 |
*
|
1189 |
* @brief This is the DW1000's Interrupt Service Routine to use when low-power listening scheme is implemented. It will
|
1190 |
* only process/report the RXFCG event (through cbRxOk callback).
|
1191 |
* It clears RXFCG interrupt and reads received frame information and frame control before calling the callback.
|
1192 |
*
|
1193 |
* /!\ This version of the ISR is designed for single buffering case only!
|
1194 |
*
|
1195 |
* input parameters
|
1196 |
*
|
1197 |
* output parameters
|
1198 |
*
|
1199 |
* no return value
|
1200 |
*/
|
1201 |
void dwt_lowpowerlistenisr(void); |
1202 |
|
1203 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1204 |
* @fn void dwt_setinterrupt()
|
1205 |
*
|
1206 |
* @brief This function enables the specified events to trigger an interrupt.
|
1207 |
* The following events can be enabled:
|
1208 |
* DWT_INT_TFRS 0x00000080 // frame sent
|
1209 |
* DWT_INT_RFCG 0x00004000 // frame received with good CRC
|
1210 |
* DWT_INT_RPHE 0x00001000 // receiver PHY header error
|
1211 |
* DWT_INT_RFCE 0x00008000 // receiver CRC error
|
1212 |
* DWT_INT_RFSL 0x00010000 // receiver sync loss error
|
1213 |
* DWT_INT_RFTO 0x00020000 // frame wait timeout
|
1214 |
* DWT_INT_RXPTO 0x00200000 // preamble detect timeout
|
1215 |
* DWT_INT_SFDT 0x04000000 // SFD timeout
|
1216 |
* DWT_INT_ARFE 0x20000000 // frame rejected (due to frame filtering configuration)
|
1217 |
*
|
1218 |
*
|
1219 |
* input parameters:
|
1220 |
* @param bitmask - sets the events which will generate interrupt
|
1221 |
* @param operation - if set to 1 the interrupts (only the ones selected in the bitmask) are enabled else they are cleared
|
1222 |
* - if set to 2 the interrupts in the bitmask are forced to selected state - i.e. the mask is written to the register directly.
|
1223 |
*
|
1224 |
* output parameters
|
1225 |
*
|
1226 |
* no return value
|
1227 |
*/
|
1228 |
void dwt_setinterrupt(uint32 bitmask, uint8 operation);
|
1229 |
|
1230 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1231 |
* @fn dwt_setpanid()
|
1232 |
*
|
1233 |
* @brief This is used to set the PAN ID
|
1234 |
*
|
1235 |
* input parameters
|
1236 |
* @param panID - this is the PAN ID
|
1237 |
*
|
1238 |
* output parameters
|
1239 |
*
|
1240 |
* no return value
|
1241 |
*/
|
1242 |
void dwt_setpanid(uint16 panID);
|
1243 |
|
1244 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1245 |
* @fn dwt_setaddress16()
|
1246 |
*
|
1247 |
* @brief This is used to set 16-bit (short) address
|
1248 |
*
|
1249 |
* input parameters
|
1250 |
* @param shortAddress - this sets the 16 bit short address
|
1251 |
*
|
1252 |
* output parameters
|
1253 |
*
|
1254 |
* no return value
|
1255 |
*/
|
1256 |
void dwt_setaddress16(uint16 shortAddress);
|
1257 |
|
1258 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1259 |
* @fn dwt_seteui()
|
1260 |
*
|
1261 |
* @brief This is used to set the EUI 64-bit (long) address
|
1262 |
*
|
1263 |
* input parameters
|
1264 |
* @param eui64 - this is the pointer to a buffer that contains the 64bit address
|
1265 |
*
|
1266 |
* output parameters
|
1267 |
*
|
1268 |
* no return value
|
1269 |
*/
|
1270 |
void dwt_seteui(uint8 *eui64);
|
1271 |
|
1272 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1273 |
* @fn dwt_geteui()
|
1274 |
*
|
1275 |
* @brief This is used to get the EUI 64-bit from the DW1000
|
1276 |
*
|
1277 |
* input parameters
|
1278 |
* @param eui64 - this is the pointer to a buffer that will contain the read 64-bit EUI value
|
1279 |
*
|
1280 |
* output parameters
|
1281 |
*
|
1282 |
* no return value
|
1283 |
*/
|
1284 |
void dwt_geteui(uint8 *eui64);
|
1285 |
|
1286 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1287 |
* @fn dwt_otpread()
|
1288 |
*
|
1289 |
* @brief This is used to read the OTP data from given address into provided array
|
1290 |
*
|
1291 |
* input parameters
|
1292 |
* @param address - this is the OTP address to read from
|
1293 |
* @param array - this is the pointer to the array into which to read the data
|
1294 |
* @param length - this is the number of 32 bit words to read (array needs to be at least this length)
|
1295 |
*
|
1296 |
* output parameters
|
1297 |
*
|
1298 |
* no return value
|
1299 |
*/
|
1300 |
void dwt_otpread(uint16 address, uint32 *array, uint8 length);
|
1301 |
|
1302 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1303 |
* @fn dwt_enableframefilter()
|
1304 |
*
|
1305 |
* @brief This is used to enable the frame filtering - (the default option is to
|
1306 |
* accept any data and ACK frames with correct destination address
|
1307 |
*
|
1308 |
* input parameters
|
1309 |
* @param - bitmask - enables/disables the frame filtering options according to
|
1310 |
* DWT_FF_NOTYPE_EN 0x000 no frame types allowed
|
1311 |
* DWT_FF_COORD_EN 0x002 behave as coordinator (can receive frames with no destination address (PAN ID has to match))
|
1312 |
* DWT_FF_BEACON_EN 0x004 beacon frames allowed
|
1313 |
* DWT_FF_DATA_EN 0x008 data frames allowed
|
1314 |
* DWT_FF_ACK_EN 0x010 ack frames allowed
|
1315 |
* DWT_FF_MAC_EN 0x020 mac control frames allowed
|
1316 |
* DWT_FF_RSVD_EN 0x040 reserved frame types allowed
|
1317 |
*
|
1318 |
* output parameters
|
1319 |
*
|
1320 |
* no return value
|
1321 |
*/
|
1322 |
void dwt_enableframefilter(uint16 bitmask);
|
1323 |
|
1324 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1325 |
* @fn dwt_enableautoack()
|
1326 |
*
|
1327 |
* @brief This call enables the auto-ACK feature. If the responseDelayTime (parameter) is 0, the ACK will be sent a.s.a.p.
|
1328 |
* otherwise it will be sent with a programmed delay (in symbols), max is 255.
|
1329 |
* NOTE: needs to have frame filtering enabled as well
|
1330 |
*
|
1331 |
* input parameters
|
1332 |
* @param responseDelayTime - if non-zero the ACK is sent after this delay, max is 255.
|
1333 |
*
|
1334 |
* output parameters
|
1335 |
*
|
1336 |
* no return value
|
1337 |
*/
|
1338 |
void dwt_enableautoack(uint8 responseDelayTime);
|
1339 |
|
1340 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1341 |
* @fn dwt_setrxaftertxdelay()
|
1342 |
*
|
1343 |
* @brief This sets the receiver turn on delay time after a transmission of a frame
|
1344 |
*
|
1345 |
* input parameters
|
1346 |
* @param rxDelayTime - (20 bits) - the delay is in UWB microseconds
|
1347 |
*
|
1348 |
* output parameters
|
1349 |
*
|
1350 |
* no return value
|
1351 |
*/
|
1352 |
void dwt_setrxaftertxdelay(uint32 rxDelayTime);
|
1353 |
|
1354 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1355 |
* @fn dwt_rxreset()
|
1356 |
*
|
1357 |
* @brief this function resets the receiver of the DW1000
|
1358 |
*
|
1359 |
* input parameters:
|
1360 |
*
|
1361 |
* output parameters
|
1362 |
*
|
1363 |
* no return value
|
1364 |
*/
|
1365 |
void dwt_rxreset(void); |
1366 |
|
1367 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1368 |
* @fn dwt_softreset()
|
1369 |
*
|
1370 |
* @brief this function resets the DW1000
|
1371 |
*
|
1372 |
* input parameters:
|
1373 |
*
|
1374 |
* output parameters
|
1375 |
*
|
1376 |
* no return value
|
1377 |
*/
|
1378 |
void dwt_softreset(void) ; |
1379 |
|
1380 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1381 |
* @fn dwt_readrxdata()
|
1382 |
*
|
1383 |
* @brief This is used to read the data from the RX buffer, from an offset location give by offset parameter
|
1384 |
*
|
1385 |
* input parameters
|
1386 |
* @param buffer - the buffer into which the data will be read
|
1387 |
* @param length - the length of data to read (in bytes)
|
1388 |
* @param rxBufferOffset - the offset in the rx buffer from which to read the data
|
1389 |
*
|
1390 |
* output parameters
|
1391 |
*
|
1392 |
* no return value
|
1393 |
*/
|
1394 |
void dwt_readrxdata(uint8 *buffer, uint16 length, uint16 rxBufferOffset);
|
1395 |
|
1396 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1397 |
* @fn dwt_readaccdata()
|
1398 |
*
|
1399 |
* @brief This is used to read the data from the Accumulator buffer, from an offset location give by offset parameter
|
1400 |
*
|
1401 |
* NOTE: Because of an internal memory access delay when reading the accumulator the first octet output is a dummy octet
|
1402 |
* that should be discarded. This is true no matter what sub-index the read begins at.
|
1403 |
*
|
1404 |
* input parameters
|
1405 |
* @param buffer - the buffer into which the data will be read
|
1406 |
* @param length - the length of data to read (in bytes)
|
1407 |
* @param accOffset - the offset in the acc buffer from which to read the data
|
1408 |
*
|
1409 |
* output parameters
|
1410 |
*
|
1411 |
* no return value
|
1412 |
*/
|
1413 |
void dwt_readaccdata(uint8 *buffer, uint16 length, uint16 rxBufferOffset);
|
1414 |
|
1415 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1416 |
* @fn dwt_readcarrierintegrator()
|
1417 |
*
|
1418 |
* @brief This is used to read the RX carrier integrator value (relating to the frequency offset of the TX node)
|
1419 |
*
|
1420 |
* input parameters - NONE
|
1421 |
*
|
1422 |
* return value - the (int32) signed carrier integrator value.
|
1423 |
* A positive value means the local RX clock is running faster than the remote TX device.
|
1424 |
*/
|
1425 |
|
1426 |
int32 dwt_readcarrierintegrator(void) ;
|
1427 |
|
1428 |
// Multiplication factors to convert carrier integrator value to a frequency offset in Hertz
|
1429 |
|
1430 |
#define FREQ_OFFSET_MULTIPLIER (998.4e6/2.0/1024.0/131072.0) |
1431 |
#define FREQ_OFFSET_MULTIPLIER_110KB (998.4e6/2.0/8192.0/131072.0) |
1432 |
|
1433 |
// Multiplication factors to convert frequency offset in Hertz to PPM crystal offset
|
1434 |
// NB: also changes sign so a positive value means the local RX clock is running slower than the remote TX device.
|
1435 |
|
1436 |
#define HERTZ_TO_PPM_MULTIPLIER_CHAN_1 (-1.0e6/3494.4e6) |
1437 |
#define HERTZ_TO_PPM_MULTIPLIER_CHAN_2 (-1.0e6/3993.6e6) |
1438 |
#define HERTZ_TO_PPM_MULTIPLIER_CHAN_3 (-1.0e6/4492.8e6) |
1439 |
#define HERTZ_TO_PPM_MULTIPLIER_CHAN_5 (-1.0e6/6489.6e6) |
1440 |
|
1441 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1442 |
* @fn dwt_readdiagnostics()
|
1443 |
*
|
1444 |
* @brief this function reads the RX signal quality diagnostic data
|
1445 |
*
|
1446 |
* input parameters
|
1447 |
* @param diagnostics - diagnostic structure pointer, this will contain the diagnostic data read from the DW1000
|
1448 |
*
|
1449 |
* output parameters
|
1450 |
*
|
1451 |
* no return value
|
1452 |
*/
|
1453 |
void dwt_readdiagnostics(dwt_rxdiag_t * diagnostics);
|
1454 |
|
1455 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1456 |
* @fn dwt_loadopsettabfromotp()
|
1457 |
*
|
1458 |
* @brief This is used to select which Operational Parameter Set table to load from OTP memory
|
1459 |
*
|
1460 |
* input parameters
|
1461 |
* @param ops_sel - Operational Parameter Set table to load:
|
1462 |
* DWT_OPSET_64LEN = 0x0 - load the operational parameter set table for 64 length preamble configuration
|
1463 |
* DWT_OPSET_TIGHT = 0x1 - load the operational parameter set table for tight xtal offsets (<1ppm)
|
1464 |
* DWT_OPSET_DEFLT = 0x2 - load the default operational parameter set table (this is loaded from reset)
|
1465 |
*
|
1466 |
* output parameters
|
1467 |
*
|
1468 |
* no return value
|
1469 |
*/
|
1470 |
void dwt_loadopsettabfromotp(uint8 ops_sel);
|
1471 |
|
1472 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1473 |
* @fn dwt_configeventcounters()
|
1474 |
*
|
1475 |
* @brief This is used to enable/disable the event counter in the IC
|
1476 |
*
|
1477 |
* input parameters
|
1478 |
* @param - enable - 1 enables (and reset), 0 disables the event counters
|
1479 |
* output parameters
|
1480 |
*
|
1481 |
* no return value
|
1482 |
*/
|
1483 |
void dwt_configeventcounters(int enable); |
1484 |
|
1485 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1486 |
* @fn dwt_readeventcounters()
|
1487 |
*
|
1488 |
* @brief This is used to read the event counters in the IC
|
1489 |
*
|
1490 |
* input parameters
|
1491 |
* @param counters - pointer to the dwt_deviceentcnts_t structure which will hold the read data
|
1492 |
*
|
1493 |
* output parameters
|
1494 |
*
|
1495 |
* no return value
|
1496 |
*/
|
1497 |
void dwt_readeventcounters(dwt_deviceentcnts_t *counters);
|
1498 |
|
1499 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1500 |
* @fn dwt_otpwriteandverify()
|
1501 |
*
|
1502 |
* @brief This is used to program 32-bit value into the DW1000 OTP memory.
|
1503 |
*
|
1504 |
* input parameters
|
1505 |
* @param value - this is the 32-bit value to be programmed into OTP
|
1506 |
* @param address - this is the 16-bit OTP address into which the 32-bit value is programmed
|
1507 |
*
|
1508 |
* output parameters
|
1509 |
*
|
1510 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error
|
1511 |
*/
|
1512 |
int dwt_otpwriteandverify(uint32 value, uint16 address);
|
1513 |
|
1514 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1515 |
* @fn dwt_setleds()
|
1516 |
*
|
1517 |
* @brief This is used to set up Tx/Rx GPIOs which could be used to control LEDs
|
1518 |
* Note: not completely IC dependent, also needs board with LEDS fitted on right I/O lines
|
1519 |
* this function enables GPIOs 2 and 3 which are connected to LED3 and LED4 on EVB1000
|
1520 |
*
|
1521 |
* input parameters
|
1522 |
* @param mode - this is a bit field interpreted as follows:
|
1523 |
* - bit 0: 1 to enable LEDs, 0 to disable them
|
1524 |
* - bit 1: 1 to make LEDs blink once on init. Only valid if bit 0 is set (enable LEDs)
|
1525 |
* - bit 2 to 7: reserved
|
1526 |
*
|
1527 |
* output parameters none
|
1528 |
*
|
1529 |
* no return value
|
1530 |
*/
|
1531 |
void dwt_setleds(uint8 mode);
|
1532 |
|
1533 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1534 |
* @fn dwt_setxtaltrim()
|
1535 |
*
|
1536 |
* @brief This is used to adjust the crystal frequency
|
1537 |
*
|
1538 |
* input parameters:
|
1539 |
* @param value - crystal trim value (in range 0x0 to 0x1F) 31 steps (~1.5ppm per step)
|
1540 |
*
|
1541 |
* output parameters
|
1542 |
*
|
1543 |
* no return value
|
1544 |
*/
|
1545 |
void dwt_setxtaltrim(uint8 value);
|
1546 |
|
1547 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1548 |
* @fn dwt_getxtaltrim()
|
1549 |
*
|
1550 |
* @brief This function returns current value of XTAL trim. If this is called after dwt_initalise it will return the OTP value
|
1551 |
* if OTP value is non-zero or FS_XTALT_MIDRANGE if OTP value is zero (not programmed).
|
1552 |
*
|
1553 |
* input parameters
|
1554 |
*
|
1555 |
* output parameters
|
1556 |
*
|
1557 |
* returns the current XTAL trim value
|
1558 |
*/
|
1559 |
uint8 dwt_getxtaltrim(void);
|
1560 |
|
1561 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1562 |
* @fn dwt_configcwmode()
|
1563 |
*
|
1564 |
* @brief this function sets the DW1000 to transmit cw signal at specific channel frequency
|
1565 |
*
|
1566 |
* input parameters:
|
1567 |
* @param chan - specifies the operating channel (e.g. 1, 2, 3, 4, 5, 6 or 7)
|
1568 |
*
|
1569 |
* output parameters
|
1570 |
*
|
1571 |
* no return value
|
1572 |
*/
|
1573 |
void dwt_configcwmode(uint8 chan);
|
1574 |
|
1575 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1576 |
* @fn dwt_configcontinuousframemode()
|
1577 |
*
|
1578 |
* @brief this function sets the DW1000 to continuous tx frame mode for regulatory approvals testing.
|
1579 |
*
|
1580 |
* input parameters:
|
1581 |
* @param framerepetitionrate - This is a 32-bit value that is used to set the interval between transmissions.
|
1582 |
* The minimum value is 4. The units are approximately 8 ns. (or more precisely 512/(499.2e6*128) seconds)).
|
1583 |
*
|
1584 |
* output parameters
|
1585 |
*
|
1586 |
* no return value
|
1587 |
*/
|
1588 |
void dwt_configcontinuousframemode(uint32 framerepetitionrate);
|
1589 |
|
1590 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1591 |
* @fn dwt_readtempvbat()
|
1592 |
*
|
1593 |
* @brief this function reads the raw battery voltage and temperature values of the DW IC
|
1594 |
* The values read here will be the current values sampled by DW IC AtoD converters.
|
1595 |
*
|
1596 |
* NB: To correctly read the temperature this read should be done with xtal clock
|
1597 |
* however that means that the receiver will be switched off, if receiver needs to be on then
|
1598 |
* the timer is used to make sure the value is stable before reading
|
1599 |
*
|
1600 |
* input parameters:
|
1601 |
* @param fastSPI - set to 1 if SPI rate > than 3MHz is used
|
1602 |
*
|
1603 |
* output parameters
|
1604 |
*
|
1605 |
* returns (temp_raw<<8)|(vbat_raw)
|
1606 |
*/
|
1607 |
uint16 dwt_readtempvbat(uint8 fastSPI); |
1608 |
|
1609 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1610 |
* @fn dwt_convertrawtemperature()
|
1611 |
*
|
1612 |
* @brief this function takes in a raw temperature value and applies the conversion factor
|
1613 |
* to give true temperature. The dwt_initialise needs to be called before call to this to
|
1614 |
* ensure pdw1000local->tempP contains the SAR_LTEMP value from OTP.
|
1615 |
*
|
1616 |
* input parameters:
|
1617 |
* @param raw_temp - this is the 8-bit raw temperature value as read by dwt_readtempvbat
|
1618 |
*
|
1619 |
* output parameters:
|
1620 |
*
|
1621 |
* returns: temperature sensor value (degrees)
|
1622 |
*/
|
1623 |
float dwt_convertrawtemperature(uint8 raw_temp);
|
1624 |
|
1625 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1626 |
* @fn dwt_convertdegtemptoraw()
|
1627 |
*
|
1628 |
* @brief this function takes in an externally measured temperature in 10ths of degrees Celcius
|
1629 |
* and applies the conversion factor to give a value in IC temperature units, as produced by the SAR A/D.
|
1630 |
* The dwt_initialise needs to be called before call to this to ensure pdw1000local->tempP contains the SAR_LTEMP value from OTP.
|
1631 |
*
|
1632 |
* input parameters:
|
1633 |
* @param externaltemp - this is the an externally measured temperature in 10ths of degrees Celcius to convert
|
1634 |
*
|
1635 |
* output parameters:
|
1636 |
*
|
1637 |
* returns: temperature sensor value in DW IC temperature units (1.14?C steps)
|
1638 |
*/
|
1639 |
uint8 dwt_convertdegtemptoraw(int16 realtemp); |
1640 |
|
1641 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1642 |
* @fn dwt_convertrawvoltage()
|
1643 |
*
|
1644 |
* @brief this function takes in a raw voltage value and applies the conversion factor
|
1645 |
* to give true voltage. The dwt_initialise needs to be called before call to this to
|
1646 |
* ensure pdw1000local->vBatP contains the SAR_LVBAT value from OTP
|
1647 |
*
|
1648 |
* input parameters:
|
1649 |
* @param raw_voltage - this is the 8-bit raw voltage value as read by dwt_readtempvbat
|
1650 |
*
|
1651 |
* output parameters:
|
1652 |
*
|
1653 |
* returns: voltage sensor value (volts)
|
1654 |
*/
|
1655 |
float dwt_convertrawvoltage(uint8 raw_voltage);
|
1656 |
|
1657 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1658 |
* @fn dwt_convertvoltstoraw()
|
1659 |
*
|
1660 |
* @brief this function takes in a true voltage in millivolts and applies the conversion factor to
|
1661 |
* give a raw DW IC value. The dwt_initialise needs to be called before call to this to
|
1662 |
* ensure pdw1000local->vBatP contains the SAR_LVBAT value from OTP.
|
1663 |
*
|
1664 |
* input parameters:
|
1665 |
* @param realvolt - this is the a true voltage in millivolts to convert
|
1666 |
*
|
1667 |
* output parameters:
|
1668 |
*
|
1669 |
* returns: voltage sensor value in DW IC voltage units
|
1670 |
*/
|
1671 |
uint8 dwt_convertvoltstoraw(int32 realvolt); |
1672 |
|
1673 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1674 |
* @fn dwt_readwakeuptemp()
|
1675 |
*
|
1676 |
* @brief this function reads the temperature of the DW1000 that was sampled
|
1677 |
* on waking from Sleep/Deepsleep. They are not current values, but read on last
|
1678 |
* wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
|
1679 |
*
|
1680 |
* input parameters:
|
1681 |
*
|
1682 |
* output parameters:
|
1683 |
*
|
1684 |
* returns: 8-bit raw temperature sensor value
|
1685 |
*/
|
1686 |
uint8 dwt_readwakeuptemp(void) ;
|
1687 |
|
1688 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1689 |
* @fn dwt_readwakeupvbat()
|
1690 |
*
|
1691 |
* @brief this function reads the battery voltage of the DW1000 that was sampled
|
1692 |
* on waking from Sleep/Deepsleep. They are not current values, but read on last
|
1693 |
* wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
|
1694 |
*
|
1695 |
* input parameters:
|
1696 |
*
|
1697 |
* output parameters:
|
1698 |
*
|
1699 |
* returns: 8-bit raw battery voltage sensor value
|
1700 |
*/
|
1701 |
uint8 dwt_readwakeupvbat(void) ;
|
1702 |
|
1703 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1704 |
* @fn dwt_calcbandwidthtempadj()
|
1705 |
*
|
1706 |
* @brief this function determines the corrected bandwidth setting (PG_DELAY register setting)
|
1707 |
* of the DW1000 which changes over temperature.
|
1708 |
*
|
1709 |
* input parameters:
|
1710 |
* @param target_count - uint16 - the PG count target to reach in order to correct the bandwidth
|
1711 |
*
|
1712 |
* output parameters:
|
1713 |
*
|
1714 |
* returns: (uint32) The setting to be programmed into the PG_DELAY value
|
1715 |
*/
|
1716 |
uint32 dwt_calcbandwidthtempadj(uint16 target_count); |
1717 |
|
1718 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1719 |
* @fn dwt_calcpowertempadj()
|
1720 |
*
|
1721 |
* @brief this function determines the corrected power setting (TX_POWER setting) for the
|
1722 |
* DW1000 which changes over temperature.
|
1723 |
*
|
1724 |
* Note: only ch2 or ch5 are supported, if other channel is used - the COMP factor should be calculated and adjusted
|
1725 |
*
|
1726 |
* input parameters:
|
1727 |
* @param channel - uint8 - the channel at which compensation of power level will be applied: 2 or 5
|
1728 |
* @param ref_powerreg - uint32 - the TX_POWER register value recorded when reference measurements were made
|
1729 |
* @param delta_temp - int - the difference between current ambient temperature (raw value units)
|
1730 |
* and the temperature at which reference measurements were made (raw value units)
|
1731 |
|
1732 |
* output parameters: None
|
1733 |
*
|
1734 |
* returns: (uint32) The corrected TX_POWER register value
|
1735 |
*/
|
1736 |
uint32 dwt_calcpowertempadj(uint8 channel, uint32 ref_powerreg, int delta_temp);
|
1737 |
|
1738 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1739 |
* @fn dwt_calcpgcount()
|
1740 |
*
|
1741 |
* @brief this function calculates the value in the pulse generator counter register (PGC_STATUS) for a given PG_DELAY
|
1742 |
* This is used to take a reference measurement, and the value recorded as the reference is used to adjust the
|
1743 |
* bandwidth of the device when the temperature changes.
|
1744 |
*
|
1745 |
* input parameters:
|
1746 |
* @param pgdly - uint8 - the PG_DELAY to set (to control bandwidth), and to find the corresponding count value for
|
1747 |
* output parameters: None
|
1748 |
*
|
1749 |
* returns: (uint16) PGC_STATUS count value calculated from the provided PG_DELAY value - used as reference for later
|
1750 |
* bandwidth adjustments
|
1751 |
*/
|
1752 |
uint16 dwt_calcpgcount(uint8 pgdly); |
1753 |
|
1754 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1755 |
* @fn dwt_writetodevice()
|
1756 |
*
|
1757 |
* @brief this function is used to write to the DW1000 device registers
|
1758 |
* Notes:
|
1759 |
* 1. Firstly we create a header (the first byte is a header byte)
|
1760 |
* a. check if sub index is used, if subindexing is used - set bit-6 to 1 to signify that the sub-index address follows the register index byte
|
1761 |
* b. set bit-7 (or with 0x80) for write operation
|
1762 |
* c. if extended sub address index is used (i.e. if index > 127) set bit-7 of the first sub-index byte following the first header byte
|
1763 |
*
|
1764 |
* 2. Write the header followed by the data bytes to the DW1000 device
|
1765 |
*
|
1766 |
*
|
1767 |
* input parameters:
|
1768 |
* @param recordNumber - ID of register file or buffer being accessed
|
1769 |
* @param index - byte index into register file or buffer being accessed
|
1770 |
* @param length - number of bytes being written
|
1771 |
* @param buffer - pointer to buffer containing the 'length' bytes to be written
|
1772 |
*
|
1773 |
* output parameters
|
1774 |
*
|
1775 |
* no return value
|
1776 |
*/
|
1777 |
void dwt_writetodevice
|
1778 |
( |
1779 |
uint16 recordNumber, // input parameter - ID of register file or buffer being accessed
|
1780 |
uint16 index, // input parameter - byte index into register file or buffer being accessed
|
1781 |
uint32 length, // input parameter - number of bytes being written
|
1782 |
const uint8 *buffer // input parameter - pointer to buffer containing the 'length' bytes to be written |
1783 |
) ; |
1784 |
|
1785 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1786 |
* @fn dwt_readfromdevice()
|
1787 |
*
|
1788 |
* @brief this function is used to read from the DW1000 device registers
|
1789 |
* Notes:
|
1790 |
* 1. Firstly we create a header (the first byte is a header byte)
|
1791 |
* a. check if sub index is used, if subindexing is used - set bit-6 to 1 to signify that the sub-index address follows the register index byte
|
1792 |
* b. set bit-7 (or with 0x80) for write operation
|
1793 |
* c. if extended sub address index is used (i.e. if index > 127) set bit-7 of the first sub-index byte following the first header byte
|
1794 |
*
|
1795 |
* 2. Write the header followed by the data bytes to the DW1000 device
|
1796 |
* 3. Store the read data in the input buffer
|
1797 |
*
|
1798 |
* input parameters:
|
1799 |
* @param recordNumber - ID of register file or buffer being accessed
|
1800 |
* @param index - byte index into register file or buffer being accessed
|
1801 |
* @param length - number of bytes being read
|
1802 |
* @param buffer - pointer to buffer in which to return the read data.
|
1803 |
*
|
1804 |
* output parameters
|
1805 |
*
|
1806 |
* no return value
|
1807 |
*/
|
1808 |
void dwt_readfromdevice
|
1809 |
( |
1810 |
uint16 recordNumber, // input parameter - ID of register file or buffer being accessed
|
1811 |
uint16 index, // input parameter - byte index into register file or buffer being accessed
|
1812 |
uint32 length, // input parameter - number of bytes being read
|
1813 |
uint8 *buffer // input parameter - pointer to buffer in which to return the read data.
|
1814 |
) ; |
1815 |
|
1816 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1817 |
* @fn dwt_read32bitoffsetreg()
|
1818 |
*
|
1819 |
* @brief this function is used to read 32-bit value from the DW1000 device registers
|
1820 |
*
|
1821 |
* input parameters:
|
1822 |
* @param regFileID - ID of register file or buffer being accessed
|
1823 |
* @param regOffset - the index into register file or buffer being accessed
|
1824 |
*
|
1825 |
* output parameters
|
1826 |
*
|
1827 |
* returns 32 bit register value
|
1828 |
*/
|
1829 |
uint32 dwt_read32bitoffsetreg(int regFileID, int regOffset) ; |
1830 |
|
1831 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1832 |
* @fn dwt_write32bitoffsetreg()
|
1833 |
*
|
1834 |
* @brief this function is used to write 32-bit value to the DW1000 device registers
|
1835 |
*
|
1836 |
* input parameters:
|
1837 |
* @param regFileID - ID of register file or buffer being accessed
|
1838 |
* @param regOffset - the index into register file or buffer being accessed
|
1839 |
* @param regval - the value to write
|
1840 |
*
|
1841 |
* output parameters
|
1842 |
*
|
1843 |
* no return value
|
1844 |
*/
|
1845 |
void dwt_write32bitoffsetreg(int regFileID, int regOffset, uint32 regval); |
1846 |
|
1847 |
#define dwt_write32bitreg(x,y) dwt_write32bitoffsetreg(x,0,y) |
1848 |
#define dwt_read32bitreg(x) dwt_read32bitoffsetreg(x,0) |
1849 |
|
1850 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1851 |
* @fn dwt_read16bitoffsetreg()
|
1852 |
*
|
1853 |
* @brief this function is used to read 16-bit value from the DW1000 device registers
|
1854 |
*
|
1855 |
* input parameters:
|
1856 |
* @param regFileID - ID of register file or buffer being accessed
|
1857 |
* @param regOffset - the index into register file or buffer being accessed
|
1858 |
*
|
1859 |
* output parameters
|
1860 |
*
|
1861 |
* returns 16 bit register value
|
1862 |
*/
|
1863 |
uint16 dwt_read16bitoffsetreg(int regFileID, int regOffset); |
1864 |
|
1865 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1866 |
* @fn dwt_write16bitoffsetreg()
|
1867 |
*
|
1868 |
* @brief this function is used to write 16-bit value to the DW1000 device registers
|
1869 |
*
|
1870 |
* input parameters:
|
1871 |
* @param regFileID - ID of register file or buffer being accessed
|
1872 |
* @param regOffset - the index into register file or buffer being accessed
|
1873 |
* @param regval - the value to write
|
1874 |
*
|
1875 |
* output parameters
|
1876 |
*
|
1877 |
* no return value
|
1878 |
*/
|
1879 |
void dwt_write16bitoffsetreg(int regFileID, int regOffset, uint16 regval) ; |
1880 |
|
1881 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1882 |
* @fn dwt_read8bitoffsetreg()
|
1883 |
*
|
1884 |
* @brief this function is used to read an 8-bit value from the DW1000 device registers
|
1885 |
*
|
1886 |
* input parameters:
|
1887 |
* @param regFileID - ID of register file or buffer being accessed
|
1888 |
* @param regOffset - the index into register file or buffer being accessed
|
1889 |
*
|
1890 |
* output parameters
|
1891 |
*
|
1892 |
* returns 8-bit register value
|
1893 |
*/
|
1894 |
uint8 dwt_read8bitoffsetreg(int regFileID, int regOffset); |
1895 |
|
1896 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1897 |
* @fn dwt_write8bitoffsetreg()
|
1898 |
*
|
1899 |
* @brief this function is used to write an 8-bit value to the DW1000 device registers
|
1900 |
*
|
1901 |
* input parameters:
|
1902 |
* @param regFileID - ID of register file or buffer being accessed
|
1903 |
* @param regOffset - the index into register file or buffer being accessed
|
1904 |
* @param regval - the value to write
|
1905 |
*
|
1906 |
* output parameters
|
1907 |
*
|
1908 |
* no return value
|
1909 |
*/
|
1910 |
void dwt_write8bitoffsetreg(int regFileID, int regOffset, uint8 regval); |
1911 |
|
1912 |
|
1913 |
/****************************************************************************************************************************************************
|
1914 |
*
|
1915 |
* Declaration of platform-dependent lower level functions.
|
1916 |
*
|
1917 |
****************************************************************************************************************************************************/
|
1918 |
|
1919 |
|
1920 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1921 |
* @fn writetospi()
|
1922 |
*
|
1923 |
* @brief
|
1924 |
* NB: In porting this to a particular microprocessor, the implementer needs to define the two low
|
1925 |
* level abstract functions to write to and read from the SPI the definitions should be in deca_spi.c file.
|
1926 |
* Low level abstract function to write to the SPI
|
1927 |
* Takes two separate byte buffers for write header and write data
|
1928 |
* returns 0 for success, or -1 for error
|
1929 |
*
|
1930 |
* Note: The body of this function is defined in deca_spi.c and is platform specific
|
1931 |
*
|
1932 |
* input parameters:
|
1933 |
* @param headerLength - number of bytes header being written
|
1934 |
* @param headerBuffer - pointer to buffer containing the 'headerLength' bytes of header to be written
|
1935 |
* @param bodylength - number of bytes data being written
|
1936 |
* @param bodyBuffer - pointer to buffer containing the 'bodylength' bytes od data to be written
|
1937 |
*
|
1938 |
* output parameters
|
1939 |
*
|
1940 |
* returns DWT_SUCCESS for success, or DWT_ERROR for error
|
1941 |
*/
|
1942 |
int writetospi(uint16 headerLength, const uint8 *headerBuffer, uint32 bodylength, const uint8 *bodyBuffer); |
1943 |
|
1944 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1945 |
* @fn readfromspi()
|
1946 |
*
|
1947 |
* @brief
|
1948 |
* NB: In porting this to a particular microprocessor, the implementer needs to define the two low
|
1949 |
* level abstract functions to write to and read from the SPI the definitions should be in deca_spi.c file.
|
1950 |
* Low level abstract function to write to the SPI
|
1951 |
* Takes two separate byte buffers for write header and write data
|
1952 |
* returns 0 for success, or -1 for error
|
1953 |
*
|
1954 |
* Note: The body of this function is defined in deca_spi.c and is platform specific
|
1955 |
*
|
1956 |
* input parameters:
|
1957 |
* @param headerLength - number of bytes header to write
|
1958 |
* @param headerBuffer - pointer to buffer containing the 'headerLength' bytes of header to write
|
1959 |
* @param readlength - number of bytes data being read
|
1960 |
* @param readBuffer - pointer to buffer containing to return the data (NB: size required = headerLength + readlength)
|
1961 |
*
|
1962 |
* output parameters
|
1963 |
*
|
1964 |
* returns DWT_SUCCESS for success (and the position in the buffer at which data begins), or DWT_ERROR for error
|
1965 |
*/
|
1966 |
int readfromspi(uint16 headerLength, const uint8 *headerBuffer, uint32 readlength, uint8 *readBuffer); |
1967 |
|
1968 |
// ---------------------------------------------------------------------------
|
1969 |
//
|
1970 |
// NB: The purpose of the deca_mutex.c file is to provide for microprocessor interrupt enable/disable, this is used for
|
1971 |
// controlling mutual exclusion from critical sections in the code where interrupts and background
|
1972 |
// processing may interact. The code using this is kept to a minimum and the disabling time is also
|
1973 |
// kept to a minimum, so blanket interrupt disable may be the easiest way to provide this. But at a
|
1974 |
// minimum those interrupts coming from the decawave device should be disabled/re-enabled by this activity.
|
1975 |
//
|
1976 |
// In porting this to a particular microprocessor, the implementer may choose to use #defines here
|
1977 |
// to map these calls transparently to the target system. Alternatively the appropriate code may
|
1978 |
// be embedded in the functions provided in the deca_irq.c file.
|
1979 |
//
|
1980 |
// ---------------------------------------------------------------------------
|
1981 |
|
1982 |
typedef int decaIrqStatus_t ; // Type for remembering IRQ status |
1983 |
|
1984 |
|
1985 |
/*! ------------------------------------------------------------------------------------------------------------------
|
1986 |
* @fn decamutexon()
|
1987 |
*
|
1988 |
* @brief This function should disable interrupts. This is called at the start of a critical section
|
1989 |
* It returns the IRQ state before disable, this value is used to re-enable in decamutexoff call
|
1990 |
*
|
1991 |
* Note: The body of this function is defined in deca_mutex.c and is platform specific
|
1992 |
*
|
1993 |
* input parameters:
|
1994 |
*
|
1995 |
* output parameters
|
1996 |
*
|
1997 |
* returns the state of the DW1000 interrupt
|
1998 |
*/
|
1999 |
decaIrqStatus_t decamutexon(void) ;
|
2000 |
|
2001 |
/*! ------------------------------------------------------------------------------------------------------------------
|
2002 |
* @fn decamutexoff()
|
2003 |
*
|
2004 |
* @brief This function should re-enable interrupts, or at least restore their state as returned(&saved) by decamutexon
|
2005 |
* This is called at the end of a critical section
|
2006 |
*
|
2007 |
* Note: The body of this function is defined in deca_mutex.c and is platform specific
|
2008 |
*
|
2009 |
* input parameters:
|
2010 |
* @param s - the state of the DW1000 interrupt as returned by decamutexon
|
2011 |
*
|
2012 |
* output parameters
|
2013 |
*
|
2014 |
* returns the state of the DW1000 interrupt
|
2015 |
*/
|
2016 |
void decamutexoff(decaIrqStatus_t s) ;
|
2017 |
|
2018 |
/*! ------------------------------------------------------------------------------------------------------------------
|
2019 |
* @fn deca_sleep()
|
2020 |
*
|
2021 |
* @brief Wait for a given amount of time.
|
2022 |
* NB: The body of this function is defined in deca_sleep.c and is platform specific
|
2023 |
*
|
2024 |
* input parameters:
|
2025 |
* @param time_ms - time to wait in milliseconds
|
2026 |
*
|
2027 |
* output parameters
|
2028 |
*
|
2029 |
* no return value
|
2030 |
*/
|
2031 |
void deca_sleep(unsigned int time_ms); |
2032 |
|
2033 |
#ifdef __cplusplus
|
2034 |
} |
2035 |
#endif
|
2036 |
|
2037 |
#endif /* _DECA_DEVICE_API_H_ */ |
2038 |
|
2039 |
|