24LCxx_I2C.h

00001 /* mbed simplified access to Microchip 24LCxx Serial EEPROM devices (I2C)
00002  * Copyright (c) 2010-2012 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(__24LCXX_I2C_H__)
00020 #define __24LCXX_I2C_H__
00021 
00022 #include <string>
00023 #include <vector>
00024 
00025 #include "Debug.h" // Include mbed header + debug primitives. See DebugLibrary
00026 
00027 namespace _24LCXX_I2C {
00028     /** This class provides simplified I2C access to a Microchip 24LCxx Serial EEPROM device. V0.0.0.3
00029      *
00030      * Note that if the LPC1768 is powered in 3.3V and Microchip 24LCxx Serial EEPROM device could be powered at 3.3V or 5V.
00031      * In this case, you shall use a bi-directional level shifter for I2C-bus. Please refer to AN97055 (http://ics.nxp.com/support/documents/interface/pdf/an97055.pdf)
00032      * Microchip 24LCxx Serial EEPROM device reference:
00033      * - 24LC256: DS21203K
00034      * - 24LC64 : DS21189D
00035      *
00036      * Note that for I2C details, please visit http://www.datelec.fr/fiches/I2C.htm
00037      *
00038      * Note that this header file include following headers:
00039      * - <string>
00040      * - <vector>
00041      * - <mbed.h>
00042      *
00043      * @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
00044      * @author Yann Garcia (Don't hesitate to contact me: garcia.yann@gmail.com)
00045      */
00046     class C24LCXX_I2C { // TODO: Add EE Polling for write methods
00047         /** Reference counter used to guarentee unicity of the instance of I2C class
00048          */
00049         static unsigned char I2CModuleRefCounter;
00050         
00051         /** Device address input: A0, A1, A2 (Pins <1,3>). See DS21203K/DS21189D - Figure 5-1: Control Byte Format for address format details
00052          */
00053         unsigned char _slaveAddress;
00054         /** WP state indicator (pin 7); true is write protected, false otherwise
00055          */
00056         DigitalOut *_wp;
00057         /** An unique instance of I2C class
00058          */
00059         I2C *_i2cInstance;
00060     public:
00061         /** Memory storage mode
00062          */
00063         enum Mode {
00064             LittleEndian, //<! Little Endian mode: 0xA0B70708 is stored as 08: MSB and A0 LSB
00065             BigEndian //<! Little Endian mode: 0xA0B70708 is stored as AO: MSB and 08 LSB
00066         };
00067     public:
00068         /** Constructor with Write Protect command pin wired. Use it to manage the first I2C module on 3.3V or 5V network
00069          *
00070          * @param p_sda: MBed pin for SDA
00071          * @param p_scl: MBed pin for SCL
00072          * @param p_address: Device address input: A0, A1, A2 (Pins <1,3>)
00073          * @param p_wp: MBed pin to manage Write Protect input. If NC, WP is not managed, default value is NC, not connected
00074          * @param p_frequency: Frequency of the I2C interface (SCL), default value is 400KHz
00075          * Example:
00076          * - If A1 and A2 pins are tired to Vdd and A0 is tired to Vss, address shall '00000110'B
00077          * - If A0 and A1 pins are tired to Vss and A2 is tired to Vdd, address shall '00000100'B
00078          */
00079         //C24LCXX_I2C(const PinName p_sda, const PinName p_scl, const unsigned char p_address, const PinName p_wp = NC, const unsigned int p_frequency = 400000);
00080         
00081         /* defaults to a 24LC256: 256 kbit, 64Bytes PageSize */
00082         C24LCXX_I2C(const PinName p_sda, const PinName p_scl, const unsigned char p_address, const PinName p_wp = NC, const unsigned int p_frequency = 400000,
00083                     const uint32_t deviceSize = 256, const uint8_t pageSize = 64);
00084     
00085         /** Destructor
00086          */
00087         virtual ~C24LCXX_I2C();
00088 
00089         /** Used to return the unique instance of I2C instance
00090          */
00091         inline const I2C * operator * () { return (const I2C *)_i2cInstance; };
00092 
00093         /** Erase of memory area starting at the specified address, using the specified pattern to fill the memory area
00094          *
00095          * @param p_startAddress The address of the memory area (from 0 to N - 1, N is the number of cells of the memory)
00096          * @param p_count The size of the memory area to erase
00097          * @param p_pattern The pattern value to use to fill the memory area. Default vqlue: 0x00
00098          * @return true on success, false otherwise
00099          * Exemple:
00100          * @code
00101          * ...
00102          * myEEPROM.EraseMemoryArea(0, 1024); // Set to 0x00 the first 1Kb memory 
00103          * ...
00104          * @endcode
00105          */
00106         bool EraseMemoryArea(const short p_startAddress, const int p_count, const unsigned char p_pattern = 0x00);
00107     
00108         /** Write a byte at the specified memory address
00109          *
00110          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00111          * @param p_byte The byte value to save
00112          * @return true on success, false otherwise
00113          * Exemple:
00114          * @code
00115          * unsigned char value = 0xaa;
00116          * ...
00117          * myEEPROM.Write(memoryAddress, value);
00118          * ...
00119          * @endcode
00120          */
00121         bool Write(const short p_address, const unsigned char p_byte);
00122     
00123         /** Write a short at the specified memory address according to the specified mode
00124          *
00125          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00126          * @param p_short The short value to save
00127          * @param p_mode The storage mode. Default value: BigEndian
00128          * @return true on success, false otherwise
00129          * Exemple:
00130          * @code
00131          * short value = 0xcafe;
00132          * ...
00133          * myEEPROM.Write(memoryAddress, value, LittleEndian);
00134          * ...
00135          * @endcode
00136          */
00137         bool Write(const short p_address, const short p_short, const C24LCXX_I2C::Mode p_mode = BigEndian);
00138     
00139         /** Write an integer at the specified memory address according to the specified mode
00140          *
00141          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00142          * @param p_int The integer value to save
00143          * @param p_mode The storage mode. Default value: BigEndian
00144          * @return true on success, false otherwise
00145          * Exemple:
00146          * @code
00147          * int value = 0xcafedeca;
00148          * ...
00149          * myEEPROM.Write(memoryAddress, value, LittleEndian);
00150          * ...
00151          * @endcode
00152          */
00153         bool Write(const short p_address, const int p_int, const C24LCXX_I2C::Mode p_mode = BigEndian);
00154     
00155         /** Write a buffer of bytes at the specified memory address
00156          *
00157          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00158          * @param p_datas The string to save
00159          * @param p_storeLength If true, store also the length of the buffer in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true.
00160          * @param p_length2write The number of bytes to write, -1 for all characters. Default value: -1
00161          * @return true on success, false otherwise
00162          */
00163         bool Write(const short p_address, const std::vector<unsigned char> & p_datas, bool p_storeLength = true, const int p_length2write = -1);
00164     
00165         /** Write a buffer of bytes at the specified memory address
00166          *
00167          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00168          * @param p_datas The buffer of bytes to save
00169          * @param p_storeLength If true, store also the length of the buffer in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true.
00170          * @param p_length2write The number of bytes to write, -1 for all bytes. Default value: -1
00171          * @return true on success, false otherwise
00172          */
00173         bool Write(const short p_address, const unsigned char *p_datas, bool p_storeLength = true, const int p_length2write = -1);
00174     
00175         /** Write a string at the specified memory address
00176          *
00177          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00178          * @param p_string The string to save
00179          * @param p_storeLength If true, store also the length of the string in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true.
00180          * @param p_length2write The number of character to write, -1 for all characters
00181          * @return true on success, false otherwise
00182          * Exemple:
00183          * @code
00184          * std::string text2save("CafeDeca");
00185          * ...
00186          * myEEPROM.Write(memoryAddress, text2save);
00187          * ...
00188          * @endcode
00189          */
00190         bool Write(const short p_address, const std::string & p_string, const bool p_storeLength = true, const int p_length2write = -1);
00191     
00192         /** Write a buffer of characters at the specified memory address (from 0 to N - 1, N is the number of cells of the memory)
00193          *
00194          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00195          * @param p_datas The string to save
00196          * @param p_storeLength If true, store also the length of the string in Big Endian mode, otherwise the length will be provided by p_length2write parameter. Default value: true.
00197          * @param length2write The number of character to write, -1 for all characters
00198          * @return true on success, false otherwise
00199          */
00200         bool Write(const short p_address, const char *p_datas, const bool p_storeLength = true, const int p_length2write = -1);
00201     
00202         /** Read a byte from the specified memory address
00203          *
00204          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00205          * @param p_byte The byte value to read
00206          * @return true on success, false otherwise
00207          * Exemple:
00208          * @code
00209          * unsigned char value;
00210          * ...
00211          * myEEPROM.Read(memoryAddress, (unsigned char *)&value);
00212          * ...
00213          * @endcode
00214          */
00215         bool Read(const short p_address, unsigned char *p_value);
00216     
00217         /** Read a short from the specified memory address
00218          *
00219          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00220          * @param p_short The short value to read
00221          * @return true on success, false otherwise
00222          * Exemple:
00223          * @code
00224          * short value;
00225          * ...
00226          * myEEPROM.Read(memoryAddress, (short *)&value);
00227          * ...
00228          * @endcode
00229          */
00230         bool Read(const short p_address, short *p_short, C24LCXX_I2C::Mode p_mode = BigEndian);
00231     
00232         /** Read an integer from the specified memory address
00233          *
00234          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00235          * @param p_int The integer value to read
00236          * @return true on success, false otherwise
00237          * Exemple:
00238          * @code
00239          * int value;
00240          * ...
00241          * myEEPROM.Read(memoryAddress, (int *)&value);
00242          * ...
00243          * @endcode
00244          */
00245         bool Read(const short p_address, int *p_int, C24LCXX_I2C::Mode p_mode = BigEndian);
00246     
00247         /** Read a buffer of bytes from the specified memory address and store it into a std::vector<unsigned char> object
00248          *
00249          * Note that the size of the buffer object is used for the number of bytes to read
00250          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00251          * @param p_datas The buffer to fill
00252          * @param p_readLengthFirst If true, read the length first and p_length2write parameter is ignored, otherwise the length is provided by p_length2write parameter. Default value: true
00253          * @param p_length2read The number of character to write, -1 to use the size of the string buffer
00254          * @return true on success, false otherwise
00255          * Exemple:
00256          * @code
00257          * std::vector<unsigned char> datas(bufferLength);
00258          * ...
00259          * myEEPROM.Read(memoryAddress, datas);
00260          * ...
00261          * @endcode
00262          */
00263         bool Read(const short p_address, std::vector<unsigned char> & p_datas, bool p_readLengthFirst = true, int p_length2read = -1);
00264     
00265         /** Read a buffer of characters from the specified memory address and store it into a string object
00266          *
00267          * Note that the size of the string object is used for the number of characters to read
00268          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00269          * @param p_string The string buffer to fill
00270          * @param p_readLengthFirst If true, read the length first and p_length2write parameter is ignored, otherwise the length is provided by p_length2write parameter. Default value: true
00271          * @param p_length2write The number of character to write, -1 to use the size of the string buffer
00272          * @return true on success, false otherwise
00273          * Exemple:
00274          * @code
00275          * std::string readtext;
00276          * ...
00277          * myEEPROM.Read(memoryAddress, readtext);
00278          * ...
00279          * @endcode
00280          */
00281         bool Read(const short p_address, std::string & p_string, bool p_readLengthFirst = true, int p_length2write = -1);
00282     
00283         /** Read a buffer of characters from the specified memory address and store it into char array
00284          *
00285          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00286          * @param p_datas The string buffer to fill
00287          * @param p_readLengthFirst If true, read the length first and p_length2write parameter is ignored, otherwise the length is provided by p_length2write parameter. Default value: true
00288          * @param p_length2write The number of character to write, -1 to use the size of the string buffer
00289          * @return true on success, false otherwise
00290          * Exemple:
00291          * @code
00292          * char[255] readtext;
00293          * ...
00294          * myEEPROM.Read(memoryAddress, readtext);
00295          * ...
00296          * @endcode
00297          */
00298         bool Read(const short p_address, unsigned char * p_datas, bool p_readLengthFirst = true, int p_length2write = -1);
00299 
00300         /** Activate or deactivate write protect (pin 7)
00301          *
00302          * Note that a voltage of 3.3V apply to WP input of 24LCxx device is enough to enable write protect
00303          * @param p_writeProtect: Set to true to activate write protection, false otherwise
00304          * @return true on success, false otherwise
00305          */
00306         bool WriteProtect(const bool p_writeProtect);
00307     
00308         /** Indicate the current WP state indicator  (pin 7)
00309          * @return true is write protected, false otherwise
00310          */
00311         inline bool IsWriteProtected() {
00312             return (_wp != NULL) ? (bool)(_wp->read() == 1) : false;
00313         }
00314 
00315 #if defined(__DEBUG)
00316         /** Dump a memory area
00317          * 
00318          * Note that this method is available only on debug mode
00319          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00320          * @param p_count The number of bytes toi dump
00321          * @return true on success, false otherwise
00322          */
00323         void DumpMemoryArea(const int p_address, const int p_count);
00324         /** For debug purpose only
00325          */
00326         inline std::string & ToString() { return _internalId; };
00327 #else // __DEBUG
00328         inline void DumpMemoryArea(const int p_address, const int p_count) {};
00329 #endif // _DEBUG
00330         
00331     private:
00332     
00333         /* write to EEPROM. Take care of pageBoundaries */
00334         int i2cWrite(short address, const char *data, int length);
00335         
00336         /** Internal reference identifier
00337          */
00338         std::string _internalId;
00339         
00340         /** pageSize of device in Bytes
00341         */
00342         uint8_t _pageSize;
00343         
00344         /** Device Size of Device in Kbits
00345         */
00346         uint32_t _deviceSize;
00347         
00348 
00349     }; // End of class C24LCXX_I2C
00350 
00351 } // End of namespace _24LCXX_I2C
00352 
00353 using namespace _24LCXX_I2C;
00354 
00355 #endif // __24LCXX_I2C_H__