DRV2605.h

00001 /*
00002     Bryce Williams 10/16/2015
00003     
00004     Library for the TI DRV2605L 2 to 5.2 V Haptic Driver for LRA and ERM
00005     With Effect Library and Smart-Loop Architecture
00006      
00007     References:
00008     http://www.ti.com/product/DRV2605L/description&lpos=Middle_Container&lid=Alternative_Devices
00009     http://www.ti.com/lit/ds/symlink/drv2605l.pdf (Datasheet) 
00010     http://www.ti.com/lit/an/sloa189/sloa189.pdf (Setup Guide; SLOA189)
00011 */
00012 
00013 #ifndef DRV2605_H
00014 #define DRV2605_H
00015 
00016 #include "mbed.h"
00017 
00018 /******************************************************************************
00019 ***** DRV2605 Addresses
00020 ******************************************************************************/
00021 #define SLAVE_ADDR_7_BIT 0x5A // 7-bit slave address 
00022 
00023 /******************************************************************************
00024 ****** DRV2605 REGISTERS ******************************************************
00025 ******************************************************************************/
00026 #define STATUS                               0x00
00027 #define MODE                                 0x01
00028 #define REAL_TIME_PLAYBACK                   0x02
00029 #define LIBRARY_SELECTION                    0x03
00030 #define WAVEFORM_SEQUENCER_1                 0x04
00031 #define WAVEFORM_SEQUENCER_2                 0x05
00032 #define WAVEFORM_SEQUENCER_3                 0x06
00033 #define WAVEFORM_SEQUENCER_4                 0x07
00034 #define WAVEFORM_SEQUENCER_5                 0x08
00035 #define WAVEFORM_SEQUENCER_6                 0x09
00036 #define WAVEFORM_SEQUENCER_7                 0x0A
00037 #define WAVEFORM_SEQUENCER_8                 0x0B
00038 #define GO                                   0x0C
00039 #define OVERDRIVE_TIME_OFFSET                0x0D
00040 #define POSITIVE_SUSTAIN_TIME_OFFSET         0x0E
00041 #define NEGATIVE_SUSTAIN_TIME_OFFSET         0x0F
00042 #define BRAKE_TIME_OFFSET                    0x10
00043 #define AUDIO_TO_VIBE_CONTROL                0x11
00044 #define AUDIO_TO_VIBE_MINIMUM_INPUT_LEVEL    0x12
00045 #define AUDIO_TO_VIBE_MAXIMUM_INPUT_LEVEL    0x13
00046 #define AUDIO_TO_VIBE_MINIMUM_OUPUT_DRIVE    0x14
00047 #define AUDIO_TO_VIBE_MAXIMUM_OUTPUT_DRIVE   0x15
00048 #define RATED_VOLTAGE                        0x16
00049 #define OVERDRIVE_CLAMP_VOLTAGE              0x17
00050 #define AUTO_CALIBRATION_COMPENSATION_RESULT 0x18
00051 #define AUTO_CALIBRATION_BACK_EMF_RESULT     0x19
00052 #define FEEDBACK_CONTROL                     0x1A
00053 #define CONTROL                              0x1B
00054 #define CONTROL2                             0x1C
00055 #define CONTROL3                             0x1D
00056 #define CONTROL4                             0x1E
00057 #define CONTROL5                             0x1F
00058 #define LRA_OPEN_LOOP_PERIOD                 0x20
00059 #define VBAT_VOLTAGE_MONITOR                 0x21
00060 #define LRA_RESONANCE_PERIOD                 0x22
00061 
00062 class DRV2605{
00063     
00064     public:
00065         //// modes defines the possible modes of the DRV2605L
00066         enum Mode{
00067             INTERNAL_TRIG,   // 0x00: Waveforms fired by Setting GO bit in Register 0x0C
00068             EXTERNAL_EDGE,   // 0x01: Rising Edge on IN/TRIG pin set GO Bit.
00069             EXTERNAL_LEVEL,  // 0x02: GO bit follows state of edge on IN/TRIG pin. 
00070             PWM_ANALOG,      // 0x03: PWM or Analog Signal accepted at IN/TRIG pin.
00071             AUDIO_TO_VIBE,   // 0x04: An AC-coupled audio signal is accepted at the IN/TRIG pin.
00072             RTP,             // 0x05: Real- Time Playback
00073             DIAG,            // 0x06: Set to perform actuator diagnostics
00074             AUTO_CAL,        // 0x07: Set to perform auto calibration of device for actuator 
00075             STANDBY = 0x40,  // 0x40: Set Device to Software Standby (Low- Power Mode)
00076             RESET = 0x80,    // 0x80: Reset Device (equivalent of power cycling the device)
00077          };
00078          
00079          //// FeedBack_Controls Fields Bitmasks (Register Addr: 0x1A)
00080          enum Actuator_Type{ERM = 0, LRA = 0x80}; // bit-7
00081          enum Brake_Factor{x1 = 0x00, x2 = 0x10, x3 = 0x20, 
00082                            x4 = 0x40, x6 = 0x80, x8 = 0x50, 
00083                            x16 = 0x60, DISABLE = 0x70}; // bit-6..4
00084          enum Loop_Gain{LOW = 0x00, 
00085                         MED = 0x04, 
00086                         HIGH = 0x08, 
00087                         VERY_HIGH = 0x0C};  // bit-3..2
00088                     
00089          enum Library{EMPTY, A, B, C, D, E,
00090                       LRA_LIB, F};              // ROM Waveform Library Selections
00091         
00092         /**
00093             Constructor for DRV2605 Objects
00094         */
00095         DRV2605(PinName sda, PinName scl);
00096         
00097         /**
00098             Write value to specified register of device
00099             @param reg      The device register to write 
00100             @param value    The value to write to the register
00101         */
00102         void i2cWriteByte(char reg, char value);
00103         
00104         /**
00105             Read value from register of device
00106             @param reg  The device register to read
00107             @return     The result
00108         */
00109         uint8_t i2cReadByte(char reg);
00110         
00111         /**
00112             Place device into specified mode
00113             @param mode     The mode to place device into
00114         */
00115         void mode(Mode mode);
00116         
00117         /**
00118             TODO: Expand to allow initialization for LRAs and Closed Loop operation 
00119             Initialize the device for Open- Loop ERM mode using specified ROM 
00120             Waveform Library as specified in Section 9.3 of Device Datasheet.
00121             See also Device Setup Guide 1.6.1 ERM Initialization Example
00122             @param actuator_peak_voltage    The Peak Voltage Rating of Actuator
00123             @param lib  The ROM Waveform Library to use
00124         */
00125         int init(float actuator_peak_voltage, Library lib = B);
00126         
00127         /**
00128             Runs diagnostics on the Actuator and Device and returns the results. 
00129             The results indicate if an actuator is detected, over- current events, 
00130             etc. Refer to STATUS Register (0x00) in device datasheet for more 
00131             description register values.
00132             
00133             Note: This should be run if the user is having trouble getting the actuator 
00134             to work.
00135             
00136             @return The results of the diagnostics (i.e. Status Reg (0x00))
00137         */
00138         uint8_t diagnostics();
00139         
00140         /**
00141             Play single waveform from ROM Library as outlined in Section 9.3.2.1
00142             of Device Datasheet.
00143             The library used is the one that is currently written 
00144             to the Library_Selection Register (0x03). This library
00145             is set in the init(Library lib) method, but can be 
00146             changed manually.
00147             @param waveform_effect  The Waveform Effect Library Index value to play
00148                                     (valid values are 1 to 123)
00149         */
00150         void play_waveform(int waveform_effect);
00151         
00152         /**
00153             Load Wave Sequence into DRV2605 Sequence Registers
00154             @param effect1... effect8   The effect to play. Valid inputs are 
00155                                         0 to 123; 0: Stop Condition, 
00156                                                   1- 123: Waveform Index
00157         */
00158         void load_waveform_sequence(int effect1 = 0, int effect2 = 0, 
00159                                     int effect3 = 0, int effect4 = 0,
00160                                     int effect5 = 0, int effect6 = 0, 
00161                                     int effect7 = 0, int effect8 = 0);
00162         
00163         /**
00164             Plays the currently loaded waveform or waveform sequence. 
00165             Call this after calling play_waveform() or after calling 
00166             load_waveform_sequence()
00167             Preconditions: User must have already loaded waveform(s) 
00168                            using play_waveform() or load_waveform_sequence()
00169         */
00170         void play();
00171         
00172         /**
00173             TODO: Add Closed Loop Calibration
00174             
00175             Run basic DRV2605L Auto- Calibration as detailed in Section 2 of 
00176             the Device Setup Guide for OPEN- LOOP ONLY.
00177             This must be done before using the device in closed- loop mode 
00178             (unless cal has been done before with values stored in non-volatile
00179              mem; see datasheet for more info). 
00180                 
00181             NOTE: It is NOT recommended to store cal values into device 
00182             non-volatile memory as this can be done only once. Thus do not 
00183             use this feature unless the device is being used in a final 
00184             project AND values have been confirmed to result in satisfactory 
00185             performance).
00186                 
00187             This uses many of the default device register values such as
00188             the default DRIVE_TIME .
00189 
00190             @param actuator_peak_voltage The maximum/peak voltage rating of the actuator
00191         */
00192         uint8_t auto_cal_open_loop(float actuator_peak_voltage);        
00193           
00194     private:
00195     I2C i2c;
00196     
00197 };
00198 
00199 #endif