Diff: FM24Vxx_I2C.h

Revision:

0:fa858f79d48d

Child:

1:6a16bddd7222

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/FM24Vxx_I2C.h	Sat Mar 23 15:54:01 2013 +0000
@@ -0,0 +1,353 @@
+/* mbed simplified access to RAMTRON FV24xx Serial 3V F-RAM Memory (I2C)
+ * Copyright (c) 2013 ygarcia, MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software 
+ * and associated documentation files (the "Software"), to deal in the Software without restriction, 
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, 
+ * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or 
+ * substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING 
+ * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+#if !defined(__FM24VXX_I2C_H__)
+#define __FM24VXX_I2C_H__
+
+#include <string>
+#include <vector>
+
+#include "FM24Vxx_IDs.h"
+#include "Debug.h" // Include mbed header + debug primitives. See DebugLibrary
+
+namespace _FM24VXX_I2C {
+    /** This class provides simplified I2C access to a RAMTRON FV24xx Serial 3V F-RAM Memory device. V0.0.0.1
+     *
+     * Note that RAMTRON FV24xx Serial 3V F-RAM Memory device could be powered at 3.3V or less only.
+     * Note that this header file include following headers:
+     * - <string>
+     * - <vector>
+     * - <mbed.h>
+     *
+     * @author Yann Garcia (Don't hesitate to contact me: garcia.yann@gmail.com)
+     */
+    class CFM24VXX_I2C { 
+        /** Reference counter used to guarentee unicity of the instance of I2C class
+         */
+        static unsigned char I2CModuleRefCounter;
+        
+        /** Device address input: A1, A2 (Pins <2,3>). See FM24V10_ds.pdf - Clause Pin Configuration
+         */
+        unsigned char _slaveAddress;
+        /** WP state indicator (pin 7); true is write protected, false otherwise
+         */
+        DigitalOut *_wp;
+        /** An unique instance of I2C class
+         */
+        I2C *_i2cInstance;
+        /** Device ID. Used for Sleep mode
+         */
+        CFM24VXX_IDs *_deviceID;
+    public:
+        /** Memory storage mode
+         */
+        enum Mode {
+            LittleEndian, //<! Little Endian mode: 0xA0B70708 is stored as 08: MSB and A0 LSB
+            BigEndian //<! Little Endian mode: 0xA0B70708 is stored as AO: MSB and 08 LSB
+        };
+    public:
+        /** Constructor with Write Protect command pin wired. Use it to manage the first I2C module
+         *
+         * @param p_sda: MBed pin for SDA
+         * @param p_scl: MBed pin for SCL
+         * @param p_address: Device address input: A1, A2 (Pins <2,3>)
+         * @param p_wp: MBed pin to manage Write Protect input. If NC, WP is not managed, default value is NC, not connected
+         * @param p_frequency: Frequency of the I2C interface (SCL), default value is 400KHz
+         * Example:
+         * - If A1 pin is tired to Vdd and A2 is tired to Vss, address shall '00000001'B
+         */
+        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);
+    
+        /** Destructor
+         */
+        virtual ~CFM24VXX_I2C();
+
+        /** Used to return the unique instance of I2C instance
+         */
+        inline const I2C * operator * () { return (const I2C *)_i2cInstance; };
+
+        /** Used to return the unique device identifier
+         */
+        inline const CFM24VXX_IDs * GetDevideID() { return (const CFM24VXX_IDs *)_deviceID; };
+
+        /**
+         * Used to swith high speed mode
+         * @param highSpeedMode Set to true to switch to high speed mode
+         * @remark See FM24V10_ds.pdf Page 4/16 Clause High Speed Mode (HS-mode)
+         */
+        inline void SwitchSpeedMode(const bool highSpeedMode) { /* FIXME To be done */ };
+
+        /**
+         * Used to enter in sleep mode
+         * @remark See FM24V10_ds.pdf Page 8/16 Clause Sleep Mode
+         */
+        inline void EnterSleepMode() { /* FIXME To be done */ };
+
+        /**
+         * Used to enter in sleep mode
+         * @remark See FM24V10_ds.pdf Page 8/16 Clause Sleep Mode
+         */
+        inline void LeaveSpeedMode() { /* FIXME To be done */ };
+        
+        /**
+         * Used to select memory page
+         * @param memoryPage The selected memory page (0 or 1)
+         * @remark See FM24V10_ds.pdf Page 3/16 Clause Memory Architecture
+        */
+        inline void SelectMemoryPage(const unsigned char memoryPage) { _slaveAddress |= ((memoryPage & 0x01) << 1) | 0xa0; };
+
+        /** Erase of memory area starting at the specified address, using the specified pattern to fill the memory area
+         *
+         * @param p_startAddress The address of the memory area (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_count The size of the memory area to erase
+         * @param p_pattern The pattern value to use to fill the memory area. Default vqlue: 0x00
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * ...
+         * myEEPROM.EraseMemoryArea(0, 1024); // Set to 0x00 the first 1Kb memory 
+         * ...
+         * @endcode
+         */
+        bool EraseMemoryArea(const short p_startAddress, const int p_count, const unsigned char p_pattern = 0x00);
+    
+        /** Write a byte at the specified memory address
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_byte The byte value to save
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * unsigned char value = 0xaa;
+         * ...
+         * myEEPROM.Write(memoryAddress, value);
+         * ...
+         * @endcode
+         */
+        bool Write(const short p_address, const unsigned char p_byte);
+    
+        /** Write a short at the specified memory address according to the specified mode
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_short The short value to save
+         * @param p_mode The storage mode. Default value: BigEndian
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * short value = 0xcafe;
+         * ...
+         * myEEPROM.Write(memoryAddress, value, LittleEndian);
+         * ...
+         * @endcode
+         */
+        bool Write(const short p_address, const short p_short, const CFM24VXX_I2C::Mode p_mode = BigEndian);
+    
+        /** Write an integer at the specified memory address according to the specified mode
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_int The integer value to save
+         * @param p_mode The storage mode. Default value: BigEndian
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * int value = 0xcafedeca;
+         * ...
+         * myEEPROM.Write(memoryAddress, value, LittleEndian);
+         * ...
+         * @endcode
+         */
+        bool Write(const short p_address, const int p_int, const CFM24VXX_I2C::Mode p_mode = BigEndian);
+    
+        /** Write a buffer of bytes at the specified memory address
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_datas The string to save
+         * @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.
+         * @param p_length2write The number of bytes to write, -1 for all characters. Default value: -1
+         * @return true on success, false otherwise
+         */
+        bool Write(const short p_address, const std::vector<unsigned char> & p_datas, bool p_storeLength = true, const int p_length2write = -1);
+    
+        /** Write a buffer of bytes at the specified memory address
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_datas The buffer of bytes to save
+         * @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.
+         * @param p_length2write The number of bytes to write, -1 for all bytes. Default value: -1
+         * @return true on success, false otherwise
+         */
+        bool Write(const short p_address, const unsigned char *p_datas, bool p_storeLength = true, const int p_length2write = -1);
+    
+        /** Write a string at the specified memory address
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_string The string to save
+         * @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.
+         * @param p_length2write The number of character to write, -1 for all characters
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * std::string text2save("CafeDeca");
+         * ...
+         * myEEPROM.Write(memoryAddress, text2save);
+         * ...
+         * @endcode
+         */
+        bool Write(const short p_address, const std::string & p_string, const bool p_storeLength = true, const int p_length2write = -1);
+    
+        /** Write a buffer of characters at the specified memory address (from 0 to N - 1, N is the number of cells of the memory)
+         *
+         * Note that the length of the buffer is not saved and the string is saved in Big Endian mode
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_datas The string to save
+         * @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.
+         * @param length2write The number of character to write, -1 for all characters
+         * @return true on success, false otherwise
+         */
+        bool Write(const short p_address, const char *p_datas, const bool p_storeLength = true, const int p_length2write = -1);
+    
+        /** Read a byte from the specified memory address
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_byte The byte value to read
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * unsigned char value;
+         * ...
+         * myEEPROM.Read(memoryAddress, (unsigned char *)&value);
+         * ...
+         * @endcode
+         */
+        bool Read(const short p_address, unsigned char *p_value);
+    
+        /** Read a short from the specified memory address
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_short The short value to read
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * short value;
+         * ...
+         * myEEPROM.Read(memoryAddress, (short *)&value);
+         * ...
+         * @endcode
+         */
+        bool Read(const short p_address, short *p_short, CFM24VXX_I2C::Mode p_mode = BigEndian);
+    
+        /** Read an integer from the specified memory address
+         *
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_int The integer value to read
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * int value;
+         * ...
+         * myEEPROM.Read(memoryAddress, (int *)&value);
+         * ...
+         * @endcode
+         */
+        bool Read(const short p_address, int *p_int, CFM24VXX_I2C::Mode p_mode = BigEndian);
+    
+        /** Read a buffer of bytes from the specified memory address and store it into a std::vector<unsigned char> object
+         *
+         * Note that the size of the buffer object is used for the number of bytes to read
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_datas The buffer to fill
+         * @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
+         * @param p_length2read The number of character to write, -1 to use the size of the string buffer
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * std::vector<unsigned char> datas(bufferLength);
+         * ...
+         * myEEPROM.Read(memoryAddress, datas);
+         * ...
+         * @endcode
+         */
+        bool Read(const short p_address, std::vector<unsigned char> & p_datas, bool p_readLengthFirst = true, int p_length2read = -1);
+    
+        /** Read a buffer of characters from the specified memory address and store it into a string object
+         *
+         * Note that the size of the string object is used for the number of characters to read
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_string The string buffer to fill
+         * @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
+         * @param p_length2write The number of character to write, -1 to use the size of the string buffer
+         * @return true on success, false otherwise
+         * Exemple:
+         * @code
+         * std::string readtext;
+         * ...
+         * myEEPROM.Read(memoryAddress, readtext);
+         * ...
+         * @endcode
+         */
+        bool Read(const short p_address, std::string & p_string, bool p_readLengthFirst = true, int p_length2write = -1);
+    
+        /** Activate or deactivate write protect (pin 7)
+         *
+         * @param p_writeProtect: Set to true to activate write protection, false otherwise
+         * @return true on success, false otherwise
+         */
+        bool WriteProtect(const bool p_writeProtect);
+    
+        /** Indicate the current WP state indicator  (pin 7)
+         * @return true is write protected, false otherwise
+         */
+        inline bool IsWriteProtected() {
+            return (_wp != NULL) ? (bool)(_wp->read() == 1) : false;
+        }
+
+#if defined(__DEBUG)
+        /** Dump a memory area
+         * 
+         * Note that this method is available only on debug mode
+         * @param p_address The memory address (from 0 to N - 1, N is the number of cells of the memory)
+         * @param p_count The number of bytes toi dump
+         * @return true on success, false otherwise
+         */
+        void DumpMemoryArea(const int p_address, const int p_count);
+        /** For debug purpose only
+         */
+        inline std::string & ToString() { return _internalId; };
+#else // __DEBUG
+        inline void DumpMemoryArea(const int p_address, const int p_count) {};
+#endif // _DEBUG
+        
+    private:
+        /** Internal reference identifier
+         */
+        std::string _internalId;
+
+    private:
+        /**
+         * Retrieve device identifiers
+         * @remark See FM24V10_ds.pdf Page 9/16 Clause Device ID
+         */
+        void GetDevideIDs();
+    
+    }; // End of class CFM24VXX_I2C
+
+}; // End of namespace _FM24VXX_I2C
+
+using namespace _FM24VXX_I2C;
+
+#endif // __FM24VXX_I2C_H__