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

Committer:
skyscraper
Date:
Sat Mar 28 18:03:39 2020 +0000
Revision:
12:d9a44fb3b9a6
Parent:
11:c3609e691623 
More documentation tidying and format wand

Who changed what in which revision?

UserRevisionLine numberNew contents of line
skyscraper 9:acc133240c9d 1
skyscraper 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 6
skyscraper 12:d9a44fb3b9a6 7 /* Copyright (c) 2015 Robin Hourahane
skyscraper 12:d9a44fb3b9a6 8 * Copyright (c) 2020 Andy Little
skyscraper 12:d9a44fb3b9a6 9 *
skyscraper 12:d9a44fb3b9a6 10 * Licensed under the Apache License, Version 2.0 (the "License");
skyscraper 12:d9a44fb3b9a6 11 * you may not use this file except in compliance with the License.
skyscraper 12:d9a44fb3b9a6 12 * You may obtain a copy of the License at
skyscraper 12:d9a44fb3b9a6 13 *
skyscraper 12:d9a44fb3b9a6 14 * http://www.apache.org/licenses/LICENSE-2.0
skyscraper 12:d9a44fb3b9a6 15 *
skyscraper 12:d9a44fb3b9a6 16 * Unless required by applicable law or agreed to in writing, software
skyscraper 12:d9a44fb3b9a6 17 * distributed under the License is distributed on an "AS IS" BASIS,
skyscraper 12:d9a44fb3b9a6 18 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
skyscraper 12:d9a44fb3b9a6 19 * See the License for the specific language governing permissions and
skyscraper 12:d9a44fb3b9a6 20 * limitations under the License.
skyscraper 12:d9a44fb3b9a6 21 */
skyscraper 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 32 ///
skyscraper 12:d9a44fb3b9a6 33 /// The library was tested on a Microchip 24LC128.
skyscraper 9:acc133240c9d 34 ///
skyscraper 12:d9a44fb3b9a6 35 /// The I2CEeprom class handles multiple page writes so any amount of data can
skyscraper 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 52 /// Mbed OS enforces a lock on the bus during a bus read/write so reads
skyscraper 12:d9a44fb3b9a6 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 12:d9a44fb3b9a6 55 /// writeCycleTime_ms specified in the constructor arg, and is then polled
skyscraper 12:d9a44fb3b9a6 56 /// at 1 ms intervals to discover whether the write has completed.
skyscraper 9:acc133240c9d 57
skyscraper 12:d9a44fb3b9a6 58 class I2CEeprom
skyscraper 12:d9a44fb3b9a6 59 {
rhourahane 1:b23f5561266c 60 public:
rhourahane 1:b23f5561266c 61 /// Constructor to create a new instance of the class.
skyscraper 12:d9a44fb3b9a6 62 /// @param i2c A reference to the i2c bus that the chip is connected to.
skyscraper 12:d9a44fb3b9a6 63 /// @param address The 8bit device I2C address
skyscraper 12:d9a44fb3b9a6 64 /// @param pageSize The device page size.
skyscraper 12:d9a44fb3b9a6 65 /// @param chipSize The device size for range check.
skyscraper 12:d9a44fb3b9a6 66 /// @param writeCycleTime_ms The device write cycle time in ms.
skyscraper 2:f3188aaccf80 67 I2CEeprom(
skyscraper 12:d9a44fb3b9a6 68 I2C& i2c,
skyscraper 12:d9a44fb3b9a6 69 int address,
skyscraper 12:d9a44fb3b9a6 70 size_t pageSize,
skyscraper 12:d9a44fb3b9a6 71 size_t chipSize,
skyscraper 12:d9a44fb3b9a6 72 uint8_t writeCycleTime_ms);
skyscraper 12:d9a44fb3b9a6 73
skyscraper 10:3824e507953c 74 /// Read a single byte from the EEprom.
skyscraper 12:d9a44fb3b9a6 75 /// @param address EEprom read address.
skyscraper 12:d9a44fb3b9a6 76 /// @param value Memory reference of char to read into.
skyscraper 10:3824e507953c 77 /// @returns Number of bytes read .
rhourahane 1:b23f5561266c 78 size_t read(size_t address, char &value);
skyscraper 12:d9a44fb3b9a6 79
skyscraper 12:d9a44fb3b9a6 80 /// Read multiple bytes from the EEprom.
skyscraper 12:d9a44fb3b9a6 81 /// @param address EEprom start read address.
skyscraper 12:d9a44fb3b9a6 82 /// @param buffer buffer to read into.
skyscraper 10:3824e507953c 83 /// @param size Number of bytes to read.
skyscraper 10:3824e507953c 84 /// @returns Number of bytes read.
rhourahane 1:b23f5561266c 85 size_t read(size_t address, char *buffer, size_t size);
skyscraper 12:d9a44fb3b9a6 86
skyscraper 10:3824e507953c 87 /// Deserialise object of type T from Eeprom memory.
skyscraper 12:d9a44fb3b9a6 88 /// @param address EEprom start address
skyscraper 12:d9a44fb3b9a6 89 /// @param value Memory Reference of object to deserialise into .
skyscraper 10:3824e507953c 90 /// @returns Number of bytes read.
skyscraper 12:d9a44fb3b9a6 91 template<typename T> size_t read(size_t address, T &value)
skyscraper 12:d9a44fb3b9a6 92 {
rhourahane 1:b23f5561266c 93 return read(address, reinterpret_cast<char *>(&value), sizeof(T));
rhourahane 1:b23f5561266c 94 }
skyscraper 12:d9a44fb3b9a6 95
skyscraper 10:3824e507953c 96 /// Write a char to EEprom.
skyscraper 12:d9a44fb3b9a6 97 /// @param address Eeprom write address.
skyscraper 12:d9a44fb3b9a6 98 /// @param value Char value to write.
skyscraper 10:3824e507953c 99 /// @returns Number of bytes written.
rhourahane 1:b23f5561266c 100 size_t write(size_t address, char value);
rhourahane 1:b23f5561266c 101
skyscraper 12:d9a44fb3b9a6 102 /// Write multiple bytes to EEprom.
skyscraper 12:d9a44fb3b9a6 103 /// In this implementation, the write is split into chunks of up to pageSize
skyscraper 12:d9a44fb3b9a6 104 /// and for each chunk a buffer of up to pageSize + 2 is temporarily
skyscraper 12:d9a44fb3b9a6 105 /// allocated on the heap while the write is in progress.
skyscraper 12:d9a44fb3b9a6 106 /// @param address EEprom start address.
skyscraper 12:d9a44fb3b9a6 107 /// @param buffer Buffer to write.
skyscraper 10:3824e507953c 108 /// @param size Number of bytes to write.
skyscraper 10:3824e507953c 109 /// @returns Number of bytes written.
rhourahane 1:b23f5561266c 110 size_t write(size_t address, const char *buffer, size_t size);
skyscraper 2:f3188aaccf80 111
skyscraper 10:3824e507953c 112 /// Serialise an object of type T.
skyscraper 12:d9a44fb3b9a6 113 /// @param address EEprom start address.
skyscraper 11:c3609e691623 114 /// @param value Object to be serialised.
skyscraper 10:3824e507953c 115 /// @returns Number of bytes written.
skyscraper 12:d9a44fb3b9a6 116 template<typename T> size_t write(size_t address, const T &value)
skyscraper 12:d9a44fb3b9a6 117 {
rhourahane 1:b23f5561266c 118 return write(address, reinterpret_cast<const char *>(&value), sizeof(T));
rhourahane 1:b23f5561266c 119 }
skyscraper 12:d9a44fb3b9a6 120
rhourahane 1:b23f5561266c 121 private:
skyscraper 10:3824e507953c 122 /// Sleep thread while write completes.
rhourahane 1:b23f5561266c 123 void waitForWrite();
skyscraper 12:d9a44fb3b9a6 124 /// atomic chunk up to page size write
skyscraper 2:f3188aaccf80 125 size_t ll_write(size_t address, const char *buffer, size_t size);
skyscraper 12:d9a44fb3b9a6 126
skyscraper 10:3824e507953c 127 /// Validate that proposed operation is in bounds.
skyscraper 4:d8f51b136dbd 128 bool checkSpace(size_t address, size_t size)
skyscraper 4:d8f51b136dbd 129 {
skyscraper 12:d9a44fb3b9a6 130 return (address + size) < m_chipSize ;
skyscraper 4:d8f51b136dbd 131 }
skyscraper 12:d9a44fb3b9a6 132
rhourahane 1:b23f5561266c 133 private:
skyscraper 2:f3188aaccf80 134 I2C & m_i2c;
skyscraper 2:f3188aaccf80 135 int const m_i2cAddress;
skyscraper 2:f3188aaccf80 136 size_t const m_chipSize;
skyscraper 2:f3188aaccf80 137 size_t const m_pageSize;
skyscraper 2:f3188aaccf80 138 uint8_t const m_writeCycleTime_ms;
rhourahane 1:b23f5561266c 139 };
rhourahane 1:b23f5561266c 140
rhourahane 1:b23f5561266c 141 #endif