Initial commit

Author: nseidle

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

ISSUE_TEMPLATE.md

@@ -0,0 +1,18 @@
+### Subject of the issue
+Describe your issue here. If you reference a datasheet please specify which one and in which section (ie, the protocol manual, section 5.1.2). Additionally, screenshots are easy to paste into github.
+
+### Your workbench
+* What development board or microcontroller are you using?
+* What version of hardware or breakout board are you using? 
+* How is the breakout board wired to your microcontroller?
+* How is everything being powered?
+* Are there any additional details that may help us help you?
+
+### Steps to reproduce
+Tell us how to reproduce this issue. Please post stripped down example code demonstrating your issue.
+
+### Expected behavior
+Tell us what should happen
+
+### Actual behavior
+Tell us what happens instead

LICENSE.md

@@ -0,0 +1,55 @@
+SparkFun License Information
+============================
+
+SparkFun uses two different licenses for our files — one for hardware and one for code.
+
+Hardware
+---------
+
+**SparkFun hardware is released under [Creative Commons Share-alike 4.0 International](http://creativecommons.org/licenses/by-sa/4.0/).**
+
+Note: This is a human-readable summary of (and not a substitute for) the [license](http://creativecommons.org/licenses/by-sa/4.0/legalcode).
+
+You are free to:
+
+Share — copy and redistribute the material in any medium or format
+Adapt — remix, transform, and build upon the material
+for any purpose, even commercially.
+The licensor cannot revoke these freedoms as long as you follow the license terms.
+Under the following terms:
+
+Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
+No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+Notices:
+
+You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
+
+
+Code
+--------
+
+**SparkFun code, firmware, and software is released under the MIT License(http://opensource.org/licenses/MIT).**
+
+The MIT License (MIT)
+
+Copyright (c) 2016 SparkFun Electronics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,57 @@
+SparkFun External EEPROM Arduino Library
+===========================================================
+
+![SparkFun Qwiic EEPROM](https://cdn.sparkfun.com//assets/parts/1/7/7/0/1/18355-SparkFun_Qwiic_EEPROM_Breakout_-_512Kbit-01.jpg)
+
+[*SparkFun Qwiic EEPROM (COM-18355)*](https://www.sparkfun.com/products/18355)
+
+A simple-to-use I2C library for talking to any EEPROM. It uses the same template system found in the Arduino EEPROM library so you can use the same get() and put() functions.
+
+The device-specific specs (overall size, page size, write times, etc) are auto-detected. This library works with all types and allows the various settings to be set at runtime. All read and write restrictions associated with pages are taken care of. You can access the external memory as if it was contiguous.
+
+Best used with the Qwiic EEPROM: https://www.sparkfun.com/products/18355
+
+This library can be installed via the Arduino Library manager. Search for **SparkFun External EEPROM**.
+
+The method for autodetection is as follows. The original data on the EEPROM is maintained once autodetection is complete:
+
+* Address Bytes: Smaller EEPROMs use one address byte and larger EEPROMs use 2 address bytes. The auto-detection routine attempts to read a byte and then write a new byte. If the read/write fails, the address byte count is increased and a write attempt is tried again. Once the correct number of address bytes is detected, the original value is written back to EEPROM.
+
+* Page Size: 256 bytes of EEPROM are read individually (to avoid page reads). Then, new bytes are generated that are random *and* different from the original data. The new bytes are written to EEPROM in increasing page size tests (8 bytes, then 16, etc) until the data does not match. Then the original data is written back to the EEPROM. Note: The page size may be reported as 32 bytes when the actual page size is larger. This is because of the size of the I2C buffer available on your microcontroller's Arduino core's Wire implementation. On some platforms (such as Arduino Uno) the I2C write buffer is 32 bytes. Once the two write bytes are removed, that leaves only 30 bytes available for sequential reads/writes. For maximum write speeds, use a platform that has a larger buffer than the page size of the EEPROM you are using.
+
+* Memory Size: Once address bytes and page size are determined, single bytes are read, then written, then checked at the end of the potential EEPROM space. For example, byte 65535 is read for its original value and stored. Then a new, different value is written to location 65535. If the read/write fails, we know the EEPROM is one size down (32768 bytes, aka 24XX256).
+
+* Page write time: This setting is not detected at begin(). All EEPROMs have a max write time of 5ms. Testing with a logic analyzer has shown that all EEPROMs respect this max and have an average of ~4.5ms for a page write. Attempting to trim the page write time lower than 5ms is much less worthwhile than using up a properly sized page size setting with an adequately sized I2C write buffer. In other words, read and write as many bytes as the page size can handle, don't worry about setting the page write time to 4ms or 5ms. Note: The 24XXM02 has a 10ms max page write time.
+
+Want to help? Please do! We are always looking for ways to improve and build out features of this library.
+
+Thanks to:
+
+* Hutch67 for correcting the [test for pollForWriteComplete setting](https://github.com/sparkfun/SparkFun_External_EEPROM_Arduino_Library/pull/4/files)
+* [TinaJ_kay](https://github.com/TylerBird) for correcting [ambiguous int declaration](https://github.com/sparkfun/SparkFun_External_EEPROM_Arduino_Library/pull/7) and adding STM32 support
+
+Repository Contents
+-------------------
+
+* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE. 
+* **/src** - Source files for the library (.cpp, .h).
+* **keywords.txt** - Keywords from this library that will be highlighted in the Arduino IDE. 
+* **library.properties** - General library properties for the Arduino package manager. 
+
+Documentation
+--------------
+
+* **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library.
+
+License Information
+-------------------
+
+This product is _**open source**_! 
+
+Various bits of the code have different licenses applied. Anything SparkFun wrote is beerware; if you see me (or any other SparkFun employee) at the local, and you've found our code helpful, please buy us a round!
+
+Please use, reuse, and modify these files as you see fit. Please maintain attribution to SparkFun Electronics and release anything derivative under the same license.
+
+Distributed as-is; no warranty is given.
+
+- Your friends at SparkFun.

examples/Example1_BasicReadWrite/Example1_BasicReadWrite.ino

@@ -0,0 +1,97 @@
+/*
+  Read and write settings and calibration data to an external I2C EEPROM
+  By: Nathan Seidle
+  SparkFun Electronics
+  Date: December 11th, 2019
+  License: This code is public domain but you buy me a beer if you use this 
+  and we meet someday (Beerware license).
+  Feel like supporting our work? Buy a board from SparkFun!
+  https://www.sparkfun.com/products/14764
+
+  This example demonstrates how to read and write various variables to memory.
+
+  The I2C EEPROM should have all its ADR pins set to GND (0). This is default
+  on the Qwiic board.
+
+  Hardware Connections:
+  Plug the SparkFun Qwiic EEPROM to an Uno, Artemis, or other Qwiic equipped board
+  Load this sketch
+  Open output window at 115200bps
+*/
+
+#include <Wire.h>
+
+#include "SparkFun_External_EEPROM.h" // Click here to get the library: http://librarymanager/All#SparkFun_External_EEPROM
+ExternalEEPROM myMem;
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println("Qwiic EEPROM example");
+
+  Wire.begin();
+
+  if (myMem.begin() == false)
+  {
+    Serial.println("No memory detected. Freezing.");
+    while (1)
+      ;
+  }
+  Serial.println("Memory detected!");
+
+  uint32_t eepromSizeBytes = myMem.getMemorySizeBytes();
+  Serial.print("Detected EEPROM size (bytes): ");
+  Serial.print(eepromSizeBytes);
+  Serial.print(" - EEPROM Type: 24XX");
+  if (eepromSizeBytes == 16)
+    Serial.print("00");
+  else
+  {
+    if ((eepromSizeBytes * 8 / 1024) < 10) Serial.print("0");
+    Serial.print(eepromSizeBytes * 8 / 1024);
+  }
+  Serial.println();
+
+  Serial.print("Detected number of address bytes: ");
+  Serial.println(myMem.getAddressBytes());
+
+  Serial.print("Detected pageSizeBytes: ");
+  Serial.println(myMem.getPageSizeBytes());
+
+  //Yes you can read and write bytes, but you shouldn't!
+  byte myValue1 = 200;
+  myMem.write(0, myValue1); //(location, data)
+
+  byte myRead1 = myMem.read(0);
+  Serial.print("I read (should be 200): ");
+  Serial.println(myRead1);
+
+  //You should use gets and puts. This will automatically and correctly arrange
+  //the bytes for larger variable types.
+  int myValue2 = -366;
+  myMem.put(10, myValue2); //(location, data)
+  int myRead2;
+  myMem.get(10, myRead2); //location to read, thing to put data into
+  Serial.print("I read (should be -366): ");
+  Serial.println(myRead2);
+
+  float myValue3 = -7.35;
+  myMem.put(20, myValue3); //(location, data)
+  float myRead3;
+  myMem.get(20, myRead3); //location to read, thing to put data into
+  Serial.print("I read (should be -7.35): ");
+  Serial.println(myRead3);
+
+  String myString = "Hi, I am just a simple test string";
+  unsigned long nextEEPROMLocation = myMem.putString(30, myString);
+  String myRead4 = "";
+  myMem.getString(30, myRead4);
+  Serial.print("I read: ");
+  Serial.println(myRead4);
+  Serial.print("Next available EEPROM location: ");
+  Serial.println(nextEEPROMLocation);  
+}
+
+void loop()
+{
+}

keywords.txt

@@ -0,0 +1,58 @@
+#######################################
+# Syntax Coloring Map
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+ExternalEEPROM	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+
+read	KEYWORD2
+write	KEYWORD2
+begin	KEYWORD2
+isConnected	KEYWORD2
+isBusy	KEYWORD2
+erase	KEYWORD2
+
+detectMemorySizeBytes	KEYWORD2
+setMemorySizeBytes	KEYWORD2
+getMemorySizeBytes	KEYWORD2
+setMemorySize	KEYWORD2
+getMemorySize	KEYWORD2
+length	KEYWORD2
+
+detectPageSizeBytes	KEYWORD2
+setPageSizeBytes	KEYWORD2
+getPageSizeBytes	KEYWORD2
+setPageSize	KEYWORD2
+getPageSize	KEYWORD2
+
+detectAddressBytes	KEYWORD2
+setAddressBytes	KEYWORD2
+getAddressBytes	KEYWORD2
+
+detectWriteTimeMs	KEYWORD2
+setWriteTimeMs	KEYWORD2
+getWriteTimeMs	KEYWORD2
+setPageWriteTime	KEYWORD2
+getPageWriteTime	KEYWORD2
+
+enablePollForWriteComplete	KEYWORD2
+disablePollForWriteComplete	KEYWORD2
+get	KEYWORD2
+put	KEYWORD2
+setI2CBufferSize	KEYWORD2
+getI2CBufferSize	KEYWORD2
+putString	KEYWORD2
+getString	KEYWORD2
+detectMemorySizeBytes	KEYWORD2
+
+#######################################
+# Constants (LITERAL1)
+#######################################
+

library.properties

@@ -0,0 +1,9 @@
+name=SparkFun External EEPROM Arduino Library
+version=3.0.0
+author=SparkFun Electronics
+maintainer=SparkFun Electronics <sparkfun.com>
+sentence=Library for I2C Communication with external EEPROMs
+paragraph=A library for the advanced control of any I2C based EEPROM. This library writes extremely fast and automatically handles the writing of pages to make the entire EEPROM act as one large writable block. Automatically reads and writes ints, floats, arrays, and structs. Automatically detected EEPROM specs including memory size, page size, address bytes, and write times. Works with all EEPROMs including very large >512kbit EEPROMs and any Wire port (Wire1, etc). Use with <a href="https://www.sparkfun.com/products/18355">Qwiic EEPROM</a> to make it easy to read and write cal data and other user settings. Configurable I2C buffer size increases throughput up to 30kB/s. Includes an example that reads binary file from SD and auto writes/verifies to EEPROM. Tested with 24LC00, 24LC01B, 24AA02, 24LC04B, 24LC16BH, 24LC32A, 24LC256, CAT24C512, 24LC1025, and 24LC1026. 
+category=Data Storage
+url=https://github.com/sparkfun/SparkFun_External_EEPROM_Arduino_Library
+architectures=*