Understanding and Using Button Switches

1//
2//
3//  This example and code is in the public domain and may  be used without restriction and
4//  without warranty.
5
6/*
7  READING  SIMPLE SWITCHES RELIABLY, WITH OR WITHOUT A SWITCH PULL DOWN RESISTER
8  '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
9  In this example sketch we look at configuring a simple button switch such that  when pressed
10  it will toggle a LED on and off.  The sketch automatically allows  for one of two switch
11  circuits to be configured, either with a pull down switch  resister or without.  This is configured
12  and controlled with a simple macro  parameter - see points of note below.
13
14  Additionally, this sketch offers  two methods to read a simple button switch, each offered as a
15  specific function.  Only one function method should be configured (..._method_1/..._method_2),
16  the choice left to preference of the user. The differences between each method  is highlighted and
17  explained below:
18    Method 1 -  Function 'bool read_switch_method_1()'  - this version of switch reading examines the switch
19                input once  each time the function is called.
20                This allows the code section  from which it is called to continue without waiting
21                for the switch  press cycle to complete once switching is initiated.
22                Only drawback,  of course, is that the design of the calling code must ensure that the
23                switch  is regularly tested to catch a change in switch status.
24
25    Method 2 -  Function  'bool read_switch_method_2()' - this version of switch reading will wait for a
26                switch cycle to complete, once it is initiated, before control is  returned to the calling code.
27                Once the switch is pressed, the  code will fully consume the debounce period AFTER switch
28                release  until control is returned back to the calling code.
29                That is,  the calling code will be held up once the switch is pressed and until
30                the  debounce period has elapsed.
31
32  Points of note:
33    1.  The digital pin  chosen as the input is initialised according to the 'circuit_type' macro
34        parameter,  either INPUT_PULLUP or INPUT using a call to pinMode(button_switch,circuit_type)
35        in the setup() function.
36        As the conditions for detecting switch  on/off are different for each 'circuit_type' (they are
37        reversed) two  variables are used ('switch_low' and 'switch_high') to provide a reference
38        indicating  low and high (on/off) conditions.  However, this is transparent to the functioning
39        of the code.  The only requirement is to define the 'circuit_type', everything  else is
40        automatically taken care of.
41
42    2.  The design for each  reading method incorporates code to debounce spurious inputs when the switch
43        is pressed which, if not accounted for, would produce unexpected/spurious  results.
44
45    3.  The wiring designs for each type of switch circuit are:
46
47        With switch pull down resister configured and 'circuit_type' of INPUT
48
49              10K ohm     button      (onboard)
50              resister    switch         LED
51          ____|<><><>|_______ \\___        O
52         |              |         |       |
53         0v         pin = 2      +5v    pin =
54                                    LED_BUILTIN
55         ___________________________________
56         |            ARDUINO              |
57
58        With NO switch pull down resister configured and 'circuit_type' of INPUT_PULLUP
59
60             button     (onboard)
61             switch        LED
62            ___  \\___        O
63           |        |       |
64         pin 2     0v     pin  =
65                       LED_BUILTIN
66         _______________________
67         |       ARDUINO       |
68
69    5.  The on board LED (MEGA 2560) is  utilised for testing to keep circuit design to a minimum.
70        If not using  the onboard LED then configure one in the traditional way using a 230ohm resister  (for
71        a red LED) and a red LED on a breadboard, or otherwise.
72*/
73//  define type of switch circuit and associated LOW and HIGH variables:
74//    -  circuit C1, INPUT with switch resister           -> switch_high = HIGH, switch_low  = LOW
75//    - circuit C2, INPUT_PULLUP with no switch resister -> switch_high  = LOW,  switch_low = HIGH
76
77#define circuit_C1    INPUT
78#define circuit_C2    INPUT_PULLUP
79
80#define circuit_type  circuit_C1   // circuit type configured,  see circuit design specs
81
82int     switch_high, switch_low;
83
84#define  button_switch        2     // digital pin connected to button switch
85#define  debounce            50     // number of milliseconds to wait for switch to settle  once pressed
86#define switched           true    // signifies switch has been  pressed
87
88#define LED        LED_BUILTIN     // digital pin connected to LED,  for testing of switch code only
89bool    led_status      =  LOW;    // start with  LED off, for testing of switch code only
90
91void setup() {
92  // define the  switch circuit type 
93  pinMode(button_switch, circuit_type); // circuit_type  == INPUT or INPUT_PULLUP
94  // establish meanings for switch on/off depending  on circuit_type
95  if (circuit_type == INPUT_PULLUP) {
96    // switch is NOT  configured with a pull down switch resister
97    switch_high = LOW;  // switch  pin goes LOW when switch pressed, ie on
98    switch_low  = HIGH; // switch pin  goes HIGH when switch released, ie off
99  } else {
100    // circuit_type == INPUT,  so switch IS configured with a pull down switch resister
101    switch_high = HIGH;  // switch pin goes HIGH when switch pressed, ie on
102    switch_low  = LOW;  //  switch pin goes LOW when switch released, ie off
103  }
104  // set LED pin for  output, for testing purposes only
105  pinMode(LED, OUTPUT);
106}
107//
108//  Button  switch reading, method 1
109//  This version of switch reading examines switch once  each time the function is called.
110//  This allows the code section from which  it is called to continue without waiting
111//  for the switch press cycle to complete  once switching is initiated.
112//  Only drawback, of course, is that the design  of the calling code must ensure that the
113//  switch is regularly tested to catch  a change in switch status.
114//
115bool read_switch_method_1() {
116  int             switch_pin_reading;
117  // static variables because we need to retain old values between function calls
118  static bool     switch_pending = false;
119  static long int elapse_timer;
120  switch_pin_reading = digitalRead(button_switch);
121  if (switch_pin_reading ==  switch_high) {
122    // switch is pressed, so start/restart debounce process
123    switch_pending = true;
124    elapse_timer = millis();    // start elapse timing
125    return !switched;           // now waiting for debounce to conclude
126  }
127  if (switch_pending && switch_pin_reading == switch_low) {
128    // switch was  pressed, now released, so check if debounce time elapsed
129    if (millis() - elapse_timer  > debounce) {
130      // dounce time elapsed, so switch press cycle complete
131      switch_pending = false;
132      return switched;
133    }
134  }
135  return  !switched;
136}
137
138//
139//  Button switch reading, method 2.
140//  This version  of switch reading will wait for a switch cycle to complete once it
141//  initiated,  before control is returned to the calling code.
142//  That is, the calling code  will be held up once the switch is pressed and until
143//  the debounce period  has elapsed.
144//
145bool read_switch_method_2() {
146  int      switch_pin_reading;
147  bool     switch_status;
148  long int elapse_timer;
149  switch_status = !switched;                            // assume switch not pressed
150  //  read the given  switch_pin, if pressed will be HIGH, if not pressed will be LOW
151  switch_pin_reading  = digitalRead(button_switch);
152  do {
153    if (switch_pin_reading  == switch_high)  {
154      // switch has been pressed, now debounce
155      switch_status = switched;                         // flag that switch was pressed
156      elapse_timer  =  millis();
157      do {} while (millis() - elapse_timer < debounce); // wait for  debounce period to lapse
158      switch_pin_reading = digitalRead(button_switch);  // see if switch is still being pressed
159    }
160  } while (switch_pin_reading  == switch_high);          // keep debouncing until switch no longer pressed
161  return switch_status;                                 // result is either 'switched'  or '!switched'
162}
163
164void loop() {
165  do {
166    if (read_switch_method_1()  == switched) {
167      led_status = HIGH - led_status;                   // flip  between HIGH and LOW
168      digitalWrite(LED, led_status);
169    }
170  } while  (true);
171}
172