I2CEeprom.h

00001 
00002 /*! \file I2CEeprom.h */
00003 /*! \class I2CEeprom */
00004 /*! \brief Simple access class for I2C EEPROM chips like Microchip 24LC
00005  */
00006 
00007 /* Copyright (c) 2015 Robin Hourahane
00008 *  Copyright (c) 2020 Andy Little
00009 *
00010 * Licensed under the Apache License, Version 2.0 (the "License");
00011 * you may not use this file except in compliance with the License.
00012 * You may obtain a copy of the License at
00013 *
00014 *     http://www.apache.org/licenses/LICENSE-2.0
00015 *
00016 * Unless required by applicable law or agreed to in writing, software
00017 * distributed under the License is distributed on an "AS IS" BASIS,
00018 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019 * See the License for the specific language governing permissions and
00020 * limitations under the License.
00021 */
00022 
00023 #ifndef __I2CEEPROM_H__
00024 #define __I2CEEPROM_H__
00025 
00026 #include <mbed.h>
00027 
00028 /// Based on the original Mbed I2CEeprom library by Robin Hourahane.
00029 ///
00030 /// Class to provide simple access to I2C EEPROM chips like Microchip's 24LC
00031 /// or AMTELS AT24C series. Chips up to 64Kb in size are directly supported.
00032 ///
00033 /// The library was tested on a Microchip 24LC128.
00034 ///
00035 /// The I2CEeprom class handles multiple page writes so any amount of data can
00036 /// be written in a single call to write.
00037 ///
00038 /// The code is modified from the original to better support RTOS.
00039 /// At start of a write(addr,buffer,size), a buffer of up to pageSize + 2
00040 /// is allocated on the heap, and the data and address are copied to it.
00041 /// This allows the cuurent write chunk to proceed without unlocking, which
00042 /// prevents another device on the bus access and so aborting the write.
00043 ///
00044 /// This allocation per write fits my usecase, where eeeprom variables
00045 /// are written in a special menu mode at start up, but it may be better to
00046 /// preallocate a buffer once at startup, if writes are occurring at arbitrary
00047 /// times during execution, to prevent surprises with out of memory issues
00048 /// when trying to write during normal execution.
00049 ///
00050 /// The constructor takes the I2C bus by non-const reference argument. This
00051 /// enables a single I2C bus to be shared among many i2c devices.
00052 /// Mbed OS enforces a lock on the bus during a bus read/write so reads
00053 /// are atomic. Writes are split into separate atomic chunks that only write
00054 /// one eeprom page. After a chunk is sent, the thread is sent to sleep for
00055 /// writeCycleTime_ms specified in the constructor arg, and is then polled
00056 /// at 1 ms intervals to discover whether the write has completed.
00057 
00058 class I2CEeprom
00059 {
00060 public:
00061     /// Constructor to create a new instance of the class.
00062     /// @param i2c A reference to the i2c bus that the chip is connected to.
00063     /// @param address The 8bit device I2C address
00064     /// @param pageSize The device page size.
00065     /// @param chipSize The device size for range check.
00066     /// @param writeCycleTime_ms The device write cycle time in ms.
00067     I2CEeprom(
00068         I2C& i2c,
00069         int address,
00070         size_t pageSize,
00071         size_t chipSize,
00072         uint8_t writeCycleTime_ms);
00073 
00074     /// Read a single byte from the EEprom.
00075     /// @param address EEprom read address.
00076     /// @param value Memory reference of char to read into.
00077     /// @returns Number of bytes read .
00078     size_t read(size_t address, char &value);
00079 
00080     /// Read multiple bytes from the EEprom.
00081     /// @param address EEprom start read address.
00082     /// @param buffer buffer to read into.
00083     /// @param size Number of bytes to read.
00084     /// @returns Number of bytes read.
00085     size_t read(size_t address, char *buffer, size_t size);
00086 
00087     /// Deserialise object of type T from Eeprom memory.
00088     /// @param address EEprom start address
00089     /// @param value Memory Reference of object to deserialise into .
00090     /// @returns Number of bytes read.
00091     template<typename T> size_t read(size_t address, T &value)
00092     {
00093         return read(address, reinterpret_cast<char *>(&value), sizeof(T));
00094     }
00095 
00096     /// Write a char to EEprom.
00097     /// @param address Eeprom write address.
00098     /// @param value Char value to write.
00099     /// @returns Number of bytes written.
00100     size_t write(size_t address, char value);
00101 
00102     /// Write multiple bytes to EEprom.
00103     /// In this implementation, the write is split into chunks of up to pageSize
00104     /// and for each chunk a buffer of up to pageSize + 2 is temporarily
00105     /// allocated on the heap while the write is in progress.
00106     /// @param address EEprom start address.
00107     /// @param buffer Buffer to write.
00108     /// @param size Number of bytes to write.
00109     /// @returns Number of bytes written.
00110     size_t write(size_t address, const char *buffer, size_t size);
00111 
00112     /// Serialise an object of type T.
00113     /// @param address EEprom start address.
00114     /// @param value Object to be serialised.
00115     /// @returns Number of bytes written.
00116     template<typename T> size_t write(size_t address, const T &value)
00117     {
00118         return write(address, reinterpret_cast<const char *>(&value), sizeof(T));
00119     }
00120 
00121 private:
00122     /// Sleep thread while write completes.
00123     void waitForWrite();
00124     ///  atomic chunk up to page size write
00125     size_t ll_write(size_t address, const char *buffer, size_t size);
00126 
00127     /// Validate that proposed operation is in bounds.
00128     bool checkSpace(size_t address, size_t size)
00129     {
00130         return (address + size) < m_chipSize ;
00131     }
00132 
00133 private:
00134     I2C & m_i2c;
00135     int const m_i2cAddress;
00136     size_t const m_chipSize;
00137     size_t const m_pageSize;
00138     uint8_t const m_writeCycleTime_ms;
00139 };
00140 
00141 #endif