Statistics
| Branch: | Tag: | Revision:

amiro-lld / include / DW1000 / v1 / alld_dw1000_v1.h @ 84450926

History | View | Annotate | Download (74.8 KB)

1 69a601a5 Cung Sang
/*
2
AMiRo-LLD is a compilation of low-level hardware drivers for the Autonomous Mini Robot (AMiRo) platform.
3 84450926 Thomas Schöpping
Copyright (C) 2016..2019  Thomas Schöpping et al.
4 69a601a5 Cung Sang

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

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

15
You should have received a copy of the GNU Lesser General Public License
16
along with this program.  If not, see <http://www.gnu.org/licenses/>.
17
*/
18
19
/*! ----------------------------------------------------------------------------
20
 * @file    deca_device_api.h
21
 * @brief   DW1000 API Functions
22
 *
23
 * @attention
24
 *
25
 * Copyright 2013 (c) Decawave Ltd, Dublin, Ireland.
26
 *
27
 * All rights reserved.
28
 *
29
 */
30
31
#ifndef __AMIROLLD_DW1000_V1_H
32
#define AMIROLLD_DW1000_V1_H
33
34
35
#include <amiro-lld.h>
36
#if (defined(AMIROLLD_CFG_DW1000) && (AMIROLLD_CFG_DW1000 == 1)) || defined(__DOXYGEN__)
37
38
#include <stddef.h>
39
#include <stdint.h>
40
#include <stdbool.h>
41
42
#define DW1000_DRIVER_VERSION               0x040005
43
#define DW1000_DEVICE_DRIVER_VER_STRING     "DW1000 Device Driver Version 04.00.05"
44
45
#ifndef DWT_NUM_DW_DEV
46
#define DWT_NUM_DW_DEV (1)
47
#endif
48
49
#define DWT_SUCCESS (0)
50
#define DWT_ERROR   (-1)
51
52
/**
53
 * Parameter declarations
54
 */
55
56
#define NUM_BR 3
57
#define NUM_PRF 2
58
#define NUM_PACS 4
59
#define NUM_BW 2            //2 bandwidths are supported
60
#define NUM_SFD 2           //supported number of SFDs - standard = 0, non-standard = 1
61
#define NUM_CH 6            //supported channels are 1, 2, 3, 4, 5, 7
62
#define NUM_CH_SUPPORTED 8  //supported channels are '0', 1, 2, 3, 4, 5, '6', 7
63
#define PCODES 25           //supported preamble codes
64
65 26dead12 Cung Sang
#define NUM_16M_OFFSET  (37)
66
#define NUM_16M_OFFSETWB  (68)
67
#define NUM_64M_OFFSET  (26)
68
#define NUM_64M_OFFSETWB  (59)
69
70
#define SPIBUFFLEN     (32)
71
72
73 69a601a5 Cung Sang
extern const uint8_t chan_idx[NUM_CH_SUPPORTED];
74 26dead12 Cung Sang
extern const uint16_t lde_replicaCoeff[PCODES];
75
extern const uint8_t chan_idxnb[NUM_CH_SUPPORTED];
76
extern const uint8_t chan_idxwb[NUM_CH_SUPPORTED];
77
extern const uint8_t range25cm16PRFnb[4][NUM_16M_OFFSET];
78
extern const uint8_t range25cm16PRFwb[2][NUM_16M_OFFSETWB];
79
extern const uint8_t range25cm64PRFnb[4][NUM_64M_OFFSET];
80
extern const uint8_t range25cm64PRFwb[2][NUM_64M_OFFSETWB];
81 69a601a5 Cung Sang
82
83
/**
84
 * @brief The DW1000 driver struct.
85
 */
86
typedef struct {
87
  apalSPIDriver_t* spid;    /**< @brief The SPI Driver */
88
  const apalControlGpio_t* gpio_exti;    /**< @brief The GPIO indicating external interrupt */
89
  const apalControlGpio_t* gpio_reset;  /**< @brief The GPIO indicating reset sig*/
90
//  const apalGpio_t* gpio_exti;    /**< @brief The GPIO indicating external interrupt */
91
//  const apalGpio_t* gpio_reset;  /**< @brief The GPIO indicating reset sig*/
92
} DW1000Driver;
93
94
95
#define DWT_TIME_UNITS  (1.0/499.2e6/128.0) //!< = 15.65e-12 s
96
97
#define DWT_DEVICE_ID   (0xDECA0130)        //!< DW1000 MP device ID
98
99
#define BUFFLEN         (4096+128)
100
101
//! constants for selecting the bit rate for data TX (and RX)
102
//! These are defined for write (with just a shift) the TX_FCTRL register
103
#define DWT_BR_110K     0   //!< UWB bit rate 110 kbits/s
104
#define DWT_BR_850K     1   //!< UWB bit rate 850 kbits/s
105
#define DWT_BR_6M8      2   //!< UWB bit rate 6.8 Mbits/s
106
107
//! constants for specifying the (Nominal) mean Pulse Repetition Frequency
108
//! These are defined for direct write (with a shift if necessary) to CHAN_CTRL and TX_FCTRL regs
109
#define DWT_PRF_16M     1   //!< UWB PRF 16 MHz
110
#define DWT_PRF_64M     2   //!< UWB PRF 64 MHz
111
112
//! constants for specifying Preamble Acquisition Chunk (PAC) Size in symbols
113
#define DWT_PAC8        0   //!< PAC  8 (recommended for RX of preamble length  128 and below
114
#define DWT_PAC16       1   //!< PAC 16 (recommended for RX of preamble length  256
115
#define DWT_PAC32       2   //!< PAC 32 (recommended for RX of preamble length  512
116
#define DWT_PAC64       3   //!< PAC 64 (recommended for RX of preamble length 1024 and up
117
118
//! constants for specifying TX Preamble length in symbols
119
//! These are defined to allow them be directly written into byte 2 of the TX_FCTRL register
120
//! (i.e. a four bit value destined for bits 20..18 but shifted left by 2 for byte alignment)
121
#define DWT_PLEN_4096   0x0C    //! Standard preamble length 4096 symbols
122
#define DWT_PLEN_2048   0x28    //! Non-standard preamble length 2048 symbols
123
#define DWT_PLEN_1536   0x18    //! Non-standard preamble length 1536 symbols
124
#define DWT_PLEN_1024   0x08    //! Standard preamble length 1024 symbols
125
#define DWT_PLEN_512    0x34    //! Non-standard preamble length 512 symbols
126
#define DWT_PLEN_256    0x24    //! Non-standard preamble length 256 symbols
127
#define DWT_PLEN_128    0x14    //! Non-standard preamble length 128 symbols
128
#define DWT_PLEN_64     0x04    //! Standard preamble length 64 symbols
129
130
#define DWT_SFDTOC_DEF              0x1041  // default SFD timeout value
131
132
#define DWT_PHRMODE_STD             0x0     // standard PHR mode
133
#define DWT_PHRMODE_EXT             0x3     // DW proprietary extended frames PHR mode
134
135
// Defined constants for "mode" bitmask parameter passed into dwt_starttx() function.
136
#define DWT_START_TX_IMMEDIATE      0
137
#define DWT_START_TX_DELAYED        1
138
#define DWT_RESPONSE_EXPECTED       2
139
140
#define DWT_START_RX_IMMEDIATE  0
141
#define DWT_START_RX_DELAYED    1    // Set up delayed RX, if "late" error triggers, then the RX will be enabled immediately
142
#define DWT_IDLE_ON_DLY_ERR     2    // If delayed RX failed due to "late" error then if this
143
                                     // flag is set the RX will not be re-enabled immediately, and device will be in IDLE when function exits
144
#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
145
                                     // re-enabling when receiving a frame in double buffer mode.
