2.0.0

joshnishikawa · joshnishikawa · commit 73f4a098af16 · 2023-03-30T15:15:43.000+09:00
diff --git a/README.md b/README.md
@@ -1,10 +1,20 @@
-# Flicker 1.1.4
+# Flicker 2.0.0
 ### A library for making capacitive touch easy to use.
 ###### by Josh Nishikawa <github.com/joshnishikawa/Flicker>
 ###### The "TouchSwitch" class was adapted from the Bounce library by: Thomas O Fredericks, Eric Lowry, Jim Schimpf and Tom Harkaway
 Includes all the functions found in the Bounce library, smoothes eratic values to make variable input more useful and includes functions for measuring velocity.
 ___
 ### VERSION LOG:
+2.0.0
+- Thresholds for TouchSwitch are now set more dynamically and updated when
+  highest/lowest readings are updated. This better accommodates more setups 
+  regardless of quiescent readings or ranges between highest/lowest readings.
+
+- setThresholds() MUST be called during setup and requires two arguments: the lowest possible reading that detects your finger and the reading at which a the value should be returned (contact). Use rangeFinder.ino to find these values.
+- responsiveRead() is deprecated. Use read() instead.
+- Setting outLo and outHi in the constructor is deprecated. Just map the return
+  value of read() in the sketch.
+
 
 1.1.4 
 - Added previousDuration() function that can be used on rising/falling edge to return the length of the input's previous state.
diff --git a/examples/multitask_example/multitask_example.ino b/examples/multitask_example/multitask_example.ino
@@ -5,7 +5,7 @@
 // Also, a variable reading is taken from the same input,
 // mapped to a range of 0~1023 and printed to serial.
 
-const uint8_t touchPin = 15; // CHOOSE A TOUCH PIN
+const uint8_t touchPin = 0; // CHOOSE A TOUCH PIN
 const uint8_t ledPin = 13;
 bool ledState = false;
 int preVal = 0;
diff --git a/examples/on-off_stable/on-off_stable.ino b/examples/on-off_stable/on-off_stable.ino
@@ -3,7 +3,7 @@
 // If you hold your finger on the input,
 // something will happen.
 
-const uint8_t touchPin = 15; // CHOOSE A TOUCH PIN
+const uint8_t touchPin = 0; // CHOOSE A TOUCH PIN
 const uint8_t ledPin = 13;
 TouchSwitch myInput(touchPin);
 
