Alejandro Ungria Hirte
/
GA-Test_copy
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Diff: decadriver/deca_device_api.h
- Revision:
- 0:a3b83d366423
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/decadriver/deca_device_api.h Wed Dec 06 21:35:45 2017 +0000
@@ -0,0 +1,1745 @@
+/*! ----------------------------------------------------------------------------
+ * @file deca_device_api.h
+ * @brief DW1000 API Functions
+ *
+ * @attention
+ *
+ * Copyright 2013 (c) Decawave Ltd, Dublin, Ireland.
+ *
+ * All rights reserved.
+ *
+ */
+
+#ifndef _DECA_DEVICE_API_H_
+#define _DECA_DEVICE_API_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+#ifndef uint8
+#ifndef _DECA_UINT8_
+#define _DECA_UINT8_
+typedef unsigned char uint8;
+#endif
+#endif
+
+#ifndef uint16
+#ifndef _DECA_UINT16_
+#define _DECA_UINT16_
+typedef unsigned short uint16;
+#endif
+#endif
+
+#ifndef uint32
+#ifndef _DECA_UINT32_
+#define _DECA_UINT32_
+typedef unsigned long uint32;
+#endif
+#endif
+
+#ifndef int8
+#ifndef _DECA_INT8_
+#define _DECA_INT8_
+typedef signed char int8;
+#endif
+#endif
+
+#ifndef int16
+#ifndef _DECA_INT16_
+#define _DECA_INT16_
+typedef signed short int16;
+#endif
+#endif
+
+#ifndef int32
+#ifndef _DECA_INT32_
+#define _DECA_INT32_
+typedef signed long int32;
+#endif
+#endif
+
+#define DWT_SUCCESS (0)
+#define DWT_ERROR (-1)
+
+#define DWT_TIME_UNITS (1.0/499.2e6/128.0) //!< = 15.65e-12 s
+
+#define DWT_DEVICE_ID (0xDECA0130) //!< DW1000 MP device ID
+
+//! constants for selecting the bit rate for data TX (and RX)
+//! These are defined for write (with just a shift) the TX_FCTRL register
+#define DWT_BR_110K 0 //!< UWB bit rate 110 kbits/s
+#define DWT_BR_850K 1 //!< UWB bit rate 850 kbits/s
+#define DWT_BR_6M8 2 //!< UWB bit rate 6.8 Mbits/s
+
+//! constants for specifying the (Nominal) mean Pulse Repetition Frequency
+//! These are defined for direct write (with a shift if necessary) to CHAN_CTRL and TX_FCTRL regs
+#define DWT_PRF_16M 1 //!< UWB PRF 16 MHz
+#define DWT_PRF_64M 2 //!< UWB PRF 64 MHz
+
+//! constants for specifying Preamble Acquisition Chunk (PAC) Size in symbols
+#define DWT_PAC8 0 //!< PAC 8 (recommended for RX of preamble length 128 and below
+#define DWT_PAC16 1 //!< PAC 16 (recommended for RX of preamble length 256
+#define DWT_PAC32 2 //!< PAC 32 (recommended for RX of preamble length 512
+#define DWT_PAC64 3 //!< PAC 64 (recommended for RX of preamble length 1024 and up
+
+//! constants for specifying TX Preamble length in symbols
+//! These are defined to allow them be directly written into byte 2 of the TX_FCTRL register
+//! (i.e. a four bit value destined for bits 20..18 but shifted left by 2 for byte alignment)
+#define DWT_PLEN_4096 0x0C //! Standard preamble length 4096 symbols
+#define DWT_PLEN_2048 0x28 //! Non-standard preamble length 2048 symbols
+#define DWT_PLEN_1536 0x18 //! Non-standard preamble length 1536 symbols
+#define DWT_PLEN_1024 0x08 //! Standard preamble length 1024 symbols
+#define DWT_PLEN_512 0x34 //! Non-standard preamble length 512 symbols
+#define DWT_PLEN_256 0x24 //! Non-standard preamble length 256 symbols
+#define DWT_PLEN_128 0x14 //! Non-standard preamble length 128 symbols
+#define DWT_PLEN_64 0x04 //! Standard preamble length 64 symbols
+
+#define DWT_SFDTOC_DEF 0x1041 // default SFD timeout value
+
+#define DWT_PHRMODE_STD 0x0 // standard PHR mode
+#define DWT_PHRMODE_EXT 0x3 // DW proprietary extended frames PHR mode
+
+// Defined constants for "mode" bitmask parameter passed into dwt_starttx() function.
+#define DWT_START_TX_IMMEDIATE 0
+#define DWT_START_TX_DELAYED 1
+#define DWT_RESPONSE_EXPECTED 2
+
+#define DWT_START_RX_IMMEDIATE 0
+#define DWT_START_RX_DELAYED 1 // Set up delayed RX, if "late" error triggers, then the RX will be enabled immediately
+#define DWT_IDLE_ON_DLY_ERR 2 // If delayed RX failed due to "late" error then if this
+ // flag is set the RX will not be re-enabled immediately, and device will be in IDLE when function exits
+#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
+ // re-enabling when receiving a frame in double buffer mode.
+
+// Defined constants for "mode" bit field parameter passed to dwt_setleds() function.
+#define DWT_LEDS_DISABLE 0x00
+#define DWT_LEDS_ENABLE 0x01
+#define DWT_LEDS_INIT_BLINK 0x02
+
+//frame filtering configuration options
+#define DWT_FF_NOTYPE_EN 0x000 // no frame types allowed (FF disabled)
+#define DWT_FF_COORD_EN 0x002 // behave as coordinator (can receive frames with no dest address (PAN ID has to match))
+#define DWT_FF_BEACON_EN 0x004 // beacon frames allowed
+#define DWT_FF_DATA_EN 0x008 // data frames allowed
+#define DWT_FF_ACK_EN 0x010 // ack frames allowed
+#define DWT_FF_MAC_EN 0x020 // mac control frames allowed
+#define DWT_FF_RSVD_EN 0x040 // reserved frame types allowed
+
+//DW1000 interrupt events
+#define DWT_INT_TFRS 0x00000080 // frame sent
+#define DWT_INT_LDED 0x00000400 // micro-code has finished execution
+#define DWT_INT_RFCG 0x00004000 // frame received with good CRC
+#define DWT_INT_RPHE 0x00001000 // receiver PHY header error
+#define DWT_INT_RFCE 0x00008000 // receiver CRC error
+#define DWT_INT_RFSL 0x00010000 // receiver sync loss error
+#define DWT_INT_RFTO 0x00020000 // frame wait timeout
+#define DWT_INT_RXOVRR 0x00100000 // receiver overrun
+#define DWT_INT_RXPTO 0x00200000 // preamble detect timeout
+#define DWT_INT_SFDT 0x04000000 // SFD timeout
+#define DWT_INT_ARFE 0x20000000 // frame rejected (due to frame filtering configuration)
+
+
+//DW1000 SLEEP and WAKEUP configuration parameters
+#define DWT_PRESRV_SLEEP 0x0100 // PRES_SLEEP - on wakeup preserve sleep bit
+#define DWT_LOADOPSET 0x0080 // ONW_L64P - on wakeup load operating parameter set for 64 PSR
+#define DWT_CONFIG 0x0040 // ONW_LDC - on wakeup restore (load) the saved configurations (from AON array into HIF)
+#define DWT_RX_EN 0x0002 // ONW_RX - on wakeup activate reception
+#define DWT_TANDV 0x0001 // ONW_RADC - on wakeup run ADC to sample temperature and voltage sensor values
+
+#define DWT_XTAL_EN 0x10 // keep XTAL running during sleep
+#define DWT_WAKE_SLPCNT 0x8 // wake up after sleep count
+#define DWT_WAKE_CS 0x4 // wake up on chip select
+#define DWT_WAKE_WK 0x2 // wake up on WAKEUP PIN
+#define DWT_SLP_EN 0x1 // enable sleep/deep sleep functionality
+
+//DW1000 INIT configuration parameters
+#define DWT_LOADUCODE 0x1
+#define DWT_LOADNONE 0x0
+
+//DW1000 OTP operating parameter set selection
+#define DWT_OPSET_64LEN 0x0
+#define DWT_OPSET_TIGHT 0x1
+#define DWT_OPSET_DEFLT 0x2
+
+// Call-back data RX frames flags
+#define DWT_CB_DATA_RX_FLAG_RNG 0x1 // Ranging bit
+
+// TX/RX call-back data
+typedef struct
+{
+ uint32 status; //initial value of register as ISR is entered
+ uint16 datalength; //length of frame
+ uint8 fctrl[2]; //frame control bytes
+ uint8 rx_flags; //RX frame flags, see above
+} dwt_cb_data_t;
+
+// Call-back type for all events
+typedef void (*dwt_cb_t)(const dwt_cb_data_t *);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * Structure typedef: dwt_config_t
+ *
+ * Structure for setting device configuration via dwt_configure() function
+ *
+ */
+typedef struct
+{
+ uint8 chan ; //!< channel number {1, 2, 3, 4, 5, 7 }
+ uint8 prf ; //!< Pulse Repetition Frequency {DWT_PRF_16M or DWT_PRF_64M}
+ uint8 txPreambLength ; //!< DWT_PLEN_64..DWT_PLEN_4096
+ uint8 rxPAC ; //!< Acquisition Chunk Size (Relates to RX preamble length)
+ uint8 txCode ; //!< TX preamble code
+ uint8 rxCode ; //!< RX preamble code
+ uint8 nsSFD ; //!< Boolean should we use non-standard SFD for better performance
+ uint8 dataRate ; //!< Data Rate {DWT_BR_110K, DWT_BR_850K or DWT_BR_6M8}
+ uint8 phrMode ; //!< PHR mode {0x0 - standard DWT_PHRMODE_STD, 0x3 - extended frames DWT_PHRMODE_EXT}
+ uint16 sfdTO ; //!< SFD timeout value (in symbols)
+} dwt_config_t ;
+
+
+typedef struct
+{
+ uint8 PGdly;
+ //TX POWER
+ //31:24 BOOST_0.125ms_PWR
+ //23:16 BOOST_0.25ms_PWR-TX_SHR_PWR
+ //15:8 BOOST_0.5ms_PWR-TX_PHR_PWR
+ //7:0 DEFAULT_PWR-TX_DATA_PWR
+ uint32 power;
+}
+dwt_txconfig_t ;
+
+
+typedef struct
+{
+
+ uint16 maxNoise ; // LDE max value of noise
+ uint16 firstPathAmp1 ; // Amplitude at floor(index FP) + 1
+ uint16 stdNoise ; // Standard deviation of noise
+ uint16 firstPathAmp2 ; // Amplitude at floor(index FP) + 2
+ uint16 firstPathAmp3 ; // Amplitude at floor(index FP) + 3
+ uint16 maxGrowthCIR ; // Channel Impulse Response max growth CIR
+ uint16 rxPreamCount ; // Count of preamble symbols accumulated
+ uint16 firstPath ; // First p ath index (10.6 bits fixed point integer)
+}dwt_rxdiag_t ;
+
+
+typedef struct
+{
+ //all of the below are mapped to a 12-bit register in DW1000
+ uint16 PHE ; //number of received header errors
+ uint16 RSL ; //number of received frame sync loss events
+ uint16 CRCG ; //number of good CRC received frames
+ uint16 CRCB ; //number of bad CRC (CRC error) received frames
+ uint16 ARFE ; //number of address filter errors
+ uint16 OVER ; //number of receiver overflows (used in double buffer mode)
+ uint16 SFDTO ; //SFD timeouts
+ uint16 PTO ; //Preamble timeouts
+ uint16 RTO ; //RX frame wait timeouts
+ uint16 TXF ; //number of transmitted frames
+ uint16 HPW ; //half period warn
+ uint16 TXW ; //power up warn
+
+} dwt_deviceentcnts_t ;
+
+
+/********************************************************************************************************************/
+/* REMOVED API LIST */
+/********************************************************************************************************************/
+/*
+ * From version 4.0.0:
+ * - dwt_setGPIOforEXTTRX: Replaced by dwt_setlnapamode to get equivalent functionality.
+ * - dwt_setGPIOdirection: Renamed to dwt_setgpiodirection.
+ * - dwt_setGPIOvalue: Renamed to dwt_setgpiovalue.
+ * - dwt_setrxmode: Replaced by dwt_setsniffmode and dwt_setlowpowerlistening depending on the RX mode the user
+ * wants to set up.
+ * - dwt_checkoverrun: As automatic RX re-enabling is not supported anymore, this functions has become useless.
+ * - dwt_setautorxreenable: As automatic RX re-enabling is not supported anymore, this functions has become
+ * useless.
+ * - dwt_getrangebias: Range bias correction values are platform dependent and should therefore be managed at user
+ * application level.
+ * - dwt_xtaltrim: Renamed to dwt_setxtaltrim.
+ * - dwt_checkIRQ: Renamed to dwt_checkirq.
+ *
+ * From version 3.0.0:
+ * - dwt_getldotune: As LDO loading is now automatically managed by the driver, this function has become useless.
+ * - dwt_getotptxpower: TX power values and location in OTP memory are platform dependent and should therefore be
+ * managed at user application level.
+ * - dwt_readantennadelay: Antenna delay values and location in OTP memory are platform dependent and should
+ * therefore be managed at user application level.
+ * - dwt_readdignostics: Renamed to dwt_readdiagnostics.
+ */
+
+/********************************************************************************************************************/
+/* API LIST */
+/********************************************************************************************************************/
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_getpartid()
+ *
+ * @brief This is used to return the read part ID of the device
+ *
+ * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns the 32 bit part ID value as programmed in the factory
+ */
+uint32 dwt_getpartid(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_getlotid()
+ *
+ * @brief This is used to return the read lot ID of the device
+ *
+ * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns the 32 bit lot ID value as programmed in the factory
+ */
+uint32 dwt_getlotid(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readdevid()
+ *
+ * @brief This is used to return the read device type and revision information of the DW1000 device (MP part is 0xDECA0130)
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns the read value which for DW1000 is 0xDECA0130
+ */
+uint32 dwt_readdevid(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_otprevision()
+ *
+ * @brief This is used to return the read OTP revision
+ *
+ * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns the read OTP revision value
+ */
+uint8 dwt_otprevision(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setfinegraintxseq()
+ *
+ * @brief This function enables/disables the fine grain TX sequencing (enabled by default).
+ *
+ * input parameters
+ * @param enable - 1 to enable fine grain TX sequencing, 0 to disable it.
+ *
+ * output parameters none
+ *
+ * no return value
+ */
+void dwt_setfinegraintxseq(int enable);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setlnapamode()
+ *
+ * @brief This is used to enable GPIO for external LNA or PA functionality - HW dependent, consult the DW1000 User Manual.
+ * This can also be used for debug as enabling TX and RX GPIOs is quite handy to monitor DW1000's activity.
+ *
+ * NOTE: Enabling PA functionality requires that fine grain TX sequencing is deactivated. This can be done using
+ * dwt_setfinegraintxseq().
+ *
+ * input parameters
+ * @param lna - 1 to enable LNA functionality, 0 to disable it
+ * @param pa - 1 to enable PA functionality, 0 to disable it
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setlnapamode(int lna, int pa);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setgpiodirection()
+ *
+ * @brief This is used to set GPIO direction as an input (1) or output (0)
+ *
+ * input parameters
+ * @param gpioNum - this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
+ * @param direction - this sets the GPIO direction - see GxP0... GxP8 in the deca_regs.h file
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setgpiodirection(uint32 gpioNum, uint32 direction);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setgpiovalue()
+ *
+ * @brief This is used to set GPIO value as (1) or (0) only applies if the GPIO is configured as output
+ *
+ * input parameters
+ * @param gpioNum - this is the GPIO to configure - see GxM0... GxM8 in the deca_regs.h file
+ * @param value - this sets the GPIO value - see GDP0... GDP8 in the deca_regs.h file
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setgpiovalue(uint32 gpioNum, uint32 value);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_initialise()
+ *
+ * @brief This function initiates communications with the DW1000 transceiver
+ * and reads its DEV_ID register (address 0x00) to verify the IC is one supported
+ * by this software (e.g. DW1000 32-bit device ID value is 0xDECA0130). Then it
+ * does any initial once only device configurations needed for use and initialises
+ * as necessary any static data items belonging to this low-level driver.
+ *
+ * NOTES:
+ * 1.this function needs to be run before dwt_configuresleep, also the SPI frequency has to be < 3MHz
+ * 2.it also reads and applies LDO tune and crystal trim values from OTP memory
+ *
+ * input parameters
+ * @param config - specifies what configuration to load
+ * DWT_LOADUCODE 0x1 - load the LDE microcode from ROM - enabled accurate RX timestamp
+ * DWT_LOADNONE 0x0 - do not load any values from OTP memory
+ *
+ * output parameters
+ *
+ * returns DWT_SUCCESS for success, or DWT_ERROR for error
+ */
+int dwt_initialise(uint16 config) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_configure()
+ *
+ * @brief This function provides the main API for the configuration of the
+ * DW1000 and this low-level driver. The input is a pointer to the data structure
+ * of type dwt_config_t that holds all the configurable items.
+ * The dwt_config_t structure shows which ones are supported
+ *
+ * input parameters
+ * @param config - pointer to the configuration structure, which contains the device configuration data.
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_configure(dwt_config_t *config) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_configuretxrf()
+ *
+ * @brief This function provides the API for the configuration of the TX spectrum
+ * including the power and pulse generator delay. The input is a pointer to the data structure
+ * of type dwt_txconfig_t that holds all the configurable items.
+ *
+ * input parameters
+ * @param config - pointer to the txrf configuration structure, which contains the tx rf config data
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_configuretxrf(dwt_txconfig_t *config) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setrxantennadelay()
+ *
+ * @brief This API function writes the antenna delay (in time units) to RX registers
+ *
+ * input parameters:
+ * @param rxDelay - this is the total (RX) antenna delay value, which
+ * will be programmed into the RX register
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setrxantennadelay(uint16 antennaDly);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_settxantennadelay()
+ *
+ * @brief This API function writes the antenna delay (in time units) to TX registers
+ *
+ * input parameters:
+ * @param txDelay - this is the total (TX) antenna delay value, which
+ * will be programmed into the TX delay register
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_settxantennadelay(uint16 antennaDly);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setsmarttxpower()
+ *
+ * @brief This call enables or disables the smart TX power feature.
+ *
+ * input parameters
+ * @param enable - this enables or disables the TX smart power (1 = enable, 0 = disable)
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setsmarttxpower(int enable);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_writetxdata()
+ *
+ * @brief This API function writes the supplied TX data into the DW1000's
+ * TX buffer. The input parameters are the data length in bytes and a pointer
+ * to those data bytes.
+ *
+ * input parameters
+ * @param txFrameLength - This is the total frame length, including the two byte CRC.
+ * Note: this is the length of TX message (including the 2 byte CRC) - max is 1023
+ * standard PHR mode allows up to 127 bytes
+ * if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
+ * see dwt_configure function
+ * @param txFrameBytes - Pointer to the users buffer containing the data to send.
+ * @param txBufferOffset - This specifies an offset in the DW1000s TX Buffer at which to start writing data.
+ *
+ * output parameters
+ *
+ * returns DWT_SUCCESS for success, or DWT_ERROR for error
+ */
+int dwt_writetxdata(uint16 txFrameLength, uint8 *txFrameBytes, uint16 txBufferOffset) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_writetxfctrl()
+ *
+ * @brief This API function configures the TX frame control register before the transmission of a frame
+ *
+ * input parameters:
+ * @param txFrameLength - this is the length of TX message (including the 2 byte CRC) - max is 1023
+ * NOTE: standard PHR mode allows up to 127 bytes
+ * if > 127 is programmed, DWT_PHRMODE_EXT needs to be set in the phrMode configuration
+ * see dwt_configure function
+ * @param txBufferOffset - the offset in the tx buffer to start writing the data
+ * @param ranging - 1 if this is a ranging frame, else 0
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_writetxfctrl(uint16 txFrameLength, uint16 txBufferOffset, int ranging);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_starttx()
+ *
+ * @brief This call initiates the transmission, input parameter indicates which TX mode is used see below
+ *
+ * input parameters:
+ * @param mode - if 0 immediate TX (no response expected)
+ * if 1 delayed TX (no response expected)
+ * if 2 immediate TX (response expected - so the receiver will be automatically turned on after TX is done)
+ * if 3 delayed TX (response expected - so the receiver will be automatically turned on after TX is done)
+ *
+ * output parameters
+ *
+ * returns DWT_SUCCESS for success, or DWT_ERROR for error (e.g. a delayed transmission will fail if the delayed time has passed)
+ */
+int dwt_starttx(uint8 mode) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setdelayedtrxtime()
+ *
+ * @brief This API function configures the delayed transmit time or the delayed RX on time
+ *
+ * input parameters
+ * @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,
+ * or at which to turn on the receiver)
+ *
+ * output parameters none
+ *
+ * no return value
+ */
+void dwt_setdelayedtrxtime(uint32 starttime) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readtxtimestamp()
+ *
+ * @brief This is used to read the TX timestamp (adjusted with the programmed antenna delay)
+ *
+ * input parameters
+ * @param timestamp - a pointer to a 5-byte buffer which will store the read TX timestamp time
+ *
+ * output parameters - the timestamp buffer will contain the value after the function call
+ *
+ * no return value
+ */
+void dwt_readtxtimestamp(uint8 * timestamp);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readtxtimestamphi32()
+ *
+ * @brief This is used to read the high 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns high 32-bits of TX timestamp
+ */
+uint32 dwt_readtxtimestamphi32(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readtxtimestamplo32()
+ *
+ * @brief This is used to read the low 32-bits of the TX timestamp (adjusted with the programmed antenna delay)
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns low 32-bits of TX timestamp
+ */
+uint32 dwt_readtxtimestamplo32(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readrxtimestamp()
+ *
+ * @brief This is used to read the RX timestamp (adjusted time of arrival)
+ *
+ * input parameters
+ * @param timestamp - a pointer to a 5-byte buffer which will store the read RX timestamp time
+ *
+ * output parameters - the timestamp buffer will contain the value after the function call
+ *
+ * no return value
+ */
+void dwt_readrxtimestamp(uint8 * timestamp);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readrxtimestamphi32()
+ *
+ * @brief This is used to read the high 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns high 32-bits of RX timestamp
+ */
+uint32 dwt_readrxtimestamphi32(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readrxtimestamplo32()
+ *
+ * @brief This is used to read the low 32-bits of the RX timestamp (adjusted with the programmed antenna delay)
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns low 32-bits of RX timestamp
+ */
+uint32 dwt_readrxtimestamplo32(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readsystimestamphi32()
+ *
+ * @brief This is used to read the high 32-bits of the system time
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns high 32-bits of system time timestamp
+ */
+uint32 dwt_readsystimestamphi32(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readsystime()
+ *
+ * @brief This is used to read the system time
+ *
+ * input parameters
+ * @param timestamp - a pointer to a 5-byte buffer which will store the read system time
+ *
+ * output parameters
+ * @param timestamp - the timestamp buffer will contain the value after the function call
+ *
+ * no return value
+ */
+void dwt_readsystime(uint8 * timestamp);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_forcetrxoff()
+ *
+ * @brief This is used to turn off the transceiver
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_forcetrxoff(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_syncrxbufptrs()
+ *
+ * @brief this function synchronizes rx buffer pointers
+ * need to make sure that the host/IC buffer pointers are aligned before starting RX
+ *
+ * input parameters:
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_syncrxbufptrs(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_rxenable()
+ *
+ * @brief This call turns on the receiver, can be immediate or delayed (depending on the mode parameter). In the case of a
+ * "late" error the receiver will only be turned on if the DWT_IDLE_ON_DLY_ERR is not set.
+ * The receiver will stay turned on, listening to any messages until
+ * it either receives a good frame, an error (CRC, PHY header, Reed Solomon) or it times out (SFD, Preamble or Frame).
+ *
+ * input parameters
+ * @param mode - this can be one of the following allowed values:
+ *
+ * DWT_START_RX_IMMEDIATE 0 used to enbale receiver immediately
+ * DWT_START_RX_DELAYED 1 used to set up delayed RX, if "late" error triggers, then the RX will be enabled immediately
+ * (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
+ * (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
+ * performing manual RX re-enabling in double buffering mode
+ *
+ * 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)
+ */
+int dwt_rxenable(int mode);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setsniffmode()
+ *
+ * @brief enable/disable and configure SNIFF mode.
+ *
+ * SNIFF mode is a low-power reception mode where the receiver is sequenced on and off instead of being on all the time.
+ * The time spent in each state (on/off) is specified through the parameters below.
+ * See DW1000 User Manual section 4.5 "Low-Power SNIFF mode" for more details.
+ *
+ * input parameters:
+ * @param enable - 1 to enable SNIFF mode, 0 to disable. When 0, all other parameters are not taken into account.
+ * @param timeOn - duration of receiver ON phase, expressed in multiples of PAC size. The counter automatically adds 1 PAC
+ * 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.
+ * @param timeOff - duration of receiver OFF phase, expressed in multiples of 128/125 µs (~1 µs). Max value is 255.
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setsniffmode(int enable, uint8 timeOn, uint8 timeOff);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setlowpowerlistening()
+ *
+ * @brief enable/disable low-power listening mode.
+ *
+ * Low-power listening is a feature whereby the DW1000 is predominantly in the SLEEP state but wakes periodically, (after
+ * this "long sleep"), for a very short time to sample the air for a preamble sequence. This preamble sampling "listening"
+ * phase is actually two reception phases separated by a "short sleep" time. See DW1000 User Manual section "Low-Power
+ * Listening" for more details.
+ *
+ * NOTE: Before enabling low-power listening, the following functions have to be called to fully configure it:
+ * - dwt_configuresleep() to configure long sleep phase. "mode" parameter should at least have DWT_PRESRV_SLEEP,
+ * DWT_CONFIG and DWT_RX_EN set and "wake" parameter should at least have both DWT_WAKE_SLPCNT and DWT_SLP_EN set.
+ * - dwt_calibratesleepcnt() and dwt_configuresleepcnt() to define the "long sleep" phase duration.
+ * - dwt_setsnoozetime() to define the "short sleep" phase duration.
+ * - dwt_setpreambledetecttimeout() to define the reception phases duration.
+ * - dwt_setinterrupt() to activate RX good frame interrupt (DWT_INT_RFCG) only.
+ * When configured, low-power listening mode can be triggered either by putting the DW1000 to sleep (using
+ * dwt_entersleep()) or by activating reception (using dwt_rxenable()).
+ *
+ * Please refer to the low-power listening examples (examples 8a/8b accompanying the API distribution on Decawave's
+ * website). They form a working example code that shows how to use low-power listening correctly.
+ *
+ * input parameters:
+ * @param enable - 1 to enable low-power listening, 0 to disable.
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setlowpowerlistening(int enable);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setsnoozetime()
+ *
+ * @brief Set duration of "short sleep" phase when in low-power listening mode.
+ *
+ * input parameters:
+ * @param snooze_time - "short sleep" phase duration, expressed in multiples of 512/19.2 µs (~26.7 µs). The counter
+ * automatically adds 1 to the value set. The smallest working value that should be set is 1,
+ * i.e. giving a snooze time of 2 units (or ~53 µs).
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setsnoozetime(uint8 snooze_time);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setdblrxbuffmode()
+ *
+ * @brief This call enables the double receive buffer mode
+ *
+ * input parameters
+ * @param enable - 1 to enable, 0 to disable the double buffer mode
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setdblrxbuffmode(int enable);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setrxtimeout()
+ *
+ * @brief This call enables RX timeout (SY_STAT_RFTO event)
+ *
+ * input parameters
+ * @param time - how long the receiver remains on from the RX enable command
+ * The time parameter used here is in 1.0256 us (512/499.2MHz) units
+ * If set to 0 the timeout is disabled.
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setrxtimeout(uint16 time);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setpreambledetecttimeout()
+ *
+ * @brief This call enables preamble timeout (SY_STAT_RXPTO event)
+ *
+ * input parameters
+ * @param timeout - Preamble detection timeout, expressed in multiples of PAC size. The counter automatically adds 1 PAC
+ * size to the value set. Min value that can be set is 1 (i.e. a timeout of 2 PAC size).
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setpreambledetecttimeout(uint16 timeout);
+
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_calibratesleepcnt()
+ *
+ * @brief calibrates the local oscillator as its frequency can vary between 7 and 13kHz depending on temp and voltage
+ *
+ * NOTE: this function needs to be run before dwt_configuresleepcnt, so that we know what the counter units are
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns the number of XTAL/2 cycles per low-power oscillator cycle. LP OSC frequency = 19.2 MHz/return value
+ */
+uint16 dwt_calibratesleepcnt(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_configuresleepcnt()
+ *
+ * @brief sets the sleep counter to new value, this function programs the high 16-bits of the 28-bit counter
+ *
+ * NOTE: this function needs to be run before dwt_configuresleep, also the SPI frequency has to be < 3MHz
+ *
+ * input parameters
+ * @param sleepcnt - this it value of the sleep counter to program
+ *
+ * output parameters
+ *
+ * no return value
+ */
+ void dwt_configuresleepcnt(uint16 sleepcnt);
+
+ /*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_configuresleep()
+ *
+ * @brief configures the device for both DEEP_SLEEP and SLEEP modes, and on-wake mode
+ * i.e. before entering the sleep, the device should be programmed for TX or RX, then upon "waking up" the TX/RX settings
+ * will be preserved and the device can immediately perform the desired action TX/RX
+ *
+ * NOTE: e.g. Tag operation - after deep sleep, the device needs to just load the TX buffer and send the frame
+ *
+ *
+ * mode: the array and LDE code (OTP/ROM) and LDO tune, and set sleep persist
+ * DWT_PRESRV_SLEEP 0x0100 - preserve sleep
+ * DWT_LOADOPSET 0x0080 - load operating parameter set on wakeup
+ * DWT_CONFIG 0x0040 - download the AON array into the HIF (configuration download)
+ * DWT_LOADEUI 0x0008
+ * DWT_GOTORX 0x0002
+ * DWT_TANDV 0x0001
+ *
+ * wake: wake up parameters
+ * DWT_XTAL_EN 0x10 - keep XTAL running during sleep
+ * DWT_WAKE_SLPCNT 0x8 - wake up after sleep count
+ * DWT_WAKE_CS 0x4 - wake up on chip select
+ * DWT_WAKE_WK 0x2 - wake up on WAKEUP PIN
+ * DWT_SLP_EN 0x1 - enable sleep/deep sleep functionality
+ *
+ * input parameters
+ * @param mode - config on-wake parameters
+ * @param wake - config wake up parameters
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_configuresleep(uint16 mode, uint8 wake);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_entersleep()
+ *
+ * @brief This function puts the device into deep sleep or sleep. dwt_configuresleep() should be called first
+ * to configure the sleep and on-wake/wake-up parameters
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_entersleep(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_entersleepaftertx(int enable)
+ *
+ * @brief sets the auto TX to sleep bit. This means that after a frame
+ * transmission the device will enter deep sleep mode. The dwt_configuresleep() function
+ * needs to be called before this to configure the on-wake settings
+ *
+ * NOTE: the IRQ line has to be low/inactive (i.e. no pending events)
+ *
+ * input parameters
+ * @param enable - 1 to configure the device to enter deep sleep after TX, 0 - disables the configuration
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_entersleepaftertx(int enable);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_spicswakeup()
+ *
+ * @brief wake up the device from sleep mode using the SPI read,
+ * the device will wake up on chip select line going low if the line is held low for at least 500us.
+ * To define the length depending on the time one wants to hold
+ * the chip select line low, use the following formula:
+ *
+ * length (bytes) = time (s) * byte_rate (Hz)
+ *
+ * where fastest byte_rate is spi_rate (Hz) / 8 if the SPI is sending the bytes back-to-back.
+ * To save time and power, a system designer could determine byte_rate value more precisely.
+ *
+ * NOTE: Alternatively the device can be waken up with WAKE_UP pin if configured for that operation
+ *
+ * input parameters
+ * @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
+ * @param length - this is the length of the dummy buffer
+ *
+ * output parameters
+ *
+ * returns DWT_SUCCESS for success, or DWT_ERROR for error
+ */
+int dwt_spicswakeup(uint8 *buff, uint16 length);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setcallbacks()
+ *
+ * @brief This function is used to register the different callbacks called when one of the corresponding event occurs.
+ *
+ * NOTE: Callbacks can be undefined (set to NULL). In this case, dwt_isr() will process the event as usual but the 'null'
+ * callback will not be called.
+ *
+ * input parameters
+ * @param cbTxDone - the pointer to the TX confirmation event callback function
+ * @param cbRxOk - the pointer to the RX good frame event callback function
+ * @param cbRxTo - the pointer to the RX timeout events callback function
+ * @param cbRxErr - the pointer to the RX error events callback function
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setcallbacks(dwt_cb_t cbTxDone, dwt_cb_t cbRxOk, dwt_cb_t cbRxTo, dwt_cb_t cbRxErr);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_checkirq()
+ *
+ * @brief This function checks if the IRQ line is active - this is used instead of interrupt handler
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * return value is 1 if the IRQS bit is set and 0 otherwise
+ */
+uint8 dwt_checkirq(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_isr()
+ *
+ * @brief This is the DW1000's general Interrupt Service Routine. It will process/report the following events:
+ * - RXFCG (through cbRxOk callback)
+ * - TXFRS (through cbTxDone callback)
+ * - RXRFTO/RXPTO (through cbRxTo callback)
+ * - RXPHE/RXFCE/RXRFSL/RXSFDTO/AFFREJ/LDEERR (through cbRxTo cbRxErr)
+ * For all events, corresponding interrupts are cleared and necessary resets are performed. In addition, in the RXFCG case,
+ * received frame information and frame control are read before calling the callback. If double buffering is activated, it
+ * will also toggle between reception buffers once the reception callback processing has ended.
+ *
+ * /!\ This version of the ISR supports double buffering but does not support automatic RX re-enabling!
+ *
+ * NOTE: In PC based system using (Cheetah or ARM) USB to SPI converter there can be no interrupts, however we still need something
+ * to take the place of it and operate in a polled way. In an embedded system this function should be configured to be triggered
+ * on any of the interrupts described above.
+
+ * input parameters
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_isr(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_isr_lplisten()
+ *
+ * @brief This is the DW1000's Interrupt Service Routine to use when low-power listening scheme is implemented. It will
+ * only process/report the RXFCG event (through cbRxOk callback).
+ * It clears RXFCG interrupt and reads received frame information and frame control before calling the callback.
+ *
+ * /!\ This version of the ISR is designed for single buffering case only!
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_lowpowerlistenisr(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn void dwt_setinterrupt()
+ *
+ * @brief This function enables the specified events to trigger an interrupt.
+ * The following events can be enabled:
+ * DWT_INT_TFRS 0x00000080 // frame sent
+ * DWT_INT_RFCG 0x00004000 // frame received with good CRC
+ * DWT_INT_RPHE 0x00001000 // receiver PHY header error
+ * DWT_INT_RFCE 0x00008000 // receiver CRC error
+ * DWT_INT_RFSL 0x00010000 // receiver sync loss error
+ * DWT_INT_RFTO 0x00020000 // frame wait timeout
+ * DWT_INT_RXPTO 0x00200000 // preamble detect timeout
+ * DWT_INT_SFDT 0x04000000 // SFD timeout
+ * DWT_INT_ARFE 0x20000000 // frame rejected (due to frame filtering configuration)
+ *
+ *
+ * input parameters:
+ * @param bitmask - sets the events which will generate interrupt
+ * @param enable - if set the interrupts are enabled else they are cleared
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setinterrupt( uint32 bitmask, uint8 enable);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setpanid()
+ *
+ * @brief This is used to set the PAN ID
+ *
+ * input parameters
+ * @param panID - this is the PAN ID
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setpanid(uint16 panID);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setaddress16()
+ *
+ * @brief This is used to set 16-bit (short) address
+ *
+ * input parameters
+ * @param shortAddress - this sets the 16 bit short address
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setaddress16(uint16 shortAddress);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_seteui()
+ *
+ * @brief This is used to set the EUI 64-bit (long) address
+ *
+ * input parameters
+ * @param eui64 - this is the pointer to a buffer that contains the 64bit address
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_seteui(uint8 *eui64);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_geteui()
+ *
+ * @brief This is used to get the EUI 64-bit from the DW1000
+ *
+ * input parameters
+ * @param eui64 - this is the pointer to a buffer that will contain the read 64-bit EUI value
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_geteui(uint8 *eui64);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_otpread()
+ *
+ * @brief This is used to read the OTP data from given address into provided array
+ *
+ * input parameters
+ * @param address - this is the OTP address to read from
+ * @param array - this is the pointer to the array into which to read the data
+ * @param length - this is the number of 32 bit words to read (array needs to be at least this length)
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_otpread(uint32 address, uint32 *array, uint8 length);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_enableframefilter()
+ *
+ * @brief This is used to enable the frame filtering - (the default option is to
+ * accept any data and ACK frames with correct destination address
+ *
+ * input parameters
+ * @param - bitmask - enables/disables the frame filtering options according to
+ * DWT_FF_NOTYPE_EN 0x000 no frame types allowed
+ * DWT_FF_COORD_EN 0x002 behave as coordinator (can receive frames with no destination address (PAN ID has to match))
+ * DWT_FF_BEACON_EN 0x004 beacon frames allowed
+ * DWT_FF_DATA_EN 0x008 data frames allowed
+ * DWT_FF_ACK_EN 0x010 ack frames allowed
+ * DWT_FF_MAC_EN 0x020 mac control frames allowed
+ * DWT_FF_RSVD_EN 0x040 reserved frame types allowed
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_enableframefilter(uint16 bitmask);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_enableautoack()
+ *
+ * @brief This call enables the auto-ACK feature. If the responseDelayTime (parameter) is 0, the ACK will be sent a.s.a.p.
+ * otherwise it will be sent with a programmed delay (in symbols), max is 255.
+ * NOTE: needs to have frame filtering enabled as well
+ *
+ * input parameters
+ * @param responseDelayTime - if non-zero the ACK is sent after this delay, max is 255.
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_enableautoack(uint8 responseDelayTime);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setrxaftertxdelay()
+ *
+ * @brief This sets the receiver turn on delay time after a transmission of a frame
+ *
+ * input parameters
+ * @param rxDelayTime - (20 bits) - the delay is in UWB microseconds
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setrxaftertxdelay(uint32 rxDelayTime);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_rxreset()
+ *
+ * @brief this function resets the receiver of the DW1000
+ *
+ * input parameters:
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_rxreset(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_softreset()
+ *
+ * @brief this function resets the DW1000
+ *
+ * input parameters:
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_softreset(void) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readrxdata()
+ *
+ * @brief This is used to read the data from the RX buffer, from an offset location give by offset parameter
+ *
+ * input parameters
+ * @param buffer - the buffer into which the data will be read
+ * @param length - the length of data to read (in bytes)
+ * @param rxBufferOffset - the offset in the rx buffer from which to read the data
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_readrxdata(uint8 *buffer, uint16 length, uint16 rxBufferOffset);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readaccdata()
+ *
+ * @brief This is used to read the data from the Accumulator buffer, from an offset location give by offset parameter
+ *
+ * NOTE: Because of an internal memory access delay when reading the accumulator the first octet output is a dummy octet
+ * that should be discarded. This is true no matter what sub-index the read begins at.
+ *
+ * input parameters
+ * @param buffer - the buffer into which the data will be read
+ * @param length - the length of data to read (in bytes)
+ * @param accOffset - the offset in the acc buffer from which to read the data
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_readaccdata(uint8 *buffer, uint16 length, uint16 rxBufferOffset);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readdiagnostics()
+ *
+ * @brief this function reads the RX signal quality diagnostic data
+ *
+ * input parameters
+ * @param diagnostics - diagnostic structure pointer, this will contain the diagnostic data read from the DW1000
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_readdiagnostics(dwt_rxdiag_t * diagnostics);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_loadopsettabfromotp()
+ *
+ * @brief This is used to select which Operational Parameter Set table to load from OTP memory
+ *
+ * input parameters
+ * @param ops_sel - Operational Parameter Set table to load:
+ * DWT_OPSET_64LEN = 0x0 - load the operational parameter set table for 64 length preamble configuration
+ * DWT_OPSET_TIGHT = 0x1 - load the operational parameter set table for tight xtal offsets (<1ppm)
+ * DWT_OPSET_DEFLT = 0x2 - load the default operational parameter set table (this is loaded from reset)
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_loadopsettabfromotp(uint8 ops_sel);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_configeventcounters()
+ *
+ * @brief This is used to enable/disable the event counter in the IC
+ *
+ * input parameters
+ * @param - enable - 1 enables (and reset), 0 disables the event counters
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_configeventcounters(int enable);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readeventcounters()
+ *
+ * @brief This is used to read the event counters in the IC
+ *
+ * input parameters
+ * @param counters - pointer to the dwt_deviceentcnts_t structure which will hold the read data
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_readeventcounters(dwt_deviceentcnts_t *counters);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_otpwriteandverify()
+ *
+ * @brief This is used to program 32-bit value into the DW1000 OTP memory.
+ *
+ * input parameters
+ * @param value - this is the 32-bit value to be programmed into OTP
+ * @param address - this is the 16-bit OTP address into which the 32-bit value is programmed
+ *
+ * output parameters
+ *
+ * returns DWT_SUCCESS for success, or DWT_ERROR for error
+ */
+uint32 dwt_otpwriteandverify(uint32 value, uint16 address);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setleds()
+ *
+ * @brief This is used to set up Tx/Rx GPIOs which could be used to control LEDs
+ * Note: not completely IC dependent, also needs board with LEDS fitted on right I/O lines
+ * this function enables GPIOs 2 and 3 which are connected to LED3 and LED4 on EVB1000
+ *
+ * input parameters
+ * @param mode - this is a bit field interpreted as follows:
+ * - bit 0: 1 to enable LEDs, 0 to disable them
+ * - bit 1: 1 to make LEDs blink once on init. Only valid if bit 0 is set (enable LEDs)
+ * - bit 2 to 7: reserved
+ *
+ * output parameters none
+ *
+ * no return value
+ */
+void dwt_setleds(uint8 mode);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_setxtaltrim()
+ *
+ * @brief This is used to adjust the crystal frequency
+ *
+ * input parameters:
+ * @param value - crystal trim value (in range 0x0 to 0x1F) 31 steps (~1.5ppm per step)
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_setxtaltrim(uint8 value);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_getinitxtaltrim()
+ *
+ * @brief This function returns the value of XTAL trim that has been applied during initialisation (dwt_init). This can
+ * be either the value read in OTP memory or a default value.
+ *
+ * NOTE: The value returned by this function is the initial value only! It is not updated on dwt_setxtaltrim calls.
+ *
+ * input parameters
+ *
+ * output parameters
+ *
+ * returns the XTAL trim value set upon initialisation
+ */
+uint8 dwt_getinitxtaltrim(void);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_configcwmode()
+ *
+ * @brief this function sets the DW1000 to transmit cw signal at specific channel frequency
+ *
+ * input parameters:
+ * @param chan - specifies the operating channel (e.g. 1, 2, 3, 4, 5, 6 or 7)
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_configcwmode(uint8 chan);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_configcontinuousframemode()
+ *
+ * @brief this function sets the DW1000 to continuous tx frame mode for regulatory approvals testing.
+ *
+ * input parameters:
+ * @param framerepetitionrate - This is a 32-bit value that is used to set the interval between transmissions.
+* The minimum value is 4. The units are approximately 8 ns. (or more precisely 512/(499.2e6*128) seconds)).
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_configcontinuousframemode(uint32 framerepetitionrate);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readtempvbat()
+ *
+ * @brief this function reads the battery voltage and temperature of the MP
+ * The values read here will be the current values sampled by DW1000 AtoD converters.
+ * Note on Temperature: the temperature value needs to be converted to give the real temperature
+ * the formula is: 1.13 * reading - 113.0
+ * Note on Voltage: the voltage value needs to be converted to give the real voltage
+ * the formula is: 0.0057 * reading + 2.3
+ *
+ * NB: To correctly read the temperature this read should be done with xtal clock
+ * however that means that the receiver will be switched off, if receiver needs to be on then
+ * the timer is used to make sure the value is stable before reading
+ *
+ * input parameters:
+ * @param fastSPI - set to 1 if SPI rate > than 3MHz is used
+ *
+ * output parameters
+ *
+ * returns (temp_raw<<8)|(vbat_raw)
+ */
+uint16 dwt_readtempvbat(uint8 fastSPI);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readwakeuptemp()
+ *
+ * @brief this function reads the temperature of the DW1000 that was sampled
+ * on waking from Sleep/Deepsleep. They are not current values, but read on last
+ * wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
+ *
+ * input parameters:
+ *
+ * output parameters:
+ *
+ * returns: 8-bit raw temperature sensor value
+ */
+uint8 dwt_readwakeuptemp(void) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readwakeupvbat()
+ *
+ * @brief this function reads the battery voltage of the DW1000 that was sampled
+ * on waking from Sleep/Deepsleep. They are not current values, but read on last
+ * wakeup if DWT_TANDV bit is set in mode parameter of dwt_configuresleep
+ *
+ * input parameters:
+ *
+ * output parameters:
+ *
+ * returns: 8-bit raw battery voltage sensor value
+ */
+uint8 dwt_readwakeupvbat(void) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_writetodevice()
+ *
+ * @brief this function is used to write to the DW1000 device registers
+ * Notes:
+ * 1. Firstly we create a header (the first byte is a header byte)
+ * 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
+ * b. set bit-7 (or with 0x80) for write operation
+ * 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
+ *
+ * 2. Write the header followed by the data bytes to the DW1000 device
+ *
+ *
+ * input parameters:
+ * @param recordNumber - ID of register file or buffer being accessed
+ * @param index - byte index into register file or buffer being accessed
+ * @param length - number of bytes being written
+ * @param buffer - pointer to buffer containing the 'length' bytes to be written
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_writetodevice
+(
+ uint16 recordNumber, // input parameter - ID of register file or buffer being accessed
+ uint16 index, // input parameter - byte index into register file or buffer being accessed
+ uint32 length, // input parameter - number of bytes being written
+ const uint8 *buffer // input parameter - pointer to buffer containing the 'length' bytes to be written
+) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_readfromdevice()
+ *
+ * @brief this function is used to read from the DW1000 device registers
+ * Notes:
+ * 1. Firstly we create a header (the first byte is a header byte)
+ * 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
+ * b. set bit-7 (or with 0x80) for write operation
+ * 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
+ *
+ * 2. Write the header followed by the data bytes to the DW1000 device
+ * 3. Store the read data in the input buffer
+ *
+ * input parameters:
+ * @param recordNumber - ID of register file or buffer being accessed
+ * @param index - byte index into register file or buffer being accessed
+ * @param length - number of bytes being read
+ * @param buffer - pointer to buffer in which to return the read data.
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_readfromdevice
+(
+ uint16 recordNumber, // input parameter - ID of register file or buffer being accessed
+ uint16 index, // input parameter - byte index into register file or buffer being accessed
+ uint32 length, // input parameter - number of bytes being read
+ uint8 *buffer // input parameter - pointer to buffer in which to return the read data.
+) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_read32bitoffsetreg()
+ *
+ * @brief this function is used to read 32-bit value from the DW1000 device registers
+ *
+ * input parameters:
+ * @param regFileID - ID of register file or buffer being accessed
+ * @param regOffset - the index into register file or buffer being accessed
+ *
+ * output parameters
+ *
+ * returns 32 bit register value
+ */
+uint32 dwt_read32bitoffsetreg(int regFileID, int regOffset) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_write32bitoffsetreg()
+ *
+ * @brief this function is used to write 32-bit value to the DW1000 device registers
+ *
+ * input parameters:
+ * @param regFileID - ID of register file or buffer being accessed
+ * @param regOffset - the index into register file or buffer being accessed
+ * @param regval - the value to write
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_write32bitoffsetreg(int regFileID, int regOffset, uint32 regval);
+
+#define dwt_write32bitreg(x,y) dwt_write32bitoffsetreg(x,0,y)
+#define dwt_read32bitreg(x) dwt_read32bitoffsetreg(x,0)
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_read16bitoffsetreg()
+ *
+ * @brief this function is used to read 16-bit value from the DW1000 device registers
+ *
+ * input parameters:
+ * @param regFileID - ID of register file or buffer being accessed
+ * @param regOffset - the index into register file or buffer being accessed
+ *
+ * output parameters
+ *
+ * returns 16 bit register value
+ */
+uint16 dwt_read16bitoffsetreg(int regFileID, int regOffset);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_write16bitoffsetreg()
+ *
+ * @brief this function is used to write 16-bit value to the DW1000 device registers
+ *
+ * input parameters:
+ * @param regFileID - ID of register file or buffer being accessed
+ * @param regOffset - the index into register file or buffer being accessed
+ * @param regval - the value to write
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_write16bitoffsetreg(int regFileID, int regOffset, uint16 regval) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_read8bitoffsetreg()
+ *
+ * @brief this function is used to read an 8-bit value from the DW1000 device registers
+ *
+ * input parameters:
+ * @param regFileID - ID of register file or buffer being accessed
+ * @param regOffset - the index into register file or buffer being accessed
+ *
+ * output parameters
+ *
+ * returns 8-bit register value
+ */
+uint8 dwt_read8bitoffsetreg(int regFileID, int regOffset);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn dwt_write8bitoffsetreg()
+ *
+ * @brief this function is used to write an 8-bit value to the DW1000 device registers
+ *
+ * input parameters:
+ * @param regFileID - ID of register file or buffer being accessed
+ * @param regOffset - the index into register file or buffer being accessed
+ * @param regval - the value to write
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void dwt_write8bitoffsetreg(int regFileID, int regOffset, uint8 regval);
+
+
+/****************************************************************************************************************************************************
+ *
+ * Declaration of platform-dependent lower level functions.
+ *
+ ****************************************************************************************************************************************************/
+
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn writetospi()
+ *
+ * @brief
+ * NB: In porting this to a particular microprocessor, the implementer needs to define the two low
+ * level abstract functions to write to and read from the SPI the definitions should be in deca_spi.c file.
+ * Low level abstract function to write to the SPI
+ * Takes two separate byte buffers for write header and write data
+ * returns 0 for success, or -1 for error
+ *
+ * Note: The body of this function is defined in deca_spi.c and is platform specific
+ *
+ * input parameters:
+ * @param headerLength - number of bytes header being written
+ * @param headerBuffer - pointer to buffer containing the 'headerLength' bytes of header to be written
+ * @param bodylength - number of bytes data being written
+ * @param bodyBuffer - pointer to buffer containing the 'bodylength' bytes od data to be written
+ *
+ * output parameters
+ *
+ * returns DWT_SUCCESS for success, or DWT_ERROR for error
+ */
+int writetospi(uint16 headerLength, const uint8 *headerBuffer, uint32 bodylength, const uint8 *bodyBuffer);
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn readfromspi()
+ *
+ * @brief
+ * NB: In porting this to a particular microprocessor, the implementer needs to define the two low
+ * level abstract functions to write to and read from the SPI the definitions should be in deca_spi.c file.
+ * Low level abstract function to write to the SPI
+ * Takes two separate byte buffers for write header and write data
+ * returns 0 for success, or -1 for error
+ *
+ * Note: The body of this function is defined in deca_spi.c and is platform specific
+ *
+ * input parameters:
+ * @param headerLength - number of bytes header to write
+ * @param headerBuffer - pointer to buffer containing the 'headerLength' bytes of header to write
+ * @param readlength - number of bytes data being read
+ * @param readBuffer - pointer to buffer containing to return the data (NB: size required = headerLength + readlength)
+ *
+ * output parameters
+ *
+ * returns DWT_SUCCESS for success (and the position in the buffer at which data begins), or DWT_ERROR for error
+ */
+int readfromspi(uint16 headerLength, const uint8 *headerBuffer, uint32 readlength, uint8 *readBuffer);
+
+// ---------------------------------------------------------------------------
+//
+// NB: The purpose of the deca_mutex.c file is to provide for microprocessor interrupt enable/disable, this is used for
+// controlling mutual exclusion from critical sections in the code where interrupts and background
+// processing may interact. The code using this is kept to a minimum and the disabling time is also
+// kept to a minimum, so blanket interrupt disable may be the easiest way to provide this. But at a
+// minimum those interrupts coming from the decawave device should be disabled/re-enabled by this activity.
+//
+// In porting this to a particular microprocessor, the implementer may choose to use #defines here
+// to map these calls transparently to the target system. Alternatively the appropriate code may
+// be embedded in the functions provided in the deca_irq.c file.
+//
+// ---------------------------------------------------------------------------
+
+typedef int decaIrqStatus_t ; // Type for remembering IRQ status
+
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn decamutexon()
+ *
+ * @brief This function should disable interrupts. This is called at the start of a critical section
+ * It returns the IRQ state before disable, this value is used to re-enable in decamutexoff call
+ *
+ * Note: The body of this function is defined in deca_mutex.c and is platform specific
+ *
+ * input parameters:
+ *
+ * output parameters
+ *
+ * returns the state of the DW1000 interrupt
+ */
+decaIrqStatus_t decamutexon(void) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn decamutexoff()
+ *
+ * @brief This function should re-enable interrupts, or at least restore their state as returned(&saved) by decamutexon
+ * This is called at the end of a critical section
+ *
+ * Note: The body of this function is defined in deca_mutex.c and is platform specific
+ *
+ * input parameters:
+ * @param s - the state of the DW1000 interrupt as returned by decamutexon
+ *
+ * output parameters
+ *
+ * returns the state of the DW1000 interrupt
+ */
+void decamutexoff(decaIrqStatus_t s) ;
+
+/*! ------------------------------------------------------------------------------------------------------------------
+ * @fn deca_sleep()
+ *
+ * @brief Wait for a given amount of time.
+ * NB: The body of this function is defined in deca_sleep.c and is platform specific
+ *
+ * input parameters:
+ * @param time_ms - time to wait in milliseconds
+ *
+ * output parameters
+ *
+ * no return value
+ */
+void deca_sleep(unsigned int time_ms);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _DECA_DEVICE_API_H_ */
+
+
+