146
147
// Defined constants for "mode" bit field parameter passed to dwt_setleds() function.
148
#define DWT_LEDS_DISABLE     0x00
149
#define DWT_LEDS_ENABLE      0x01
150
#define DWT_LEDS_INIT_BLINK  0x02
151
152
//frame filtering configuration options
153
#define DWT_FF_NOTYPE_EN            0x000           // no frame types allowed (FF disabled)
154
#define DWT_FF_COORD_EN             0x002           // behave as coordinator (can receive frames with no dest address (PAN ID has to match))
155
#define DWT_FF_BEACON_EN            0x004           // beacon frames allowed
156
#define DWT_FF_DATA_EN              0x008           // data frames allowed
157
#define DWT_FF_ACK_EN               0x010           // ack frames allowed
158
#define DWT_FF_MAC_EN               0x020           // mac control frames allowed
159
#define DWT_FF_RSVD_EN              0x040           // reserved frame types allowed
160
161
//DW1000 interrupt events
162
#define DWT_INT_TFRS            0x00000080          // frame sent
163
#define DWT_INT_LDED            0x00000400          // micro-code has finished execution
164
#define DWT_INT_RFCG            0x00004000          // frame received with good CRC
165
#define DWT_INT_RPHE            0x00001000          // receiver PHY header error
166
#define DWT_INT_RFCE            0x00008000          // receiver CRC error
167
#define DWT_INT_RFSL            0x00010000          // receiver sync loss error
168
#define DWT_INT_RFTO            0x00020000          // frame wait timeout
169
#define DWT_INT_RXOVRR          0x00100000          // receiver overrun
170
#define DWT_INT_RXPTO           0x00200000          // preamble detect timeout
171
#define DWT_INT_SFDT            0x04000000          // SFD timeout
172
#define DWT_INT_ARFE            0x20000000          // frame rejected (due to frame filtering configuration)
173
174
175
//DW1000 SLEEP and WAKEUP configuration parameters
176
#define DWT_PRESRV_SLEEP 0x0100                      // PRES_SLEEP - on wakeup preserve sleep bit
177
#define DWT_LOADOPSET    0x0080                      // ONW_L64P - on wakeup load operating parameter set for 64 PSR
178
#define DWT_CONFIG       0x0040                      // ONW_LDC - on wakeup restore (load) the saved configurations (from AON array into HIF)
179
#define DWT_LOADEUI      0x0008                      // ONW_LEUI - on wakeup load EUI
180
#define DWT_RX_EN        0x0002                      // ONW_RX - on wakeup activate reception
181
#define DWT_TANDV        0x0001                      // ONW_RADC - on wakeup run ADC to sample temperature and voltage sensor values
182
183
#define DWT_XTAL_EN      0x10                       // keep XTAL running during sleep
184
#define DWT_WAKE_SLPCNT  0x8                        // wake up after sleep count
185
#define DWT_WAKE_CS      0x4                        // wake up on chip select
186
#define DWT_WAKE_WK      0x2                        // wake up on WAKEUP PIN
187
#define DWT_SLP_EN       0x1                        // enable sleep/deep sleep functionality
188
189
//DW1000 INIT configuration parameters
190
#define DWT_LOADUCODE     0x1
191
#define DWT_LOADNONE      0x0
192
193
//DW1000 OTP operating parameter set selection
194
#define DWT_OPSET_64LEN   0x0
195
#define DWT_OPSET_TIGHT   0x1
196
#define DWT_OPSET_DEFLT   0x2
197
198
// Call-back data RX frames flags
199
#define DWT_CB_DATA_RX_FLAG_RNG 0x1 // Ranging bit
200
201
202
// TX/RX call-back data
203
typedef struct
204
{
205
    uint32_t status;      //initial value of register as ISR is entered
206
    uint16_t datalength;  //length of frame
207
    uint8_t  fctrl[2];    //frame control bytes
208
    uint8_t  rx_flags;    //RX frame flags, see above
209
} dwt_cb_data_t;
210
211
// Call-back type for all events
212
typedef void (*dwt_cb_t)(const dwt_cb_data_t *);
213
214
215
// -------------------------------------------------------------------------------------------------------------------
216
// Structure to hold device data
217
typedef struct
218
{
219
    uint32_t      partID ;            // IC Part ID - read during initialisation
220
    uint32_t      lotID ;             // IC Lot ID - read during initialisation
221
    uint8_t       longFrames ;        // Flag in non-standard long frame mode
222
    uint8_t       otprev ;            // OTP revision number (read during initialisation)
223
    uint32_t      txFCTRL ;           // Keep TX_FCTRL register config
224
    uint8_t       init_xtrim;         // initial XTAL trim value read from OTP (or defaulted to mid-range if OTP not programmed)
225
    uint8_t       dblbuffon;          // Double RX buffer mode flag
226
    uint32_t      sysCFGreg ;         // Local copy of system config register
227
    uint16_t      sleep_mode;         // Used for automatic reloading of LDO tune and microcode at wake-up
228
    uint8_t       wait4resp ;         // wait4response was set with last TX start command
229
    dwt_cb_data_t cbData;             // Callback data structure
230
    dwt_cb_t      cbTxDone;           // Callback for TX confirmation event
231
    dwt_cb_t      cbRxOk;             // Callback for RX good frame event
232
    dwt_cb_t      cbRxTo;             // Callback for RX timeout events
233
    dwt_cb_t      cbRxErr;            // Callback for RX error events
234
    DW1000Driver  *driver;      // Reference to local hardware SPI, GPIO, ...
235
} dwt_local_data_t ;
236
237
/*! ------------------------------------------------------------------------------------------------------------------
238
 * Structure typedef: dwt_config_t
239
 *
240
 * Structure for setting device configuration via dwt_configure() function
241
 *
242
 */
243
typedef struct
244
{
245
    uint8_t chan ;           //!< channel number {1, 2, 3, 4, 5, 7 }
246
    uint8_t prf ;            //!< Pulse Repetition Frequency {DWT_PRF_16M or DWT_PRF_64M}
247
    uint8_t txPreambLength ; //!< DWT_PLEN_64..DWT_PLEN_4096
248
    uint8_t rxPAC ;          //!< Acquisition Chunk Size (Relates to RX preamble length)
249
    uint8_t txCode ;         //!< TX preamble code
250
    uint8_t rxCode ;         //!< RX preamble code
251
    uint8_t nsSFD ;          //!< Boolean should we use non-standard SFD for better performance
252
    uint8_t dataRate ;       //!< Data Rate {DWT_BR_110K, DWT_BR_850K or DWT_BR_6M8}
253
    uint8_t phrMode ;        //!< PHR mode {0x0 - standard DWT_PHRMODE_STD, 0x3 - extended frames DWT_PHRMODE_EXT}
254 26dead12 Cung Sang
    uint8_t smartPowerEn ;  //!< Smart Power enable / disable
255 69a601a5 Cung Sang
    uint16_t sfdTO ;         //!< SFD timeout value (in symbols)    
256
} dwt_config_t ;
257
258
259
typedef struct
260
{
261
    uint8_t   PGdly;
262
    //TX POWER
263
    //31:24     BOOST_0.125ms_PWR
264
    //23:16     BOOST_0.25ms_PWR-TX_SHR_PWR
265
    //15:8      BOOST_0.5ms_PWR-TX_PHR_PWR
266
    //7:0       DEFAULT_PWR-TX_DATA_PWR
267
    uint32_t  power;
268
} dwt_txconfig_t ;
269
270
271
typedef struct
272
{
273
274
    uint16_t      maxNoise ;          // LDE max value of noise
275
    uint16_t      firstPathAmp1 ;     // Amplitude at floor(index FP) + 1
276
    uint16_t      stdNoise ;          // Standard deviation of noise
277
    uint16_t      firstPathAmp2 ;     // Amplitude at floor(index FP) + 2
278
    uint16_t      firstPathAmp3 ;     // Amplitude at floor(index FP) + 3
279
    uint16_t      maxGrowthCIR ;      // Channel Impulse Response max growth CIR
280
    uint16_t      rxPreamCount ;      // Count of preamble symbols accumulated
281
    uint16_t      firstPath ;         // First path index (10.6 bits fixed point integer)
282
}dwt_rxdiag_t ;
283
284
285
typedef struct
286
{
287
    //all of the below are mapped to a 12-bit register in DW1000
288
    uint16_t PHE ;                    //number of received header errors
289
    uint16_t RSL ;                    //number of received frame sync loss events
290
    uint16_t CRCG ;                   //number of good CRC received frames
291
    uint16_t CRCB ;                   //number of bad CRC (CRC error) received frames
292
    uint16_t ARFE ;                   //number of address filter errors
293
    uint16_t OVER ;                   //number of receiver overflows (used in double buffer mode)
294
    uint16_t SFDTO ;                  //SFD timeouts
295
    uint16_t PTO ;                    //Preamble timeouts
296
    uint16_t RTO ;                    //RX frame wait timeouts
297
    uint16_t TXF ;                    //number of transmitted frames
298
    uint16_t HPW ;                    //half period warn
299
    uint16_t TXW ;                    //power up warn
300
301
} dwt_deviceentcnts_t ;
302
303
304
/********************************************************************************************************************/
305
/*                                                 REMOVED API LIST                                                 */
306
/********************************************************************************************************************/
307
/*
308
 * From version 4.0.0:
309
 *  - dwt_setGPIOforEXTTRX: Replaced by dwt_setlnapamode to get equivalent functionality.
310
 *  - dwt_setGPIOdirection: Renamed to dwt_setgpiodirection.
311
 *  - dwt_setGPIOvalue: Renamed to dwt_setgpiovalue.
312
 *  - dwt_setrxmode: Replaced by dwt_setsniffmode and dwt_setlowpowerlistening depending on the RX mode the user
313
 *    wants to set up.
314
 *  - dwt_checkoverrun: As automatic RX re-enabling is not supported anymore, this functions has become useless.
315
 *  - dwt_setautorxreenable: As automatic RX re-enabling is not supported anymore, this functions has become
316
 *    useless.
317
 *  - dwt_getrangebias: Range bias correction values are platform dependent and should therefore be managed at user
318
 *    application level.
319
 *  - dwt_xtaltrim: Renamed to dwt_setxtaltrim.
320
 *  - dwt_checkIRQ: Renamed to dwt_checkirq.
321
 *
322
 * From version 3.0.0:
323
 *  - dwt_getldotune: As LDO loading is now automatically managed by the driver, this function has become useless.
324
 *  - dwt_getotptxpower: TX power values and location in OTP memory are platform dependent and should therefore be
325
 *    managed at user application level.
326
 *  - dwt_readantennadelay: Antenna delay values and location in OTP memory are platform dependent and should
327
 *    therefore be managed at user application level.
328
 *  - dwt_readdignostics: Renamed to dwt_readdiagnostics.
329
 */
330
331
/********************************************************************************************************************/
332
/*                                                     API LIST                                                     */
333
/********************************************************************************************************************/
334
335
/*! ------------------------------------------------------------------------------------------------------------------
336
 * @fn dwt_setdevicedataptr()
337
 *
338
 * @brief This function sets the local data structure pointer to point to the structure in the local array as given by the index.
339
 *
340
 * input parameters
341
 * @param index    - selects the array object to point to. Must be within the array bounds, i.e. < DWT_NUM_DW_DEV
342
 *
343
 * output parameters
344
 *
345
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
346
 */
347
int dwt_setdevicedataptr(unsigned int index);
348
349
/*! ------------------------------------------------------------------------------------------------------------------
350
 * @fn dwt_getpartid()
351
 *
352
 * @brief This is used to return the read part ID of the device
353
 *
354
 * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
355
 *
356
 * input parameters
357
 *
358
 * output parameters
359
 *
360
 * returns the 32 bit part ID value as programmed in the factory
361
 */
362
uint32_t dwt_getpartid(void);
363
364
/*! ------------------------------------------------------------------------------------------------------------------
365
 * @fn dwt_getlotid()
366
 *
367
 * @brief This is used to return the read lot ID of the device
368
 *
369
 * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
370
 *
371
 * input parameters
372
 *
373
 * output parameters
374
 *
375
 * returns the 32 bit lot ID value as programmed in the factory
376
 */
