File content as of revision 16:2080adef6fa6:

// by Matthias Grob & Manuel Stalder - ETH Zürich - 2015

#ifndef DW1000_H
#define DW1000_H

#include "mbed.h"

// register addresses
//      Mnemonic                    Address Bytes Description
#define DW1000_DEV_ID               0x00 //     4 Device Identifier – includes device type and revision information
#define DW1000_EUI                  0x01 //     8 Extended Unique Identifier
#define DW1000_PANADR               0x03 //     4 PAN Identifier and Short Address
#define DW1000_SYS_CFG              0x04 //     4 System Configuration bitmap
#define DW1000_SYS_TIME             0x06 //     5 System Time Counter (40-bit)
#define DW1000_TX_FCTRL             0x08 //     5 Transmit Frame Control
#define DW1000_TX_BUFFER            0x09 //  1024 Transmit Data Buffer
#define DW1000_DX_TIME              0x0A //     5 Delayed Send or Receive Time (40-bit)
#define DW1000_RX_FWTO              0x0C //     2 Receive Frame Wait Timeout Period
#define DW1000_SYS_CTRL             0x0D //     4 System Control Register
#define DW1000_SYS_MASK             0x0E //     4 System Event Mask Register
#define DW1000_SYS_STATUS           0x0F //     5 System Event Status Register
#define DW1000_RX_FINFO             0x10 //     4 RX Frame Information                (in double buffer set)
#define DW1000_RX_BUFFER            0x11 //  1024 Receive Data Buffer                 (in double buffer set)
#define DW1000_RX_FQUAL             0x12 //     8 Rx Frame Quality information        (in double buffer set)
#define DW1000_RX_TTCKI             0x13 //     4 Receiver Time Tracking Interval     (in double buffer set)
#define DW1000_RX_TTCKO             0x14 //     5 Receiver Time Tracking Offset       (in double buffer set)
#define DW1000_RX_TIME              0x15 //    14 Receive Message Time of Arrival     (in double buffer set)
#define DW1000_TX_TIME              0x17 //    10 Transmit Message Time of Sending    (in double buffer set)
#define DW1000_TX_ANTD              0x18 //     2 16-bit Delay from Transmit to Antenna
#define DW1000_SYS_STATE            0x19 //     5 System State information
#define DW1000_ACK_RESP_T           0x1A //     4 Acknowledgement Time and Response Time
#define DW1000_RX_SNIFF             0x1D //     4 Pulsed Preamble Reception Configuration
#define DW1000_TX_POWER             0x1E //     4 TX Power Control
#define DW1000_CHAN_CTRL            0x1F //     4 Channel Control
#define DW1000_USR_SFD              0x21 //    41 User-specified short/long TX/RX SFD sequences
#define DW1000_AGC_CTRL             0x23 //    32 Automatic Gain Control configuration
#define DW1000_EXT_SYNC             0x24 //    12 External synchronisation control.
#define DW1000_ACC_MEM              0x25 //  4064 Read access to accumulator data
#define DW1000_GPIO_CTRL            0x26 //    44 Peripheral register bus 1 access - GPIO control
#define DW1000_DRX_CONF             0x27 //    44 Digital Receiver configuration
#define DW1000_RF_CONF              0x28 //    58 Analog RF Configuration
#define DW1000_TX_CAL               0x2A //    52 Transmitter calibration block
#define DW1000_FS_CTRL              0x2B //    21 Frequency synthesiser control block
#define DW1000_AON                  0x2C //    12 Always-On register set
#define DW1000_OTP_IF               0x2D //    18 One Time Programmable Memory Interface
#define DW1000_LDE_CTRL             0x2E //     - Leading edge detection control block
#define DW1000_DIG_DIAG             0x2F //    41 Digital Diagnostics Interface
#define DW1000_PMSC                 0x36 //    48 Power Management System Control Block

// AGC_CTRL sub registers
#define DWAGCCTRL_AGC_CTRL1         0x02
#define DWAGCCTRL_AGC_TUNE1         0x04
#define DWAGCCTRL_AGC_TUNE2         0x0C
#define DWAGCCTRL_AGC_TUNE3         0x12

// EXT_SYNC sub registers
#define DWEXTSYNC_EC_CTRL           0x00
#define DWEXTSYNC_EC_RXTC           0x04
#define DWEXTSYNC_EC_GOLP           0x08

// GPIO sub registers
#define DWGPIO_GPIO_MODE           0x00
#define DWGPIO_GPIO_DIR            0x08
#define DWGPIO_GPIO_DOUT           0x0C
#define DWGPIO_GPIO_IRQE           0x10
#define DWGPIO_GPIO_ISEN           0x14
#define DWGPIO_GPIO_IMODE          0x18
#define DWGPIO_GPIO_IBES           0x1C
#define DWGPIO_GPIO_ICLR           0x20
#define DWGPIO_GPIO_IDBE           0x24
#define DWGPIO_GPIO_RAW            0x28

