Revision fce9feec

View differences:

include/alld_dw1000.h
1
/*
2
AMiRo-LLD is a compilation of low-level hardware drivers for the Autonomous Mini Robot (AMiRo) platform.
3
Copyright (C) 2016..2018  Thomas Schöpping et al.
4

  
5
This program is free software: you can redistribute it and/or modify
6
it under the terms of the GNU Lesser General Public License as published by
7
the Free Software Foundation, either version 3 of the License, or
8
(at your option) any later version.
9

  
10
This program is distributed in the hope that it will be useful,
11
but WITHOUT ANY WARRANTY; without even the implied warranty of
12
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13
GNU Lesser General Public License for more details.
14

  
15
You should have received a copy of the GNU Lesser General Public License
16
along with this program.  If not, see <http://www.gnu.org/licenses/>.
17
*/
18

  
19
/*! ----------------------------------------------------------------------------
20
 * @file    deca_device_api.h
21
 * @brief   DW1000 API Functions
22
 *
23
 * @attention
24
 *
25
 * Copyright 2013 (c) Decawave Ltd, Dublin, Ireland.
26
 *
27
 * All rights reserved.
28
 *
29
 */
30

  
31
#ifndef __AMIROLLD_DW1000_H__
32
#define __AMIROLLD_DW1000_H__
33

  
34
#include <amiro-lld.h>
35
#if defined(AMIROLLD_CFG_USE_DW1000) || defined(__DOXYGEN__)
36

  
37

  
38

  
39
#include <stddef.h>
40
#include <stdint.h>
41
#include <stdbool.h>
42

  
43
#define DW1000_DRIVER_VERSION               0x040005
44
#define DW1000_DEVICE_DRIVER_VER_STRING     "DW1000 Device Driver Version 04.00.05"
45

  
46
#ifndef DWT_NUM_DW_DEV
47
#define DWT_NUM_DW_DEV (1)
48
#endif
49

  
50
#define DWT_SUCCESS (0)
51
#define DWT_ERROR   (-1)
52

  
53

  
54
/**
55
 * @brief The DW1000 driver struct.
56
 */
57
typedef struct {
58
  apalSPIDriver_t* spid;    /**< @brief The SPI Driver */
59
  apalGpio_t* gpio_exti;    /**< @brief The GPIO indicating external interrupt */
60
  apalGpio_t* gpio_reset;  /**< @brief The GPIO indicating reset sig*/
61
  /* TODO: better apalControlGpio_t instead of apalGpio_t ? */
62
  /* TODO: EXTI, GPIO (RESET) */
63
} DW1000Driver;
64

  
65

  
66
#define DWT_TIME_UNITS  (1.0/499.2e6/128.0) //!< = 15.65e-12 s
67

  
68
#define DWT_DEVICE_ID   (0xDECA0130)        //!< DW1000 MP device ID
69

  
70
#define BUFFLEN 	(4096+128)
71

  
72
//! constants for selecting the bit rate for data TX (and RX)
73
//! These are defined for write (with just a shift) the TX_FCTRL register
74
#define DWT_BR_110K     0   //!< UWB bit rate 110 kbits/s
75
#define DWT_BR_850K     1   //!< UWB bit rate 850 kbits/s
76
#define DWT_BR_6M8      2   //!< UWB bit rate 6.8 Mbits/s
77

  
78
//! constants for specifying the (Nominal) mean Pulse Repetition Frequency
79
//! These are defined for direct write (with a shift if necessary) to CHAN_CTRL and TX_FCTRL regs
80
#define DWT_PRF_16M     1   //!< UWB PRF 16 MHz
81
#define DWT_PRF_64M     2   //!< UWB PRF 64 MHz
82

  
83
//! constants for specifying Preamble Acquisition Chunk (PAC) Size in symbols
84
#define DWT_PAC8        0   //!< PAC  8 (recommended for RX of preamble length  128 and below
85
#define DWT_PAC16       1   //!< PAC 16 (recommended for RX of preamble length  256
86
#define DWT_PAC32       2   //!< PAC 32 (recommended for RX of preamble length  512
87
#define DWT_PAC64       3   //!< PAC 64 (recommended for RX of preamble length 1024 and up
88

  
89
//! constants for specifying TX Preamble length in symbols
90
//! These are defined to allow them be directly written into byte 2 of the TX_FCTRL register
91
//! (i.e. a four bit value destined for bits 20..18 but shifted left by 2 for byte alignment)
92
#define DWT_PLEN_4096   0x0C    //! Standard preamble length 4096 symbols
93
#define DWT_PLEN_2048   0x28    //! Non-standard preamble length 2048 symbols
94
#define DWT_PLEN_1536   0x18    //! Non-standard preamble length 1536 symbols
95
#define DWT_PLEN_1024   0x08    //! Standard preamble length 1024 symbols
96
#define DWT_PLEN_512    0x34    //! Non-standard preamble length 512 symbols
97
#define DWT_PLEN_256    0x24    //! Non-standard preamble length 256 symbols
98
#define DWT_PLEN_128    0x14    //! Non-standard preamble length 128 symbols
99
#define DWT_PLEN_64     0x04    //! Standard preamble length 64 symbols
100

  
101
#define DWT_SFDTOC_DEF              0x1041  // default SFD timeout value
102

  
103
#define DWT_PHRMODE_STD             0x0     // standard PHR mode
104
#define DWT_PHRMODE_EXT             0x3     // DW proprietary extended frames PHR mode
105

  
106
// Defined constants for "mode" bitmask parameter passed into dwt_starttx() function.
107
#define DWT_START_TX_IMMEDIATE      0
108
#define DWT_START_TX_DELAYED        1
109
#define DWT_RESPONSE_EXPECTED       2
110

  
111
#define DWT_START_RX_IMMEDIATE  0
112
#define DWT_START_RX_DELAYED    1    // Set up delayed RX, if "late" error triggers, then the RX will be enabled immediately
113
#define DWT_IDLE_ON_DLY_ERR     2    // If delayed RX failed due to "late" error then if this
114
                                     // flag is set the RX will not be re-enabled immediately, and device will be in IDLE when function exits
115
#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
116
                                     // re-enabling when receiving a frame in double buffer mode.