377
uint32_t dwt_getlotid(void);
378
379
/*! ------------------------------------------------------------------------------------------------------------------
380
 * @fn dwt_readdevid()
381
 *
382
 * @brief This is used to return the read device type and revision information of the DW1000 device (MP part is 0xDECA0130)
383
 *
384
 * input parameters
385
 *
386
 * output parameters
387
 *
388
 * returns the read value which for DW1000 is 0xDECA0130
389
 */
390
uint32_t dwt_readdevid(void);
391
392
/*! ------------------------------------------------------------------------------------------------------------------
393
 * @fn dwt_otprevision()
394
 *
395
 * @brief This is used to return the read OTP revision
396
 *
397
 * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
398
 *
399
 * input parameters
400
 *
401
 * output parameters
402
 *
403
 * returns the read OTP revision value
404
 */
405
uint8_t dwt_otprevision(void);
406
407
/*! ------------------------------------------------------------------------------------------------------------------
408
 * @fn dwt_setfinegraintxseq()
409
 *
410
 * @brief This function enables/disables the fine grain TX sequencing (enabled by default).
411
 *
412
 * input parameters
413
 * @param enable - 1 to enable fine grain TX sequencing, 0 to disable it.
414
 *
415
 * output parameters none
416
 *
417
 * no return value
418
 */
419
void dwt_setfinegraintxseq(int enable);
420
421
/*! ------------------------------------------------------------------------------------------------------------------
422
 * @fn dwt_setlnapamode()
423
 *
424
 * @brief This is used to enable GPIO for external LNA or PA functionality - HW dependent, consult the DW1000 User Manual.
425
 *        This can also be used for debug as enabling TX and RX GPIOs is quite handy to monitor DW1000's activity.
426
 *
427
 * NOTE: Enabling PA functionality requires that fine grain TX sequencing is deactivated. This can be done using
428
 *       dwt_setfinegraintxseq().
429
 *
430
 * input parameters
431
 * @param lna - 1 to enable LNA functionality, 0 to disable it
432
 * @param pa - 1 to enable PA functionality, 0 to disable it
433
 *
434
 * output parameters
435
 *
436
 * no return value
437
 */
438
void dwt_setlnapamode(int lna, int pa);
439
440
/*! ------------------------------------------------------------------------------------------------------------------
441
 * @fn dwt_setgpiodirection()
442
 *
443
 * @brief This is used to set GPIO direction as an input (1) or output (0)
444
 *
445
 * input parameters
446
 * @param gpioNum    -   this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
447
 * @param direction  -   this sets the GPIO direction - see GxP0... GxP8 in the deca_regs.h file
448
 *
449
 * output parameters
450
 *
451
 * no return value
452
 */
453
void dwt_setgpiodirection(uint32_t gpioNum, uint32_t direction);
454
455
/*! ------------------------------------------------------------------------------------------------------------------
456
 * @fn dwt_setgpiovalue()
457
 *
458
 * @brief This is used to set GPIO value as (1) or (0) only applies if the GPIO is configured as output
459
 *
460
 * input parameters
461
 * @param gpioNum    -   this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
462
 * @param value  -   this sets the GPIO value - see GDP0... GDP8 in the deca_regs.h file
463
 *
464
 * output parameters
465
 *
466
 * no return value
467
 */
468
void dwt_setgpiovalue(uint32_t gpioNum, uint32_t value);
469
470
/*! ------------------------------------------------------------------------------------------------------------------
471
 * @fn dwt_initialise()
472
 *
473
 * @brief This function initiates communications with the DW1000 transceiver
474
 * and reads its DEV_ID register (address 0x00) to verify the IC is one supported
475
 * by this software (e.g. DW1000 32-bit device ID value is 0xDECA0130).  Then it
476
 * does any initial once only device configurations needed for use and initialises
477
 * as necessary any static data items belonging to this low-level driver.
478
 *
479
 * NOTES:
480
 * 1.this function needs to be run before dwt_configuresleep, also the SPI frequency has to be < 3MHz
481
 * 2.it also reads and applies LDO tune and crystal trim values from OTP memory
482
 *
483
 * input parameters
484
 * @param config    -   specifies what configuration to load
485
 *                  DWT_LOADUCODE     0x1 - load the LDE microcode from ROM - enabled accurate RX timestamp
486
 *                  DWT_LOADNONE      0x0 - do not load any values from OTP memory
487
 * @param drv       -   hardware specifc struct containg refernce to SPI, GPIO etc.
488
 *
489
 * output parameters
490
 *
491
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
492
 */
493 33f54213 Cung Sang
int dwt_initialise(uint16_t config, DW1000Driver* drv) ;
494 69a601a5 Cung Sang
495
/*! ------------------------------------------------------------------------------------------------------------------
496
 * @fn dwt_configure()
497
 *
498
 * @brief This function provides the main API for the configuration of the
499
 * DW1000 and this low-level driver.  The input is a pointer to the data structure
500
 * of type dwt_config_t that holds all the configurable items.
501
 * The dwt_config_t structure shows which ones are supported
502
 *
503
 * input parameters
504
 * @param config    -   pointer to the configuration structure, which contains the device configuration data.
505
 *
506
 * output parameters
507
 *
508
 * no return value
509
 */
510
void dwt_configure(dwt_config_t* config) ;
511
512
/*! ------------------------------------------------------------------------------------------------------------------
513
 * @fn dwt_configuretxrf()
514
 *
515
 * @brief This function provides the API for the configuration of the TX spectrum
516
 * including the power and pulse generator delay. The input is a pointer to the data structure
517
 * of type dwt_txconfig_t that holds all the configurable items.
518
 *
519
 * input parameters
520
 * @param config    -   pointer to the txrf configuration structure, which contains the tx rf config data
521
 *
522
 * output parameters
523
 *
524
 * no return value
525
 */
526
void dwt_configuretxrf(dwt_txconfig_t *config) ;
527
528
/*! ------------------------------------------------------------------------------------------------------------------
529
 * @fn dwt_setrxantennadelay()
530
 *
531
 * @brief This API function writes the antenna delay (in time units) to RX registers
532
 *
533
 * input parameters:
534
 * @param rxDelay - this is the total (RX) antenna delay value, which
535
 *                          will be programmed into the RX register
536
 *
537
 * output parameters
538
 *
539
 * no return value
540
 */
541
void dwt_setrxantennadelay(uint16_t antennaDly);
542
543
/*! ------------------------------------------------------------------------------------------------------------------
544
 * @fn dwt_settxantennadelay()
545
 *
546
 * @brief This API function writes the antenna delay (in time units) to TX registers
547
 *
548
 * input parameters:
549
 * @param txDelay - this is the total (TX) antenna delay value, which
550
 *                          will be programmed into the TX delay register
551
 *
552
 * output parameters
553
 *
554
 * no return value
555
 */
556
void dwt_settxantennadelay(uint16_t antennaDly);
557
558
/*! ------------------------------------------------------------------------------------------------------------------
559
 * @fn dwt_setsmarttxpower()
560
 *
561
 * @brief This call enables or disables the smart TX power feature.
562
 *
563
 * input parameters
564
 * @param enable - this enables or disables the TX smart power (1 = enable, 0 = disable)
565
 *
566
 * output parameters
567
 *
568
 * no return value
569
 */
570
void dwt_setsmarttxpower(int enable);
571
572
/*! ------------------------------------------------------------------------------------------------------------------
573
 * @fn dwt_writetxdata()
574
 *
575
 * @brief This API function writes the supplied TX data into the DW1000's
576
 * TX buffer.  The input parameters are the data length in bytes and a pointer
577
 * to those data bytes.
578
 *
579
 * input parameters
580
 * @param txFrameLength  - This is the total frame length, including the two byte CRC.
581
 *                         Note: this is the length of TX message (including the 2 byte CRC) - max is 1023
582
 *                         standard PHR mode allows up to 127 bytes
583
 *                         if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
584
 *                         see dwt_configure function
585
 * @param txFrameBytes   - Pointer to the user’s buffer containing the data to send.
586
 * @param txBufferOffset - This specifies an offset in the DW1000’s TX Buffer at which to start writing data.
587
 *
588
 * output parameters
589
 *
590
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
591
 */
592
int dwt_writetxdata(uint16_t txFrameLength, uint8_t *txFrameBytes, uint16_t txBufferOffset) ;
593
594
/*! ------------------------------------------------------------------------------------------------------------------
595
 * @fn dwt_writetxfctrl()
596
 *
597
 * @brief This API function configures the TX frame control register before the transmission of a frame
598
 *
599
 * input parameters:
600
 * @param txFrameLength - this is the length of TX message (including the 2 byte CRC) - max is 1023
601
 *                              NOTE: standard PHR mode allows up to 127 bytes
602
 *                              if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
603
 *                              see dwt_configure function
604
 * @param txBufferOffset - the offset in the tx buffer to start writing the data
605
 * @param ranging - 1 if this is a ranging frame, else 0
606
 *
607
 * output parameters
608
 *
609
 * no return value
610
 */
611
void dwt_writetxfctrl(uint16_t txFrameLength, uint16_t txBufferOffset, int ranging);
612
613
/*! ------------------------------------------------------------------------------------------------------------------
614
 * @fn dwt_starttx()
615
 *
616
 * @brief This call initiates the transmission, input parameter indicates which TX mode is used see below
617
 *
618
 * input parameters:
619
 * @param mode - is a bitmask for which the following values can be combined to define the operation
620
 *               DWT_START_TX_IMMEDIATE (0)            - to begin transmission immediatelty.
621
 *               DWT_START_TX_DELAYED   (to set bit 0) - to begin TX at pre-configured delay time
622
 *               DWT_RESPONSE_EXPECTED  (to set bit 1) - to turn the receiver on automatically (after the TX) after a pre-programmed delay
623
 * output parameters
624
 *
625
 * returns DWT_SUCCESS for success, or DWT_ERROR for error (e.g. a delayed transmission will fail if the delayed time has passed)
626
 */
