⬆️ Release non-blocking v2.0.0 (#5)

* ✨ 🐎 Initial non-blocking v2.0.0 code

* 📝 Add calibrationRatio README

* 🐛 Fix code syntax issues

* 📝 Add library.properties

.editorconfig

@@ -8,10 +8,7 @@ indent_size = 2
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false
+insert_final_newline = true
 
 [keywords.txt]
 indent_style = tab

README.md

@@ -1,65 +1,47 @@
 # Arduino Shutters
 
-This Arduino library allows non-smart roller-shutters to be controlled using time.
+This Arduino library allows non-smart roller-shutters to be percentage-controlled using time.
 Using relays, it is easy to make shutters go up and down. But I wanted to be able
-to make the shutters go halfway (50%) for example. So I built this lib.
+to make the shutters go halfway (50%) for example. So I built this library.
 
 ## Features
 
 * Ability to set aperture percentage
 * Power outage safe
-  * Shutters state saved in EEPROM (using 1 byte)
-    * ESP8266 compatible
-* Automatic recalibration
-* Flexible control method (might use relays, RF...)
+  * Shutters state saved using 1 byte
+  * Store in EEPROM, SPIFFS, etc. using callbacks
+* Automatic calibration on extremes (0% and 100%)
+* Flexible control method (might use relays, RF, etc.) using callbacks
 
 ## Requirement
 
-* Measure as precisely as possible the time of a full course in seconds
-
-## Notes
-
-#### EEPROM lifetime
-
-An Arduino EEPROM cell (byte) is rated for 100 000 erase cycles.
-This library is optimized to use the EEPROM as little as possible.
-Each time you use the `requestLevel` or `stop` functions, 1 erase happens.
-To illustrate that, let's say you open and close your shutters 4 times a day.
-The EEPROM won't die until at least `100 000/365/4 ~= 68.5` years — this should be enough, nope? —.
+* Measure as precisely as possible the time of a full shutters course
+* The initial state callback must return 255 on first boot
 
 ## Installation
 
 1. Download the [latest version](https://github.com/marvinroger/arduino-shutters/archive/master.zip)
 2. Load the `.zip` with **Sketch → Include Library → Add .ZIP Library**
-3. Be sure that the EEPROM byte you want to use (0 by default) is clear.
-You can load the EraseEEPROM example sketch to achieve this
 
 ## API
 
 See examples folder for examples.
 
-#### Shutters (float `time_full_course`, void (\*`upCallback`)(void), void (\*`downCallback`)(void), void (\*`haltCallback`)(void), byte `eeprom_offset` = 0)
+#### Shutters (unsigned long `courseTime`, void (\*`upCallback`)(void), void (\*`downCallback`)(void), void (\*`haltCallback`)(void), byte (\*`getStateCallback`)(void), void (\*`setStateCallback`)(byte state), float `calibrationRatio` = 0.1)
 
-* **`time_full_course`**: Time in seconds to do a full shutters course
+* **`courseTime`**: Time in milliseconds to do a full shutters course
 * **`upCallback`**: Function to execute for the shutters to go up
 * **`downCallback`**: Function to execute for the shutters to go down
 * **`haltCallback`**: Function to execute for the shutters to halt
-* **`eeprom_offset`**: Maybe your code already uses EEPROM, so you can put an offset. Default to 0
+* **`getStateCallback`**: Function to get state. This must return the state byte, or 255 if you don't know the state byte (on first boot)
+* **`setStateCallback(byte state)`**: Function to set the state byte. Store this in the EEPROM of SPIFFS, etc.
+* **`calibrationRatio`**: The calibration ratio. If the full course is 30 sec. and the ratio is 0.1, the calibration time will be 30 * 0.1 = 3 sec. Defaults to 0.1
 
 #### bool .begin ()
 
 Setup the shutters. Must be called once in `setup()`.
-Return: read below.
-
-**First boot**: Initialize the EEPROM and put the shutters at their minimum position. This will be blocking for `time_full_course` seconds. Return true.
 
-**Subsequent boots**: If the Arduino was powered off while the shutters were not moving, nothing is done because the current state of the shutters is known and false is returned. Else, it will put the shutters at their minimum position so the level will be known again (being 0%), blocking for `time_full_course` seconds and true will be returned.
-
-#### void .loop ()
-
-Handle the shutters. Must be called in `loop()`. **Don't call `delay()` in loop() as it will block the loop, so Shutters will malfunction.**
-
-#### void .requestLevel (byte `percentage`)
+#### void .setLevel (byte `percentage`)
 
 Put the shutters to the given position.
 Note that if `percentage` == 0 || `percentage` == 100, the shutters will recalibrate (relays will stay active a bit longer than it should to ensure the shutters are really at their minimum or maximum position).
@@ -70,20 +52,18 @@ Note that if `percentage` == 0 || `percentage` == 100, the shutters will recalib
 
 Stop the shutters.
 
-#### bool .moving ()
+#### bool .isIdle ()
 
-Return whether the shutters are currently moving or not.
+Return whether the shutters are currently idle or not.
 
-#### byte .currentLevel ()
+#### void .loop ()
 
-Return the current level of the shutters. Might be +/- 1% if the shutters are moving.
+Handle the shutters. Must be called in `loop()`. **Don't call `delay()` in loop() as it will block the loop, so Shutters will malfunction.**
 
-#### bool .reached ()
+#### byte .getCurrentLevel ()
 
-Return whether or not the shutters just reached the latest requested level. For example, if the shutters are at 0% and you requested 100%, `reached()` will be true once, allowing you to report to the controller that the shutters reached the requested level.
+Return the current level of the shutters. Might be +/- 1% if the shutters are moving.
 
-#### void .eraseSavedState ()
+#### void .reset ()
 
-Erase data stored in EEPROM, for example for a reset routine.
-Once erased, don't forget to restart/reset the Arduino, otherwise EEPROM might
-be rewritten if `requestLevel` is called for example.
+Erase saved state, for example for a reset routine. This disables the library, so don't forget to restart/reset the Arduino.