117

  
118
// Defined constants for "mode" bit field parameter passed to dwt_setleds() function.
119
#define DWT_LEDS_DISABLE     0x00
120
#define DWT_LEDS_ENABLE      0x01
121
#define DWT_LEDS_INIT_BLINK  0x02
122

  
123
//frame filtering configuration options
124
#define DWT_FF_NOTYPE_EN            0x000           // no frame types allowed (FF disabled)
125
#define DWT_FF_COORD_EN             0x002           // behave as coordinator (can receive frames with no dest address (PAN ID has to match))
126
#define DWT_FF_BEACON_EN            0x004           // beacon frames allowed
127
#define DWT_FF_DATA_EN              0x008           // data frames allowed
128
#define DWT_FF_ACK_EN               0x010           // ack frames allowed
129
#define DWT_FF_MAC_EN               0x020           // mac control frames allowed
130
#define DWT_FF_RSVD_EN              0x040           // reserved frame types allowed
131

  
132
//DW1000 interrupt events
133
#define DWT_INT_TFRS            0x00000080          // frame sent
134
#define DWT_INT_LDED            0x00000400          // micro-code has finished execution
135
#define DWT_INT_RFCG            0x00004000          // frame received with good CRC
136
#define DWT_INT_RPHE            0x00001000          // receiver PHY header error
137
#define DWT_INT_RFCE            0x00008000          // receiver CRC error
138
#define DWT_INT_RFSL            0x00010000          // receiver sync loss error
139
#define DWT_INT_RFTO            0x00020000          // frame wait timeout
140
#define DWT_INT_RXOVRR          0x00100000          // receiver overrun
141
#define DWT_INT_RXPTO           0x00200000          // preamble detect timeout
142
#define DWT_INT_SFDT            0x04000000          // SFD timeout
143
#define DWT_INT_ARFE            0x20000000          // frame rejected (due to frame filtering configuration)
144

  
145

  
146
//DW1000 SLEEP and WAKEUP configuration parameters
147
#define DWT_PRESRV_SLEEP 0x0100                      // PRES_SLEEP - on wakeup preserve sleep bit
148
#define DWT_LOADOPSET    0x0080                      // ONW_L64P - on wakeup load operating parameter set for 64 PSR
149
#define DWT_CONFIG       0x0040                      // ONW_LDC - on wakeup restore (load) the saved configurations (from AON array into HIF)
150
#define DWT_LOADEUI      0x0008                      // ONW_LEUI - on wakeup load EUI
151
#define DWT_RX_EN        0x0002                      // ONW_RX - on wakeup activate reception
152
#define DWT_TANDV        0x0001                      // ONW_RADC - on wakeup run ADC to sample temperature and voltage sensor values
153

  
154
#define DWT_XTAL_EN      0x10                       // keep XTAL running during sleep
155
#define DWT_WAKE_SLPCNT  0x8                        // wake up after sleep count
156
#define DWT_WAKE_CS      0x4                        // wake up on chip select
157
#define DWT_WAKE_WK      0x2                        // wake up on WAKEUP PIN
158
#define DWT_SLP_EN       0x1                        // enable sleep/deep sleep functionality
159

  
160
//DW1000 INIT configuration parameters
161
#define DWT_LOADUCODE     0x1
162
#define DWT_LOADNONE      0x0
163

  
164
//DW1000 OTP operating parameter set selection
165
#define DWT_OPSET_64LEN   0x0
166
#define DWT_OPSET_TIGHT   0x1
167
#define DWT_OPSET_DEFLT   0x2
168

  
169
// Call-back data RX frames flags
170
#define DWT_CB_DATA_RX_FLAG_RNG 0x1 // Ranging bit
171

  
172

  
173
// TX/RX call-back data
174
typedef struct
175
{
176
    uint32_t status;      //initial value of register as ISR is entered
177
    uint16_t datalength;  //length of frame
178
    uint8_t  fctrl[2];    //frame control bytes
179
    uint8_t  rx_flags;    //RX frame flags, see above
180
} dwt_cb_data_t;
181

  
182
// Call-back type for all events
183
typedef void (*dwt_cb_t)(const dwt_cb_data_t *);
184

  
185

  
186
// -------------------------------------------------------------------------------------------------------------------
187
// Structure to hold device data
188
typedef struct
189
{
190
    uint32_t      partID ;            // IC Part ID - read during initialisation
191
    uint32_t      lotID ;             // IC Lot ID - read during initialisation
192
    uint8_t       longFrames ;        // Flag in non-standard long frame mode
193
    uint8_t       otprev ;            // OTP revision number (read during initialisation)
194
    uint32_t      txFCTRL ;           // Keep TX_FCTRL register config
195
    uint8_t       init_xtrim;         // initial XTAL trim value read from OTP (or defaulted to mid-range if OTP not programmed)
196
    uint8_t       dblbuffon;          // Double RX buffer mode flag
197
    uint32_t      sysCFGreg ;         // Local copy of system config register
198
    uint16_t      sleep_mode;         // Used for automatic reloading of LDO tune and microcode at wake-up
199
    uint8_t       wait4resp ;         // wait4response was set with last TX start command
200
    dwt_cb_data_t cbData;             // Callback data structure
201
    dwt_cb_t      cbTxDone;           // Callback for TX confirmation event
202
    dwt_cb_t      cbRxOk;             // Callback for RX good frame event
203
    dwt_cb_t      cbRxTo;             // Callback for RX timeout events
204
    dwt_cb_t      cbRxErr;            // Callback for RX error events
205
    DW1000Driver  *driver;      // Reference to local hardware SPI, GPIO, ...
206
} dwt_local_data_t ;
207

  
208
/*! ------------------------------------------------------------------------------------------------------------------
209
 * Structure typedef: dwt_config_t
210
 *
211
 * Structure for setting device configuration via dwt_configure() function
212
 *
213
 */
214
typedef struct
215
{
216
    uint8_t chan ;           //!< channel number {1, 2, 3, 4, 5, 7 }
217
    uint8_t prf ;            //!< Pulse Repetition Frequency {DWT_PRF_16M or DWT_PRF_64M}
218
    uint8_t txPreambLength ; //!< DWT_PLEN_64..DWT_PLEN_4096
219
    uint8_t rxPAC ;          //!< Acquisition Chunk Size (Relates to RX preamble length)
220
    uint8_t txCode ;         //!< TX preamble code
221
    uint8_t rxCode ;         //!< RX preamble code
222
    uint8_t nsSFD ;          //!< Boolean should we use non-standard SFD for better performance
223
    uint8_t dataRate ;       //!< Data Rate {DWT_BR_110K, DWT_BR_850K or DWT_BR_6M8}
224
    uint8_t phrMode ;        //!< PHR mode {0x0 - standard DWT_PHRMODE_STD, 0x3 - extended frames DWT_PHRMODE_EXT}
225
    uint16_t sfdTO ;         //!< SFD timeout value (in symbols)
226
} dwt_config_t ;
227

  
228

  
229
typedef struct
230
{
231
    uint8_t   PGdly;
232
    //TX POWER
233
    //31:24     BOOST_0.125ms_PWR
234
    //23:16     BOOST_0.25ms_PWR-TX_SHR_PWR
235
    //15:8      BOOST_0.5ms_PWR-TX_PHR_PWR
236
    //7:0       DEFAULT_PWR-TX_DATA_PWR
237
    uint32_t  power;
238
} dwt_txconfig_t ;
239

  
240

  
241
typedef struct
242
{
243

  
244
    uint16_t      maxNoise ;          // LDE max value of noise
245
    uint16_t      firstPathAmp1 ;     // Amplitude at floor(index FP) + 1
246
    uint16_t      stdNoise ;          // Standard deviation of noise
247
    uint16_t      firstPathAmp2 ;     // Amplitude at floor(index FP) + 2
248
    uint16_t      firstPathAmp3 ;     // Amplitude at floor(index FP) + 3
249
    uint16_t      maxGrowthCIR ;      // Channel Impulse Response max growth CIR
250
    uint16_t      rxPreamCount ;      // Count of preamble symbols accumulated
251
    uint16_t      firstPath ;         // First path index (10.6 bits fixed point integer)
252
}dwt_rxdiag_t ;
253

  
254

  
255
typedef struct
256
{
257
    //all of the below are mapped to a 12-bit register in DW1000
258
    uint16_t PHE ;                    //number of received header errors
259
    uint16_t RSL ;                    //number of received frame sync loss events
260
    uint16_t CRCG ;                   //number of good CRC received frames
261
    uint16_t CRCB ;                   //number of bad CRC (CRC error) received frames
262
    uint16_t ARFE ;                   //number of address filter errors
263
    uint16_t OVER ;                   //number of receiver overflows (used in double buffer mode)
264
    uint16_t SFDTO ;                  //SFD timeouts
265
    uint16_t PTO ;                    //Preamble timeouts
266
    uint16_t RTO ;                    //RX frame wait timeouts
267
    uint16_t TXF ;                    //number of transmitted frames
268
    uint16_t HPW ;                    //half period warn
269
    uint16_t TXW ;                    //power up warn
270

  
271
} dwt_deviceentcnts_t ;
272

  
273

  
274
/********************************************************************************************************************/
275
/*                                                 REMOVED API LIST                                                 */
276
/********************************************************************************************************************/
277
/*
278
 * From version 4.0.0:
279
 *  - dwt_setGPIOforEXTTRX: Replaced by dwt_setlnapamode to get equivalent functionality.
280
 *  - dwt_setGPIOdirection: Renamed to dwt_setgpiodirection.
281
 *  - dwt_setGPIOvalue: Renamed to dwt_setgpiovalue.
282
 *  - dwt_setrxmode: Replaced by dwt_setsniffmode and dwt_setlowpowerlistening depending on the RX mode the user
283
 *    wants to set up.
284
 *  - dwt_checkoverrun: As automatic RX re-enabling is not supported anymore, this functions has become useless.
285
 *  - dwt_setautorxreenable: As automatic RX re-enabling is not supported anymore, this functions has become
286
 *    useless.
287
 *  - dwt_getrangebias: Range bias correction values are platform dependent and should therefore be managed at user
288
 *    application level.
289
 *  - dwt_xtaltrim: Renamed to dwt_setxtaltrim.
290
 *  - dwt_checkIRQ: Renamed to dwt_checkirq.
291
 *
292
 * From version 3.0.0:
293
 *  - dwt_getldotune: As LDO loading is now automatically managed by the driver, this function has become useless.
294
 *  - dwt_getotptxpower: TX power values and location in OTP memory are platform dependent and should therefore be
295
 *    managed at user application level.
296
 *  - dwt_readantennadelay: Antenna delay values and location in OTP memory are platform dependent and should
297
 *    therefore be managed at user application level.
298
 *  - dwt_readdignostics: Renamed to dwt_readdiagnostics.
299
 */