627
int dwt_starttx(uint8_t mode) ;
628
629
/*! ------------------------------------------------------------------------------------------------------------------
630
 * @fn dwt_setdelayedtrxtime()
631
 *
632
 * @brief This API function configures the delayed transmit time or the delayed RX on time
633
 *
634
 * input parameters
635
 * @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,
636
 * or at which to turn on the receiver)
637
 *
638
 * output parameters none
639
 *
640
 * no return value
641
 */
642
void dwt_setdelayedtrxtime(uint32_t starttime) ;
643
644
/*! ------------------------------------------------------------------------------------------------------------------
645
 * @fn dwt_readtxtimestamp()
646
 *
647
 * @brief This is used to read the TX timestamp (adjusted with the programmed antenna delay)
648
 *
649
 * input parameters
650
 * @param timestamp - a pointer to a 5-byte buffer which will store the read TX timestamp time
651
 *
652
 * output parameters - the timestamp buffer will contain the value after the function call
653
 *
654
 * no return value
655
 */
656
void dwt_readtxtimestamp(uint8_t * timestamp);
657
658
/*! ------------------------------------------------------------------------------------------------------------------
659
 * @fn dwt_readtxtimestamphi32()
660
 *
661
 * @brief This is used to read the high 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
662
 *
663
 * input parameters
664
 *
665
 * output parameters
666
 *
667
 * returns high 32-bits of TX timestamp
668
 */
669
uint32_t dwt_readtxtimestamphi32(void);
670
671
/*! ------------------------------------------------------------------------------------------------------------------
672
 * @fn dwt_readtxtimestamplo32()
673
 *
674
 * @brief This is used to read the low 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
675
 *
676
 * input parameters
677
 *
678
 * output parameters
679
 *
680
 * returns low 32-bits of TX timestamp
681
 */
682
uint32_t dwt_readtxtimestamplo32(void);
683
684
/*! ------------------------------------------------------------------------------------------------------------------
685
 * @fn dwt_readrxtimestamp()
686
 *
687
 * @brief This is used to read the RX timestamp (adjusted time of arrival)
688
 *
689
 * input parameters
690
 * @param timestamp - a pointer to a 5-byte buffer which will store the read RX timestamp time
691
 *
692
 * output parameters - the timestamp buffer will contain the value after the function call
693
 *
694
 * no return value
695
 */
696
void dwt_readrxtimestamp(uint8_t * timestamp);
697
698
/*! ------------------------------------------------------------------------------------------------------------------
699
 * @fn dwt_readrxtimestamphi32()
700
 *
701
 * @brief This is used to read the high 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
702
 *
703
 * input parameters
704
 *
705
 * output parameters
706
 *
707
 * returns high 32-bits of RX timestamp
708
 */
709
uint32_t dwt_readrxtimestamphi32(void);
710
711
/*! ------------------------------------------------------------------------------------------------------------------
712
 * @fn dwt_readrxtimestamplo32()
713
 *
714
 * @brief This is used to read the low 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
715
 *
716
 * input parameters
717
 *
718
 * output parameters
719
 *
720
 * returns low 32-bits of RX timestamp
721
 */
722
uint32_t dwt_readrxtimestamplo32(void);
723
724
/*! ------------------------------------------------------------------------------------------------------------------
725
 * @fn dwt_readsystimestamphi32()
726
 *
727
 * @brief This is used to read the high 32-bits of the system time
728
 *
729
 * input parameters
730
 *
731
 * output parameters
732
 *
733
 * returns high 32-bits of system time timestamp
734
 */
735
uint32_t dwt_readsystimestamphi32(void);
736
737
/*! ------------------------------------------------------------------------------------------------------------------
738
 * @fn dwt_readsystime()
739
 *
740
 * @brief This is used to read the system time
741
 *
742
 * input parameters
743
 * @param timestamp - a pointer to a 5-byte buffer which will store the read system time
744
 *
745
 * output parameters
746
 * @param timestamp - the timestamp buffer will contain the value after the function call
747
 *
748
 * no return value
749
 */
750
void dwt_readsystime(uint8_t * timestamp);
751
752
/*! ------------------------------------------------------------------------------------------------------------------
753
 * @fn dwt_forcetrxoff()
754
 *
755
 * @brief This is used to turn off the transceiver
756
 *
757
 * input parameters
758
 *
759
 * output parameters
760
 *
761
 * no return value
762
 */
763
void dwt_forcetrxoff(void);
764
765
/*! ------------------------------------------------------------------------------------------------------------------
766
 * @fn dwt_syncrxbufptrs()
767
 *
768
 * @brief this function synchronizes rx buffer pointers
769
 * need to make sure that the host/IC buffer pointers are aligned before starting RX
770
 *
771
 * input parameters:
772
 *
773
 * output parameters
774
 *
775
 * no return value
776
 */
777
void dwt_syncrxbufptrs(void);
778
779
/*! ------------------------------------------------------------------------------------------------------------------
780
 * @fn dwt_rxenable()
781
 *
782
 * @brief This call turns on the receiver, can be immediate or delayed (depending on the mode parameter). In the case of a
783
 * "late" error the receiver will only be turned on if the DWT_IDLE_ON_DLY_ERR is not set.
784
 * The receiver will stay turned on, listening to any messages until
785
 * it either receives a good frame, an error (CRC, PHY header, Reed Solomon) or  it times out (SFD, Preamble or Frame).
786
 *
787
 * input parameters
788
 * @param mode - this can be one of the following allowed values:
789
 *
790
 * DWT_START_RX_IMMEDIATE      0 used to enbale receiver immediately
791
 * DWT_START_RX_DELAYED        1 used to set up delayed RX, if "late" error triggers, then the RX will be enabled immediately
792
 * (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
793
 * (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
794
 *                                               performing manual RX re-enabling in double buffering mode
795
 *
796
 * 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)
797
 */
798
int dwt_rxenable(int mode);
799
800
/*! ------------------------------------------------------------------------------------------------------------------
801
 * @fn dwt_setsniffmode()
802
 *
803
 * @brief enable/disable and configure SNIFF mode.
804
 *
805
 * SNIFF mode is a low-power reception mode where the receiver is sequenced on and off instead of being on all the time.
806
 * The time spent in each state (on/off) is specified through the parameters below.
807
 * See DW1000 User Manual section 4.5 "Low-Power SNIFF mode" for more details.
808
 *
809
 * input parameters:
810
 * @param enable - 1 to enable SNIFF mode, 0 to disable. When 0, all other parameters are not taken into account.
811
 * @param timeOn - duration of receiver ON phase, expressed in multiples of PAC size. The counter automatically adds 1 PAC
812
 *                 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.
813
 * @param timeOff - duration of receiver OFF phase, expressed in multiples of 128/125 µs (~1 µs). Max value is 255.
814
 *
815
 * output parameters
816
 *
817
 * no return value
818
 */
819
void dwt_setsniffmode(int enable, uint8_t timeOn, uint8_t timeOff);
820
821
/*! ------------------------------------------------------------------------------------------------------------------
822
 * @fn dwt_setlowpowerlistening()
823
 *
824
 * @brief enable/disable low-power listening mode.
825
 *
826
 * Low-power listening is a feature whereby the DW1000 is predominantly in the SLEEP state but wakes periodically, (after
827
 * this "long sleep"), for a very short time to sample the air for a preamble sequence. This preamble sampling "listening"
828
 * phase is actually two reception phases separated by a "short sleep" time. See DW1000 User Manual section "Low-Power
829
 * Listening" for more details.
830
 *
831
 * NOTE: Before enabling low-power listening, the following functions have to be called to fully configure it:
832
 *           - dwt_configuresleep() to configure long sleep phase. "mode" parameter should at least have DWT_PRESRV_SLEEP,
833
 *             DWT_CONFIG and DWT_RX_EN set and "wake" parameter should at least have both DWT_WAKE_SLPCNT and DWT_SLP_EN set.
834
 *           - dwt_calibratesleepcnt() and dwt_configuresleepcnt() to define the "long sleep" phase duration.
835
 *           - dwt_setsnoozetime() to define the "short sleep" phase duration.
836
 *           - dwt_setpreambledetecttimeout() to define the reception phases duration.
837
 *           - dwt_setinterrupt() to activate RX good frame interrupt (DWT_INT_RFCG) only.
838
 *       When configured, low-power listening mode can be triggered either by putting the DW1000 to sleep (using
839
 *       dwt_entersleep()) or by activating reception (using dwt_rxenable()).
840
 *
841
 *       Please refer to the low-power listening examples (examples 8a/8b accompanying the API distribution on Decawave's
842
 *       website). They form a working example code that shows how to use low-power listening correctly.
843
 *
844
 * input parameters:
845
 * @param enable - 1 to enable low-power listening, 0 to disable.
846
 *
847
 * output parameters
848
 *
849
 * no return value
850
 */
851
void dwt_setlowpowerlistening(int enable);
852
853
/*! ------------------------------------------------------------------------------------------------------------------
854
 * @fn dwt_setsnoozetime()
855
 *
856
 * @brief Set duration of "short sleep" phase when in low-power listening mode.
857
 *
858
 * input parameters:
859
 * @param snooze_time - "short sleep" phase duration, expressed in multiples of 512/19.2 µs (~26.7 µs). The counter
860
 *                      automatically adds 1 to the value set. The smallest working value that should be set is 1,
861
 *                      i.e. giving a snooze time of 2 units (or ~53 µs).
862
 *
863
 * output parameters
864
 *
865
 * no return value
866
 */
867
void dwt_setsnoozetime(uint8_t snooze_time);
868
869
/*! ------------------------------------------------------------------------------------------------------------------
870
 * @fn dwt_setdblrxbuffmode()
871
 *
872
 * @brief This call enables the double receive buffer mode
873
 *
874
 * input parameters
875
 * @param enable - 1 to enable, 0 to disable the double buffer mode
876
 *
877
 * output parameters
878
 *
879
 * no return value
880
 */
