MCP4xxxx_SPI.h

00001 /* mbed simplified access to Microchip MCP42xxx/MCP41xxx Digital Potentiometer devices (SPI)
00002  * Copyright (c) 2013-2013 ygarcia, MIT License
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software 
00005  * and associated documentation files (the "Software"), to deal in the Software without restriction, 
00006  * including without limitation the rights to use, copy, modify, merge, publish, distribute, 
00007  * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 
00008  * furnished to do so, subject to the following conditions:
00009  *
00010  * The above copyright notice and this permission notice shall be included in all copies or 
00011  * substantial portions of the Software.
00012  *
00013  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING 
00014  * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
00015  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 
00016  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
00017  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00018  */
00019 #if !defined(__MCP4xxxx_SPI_H__)
00020 #define __MCP4xxxx_SPI_H__
00021 
00022 #include <string>
00023 #include <vector>
00024 
00025 #include "Debug.h" // Include mbed header + debug primitives. See DebugLibrary
00026 
00027 namespace MCP4xxxx_SPI {
00028 
00029     /** This class provides simplified SPI access to a Microchip MCP42xxx/MCP41xxx Digital Potentiometer device. V0.0.0.2
00030      * The SPI static settings are: 16bits, mode (0,0)
00031      * This class manages ONLY ONE /CS pin. If more than one SPI devices are used, ALL /CS pins shall be done by the application itself
00032      *
00033      * Microchip MCP42xxx/MCP41xxx Serial EEPROM device reference: DS11195C
00034      * Microchip MCP41xx/MCP42xx Serial EEPROM device reference: DS122060B
00035      *
00036      * Note that MCP41xxx has no SO pin, only a SOI input pin
00037      * Note that MCP42xxx has a SO pin reserved for daisy-chain configuration
00038      * Note that MCP41xx/MCP42xx increment/decrement operations are not supported due to the 16 bits SPI setting
00039      * Note that for SPI details, please visit http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus
00040      *
00041      * @remark This class was validated with Tektronix TDS2014 oscilloscope in 3.3V and in mixte power mode 3.3V for mbed and 5V for the Microchip 24LCxx Serial EEPROM device
00042      * @author Yann Garcia (Don't hesitate to contact me: garcia.yann@gmail.com)
00043      */
00044     class CMCP4xxxx_SPI { 
00045         /** Reference counter used to guarentee unicity of the instance of SPI class
00046          */
00047         static unsigned char SPIModuleRefCounter;
00048         
00049         /** ChipSelect (pin 1) see DS11195C-page 12 Clause 3.4 Chip Select (CS)
00050          */
00051         DigitalOut *_cs;
00052         
00053         /** Reset state indicator (pin 11), see DS11195C-page 21 Clause 5.5 Reset (RS) Pin Operation
00054          */
00055         DigitalOut *_reset;
00056         
00057         /** Shutdown state indicator (pin 12) see DS11195C-page 21 5.6 Shutdown (SHDN) Pin Operation
00058          */
00059         DigitalOut *_shdn;
00060         
00061         /** An unique instance of SPI class
00062          */
00063         SPI *_spiInstance;
00064         /** Increment step value used for inc/dec methods, when inc/dec commands are not supported (such as _4xxxx famillies)
00065          */
00066         unsigned char _incStep;
00067      public:
00068         /** MCP32xx family
00069          */
00070         enum Mcp4xxxFamily {
00071             _41xxx = 0x00,  //<! 41xxx family such as MCP41010 - See DS11195C
00072             _42xxx = 0x01,  //<! 42xxx family such as MCP42010 - See DS11195C
00073             _41xx = 0x02,   //<! 41xx family such as MCP4251 - Single Potentiometer/Rheostat
00074             _42xx = 0x03    //<! 42x2 family such as MCP42x2 - Dual Potentiometer/Rheostat
00075        };
00076         Mcp4xxxFamily _family;     
00077      public:
00078         /** Authorized commands
00079          * See DS11195C-page 18
00080          */
00081         enum Commands {
00082             WriteToDigiPot1,    //<! Write to digital potentiometer #1
00083             WriteToDigiPot2,    //<! Write to digital potentiometer #2
00084             WriteToBoth,        //<! Write to both digital potentiometers
00085             ShutdownDigiPot1,   //<! Shutdown digital potentiometer #1
00086             ShutdownDigiPot2,   //<! Shutdown digital potentiometer #2
00087             ShutdownBoth,       //<! Shutdown both digital potentiometers
00088         };
00089         /** Register adresses
00090          * See DS22060B-page 33 Clause 4.0 FUNCTIONAL OVERVIEW 
00091          */
00092         enum Addresses {
00093             TCon = 0x04,
00094             Status = 0x05
00095         };
00096    public:
00097         /** Constructor with Write Protect command pin wired.
00098          *
00099          * @param p_mosi: MBed pin for SDI
00100          * @param p_miso: MBed pin for SDO. Note that this pin does not exist for MCP41xxx
00101          * @param p_sclk: MBed pin for CLK
00102          * @param p_cs  : MBed pin for Chip Select. If NC, assumes that application manage /CS, default value is NC, not connected
00103          * @param p_reset: MBed pin to manage /RESET input. If NC, /RESET is not managed, default value is NC, not connected
00104          * @param p_shdn: MBed pin to manage /SHDN input. If NC, /SHDN is not managed, default value is NC, not connected
00105          * @param p_frequency: Frequency of the SPI interface (SCK), default value is 1MHz
00106          */
00107         CMCP4xxxx_SPI(const PinName p_mosi, const PinName p_miso, const PinName p_sclk, const PinName p_cs = NC, const PinName p_reset = NC, const PinName p_shdn = NC, const Mcp4xxxFamily family = _41xxx, const unsigned int p_frequency = 1000000);
00108     
00109         /** Destructor
00110          */
00111         virtual ~CMCP4xxxx_SPI();
00112 
00113         /** Used to return the unique instance of SPI instance
00114          */
00115         inline const SPI * operator * () { return (const SPI *)_spiInstance; };
00116 
00117         /** Write a value to the specified register. Only for _41xx/_42xx famillies
00118          * @param p_address The register to be written
00119          * @param p_value The value to write
00120          * @return 0x0000 on success, any value otherwise
00121          */
00122         unsigned short WriteRegister(const Addresses p_address, const unsigned char p_value);
00123         
00124         /** Read the content of the specified register. Only for _41xx/_42xx famillies
00125          * @param p_address The register to be written
00126          * @return The register value 
00127          */
00128         unsigned short ReadRegister(const Addresses p_address);
00129         
00130         /** Increment the specified digital potentiometer
00131          * @param p_command The digital potentiometer to increment. Default: WriteToDigiPot1
00132          * @return 0x0000 on success, any value otherwise
00133          */
00134         unsigned short Increment(const Commands p_command = WriteToDigiPot1);
00135         
00136         /** Decrement the specified digital potentiometer
00137          * @param p_command The digital potentiometer to decrement. Default: WriteToDigiPot1
00138          * @return 0x0000 on success, any value otherwise
00139          */
00140         unsigned short Decrement(const Commands p_command = WriteToDigiPot1);
00141 
00142         /** Send a write a command (WriteToPot1, WriteToPot2 or WriteBoth)
00143          *
00144          * @param p_command The command to execute (See DS11195C-page 18)
00145          * @param p_value The potentiometer selection bits (See DS11195C-page 14 Clause 4.1 Modes of Operation)
00146          * @return 0x0000 on success, 0Xffff otherwise
00147          * Exemple:
00148          * @code
00149          * unsigned char potLevel;
00150          * ...
00151          * g_chipSelect.write(0);
00152          * g_digitalPot.Write(CMCP4xxxx_SPI::WriteToPot2, potLevel);
00153          * g_chipSelect.write(1);
00154          * ...
00155          * @endcode
00156          */
00157         unsigned short Write(const Commands p_command, const unsigned char p_value);
00158     
00159         /** Send a shutdown a command (ShutdownPot1, ShutdownPot2 or ShutdownBoth)
00160          *
00161          * @param p_command The command to execute (See DS11195C-page 18)
00162          * @param p_set Set to true to shutdown, false to set up. Only used for _41xx/_42xx famillies (See DS22060B-page 36 REGISTER 4-2: TCON BITS)
00163          * @return 0x0000 on success, 0Xffff otherwise
00164          * Exemple:
00165          * @code
00166          * ...
00167          * g_chipSelect.write(0);
00168          * g_digitalPot.Shutdown(CMCP4xxxx_SPI::ShutdownPot1);
00169          * g_chipSelect.write(1);
00170          * ...
00171          * @endcode
00172          */
00173         unsigned short Shutdown(const Commands p_command, const bool p_set = true);
00174     
00175          /** Write a NOP command
00176           */
00177         //unsigned short Write();
00178     
00179          /** Change the current family 
00180           * @param family The new type of ICs 
00181           * @return the previous type of ICs 
00182           */
00183         Mcp4xxxFamily SetFamilly(const Mcp4xxxFamily family);
00184     
00185        /** Reset the device
00186         * @code
00187         * unsigned char potLevel;
00188         * ...
00189         * g_digitalPot.Reset();
00190         * ...
00191         * @endcode
00192         */
00193         void Reset();
00194     
00195         /** Shutdown the device
00196          */
00197         void Shutdown(const bool p_set);
00198     
00199     private:
00200         /** Internal reference identifier. Only used when /RS in is available
00201          *
00202          * @param p_set Set to true to shutdown, false to set up
00203          */
00204         std::string _internalId;
00205 
00206     }; // End of class CMCP4xxxx_SPI
00207 
00208 } // End of namespace MCP4xxxx_SPI
00209 
00210 using namespace MCP4xxxx_SPI;
00211 
00212 #endif // __MCP4xxxx_SPI_H__