mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
193 lines
7.1 KiB
Markdown
193 lines
7.1 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/I2C_EEPROM/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/I2C_EEPROM/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/I2C_EEPROM/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/I2C_EEPROM/releases)
|
|
|
|
|
|
# I2C_EEPROM
|
|
|
|
Arduino Library for external I2C EEPROM - 24LC512, 24LC256, 24LC64/32/16/08/04/02/01.
|
|
|
|
|
|
## Description
|
|
|
|
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)
|
|
|
|
|
|
## Schematic
|
|
|
|
```cpp
|
|
+---U---+
|
|
A0 | 1 8 | VCC = +5V
|
|
A1 | 2 7 | WP = write protect pin
|
|
A2 | 3 6 | SCL = I2C clock
|
|
GND | 4 5 | SDA = I2C data
|
|
+-------+
|
|
|
|
default address = 0x50 .. 0x57 depending on three address lines
|
|
|
|
```
|
|
|
|
|
|
## Interface
|
|
|
|
The interface is kept quite identical to the I2C_24LC1025 library.
|
|
https://github.com/RobTillaart/I2C_24LC1025
|
|
|
|
Most important change is 32 bit memory addresses.
|
|
|
|
|
|
### 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 with the default pins.
|
|
Furthermore it checks if the deviceAddress is available on the I2C bus.
|
|
Returns true if deviceAddress is found on the bus, false otherwise.
|
|
- **bool begin(uint8_t sda, uint8_t scl)** (ESP32 / ESP8266 only)
|
|
initializes the I2C bus with the specified pins, therby overruling the default pins.
|
|
Furthermore it checks if the deviceAddress is available on the I2C bus.
|
|
Returns true if deviceAddress is found on the bus, false otherwise.
|
|
- **bool isConnected()** test to see if deviceAddress is found on the bus.
|
|
|
|
|
|
### Write functions
|
|
|
|
- **int writeByte(uint16_t memoryAddress, uint8_t value)** write a single byte to
|
|
the specified memory address.
|
|
Returns I2C status, 0 = OK.
|
|
- **int writeBlock(uint16_t memoryAddress, uint8_t \* buffer, uint16_t length)**
|
|
write a buffer starting at the specified memory address.
|
|
Returns I2C status, 0 = OK.
|
|
- **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 I2C status, 0 = OK.
|
|
|
|
|
|
### Update functions
|
|
|
|
- **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.
|
|
- **uint16_t updateBlock(uint16_t memoryAddress, uint8_t \* buffer, uint16_t length)**
|
|
write a buffer starting at the specified memory address, but only if changed.
|
|
Returns bytes written.
|
|
|
|
|
|
### Read functions
|
|
|
|
- **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.
|
|
|
|
|
|
### Verify functions
|
|
|
|
Since 1.6.0. - experimental, needs extensive testing.
|
|
|
|
Same as write and update functions above. Returns true if successful, false indicates an error.
|
|
|
|
- **bool writeByteVerify(uint16_t memoryAddress, uint8_t value)**
|
|
- **bool writeBlockVerify(uint16_t memoryAddress, uint8_t \* buffer, uint16_t length)**
|
|
- **bool setBlockVerify(uint16_t memoryAddress, uint8_t value, uint16_t length)**
|
|
- **bool updateByteVerify(uint16_t memoryAddress, uint8_t value)**
|
|
- **bool updateBlockVerify(uint16_t memoryAddress, uint8_t \* buffer, uint16_t length)**
|
|
|
|
|
|
### 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)**
|
|
function that determines the size of the EEPROM by detecting when a memory address is folded upon memory address 0.
|
|
It is based upon the observation that memory wraps around.
|
|
The debug flag prints some output to Serial.
|
|
|
|
**Warning**: this function has changed (again) in 1.4.0
|
|
|
|
Test results
|
|
|
|
| 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.
|
|
|
|
|
|
#### 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.
|
|
|
|
As the function reads/writes the data in blocks with a maximum length of **I2C_TWIBUFFERSIZE**
|
|
(== 30 AVR limitation; 128 for ESP32)
|
|
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.
|
|
|
|
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()**
|
|
|
|
|
|
#### ExtraWriteCycleTime (experimental)
|
|
|
|
To improve support older I2C EEPROMs e.g. IS24C16 two functions were
|
|
added to increase the waiting time before a read and/or write as some
|
|
older devices have a larger timeout
|
|
than 5 milliseconds which is the minimum.
|
|
|
|
- **void setExtraWriteCycleTime(uint8_t ms)** idem
|
|
- **uint8_t getExtraWriteCycleTime()** idem
|
|
|
|
|
|
## Limitation
|
|
|
|
The library does not offer multiple EEPROMS as one continuous storage device.
|
|
|
|
|
|
## Operation
|
|
|
|
See examples
|
|
|
|
## Future
|
|
|
|
#### must
|
|
- improve documentation
|
|
|
|
#### should
|
|
- investigate multi-EEPROM storage
|
|
- wrapper class?
|
|
- improve error handling, write functions should return bytes written or so.
|
|
|
|
#### could
|
|
- investigate smarter strategy for **updateBlock()**
|
|
=> find first and last changed position could possibly result in less writes.
|
|
- can **setBlock()** use strategies from **updateBlock()**
|
|
- **\_waitEEReady();** can return bool and could use isConnected() internally.
|
|
- added value?
|
|
- investigate the print interface?
|
|
- circular buffer? (see FRAM library)
|
|
- dump function?
|
|
|