// DRX sub registers
#define DWDRX_DRX_TUNE0B            0x02
#define DWDRX_DRX_TUNE1A            0x04
#define DWDRX_DRX_TUNE1B            0x06
#define DWDRX_DRX_TUNE2             0x08
#define DWDRX_DRX_SFDTOC            0x20
#define DWDRX_DRX_PRETOC            0x24
#define DWDRX_DRX_TUNE4H            0x26

//RF conf sub registers
#define DWRFCONF_RF_CONF            0x00
#define DWRFCONF_RF_RXCTRLH         0x0B
#define DWRFCONF_RF_TXCTRL          0x0C
#define DWRFCONF_RF_STATUS          0x2C
#define DWRFCONF_RF_LDOTUNE         0x30

// TX cal sub registers
#define DWTXCAL_TC_SARC             0x00
#define DWTXCAL_TC_SARL             0x03
#define DWTXCAL_TC_SARW             0x06
#define DWTXCAL_TC_PGDELAY          0x0B
#define DWTXCAL_TC_PGTEST           0x0C

// Freq synth sub registers
#define DWFSCTRL_FS_PLLCFG          0x07
#define DWFSCTRL_FS_PLLTUNE         0x0B
#define DWFSCTRL_FS_XTALT           0x0E

// Always on sub registers
#define DWAON_AON_WCFG              0x00
#define DWAON_AON_CTRL              0x02
#define DWAON_AON_RDAT              0x03
#define DWAON_AON_ADDR              0x04
#define DWAON_AON_CFG0              0x06
#define DWAON_AON_CFG1              0x0A

// OTP sub registers
#define DWOTP_OTP_WDAT              0x00
#define DWOTP_OTP_ADDR              0x04
#define DWOTP_OTP_CTRL              0x06
#define DWOTP_OTP_STAT              0x08
#define DWOTP_OTP_RDAT              0x0A
#define DWOTP_OTP_SRDAT             0x0E
#define DWOTP_OTP_SF                0x12

//LDE_IF sub registers
#define DWLDE_LDE_THRESH            0x0000
#define DWLDE_LDE_CFG1              0x0806
#define DWLDE_LDE_PPINDX            0x1000
#define DWLDE_LDE_PPAMPL            0x1002
#define DWLDE_LDE_RXANTD            0x1804
#define DWLDE_LDE_CFG2              0x1806
#define DWLDE_LDE_REPC              0x2804

// Dig Diag sub registers
#define DWDIAG_EVC_CTRL             0x00
#define DWDIAG_EVC_PHE              0x04
#define DWDIAG_EVC_RSE              0x06
#define DWDIAG_EVC_FCG              0x08
#define DWDIAG_EVC_FCE              0x0A
#define DWDIAG_EVC_FFR              0x0C
#define DWDIAG_EVC_OVR              0x0E
#define DWDIAG_EVC_STO              0x10
#define DWDIAG_EVC_PTO              0x12
#define DWDIAG_EVC_FWTO             0x14
#define DWDIAG_EVC_TXFS             0x16
#define DWDIAG_EVC_HPW              0x18
#define DWDIAG_EVC_TPW              0x1A
#define DWDIAG_DIAG_TMC             0x24

// power control sub registers
#define DWPMSC_PMSC_CTRL0           0x00
#define DWPMSC_PMSC_CTRL1           0x04
#define DWPMSC_PMSC_SNOZT           0x0C
#define DWPMSC_PMSC_TXFSEQ          0x26
#define DWPMSC_PMSC_LEDC            0x28


#define DW1000_WRITE_FLAG           0x80 // First Bit of the address has to be 1 to indicate we want to write
#define DW1000_SUBADDRESS_FLAG      0x40 // if we have a sub address second Bit has to be 1
#define DW1000_2_SUBADDRESS_FLAG    0x80 // if we have a long sub adress (more than 7 Bit) we set this Bit in the first part

/**
* The supported radio modes
* @param defaultConfig Leave everything as it's power up default
* @param tunedDefault The default plus the changes listed in V2.07 of the user manual as recomended changes to the default configuration
* @param user110k The lower data rate options used by Matthias Grob & Manuel Stalder in the origional version of the driver.
*/
typedef enum {defaultConfig, tunedDefault, user110k} UWBMode;