300

  
301
/********************************************************************************************************************/
302
/*                                                     API LIST                                                     */
303
/********************************************************************************************************************/
304

  
305
/*! ------------------------------------------------------------------------------------------------------------------
306
 * @fn dwt_setdevicedataptr()
307
 *
308
 * @brief This function sets the local data structure pointer to point to the structure in the local array as given by the index.
309
 *
310
 * input parameters
311
 * @param index    - selects the array object to point to. Must be within the array bounds, i.e. < DWT_NUM_DW_DEV
312
 *
313
 * output parameters
314
 *
315
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
316
 */
317
int dwt_setdevicedataptr(unsigned int index);
318

  
319
/*! ------------------------------------------------------------------------------------------------------------------
320
 * @fn dwt_getpartid()
321
 *
322
 * @brief This is used to return the read part ID of the device
323
 *
324
 * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
325
 *
326
 * input parameters
327
 *
328
 * output parameters
329
 *
330
 * returns the 32 bit part ID value as programmed in the factory
331
 */
332
uint32_t dwt_getpartid(void);
333

  
334
/*! ------------------------------------------------------------------------------------------------------------------
335
 * @fn dwt_getlotid()
336
 *
337
 * @brief This is used to return the read lot ID of the device
338
 *
339
 * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
340
 *
341
 * input parameters
342
 *
343
 * output parameters
344
 *
345
 * returns the 32 bit lot ID value as programmed in the factory
346
 */
347
uint32_t dwt_getlotid(void);
348

  
349
/*! ------------------------------------------------------------------------------------------------------------------
350
 * @fn dwt_readdevid()
351
 *
352
 * @brief This is used to return the read device type and revision information of the DW1000 device (MP part is 0xDECA0130)
353
 *
354
 * input parameters
355
 *
356
 * output parameters
357
 *
358
 * returns the read value which for DW1000 is 0xDECA0130
359
 */
360
uint32_t dwt_readdevid(void);
361

  
362
/*! ------------------------------------------------------------------------------------------------------------------
363
 * @fn dwt_otprevision()
364
 *
365
 * @brief This is used to return the read OTP revision
366
 *
367
 * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
368
 *
369
 * input parameters
370
 *
371
 * output parameters
372
 *
373
 * returns the read OTP revision value
374
 */
375
uint8_t dwt_otprevision(void);
376

  
377
/*! ------------------------------------------------------------------------------------------------------------------
378
 * @fn dwt_setfinegraintxseq()
379
 *
380
 * @brief This function enables/disables the fine grain TX sequencing (enabled by default).
381
 *
382
 * input parameters
383
 * @param enable - 1 to enable fine grain TX sequencing, 0 to disable it.
384
 *
385
 * output parameters none
386
 *
387
 * no return value
388
 */
389
void dwt_setfinegraintxseq(int enable);
390

  
391
/*! ------------------------------------------------------------------------------------------------------------------
392
 * @fn dwt_setlnapamode()
393
 *
394
 * @brief This is used to enable GPIO for external LNA or PA functionality - HW dependent, consult the DW1000 User Manual.
395
 *        This can also be used for debug as enabling TX and RX GPIOs is quite handy to monitor DW1000's activity.
396
 *
397
 * NOTE: Enabling PA functionality requires that fine grain TX sequencing is deactivated. This can be done using
398
 *       dwt_setfinegraintxseq().
399
 *
400
 * input parameters
401
 * @param lna - 1 to enable LNA functionality, 0 to disable it
402
 * @param pa - 1 to enable PA functionality, 0 to disable it
403
 *
404
 * output parameters
405
 *
406
 * no return value
407
 */
408
void dwt_setlnapamode(int lna, int pa);
409

  
410
/*! ------------------------------------------------------------------------------------------------------------------
411
 * @fn dwt_setgpiodirection()
412
 *
413
 * @brief This is used to set GPIO direction as an input (1) or output (0)
414
 *
415
 * input parameters
416
 * @param gpioNum    -   this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
417
 * @param direction  -   this sets the GPIO direction - see GxP0... GxP8 in the deca_regs.h file
418
 *
419
 * output parameters
420
 *
421
 * no return value
422
 */
423
void dwt_setgpiodirection(uint32_t gpioNum, uint32_t direction);
424

  
425
/*! ------------------------------------------------------------------------------------------------------------------
426
 * @fn dwt_setgpiovalue()
427
 *
428
 * @brief This is used to set GPIO value as (1) or (0) only applies if the GPIO is configured as output
429
 *
430
 * input parameters
431
 * @param gpioNum    -   this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
432
 * @param value  -   this sets the GPIO value - see GDP0... GDP8 in the deca_regs.h file
433
 *
434
 * output parameters
435
 *
436
 * no return value
437
 */
438
void dwt_setgpiovalue(uint32_t gpioNum, uint32_t value);
439

  
440
/*! ------------------------------------------------------------------------------------------------------------------
441
 * @fn dwt_initialise()
442
 *
443
 * @brief This function initiates communications with the DW1000 transceiver
444
 * and reads its DEV_ID register (address 0x00) to verify the IC is one supported
445
 * by this software (e.g. DW1000 32-bit device ID value is 0xDECA0130).  Then it
446
 * does any initial once only device configurations needed for use and initialises
447
 * as necessary any static data items belonging to this low-level driver.
448
 *
449
 * NOTES:
450
 * 1.this function needs to be run before dwt_configuresleep, also the SPI frequency has to be < 3MHz
451
 * 2.it also reads and applies LDO tune and crystal trim values from OTP memory
452
 *
453
 * input parameters
454
 * @param config    -   specifies what configuration to load
455
 *                  DWT_LOADUCODE     0x1 - load the LDE microcode from ROM - enabled accurate RX timestamp
456
 *                  DWT_LOADNONE      0x0 - do not load any values from OTP memory
457
 * @param drv       -   hardware specifc struct containg refernce to SPI, GPIO etc.
458
 *
459
 * output parameters
460
 *
461
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
462
 */
463
int dwt_initialise(uint16_t config, DW1000Driver* drv) ;
464

  
465
/*! ------------------------------------------------------------------------------------------------------------------
466
 * @fn dwt_configure()
467
 *
468
 * @brief This function provides the main API for the configuration of the
469
 * DW1000 and this low-level driver.  The input is a pointer to the data structure
470
 * of type dwt_config_t that holds all the configurable items.
471
 * The dwt_config_t structure shows which ones are supported
472
 *
473
 * input parameters
474
 * @param config    -   pointer to the configuration structure, which contains the device configuration data.
475
 *
476
 * output parameters
477
 *
478
 * no return value
479
 */
480
void dwt_configure(dwt_config_t* config) ;
481

  
482
/*! ------------------------------------------------------------------------------------------------------------------
483
 * @fn dwt_configuretxrf()
484
 *
485
 * @brief This function provides the API for the configuration of the TX spectrum
486
 * including the power and pulse generator delay. The input is a pointer to the data structure
487
 * of type dwt_txconfig_t that holds all the configurable items.
488
 *
489
 * input parameters
490
 * @param config    -   pointer to the txrf configuration structure, which contains the tx rf config data
491
 *
492
 * output parameters
493
 *
494
 * no return value
495
 */
496
void dwt_configuretxrf(dwt_txconfig_t *config) ;
497

  
498
/*! ------------------------------------------------------------------------------------------------------------------
499
 * @fn dwt_setrxantennadelay()
500
 *
501
 * @brief This API function writes the antenna delay (in time units) to RX registers
502
 *
503
 * input parameters:
504
 * @param rxDelay - this is the total (RX) antenna delay value, which
505
 *                          will be programmed into the RX register
506
 *
507
 * output parameters
508
 *
509
 * no return value
510
 */
