Andy Little / I2CEeprom

Class to provide simple access to I2C EEPROM chiles like Microchip's 24LC range or AMTELS AT24C range. Chips up to 64Kb in size are directly supported. Updated to Mbed OS v 5.1

Dependents:   storage_test

I2CEeprom.h@10:3824e507953c, 2020-03-28 (annotated)

Committer:
skyscraper
Date:
Sat Mar 28 16:42:13 2020 +0000
Revision:
10:3824e507953c
Parent:
9:acc133240c9d
Child:
11:c3609e691623
more docs

Who changed what in which revision?

UserRevisionLine numberNew contents of line
skyscraper 9:acc133240c9d 1
skyscraper 10:3824e507953c 2 /*! \file I2CEeprom.h */
skyscraper 10:3824e507953c 3 /*! \class I2CEeprom */
skyscraper 10:3824e507953c 4 /*! \brief Simple access class for I2C EEPROM chips like Microchip 24LC
skyscraper 9:acc133240c9d 5 */
skyscraper 9:acc133240c9d 6
skyscraper 10:3824e507953c 7 /* Copyright (c) 2015 Robin Hourahane
skyscraper 10:3824e507953c 8 * Copyright (c) 2020 Andy Little
rhourahane 1:b23f5561266c 9 *
rhourahane 1:b23f5561266c 10 * Licensed under the Apache License, Version 2.0 (the "License");
rhourahane 1:b23f5561266c 11 * you may not use this file except in compliance with the License.
rhourahane 1:b23f5561266c 12 * You may obtain a copy of the License at
rhourahane 1:b23f5561266c 13 *
rhourahane 1:b23f5561266c 14 * http://www.apache.org/licenses/LICENSE-2.0
rhourahane 1:b23f5561266c 15 *
rhourahane 1:b23f5561266c 16 * Unless required by applicable law or agreed to in writing, software
rhourahane 1:b23f5561266c 17 * distributed under the License is distributed on an "AS IS" BASIS,
rhourahane 1:b23f5561266c 18 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rhourahane 1:b23f5561266c 19 * See the License for the specific language governing permissions and
rhourahane 1:b23f5561266c 20 * limitations under the License.
rhourahane 1:b23f5561266c 21 */
skyscraper 6:0b18a49e03b9 22
skyscraper 6:0b18a49e03b9 23 #ifndef __I2CEEPROM_H__
skyscraper 6:0b18a49e03b9 24 #define __I2CEEPROM_H__
rhourahane 1:b23f5561266c 25
rhourahane 1:b23f5561266c 26 #include <mbed.h>
rhourahane 1:b23f5561266c 27
skyscraper 10:3824e507953c 28 /// Based on the original Mbed I2CEeprom library by Robin Hourahane.
skyscraper 9:acc133240c9d 29 ///
skyscraper 9:acc133240c9d 30 /// Class to provide simple access to I2C EEPROM chips like Microchip's 24LC
skyscraper 9:acc133240c9d 31 /// or AMTELS AT24C series. Chips up to 64Kb in size are directly supported.
skyscraper 9:acc133240c9d 32 ///
skyscraper 9:acc133240c9d 33 /// The library was tested on a Microchip 24LC128.
skyscraper 9:acc133240c9d 34 ///
skyscraper 9:acc133240c9d 35 /// The I2CEeprom class handles multiple page writes so any amount of data can
skyscraper 9:acc133240c9d 36 /// be written in a single call to write.
skyscraper 9:acc133240c9d 37 ///
skyscraper 8:0c122f839dc9 38 /// The code is modified from the original to better support RTOS.
skyscraper 7:29e505d37158 39 /// At start of a write(addr,buffer,size), a buffer of up to pageSize + 2
skyscraper 7:29e505d37158 40 /// is allocated on the heap, and the data and address are copied to it.
skyscraper 9:acc133240c9d 41 /// This allows the cuurent write chunk to proceed without unlocking, which
skyscraper 9:acc133240c9d 42 /// prevents another device on the bus access and so aborting the write.
skyscraper 9:acc133240c9d 43 ///
skyscraper 7:29e505d37158 44 /// This allocation per write fits my usecase, where eeeprom variables
skyscraper 7:29e505d37158 45 /// are written in a special menu mode at start up, but it may be better to
skyscraper 7:29e505d37158 46 /// preallocate a buffer once at startup, if writes are occurring at arbitrary
skyscraper 9:acc133240c9d 47 /// times during execution, to prevent surprises with out of memory issues
skyscraper 7:29e505d37158 48 /// when trying to write during normal execution.
skyscraper 8:0c122f839dc9 49 ///
skyscraper 9:acc133240c9d 50 /// The constructor takes the I2C bus by non-const reference argument. This
skyscraper 9:acc133240c9d 51 /// enables a single I2C bus to be shared among many i2c devices.
skyscraper 9:acc133240c9d 52 /// Mbed OS enforces a lock on the bus during a bus read/write so reads
skyscraper 9:acc133240c9d 53 /// are atomic. Writes are split into separate atomic chunks that only write
skyscraper 9:acc133240c9d 54 /// one eeprom page. After a chunk is sent, the thread is sent to sleep for
skyscraper 9:acc133240c9d 55 /// writeCycleTime_ms as in the constructor arg, and is then polled at 1 ms
skyscraper 9:acc133240c9d 56 /// intervals to discover whether the write has completed.
skyscraper 9:acc133240c9d 57
rhourahane 1:b23f5561266c 58 class I2CEeprom {
rhourahane 1:b23f5561266c 59 public:
rhourahane 1:b23f5561266c 60 /// Constructor to create a new instance of the class.
skyscraper 10:3824e507953c 61 /// @param i2c A reference to the i2c bus the chip is connected to.
skyscraper 6:0b18a49e03b9 62 /// @param address The 8bit I2C address of the chip.
rhourahane 1:b23f5561266c 63 /// @param pageSize The size of the page used in writing to the chip.
skyscraper 5:315872eec0ae 64 /// @param chipSize The size of the memory in the chip for range check.
skyscraper 6:0b18a49e03b9 65 /// @param writeCycleTime_ms The write cycle time in ms.
skyscraper 2:f3188aaccf80 66 I2CEeprom(
skyscraper 2:f3188aaccf80 67 I2C& i2c,
skyscraper 2:f3188aaccf80 68 int address,
skyscraper 2:f3188aaccf80 69 size_t pageSize,
skyscraper 2:f3188aaccf80 70 size_t chipSize,
skyscraper 5:315872eec0ae 71 uint8_t writeCycleTime_ms);
rhourahane 1:b23f5561266c 72
skyscraper 10:3824e507953c 73 /// Read a single byte from the EEprom.
skyscraper 10:3824e507953c 74 /// @param address EEprom address to read from.
skyscraper 10:3824e507953c 75 /// @param value Reference of char to read into.
skyscraper 10:3824e507953c 76 /// @returns Number of bytes read .
rhourahane 1:b23f5561266c 77 size_t read(size_t address, char &value);
rhourahane 1:b23f5561266c 78
skyscraper 10:3824e507953c 79 /// Read multiple bytes starting from EEprom memory.
skyscraper 10:3824e507953c 80 /// @param address EEprom Memory start read address.
skyscraper 10:3824e507953c 81 /// @param buffer Pointer to buffer to hold bytes read.
skyscraper 10:3824e507953c 82 /// @param size Number of bytes to read.
skyscraper 10:3824e507953c 83 /// @returns Number of bytes read.
rhourahane 1:b23f5561266c 84 size_t read(size_t address, char *buffer, size_t size);
rhourahane 1:b23f5561266c 85
skyscraper 10:3824e507953c 86 /// Deserialise object of type T from Eeprom memory.
skyscraper 10:3824e507953c 87 /// @param address Start address of Object in EEprom.
skyscraper 10:3824e507953c 88 /// @param value Reference to Object to deserialise into.
skyscraper 10:3824e507953c 89 /// @returns Number of bytes read.
rhourahane 1:b23f5561266c 90 template<typename T> size_t read(size_t address, T &value) {
rhourahane 1:b23f5561266c 91 return read(address, reinterpret_cast<char *>(&value), sizeof(T));
rhourahane 1:b23f5561266c 92 }
rhourahane 1:b23f5561266c 93
skyscraper 10:3824e507953c 94 /// Write a char to EEprom.
skyscraper 10:3824e507953c 95 /// @param address Eeprom address to write to.
skyscraper 10:3824e507953c 96 /// @param value Value of char to write.
skyscraper 10:3824e507953c 97 /// @returns Number of bytes written.
rhourahane 1:b23f5561266c 98 size_t write(size_t address, char value);
rhourahane 1:b23f5561266c 99
skyscraper 10:3824e507953c 100 /// Write multiple bytes to EEprom
skyscraper 10:3824e507953c 101 /// Note that in this implementation, the write is split into chunks
skyscraper 10:3824e507953c 102 /// of up to pageSize and for each chunk a buffer of up to pageSize +2
skyscraper 10:3824e507953c 103 /// is temporarily allocated on the heap while the write is in progress.
skyscraper 10:3824e507953c 104 /// @param address Start EEprom address.
skyscraper 10:3824e507953c 105 /// @param buffer Buffer holding the bytes to write.
skyscraper 10:3824e507953c 106 /// @param size Number of bytes to write.
skyscraper 10:3824e507953c 107 /// @returns Number of bytes written.
rhourahane 1:b23f5561266c 108 size_t write(size_t address, const char *buffer, size_t size);
skyscraper 2:f3188aaccf80 109
skyscraper 10:3824e507953c 110 /// Serialise an object of type T.
skyscraper 10:3824e507953c 111 /// @param address EEprom write start address.
skyscraper 10:3824e507953c 112 /// @returns Number of bytes written.
rhourahane 1:b23f5561266c 113 template<typename T> size_t write(size_t address, const T &value) {
rhourahane 1:b23f5561266c 114 return write(address, reinterpret_cast<const char *>(&value), sizeof(T));
rhourahane 1:b23f5561266c 115 }
skyscraper 2:f3188aaccf80 116
rhourahane 1:b23f5561266c 117 private:
skyscraper 10:3824e507953c 118 /// Sleep thread while write completes.
rhourahane 1:b23f5561266c 119 void waitForWrite();
skyscraper 10:3824e507953c 120 /// atomic chunk up to page aize write
skyscraper 2:f3188aaccf80 121 size_t ll_write(size_t address, const char *buffer, size_t size);
rhourahane 1:b23f5561266c 122
skyscraper 10:3824e507953c 123 /// Validate that proposed operation is in bounds.
skyscraper 4:d8f51b136dbd 124 bool checkSpace(size_t address, size_t size)
skyscraper 4:d8f51b136dbd 125 {
skyscraper 4:d8f51b136dbd 126 return (address + size) < m_chipSize ;
skyscraper 4:d8f51b136dbd 127 }
rhourahane 1:b23f5561266c 128
rhourahane 1:b23f5561266c 129 private:
skyscraper 2:f3188aaccf80 130 I2C & m_i2c;
skyscraper 2:f3188aaccf80 131 int const m_i2cAddress;
skyscraper 2:f3188aaccf80 132 size_t const m_chipSize;
skyscraper 2:f3188aaccf80 133 size_t const m_pageSize;
skyscraper 2:f3188aaccf80 134 uint8_t const m_writeCycleTime_ms;
rhourahane 1:b23f5561266c 135 };
rhourahane 1:b23f5561266c 136
rhourahane 1:b23f5561266c 137 #endif