Merge pull request #119 from Marzogh/development

v3.1.0 ready for release

.github/ISSUE_TEMPLATE.md

@@ -1,7 +1,10 @@
 Hey there! Thanks for using the SPIFlash library for Arduino. 
+### Please note that starting 01.03.2018 any issue raised here MUST be submitted according to this template or it will be flagged with 'Not enough information'. No action will be taken till all the prerequisite information is provided. If no information is provided for over a month, the issue will be closed.
 
 **Note: For support questions, please use the [Arduino Forums](http://forum.arduino.cc/index.php?topic=324009.0). This repository's issues are reserved for feature requests and bug reports.**
 
+# Issue details
+
 **I'm submitting a ...**
   - [ ] bug report
   - [ ] feature request
@@ -27,8 +30,21 @@ When opening an issue please include the following details:
 
 --------------------------
 ###### Bug reports only
-
-- [ ] If this is a bug report - Provide a **minimal code snippet** example that reproduces the bug. Please make sure you wrap any code in the proper code blocks like below 
+- If this is a bug report - 
+
+- [ ] Make sure you have run FlashDiagnostics.ino with ``` #define RUNDIAGNOSTICS ``` uncommented in SPIFlash.h. **List any error codes** that pop up in your Serial output when you run FlashDiagnostics.ino.here:
+      Error codes
+      ------------
+        - 
+        -
+        -
+        -
+        -
+- [ ] If you have a problem with a particular function, call the flash.error() function (after you have made sure you have started up your Serial port with a ``` Serial.begin(BAUD) ``` ). Provide details of the function, the data given to/ expected from the function and the error code here: (**Please repeat this for every function you have an error with***)
+        Function - 
+        Data - 
+        Error code - 
+- [ ] Provide a **minimal code snippet** example that reproduces the bug. Please make sure you wrap any code in the proper code blocks like below 
 ```
 ```CODE HERE```
 ```

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,11 +1,19 @@
+Hey there! Thanks for using the SPIFlash library for Arduino. 
+### Please note that starting 01.03.2018 any Pull request raised here MUST be submitted according to this template or it will be flagged with 'Not enough information'. No action will be taken till all the prerequisite information is provided. If no information is provided for over a month, the pull request will be closed.
+
+# Pull request details
+
 * **Please check if the PR fulfills these requirements**
 - [ ] The commit message/s explain/s all the changes clearly
 - [ ] Tests for the changes have been added (for bug fixes / features)
 - [ ] Docs have been added / updated (for bug fixes / features)
 
 
 * **What kind of change does this PR introduce?** (Bug fix, feature, docs update, ...)
-
+- [ ] Bug fix
+- [ ] Added feature
+- [ ] Documentation update
+- [ ] Other - Please explain here:
 
 
 * **What is the current behavior?** (You can also link to an open issue here)

.travis.yml

@@ -4,18 +4,18 @@ before_install:
   - source <(curl -SLs https://raw.githubusercontent.com/Marzogh/Travis-CI/master/install.sh)
 script:
   - build_main_platforms
-  #- build_platform trinket
   #- build_platform rtl8195a
   #- build_platform uno
   #- build_platform due
   #- build_platform zero
   #- build_platform esp8266
   #- build_platform leonardo
+  #- build_platform mega
   #- build_platform rtl8195a
   #- build_platform simblee
-  #- build_platform mega
-  #- build_platform fio
-  #- build_platform micro
+  #- build_platform cplayClassic
+  #- build_platform cplayExpress
+  #- build_platform trinket
 notifications:
   email:
     on_success: change

README.md

@@ -1,28 +1,52 @@
 # SPIFlash [![Build Status](https://travis-ci.org/Marzogh/SPIFlash.svg?branch=stable)](https://travis-ci.org/Marzogh/SPIFlash) [![DOI](https://zenodo.org/badge/18908/Marzogh/SPIFlash.svg)](https://zenodo.org/badge/latestdoi/18908/Marzogh/SPIFlash)
 [![GitHub release](https://img.shields.io/github/release/Marzogh/SPIFlash.svg)](https://github.com/Marzogh/SPIFlash)
-[![GitHub commits](https://img.shields.io/github/commits-since/Marzogh/SPIFlash/v3.0.0.svg)](https://github.com/Marzogh/SPIFlash/compare/v3.0.0...development)
+[![GitHub commits](https://img.shields.io/github/commits-since/Marzogh/SPIFlash/v3.0.0.svg)](https://github.com/Marzogh/SPIFlash/compare/v3.0.1...stable)
 [![GitHub issues](https://img.shields.io/github/issues/Marzogh/SPIFlash.svg)](https://github.com/Marzogh/SPIFlash/issues)
 [![GitHub pull requests](https://img.shields.io/github/issues-pr/Marzogh/SPIFlash.svg)](https://github.com/Marzogh/SPIFlash/pulls)
 [![license](https://img.shields.io/github/license/Marzogh/SPIFlash.svg)](https://github.com/Marzogh/SPIFlash/blob/master/LICENSE)
 
-### Arduino library for Flash Memory Chips (SPI based only)
-<sup> Download the latest stable release (v3.0.0) from <a href = "https://github.com/Marzogh/SPIFlash/releases/latest">here</a>. Please report any bugs in issues.</sup>
+## Arduino library for Flash Memory Chips (SPI based only)
+<sup> Download the latest stable release from [here](https://github.com/Marzogh/SPIFlash/releases/latest). Please report any bugs in [issues](https://github.com/Marzogh/SPIFlash/issues/new).</sup>
 
 This Arduino library is for use with flash memory chips that communicate using the SPI protocol. In its current form it supports identifying the flash chip and its various features; automatic address allocation and management; writing and reading a number of different types of data, ranging from 8-bit to 32-bit (signed and unsigned) values, floats, Strings, arrays of bytes/chars and structs to and from various locations; sector, block and chip erase; and powering down for low power operation.
+<hr>
+
+>### Important note from developer
+>The term 'SPI Flash' is a fairly common way to refer to Flash memory chips that communicate over the SPI protocol and there are a number of libraries that are named SPIFlash. When I first started work on this library in 2014, it was mostly as an exercise to improve my embedded systems programming skills. When I asked for it to be included in the list of Arduino libraries, I did not really expect it to go very far or get very popular. But, before I knew it, I was releasing new versions every other month and I found the number of users got way bigger than I imagined it would. The amount of traffic the GitHub repository gets still surprises me.
+>
+>A few months ago, @LowPowerLab raised an issue ([#83](https://github.com/Marzogh/SPIFlash/issues/83)) about the problems the name of this library was causing the users of his library - also called SPIFlash. The fact that this library is in the Arduino Library manager meant that his users were being asked to upgrade their version of SPIFlash when the libraries were actually different. I can understand how much of an annoyance this can be for a user.
+>
+>@LowPowerLab's version of SPIFlash has been around for longer than this one and his library is a major part of his commercial line of development boards. Since I am a hobbyist developer (I'm a full-time geneticist & a part-time dabbler in ecology - if you're curious) and this library is not a commercial product with branding and trademarks to worry about, the least I can do is change the name of this library so it stops being an annoyance to @LowPowerLab's customers.
+>> On a side note, if you did not know already, @LowPowerLab makes and sells a fantastic line of Arduino compatible boards - the [Moteino](https://lowpowerlab.com/shop/) series - and has developed a fantastic IoT protocol to use with them to add smarts to your home. In January this year, I finally got around to getting my hands on some of his boards and have been playing around with them. They are fantastic! I'd strongly recommend you check them out - if you haven't already done so.
+>
+>I asked the Arduino developers if there was a way to migrate this library to a new name without breaking the upgrade path ([Issue #6904](https://github.com/arduino/Arduino/issues/6904)) and was told that it was not possible. The only way is to pull my version of SPIFlash from the library manager and ask for a renamed version to be included in the library manager after.
+>
+>So, this is what I have decided to do.:
+>- This version - v3.1.0 - will be the last version to be released under the SPIFlash name.
+>- Anyone downloading this version of the library will be able to read this notice in the ReadMe file.
+>- Anyone using this version of the library will see a notice in their Serial output directing them to this notice in the ReadMe file. (this can be removed by commenting out the `#define PRINTNAMECHANGEALERT` in `SPIFlash.h`)
+>- Version 3.2.0 will be released in a couple of months (in May most likely) under a new name - SPIMemory.
+>- This version of SPIFlash will be removed from the library manager then and replaced with the new one.
+>
+>The only change will have to be made in end-user code will be to change the `#include SPIFlash.h` to `#include SPIMemory.h`. After the name change, rest assured that older versions will remain accessible and the development history of the library will be preserved.
+>
+>I apologise for any trouble this might cause you as the end user, but, given the facts, it is the only thing I can do to be fair to @LowPowerLab
+>
+>Thanks again for using `SPIFlash` and I hope you will continue to find it useful in whatever new name it will take on.
 
-- For details of the Flash chips compatible with this library please refer to the list below.
+<hr>
 
-#### Compatibility
+### Compatibility
 
-##### Arduino IDEs supported (actually tested with)
+#### Arduino IDEs supported (actually tested with)
 - IDE v1.5.x
 - IDE v1.6.0-v1.6.5
 - IDE v1.6.9-v1.6.12
 - IDE v1.8.1-v1.8.5
 
-##### Boards
+#### Boards
 
-###### Completely supported
+##### Completely supported
 - Arduino Uno
 - Arduino Leonardo
 - Arduino Due
@@ -36,16 +60,16 @@ This Arduino library is for use with flash memory chips that communicate using t
 - Arduino Micro
 - Arduino Fio
 
-###### In BETA
+##### In BETA
 - ESP32 Boards (Tested on the Adafruit ESP32 Feather) The library is known to work with the ESP32 core as of the current commit <a href = "https://github.com/espressif/arduino-esp32/commit/8ba91b945330303f9013f30da75c49c4d6dd8a09">8ba91b9</a> on 07.11.2017. ```ESP32 support will remain in beta till the ESP32 core can be installed via the Arduino boards manager.```
 NOTE: ESP32 boards usually have an SPIFlash already attached to their SS pin, so the user has to declare the ChipSelect pin being used when the constructor is declared - for example
 ```
 SPIFlash flash(33);
 ```
 
-##### Flash memory compatibility
+#### Flash memory compatibility
 
-###### Completely supported (Actually tested with)
+##### Completely supported (Actually tested with)
 - Winbond
   - W25Q16BV
   - W25Q64FV
@@ -58,67 +82,66 @@ SPIFlash flash(33);
   - S25FL116K
   - S25FL127S
 
-###### Should work with (Similar enough to the ones actually tested with)
+##### Should work with (Similar enough to the ones actually tested with)
 - Winbond (All SPI Flash chips)
 - Microchip (SST25 & SST26 series)
 - Cypress/Spansion (S25FL series)
 
-#### Installation
+### Installation
 
-##### Option 1
+#### Option 1
 - Open the Arduino IDE.
 - Go to Sketch > Include Library > Manage libraries.
 - Search for SPIFlash.
 - Install the latest version.
 
-##### Option 2
+#### Option 2
 - Click on the 'Clone or download' button above the list of files on this <a href = "https://github.com/Marzogh/SPIFlash/tree/master"> page </a>.
 - Select Download ZIP. A .zip file will download to your computer.
 - Unzip the archive and rename resulting folder to 'SPIFlash'
 - Move the folder to your libraries folder (~/sketches/libraries)
 
-#### Usage
+### Usage
 
 - The library is called by declaring the```SPIFlash flash(csPin*)``` constructor where 'flash' can be replaced by a user constructor of choice and 'csPin' is the Chip Select pin for the flash module.
 
     <sub>* Optional. Do not include csPin if using the default slave select pin for your board.</sub>
 - Every version of the library >= v3.0.0 supports the ability to use any of multiple SPI interfaces (if your micro-controller supports them). Switching to use another SPI interface is done by calling ```SPIFlash flash(csPin, &SPI1);``` (or &SPI2 and so on), instead of ```SPIFlash flash(csPin)```.
 
     <sub>* NOTE: This is currently only supported on the SAMD and STM32 architectures.</sub>
-- Make sure to include ```#include<SPI.H>``` when you include ```#include<SPIFlash.h>```.
 - Also make sure to include ```flash.begin(CHIPSIZE*)``` in ```void setup()```. This enables the library to detect the type of flash chip installed and load the right parameters.
 
     <sub>* Optional</sub>
 
-###### Notes on Address overflow and Error checking
+##### Notes on Address overflow and Error checking
 - The library has Address overflow enabled by default - i.e. if the last address read/written from/to,  in any function, is 0xFFFFF then, the next address read/written from/to is 0x00000. This can be disabled by uncommenting ```#define DISABLEOVERFLOW``` in SPIFlash.h. (Address overflow only works for Read / Write functions. Erase functions erase only a set number of blocks/sectors irrespective of overflow.)
 - All write functions have Error checking turned on by default - i.e. every byte written to the flash memory will be checked against the data stored on the Arduino. Users who require greater write speeds can disable this function by setting an optional last 'errorCheck' argument in any write function to NOERRCHK - For eg. call the function ```writeByte(address, *data_buffer, NOERRCHK)``` instead of ```writeByte(address, *data_buffer)```.
 
 The library enables the following functions:
 <hr>
 
-##### Non-I/O commands
+#### Non-Read/Write functions
 <hr>
 
-###### begin(_chipsize*)
-Must be called at the start in setup(). This function detects the type of chip being used and sets parameters accordingly. An optional CHIPSIZE parameter can be declared as an argument with this function. For supported CHIPSIZE values, please refer to the appropriate [wiki section](https://github.com/Marzogh/SPIFlash/wiki/begin()) or look at defines.h .
+###### `begin(_chipsize*)`
+Must be called at the start in setup(). This function detects the type of chip being used and sets parameters accordingly. An optional CHIPSIZE parameter can be declared as an argument with this function. For supported CHIPSIZE values, please refer to the appropriate [wiki section](https://github.com/Marzogh/SPIFlash/wiki/Chipsize) or look at defines.h .
 
-###### setClock(clockSpeed)
+###### `setClock(clockSpeed)`
 Must be called straight after begin(). This function takes a 32-bit number as replacement for the default maximum clock speed (104MHz for Winbond NOR flash) thereby initiating future SPI transactions with the user-defined clock speed. Use with care.
 
-###### error(_verbosity)
+###### `error(_verbosity)`
 Returns the (8-bit) error code generated by the function called immediately before this is called. If the optional VERBOSE argument is used, a verbose troubleshooting report is printed to Serial. Refer to the [Error reporting](https://github.com/Marzogh/SPIFlash/wiki/Error-reporting) section the Wiki for further reference.
 
-###### getMANID()
+###### `getManID()`
 Returns the Manufacturer ID as a 16-bit value.
 
-###### getJEDECID()
+###### `getJEDECID()`
 Returns the JEDEC ID as a 32-bit value.
 
-###### getUniqueID()
+###### `getUniqueID()`
 Returns the Unique ID as a 64-bit value.
 
-###### getAddress(sizeOfData)
+###### `getAddress(sizeOfData)`
 Gets the next available address for use. Has two variants:
 * Takes the size of the data as an argument and returns a 32-bit address
 * Takes a three variables, the size of the data and two other variables to return a page number value & an offset into.
@@ -133,7 +156,7 @@ size = sizeof(variable) can be used for all types of data but String objects.
 ###### getCapacity()
 Returns the capacity in bytes as a 32-bit value.
 
-###### getmaxPage()
+###### getMaxPage()
 Returns the maximum number of pages in the flash memory as a 32-bit value.
 
 ###### functionRunTime()
@@ -258,6 +281,11 @@ Erases one 64KB block - 256 pages - containing the address to be erased. The blo
 
 ###### eraseChip()
 Erases entire chip. Use with care.
+
+###### eraseSection(address, sizeOfData)
+Erases the specific number of blocks/sectors to fit data (size defined by the sizeOfData arguement) into. When a user requires a large and variable (between writes) amount of data to be written to the flash memory on the fly and to have the correct amount of space erased to fit the data, this function will automatically calculate and erase the right amount of space to fit the data.
+
+Please note that if the the amount of data being written is consistently the same size, the pre-existing 'flash.eraseSector()', 'flash.eraseBlock32K()' and 'flash.eraseBlock64K()' functions will operate a lot faster.
 <hr>
 
 ##### Suspend/Resume commands