From 02c3481048785bccff5aee758edcd17aa4729011 Mon Sep 17 00:00:00 2001
From: mmcw-dev <hi@mmcwilliams.com>
Date: Wed, 17 Oct 2018 23:24:38 -0400
Subject: [PATCH] Add comments to intval2_buttons.ino, which is the first
 2-speed version of the script.

---
 ino/intval2_buttons/intval2_buttons.ino | 69 ++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/ino/intval2_buttons/intval2_buttons.ino b/ino/intval2_buttons/intval2_buttons.ino
index 567850d..bd88dc1 100644
--- a/ino/intval2_buttons/intval2_buttons.ino
+++ b/ino/intval2_buttons/intval2_buttons.ino
@@ -16,7 +16,7 @@ const int SLOW_PWM = 127;
 /* ------------------------------------------------
  *  pins
  * ------------------------------------------------*/
-//Trinket Pro
+//5V Trinket Pro
 const int PIN_INDICATOR = 13;
 const int PIN_MOTOR_FORWARD = 9;
 const int PIN_MOTOR_BACKWARD = 10;
@@ -55,11 +55,21 @@ volatile int cam_pos = 0;
 
 volatile long seq_delay = 42;
 
+/* ------------------------------------------------
+ *  Runs once at startup, defines pin modes for
+ *  buttons and other inputs.
+ * ------------------------------------------------*/
 void setup () {
   Pins_init();
   Buttons_init();
 }
 
+/* ------------------------------------------------
+ *  Runs constantly, sets a timer at beginning of loop,
+ *  checks states of every button and then either compares
+ *  the timer to the delay end, watches for the microswitch
+ *  to stop the frame or alternately delays for LOOP_DELAY.
+ * ------------------------------------------------*/
 void loop () {
   timer = millis();
   Btn(0);
@@ -77,6 +87,10 @@ void loop () {
   }
 }
 
+/* ------------------------------------------------
+ *  Defines pin modes for motor control pins, microswitch
+ *  and the indicator (LED) pin.
+ * ------------------------------------------------*/
 void Pins_init () {
   pinMode(PIN_MOTOR_FORWARD, OUTPUT);
   pinMode(PIN_MOTOR_BACKWARD, OUTPUT);
@@ -84,6 +98,11 @@ void Pins_init () {
   pinMode(PIN_INDICATOR, OUTPUT);
 }
 
+/* ------------------------------------------------
+ *  Starts a frame by updating the frame_start timer,
+ *  starts motor in set direction, sets running flag
+ *  to true and primes the micoswitch flag.
+ * ------------------------------------------------*/
 void Frame () {
   frame_start = millis();
   if (cam_dir) {
@@ -97,6 +116,12 @@ void Frame () {
   micro_primed = false;
 }
 
+/* ------------------------------------------------
+ *  Determines whether or not the motor has turned
+ *  far enough to start reading the micoswitch state.
+ *  This prevents the switch from checking too early,
+ *  while it is not yet pressed.
+ * ------------------------------------------------*/
 boolean Read_delay () {
   if (fwd_speed == FAST_PWM) {
       if (timer - frame_start >= 300) {
@@ -110,6 +135,12 @@ boolean Read_delay () {
   return false;
 }
 
+/* ------------------------------------------------
+ *  Reads the state of the microswitch after the
+ *  Read_delay() period. If the micoswitch is pressed,
+ *  set the micro_primed flag to true. If primed and
+ *  microswitch gets opened, Stop() the frame.
+ * ------------------------------------------------*/
 void Read_micro () {
   if (Read_delay()) {
     micro_position = digitalRead(PIN_MICRO);
@@ -124,6 +155,10 @@ void Read_micro () {
   }
 }
 
+/* ------------------------------------------------
+ *  Determines when the delay period between frames
+ *  in a sequence is over.
+ * ------------------------------------------------*/
 void Watch_delay () {
   if (timer - delay_start >= seq_delay) {
     delaying = false;
@@ -131,6 +166,12 @@ void Watch_delay () {
   }
 }
 
+/* ------------------------------------------------
+ *  Stops the motor after a 10ms delay. Increments
+ *  a cam counter when complete. Resets running and
+ *  micro_primed flags to false, starts delaying if
+ *  sequence flag is set to true.
+ * ------------------------------------------------*/
 void Stop () {
   delay(10);
   analogWrite(PIN_MOTOR_FORWARD, 0);
@@ -151,7 +192,9 @@ void Stop () {
     delay_start = millis();
   }
 }
-
+/* ------------------------------------------------
+ *  Turns on or off the indicator LED.
+ * ------------------------------------------------*/
 void Indicator (boolean state) {
   if (state) {
     digitalWrite(PIN_INDICATOR, HIGH);
@@ -160,12 +203,24 @@ void Indicator (boolean state) {
   }
 }
 
+/* ------------------------------------------------
+ *  Declare the pin mode of all buttons as, input pullup
+ *  which enables the internal pullup resistor.
+ * ------------------------------------------------*/
 void Buttons_init () {
   for (int i = 0; i < 4; i++) {
     pinMode(BUTTON[i], INPUT_PULLUP);
   }
 }
 
+/* ------------------------------------------------
+ *  Reads the state of a specific button and compares
+ *  it to a stored value in the button_state array.
+ *  If the value is different than what is stored,
+ *  check if button is pressed and store new timer value,
+ *  if button is released, compare current time to the stored
+ *  time value and pass that to the button_end function.
+ * ------------------------------------------------*/
 void Btn (int index) {
   int val = digitalRead(BUTTON[index]);
   if (val != button_state[index]) {
@@ -187,6 +242,11 @@ void Btn (int index) {
   }
 }*/
 
+/* ------------------------------------------------
+ *  Determines a specific action for each press length
+ *  of each button. In most cases a press over 1 second is
+ *  distinct from one less than 1 second.
+ * ------------------------------------------------*/
 void button_end (int index, long buttontime) {
   if (index == 0) {
     if (buttontime > 1000) {
@@ -233,6 +293,11 @@ void button_end (int index, long buttontime) {
   buttontime = 0;
 }
 
+
+/* ------------------------------------------------
+ *  Display a specified number of flashes on the 
+ *  indicator LED for a specified amount of time.
+ * ------------------------------------------------*/
 void Output (int number, int len) {
   for (int i = 0; i < number; i++) {
     Indicator(true);