511
void dwt_setrxantennadelay(uint16_t antennaDly);
512

  
513
/*! ------------------------------------------------------------------------------------------------------------------
514
 * @fn dwt_settxantennadelay()
515
 *
516
 * @brief This API function writes the antenna delay (in time units) to TX registers
517
 *
518
 * input parameters:
519
 * @param txDelay - this is the total (TX) antenna delay value, which
520
 *                          will be programmed into the TX delay register
521
 *
522
 * output parameters
523
 *
524
 * no return value
525
 */
526
void dwt_settxantennadelay(uint16_t antennaDly);
527

  
528
/*! ------------------------------------------------------------------------------------------------------------------
529
 * @fn dwt_setsmarttxpower()
530
 *
531
 * @brief This call enables or disables the smart TX power feature.
532
 *
533
 * input parameters
534
 * @param enable - this enables or disables the TX smart power (1 = enable, 0 = disable)
535
 *
536
 * output parameters
537
 *
538
 * no return value
539
 */
540
void dwt_setsmarttxpower(int enable);
541

  
542
/*! ------------------------------------------------------------------------------------------------------------------
543
 * @fn dwt_writetxdata()
544
 *
545
 * @brief This API function writes the supplied TX data into the DW1000's
546
 * TX buffer.  The input parameters are the data length in bytes and a pointer
547
 * to those data bytes.
548
 *
549
 * input parameters
550
 * @param txFrameLength  - This is the total frame length, including the two byte CRC.
551
 *                         Note: this is the length of TX message (including the 2 byte CRC) - max is 1023
552
 *                         standard PHR mode allows up to 127 bytes
553
 *                         if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
554
 *                         see dwt_configure function
555
 * @param txFrameBytes   - Pointer to the user’s buffer containing the data to send.
556
 * @param txBufferOffset - This specifies an offset in the DW1000’s TX Buffer at which to start writing data.
557
 *
558
 * output parameters
559
 *
560
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
561
 */
562
int dwt_writetxdata(uint16_t txFrameLength, uint8_t *txFrameBytes, uint16_t txBufferOffset) ;
563

  
564
/*! ------------------------------------------------------------------------------------------------------------------
565
 * @fn dwt_writetxfctrl()
566
 *
567
 * @brief This API function configures the TX frame control register before the transmission of a frame
568
 *
569
 * input parameters:
570
 * @param txFrameLength - this is the length of TX message (including the 2 byte CRC) - max is 1023
571
 *                              NOTE: standard PHR mode allows up to 127 bytes
572
 *                              if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
573
 *                              see dwt_configure function
574
 * @param txBufferOffset - the offset in the tx buffer to start writing the data
575
 * @param ranging - 1 if this is a ranging frame, else 0
576
 *
577
 * output parameters
578
 *
579
 * no return value
580
 */
581
void dwt_writetxfctrl(uint16_t txFrameLength, uint16_t txBufferOffset, int ranging);
582

  
583
/*! ------------------------------------------------------------------------------------------------------------------
584
 * @fn dwt_starttx()
585
 *
586
 * @brief This call initiates the transmission, input parameter indicates which TX mode is used see below
587
 *
588
 * input parameters:
589
 * @param mode - is a bitmask for which the following values can be combined to define the operation
590
 *               DWT_START_TX_IMMEDIATE (0)            - to begin transmission immediatelty.
591
 *               DWT_START_TX_DELAYED   (to set bit 0) - to begin TX at pre-configured delay time
592
 *               DWT_RESPONSE_EXPECTED  (to set bit 1) - to turn the receiver on automatically (after the TX) after a pre-programmed delay
593
 * output parameters
594
 *
595
 * returns DWT_SUCCESS for success, or DWT_ERROR for error (e.g. a delayed transmission will fail if the delayed time has passed)
596
 */
597
int dwt_starttx(uint8_t mode) ;
598

  
599
/*! ------------------------------------------------------------------------------------------------------------------
600
 * @fn dwt_setdelayedtrxtime()
601
 *
602
 * @brief This API function configures the delayed transmit time or the delayed RX on time
603
 *
604
 * input parameters
605
 * @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,
606
 * or at which to turn on the receiver)
607
 *
608
 * output parameters none
609
 *
610
 * no return value
611
 */
612
void dwt_setdelayedtrxtime(uint32_t starttime) ;
613

  
614
/*! ------------------------------------------------------------------------------------------------------------------
615
 * @fn dwt_readtxtimestamp()
616
 *
617
 * @brief This is used to read the TX timestamp (adjusted with the programmed antenna delay)
618
 *
619
 * input parameters
620
 * @param timestamp - a pointer to a 5-byte buffer which will store the read TX timestamp time
621
 *
622
 * output parameters - the timestamp buffer will contain the value after the function call
623
 *
624
 * no return value
625
 */
626
void dwt_readtxtimestamp(uint8_t * timestamp);
627

  
628
/*! ------------------------------------------------------------------------------------------------------------------
629
 * @fn dwt_readtxtimestamphi32()
630
 *
631
 * @brief This is used to read the high 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
632
 *
633
 * input parameters
634
 *
635
 * output parameters
636
 *
637
 * returns high 32-bits of TX timestamp
638
 */
639
uint32_t dwt_readtxtimestamphi32(void);
640

  
641
/*! ------------------------------------------------------------------------------------------------------------------
642
 * @fn dwt_readtxtimestamplo32()
643
 *
644
 * @brief This is used to read the low 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
645
 *
646
 * input parameters
647
 *
648
 * output parameters
649
 *
650
 * returns low 32-bits of TX timestamp
651
 */
652
uint32_t dwt_readtxtimestamplo32(void);
653

  
654
/*! ------------------------------------------------------------------------------------------------------------------
655
 * @fn dwt_readrxtimestamp()
656
 *
657
 * @brief This is used to read the RX timestamp (adjusted time of arrival)
658
 *
659
 * input parameters
660
 * @param timestamp - a pointer to a 5-byte buffer which will store the read RX timestamp time
661
 *
662
 * output parameters - the timestamp buffer will contain the value after the function call
663
 *
664
 * no return value
665
 */
666
void dwt_readrxtimestamp(uint8_t * timestamp);
667

  
668
/*! ------------------------------------------------------------------------------------------------------------------
669
 * @fn dwt_readrxtimestamphi32()
670
 *
671
 * @brief This is used to read the high 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
672
 *
673
 * input parameters
674
 *
675
 * output parameters
676
 *
677
 * returns high 32-bits of RX timestamp
678
 */
679
uint32_t dwt_readrxtimestamphi32(void);
680

  
681
/*! ------------------------------------------------------------------------------------------------------------------
682
 * @fn dwt_readrxtimestamplo32()
683
 *
684
 * @brief This is used to read the low 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
685
 *
686
 * input parameters
687
 *
688
 * output parameters
689
 *
690
 * returns low 32-bits of RX timestamp
691
 */
692
uint32_t dwt_readrxtimestamplo32(void);
693

  
694
/*! ------------------------------------------------------------------------------------------------------------------
695
 * @fn dwt_readsystimestamphi32()
696
 *
697
 * @brief This is used to read the high 32-bits of the system time
698
 *
699
 * input parameters
700
 *
701
 * output parameters
702
 *
703
 * returns high 32-bits of system time timestamp
704
 */
705
uint32_t dwt_readsystimestamphi32(void);
706

  
707
/*! ------------------------------------------------------------------------------------------------------------------
708
 * @fn dwt_readsystime()
709
 *
710
 * @brief This is used to read the system time
711
 *
712
 * input parameters
713
 * @param timestamp - a pointer to a 5-byte buffer which will store the read system time
714
 *
715
 * output parameters
716
 * @param timestamp - the timestamp buffer will contain the value after the function call
717
 *
718
 * no return value
719
 */
720
void dwt_readsystime(uint8_t * timestamp);
721

  
722
/*! ------------------------------------------------------------------------------------------------------------------
723
 * @fn dwt_forcetrxoff()
724
 *
725
 * @brief This is used to turn off the transceiver
726
 *
727
 * input parameters
728
 *
729
 * output parameters
730
 *
731
 * no return value
732
 */
