FM24Vxx_I2C.h

00001 /* mbed simplified access to RAMTRON FV24xx Serial 3V F-RAM Memory (I2C)
00002  * Copyright (c) 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(__FM24VXX_I2C_H__)
00020 #define __FM24VXX_I2C_H__
00021 
00022 #include <string>
00023 #include <vector>
00024 
00025 #include "FM24Vxx_IDs.h"
00026 #include "FM24Vxx_SN.h"
00027 #include "Debug.h" // Include mbed header + debug primitives. See DebugLibrary
00028 
00029 namespace _FM24VXX_I2C {
00030     /** This class provides simplified I2C access to a RAMTRON FV24xx Serial 3V F-RAM Memory device. V0.0.0.1
00031      *
00032      * Note that RAMTRON FV24xx Serial 3V F-RAM Memory device could be powered at 3.3V or less only.
00033      * Note that this header file include following headers:
00034      * - <string>
00035      * - <vector>
00036      * - <mbed.h>
00037      *
00038      * @author Yann Garcia (Don't hesitate to contact me: garcia.yann@gmail.com)
00039      */
00040     class CFM24VXX_I2C { 
00041         /** Reference counter used to guarentee unicity of the instance of I2C class
00042          */
00043         static unsigned char I2CModuleRefCounter;
00044         
00045         /** Device address input: A1, A2 (Pins <2,3>). See FM24V10_ds.pdf - Clause Pin Configuration
00046          */
00047         unsigned char _slaveAddress;
00048         /** WP state indicator (pin 7); true is write protected, false otherwise
00049          */
00050         DigitalOut *_wp;
00051         /** An unique instance of I2C class
00052          */
00053         I2C *_i2cInstance;
00054         /** Device ID
00055          */
00056         CFM24VXX_IDs *_deviceID;
00057         /** Serial number
00058          */
00059         CFM24VXX_SN *_sn;
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
00069          *
00070          * @param p_sda: MBed pin for SDA
00071          * @param p_scl: MBed pin for SCL
00072          * @param p_address: Device address input: A1, A2 (Pins <2,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 pin is tired to Vdd and A2 is tired to Vss, address shall '00000001'B
00077          */
00078         CFM24VXX_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);
00079     
00080         /** Destructor
00081          */
00082         virtual ~CFM24VXX_I2C();
00083 
00084         /** Used to return the unique instance of I2C instance
00085          */
00086         inline const I2C * operator * () { return (const I2C *)_i2cInstance; };
00087 
00088         /** Used to return the unique device identifier
00089          */
00090         inline const CFM24VXX_IDs * GetDeviceID() { return (const CFM24VXX_IDs *)_deviceID; };
00091 
00092         /** 
00093          * Used to return the serial number
00094          * Note This functionality is available only for the FM24VN10. In other case, it will return 0xff
00095          * @remark See FM24V10_ds.pdf Page 10/16 Clause Unique Serial Number (FM24VN10 only)
00096          */
00097         inline const CFM24VXX_SN * GetSerialNumber() { return (const CFM24VXX_SN *)_sn; };
00098         
00099         /**
00100          * Used to swith high speed mode
00101          * @param highSpeedMode Set to true to switch to high speed mode
00102          * @remark See FM24V10_ds.pdf Page 4/16 Clause High Speed Mode (HS-mode)
00103          */
00104         inline void SwitchSpeedMode(const bool highSpeedMode) { /* FIXME To be done */ };
00105 
00106         /**
00107          * Used to enter in sleep mode
00108          * @remark See FM24V10_ds.pdf Page 8/16 Clause Sleep Mode
00109          */
00110         inline void EnterSleepMode() { /* FIXME To be done */ };
00111 
00112         /**
00113          * Used to leave sleep mode
00114          * @remark See FM24V10_ds.pdf Page 8/16 Clause Sleep Mode
00115          */
00116         inline void LeaveSpeedMode() { /* FIXME To be done */ };
00117         
00118         /**
00119          * Used to select memory page
00120          * @param memoryPage The selected memory page (0 or 1)
00121          * @remark See FM24V10_ds.pdf Page 3/16 Clause Memory Architecture
00122         */
00123         inline void SelectMemoryPage(const unsigned char memoryPage) { _slaveAddress |= ((memoryPage & 0x01) << 1); };
00124 
00125         /** Erase of memory area starting at the specified address, using the specified pattern to fill the memory area
00126          *
00127          * @param p_startAddress The address of the memory area (from 0 to N - 1, N is the number of cells of the memory)
00128          * @param p_count The size of the memory area to erase
00129          * @param p_pattern The pattern value to use to fill the memory area. Default vqlue: 0x00
00130          * @return true on success, false otherwise
00131          * Exemple:
00132          * @code
00133          * ...
00134          * myEEPROM.EraseMemoryArea(0, 1024); // Set to 0x00 the first 1Kb memory 
00135          * ...
00136          * @endcode
00137          */
00138         bool EraseMemoryArea(const short p_startAddress, const int p_count, const unsigned char p_pattern = 0x00);
00139     
00140         /** Write a byte at the specified memory address
00141          *
00142          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00143          * @param p_byte The byte value to save
00144          * @return true on success, false otherwise
00145          * Exemple:
00146          * @code
00147          * unsigned char value = 0xaa;
00148          * ...
00149          * myEEPROM.Write(memoryAddress, value);
00150          * ...
00151          * @endcode
00152          */
00153         bool Write(const short p_address, const unsigned char p_byte);
00154     
00155         /** Write a short at the specified memory address according to the specified mode
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_short The short value to save
00159          * @param p_mode The storage mode. Default value: BigEndian
00160          * @return true on success, false otherwise
00161          * Exemple:
00162          * @code
00163          * short value = 0xcafe;
00164          * ...
00165          * myEEPROM.Write(memoryAddress, value, LittleEndian);
00166          * ...
00167          * @endcode
00168          */
00169         bool Write(const short p_address, const short p_short, const CFM24VXX_I2C::Mode p_mode = BigEndian);
00170     
00171         /** Write an integer at the specified memory address according to the specified mode
00172          *
00173          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00174          * @param p_int The integer value to save
00175          * @param p_mode The storage mode. Default value: BigEndian
00176          * @return true on success, false otherwise
00177          * Exemple:
00178          * @code
00179          * int value = 0xcafedeca;
00180          * ...
00181          * myEEPROM.Write(memoryAddress, value, LittleEndian);
00182          * ...
00183          * @endcode
00184          */
00185         bool Write(const short p_address, const int p_int, const CFM24VXX_I2C::Mode p_mode = BigEndian);
00186     
00187         /** Write a buffer of bytes at the specified memory address
00188          *
00189          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00190          * @param p_datas The string to save
00191          * @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.
00192          * @param p_length2write The number of bytes to write, -1 for all characters. Default value: -1
00193          * @return true on success, false otherwise
00194          */
00195         bool Write(const short p_address, const std::vector<unsigned char> & p_datas, bool p_storeLength = true, const int p_length2write = -1);
00196     
00197         /** Write a buffer of bytes at the specified memory address
00198          *
00199          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00200          * @param p_datas The buffer of bytes to save
00201          * @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.
00202          * @param p_length2write The number of bytes to write, -1 for all bytes. Default value: -1
00203          * @return true on success, false otherwise
00204          */
00205         bool Write(const short p_address, const unsigned char *p_datas, bool p_storeLength = true, const int p_length2write = -1);
00206     
00207         /** Write a string at the specified memory address
00208          *
00209          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00210          * @param p_string The string to save
00211          * @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.
00212          * @param p_length2write The number of character to write, -1 for all characters
00213          * @return true on success, false otherwise
00214          * Exemple:
00215          * @code
00216          * std::string text2save("CafeDeca");
00217          * ...
00218          * myEEPROM.Write(memoryAddress, text2save);
00219          * ...
00220          * @endcode
00221          */
00222         bool Write(const short p_address, const std::string & p_string, const bool p_storeLength = true, const int p_length2write = -1);
00223     
00224         /** Write a buffer of characters at the specified memory address (from 0 to N - 1, N is the number of cells of the memory).
00225          *  The NULL character is not written.
00226          *
00227          * Note that the length of the buffer is not saved and the string is saved in Big Endian mode
00228          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00229          * @param p_string The string to save
00230          * @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.
00231          * @param length2write The number of character to write, -1 for all characters
00232          * @return true on success, false otherwise
00233          */
00234         bool Write(const short p_address, const char *p_string, const bool p_storeLength = true, const int p_length2write = -1);
00235     
00236         /** Read a byte from the specified memory address
00237          *
00238          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00239          * @param p_byte The byte value to read
00240          * @return true on success, false otherwise
00241          * Exemple:
00242          * @code
00243          * unsigned char value;
00244          * ...
00245          * myEEPROM.Read(memoryAddress, (unsigned char *)&value);
00246          * ...
00247          * @endcode
00248          */
00249         bool Read(const short p_address, unsigned char *p_value);
00250     
00251         /** Read a short from the specified memory address
00252          *
00253          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00254          * @param p_short The short value to read
00255          * @return true on success, false otherwise
00256          * Exemple:
00257          * @code
00258          * short value;
00259          * ...
00260          * myEEPROM.Read(memoryAddress, (short *)&value);
00261          * ...
00262          * @endcode
00263          */
00264         bool Read(const short p_address, short *p_short, CFM24VXX_I2C::Mode p_mode = BigEndian);
00265     
00266         /** Read an integer from the specified memory address
00267          *
00268          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00269          * @param p_int The integer value to read
00270          * @return true on success, false otherwise
00271          * Exemple:
00272          * @code
00273          * int value;
00274          * ...
00275          * myEEPROM.Read(memoryAddress, (int *)&value);
00276          * ...
00277          * @endcode
00278          */
00279         bool Read(const short p_address, int *p_int, CFM24VXX_I2C::Mode p_mode = BigEndian);
00280     
00281         /** Read a buffer of bytes from the specified memory address and store it into a std::vector<unsigned char> object
00282          *
00283          * Note that the size of the buffer object is used for the number of bytes to read
00284          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00285          * @param p_datas The buffer to fill
00286          * @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
00287          * @param p_length2read The number of character to write, -1 to use the size of the string buffer
00288          * @return true on success, false otherwise
00289          * Exemple:
00290          * @code
00291          * std::vector<unsigned char> datas(bufferLength);
00292          * ...
00293          * myEEPROM.Read(memoryAddress, datas);
00294          * ...
00295          * @endcode
00296          */
00297         bool Read(const short p_address, std::vector<unsigned char> & p_datas, bool p_readLengthFirst = true, int p_length2read = -1);
00298     
00299         /** Read a buffer of characters from the specified memory address and store it into a string object
00300          *
00301          * Note that the size of the string object is used for the number of characters to read
00302          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00303          * @param p_string The string buffer to fill
00304          * @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
00305          * @param p_length2write The number of character to write, -1 to use the size of the string buffer
00306          * @return true on success, false otherwise
00307          * Exemple:
00308          * @code
00309          * std::string readtext;
00310          * ...
00311          * myEEPROM.Read(memoryAddress, readtext);
00312          * ...
00313          * @endcode
00314          */
00315         bool Read(const short p_address, std::string & p_string, bool p_readLengthFirst = true, int p_length2write = -1);
00316         
00317         /** Read a buffer of characters at the specified memory address. The NULL character is not read.
00318          *
00319          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00320          * @param p_string The string to read
00321          * @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.
00322          * @param p_length2write The number of characters to write, -1 for all bytes. Default value: -1
00323          * @return true on success, false otherwise
00324          */
00325         bool Read(const short p_address, char *p_string, const bool p_storeLength = true, const int p_length2write = -1);
00326         
00327         /** Activate or deactivate write protect (pin 7)
00328          *
00329          * @param p_writeProtect: Set to true to activate write protection, false otherwise
00330          * @return true on success, false otherwise
00331          */
00332         bool WriteProtect(const bool p_writeProtect);
00333     
00334         /** Indicate the current WP state indicator  (pin 7)
00335          * @return true is write protected, false otherwise
00336          */
00337         inline bool IsWriteProtected() {
00338             return (_wp != NULL) ? (bool)(_wp->read() == 1) : false;
00339         }
00340 
00341 #if defined(__DEBUG)
00342         /** Dump a memory area
00343          * 
00344          * Note that this method is available only on debug mode
00345          * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
00346          * @param p_count The number of bytes toi dump
00347          * @return true on success, false otherwise
00348          */
00349         void DumpMemoryArea(const int p_address, const int p_count);
00350         /** For debug purpose only
00351          */
00352         inline std::string & ToString() { return _internalId; };
00353 #else // __DEBUG
00354         inline void DumpMemoryArea(const int p_address, const int p_count) {};
00355 #endif // _DEBUG
00356         
00357     private:
00358         /** Internal reference identifier
00359          */
00360         std::string _internalId;
00361 
00362     private:
00363 
00364         /** Retrieve device identifiers
00365          * @remark See FM24V10_ds.pdf Page 9/16 Clause Device ID
00366          */
00367         bool GetDevideIDs();
00368     
00369         /** 
00370          * Used to return the serial number
00371          * Note This functionality is available only for the FM24VN10. In other case, it will return 0xff
00372          * @remark See FM24V10_ds.pdf Page 10/16 Clause Unique Serial Number (FM24VN10 only)
00373          */
00374         bool GetSerialNumbers();
00375         
00376         /**
00377          * Function to Calculate CRC
00378          * @param pdatas The read Serial Number
00379          * @param length The number of bytes in the pdatas array. Default: 7 bytes length
00380          * @return The 8-bits length checksum
00381          * @see See FM24V10_ds.pdf Page 10/16 Clause Unique Serial Number (FM24VN10 only)
00382          */
00383         unsigned char ChecksumSN(const unsigned char *pdatas, const unsigned int length = 7);
00384 
00385     }; // End of class CFM24VXX_I2C
00386 
00387 }; // End of namespace _FM24VXX_I2C
00388 
00389 using namespace _FM24VXX_I2C;
00390 
00391 #endif // __FM24VXX_I2C_H__