Diff: DW1000.h

Revision:

16:2080adef6fa6

Parent:

1:dcbd071f38d5

diff -r dcbd071f38d5 -r 2080adef6fa6 DW1000.h
--- a/DW1000.h	Tue Apr 05 11:37:23 2016 +0000
+++ b/DW1000.h	Tue Apr 05 13:43:54 2016 +0000
@@ -152,14 +152,43 @@
 #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);
@@ -168,40 +197,174 @@
     }
 
     // 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!)
-    uint64_t getEUI();                                                                      // gets 64 bit Extended Unique Identifier according to IEEE standard
+    
+/** 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();
 
-    void sendString(char* message);                                                         // to send String with arbitrary length
-    void receiveString(char* message);                                                      // to receive char string (length of the buffer must be 1021 to be safe)
+/** 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