/** A driver for the DW1000 UWB module
*/
class DW1000
{
public:

/** Constructor.
*
*  @param setup The radio mode to configure the unit to use.
*
*/
    DW1000(UWBMode setup, PinName MOSI, PinName MISO, PinName SCLK, PinName CS, PinName IRQ);              // constructor, uses SPI class

/** 
* Sets the callbacks on packet Rx and Tx
* @param callbackRX The function to call on packet Rx complete
* @param callbackTX The function to call on packet Tx complete
*
* set either or both to null to disable the appropriate interupt
*/
    void setCallbacks(void (*callbackRX)(void), void (*callbackTX)(void));                  // setter for callback functions, automatically enables interrupt, if NULL is passed the coresponding interrupt gets disabled

/**
* c++ version of setCallbacks()
* @param tptr object for callbacks
* @param mptrRX method to call on packet Rx complete
* @param mptrTX method to call on packet Tx complete
*
*/
    template<typename T>
    void setCallbacks(T* tptr, void (T::*mptrRX)(void), void (T::*mptrTX)(void)) {      // overloaded setter to treat member function pointers of objects
        callbackRX.attach(tptr, mptrRX);                                                    // possible client code: dw.setCallbacks(this, &A::callbackRX, &A::callbackTX);
        callbackTX.attach(tptr, mptrTX);                                                    // concept seen in line 100 of http://developer.mbed.org/users/mbed_official/code/mbed/docs/4fc01daae5a5/InterruptIn_8h_source.html
        setInterrupt(true,true);
    }

    // Device API
/** Read the device ID
* @return the device ID (0xDECA0130)
*/
    uint32_t getDeviceID();                                                                 // gets the Device ID which should be 0xDECA0130 (good for testing SPI!)
    
/** Read the Extended Unique ID
* @return The device EUI as stored in the system registers
*/
    uint64_t getEUI();  
    
    /** Set the Extended Unique ID
    * @param EUI The EUID to use
    *
    * Note - ID is only valid until the next power cycle and overrides the value in the OTP memory.
    * To set a value that is automatically loaded on startup set OTP memory addresses 0 and 1.
    */
    void setEUI(uint64_t EUI);                                                              // sets 64 bit Extended Unique Identifier according to IEEE standard

/** Read voltage input

@return the current device voltage
    
    For accurate ranging the voltage of the device should be taken into account.
    User manual give variation as ~5.35cm / V
*/
    float getVoltage();                                                                     // gets the current chip voltage measurement form the A/D converter
    