881
void dwt_setdblrxbuffmode(int enable);
882
883
/*! ------------------------------------------------------------------------------------------------------------------
884
 * @fn dwt_setrxtimeout()
885
 *
886
 * @brief This call enables RX timeout (SY_STAT_RFTO event)
887
 *
888
 * input parameters
889
 * @param time - how long the receiver remains on from the RX enable command
890
 *               The time parameter used here is in 1.0256 us (512/499.2MHz) units
891
 *               If set to 0 the timeout is disabled.
892
 *
893
 * output parameters
894
 *
895
 * no return value
896
 */
897
void dwt_setrxtimeout(uint16_t time);
898
899
/*! ------------------------------------------------------------------------------------------------------------------
900
 * @fn dwt_setpreambledetecttimeout()
901
 *
902
 * @brief This call enables preamble timeout (SY_STAT_RXPTO event)
903
 *
904
 * input parameters
905
 * @param  timeout - Preamble detection timeout, expressed in multiples of PAC size. The counter automatically adds 1 PAC
906
 *                   size to the value set. Min value that can be set is 1 (i.e. a timeout of 2 PAC size).
907
 *
908
 * output parameters
909
 *
910
 * no return value
911
 */
912
void dwt_setpreambledetecttimeout(uint16_t timeout);
913
914
915
/*! ------------------------------------------------------------------------------------------------------------------
916
 * @fn dwt_calibratesleepcnt()
917
 *
918
 * @brief calibrates the local oscillator as its frequency can vary between 7 and 13kHz depending on temp and voltage
919
 *
920
 * NOTE: this function needs to be run before dwt_configuresleepcnt, so that we know what the counter units are
921
 *
922
 * input parameters
923
 *
924
 * output parameters
925
 *
926
 * returns the number of XTAL/2 cycles per low-power oscillator cycle. LP OSC frequency = 19.2 MHz/return value
927
 */
928
uint16_t dwt_calibratesleepcnt(void);
929
930
/*! ------------------------------------------------------------------------------------------------------------------
931
 * @fn dwt_configuresleepcnt()
932
 *
933
 * @brief sets the sleep counter to new value, this function programs the high 16-bits of the 28-bit counter
934
 *
935
 * NOTE: this function needs to be run before dwt_configuresleep, also the SPI frequency has to be < 3MHz
936
 *
937
 * input parameters
938
 * @param sleepcnt - this it value of the sleep counter to program
939
 *
940
 * output parameters
941
 *
942
 * no return value
943
 */
944
 void dwt_configuresleepcnt(uint16_t sleepcnt);
945
946
 /*! ------------------------------------------------------------------------------------------------------------------
947
  * @fn dwt_configuresleep()
948
  *
949
  * @brief configures the device for both DEEP_SLEEP and SLEEP modes, and on-wake mode
950
  * i.e. before entering the sleep, the device should be programmed for TX or RX, then upon "waking up" the TX/RX settings
951
  * will be preserved and the device can immediately perform the desired action TX/RX
952
  *
953
  * NOTE: e.g. Tag operation - after deep sleep, the device needs to just load the TX buffer and send the frame
954
  *
955
  *
956
  *      mode: the array and LDE code (OTP/ROM) and LDO tune, and set sleep persist
957
  *      DWT_PRESRV_SLEEP 0x0100 - preserve sleep
958
  *      DWT_LOADOPSET    0x0080 - load operating parameter set on wakeup
959
  *      DWT_CONFIG       0x0040 - download the AON array into the HIF (configuration download)
960
  *      DWT_LOADEUI      0x0008
961
  *      DWT_GOTORX       0x0002
962
  *      DWT_TANDV        0x0001
963
  *
964
  *      wake: wake up parameters
965
  *      DWT_XTAL_EN      0x10 - keep XTAL running during sleep
966
  *      DWT_WAKE_SLPCNT  0x8 - wake up after sleep count
967
  *      DWT_WAKE_CS      0x4 - wake up on chip select
968
  *      DWT_WAKE_WK      0x2 - wake up on WAKEUP PIN
969
  *      DWT_SLP_EN       0x1 - enable sleep/deep sleep functionality
970
  *
971
  * input parameters
972
  * @param mode - config on-wake parameters
973
  * @param wake - config wake up parameters
974
  *
975
  * output parameters
976
  *
977
  * no return value
978
  */
979
void dwt_configuresleep(uint16_t mode, uint8_t wake);
980
981
/*! ------------------------------------------------------------------------------------------------------------------
982
 * @fn dwt_entersleep()
983
 *
984
 * @brief This function puts the device into deep sleep or sleep. dwt_configuresleep() should be called first
985
 * to configure the sleep and on-wake/wake-up parameters
986
 *
987
 * input parameters
988
 *
989
 * output parameters
990
 *
991
 * no return value
992
 */
993
void dwt_entersleep(void);
994
995
/*! ------------------------------------------------------------------------------------------------------------------
996
 * @fn dwt_entersleepaftertx(int enable)
997
 *
998
 * @brief sets the auto TX to sleep bit. This means that after a frame
999
 * transmission the device will enter deep sleep mode. The dwt_configuresleep() function
1000
 * needs to be called before this to configure the on-wake settings
1001
 *
1002
 * NOTE: the IRQ line has to be low/inactive (i.e. no pending events)
1003
 *
1004
 * input parameters
1005
 * @param enable - 1 to configure the device to enter deep sleep after TX, 0 - disables the configuration
1006
 *
1007
 * output parameters
1008
 *
1009
 * no return value
1010
 */
1011
void dwt_entersleepaftertx(int enable);
1012
1013
/*! ------------------------------------------------------------------------------------------------------------------
1014
 * @fn dwt_spicswakeup()
1015
 *
1016
 * @brief wake up the device from sleep mode using the SPI read,
1017
 * the device will wake up on chip select line going low if the line is held low for at least 500us.
1018
 * To define the length depending on the time one wants to hold
1019
 * the chip select line low, use the following formula:
1020
 *
1021
 *      length (bytes) = time (s) * byte_rate (Hz)
1022
 *
1023
 * where fastest byte_rate is spi_rate (Hz) / 8 if the SPI is sending the bytes back-to-back.
1024
 * To save time and power, a system designer could determine byte_rate value more precisely.
1025
 *
1026
 * NOTE: Alternatively the device can be waken up with WAKE_UP pin if configured for that operation
1027
 *
1028
 * input parameters
1029
 * @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
1030
 * @param length - this is the length of the dummy buffer
1031
 *
1032
 * output parameters
1033
 *
1034
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
1035
 */
1036
int dwt_spicswakeup(uint8_t *buff, uint16_t length);
1037
1038
/*! ------------------------------------------------------------------------------------------------------------------
1039
 * @fn dwt_setcallbacks()
1040
 *
1041
 * @brief This function is used to register the different callbacks called when one of the corresponding event occurs.
1042
 *
1043
 * NOTE: Callbacks can be undefined (set to NULL). In this case, dwt_isr() will process the event as usual but the 'null'
1044
 * callback will not be called.
1045
 *
1046
 * input parameters
1047
 * @param cbTxDone - the pointer to the TX confirmation event callback function
1048
 * @param cbRxOk - the pointer to the RX good frame event callback function
1049
 * @param cbRxTo - the pointer to the RX timeout events callback function
1050
 * @param cbRxErr - the pointer to the RX error events callback function
1051
 *
1052
 * output parameters
1053
 *
1054
 * no return value
1055
 */
1056
void dwt_setcallbacks(dwt_cb_t cbTxDone, dwt_cb_t cbRxOk, dwt_cb_t cbRxTo, dwt_cb_t cbRxErr);
1057
1058
/*! ------------------------------------------------------------------------------------------------------------------
1059
 * @fn dwt_checkirq()
1060
 *
1061
 * @brief This function checks if the IRQ line is active - this is used instead of interrupt handler
1062
 *
1063
 * input parameters
1064
 *
1065
 * output parameters
1066
 *
1067
 * return value is 1 if the IRQS bit is set and 0 otherwise
1068
 */
1069
uint8_t dwt_checkirq(void);
1070
1071
/*! ------------------------------------------------------------------------------------------------------------------
1072
 * @fn dwt_isr()
1073
 *
1074
 * @brief This is the DW1000's general Interrupt Service Routine. It will process/report the following events:
1075
 *          - RXFCG (through cbRxOk callback)
1076
 *          - TXFRS (through cbTxDone callback)
1077
 *          - RXRFTO/RXPTO (through cbRxTo callback)
1078
 *          - RXPHE/RXFCE/RXRFSL/RXSFDTO/AFFREJ/LDEERR (through cbRxTo cbRxErr)
1079
 *        For all events, corresponding interrupts are cleared and necessary resets are performed. In addition, in the RXFCG case,
1080
 *        received frame information and frame control are read before calling the callback. If double buffering is activated, it
1081
 *        will also toggle between reception buffers once the reception callback processing has ended.
1082
 *
1083
 *        /!\ This version of the ISR supports double buffering but does not support automatic RX re-enabling!
1084
 *
1085
 * NOTE:  In PC based system using (Cheetah or ARM) USB to SPI converter there can be no interrupts, however we still need something
1086
 *        to take the place of it and operate in a polled way. In an embedded system this function should be configured to be triggered
1087
 *        on any of the interrupts described above.
1088

1089
 * input parameters
1090
 *
1091
 * output parameters
1092
 *
1093
 * no return value
1094
 */
1095
void dwt_isr(void);
1096
1097
/*! ------------------------------------------------------------------------------------------------------------------
1098
 * @fn dwt_isr_lplisten()
1099
 *
1100
 * @brief This is the DW1000's Interrupt Service Routine to use when low-power listening scheme is implemented. It will
1101
 *        only process/report the RXFCG event (through cbRxOk callback).
1102
 *        It clears RXFCG interrupt and reads received frame information and frame control before calling the callback.
1103
 *
1104
 *        /!\ This version of the ISR is designed for single buffering case only!
1105
 *
1106
 * input parameters
1107
 *
1108
 * output parameters
1109
 *
1110
 * no return value
1111
 */
