DW1000 UWB driver based on work of Matthias Grob & Manuel Stalder - ETH Zürich - 2015
Diff: DW1000.h
- Revision:
- 6:2c77afdf7367
- Parent:
- 5:68ffaa5962d1
- Child:
- 7:b13881dbb09d
--- a/DW1000.h Thu Apr 07 16:27:51 2016 +0000 +++ b/DW1000.h Mon Apr 11 14:45:44 2016 +0000 @@ -186,28 +186,44 @@ } /// enum for PRF options - enum prf_e {prf16MHz,prf64MHz}; + enum prf_e {prf16MHz, ///< PRF rate of 16MHz. Lower power + prf64MHz ///< PRF rate of 64MHz. Higher power but more accurate timing. + }; + +/// enum for data rate options + enum dataRate_e {kbps110, ///< Data rate of 110kb/s (non-standard) + kbps850,///< Data rate of 850kb/s + kbps6800///< Data rate of 6.8Mb/s + }; -/// enum for data rate options - enum dataRate_e {kbps110,kbps850,kbps6800}; - -/// enum for SFD options - enum sfd_e {standard, decaWave, user}; - -/// enum for preamble length options - enum preamble_e { pre64, pre128, pre256, pre512, pre1024, pre1536, pre2048, pre4096}; +/// enum for SFD options + enum sfd_e {standard, ///< IEEE standard SFD + decaWave, ///< Decawave defined SFD + user ///< user defined SFD + }; -/** Set the PRF -* @return true if a valid option -*/ +/// enum for preamble length options + enum preamble_e { pre64,///< Preamble is 64 symbols + pre128,///< Preamble is 128 symbols (non-standard) + pre256,///< Preamble is 256 symbols (non-standard) + pre512,///< Preamble is 512 symbols (non-standard) + pre1024,///< Preamble is 1024 symbols + pre1536,///< Preamble is 1536 symbols (non-standard) + pre2048, ///< Preamble is 2048 symbols (non-standard) + pre4096///< Preamble is 4096 symbols + }; + + /** Set the PRF + * @return true if a valid option + */ bool setPRF(enum prf_e newSetting) { prf = newSetting; return true; }; -/** Set the Channel -* @return true if a valid option -*/ + /** Set the Channel + * @return true if a valid option + */ bool setChannel(unsigned char newChannel) { if ((channel > 0) && ((channel <= 5) || (channel == 7))) { channel = newChannel; @@ -215,33 +231,33 @@ } return false; }; -/** Set the SFD -* @return true if a valid option -*/ + /** Set the SFD + * @return true if a valid option + */ bool setSfd(enum sfd_e newSetting) { sfd = newSetting; return true; }; -/** Set the Preamble length -* @return true if a valid option -*/ + /** Set the Preamble length + * @return true if a valid option + */ bool setPreambleLength(enum preamble_e newSetting) { preamble = newSetting; return true; }; -/** Set the Data rate -* @return true if a valid option -*/ + /** Set the Data rate + * @return true if a valid option + */ bool setDataRate(enum dataRate_e newSetting) { dataRate = newSetting; return true; }; -/** Set the Preamble code -* @return true if a valid option -* -* note - not all codes are valid for all channels. Set the channel first. -* TODO - enforce code restrictions -*/ + /** Set the Preamble code + * @return true if a valid option + * + * note - not all codes are valid for all channels. Set the channel first. + * TODO - enforce code restrictions + */ bool setPreambleCode(unsigned char newCode) { if ((newCode > 0) && (newCode <= 24)) { preambleCode = newCode; @@ -249,36 +265,54 @@ } return false; }; -/** Set the smartpower state -* @return true if a valid option -* -* only takes effect at 6.8Mb/s -*/ + /** Set the smartpower state + * @return true if a valid option + * + * only takes effect at 6.8Mb/s + */ bool setSmartPower(bool enable) { enableSmartPower = enable; return true; }; -/** Get the current channel -* @return the channel number -*/ + /** Get the current channel + * @return the channel number + */ unsigned char getChannel() { return channel; }; + /** Get the current PRF + * @return the PRF + */ enum prf_e getPRF() { return prf; }; - enum dataRate_e getDataRate() { + /** Get the current data rate + * @return the data rate + */ enum dataRate_e getDataRate() { return dataRate; }; - - enum sfd_e getSfd() {return sfd;}; - enum preamble_e getPreambleLength() { + + /** Get the current SFD mode + * @return the SFD + */ enum sfd_e getSfd() { + return sfd; + }; + /** Get the current preamble length + * @return the preamble length + */ + enum preamble_e getPreambleLength() { return preamble; }; + /** Get the current preamble code + * @return the preamble code + */ unsigned char getPreambleCode() { return preambleCode; }; + /** Get the current smart power mode + * @return true if smartpower is on + */ bool getSmartPower() { return enableSmartPower; }; @@ -302,8 +336,30 @@ { public: + /** Constructor. + * + * @param setup The radio mode to configure the unit to use. + * + * Valid setup values are defaultConfig, tunedDefault, user110k + */ 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); @@ -312,38 +368,160 @@ } // 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. + /** Get setup description * * @param buffer Data buffer to place description in @@ -354,7 +532,19 @@ void getSetup(char *buffer, int len); 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 /** Set Transmit gain