├── .gitignore ├── keywords.txt ├── README.md ├── LICENSE.md ├── examples └── eepromTest │ └── eepromTest.ino ├── extEEPROM.h ├── ReadMe.bak └── extEEPROM.cpp /.gitignore: -------------------------------------------------------------------------------- 1 | *.zip 2 | *.7z 3 | -------------------------------------------------------------------------------- /keywords.txt: -------------------------------------------------------------------------------- 1 | extEEPROM KEYWORD1 2 | begin KEYWORD2 3 | write KEYWORD2 4 | read KEYWORD2 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## This library has been renamed. ## 2 | ### Please use https://github.com/JChristensen/JC_EEPROM instead. ### 3 | This repository is no longer maintained; it has been archived and is read-only. 4 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # Arduino External EEPROM Library v3 # 2 | http://github.com/JChristensen/extEEPROM 3 | LICENSE file 4 | Jack Christensen Jul 2014 5 | 6 | ![CC BY-SA](http://mirrors.creativecommons.org/presskit/buttons/88x31/png/by-sa.png) 7 | ## CC BY-SA ## 8 | "Arduino External EEPROM Library" by Jack Christensen is licensed under [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/). -------------------------------------------------------------------------------- /examples/eepromTest/eepromTest.ino: -------------------------------------------------------------------------------- 1 | //Test extEEPROM library. 2 | //Writes the EEPROM full of 32-bit integers and reads them back to verify. 3 | //Wire a button from digital pin 6 to ground, this is used as a start button 4 | //so the sketch doesn't do unnecessary EEPROM writes every time it's reset. 5 | //Jack Christensen 09Jul2014 6 | 7 | #include //http://github.com/JChristensen/extEEPROM/tree/dev 8 | #include //http://arduiniana.org/libraries/streaming/ 9 | #include //http://arduino.cc/en/Reference/Wire 10 | 11 | //Two 24LC256 EEPROMs on the bus 12 | const uint32_t totalKBytes = 64; //for read and write test functions 13 | extEEPROM eep(kbits_256, 2, 64); //device size, number of devices, page size 14 | 15 | const uint8_t btnStart = 6; //start button 16 | 17 | void setup(void) 18 | { 19 | pinMode(btnStart, INPUT_PULLUP); 20 | Serial.begin(115200); 21 | uint8_t eepStatus = eep.begin(extEEPROM::twiClock400kHz); //go fast! 22 | if (eepStatus) { 23 | Serial << endl << F("extEEPROM.begin() failed, status = ") << eepStatus << endl; 24 | while (1); 25 | } 26 | 27 | Serial << endl << F("Press button to start...") << endl; 28 | while (digitalRead(btnStart) == HIGH) delay(10); //wait for button push 29 | 30 | uint8_t chunkSize = 64; //this can be changed, but must be a multiple of 4 since we're writing 32-bit integers 31 | // eeErase(chunkSize, 0, totalKBytes * 1024 - 1); 32 | eeWrite(chunkSize); 33 | eeRead(chunkSize); 34 | 35 | dump(0, 16); //the first 16 bytes 36 | dump(32752, 32); //across the device boundary 37 | dump(65520, 16); //the last 16 bytes 38 | } 39 | 40 | void loop(void) 41 | { 42 | } 43 | 44 | //write test data (32-bit integers) to eeprom, "chunk" bytes at a time 45 | void eeWrite(uint8_t chunk) 46 | { 47 | chunk &= 0xFC; //force chunk to be a multiple of 4 48 | uint8_t data[chunk]; 49 | uint32_t val = 0; 50 | Serial << F("Writing...") << endl; 51 | uint32_t msStart = millis(); 52 | 53 | for (uint32_t addr = 0; addr < totalKBytes * 1024; addr += chunk) { 54 | if ( (addr &0xFFF) == 0 ) Serial << addr << endl; 55 | for (uint8_t c = 0; c < chunk; c += 4) { 56 | data[c+0] = val >> 24; 57 | data[c+1] = val >> 16; 58 | data[c+2] = val >> 8; 59 | data[c+3] = val; 60 | ++val; 61 | } 62 | eep.write(addr, data, chunk); 63 | } 64 | uint32_t msLapse = millis() - msStart; 65 | Serial << "Write lapse: " << msLapse << " ms" << endl; 66 | } 67 | 68 | //read test data (32-bit integers) from eeprom, "chunk" bytes at a time 69 | void eeRead(uint8_t chunk) 70 | { 71 | chunk &= 0xFC; //force chunk to be a multiple of 4 72 | uint8_t data[chunk]; 73 | uint32_t val = 0, testVal; 74 | Serial << F("Reading...") << endl; 75 | uint32_t msStart = millis(); 76 | 77 | for (uint32_t addr = 0; addr < totalKBytes * 1024; addr += chunk) { 78 | if ( (addr &0xFFF) == 0 ) Serial << addr << endl; 79 | eep.read(addr, data, chunk); 80 | for (uint8_t c = 0; c < chunk; c += 4) { 81 | testVal = ((uint32_t)data[c+0] << 24) + ((uint32_t)data[c+1] << 16) + ((uint32_t)data[c+2] << 8) + (uint32_t)data[c+3]; 82 | if (testVal != val) Serial << F("Error @ addr ") << addr+c << F(" Expected ") << val << F(" Read ") << testVal << F(" 0x") << _HEX(testVal) << endl; 83 | ++val; 84 | } 85 | } 86 | uint32_t msLapse = millis() - msStart; 87 | Serial << "Last value: " << --val << " Read lapse: " << msLapse << " ms" << endl; 88 | } 89 | 90 | //write 0xFF to eeprom, "chunk" bytes at a time 91 | void eeErase(uint8_t chunk, uint32_t startAddr, uint32_t endAddr) 92 | { 93 | chunk &= 0xFC; //force chunk to be a multiple of 4 94 | uint8_t data[chunk]; 95 | Serial << F("Erasing...") << endl; 96 | for (int i = 0; i < chunk; i++) data[i] = 0xFF; 97 | uint32_t msStart = millis(); 98 | 99 | for (uint32_t a = startAddr; a <= endAddr; a += chunk) { 100 | if ( (a &0xFFF) == 0 ) Serial << a << endl; 101 | eep.write(a, data, chunk); 102 | } 103 | uint32_t msLapse = millis() - msStart; 104 | Serial << "Erase lapse: " << msLapse << " ms" << endl; 105 | } 106 | 107 | //dump eeprom contents, 16 bytes at a time. 108 | //always dumps a multiple of 16 bytes. 109 | void dump(uint32_t startAddr, uint32_t nBytes) 110 | { 111 | Serial << endl << F("EEPROM DUMP 0x") << _HEX(startAddr) << F(" 0x") << _HEX(nBytes) << ' ' << startAddr << ' ' << nBytes << endl; 112 | uint32_t nRows = (nBytes + 15) >> 4; 113 | 114 | uint8_t d[16]; 115 | for (uint32_t r = 0; r < nRows; r++) { 116 | uint32_t a = startAddr + 16 * r; 117 | eep.read(a, d, 16); 118 | Serial << "0x"; 119 | if ( a < 16 * 16 * 16 ) Serial << '0'; 120 | if ( a < 16 * 16 ) Serial << '0'; 121 | if ( a < 16 ) Serial << '0'; 122 | Serial << _HEX(a) << ' '; 123 | for ( int c = 0; c < 16; c++ ) { 124 | if ( d[c] < 16 ) Serial << '0'; 125 | Serial << _HEX( d[c] ) << ( c == 7 ? " " : " " ); 126 | } 127 | Serial << endl; 128 | } 129 | } 130 | 131 | -------------------------------------------------------------------------------- /extEEPROM.h: -------------------------------------------------------------------------------- 1 | /*-----------------------------------------------------------------------------* 2 | * extEEPROM.h - Arduino library to support external I2C EEPROMs. * 3 | * * 4 | * This library will work with most I2C serial EEPROM chips between 2k bits * 5 | * and 2048k bits (2M bits) in size. Multiple EEPROMs on the bus are supported * 6 | * as a single address space. I/O across block, page and device boundaries * 7 | * is supported. Certain assumptions are made regarding the EEPROM * 8 | * device addressing. These assumptions should be true for most EEPROMs * 9 | * but there are exceptions, so read the datasheet and know your hardware. * 10 | * * 11 | * The library should also work for EEPROMs smaller than 2k bits, assuming * 12 | * that there is only one EEPROM on the bus and also that the user is careful * 13 | * to not exceed the maximum address for the EEPROM. * 14 | * * 15 | * Library tested with: * 16 | * Microchip 24AA02E48 (2k bit) * 17 | * 24xx32 (32k bit, thanks to Richard M) * 18 | * Microchip 24LC256 (256k bit) * 19 | * Microchip 24FC1026 (1M bit, thanks to Gabriele B on the Arduino forum) * 20 | * ST Micro M24M02 (2M bit) * 21 | * * 22 | * Library will NOT work with Microchip 24xx1025 as its control byte does not * 23 | * conform to the following assumptions. * 24 | * * 25 | * Device addressing assumptions: * 26 | * 1. The I2C address sequence consists of a control byte followed by one * 27 | * address byte (for EEPROMs <= 16k bits) or two address bytes (for * 28 | * EEPROMs > 16k bits). * 29 | * 2. The three least-significant bits in the control byte (excluding the R/W * 30 | * bit) comprise the three most-significant bits for the entire address * 31 | * space, i.e. all chips on the bus. As such, these may be chip-select * 32 | * bits or block-select bits (for individual chips that have an internal * 33 | * block organization), or a combination of both (in which case the * 34 | * block-select bits must be of lesser significance than the chip-select * 35 | * bits). * 36 | * 3. Regardless of the number of bits needed to address the entire address * 37 | * space, the three most-significant bits always go in the control byte. * 38 | * Depending on EEPROM device size, this may result in one or more of the * 39 | * most significant bits in the I2C address bytes being unused (or "don't * 40 | * care"). * 41 | * 4. An EEPROM contains an integral number of pages. * 42 | * * 43 | * To use the extEEPROM library, the Arduino Wire library must also * 44 | * be included. * 45 | * * 46 | * Jack Christensen 23Mar2013 v1 * 47 | * 29Mar2013 v2 - Updated to span page boundaries (and therefore also * 48 | * device boundaries, assuming an integral number of pages per device) * 49 | * 08Jul2014 v3 - Generalized for 2kb - 2Mb EEPROMs. * 50 | * * 51 | * External EEPROM Library by Jack Christensen is licensed under CC BY-SA 4.0, * 52 | * http://creativecommons.org/licenses/by-sa/4.0/ * 53 | *-----------------------------------------------------------------------------*/ 54 | 55 | #ifndef extEEPROM_h 56 | #define extEEPROM_h 57 | 58 | #include 59 | 60 | //EEPROM size in kilobits. EEPROM part numbers are usually designated in k-bits. 61 | enum eeprom_size_t { 62 | kbits_2 = 2, 63 | kbits_4 = 4, 64 | kbits_8 = 8, 65 | kbits_16 = 16, 66 | kbits_32 = 32, 67 | kbits_64 = 64, 68 | kbits_128 = 128, 69 | kbits_256 = 256, 70 | kbits_512 = 512, 71 | kbits_1024 = 1024, 72 | kbits_2048 = 2048 73 | }; 74 | 75 | //EEPROM addressing error, returned by write() or read() if upper address bound is exceeded 76 | const uint8_t EEPROM_ADDR_ERR = 9; 77 | 78 | class extEEPROM 79 | { 80 | public: 81 | //I2C clock frequencies 82 | enum twiClockFreq_t { twiClock100kHz = 100000, twiClock400kHz = 400000 }; 83 | extEEPROM(eeprom_size_t deviceCapacity, byte nDevice, unsigned int pageSize, byte eepromAddr = 0x50); 84 | byte begin(twiClockFreq_t twiFreq = twiClock100kHz); 85 | byte write(unsigned long addr, byte *values, unsigned int nBytes); 86 | byte write(unsigned long addr, byte value); 87 | byte read(unsigned long addr, byte *values, unsigned int nBytes); 88 | int read(unsigned long addr); 89 | 90 | private: 91 | uint8_t _eepromAddr; //eeprom i2c address 92 | uint16_t _dvcCapacity; //capacity of one EEPROM device, in kbits 93 | uint8_t _nDevice; //number of devices on the bus 94 | uint16_t _pageSize; //page size in bytes 95 | uint8_t _csShift; //number of bits to shift address for chip select bits in control byte 96 | uint16_t _nAddrBytes; //number of address bytes (1 or 2) 97 | unsigned long _totalCapacity; //capacity of all EEPROM devices on the bus, in bytes 98 | }; 99 | 100 | #endif 101 | -------------------------------------------------------------------------------- /ReadMe.bak: -------------------------------------------------------------------------------- 1 | # Arduino External EEPROM Library v3 # 2 | http://github.com/JChristensen/extEEPROM 3 | ReadMe file 4 | Jack Christensen Jul 2014 5 | 6 | ![CC BY-SA](http://mirrors.creativecommons.org/presskit/buttons/80x15/png/by-sa.png) 7 | 8 | ## Introduction ## 9 | **Arduino External EEPROM Library** 10 | 11 | This library will work with most I2C serial EEPROM chips between 2k bits and 2048k bits (2M bits) in size. Multiple EEPROMs on the bus are supported as a single address space. I/O across block, page and device boundaries is supported. Certain assumptions are made regarding the EEPROM device addressing. These assumptions should be true for most EEPROMs but there are exceptions, so read the datasheet and know your hardware. 12 | 13 | The library should also work for EEPROMs smaller than 2k bits, assuming that there is only one EEPROM on the bus and also that the user is careful to not exceed the maximum address for the EEPROM. 14 | 15 | The **extEEPROM Library** has been tested with: 16 | - Microchip 24AA02E48 (2k bit) 17 | - 24xx32 (32k bit, thanks to Richard M) 18 | - Microchip 24LC256 (256k bit) 19 | - Microchip 24FC1026 (1M bit, thanks to Gabriele B on the Arduino forum) 20 | - ST Micro M24M02 (2M bit) 21 | 22 | The **extEEPROM Library** will **NOT** work with Microchip 24xx1025 as its control byte does not conform to the following assumptions. 23 | 24 | **Device addressing assumptions:** 25 | - The I2C address sequence consists of a control byte followed by one address byte (for EEPROMs <= 16k bits) or two address bytes (for EEPROMs > 16k bits). 26 | - The three least-significant bits in the control byte (excluding the R/W bit) comprise the three most-significant bits for the entire address space, i.e. all chips on the bus. As such, these may be chip-select bits or block-select bits (for individual chips that have an internal block organization), or a combination of both (in which case the block-select bits must be of lesser significance than the chip-select bits). 27 | - Regardless of the number of bits needed to address the entire address space, the three most-significant bits always go in the control byte. Depending on EEPROM device size, this may result in one or more of the most significant bits in the I2C address bytes being unused (or "don't care" bits). 28 | - An EEPROM contains an integral number of pages. 29 | 30 | Note that the Arduino Wire library has a buffer size of 32 bytes. This limits the size of physical I/Os that can be done to EEPROM. For writes, one or two bytes are used for the address, so writing is therefore limited to 31 or 30 bytes. Because the **extEEPROM Library** will handle I/O across block, page and device boundaries, the only consequence this has for the user is one of efficiency; arbitrarily large blocks of data can be written and read; however, carefully chosen block sizes may reduce the number of physical I/Os needed. 31 | 32 | "Arduino External EEPROM Library" by Jack Christensen is licensed under [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/). 33 | 34 | ## Installation ## 35 | To use the **extEEPROM Library**: 36 | - Go to http://github.com/JChristensen/extEEPROM, click the **Download ZIP** button and save the ZIP file to a convenient location on your PC. 37 | - Uncompress the downloaded file. This will result in a folder containing all the files for the library, that has a name that includes the branch name, usually **extEEPROM-master**. 38 | - Rename the folder to just **extEEPROM**. 39 | - Copy the renamed folder to the Arduino sketchbook\libraries folder. 40 | 41 | ## Examples ## 42 | The following example sketch is included with the **extEEPROM Library**: 43 | - **eepromTest:** Writes 32-bit integers to the entire EEPROM address space, starting at address 0 and continuing to the topmost address. These are then read back in and verified; any discrepancies are reported to the serial monitor. 44 | 45 | ## Usage notes ## 46 | The **extEEPROM Library** is designed for use with Arduino version 1.0 or later. 47 | 48 | To use the **extEEPROM Library**, the standard [Arduino Wire library](http://arduino.cc/en/Reference/Wire) must also be included. For brevity, this include is not repeated in the examples below: 49 | ```c++ 50 | #include //http://arduino.cc/en/Reference/Wire (included with Arduino IDE) 51 | ``` 52 | ## Enumerations ## 53 | 54 | ###eeprom_size_t 55 | #####Description 56 | EEPROM device size in k-bits. Many manufacturers' EEPROM part numbers are designated in k-bits. 57 | #####Values 58 | - kbits_2 59 | - kbits_4 60 | - kbits_8 61 | - kbits_16 62 | - kbits_32 63 | - kbits_64 64 | - kbits_128 65 | - kbits_256 66 | - kbits_512 67 | - kbits_1024 68 | - kbits_2048 69 | 70 | ###twiClockFreq_t 71 | #####Description 72 | I2C bus speed. 73 | #####Values 74 | - extEEPROM::twiClock100kHz 75 | - extEEPROM::twiClock400kHz 76 | 77 | ## Constructor ## 78 | 79 | ###extEEPROM(eeprom_size_t devCap, byte nDev, unsigned int pgSize, byte busAddr) 80 | #####Description 81 | Instantiates an external EEPROM object. 82 | #####Syntax 83 | `extEEPROM myEEPROM(eeprom_size_t devCap, byte nDev, unsigned int pgSize, byte busAddr));` 84 | #####Parameters 85 | **devCap** *(eeprom_size_t)*: The size of one EEPROM device in k-bits. Choose a value from the eeprom_size_t enumeration above. 86 | **nDev** *(byte)*: The number of EEPROM devices on the bus. Note that if there are multiple EEPROM devices on the bus, they must be identical and each must have its address pins strapped properly. 87 | **pgSize** *(unsigned int)*: The EEPROM page size in bytes. Consult the datasheet if you are unsure of the page size. 88 | **busAddr** *(byte)*: The base I2C bus address for the EEPROM(s). 0x50 is a common value and this parameter can be omitted, in which case 0x50 will be used as the default. 89 | #####Example 90 | ```c++ 91 | extEEPROM myEEPROM(kbits_256, 2, 64); //two 24LC256 EEPROMS on the bus 92 | extEEPROM oddEEPROM(kbits_8, 1, 16, 0x42); //an EEPROM with a non-standard I2C address 93 | ``` 94 | 95 | ## Methods ## 96 | ###begin(twiClockFreq_t freq) 97 | #####Description 98 | Initializes the library. Call this method once in the setup code. begin() does a dummy I/O so that the user may interrogate the return status to ensure the EEPROM is operational. 99 | #####Syntax 100 | `myEEPROM.begin(twiClockFreq_t freq);` 101 | #####Parameters 102 | **freq** *(twiClockFreq_t)*: The desired I2C bus speed, `extEEPROM::twiClock100kHz` or `extEEPROM::twiClock400kHz`. Can be omitted in which case it will default to `twiClock100kHz`. **NOTE:** When using 400kHz, if there are other devices on the bus they must all support a 400kHz bus speed. **Secondly**, the other devices should be initialized first, as other libraries may not support adjusting the bus speed. To ensure the desired speed is set, call the extEEPROM.begin() function *after* initializing all other I2C devices. 103 | #####Returns 104 | I2C I/O status, zero if successful *(byte)*. See the [Arduino Wire.endTransmission() function](http://arduino.cc/en/Reference/WireEndTransmission) for a description of other return codes. 105 | #####Example 106 | ```c++ 107 | extEEPROM myEEPROM(kbits_256, 2, 64); 108 | byte i2cStat = myEEPROM.begin(extEEPROM::twiClock400kHz); 109 | if ( i2cStat != 0 ) { 110 | //there was a problem 111 | } 112 | ``` 113 | ###write(unsigned long addr, byte *values, unsigned int nBytes) 114 | #####Description 115 | Write one or more bytes to external EEPROM. 116 | #####Syntax 117 | `myEEPROM.write(unsigned long addr, byte* values, byte nBytes);` 118 | #####Parameters 119 | **addr** *(unsigned long)*: The beginning EEPROM location to write. 120 | **values** _(byte*)_: Pointer to an array containing the data to write. 121 | **nBytes** *(unsigned int)*: The number of bytes to write. 122 | #####Returns 123 | I2C I/O status, zero if successful *(byte)*. See the [Arduino Wire.endTransmission() function](http://arduino.cc/en/Reference/WireEndTransmission) for a description of other return codes. Returns a status of EEPROM_ADDR_ERR if the I/O would extend past the top of the EEPROM address space. 124 | #####Example 125 | ```c++ 126 | byte myData[10]; 127 | //write 10 bytes starting at location 42 128 | byte i2cStat = myEEPROM.write(42, &data, 10); 129 | if ( i2cStat != 0 ) { 130 | //there was a problem 131 | if ( i2cStat == EEPROM_ADDR_ERR) { 132 | //bad address 133 | } 134 | else { 135 | //some other I2C error 136 | } 137 | } 138 | ``` 139 | ###write(unsigned long addr, byte value) 140 | #####Description 141 | Writes a single byte to external EEPROM. 142 | #####Syntax 143 | `myEEPROM.write(unsigned long addr, byte value);` 144 | #####Parameters 145 | **addr** *(unsigned long)*: The EEPROM location to write. 146 | **values** _(byte)_: The value to write. 147 | #####Returns 148 | Same as multiple-byte write() above. 149 | #####Example 150 | ```c++ 151 | //write the value 16 to EEPROM location 314. 152 | byte i2cStat = myEEPROM.write(314, 16); 153 | ``` 154 | ###read(unsigned long addr, byte *values, unsigned int nBytes) 155 | #####Description 156 | Reads one or more bytes from external EEPROM into an array supplied by the caller. 157 | #####Syntax 158 | `myEEPROM.read(unsigned long addr, byte *values, byte nBytes);` 159 | #####Parameters 160 | **addr** *(unsigned long)*: The beginning EEPROM location to read from. 161 | **values** _(byte*)_: Pointer to an array to receive the data. 162 | **nBytes** *(unsigned int)*: The number of bytes to read. 163 | #####Returns 164 | I2C I/O status, zero if successful *(byte)*. See the [Arduino Wire.endTransmission() function](http://arduino.cc/en/Reference/WireEndTransmission) for a description of other return codes. Returns a status of EEPROM_ADDR_ERR if the I/O would extend past the top of the EEPROM address space. 165 | #####Example 166 | ```c++ 167 | byte myData[10]; 168 | //read 10 bytes starting at location 42 169 | byte i2cStat = myEEPROM.read(42, &data, 10); 170 | if ( i2cStat != 0 ) { 171 | //there was a problem 172 | if ( i2cStat == EEPROM_ADDR_ERR) { 173 | //bad address 174 | } 175 | else { 176 | //some other I2C error 177 | } 178 | } 179 | ``` 180 | ###read(unsigned long addr) 181 | #####Description 182 | Reads a single byte from external EEPROM. 183 | #####Syntax 184 | `myEEPROM.read(unsigned long addr);` 185 | #####Parameters 186 | **addr** *(unsigned long)*: The EEPROM location to read from. 187 | #####Returns 188 | The data read from EEPROM or an error code *(int)*. To distinguish error values from valid data, error values are returned as negative numbers. See the [Arduino Wire.endTransmission() function](http://arduino.cc/en/Reference/WireEndTransmission) for a description of return codes. Returns a status of EEPROM_ADDR_ERR if the I/O would extend past the top of the EEPROM address space. 189 | 190 | #####Example 191 | ```c++ 192 | int myData; 193 | //read a byte from location 42 194 | int readValue = myEEPROM.read(42); 195 | if ( readValue < 0 ) { 196 | //there was a problem 197 | if ( -readValue == EEPROM_ADDR_ERR) { 198 | //bad address 199 | } 200 | else { 201 | //some other I2C error 202 | } 203 | } 204 | else { 205 | //data read ok 206 | } 207 | ``` -------------------------------------------------------------------------------- /extEEPROM.cpp: -------------------------------------------------------------------------------- 1 | /*-----------------------------------------------------------------------------* 2 | * extEEPROM.cpp - Arduino library to support external I2C EEPROMs. * 3 | * * 4 | * This library will work with most I2C serial EEPROM chips between 2k bits * 5 | * and 2048k bits (2M bits) in size. Multiple EEPROMs on the bus are supported * 6 | * as a single address space. I/O across block, page and device boundaries * 7 | * is supported. Certain assumptions are made regarding the EEPROM * 8 | * device addressing. These assumptions should be true for most EEPROMs * 9 | * but there are exceptions, so read the datasheet and know your hardware. * 10 | * * 11 | * The library should also work for EEPROMs smaller than 2k bits, assuming * 12 | * that there is only one EEPROM on the bus and also that the user is careful * 13 | * to not exceed the maximum address for the EEPROM. * 14 | * * 15 | * Library tested with: * 16 | * Microchip 24AA02E48 (2k bit) * 17 | * 24xx32 (32k bit, thanks to Richard M) * 18 | * Microchip 24LC256 (256k bit) * 19 | * Microchip 24FC1026 (1M bit, thanks to Gabriele B on the Arduino forum) * 20 | * ST Micro M24M02 (2M bit) * 21 | * * 22 | * Library will NOT work with Microchip 24xx1025 as its control byte does not * 23 | * conform to the following assumptions. * 24 | * * 25 | * Device addressing assumptions: * 26 | * 1. The I2C address sequence consists of a control byte followed by one * 27 | * address byte (for EEPROMs <= 16k bits) or two address bytes (for * 28 | * EEPROMs > 16k bits). * 29 | * 2. The three least-significant bits in the control byte (excluding the R/W * 30 | * bit) comprise the three most-significant bits for the entire address * 31 | * space, i.e. all chips on the bus. As such, these may be chip-select * 32 | * bits or block-select bits (for individual chips that have an internal * 33 | * block organization), or a combination of both (in which case the * 34 | * block-select bits must be of lesser significance than the chip-select * 35 | * bits). * 36 | * 3. Regardless of the number of bits needed to address the entire address * 37 | * space, the three most-significant bits always go in the control byte. * 38 | * Depending on EEPROM device size, this may result in one or more of the * 39 | * most significant bits in the I2C address bytes being unused (or "don't * 40 | * care"). * 41 | * 4. An EEPROM contains an integral number of pages. * 42 | * * 43 | * To use the extEEPROM library, the Arduino Wire library must also * 44 | * be included. * 45 | * * 46 | * Jack Christensen 23Mar2013 v1 * 47 | * 29Mar2013 v2 - Updated to span page boundaries (and therefore also * 48 | * device boundaries, assuming an integral number of pages per device) * 49 | * 08Jul2014 v3 - Generalized for 2kb - 2Mb EEPROMs. * 50 | * * 51 | * External EEPROM Library by Jack Christensen is licensed under CC BY-SA 4.0, * 52 | * http://creativecommons.org/licenses/by-sa/4.0/ * 53 | *-----------------------------------------------------------------------------*/ 54 | 55 | #include 56 | #include 57 | 58 | // Constructor. 59 | // - deviceCapacity is the capacity of a single EEPROM device in 60 | // kilobits (kb) and should be one of the values defined in the 61 | // eeprom_size_t enumeration in the extEEPROM.h file. (Most 62 | // EEPROM manufacturers use kbits in their part numbers.) 63 | // - nDevice is the number of EEPROM devices on the I2C bus (all must 64 | // be identical). 65 | // - pageSize is the EEPROM's page size in bytes. 66 | // - eepromAddr is the EEPROM's I2C address and defaults to 0x50 which is common. 67 | extEEPROM::extEEPROM(eeprom_size_t deviceCapacity, byte nDevice, unsigned int pageSize, uint8_t eepromAddr) 68 | { 69 | _dvcCapacity = deviceCapacity; 70 | _nDevice = nDevice; 71 | _pageSize = pageSize; 72 | _eepromAddr = eepromAddr; 73 | _totalCapacity = _nDevice * _dvcCapacity * 1024UL / 8; 74 | _nAddrBytes = deviceCapacity > kbits_16 ? 2 : 1; //two address bytes needed for eeproms > 16kbits 75 | 76 | //determine the bitshift needed to isolate the chip select bits from the address to put into the control byte 77 | uint16_t kb = _dvcCapacity; 78 | if ( kb <= kbits_16 ) _csShift = 8; 79 | else if ( kb >= kbits_512 ) _csShift = 16; 80 | else { 81 | kb >>= 6; 82 | _csShift = 12; 83 | while ( kb >= 1 ) { 84 | ++_csShift; 85 | kb >>= 1; 86 | } 87 | } 88 | } 89 | 90 | //initialize the I2C bus and do a dummy write (no data sent) 91 | //to the device so that the caller can determine whether it is responding. 92 | //when using a 400kHz bus speed and there are multiple I2C devices on the 93 | //bus (other than EEPROM), call extEEPROM::begin() after any initialization 94 | //calls for the other devices to ensure the intended I2C clock speed is set. 95 | byte extEEPROM::begin(twiClockFreq_t twiFreq) 96 | { 97 | Wire.begin(); 98 | TWBR = ( (F_CPU / twiFreq) - 16) / 2; 99 | Wire.beginTransmission(_eepromAddr); 100 | if (_nAddrBytes == 2) Wire.write(0); //high addr byte 101 | Wire.write(0); //low addr byte 102 | return Wire.endTransmission(); 103 | } 104 | 105 | //Write bytes to external EEPROM. 106 | //If the I/O would extend past the top of the EEPROM address space, 107 | //a status of EEPROM_ADDR_ERR is returned. For I2C errors, the status 108 | //from the Arduino Wire library is passed back through to the caller. 109 | byte extEEPROM::write(unsigned long addr, byte *values, unsigned int nBytes) 110 | { 111 | uint8_t ctrlByte; //control byte (I2C device address & chip/block select bits) 112 | uint8_t txStatus = 0; //transmit status 113 | uint16_t nWrite; //number of bytes to write 114 | uint16_t nPage; //number of bytes remaining on current page, starting at addr 115 | 116 | if (addr + nBytes > _totalCapacity) { //will this write go past the top of the EEPROM? 117 | return EEPROM_ADDR_ERR; //yes, tell the caller 118 | } 119 | 120 | while (nBytes > 0) { 121 | nPage = _pageSize - ( addr & (_pageSize - 1) ); 122 | //find min(nBytes, nPage, BUFFER_LENGTH) -- BUFFER_LENGTH is defined in the Wire library. 123 | nWrite = nBytes < nPage ? nBytes : nPage; 124 | nWrite = BUFFER_LENGTH - _nAddrBytes < nWrite ? BUFFER_LENGTH - _nAddrBytes : nWrite; 125 | ctrlByte = _eepromAddr | (byte) (addr >> _csShift); 126 | Wire.beginTransmission(ctrlByte); 127 | if (_nAddrBytes == 2) Wire.write( (byte) (addr >> 8) ); //high addr byte 128 | Wire.write( (byte) addr ); //low addr byte 129 | Wire.write(values, nWrite); 130 | txStatus = Wire.endTransmission(); 131 | if (txStatus != 0) return txStatus; 132 | 133 | //wait up to 50ms for the write to complete 134 | for (uint8_t i=100; i; --i) { 135 | delayMicroseconds(500); //no point in waiting too fast 136 | Wire.beginTransmission(ctrlByte); 137 | if (_nAddrBytes == 2) Wire.write(0); //high addr byte 138 | Wire.write(0); //low addr byte 139 | txStatus = Wire.endTransmission(); 140 | if (txStatus == 0) break; 141 | } 142 | if (txStatus != 0) return txStatus; 143 | 144 | addr += nWrite; //increment the EEPROM address 145 | values += nWrite; //increment the input data pointer 146 | nBytes -= nWrite; //decrement the number of bytes left to write 147 | } 148 | return txStatus; 149 | } 150 | 151 | //Read bytes from external EEPROM. 152 | //If the I/O would extend past the top of the EEPROM address space, 153 | //a status of EEPROM_ADDR_ERR is returned. For I2C errors, the status 154 | //from the Arduino Wire library is passed back through to the caller. 155 | byte extEEPROM::read(unsigned long addr, byte *values, unsigned int nBytes) 156 | { 157 | byte ctrlByte; 158 | byte rxStatus; 159 | uint16_t nRead; //number of bytes to read 160 | uint16_t nPage; //number of bytes remaining on current page, starting at addr 161 | 162 | if (addr + nBytes > _totalCapacity) { //will this read take us past the top of the EEPROM? 163 | return EEPROM_ADDR_ERR; //yes, tell the caller 164 | } 165 | 166 | while (nBytes > 0) { 167 | nPage = _pageSize - ( addr & (_pageSize - 1) ); 168 | nRead = nBytes < nPage ? nBytes : nPage; 169 | nRead = BUFFER_LENGTH < nRead ? BUFFER_LENGTH : nRead; 170 | ctrlByte = _eepromAddr | (byte) (addr >> _csShift); 171 | Wire.beginTransmission(ctrlByte); 172 | if (_nAddrBytes == 2) Wire.write( (byte) (addr >> 8) ); //high addr byte 173 | Wire.write( (byte) addr ); //low addr byte 174 | rxStatus = Wire.endTransmission(); 175 | if (rxStatus != 0) return rxStatus; //read error 176 | 177 | Wire.requestFrom(ctrlByte, nRead); 178 | for (byte i=0; i