1112
void dwt_lowpowerlistenisr(void);
1113
1114
/*! ------------------------------------------------------------------------------------------------------------------
1115
 * @fn void dwt_setinterrupt()
1116
 *
1117
 * @brief This function enables the specified events to trigger an interrupt.
1118
 * The following events can be enabled:
1119
 * DWT_INT_TFRS         0x00000080          // frame sent
1120
 * DWT_INT_RFCG         0x00004000          // frame received with good CRC
1121
 * DWT_INT_RPHE         0x00001000          // receiver PHY header error
1122
 * DWT_INT_RFCE         0x00008000          // receiver CRC error
1123
 * DWT_INT_RFSL         0x00010000          // receiver sync loss error
1124
 * DWT_INT_RFTO         0x00020000          // frame wait timeout
1125
 * DWT_INT_RXPTO        0x00200000          // preamble detect timeout
1126
 * DWT_INT_SFDT         0x04000000          // SFD timeout
1127
 * DWT_INT_ARFE         0x20000000          // frame rejected (due to frame filtering configuration)
1128
 *
1129
 *
1130
 * input parameters:
1131
 * @param bitmask - sets the events which will generate interrupt
1132
 * @param enable - if set the interrupts are enabled else they are cleared
1133
 *
1134
 * output parameters
1135
 *
1136
 * no return value
1137
 */
1138
void dwt_setinterrupt( uint32_t bitmask, uint8_t enable);
1139
1140
/*! ------------------------------------------------------------------------------------------------------------------
1141
 * @fn dwt_setpanid()
1142
 *
1143
 * @brief This is used to set the PAN ID
1144
 *
1145
 * input parameters
1146
 * @param panID - this is the PAN ID
1147
 *
1148
 * output parameters
1149
 *
1150
 * no return value
1151
 */
1152
void dwt_setpanid(uint16_t panID);
1153
1154
/*! ------------------------------------------------------------------------------------------------------------------
1155
 * @fn dwt_setaddress16()
1156
 *
1157
 * @brief This is used to set 16-bit (short) address
1158
 *
1159
 * input parameters
1160
 * @param shortAddress - this sets the 16 bit short address
1161
 *
1162
 * output parameters
1163
 *
1164
 * no return value
1165
 */
1166
void dwt_setaddress16(uint16_t shortAddress);
1167
1168
/*! ------------------------------------------------------------------------------------------------------------------
1169
 * @fn dwt_seteui()
1170
 *
1171
 * @brief This is used to set the EUI 64-bit (long) address
1172
 *
1173
 * input parameters
1174
 * @param eui64 - this is the pointer to a buffer that contains the 64bit address
1175
 *
1176
 * output parameters
1177
 *
1178
 * no return value
1179
 */
1180
void dwt_seteui(uint8_t *eui64);
1181
1182
/*! ------------------------------------------------------------------------------------------------------------------
1183
 * @fn dwt_geteui()
1184
 *
1185
 * @brief This is used to get the EUI 64-bit from the DW1000
1186
 *
1187
 * input parameters
1188
 * @param eui64 - this is the pointer to a buffer that will contain the read 64-bit EUI value
1189
 *
1190
 * output parameters
1191
 *
1192
 * no return value
1193
 */
1194
void dwt_geteui(uint8_t *eui64);
1195
1196
/*! ------------------------------------------------------------------------------------------------------------------
1197
 * @fn dwt_otpread()
1198
 *
1199
 * @brief This is used to read the OTP data from given address into provided array
1200
 *
1201
 * input parameters
1202
 * @param address - this is the OTP address to read from
1203
 * @param array - this is the pointer to the array into which to read the data
1204
 * @param length - this is the number of 32 bit words to read (array needs to be at least this length)
1205
 *
1206
 * output parameters
1207
 *
1208
 * no return value
1209
 */
1210
void dwt_otpread(uint32_t address, uint32_t *array, uint8_t length);
1211
1212
/*! ------------------------------------------------------------------------------------------------------------------
1213
 * @fn dwt_enableframefilter()
1214
 *
1215
 * @brief This is used to enable the frame filtering - (the default option is to
1216
 * accept any data and ACK frames with correct destination address
1217
 *
1218
 * input parameters
1219
 * @param - bitmask - enables/disables the frame filtering options according to
1220
 *      DWT_FF_NOTYPE_EN        0x000   no frame types allowed
1221
 *      DWT_FF_COORD_EN         0x002   behave as coordinator (can receive frames with no destination address (PAN ID has to match))
1222
 *      DWT_FF_BEACON_EN        0x004   beacon frames allowed
1223
 *      DWT_FF_DATA_EN          0x008   data frames allowed
1224
 *      DWT_FF_ACK_EN           0x010   ack frames allowed
1225
 *      DWT_FF_MAC_EN           0x020   mac control frames allowed
1226
 *      DWT_FF_RSVD_EN          0x040   reserved frame types allowed
1227
 *
1228
 * output parameters
1229
 *
1230
 * no return value
1231
 */
1232
void dwt_enableframefilter(uint16_t bitmask);
1233
1234
/*! ------------------------------------------------------------------------------------------------------------------
1235
 * @fn dwt_enableautoack()
1236
 *
1237
 * @brief This call enables the auto-ACK feature. If the responseDelayTime (parameter) is 0, the ACK will be sent a.s.a.p.
1238
 * otherwise it will be sent with a programmed delay (in symbols), max is 255.
1239
 * NOTE: needs to have frame filtering enabled as well
1240
 *
1241
 * input parameters
1242
 * @param responseDelayTime - if non-zero the ACK is sent after this delay, max is 255.
1243
 *
1244
 * output parameters
1245
 *
1246
 * no return value
1247
 */
1248
void dwt_enableautoack(uint8_t responseDelayTime);
1249
1250
/*! ------------------------------------------------------------------------------------------------------------------
1251
 * @fn dwt_setrxaftertxdelay()
1252
 *
1253
 * @brief This sets the receiver turn on delay time after a transmission of a frame
1254
 *
1255
 * input parameters
1256
 * @param rxDelayTime - (20 bits) - the delay is in UWB microseconds
1257
 *
1258
 * output parameters
1259
 *
1260
 * no return value
1261
 */
1262
void dwt_setrxaftertxdelay(uint32_t rxDelayTime);
1263
1264
/*! ------------------------------------------------------------------------------------------------------------------
1265
 * @fn dwt_rxreset()
1266
 *
1267
 * @brief this function resets the receiver of the DW1000
1268
 *
1269
 * input parameters:
1270
 *
1271
 * output parameters
1272
 *
1273
 * no return value
1274
 */
1275
void dwt_rxreset(void);
1276
1277
/*! ------------------------------------------------------------------------------------------------------------------
1278
 * @fn dwt_softreset()
1279
 *
1280
 * @brief this function resets the DW1000
1281
 *
1282
 * input parameters:
1283
 *
1284
 * output parameters
1285
 *
1286
 * no return value
1287
 */
1288
void dwt_softreset(void) ;
1289
1290
/*! ------------------------------------------------------------------------------------------------------------------
1291
 * @fn dwt_readrxdata()
1292
 *
1293
 * @brief This is used to read the data from the RX buffer, from an offset location give by offset parameter
1294
 *
1295
 * input parameters
1296
 * @param buffer - the buffer into which the data will be read
1297
 * @param length - the length of data to read (in bytes)
1298
 * @param rxBufferOffset - the offset in the rx buffer from which to read the data
1299
 *
1300
 * output parameters
1301
 *
1302
 * no return value
1303
 */
1304
void dwt_readrxdata(uint8_t *buffer, uint16_t length, uint16_t rxBufferOffset);
1305
1306
/*! ------------------------------------------------------------------------------------------------------------------
1307
 * @fn dwt_readaccdata()
1308
 *
1309
 * @brief This is used to read the data from the Accumulator buffer, from an offset location give by offset parameter
1310
 *
1311
 * NOTE: Because of an internal memory access delay when reading the accumulator the first octet output is a dummy octet
1312
 *       that should be discarded. This is true no matter what sub-index the read begins at.
1313
 *
1314
 * input parameters
1315
 * @param buffer - the buffer into which the data will be read
1316
 * @param length - the length of data to read (in bytes)
1317
 * @param accOffset - the offset in the acc buffer from which to read the data
1318
 *
1319
 * output parameters
1320
 *
1321
 * no return value
1322
 */
1323
void dwt_readaccdata(uint8_t *buffer, uint16_t length, uint16_t rxBufferOffset);
1324
1325
/*! ------------------------------------------------------------------------------------------------------------------
1326
 * @fn dwt_readdiagnostics()
1327
 *
1328
 * @brief this function reads the RX signal quality diagnostic data
1329
 *
1330
 * input parameters
1331
 * @param diagnostics - diagnostic structure pointer, this will contain the diagnostic data read from the DW1000
1332
 *
1333
 * output parameters
1334
 *
1335
 * no return value
1336
 */
1337
void dwt_readdiagnostics(dwt_rxdiag_t * diagnostics);
1338
1339
/*! ------------------------------------------------------------------------------------------------------------------
1340
 * @fn dwt_loadopsettabfromotp()
1341
 *
1342
 * @brief This is used to select which Operational Parameter Set table to load from OTP memory
1343
 *
1344
 * input parameters
1345
 * @param ops_sel - Operational Parameter Set table to load:
1346
 *                  DWT_OPSET_64LEN = 0x0 - load the operational parameter set table for 64 length preamble configuration
1347
 *                  DWT_OPSET_TIGHT = 0x1 - load the operational parameter set table for tight xtal offsets (<1ppm)
1348
 *                  DWT_OPSET_DEFLT = 0x2 - load the default operational parameter set table (this is loaded from reset)
1349
 *
1350
 * output parameters
1351
 *
1352
 * no return value
1353
 */