733
void dwt_forcetrxoff(void);
734

  
735
/*! ------------------------------------------------------------------------------------------------------------------
736
 * @fn dwt_syncrxbufptrs()
737
 *
738
 * @brief this function synchronizes rx buffer pointers
739
 * need to make sure that the host/IC buffer pointers are aligned before starting RX
740
 *
741
 * input parameters:
742
 *
743
 * output parameters
744
 *
745
 * no return value
746
 */
747
void dwt_syncrxbufptrs(void);
748

  
749
/*! ------------------------------------------------------------------------------------------------------------------
750
 * @fn dwt_rxenable()
751
 *
752
 * @brief This call turns on the receiver, can be immediate or delayed (depending on the mode parameter). In the case of a
753
 * "late" error the receiver will only be turned on if the DWT_IDLE_ON_DLY_ERR is not set.
754
 * The receiver will stay turned on, listening to any messages until
755
 * it either receives a good frame, an error (CRC, PHY header, Reed Solomon) or  it times out (SFD, Preamble or Frame).
756
 *
757
 * input parameters
758
 * @param mode - this can be one of the following allowed values:
759
 *
760
 * DWT_START_RX_IMMEDIATE      0 used to enbale receiver immediately
761
 * DWT_START_RX_DELAYED        1 used to set up delayed RX, if "late" error triggers, then the RX will be enabled immediately
762
 * (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
763
 * (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
764
 *                                               performing manual RX re-enabling in double buffering mode
765
 *
766
 * 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)
767
 */
768
int dwt_rxenable(int mode);
769

  
770
/*! ------------------------------------------------------------------------------------------------------------------
771
 * @fn dwt_setsniffmode()
772
 *
773
 * @brief enable/disable and configure SNIFF mode.
774
 *
775
 * SNIFF mode is a low-power reception mode where the receiver is sequenced on and off instead of being on all the time.
776
 * The time spent in each state (on/off) is specified through the parameters below.
777
 * See DW1000 User Manual section 4.5 "Low-Power SNIFF mode" for more details.
778
 *
779
 * input parameters:
780
 * @param enable - 1 to enable SNIFF mode, 0 to disable. When 0, all other parameters are not taken into account.
781
 * @param timeOn - duration of receiver ON phase, expressed in multiples of PAC size. The counter automatically adds 1 PAC
782
 *                 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.
783
 * @param timeOff - duration of receiver OFF phase, expressed in multiples of 128/125 µs (~1 µs). Max value is 255.
784
 *
785
 * output parameters
786
 *
787
 * no return value
788
 */
789
void dwt_setsniffmode(int enable, uint8_t timeOn, uint8_t timeOff);
790

  
791
/*! ------------------------------------------------------------------------------------------------------------------
792
 * @fn dwt_setlowpowerlistening()
793
 *
794
 * @brief enable/disable low-power listening mode.
795
 *
796
 * Low-power listening is a feature whereby the DW1000 is predominantly in the SLEEP state but wakes periodically, (after
797
 * this "long sleep"), for a very short time to sample the air for a preamble sequence. This preamble sampling "listening"
798
 * phase is actually two reception phases separated by a "short sleep" time. See DW1000 User Manual section "Low-Power
799
 * Listening" for more details.
800
 *
801
 * NOTE: Before enabling low-power listening, the following functions have to be called to fully configure it:
802
 *           - dwt_configuresleep() to configure long sleep phase. "mode" parameter should at least have DWT_PRESRV_SLEEP,
803
 *             DWT_CONFIG and DWT_RX_EN set and "wake" parameter should at least have both DWT_WAKE_SLPCNT and DWT_SLP_EN set.
804
 *           - dwt_calibratesleepcnt() and dwt_configuresleepcnt() to define the "long sleep" phase duration.
805
 *           - dwt_setsnoozetime() to define the "short sleep" phase duration.
806
 *           - dwt_setpreambledetecttimeout() to define the reception phases duration.
807
 *           - dwt_setinterrupt() to activate RX good frame interrupt (DWT_INT_RFCG) only.
808
 *       When configured, low-power listening mode can be triggered either by putting the DW1000 to sleep (using
809
 *       dwt_entersleep()) or by activating reception (using dwt_rxenable()).
810
 *
811
 *       Please refer to the low-power listening examples (examples 8a/8b accompanying the API distribution on Decawave's
812
 *       website). They form a working example code that shows how to use low-power listening correctly.
813
 *
814
 * input parameters:
815
 * @param enable - 1 to enable low-power listening, 0 to disable.
816
 *
817
 * output parameters
818
 *
819
 * no return value
820
 */
821
void dwt_setlowpowerlistening(int enable);
822

  
823
/*! ------------------------------------------------------------------------------------------------------------------
824
 * @fn dwt_setsnoozetime()
825
 *
826
 * @brief Set duration of "short sleep" phase when in low-power listening mode.
827
 *
828
 * input parameters:
829
 * @param snooze_time - "short sleep" phase duration, expressed in multiples of 512/19.2 µs (~26.7 µs). The counter
830
 *                      automatically adds 1 to the value set. The smallest working value that should be set is 1,
831
 *                      i.e. giving a snooze time of 2 units (or ~53 µs).
832
 *
833
 * output parameters
834
 *
835
 * no return value
836
 */
837
void dwt_setsnoozetime(uint8_t snooze_time);
838

  
839
/*! ------------------------------------------------------------------------------------------------------------------
840
 * @fn dwt_setdblrxbuffmode()
841
 *
842
 * @brief This call enables the double receive buffer mode
843
 *
844
 * input parameters
845
 * @param enable - 1 to enable, 0 to disable the double buffer mode
846
 *
847
 * output parameters
848
 *
849
 * no return value
850
 */
851
void dwt_setdblrxbuffmode(int enable);
852

  
853
/*! ------------------------------------------------------------------------------------------------------------------
854
 * @fn dwt_setrxtimeout()
855
 *
856
 * @brief This call enables RX timeout (SY_STAT_RFTO event)
857
 *
858
 * input parameters
859
 * @param time - how long the receiver remains on from the RX enable command
860
 *               The time parameter used here is in 1.0256 us (512/499.2MHz) units
861
 *               If set to 0 the timeout is disabled.
862
 *
863
 * output parameters
864
 *
865
 * no return value
866
 */
867
void dwt_setrxtimeout(uint16_t time);
868

  
869
/*! ------------------------------------------------------------------------------------------------------------------
870
 * @fn dwt_setpreambledetecttimeout()
871
 *
872
 * @brief This call enables preamble timeout (SY_STAT_RXPTO event)
873
 *
874
 * input parameters
875
 * @param  timeout - Preamble detection timeout, expressed in multiples of PAC size. The counter automatically adds 1 PAC
876
 *                   size to the value set. Min value that can be set is 1 (i.e. a timeout of 2 PAC size).
877
 *
878
 * output parameters
879
 *
880
 * no return value
881
 */
882
void dwt_setpreambledetecttimeout(uint16_t timeout);
883

  
884

  
885
/*! ------------------------------------------------------------------------------------------------------------------
886
 * @fn dwt_calibratesleepcnt()
887
 *
888
 * @brief calibrates the local oscillator as its frequency can vary between 7 and 13kHz depending on temp and voltage
889
 *
890
 * NOTE: this function needs to be run before dwt_configuresleepcnt, so that we know what the counter units are
891
 *
892
 * input parameters
893
 *
894
 * output parameters
895
 *
896
 * returns the number of XTAL/2 cycles per low-power oscillator cycle. LP OSC frequency = 19.2 MHz/return value
897
 */
898
uint16_t dwt_calibratesleepcnt(void);
899

  
900
/*! ------------------------------------------------------------------------------------------------------------------
901
 * @fn dwt_configuresleepcnt()
902
 *
903
 * @brief sets the sleep counter to new value, this function programs the high 16-bits of the 28-bit counter
904
 *
905
 * NOTE: this function needs to be run before dwt_configuresleep, also the SPI frequency has to be < 3MHz
906
 *
907
 * input parameters
908
 * @param sleepcnt - this it value of the sleep counter to program
909
 *
910
 * output parameters
911
 *
912
 * no return value
913
 */
