Bug Fix/Doc Update: Spurious 'pinMode' spoil the work of the lib, update of the readme and code comments.

Author: stdevPavelmc

README.md

@@ -8,7 +8,9 @@ Acctually we have the following features implemented:
 
 * Up to 8 buttons in a single Analog pin _(by default limited to 8 to keep firmware footprint low, it's tunable in software)_.
 * Secondary functions (press & hold) in each button, configured on demand.
-* Intuitive behavior in the case you held a button pressed (_on the original AnalogButtons library when you held a button you got two events, first a click and then a hold one, that's not acceptable for some uses._)
+* Intuitive behavior in the case you held a button pressed (_on the original AnalogButtons library when you held a button you got two events, first a click and then a hold one, that's not intuitive._)
+* Single click event (the click does not repeat itself)
+* Hold event will repeat at a pace defined by the hold limit (if you keep the button pressed long enough)
 
 ## Inspiration ##
 
@@ -21,7 +23,20 @@ This library is based in the following source codes:
 
 The first thing to do is determine how many buttons you will manage in the analog pin. By default max number of buttons per pin is limited to 8 to limit memory consumption (you can declare less or more buttons as your need commands), it can be controlled defining the `BUTTONS_COUNT` macro **before** including this library.
 
-You then create an instance of the lib to be configured and user later in our code; like this:
+It's time to play with your hardware, to setup a resistor network you have two main variants:
+
+* As a fixed resistors stair values
+* As a multiple resistors values
+
+The two main configuration can be seen on the file Resistors_variants.png in the project folder.
+
+**Note:** _In theory you can declare up to ~21 buttons with a +/- 20 units of tolerance and a guard zone of 10 units_
+
+_That means that you have to setup your resistors in a way that the specific central values are at least 3 units of tolerance away from each other, if not you will have problems_
+
+_For example if your resistor network yields a values of 256, 270 and 350 and you use the default 10 units of tolerance the first two will make you in trouble as 270 - 256 = 14; as you can see 14 is less than the recommended 30 units (3 * 10)_
+
+Now you create an instance of the lib at the beginning of your code; like this:
 
 ```
 BMux abm;

examples/AnalogButtonMuxer/AnalogButtonMuxer.ino

@@ -34,7 +34,7 @@
 
 #include <BMux.h>
 
-#define ANALOG_PIN A1
+#define ANALOG_PIN A2
 
 // First define the callback functions for the buttons action handling,
 // in this example just a Serial notification
@@ -86,7 +86,7 @@ Button b5 = Button(860, &b5Click, &b5Hold, 5000);
 
 void setup() {
     Serial.begin(9600);
-    Serial.println("Testing your Analog buttons 2");
+    Serial.println("Testing your Analog Button Muxer Library");
 
     abm.init(ANALOG_PIN, 5, 20);
     abm.add(b1);
@@ -103,7 +103,7 @@ void loop() {
     // To configure the MAX/Min values for each button: uncomment the following
     // line and attach a serial terminal to see the data and note down the values
 
-    //configure();
+    configure();
 }
 
 void configure() {

src/BMux.cpp

@@ -48,7 +48,6 @@ void BMux::init(uint8_t pin, uint8_t debounce, uint8_t margin) {
     this->pin = pin;
     this->debounce = debounce;
     this->margin = margin;
-    pinMode(pin, INPUT);
 }
 
 void BMux::add(Button button) {
@@ -58,21 +57,36 @@ void BMux::add(Button button) {
 }
 
 void BMux::check() {
-    // In case this function gets called very frequently avoid sampling the analog pin too often: max frequency is 50Hz
-    if (millis() - time > 20) {
+    // In case this function gets called very frequently avoid sampling the
+    // analog pin too often: default (max) frequency is 50Hz
+    if (millis() - time > 1000 / BMUX_SAMPLING) {
         time = millis();
         uint16_t reading = analogRead(pin);
         uint16_t msec = 0;
+        uint16_t min = 0;
+        uint16_t max = 0;
 
         // we changed the strategy here, all events will be emitted on button release
         for (uint8_t i = 0; i < buttonsCount; i++) {
-            if (reading >= buttons[i].value - margin && reading <= buttons[i].value + margin) {
+            // low limit checking (this led to overflows in the past)
+            if (buttons[i].value <= margin) {
+                min = 0;
+            } else {
+                min = buttons[i].value - margin;
+            }
+
+            // max limit check
+            max = buttons[i].value + margin;
+            if (max > 1023) max = 1023;
+
+            // checking
+            if (reading >= min && reading <= max) {
                 // just increment the count of the pressed buttons
                 buttons[i].counter += 1;
 
                 // check for button held & still pressed
                 msec = buttons[i].counter;
-                msec *= 20;
+                msec *= 1000 / BMUX_SAMPLING;
                 if (msec >= buttons[i].duration) {
                     buttons[i].held();
                     buttons[i].counter = 0;

src/BMux.h

@@ -49,6 +49,8 @@
 
 
 // Take into account that by default we use a sampling interval of 50Hz
+// but you can change that setting by declaring a external var before
+// loading the lib in your code, BMUX_SAMPLING is the var
 
 #include "Arduino.h"
 
@@ -59,11 +61,15 @@
     #define BUTTONS_COUNT 8
 #endif
 
+#ifndef BMUX_SAMPLING
+    #define BMUX_SAMPLING 50    // how many times per second will be sampled
+#endif
+
 class Button {
 public:
     uint16_t value;         // to hold a max of 1023
     uint16_t duration;      // in msecs, max is 65.5 seconds
-    uint8_t counter;        // in sample intervals of 50Hz (20 msecs)
+    uint8_t counter;        // in sample intervals of BMUX_SAMPLING
     boolean isHeld;         // flag to sign that the button is held
 
     Button() {};
@@ -87,7 +93,7 @@ class Button {
 
 class BMux {
 private:
-    uint8_t debounce;       // in sample intervals
+    uint8_t debounce;       // in sample intervals of BMUX_SAMPLING
     uint32_t time;          // time stamp to define the sampling interval
     uint8_t margin;         // max is 255, which is bigger than we need
     uint8_t pin;            // the analog pin