    /** Read on board temperature sensor
    @return The temperature in C
    
    For accurate ranging the temperature of the device should be taken into account.
    User manual give variation as ~2.15mm / C
*/
    float getTemperature();                                                                 // gets the current chip temperature measurement form the A/D converter

/** Get the status register
* @return The system status register
*
* See user manual section 7.2.17 for details
*/
    uint64_t getStatus();                                                                   // get the 40 bit device status

/** Get the last packet recieve time
* @return the internal time stamp for the last packet Rx
*
* Time is counted on a clock running at 499.2MHz * 128 (~15.65ps)
* This value is raw time minus user set Rx antenna delay.
*/
    uint64_t getRXTimestamp();
    
/** Get the last packet transmit time
* @return the internal time stamp for the last packet Tx
*
* Time is counted on a clock running at 499.2MHz * 128 (~15.65ps)
* This value is raw time plus user set Tx antenna delay to give time at the antenna.
*/   
    uint64_t getTXTimestamp();

/** Send a packet
* @param message A buffer containing the data to send
* @param length The length of the data in bytes.
*
* The supplied packet is transmitted as soon as possible and the reciever re-enabled once transmission is complete.
* Maximum packet size is 125 bytes.
*/ 
    void sendFrame(uint8_t* message, uint16_t length);                                      // send a raw frame (length in bytes)
    
/** Send a packet at a certain time
* @param message A buffer containing the data to send
* @param length The length of the data in bytes.
* @param TxTimestamp The timestamp to send the packet.
*
* The supplied packet is transmitted once the internal clock reaches the specified timestamp.
* Maximum packet size is 125 bytes.
* Rx is disabled as soon as this command is issued and re-enabled once transmission is complete.
* Note - 9 LSBs are ignored so timings are only accurate to ~8ns. For more accurate timing check the
* tx timestamp after transmission is complete.
*/    
    void sendDelayedFrame(uint8_t* message, uint16_t length, uint64_t TxTimestamp);

/** Set up data for a transmit on sync
* @param message A buffer containing the data to send
* @param length The length of the data in bytes.
*
* Data is loaded into the transmit buffer but the transmission is not started.
* Maximum packet size is 125 bytes.
*/
    void setupSyncedFrame(uint8_t* message, uint16_t length);

/** Transmit on the next sync pulse
*
* On the next rising edge of the sync line the transmitter will be activated.
* The packet must have previously been set up using setupSyncedFrame()
*
* Rx is disabled until transmission is complete.
*/
    void armSyncedFrame();

/** Enable reciever
*
* This is automatically done after each Tx completes but can also be forced manually
*/
    void startRX();                                                                         // start listening for frames
    
/** Disable radio link
*
* Disables both the recieve and transmit systems.
* Any transmissions waiting for a delayed time or sync pulse will be canceled.
*/
    void stopTRX();                                                                         // disable tranceiver go back to idle mode

/** Set receive antenna delay
* @param ticks Delay in system clock cycles
*/
    void setRxDelay(uint16_t ticks);
/** Set transmit antenna delay
* @param ticks Delay in system clock cycles
*/
    void setTxDelay(uint16_t ticks);

/** Get last packet size
* @return The length in bytes of the last packet received
*/
    uint16_t getFramelength();                                                              // to get the framelength of the received frame from the PHY header

/** Get last recieved packet
* @param buffer The location to put the received data
* @param length The number of bytes to read
*/
    void readRxBuffer( uint8_t *buffer, int length ) {
        readRegister(DW1000_RX_BUFFER, 0, buffer, length);
    }

/** Read a value from the OTP memory
* @param word_address The OTP memory address to read.
* @return The 32 bit value at that address.
*
* See Section 6.3.1 of the user manual for the memory map.
*/
    uint32_t readOTP (uint16_t word_address);

/** Write a value to the OTP memory
* @param word_address The OTP memory address to read.
* @param data The value to write
* @return True if the write was sucessful.
*
* Writes the supplied data to the OTP memory and then reads it back to verify it was sucessfully programmed.
* Note - this is a one time operation for each memory address.
* See Section 6.3.1 of the user manual for the memory map.
* It is recommened that the device is reset or power cycled after programing.
*/
    bool writeOTP(uint16_t word_address,uint32_t data);                                          // program a value in the OTP. It is recommended to reset afterwards.

protected:

/** Reset the reciever logic
*
* This should be done after any receive errors
*/
    void resetRX();                                                                         // soft reset only the tranciever part of DW1000
    
/** Enable/Disable interrupts
* @param RX true to enable recieve interrupts
* @param TX true to enable transmit interrupts
*
* For c style callbacks simply set the callback to null to disable it.
* When using c++ style callbacks both are enabled as default, this allows a method to disabled one or both.
*/
    void setInterrupt(bool RX, bool TX);                                                    // set Interrupt for received a good frame (CRC ok) or transmission done


private:
    void resetAll();                                                                        // soft reset the entire DW1000 (some registers stay as they were see User Manual)
    void loadLDE();                                                                         // load the leading edge detection algorithm to RAM, [IMPORTANT because receiving malfunction may occur] see User Manual LDELOAD on p22 & p158
    void loadLDOTUNE();                                                                     // load the LDO tuning as set in the factory


    // Interrupt
    InterruptIn irq;                                                                        // Pin used to handle Events from DW1000 by an Interrupthandler
    FunctionPointer callbackRX;                                                             // function pointer to callback which is called when successfull RX took place
    FunctionPointer callbackTX;                                                             // function pointer to callback which is called when successfull TX took place
    void ISR();                                                                             // interrupt handling method (also calls according callback methods)

    // SPI Inteface
    SPI spi;                                                                                // SPI Bus
    DigitalOut cs;                                                                          // Slave selector for SPI-Bus (here explicitly needed to start and end SPI transactions also usable to wake up DW1000)

    uint8_t readRegister8(uint8_t reg, uint16_t subaddress);                                // expressive methods to read or write the number of bits written in the name
    uint16_t readRegister16(uint8_t reg, uint16_t subaddress);
    uint32_t readRegister32(uint8_t reg, uint16_t subaddress);
    uint64_t readRegister40(uint8_t reg, uint16_t subaddress);
    uint64_t readRegister64(uint8_t reg, uint16_t subaddress);
    void writeRegister8(uint8_t reg, uint16_t subaddress, uint8_t buffer);
    void writeRegister16(uint8_t reg, uint16_t subaddress, uint16_t buffer);
    void writeRegister32(uint8_t reg, uint16_t subaddress, uint32_t buffer);
    void writeRegister40(uint8_t reg, uint16_t subaddress, uint64_t buffer);

    void readRegister(uint8_t reg, uint16_t subaddress, uint8_t *buffer, int length);       // reads the selected part of a slave register into the buffer memory
    void writeRegister(uint8_t reg, uint16_t subaddress, uint8_t *buffer, int length);      // writes the buffer memory to the selected slave register
    void setupTransaction(uint8_t reg, uint16_t subaddress, bool write);                    // sets up an SPI read or write transaction with correct register address and offset
    void select();                                                                          // selects the only slave for a transaction
    void deselect();                                                                        // deselects the only slave after transaction
};

#endif