1354
void dwt_loadopsettabfromotp(uint8_t ops_sel);
1355
1356
/*! ------------------------------------------------------------------------------------------------------------------
1357
 * @fn dwt_configeventcounters()
1358
 *
1359
 * @brief This is used to enable/disable the event counter in the IC
1360
 *
1361
 * input parameters
1362
 * @param - enable - 1 enables (and reset), 0 disables the event counters
1363
 * output parameters
1364
 *
1365
 * no return value
1366
 */
1367
void dwt_configeventcounters(int enable);
1368
1369
/*! ------------------------------------------------------------------------------------------------------------------
1370
 * @fn dwt_readeventcounters()
1371
 *
1372
 * @brief This is used to read the event counters in the IC
1373
 *
1374
 * input parameters
1375
 * @param counters - pointer to the dwt_deviceentcnts_t structure which will hold the read data
1376
 *
1377
 * output parameters
1378
 *
1379
 * no return value
1380
 */
1381
void dwt_readeventcounters(dwt_deviceentcnts_t *counters);
1382
1383
/*! ------------------------------------------------------------------------------------------------------------------
1384
 * @fn dwt_otpwriteandverify()
1385
 *
1386
 * @brief This is used to program 32-bit value into the DW1000 OTP memory.
1387
 *
1388
 * input parameters
1389
 * @param value - this is the 32-bit value to be programmed into OTP
1390
 * @param address - this is the 16-bit OTP address into which the 32-bit value is programmed
1391
 *
1392
 * output parameters
1393
 *
1394
 * returns DWT_SUCCESS for success, or DWT_ERROR for error
1395
 */
1396
int dwt_otpwriteandverify(uint32_t value, uint16_t address);
1397
1398
/*! ------------------------------------------------------------------------------------------------------------------
1399
 * @fn dwt_setleds()
1400
 *
1401
 * @brief This is used to set up Tx/Rx GPIOs which could be used to control LEDs
1402
 * Note: not completely IC dependent, also needs board with LEDS fitted on right I/O lines
1403
 *       this function enables GPIOs 2 and 3 which are connected to LED3 and LED4 on EVB1000
1404
 *
1405
 * input parameters
1406
 * @param mode - this is a bit field interpreted as follows:
1407
 *          - bit 0: 1 to enable LEDs, 0 to disable them
1408
 *          - bit 1: 1 to make LEDs blink once on init. Only valid if bit 0 is set (enable LEDs)
1409
 *          - bit 2 to 7: reserved
1410
 *
1411
 * output parameters none
1412
 *
1413
 * no return value
1414
 */
1415
void dwt_setleds(uint8_t mode);
1416
1417
/*! ------------------------------------------------------------------------------------------------------------------
1418
 * @fn dwt_setxtaltrim()
1419
 *
1420
 * @brief This is used to adjust the crystal frequency
1421
 *
1422
 * input parameters:
1423
 * @param   value - crystal trim value (in range 0x0 to 0x1F) 31 steps (~1.5ppm per step)
1424
 *
1425
 * output parameters
1426
 *
1427
 * no return value
1428
 */
1429
void dwt_setxtaltrim(uint8_t value);
1430
1431
/*! ------------------------------------------------------------------------------------------------------------------
1432
 * @fn dwt_getinitxtaltrim()
1433
 *
1434
 * @brief This function returns the value of XTAL trim that has been applied during initialisation (dwt_init). This can
1435
 *        be either the value read in OTP memory or a default value.
1436
 *
1437
 * NOTE: The value returned by this function is the initial value only! It is not updated on dwt_setxtaltrim calls.
1438
 *
1439
 * input parameters
1440
 *
1441
 * output parameters
1442
 *
1443
 * returns the XTAL trim value set upon initialisation
1444
 */
1445
uint8_t dwt_getinitxtaltrim(void);
1446
1447
/*! ------------------------------------------------------------------------------------------------------------------
1448
 * @fn dwt_configcwmode()
1449
 *
1450
 * @brief this function sets the DW1000 to transmit cw signal at specific channel frequency
1451
 *
1452
 * input parameters:
1453
 * @param chan - specifies the operating channel (e.g. 1, 2, 3, 4, 5, 6 or 7)
1454
 *
1455
 * output parameters
1456
 *
1457
 * no return value
1458
 */
1459
void dwt_configcwmode(uint8_t chan);
1460
1461
/*! ------------------------------------------------------------------------------------------------------------------
1462
 * @fn dwt_configcontinuousframemode()
1463
 *
1464
 * @brief this function sets the DW1000 to continuous tx frame mode for regulatory approvals testing.
1465
 *
1466
 * input parameters:
1467
 * @param framerepetitionrate - This is a 32-bit value that is used to set the interval between transmissions.
1468
*  The minimum value is 4. The units are approximately 8 ns. (or more precisely 512/(499.2e6*128) seconds)).
1469
 *
1470
 * output parameters
1471
 *
1472
 * no return value
1473
 */
1474
void dwt_configcontinuousframemode(uint32_t framerepetitionrate);
1475
1476
/*! ------------------------------------------------------------------------------------------------------------------
1477
 * @fn dwt_readtempvbat()
1478
 *
1479
 * @brief this function reads the battery voltage and temperature of the MP
1480
 * The values read here will be the current values sampled by DW1000 AtoD converters.
1481
 * Note on Temperature: the temperature value needs to be converted to give the real temperature
1482
 * the formula is: 1.13 * reading - 113.0
1483
 * Note on Voltage: the voltage value needs to be converted to give the real voltage
1484
 * the formula is: 0.0057 * reading + 2.3
1485
 *
1486
 * NB: To correctly read the temperature this read should be done with xtal clock
1487
 * however that means that the receiver will be switched off, if receiver needs to be on then
1488
 * the timer is used to make sure the value is stable before reading
1489
 *
1490
 * input parameters:
1491
 * @param fastSPI - set to 1 if SPI rate > than 3MHz is used
1492
 *
1493
 * output parameters
1494
 *
1495
 * returns  (temp_raw<<8)|(vbat_raw)
1496
 */
1497
uint16_t dwt_readtempvbat(uint8_t fastSPI);
1498
1499
/*! ------------------------------------------------------------------------------------------------------------------
1500
 * @fn dwt_readwakeuptemp()
1501
 *
1502
 * @brief this function reads the temperature of the DW1000 that was sampled
1503
 * on waking from Sleep/Deepsleep. They are not current values, but read on last
1504
 * wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
1505
 *
1506
 * input parameters:
1507
 *
1508
 * output parameters:
1509
 *
1510
 * returns: 8-bit raw temperature sensor value
1511
 */
1512
uint8_t dwt_readwakeuptemp(void) ;
1513
1514
/*! ------------------------------------------------------------------------------------------------------------------
1515
 * @fn dwt_readwakeupvbat()
1516
 *
1517
 * @brief this function reads the battery voltage of the DW1000 that was sampled
1518
 * on waking from Sleep/Deepsleep. They are not current values, but read on last
1519
 * wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
1520
 *
1521
 * input parameters:
1522
 *
1523
 * output parameters:
1524
 *
1525
 * returns: 8-bit raw battery voltage sensor value
1526
 */
1527
uint8_t dwt_readwakeupvbat(void) ;
1528
1529
/*! ------------------------------------------------------------------------------------------------------------------
1530
 * @fn dwt_calcbandwidthtempadj()
1531
 *
1532
 * @brief this function determines the corrected bandwidth setting (PG_DELAY register setting)
1533
 * of the DW1000 which changes over temperature.
1534
 *
1535
 * input parameters:
1536
 * @param target_count - uint16_t - the PG count target to reach in order to correct the bandwidth
1537
 *
1538
 * output parameters:
1539
 *
1540
 * returns: (uint32) The setting to be programmed into the PG_DELAY value
1541
 */
1542
uint32_t dwt_calcbandwidthtempadj(uint16_t target_count);
1543
1544
/*! ------------------------------------------------------------------------------------------------------------------
1545
 * @fn dwt_calcpowertempadj()
1546
 *
1547
 * @brief this function determines the corrected power setting (TX_POWER setting) for the
1548
 * DW1000 which changes over temperature.
1549
 *
1550
 * input parameters:
1551
 * @param channel - uint8_t - the channel at which compensation of power level will be applied
1552
 * @param ref_powerreg - uint32_t - the TX_POWER register value recorded when reference measurements were made
1553
 * @param current_temperature - double - the current ambient temperature in degrees Celcius
1554
 * @param reference_temperature - double - the temperature at which reference measurements were made
1555
 * output parameters: None
1556
 *
1557
 * returns: (uint32) The corrected TX_POWER register value
1558
 */
1559
uint32_t dwt_calcpowertempadj(uint8_t channel, uint32_t ref_powerreg, double current_temperature, double reference_temperature);
1560
1561
/*! ------------------------------------------------------------------------------------------------------------------
1562
 * @fn dwt_calcpgcount()
1563
 *
1564
 * @brief this function calculates the value in the pulse generator counter register (PGC_STATUS) for a given PG_DELAY
1565
 * This is used to take a reference measurement, and the value recorded as the reference is used to adjust the
1566
 * bandwidth of the device when the temperature changes.
1567
 *
1568
 * input parameters:
1569
 * @param pgdly - uint8_t - the PG_DELAY to set (to control bandwidth), and to find the corresponding count value for
1570
 * output parameters: None
1571
 *
1572
 * returns: (uint16) PGC_STATUS count value calculated from the provided PG_DELAY value - used as reference for later
1573
 * bandwidth adjustments
1574
 */
