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@8:0c122f839dc9, 2020-03-28 (annotated)

Committer:
skyscraper
Date:
Sat Mar 28 15:45:00 2020 +0000
Revision:
8:0c122f839dc9
Parent:
7:29e505d37158
Child:
9:acc133240c9d
docs update

Who changed what in which revision?

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