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@9:acc133240c9d, 2020-03-28 (annotated)

Committer:
skyscraper
Date:
Sat Mar 28 16:11:37 2020 +0000
Revision:
9:acc133240c9d
Parent:
8:0c122f839dc9
Child:
10:3824e507953c
doc update

Who changed what in which revision?

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