@@ -14,7 +14,11 @@ void setup() {
   // WARNING! if you setThreshold with no argument,
   // the threshold is calculated based on a call to
   // touchRead() so DON'T touch the input during setup()
-  myInput.setThreshold(); 
+  myInput.setThreshold();
+
+  // Use rangeFinder.ino to find a specific threshold
+  // Then replace '1200' and use the following line instead.
+  // myInput.setThreshold(1200);
 }
 
 void loop() {
diff --git a/examples/rangeFinder/rangeFinder.ino b/examples/rangeFinder/rangeFinder.ino
@@ -0,0 +1,36 @@
+/*
+  This is not an example for how to use this library.
+  Rather, it's a utility to find a usable range and/or
+  thresholds for your particular needs. Get the values
+  printed in the serial monitor to use in other sketches.  
+*/
+
+#include "Bounce2.h"
+
+int touchPin = 0; // Change to the TOUCH pin you want to use.
+int resetPin = 19; // you can set a pin to reset hi/lo
+Bounce reset = Bounce(resetPin, 50);
+int hi;
+
+void setReset(){
+  hi = touchRead(touchPin);
+  Serial.print("High Touch: "); Serial.println(hi);
+}
+
+void setup(){
+  pinMode(resetPin, INPUT_PULLUP);
+  setReset();
+}
+
+void loop(){
+  reset.update();
+  if(reset.rose()){
+    setReset();
+  }
+
+  int newVal = touchRead(touchPin);
+  if (newVal > hi){
+    hi = newVal;
+    Serial.print("High Touch: "); Serial.println(hi);
+  }
+}
diff --git a/examples/switch_duration/switch_duration.ino b/examples/switch_duration/switch_duration.ino
@@ -3,7 +3,7 @@
 // If you hold your finger on the input
 // for long enough, something will happen.
 
-const uint8_t touchPin = 15; // CHOOSE A TOUCH PIN
+const uint8_t touchPin = 0; // CHOOSE A TOUCH PIN
 const uint8_t ledPin = 13;
 TouchSwitch myInput(touchPin);
 
@@ -14,7 +14,12 @@ void setup() {
   // the threshold is calculated based on a call to
   // touchRead() so DON'T touch the input during setup()
   myInput.setThreshold(); 
-  myInput.interval(300); // How long to hold?
+
+  // Use rangeFinder.ino to find a specific threshold
+  // Then replace '1200' and use the following line instead.
+  // myInput.setThreshold(1200);
+
+  myInput.interval(300); // How long to hold before response?
 }
 
 void loop() {
diff --git a/examples/switch_latch/switch_latch.ino b/examples/switch_latch/switch_latch.ino
@@ -3,7 +3,7 @@
 // The input goes on when touched
 // and off when touched again.
 
-byte touchPin = 15; // CHOOSE A TOUCH PIN
+byte touchPin = 0; // CHOOSE A TOUCH PIN
 byte ledPin = 13;
 
 // MOMENTARY (the default) or LATCH can be specified
diff --git a/examples/switch_previousDuration/switch_previousDuration.ino b/examples/switch_previousDuration/switch_previousDuration.ino
@@ -3,7 +3,7 @@
 // This will tell you how long the input stayed in its PREVIOUS state.
 // It may be useful to call this within rose() or fell().
 
-const uint8_t touchPin = 15; // CHOOSE A TOUCH PIN
+const uint8_t touchPin = 0; // CHOOSE A TOUCH PIN
 const uint8_t ledPin = 13;
 TouchSwitch myInput(touchPin);
 
diff --git a/examples/switch_retrigger/switch_retrigger.ino b/examples/switch_retrigger/switch_retrigger.ino
@@ -3,7 +3,7 @@
 // As long as the input is held, 
 // it will be triggered repeatedly.
 
-const uint8_t touchPin = 15; // CHOOSE A TOUCH PIN
+const uint8_t touchPin = 0; // CHOOSE A TOUCH PIN
 const uint8_t ledPin = 13;
 bool ledState = false;
 TouchSwitch myInput(touchPin); 
diff --git a/examples/variable_setOutputRange/variable_setOutputRange.ino b/examples/variable_setOutputRange/variable_setOutputRange.ino
@@ -3,7 +3,7 @@
 // Map the variable touuch input to a specific range.
 // Examples: 0~1023 to emulate analog; or 0~127 for MIDI.
 
-byte touchPin = 15; // CHOOSE A TOUCH PIN
+byte touchPin = 0; // CHOOSE A TOUCH PIN
 int preVal;
 TouchVariable myInput(touchPin);
 
@@ -14,7 +14,7 @@ void setup() {
   // the input range is calculated based on a call to
   // touchRead() so DON'T touch the input during setup()
   myInput.setInputRange();
-  myInput.setOutputRange(0, 1023); // 7-bit MIDI
+  myInput.setOutputRange(0, 1023); // 10-bit analog
 }
 
 void loop(){
diff --git a/examples/variable_stable/variable_stable.ino b/examples/variable_stable/variable_stable.ino
@@ -4,7 +4,7 @@
 // value only when the signal is biased enough.
 // The larger the change, the more immediate the response.
 
-byte touchPin = 15; // CHOOSE A TOUCH PIN
+byte touchPin = 0; // CHOOSE A TOUCH PIN
 byte ledPin = 13;
 int preVal;
 TouchVariable myInput(touchPin);
diff --git a/examples/velocity_MIDI/velocity_MIDI.ino b/examples/velocity_MIDI/velocity_MIDI.ino
@@ -1,24 +1,29 @@
 #include <Flicker.h>
 
-/* This detects how hard/fast an input is touched and
-   sends a MIDI note with corresponding velocity.
-   Be sure to choose MIDI from the "Tools/USB Type" menu.*/
+/* WARNING! This example is useless if you haven't used the velocity_basic
+   example to determine the fastest and slowest readings that you want to map
+   to MIDI velocities. Once you have those numbers, enter them here.*/
+int slowest = 2200;
+int fastest = 550;
 
-byte touchPin = 15; // CHOOSE A TOUCH PIN
+byte touchPin = 0; // CHOOSE A TOUCH PIN
 int noteNumber = 38; // CHOOSE A NOTE TO PLAY
 
-// Parameters are: pin, minimum velocity, maximum velocity
-TouchVelocity myInput(touchPin, 1, 127);
+TouchVelocity myInput(touchPin);
  
 void setup() {
-  // WARNING! setThreshold() uses a call to touchRead()
-  // so DON'T touch the input during setup()
-  myInput.setThreshold();
+  // WARNING! You must pass two arguments to setThresholds()
+  // Use the rangeFinder example to get a reading with your finger 1mm above the
+  // input and another reading with your finger lightly touching the input.
+  // You will not likely be able to use these values (900, 1250) as is.
+  myInput.setThresholds(900, 1250);
 }
 
 void loop(){
-  int velocity = myInput.responsiveRead();
+  int velocity = myInput.read();
   if (velocity >= 1){
+    velocity = map(velocity, slowest, fastest, 1, 127);
+    velocity = constrain(velocity, 1, 127);
     usbMIDI.sendNoteOn(noteNumber, velocity, 0);
   }
   if (myInput.fell()){
diff --git a/examples/velocity_basic/velocity_basic.ino b/examples/velocity_basic/velocity_basic.ino
@@ -6,16 +6,19 @@
    The LED lights when your finger goes below the
    'hover' threshold to act as a 'ready' light.*/
 
-byte touchPin = 15; // CHOOSE A TOUCH PIN
+byte touchPin = 0; // CHOOSE A TOUCH PIN
 byte LED = 13;
 TouchVelocity myInput(touchPin);
  
 void setup() {
   pinMode(LED, OUTPUT);
   
-  // WARNING! setThreshold() uses a call to touchRead()
-  // so DON'T touch the input during setup()
-  myInput.setThreshold();
+  // WARNING! You must pass two arguments to setThresholds()
+  // Use the rangeFinder example to get a reading with your finger 1mm above the
+  // input and another reading with your finger lightly touching the input.
+  // You will not likely be able to use these values (900, 1250) as is.
+  myInput.setThresholds(900, 1250);
+
   digitalWrite(LED, HIGH); 
 }
 
diff --git a/library.properties b/library.properties
@@ -1,9 +1,9 @@
 name=Flicker
-version=1.1.4
+version=2.0.0
 author=Josh Nishikawa <joshnishikawa@gmail.com>
 maintainer=Josh Nishikawa <joshnishikawa@gmail.com>
 sentence=A library for making capacitive touch easy to use.
-paragraph=Includes all the functions found in the Bounce library, smoothes eratic values to make variable input more useful and includes functions for measuring velocity.
+paragraph=Includes all the functions found in the Bounce library, smoothes eratic values to make variable input more useful and includes a class for measuring velocity.
 category=Sensors
 url=https://github.com/joshnishikawa/Flicker
 architectures=avr
diff --git a/src/TouchSwitch.cpp b/src/TouchSwitch.cpp
@@ -5,40 +5,62 @@ TouchSwitch::TouchSwitch(){};
 TouchSwitch::TouchSwitch(byte pin){
   this->pin = pin;
   latched = false;
+  setThreshold(); // only works if creating objects during setup
 };
 
 TouchSwitch::TouchSwitch(byte pin, byte mode){
   this->pin = pin;
   this->latched = mode;
+  setThreshold(); // only works if creating objects during setup
 };
 
-TouchSwitch::TouchSwitch(byte pin, byte mode, int onThreshold){
+TouchSwitch::TouchSwitch(byte pin, byte mode, int onT){
   this->pin = pin;
   latched = mode;
-  this->onThreshold = onThreshold;
-  offThreshold = onThreshold / 1.2 * 1.1;
+  onThreshold = onT;
+  setThreshold(onThreshold); // only works if creating objects during setup
 };
 
 TouchSwitch::~TouchSwitch(){};
 
 
 void TouchSwitch::setThreshold(){
-  int qval = 0;
   analogRead(A0); // The ADC can affect touch values so fire it up first.
+  inLo = touchRead(pin);
+  onThreshold = inLo * 1.1;  // initial threshold 10% above quiescent
+  updateThreshold(inLo, onThreshold); // updated on higher reading
+}
 
-  for (int i = 0; i < 10; i++){ // store the highest quiescent reading of 10
-    int newValue = touchRead(pin);
-    if (newValue > qval) qval = newValue;
-  }
 
-  onThreshold =  qval * 1.2; // Threshold for rising edge
-  offThreshold = qval * 1.1; // Slightly lower for falling edge
+void TouchSwitch::setThreshold(int threshold){
+  userSetThreshold = true;
+  onThreshold = threshold;
+  analogRead(A0); // The ADC can affect touch values so fire it up first.
+  inLo = touchRead(pin);
+
+  // breaks if user-set threshold is lower than the quiescent reading
+  updateThreshold(inLo, onThreshold);
 }
 
 
-void TouchSwitch::setThreshold(int threshold){
-  onThreshold = threshold; // Threshold for rising edge
-  offThreshold = threshold / 1.2 * 1.1; // Slightly lower for falling edge
+void TouchSwitch::updateThreshold(int low, int high){ // internal use only
+  inLo = low;
+  inHi = high;
+  int range = inHi - inLo;
+
+  if (!userSetThreshold){
+    // Assumes that halfway between lowest & highest readings is a good place
+    // for a threshold. Still a magic number but at least it's somewhat dynamic.
+    onThreshold = inLo + range * 0.5;
+    offThreshold = inLo + range * 0.3;
+  }
+  else{
+    // The user can forego assumptions and set the threshold themselves.
+    // We need to know where the threshold is in relation to the range of values
+    float sens = float(onThreshold - inLo) / float(range);
+    // Then we set the offThreshold to be 10% below the onThreshold
+    offThreshold = inLo + range * (sens - 0.1);
+  }
 }
 
 
@@ -62,9 +84,9 @@ int TouchSwitch::read(){
 }
 
 
-byte TouchSwitch::rose() {return stateChanged && state; }
+byte TouchSwitch::rose() { return stateChanged && state; }
 
-byte TouchSwitch::fell() {return stateChanged && !state; }
+byte TouchSwitch::fell() { return stateChanged && !state; }
 
 
 unsigned long TouchSwitch::duration(){
@@ -92,6 +114,9 @@ int TouchSwitch::trigger(){
   int newValue = touchRead(pin);
   int current_millis = millis();
 
+  if (newValue > inHi){updateThreshold(inLo, newValue);}
+  else if (newValue < inLo){updateThreshold(newValue, inHi);}
+
   if(latched){ // LATCH behavior
     if (newValue >= onThreshold){
       if (waiting && held_millis >= interval_millis){
@@ -161,4 +186,3 @@ int TouchSwitch::trigger(){
       return 0;}
   }
 }
-
diff --git a/src/TouchSwitch.h b/src/TouchSwitch.h
@@ -20,7 +20,7 @@ class TouchSwitch{
     TouchSwitch(byte pin, byte mode);
 
     // Initialize a momentary or latched switch with a specific threshold.
-    TouchSwitch(byte pin, byte mode, int onThreshold);
+    TouchSwitch(byte pin, byte mode, int onT);
 
     // Destructor
     ~TouchSwitch();
@@ -60,19 +60,20 @@ class TouchSwitch{
     unsigned long previousDuration();
 
   protected:
+    byte pin = 0;
+    bool latched = false;
+    bool waiting = false;
+    bool stateChanged = false;
+    int inHi, onThreshold, offThreshold, inLo;
     int trigger();
-    byte state = 0;
-    int onThreshold = 0;
-    int offThreshold = 0;
+    void updateThreshold(int low, int high);
+    bool state = false;
+    bool userSetThreshold = false;
     elapsedMillis held_millis = 0;
     unsigned long previous_millis = 0;
     unsigned long interval_millis = 0;
     unsigned long retrigger_millis = 0;
     unsigned long durationOfPreviousState;
-    byte pin = 0;
-    bool latched = false;
-    bool waiting = false;
-    bool stateChanged = false;
 };
 
 #endif
diff --git a/src/TouchVariable.cpp b/src/TouchVariable.cpp
diff --git a/src/TouchVariable.h b/src/TouchVariable.h
diff --git a/src/TouchVelocity.cpp b/src/TouchVelocity.cpp
diff --git a/src/TouchVelocity.h b/src/TouchVelocity.h