1575
uint16_t dwt_calcpgcount(uint8_t pgdly);
1576
1577
/*! ------------------------------------------------------------------------------------------------------------------
1578
 * @fn dwt_writetodevice()
1579
 *
1580
 * @brief  this function is used to write to the DW1000 device registers
1581
 * Notes:
1582
 *        1. Firstly we create a header (the first byte is a header byte)
1583
 *        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
1584
 *        b. set bit-7 (or with 0x80) for write operation
1585
 *        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
1586
 *
1587
 *        2. Write the header followed by the data bytes to the DW1000 device
1588
 *
1589
 *
1590
 * input parameters:
1591
 * @param recordNumber  - ID of register file or buffer being accessed
1592
 * @param index         - byte index into register file or buffer being accessed
1593
 * @param length        - number of bytes being written
1594
 * @param buffer        - pointer to buffer containing the 'length' bytes to be written
1595
 *
1596
 * output parameters
1597
 *
1598
 * no return value
1599
 */
1600
void dwt_writetodevice
1601
(
1602
    uint16_t      recordNumber,   // input parameter - ID of register file or buffer being accessed
1603
    uint16_t      index,          // input parameter - byte index into register file or buffer being accessed
1604
    uint32_t      length,         // input parameter - number of bytes being written
1605
    const uint8_t *buffer         // input parameter - pointer to buffer containing the 'length' bytes to be written
1606
) ;
1607
1608
/*! ------------------------------------------------------------------------------------------------------------------
1609
 * @fn dwt_readfromdevice()
1610
 *
1611
 * @brief  this function is used to read from the DW1000 device registers
1612
 * Notes:
1613
 *        1. Firstly we create a header (the first byte is a header byte)
1614
 *        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
1615
 *        b. set bit-7 (or with 0x80) for write operation
1616
 *        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
1617
 *
1618
 *        2. Write the header followed by the data bytes to the DW1000 device
1619
 *        3. Store the read data in the input buffer
1620
 *
1621
 * input parameters:
1622
 * @param recordNumber  - ID of register file or buffer being accessed
1623
 * @param index         - byte index into register file or buffer being accessed
1624
 * @param length        - number of bytes being read
1625
 * @param buffer        - pointer to buffer in which to return the read data.
1626
 *
1627
 * output parameters
1628
 *
1629
 * no return value
1630
 */
1631
void dwt_readfromdevice
1632
(
1633
    uint16_t  recordNumber,       // input parameter - ID of register file or buffer being accessed
1634
    uint16_t  index,              // input parameter - byte index into register file or buffer being accessed
1635
    uint32_t  length,             // input parameter - number of bytes being read
1636
    uint8_t   *buffer             // input parameter - pointer to buffer in which to return the read data.
1637
) ;
1638
1639
/*! ------------------------------------------------------------------------------------------------------------------
1640
 * @fn dwt_read32bitoffsetreg()
1641
 *
1642
 * @brief  this function is used to read 32-bit value from the DW1000 device registers
1643
 *
1644
 * input parameters:
1645
 * @param regFileID - ID of register file or buffer being accessed
1646
 * @param regOffset - the index into register file or buffer being accessed
1647
 *
1648
 * output parameters
1649
 *
1650
 * returns 32 bit register value
1651
 */
1652
uint32_t dwt_read32bitoffsetreg(int regFileID, int regOffset) ;
1653
1654
/*! ------------------------------------------------------------------------------------------------------------------
1655
 * @fn dwt_write32bitoffsetreg()
1656
 *
1657
 * @brief  this function is used to write 32-bit value to the DW1000 device registers
1658
 *
1659
 * input parameters:
1660
 * @param regFileID - ID of register file or buffer being accessed
1661
 * @param regOffset - the index into register file or buffer being accessed
1662
 * @param regval    - the value to write
1663
 *
1664
 * output parameters
1665
 *
1666
 * no return value
1667
 */
1668
void dwt_write32bitoffsetreg(int regFileID, int regOffset, uint32_t regval);
1669
1670
#define dwt_write32bitreg(x,y)  dwt_write32bitoffsetreg(x,0,y)
1671
#define dwt_read32bitreg(x)     dwt_read32bitoffsetreg(x,0)
1672
1673
/*! ------------------------------------------------------------------------------------------------------------------
1674
 * @fn dwt_read16bitoffsetreg()
1675
 *
1676
 * @brief  this function is used to read 16-bit value from the DW1000 device registers
1677
 *
1678
 * input parameters:
1679
 * @param regFileID - ID of register file or buffer being accessed
1680
 * @param regOffset - the index into register file or buffer being accessed
1681
 *
1682
 * output parameters
1683
 *
1684
 * returns 16 bit register value
1685
 */
1686
uint16_t dwt_read16bitoffsetreg(int regFileID, int regOffset);
1687
1688
/*! ------------------------------------------------------------------------------------------------------------------
1689
 * @fn dwt_write16bitoffsetreg()
1690
 *
1691
 * @brief  this function is used to write 16-bit value to the DW1000 device registers
1692
 *
1693
 * input parameters:
1694
 * @param regFileID - ID of register file or buffer being accessed
1695
 * @param regOffset - the index into register file or buffer being accessed
1696
 * @param regval    - the value to write
1697
 *
1698
 * output parameters
1699
 *
1700
 * no return value
1701
 */
1702
void dwt_write16bitoffsetreg(int regFileID, int regOffset, uint16_t regval) ;
1703
1704
/*! ------------------------------------------------------------------------------------------------------------------
1705
 * @fn dwt_read8bitoffsetreg()
1706
 *
1707
 * @brief  this function is used to read an 8-bit value from the DW1000 device registers
1708
 *
1709
 * input parameters:
1710
 * @param regFileID - ID of register file or buffer being accessed
1711
 * @param regOffset - the index into register file or buffer being accessed
1712
 *
1713
 * output parameters
1714
 *
1715
 * returns 8-bit register value
1716
 */
1717
uint8_t dwt_read8bitoffsetreg(int regFileID, int regOffset);
1718
1719
/*! ------------------------------------------------------------------------------------------------------------------
1720
 * @fn dwt_write8bitoffsetreg()
1721
 *
1722
 * @brief  this function is used to write an 8-bit value to the DW1000 device registers
1723
 *
1724
 * input parameters:
1725
 * @param regFileID - ID of register file or buffer being accessed
1726
 * @param regOffset - the index into register file or buffer being accessed
1727
 * @param regval    - the value to write
1728
 *
1729
 * output parameters
1730
 *
1731
 * no return value
1732
 */
1733
void dwt_write8bitoffsetreg(int regFileID, int regOffset, uint8_t regval);
1734
1735
1736
/****************************************************************************************************************************************************
1737
 *
1738
 * Declaration of platform-dependent lower level functions.
1739
 *
1740
 ****************************************************************************************************************************************************/
1741
1742
1743
// ---------------------------------------------------------------------------
1744
//
1745
// NB: The purpose of the deca_mutex.c file is to provide for microprocessor interrupt enable/disable, this is used for
1746
//     controlling mutual exclusion from critical sections in the code where interrupts and background
1747
//     processing may interact.  The code using this is kept to a minimum and the disabling time is also
1748
//     kept to a minimum, so blanket interrupt disable may be the easiest way to provide this.  But at a
1749
//     minimum those interrupts coming from the decawave device should be disabled/re-enabled by this activity.
1750
//
1751
//     In porting this to a particular microprocessor, the implementer may choose to use #defines here
1752
//     to map these calls transparently to the target system.  Alternatively the appropriate code may
1753
//     be embedded in the functions provided in the deca_irq.c file.
1754
//
1755
// ---------------------------------------------------------------------------
1756
1757
typedef int decaIrqStatus_t ; // Type for remembering IRQ status
1758
1759
1760
/*! ------------------------------------------------------------------------------------------------------------------
1761
 * @fn decamutexon()
1762
 *
1763
 * @brief This function should disable interrupts. This is called at the start of a critical section
1764
 * It returns the IRQ state before disable, this value is used to re-enable in decamutexoff call
1765
 *
1766
 * Note: The body of this function is platform specific
1767
 *
1768
 * input parameters:
1769
 *
1770
 * output parameters
1771
 *
1772
 * returns the state of the DW1000 interrupt
1773
 */
1774
decaIrqStatus_t decamutexon(void) ;
1775
1776
/*! ------------------------------------------------------------------------------------------------------------------
1777
 * @fn decamutexoff()
1778
 *
1779
 * @brief This function should re-enable interrupts, or at least restore their state as returned(&saved) by decamutexon
1780
 * This is called at the end of a critical section
1781
 *
1782
 * Note: The body of this function is platform specific
1783
 *
1784
 * input parameters:
1785
 * @param s - the state of the DW1000 interrupt as returned by decamutexon
1786
 *
1787
 * output parameters
1788
 *
1789
 * returns the state of the DW1000 interrupt
1790
 */
1791
void decamutexoff(decaIrqStatus_t s) ;
1792
1793
/*! ------------------------------------------------------------------------------------------------------------------
1794
 * @fn deca_sleep()
1795
 *
1796
 * @brief Wait for a given amount of time.
1797
 * NB: The body of this function is platform specific
1798
 *
1799
 * input parameters:
1800
 * @param time_ms - time to wait in milliseconds
1801
 *
1802
 * output parameters
1803
 *
1804
 * no return value
1805
 */
1806
void deca_sleep(unsigned int time_ms);
1807
void Sleep(unsigned int time_ms);
1808
1809
1810
void port_EnableEXT_IRQ(void);
1811
void port_DisableEXT_IRQ(void);
1812 33f54213 Cung Sang
decaIrqStatus_t port_GetEXT_IRQStatus(void);
1813 69a601a5 Cung Sang
1814
void port_set_dw1000_slowrate(void);
1815
void port_set_dw1000_fastrate(void);
1816
void port_wakeup_dw1000_fast(void);
1817
uint32_t portGetTickCnt(void);
1818
1819
1820
/**
1821
 * @brief   Pad specific IRQn handler. modify it if the PIN no. is changed
1822
 */
1823
#define DW1000_EXTI_IRQn    EXTI15_10_IRQn
1824
1825
1826
#endif /* defined(AMIROLLD_CFG_DW1000) && (AMIROLLD_CFG_DW1000 == 1) */
1827
1828
#endif //AMIROLLD_DW1000_V1_H