# debounce

Generic debouncer.

Author | Alun Jones, Copyright © 2012..2012, all rights reserved.
Adapted-by |
Compiler | >=2.4o

Description

    This library provides a simple switch debounce function.
    .
    Quite often, when monitoring the state of a mechanical switch, it is
    necessary to take switch bounce into consideration. Rather than going
    straight from one stable state to another, it can take a significant
    period during which the contacts of the switch bounce together. If
    you don't take this into consideration then, rather than receiving
    a single pulse, your sofware can end up seeing a sequence of many
    pulses.
    .
    In an ideal world without switch bounce, perhaps you'd like to have the
    following:
    .
    forever loop
      if (pin_a0 == true) then
         -- do some stuff
      end if
      -- do some other stuff
    end loop
    .
    This library tries to make it possible to do this while handling
    switch bounce for you. At its simplest, you could do the following:
    .
    var word state = debounce_init(200)
    forever loop
      if (debounce(pin_a0, state) == 1) then
         -- do some stuff
      end if
      -- do some other stuff
    end loop
    .
    In the example above, the lowest bit returned by the debounce function
    will only flip after pin_a0's state has been polled in a stable state
    200 times in a row. Choosing the threshold (200 in this case) is probably
    matter of trial and error - it'll depend on the characteristics of the
    switch you're using and how quickly your polling loop runs.
    .
    You must allocate a word to hold the bounce state, threshold and counter,
    and initialise it using debounce_init (as above). The maximum threshold
    value you can specify is 255, and the value is only stored with a
    resolution of 6 bits. All threshold values are ORed with 0b11, so
    specifying a threshold value of 9, for example, will give an actual
    threshold value of 11. This may sound a bit odd, but it's so the bottom 2
    bits of the status word can be stolen and used for storing internal
    state. The actual counter uses the full 8 bits.
    .
    The debounce function also returns a second bit, which is set only when
    the returned state has just changed. This is useful if you want something
    to happen just once when a button is pressed, for example.
    .
      if (debounce(pin_a0, state) == 3) then
          -- do some stuff
      end if
    .
    The returned values are as follows then:
    .
        0b00 =  0   - Input is stable at 0 and has not just changed
        0b01 =  1   - Input is stable at 1 and has not just changed
        0b10 =  2   - Input is stable at 0 and has just changed from 1
        0b11 =  3   - Input it stable at 1 and has just changed from 0
    .
    Here is a full list of all functions:
    .
    function debounce_init(byte in threshold) return word
    .
       This is used to initialise a state variable ready for use.
       threshold is the number of calls after which the debounce
       function should consider a new state stable.
    .
    function debounce(bit in polled, word in out state) return byte
    .
       This is the main function - I'm not going to go into detail here as
       it's described above.
    .
    function debounce_fast(bit in polled, word in out state) return byte
    .
       You may have noticed that debounce() imposes a lag while it decides
       whether the new state is stable. If it's critical that you respond
       immediately to a state change, you can use debounce_fast instead. This
       one is used in exactly the same way as debounce(), but rather than
       waiting for a stable state, it assumes that a changed state is going
       to stabilise to that changed state. So it flips its return value
       immediately on detecting a state change. Then, it embargoes further
       state changes until the threshold period has passed.
    .
       The downside of this is that if your input data sometimes receives
       spurious short pulses that you'd like to ignore, debounce_fast will
       act on them, turning them into longer pulses.
    .
    function debounce_state(word in state) return byte
    .
       This returns the last value that was returned by debounce for this
       state variable.
    .
    function debounce_just_changed(word in state) return bit
    .
       This returns the last "just changed" flag that was returned by
       debounce for this state variable.
    .
    function debounce_stable_state(word in state) return bit
    .
       This returns the last stable state that was returned by
       debounce for this state variable.
    .
    function debounce_threshold(word in state) return byte is
    .
       This returns the threshold value that's in use in this
       state variable.

Dependencies

No dependency found

## Summary

### Global variables/contants

### Procedures

### Functions

- `debounce_just_changed(word in state) return bit`
- `debounce_threshold(word in state) return byte`
- `debounce(bit in polled, word in out state) return byte`
- `debounce_fast(bit in polled, word in out state) return byte`
- `debounce_init(byte in threshold) return word`
- `debounce_stable_state(word in state) return bit`
- `debounce_state(word in state) return byte`

## API details

### Global variables/contants

### Procedures

### Functions

- `debounce_just_changed(word in state) return bit`

      Return the "just changed" flag.

- `debounce_threshold(word in state) return byte`

      Return the threshold for the state variable.

- `debounce(bit in polled, word in out state) return byte`

      The real meat of the system...

- `debounce_fast(bit in polled, word in out state) return byte`

  No documentation found

- `debounce_init(byte in threshold) return word`

      Initialise. Set the threshold and the counter.

- `debounce_stable_state(word in state) return bit`

      Return the current stable state.

- `debounce_state(word in state) return byte`

      Return the same as debounce() returns.

## Related samples

Here are the list of samples which use this library:

16f73 | 16f73_debounce.jal
16f877 | 16f877_debounce.jal
16f877a | 16f877a_debounce.jal
16f88 | 16f88_debounce.jal
18f14k50 | 18f14k50_pll.jal
18f2450 | 18f2450_debounce.jal
18f2520 | 18f2520_debounce.jal
18f2550 | 18f2550_debounce.jal
18f2620 | 18f2620_debounce.jal
18f452 | 18f452_debounce.jal
18f4550 | 18f4550_debounce.jal
18f4620 | 18f4620_debounce.jal
18f67j50 | 18f67j50_debounce.jal