Statistics
| Branch: | Tag: | Revision:

amiro-lld / drivers / DW1000 / v2 / decadriver / deca_device_api.h @ 22401187

History | View | Annotate | Download (83.1 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