2021-01-29 06:31:58 -05:00
[](https://github.com/marketplace/actions/arduino_ci)
[](https://github.com/RobTillaart/I2C_EEPROM/blob/master/LICENSE)
[](https://github.com/RobTillaart/I2C_EEPROM/releases)
2020-11-27 05:16:22 -05:00
# I2C_EEPROM
2021-01-29 06:31:58 -05:00
Arduino Library for external I2C EEPROM - 24LC512, 24LC256, 24LC64/32/16/08/04/02/01
2020-11-27 05:16:22 -05:00
## Description
2021-01-29 06:31:58 -05:00
This library is to access external I2C EEPROM up to 64KB (= 512 Kbit) in size.
MicroChip 24LC512, 24LC256, 24LC64, 24LC32, 24LC16, 24LC08, 24LC04, 24LC02, 24LC01 and equivalents.
The **I2C_eeprom_cyclic_store** interface is documented [here ](README_cyclic_store.md )
## Interface
### Constructor
- **I2C_eeprom(uint8_t deviceAddress, TwoWire \*wire = & Wire)** constructor, optional Wire interface
- **I2C_eeprom(uint8_t deviceAddress, uint32_t deviceSize, TwoWire \*wire = & Wire)** constructor, with optional Wire interface.
- **bool begin()** initializes the I2C bus and checks if the device is available on the I2C bus.
- **bool begin(uint8_t sda, uint8_t scl)** idem for ESP32 / ESP8266 and alike.
2021-07-01 04:58:13 -04:00
- **bool isConnected()** test to see if deviceAddress is found on the bus.
2021-01-29 06:31:58 -05:00
2020-11-27 05:16:22 -05:00
2021-01-29 06:31:58 -05:00
### Core functions
2020-11-27 05:16:22 -05:00
2021-01-29 06:31:58 -05:00
- **int writeByte(uint16_t memoryAddress, uint8_t value)** write a single byte to the specified memory address.
- **int updateByte(uint16_t memoryAddress, uint8_t value)** write a single byte, but only if changed. Returns 0 if value was same or write succeeded.
- **int writeBlock(uint16_t memoryAddress, uint8_t \* buffer, uint16_t length)** write a buffer starting at the specified memory address.
2021-02-03 11:20:20 -05:00
- **int updateBlock(uint16_t memoryAddress, uint8_t \* buffer, uint16_t length)** write a buffer starting at the specified memory address, but only if changed
2021-01-29 06:31:58 -05:00
- **int setBlock(uint16_t memoryAddress, uint8_t value, uint16_t length)** writes the same byte to length places starting at the specified memory address. Returns 0 if OK.
- **uint8_t readByte(uint16_t memoryAddress)** read a single byte from a given address
- **uint16_t readBlock(uint16_t memoryAddress, uint8_t \* buffer, uint16_t length)** read length bytes into buffer starting at specified memory address. Returns the number of bytes read, which should be length.
2020-11-27 05:16:22 -05:00
2021-01-29 06:31:58 -05:00
### Other
- **uint32_t getDeviceSize()** idem
- **uint8_t getPageSize()** idem
- **uint8_t getPageSize(uint32_t deviceSize)** idem
- **uint32_t getLastWrite()** idem
- **uint32_t determineSize(bool debug = false)**
2021-07-01 04:58:13 -04:00
function that determines the size of the EEPROM by detecting when a memory address is folded upon memory address 0.
2021-01-29 06:31:58 -05:00
It is based upon the observation that memory wraps around.
The debug flag gives some output to Serial.
**Warning**: this function has changed (again) in 1.4.0
2021-07-01 04:58:13 -04:00
Test results
2021-01-29 06:31:58 -05:00
| Type | returns | Memory | Page Size | Notes |
|:--------|:--------|:---------|:-----:|:------|
| - | 0 | | | connect error, check device address / wiring |
| 24LC512 | 65536 | 64 KB | 128 | |
| 24LC256 | 32768 | 32 KB | 64 | |
| 24LC128 | 16384 | 16 KB | 64 | |
| 24LC64 | 8192 | 8 KB | 32 | |
| 24LC32 | 4096 | 4 KB | 32 | not tested with hardware |
| 24LC16 | 2048 | 2 KB | 16 | |
| 24LC08 | 1024 | 1 KB | 16 | |
| 24LC04 | 512 | 512 b | 16 | |
| 24LC02 | 256 | 256 b | 8 | |
| 24LC01 | 128 | 128 b | 8 | |
The function cannot detect smaller than 128 bit EEPROMS.
2020-11-27 05:16:22 -05:00
2021-02-03 11:20:20 -05:00
#### UpdateBlock()
(new since 1.4.2)
The function **updateBlock()** reads the block of data and compares it with the new values to see if it needs rewriting.
2021-07-01 04:58:13 -04:00
As the function reads/writes the data in blocks with a maximum length of **I2C_BUFFERSIZE** (== 30 on AVR limitation).
It does this comparison in chunks if the length exceeds this number.
The result is that an **updateBlock()** call can result e.g. in 4 reads and only 2 writes under the hood.
2021-02-03 11:20:20 -05:00
If data is changed often between writes, **updateBlock()** is slower than **writeBlock()** .
So you should verify if your sketch can make use of the advantages of **updateBlock()**
2020-11-27 05:16:22 -05:00
## Limitation
2021-01-29 06:31:58 -05:00
The library does not offer multiple EEPROMS as one continuous storage device.
## Future
- improve error handling, write functions should return bytes written or so.
- what can we do with the print interface? (investigate)
- investigate multi-EEPROM storage,
2021-07-01 04:58:13 -04:00
- investigate smarter strategy for updateBlock() => find first and last changed position could possibly result in less writes.
2020-11-27 05:16:22 -05:00
## Operational
See examples