914
 void dwt_configuresleepcnt(uint16_t sleepcnt);
915

  
916
 /*! ------------------------------------------------------------------------------------------------------------------
917
  * @fn dwt_configuresleep()
918
  *
919
  * @brief configures the device for both DEEP_SLEEP and SLEEP modes, and on-wake mode
920
  * i.e. before entering the sleep, the device should be programmed for TX or RX, then upon "waking up" the TX/RX settings
921
  * will be preserved and the device can immediately perform the desired action TX/RX
922
  *
923
  * NOTE: e.g. Tag operation - after deep sleep, the device needs to just load the TX buffer and send the frame
924
  *
925
  *
926
  *      mode: the array and LDE code (OTP/ROM) and LDO tune, and set sleep persist
927
  *      DWT_PRESRV_SLEEP 0x0100 - preserve sleep
928
  *      DWT_LOADOPSET    0x0080 - load operating parameter set on wakeup
929
  *      DWT_CONFIG       0x0040 - download the AON array into the HIF (configuration download)
930
  *      DWT_LOADEUI      0x0008
931
  *      DWT_GOTORX       0x0002
932
  *      DWT_TANDV        0x0001
933
  *
934
  *      wake: wake up parameters
935
  *      DWT_XTAL_EN      0x10 - keep XTAL running during sleep
936
  *      DWT_WAKE_SLPCNT  0x8 - wake up after sleep count
937
  *      DWT_WAKE_CS      0x4 - wake up on chip select
938
  *      DWT_WAKE_WK      0x2 - wake up on WAKEUP PIN
939
  *      DWT_SLP_EN       0x1 - enable sleep/deep sleep functionality
940
  *
941
  * input parameters
942
  * @param mode - config on-wake parameters
943
  * @param wake - config wake up parameters
944
  *
945
  * output parameters
946
  *
947
  * no return value
948
  */
949
void dwt_configuresleep(uint16_t mode, uint8_t wake);
950

  
951
/*! ------------------------------------------------------------------------------------------------------------------
952
 * @fn dwt_entersleep()
953
 *
954
 * @brief This function puts the device into deep sleep or sleep. dwt_configuresleep() should be called first
955
 * to configure the sleep and on-wake/wake-up parameters
956
 *
957
 * input parameters
958
 *
959
 * output parameters
960
 *
961
 * no return value
962
 */
963
void dwt_entersleep(void);
964

  
965
/*! ------------------------------------------------------------------------------------------------------------------
966
 * @fn dwt_entersleepaftertx(int enable)
967
 *
968
 * @brief sets the auto TX to sleep bit. This means that after a frame
969
 * transmission the device will enter deep sleep mode. The dwt_configuresleep() function
970
 * needs to be called before this to configure the on-wake settings
971
 *
972
 * NOTE: the IRQ line has to be low/inactive (i.e. no pending events)
973
 *
974
 * input parameters
975
 * @param enable - 1 to configure the device to enter deep sleep after TX, 0 - disables the configuration
976
 *
977
 * output parameters
978
 *
979
 * no return value
980
 */
981
void dwt_entersleepaftertx(int enable);
982

  
983
/*! ------------------------------------------------------------------------------------------------------------------
984
 * @fn dwt_spicswakeup()
985
 *
986
 * @brief wake up the device from sleep mode using the SPI read,
987
 * the device will wake up on chip select line going low if the line is held low for at least 500us.
988
 * To define the length depending on the time one wants to hold
989
 * the chip select line low, use the following formula:
990
 *
991
 *      length (bytes) = time (s) * byte_rate (Hz)
992
 *
993
 * where fastest byte_rate is spi_rate (Hz) / 8 if the SPI is sending the bytes back-to-back.
994
 * To save time and power, a system designer could determine byte_rate value more precisely.
995
 *
996
 * NOTE: Alternatively the device can be waken up with WAKE_UP pin if configured for that operation
997
 *
998
 * input parameters
999
 * @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
1000
 * @param length - this is the length of the dummy buffer
1001
 *
1002
 * output parameters
1003
 *
1004
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
1005
 */
1006
int dwt_spicswakeup(uint8_t *buff, uint16_t length);
1007

  
1008
/*! ------------------------------------------------------------------------------------------------------------------
1009
 * @fn dwt_setcallbacks()
1010
 *
1011
 * @brief This function is used to register the different callbacks called when one of the corresponding event occurs.
1012
 *
1013
 * NOTE: Callbacks can be undefined (set to NULL). In this case, dwt_isr() will process the event as usual but the 'null'
1014
 * callback will not be called.
1015
 *
1016
 * input parameters
1017
 * @param cbTxDone - the pointer to the TX confirmation event callback function
1018
 * @param cbRxOk - the pointer to the RX good frame event callback function
1019
 * @param cbRxTo - the pointer to the RX timeout events callback function
1020
 * @param cbRxErr - the pointer to the RX error events callback function
1021
 *
1022
 * output parameters
1023
 *
1024
 * no return value
1025
 */
1026
void dwt_setcallbacks(dwt_cb_t cbTxDone, dwt_cb_t cbRxOk, dwt_cb_t cbRxTo, dwt_cb_t cbRxErr);
1027

  
1028
/*! ------------------------------------------------------------------------------------------------------------------
1029
 * @fn dwt_checkirq()
1030
 *
1031
 * @brief This function checks if the IRQ line is active - this is used instead of interrupt handler
1032
 *
1033
 * input parameters
1034
 *
1035
 * output parameters
1036
 *
1037
 * return value is 1 if the IRQS bit is set and 0 otherwise
1038
 */
1039
uint8_t dwt_checkirq(void);
1040

  
1041
/*! ------------------------------------------------------------------------------------------------------------------
1042
 * @fn dwt_isr()
1043
 *
1044
 * @brief This is the DW1000's general Interrupt Service Routine. It will process/report the following events:
1045
 *          - RXFCG (through cbRxOk callback)
1046
 *          - TXFRS (through cbTxDone callback)
1047
 *          - RXRFTO/RXPTO (through cbRxTo callback)
1048
 *          - RXPHE/RXFCE/RXRFSL/RXSFDTO/AFFREJ/LDEERR (through cbRxTo cbRxErr)
1049
 *        For all events, corresponding interrupts are cleared and necessary resets are performed. In addition, in the RXFCG case,
1050
 *        received frame information and frame control are read before calling the callback. If double buffering is activated, it
1051
 *        will also toggle between reception buffers once the reception callback processing has ended.
1052
 *
1053
 *        /!\ This version of the ISR supports double buffering but does not support automatic RX re-enabling!
1054
 *
1055
 * NOTE:  In PC based system using (Cheetah or ARM) USB to SPI converter there can be no interrupts, however we still need something
1056
 *        to take the place of it and operate in a polled way. In an embedded system this function should be configured to be triggered
1057
 *        on any of the interrupts described above.
1058

  
1059
 * input parameters
1060
 *
1061
 * output parameters
1062
 *
1063
 * no return value
1064
 */
1065
void dwt_isr(void);
1066

  
1067
/*! ------------------------------------------------------------------------------------------------------------------
1068
 * @fn dwt_isr_lplisten()
1069
 *
1070
 * @brief This is the DW1000's Interrupt Service Routine to use when low-power listening scheme is implemented. It will
1071
 *        only process/report the RXFCG event (through cbRxOk callback).
1072
 *        It clears RXFCG interrupt and reads received frame information and frame control before calling the callback.
1073
 *
1074
 *        /!\ This version of the ISR is designed for single buffering case only!
1075
 *
1076
 * input parameters
1077
 *
1078
 * output parameters
1079
 *
1080
 * no return value
1081
 */
