.. include:: defs.hrst

DigitalIn
=========

A digital (ie. binary) input unit that can be either "on" or "off".

The unit is assigned to a specific ``pin`` on the board.

The ``mode`` specifies the behavior of the component attached to the pin:

- in ``DIRECT`` mode (default) the unit will be "on" when the voltage on the pin is high (Vref, typically 5V)
- in ``INVERTED`` mode the unit will be "on" when the voltage on the pin is low (GND)
- in ``INTERNAL_PULLUP`` mode the internal `pullup resistor <https://en.wikipedia.org/wiki/Pull-up_resistor>`_ is used,
  simplifying usage of switches and buttons

Debouncing
----------

Some digital inputs such as `push-buttons <https://en.wikipedia.org/wiki/Push-button>`_ often
generate spurious open/close transitions when pressed, due to mechanical and physical issues:
these transitions called "bouncing" may be read as multiple presses in a very short time, fooling
the program.

The DigitalIn object features debouncing capabilities which can prevent this kind of problems. Debouncing
can be achieved using different modes: stable (default) (``DEBOUNCE_STABLE``), lock-out (``DEBOUNCE_LOCK_OUT``)
and prompt-detect (``DEBOUNCE_PROMPT_DETECT``). For more information please refer to the documentation
of the `Bounce2 Arduino Library <https://github.com/thomasfredericks/Bounce2>`_.

Events
------

.. list-table::
   :header-rows: 1
   :widths: 50 25 25

   * - When
     - Trigger
     - Callback
   * - Digital value toggles (on/off)
     - ``changed()``
     - ``onChange(c)``
   * - Digital value goes from on to off
     - ``fell()``
     - ``onFall(c)``
   * - Digital value goes from off to on
     - ``rose()``
     - ``onRise(c)``

|Example|
---------

Turns on and off a light emitting diode (LED) connected to digital pin 13, when
pressing a pushbutton attached to digital pin 2. Pushbutton should be wired by connecting
one side to pin 2 and the other to ground.

.. code-block:: c++

   #include <Plaquette.h>

   DigitalIn button(2, INTERNAL_PULLUP);

   DigitalOut led(13);

   void begin() {
     button.debounce(); // debounce button
   }

   void step() {
     // Toggle the LED each time the button is pressed.
     if (button.rose())
       led.toggle();
   }


|Reference|
-----------

.. doxygenclass:: DigitalIn
   :project: Plaquette
   :members:

|SeeAlso|
---------
- :doc:`AnalogIn`
- :doc:`DigitalOut`
- `Bounce2 Arduino Library <https://github.com/thomasfredericks/Bounce2>`_
