Andy A
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