1082
void dwt_lowpowerlistenisr(void);
1083

  
1084
/*! ------------------------------------------------------------------------------------------------------------------
1085
 * @fn void dwt_setinterrupt()
1086
 *
1087
 * @brief This function enables the specified events to trigger an interrupt.
1088
 * The following events can be enabled:
1089
 * DWT_INT_TFRS         0x00000080          // frame sent
1090
 * DWT_INT_RFCG         0x00004000          // frame received with good CRC
1091
 * DWT_INT_RPHE         0x00001000          // receiver PHY header error
1092
 * DWT_INT_RFCE         0x00008000          // receiver CRC error
1093
 * DWT_INT_RFSL         0x00010000          // receiver sync loss error
1094
 * DWT_INT_RFTO         0x00020000          // frame wait timeout
1095
 * DWT_INT_RXPTO        0x00200000          // preamble detect timeout
1096
 * DWT_INT_SFDT         0x04000000          // SFD timeout
1097
 * DWT_INT_ARFE         0x20000000          // frame rejected (due to frame filtering configuration)
1098
 *
1099
 *
1100
 * input parameters:
1101
 * @param bitmask - sets the events which will generate interrupt
1102
 * @param enable - if set the interrupts are enabled else they are cleared
1103
 *
1104
 * output parameters
1105
 *
1106
 * no return value
1107
 */
1108
void dwt_setinterrupt( uint32_t bitmask, uint8_t enable);
1109

  
1110
/*! ------------------------------------------------------------------------------------------------------------------
1111
 * @fn dwt_setpanid()
1112
 *
1113
 * @brief This is used to set the PAN ID
1114
 *
1115
 * input parameters
1116
 * @param panID - this is the PAN ID
1117
 *
1118
 * output parameters
1119
 *
1120
 * no return value
1121
 */
1122
void dwt_setpanid(uint16_t panID);
1123

  
1124
/*! ------------------------------------------------------------------------------------------------------------------
1125
 * @fn dwt_setaddress16()
1126
 *
1127
 * @brief This is used to set 16-bit (short) address
1128
 *
1129
 * input parameters
1130
 * @param shortAddress - this sets the 16 bit short address
1131
 *
1132
 * output parameters
1133
 *
1134
 * no return value
1135
 */
1136
void dwt_setaddress16(uint16_t shortAddress);
1137

  
1138
/*! ------------------------------------------------------------------------------------------------------------------
1139
 * @fn dwt_seteui()
1140
 *
1141
 * @brief This is used to set the EUI 64-bit (long) address
1142
 *
1143
 * input parameters
1144
 * @param eui64 - this is the pointer to a buffer that contains the 64bit address
1145
 *
1146
 * output parameters
1147
 *
1148
 * no return value
1149
 */
1150
void dwt_seteui(uint8_t *eui64);
1151

  
1152
/*! ------------------------------------------------------------------------------------------------------------------
1153
 * @fn dwt_geteui()
1154
 *
1155
 * @brief This is used to get the EUI 64-bit from the DW1000
1156
 *
1157
 * input parameters
1158
 * @param eui64 - this is the pointer to a buffer that will contain the read 64-bit EUI value
1159
 *
1160
 * output parameters
1161
 *
1162
 * no return value
1163
 */
1164
void dwt_geteui(uint8_t *eui64);
1165

  
1166
/*! ------------------------------------------------------------------------------------------------------------------
1167
 * @fn dwt_otpread()
1168
 *
1169
 * @brief This is used to read the OTP data from given address into provided array
1170
 *
1171
 * input parameters
1172
 * @param address - this is the OTP address to read from
1173
 * @param array - this is the pointer to the array into which to read the data
1174
 * @param length - this is the number of 32 bit words to read (array needs to be at least this length)
1175
 *
1176
 * output parameters
1177
 *
1178
 * no return value
1179
 */
1180
void dwt_otpread(uint32_t address, uint32_t *array, uint8_t length);
1181

  
1182
/*! ------------------------------------------------------------------------------------------------------------------
1183
 * @fn dwt_enableframefilter()
1184
 *
1185
 * @brief This is used to enable the frame filtering - (the default option is to
1186
 * accept any data and ACK frames with correct destination address
1187
 *
1188
 * input parameters
1189
 * @param - bitmask - enables/disables the frame filtering options according to
1190
 *      DWT_FF_NOTYPE_EN        0x000   no frame types allowed
1191
 *      DWT_FF_COORD_EN         0x002   behave as coordinator (can receive frames with no destination address (PAN ID has to match))
1192
 *      DWT_FF_BEACON_EN        0x004   beacon frames allowed
1193
 *      DWT_FF_DATA_EN          0x008   data frames allowed
1194
 *      DWT_FF_ACK_EN           0x010   ack frames allowed
1195
 *      DWT_FF_MAC_EN           0x020   mac control frames allowed
1196
 *      DWT_FF_RSVD_EN          0x040   reserved frame types allowed
1197
 *
1198
 * output parameters
1199
 *
1200
 * no return value
1201
 */
1202
void dwt_enableframefilter(uint16_t bitmask);
1203

  
1204
/*! ------------------------------------------------------------------------------------------------------------------
1205
 * @fn dwt_enableautoack()
1206
 *
1207
 * @brief This call enables the auto-ACK feature. If the responseDelayTime (parameter) is 0, the ACK will be sent a.s.a.p.
1208
 * otherwise it will be sent with a programmed delay (in symbols), max is 255.
1209
 * NOTE: needs to have frame filtering enabled as well
1210
 *
1211
 * input parameters
1212
 * @param responseDelayTime - if non-zero the ACK is sent after this delay, max is 255.
1213
 *
1214
 * output parameters
1215
 *
1216
 * no return value
1217
 */
1218
void dwt_enableautoack(uint8_t responseDelayTime);
1219

  
1220
/*! ------------------------------------------------------------------------------------------------------------------
1221
 * @fn dwt_setrxaftertxdelay()
1222
 *
1223
 * @brief This sets the receiver turn on delay time after a transmission of a frame
1224
 *
1225
 * input parameters
1226
 * @param rxDelayTime - (20 bits) - the delay is in UWB microseconds
1227
 *
1228
 * output parameters
1229
 *
1230
 * no return value
1231
 */
1232
void dwt_setrxaftertxdelay(uint32_t rxDelayTime);
1233

  
1234
/*! ------------------------------------------------------------------------------------------------------------------
1235
 * @fn dwt_rxreset()
1236
 *
1237
 * @brief this function resets the receiver of the DW1000
1238
 *
1239
 * input parameters:
1240
 *
1241
 * output parameters
1242
 *
1243
 * no return value
1244
 */
1245
void dwt_rxreset(void);
1246

  
1247
/*! ------------------------------------------------------------------------------------------------------------------
1248
 * @fn dwt_softreset()
1249
 *
1250
 * @brief this function resets the DW1000
1251
 *
1252
 * input parameters:
1253
 *
1254
 * output parameters
1255
 *
1256
 * no return value
1257
 */
1258
void dwt_softreset(void) ;
1259

  
1260
/*! ------------------------------------------------------------------------------------------------------------------
1261
 * @fn dwt_readrxdata()
1262
 *
1263
 * @brief This is used to read the data from the RX buffer, from an offset location give by offset parameter
1264
 *
1265
 * input parameters
1266
 * @param buffer - the buffer into which the data will be read
1267
 * @param length - the length of data to read (in bytes)
1268
 * @param rxBufferOffset - the offset in the rx buffer from which to read the data
1269
 *
1270
 * output parameters
1271
 *
1272
 * no return value
1273
 */
1274
void dwt_readrxdata(uint8_t *buffer, uint16_t length, uint16_t rxBufferOffset);
1275

  
1276
/*! ------------------------------------------------------------------------------------------------------------------
1277
 * @fn dwt_readaccdata()
1278
 *
1279
 * @brief This is used to read the data from the Accumulator buffer, from an offset location give by offset parameter
1280
 *
1281
 * NOTE: Because of an internal memory access delay when reading the accumulator the first octet output is a dummy octet
1282
 *       that should be discarded. This is true no matter what sub-index the read begins at.
1283
 *
1284
 * input parameters
1285
 * @param buffer - the buffer into which the data will be read
1286
 * @param length - the length of data to read (in bytes)
1287
 * @param accOffset - the offset in the acc buffer from which to read the data
1288
 *
1289
 * output parameters
1290
 *
1291
 * no return value
1292
 */
1293
void dwt_readaccdata(uint8_t *buffer, uint16_t length, uint16_t rxBufferOffset);
1294

  
1295
/*! ------------------------------------------------------------------------------------------------------------------
1296
 * @fn dwt_readdiagnostics()
1297
 *
1298
 * @brief this function reads the RX signal quality diagnostic data
1299
 *
1300
 * input parameters
1301
 * @param diagnostics - diagnostic structure pointer, this will contain the diagnostic data read from the DW1000
1302
 *
1303
 * output parameters
1304
 *
1305
 * no return value
1306
 */
1307
void dwt_readdiagnostics(dwt_rxdiag_t * diagnostics);
1308

  
1309
/*! ------------------------------------------------------------------------------------------------------------------
1310
 * @fn dwt_loadopsettabfromotp()
1311
 *
1312
 * @brief This is used to select which Operational Parameter Set table to load from OTP memory
1313
 *
1314
 * input parameters
1315
 * @param ops_sel - Operational Parameter Set table to load:
1316
 *                  DWT_OPSET_64LEN = 0x0 - load the operational parameter set table for 64 length preamble configuration
1317
 *                  DWT_OPSET_TIGHT = 0x1 - load the operational parameter set table for tight xtal offsets (<1ppm)
1318
 *                  DWT_OPSET_DEFLT = 0x2 - load the default operational parameter set table (this is loaded from reset)
1319
 *
1320
 * output parameters
1321
 *
1322
 * no return value
1323
 */
1324
void dwt_loadopsettabfromotp(uint8_t ops_sel);
1325

  
1326
/*! ------------------------------------------------------------------------------------------------------------------
1327
 * @fn dwt_configeventcounters()
1328
 *
1329
 * @brief This is used to enable/disable the event counter in the IC
1330
 *
1331
 * input parameters
1332
 * @param - enable - 1 enables (and reset), 0 disables the event counters
1333
 * output parameters
1334
 *
1335
 * no return value
1336
 */
1337
void dwt_configeventcounters(int enable);
1338

  
1339
/*! ------------------------------------------------------------------------------------------------------------------
1340
 * @fn dwt_readeventcounters()
1341
 *
1342
 * @brief This is used to read the event counters in the IC
1343
 *
1344
 * input parameters
1345
 * @param counters - pointer to the dwt_deviceentcnts_t structure which will hold the read data
1346
 *
1347
 * output parameters
1348
 *
1349
 * no return value
1350
 */
1351
void dwt_readeventcounters(dwt_deviceentcnts_t *counters);
1352

  
1353
/*! ------------------------------------------------------------------------------------------------------------------
1354
 * @fn dwt_otpwriteandverify()
1355
 *
1356
 * @brief This is used to program 32-bit value into the DW1000 OTP memory.
1357
 *
1358
 * input parameters
1359
 * @param value - this is the 32-bit value to be programmed into OTP
1360
 * @param address - this is the 16-bit OTP address into which the 32-bit value is programmed
1361
 *
1362
 * output parameters
1363
 *
1364
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
1365
 */
1366
int dwt_otpwriteandverify(uint32_t value, uint16_t address);
1367

  
1368
/*! ------------------------------------------------------------------------------------------------------------------
1369
 * @fn dwt_setleds()
1370
 *
1371
 * @brief This is used to set up Tx/Rx GPIOs which could be used to control LEDs
1372
 * Note: not completely IC dependent, also needs board with LEDS fitted on right I/O lines
1373
 *       this function enables GPIOs 2 and 3 which are connected to LED3 and LED4 on EVB1000
1374
 *
1375
 * input parameters
1376
 * @param mode - this is a bit field interpreted as follows:
1377
 *          - bit 0: 1 to enable LEDs, 0 to disable them
1378
 *          - bit 1: 1 to make LEDs blink once on init. Only valid if bit 0 is set (enable LEDs)
1379
 *          - bit 2 to 7: reserved
1380
 *
1381
 * output parameters none
1382
 *
1383
 * no return value
1384
 */
1385
void dwt_setleds(uint8_t mode);
1386

  
1387
/*! ------------------------------------------------------------------------------------------------------------------
1388
 * @fn dwt_setxtaltrim()
1389
 *
1390
 * @brief This is used to adjust the crystal frequency
1391
 *
1392
 * input parameters:
1393
 * @param   value - crystal trim value (in range 0x0 to 0x1F) 31 steps (~1.5ppm per step)
1394
 *
1395
 * output parameters
1396
 *
1397
 * no return value
1398
 */
1399
void dwt_setxtaltrim(uint8_t value);
1400

  
1401
/*! ------------------------------------------------------------------------------------------------------------------
1402
 * @fn dwt_getinitxtaltrim()
1403
 *
1404
 * @brief This function returns the value of XTAL trim that has been applied during initialisation (dwt_init). This can
1405
 *        be either the value read in OTP memory or a default value.
1406
 *
1407
 * NOTE: The value returned by this function is the initial value only! It is not updated on dwt_setxtaltrim calls.
1408
 *
1409
 * input parameters
1410
 *
1411
 * output parameters
1412
 *
1413
 * returns the XTAL trim value set upon initialisation
1414
 */
1415
uint8_t dwt_getinitxtaltrim(void);
1416

  
1417
/*! ------------------------------------------------------------------------------------------------------------------
1418
 * @fn dwt_configcwmode()
1419
 *
1420
 * @brief this function sets the DW1000 to transmit cw signal at specific channel frequency
1421
 *
1422
 * input parameters:
1423
 * @param chan - specifies the operating channel (e.g. 1, 2, 3, 4, 5, 6 or 7)
1424
 *
1425
 * output parameters
1426
 *
1427
 * no return value
1428
 */
1429
void dwt_configcwmode(uint8_t chan);
1430

  
1431
/*! ------------------------------------------------------------------------------------------------------------------
1432
 * @fn dwt_configcontinuousframemode()
1433
 *
1434
 * @brief this function sets the DW1000 to continuous tx frame mode for regulatory approvals testing.
1435
 *
1436
 * input parameters:
1437
 * @param framerepetitionrate - This is a 32-bit value that is used to set the interval between transmissions.
1438
*  The minimum value is 4. The units are approximately 8 ns. (or more precisely 512/(499.2e6*128) seconds)).
1439
 *
1440
 * output parameters
1441
 *
1442
 * no return value
1443
 */
1444
void dwt_configcontinuousframemode(uint32_t framerepetitionrate);
1445

  
1446
/*! ------------------------------------------------------------------------------------------------------------------
1447
 * @fn dwt_readtempvbat()
1448
 *
1449
 * @brief this function reads the battery voltage and temperature of the MP
1450
 * The values read here will be the current values sampled by DW1000 AtoD converters.
1451
 * Note on Temperature: the temperature value needs to be converted to give the real temperature
1452
 * the formula is: 1.13 * reading - 113.0
1453
 * Note on Voltage: the voltage value needs to be converted to give the real voltage
1454
 * the formula is: 0.0057 * reading + 2.3
1455
 *
1456
 * NB: To correctly read the temperature this read should be done with xtal clock
1457
 * however that means that the receiver will be switched off, if receiver needs to be on then
1458
 * the timer is used to make sure the value is stable before reading
1459
 *
1460
 * input parameters:
1461
 * @param fastSPI - set to 1 if SPI rate > than 3MHz is used
1462
 *
1463
 * output parameters
1464
 *
1465
 * returns  (temp_raw<<8)|(vbat_raw)
1466
 */
1467
uint16_t dwt_readtempvbat(uint8_t fastSPI);
1468

  
1469
/*! ------------------------------------------------------------------------------------------------------------------
1470
 * @fn dwt_readwakeuptemp()
1471
 *
1472
 * @brief this function reads the temperature of the DW1000 that was sampled
1473
 * on waking from Sleep/Deepsleep. They are not current values, but read on last
1474
 * wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
1475
 *
1476
 * input parameters:
1477
 *
1478
 * output parameters:
1479
 *
1480
 * returns: 8-bit raw temperature sensor value
1481
 */
1482
uint8_t dwt_readwakeuptemp(void) ;
1483

  
1484
/*! ------------------------------------------------------------------------------------------------------------------
1485
 * @fn dwt_readwakeupvbat()
1486
 *
1487
 * @brief this function reads the battery voltage of the DW1000 that was sampled
1488
 * on waking from Sleep/Deepsleep. They are not current values, but read on last
1489
 * wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
... This diff was truncated because it exceeds the maximum size that can be displayed.

Also available in: Unified diff