/*
Doc: prototype-buttons.dts.txt
Changed: prior 2025sep21

This is an example for prototyping buttons connected
to gpio pins.
Seek "Beginning" for skipping the introduction.
*/

/*
More info about device tree source (DTS) documents:
 /raspberrypi.org/documentation/
  configuration/device-tree.md

That says a node is described sort of like a path,
f.e. the single "/" is the root node.
Curly braces have the definition for a node: {};
A semicolon is required after the curly brace pair.
*/

/*
Compile and install instructions.

The name of the DTS document is of no importance.
A different name for the DTBO (device tree blob overlay)
can be declared when compiled.

Compile with the "dtc" command:
dtc \
-I dts \
-O dtb \
-o  /boot/overlays/prototype-buttons.dtbo \
prototype-buttons.dts

Or, output it to a different location, then copy it to:
  /boot/overlays/

Add it to /boot/config.txt:
  dtoverlay=prototype-buttons
Or whatever name was chosen for the output when compiled.
*/

/*
The documentation referenced later is also
consolidated here, at the top.

Compatible with feature: gpio-keys.
  /github.com/torvalds/linux/tree/master/
   Documentation/devicetree/
   bindings/input/gpio-keys.yaml
(Find that file in the linux source
 and add more info about this.)

The input event codes.
  /github.com/torvalds/linux/tree/master/
   include/uapi/linux/input-event-codes.h
Or might be available locally:
  /usr/include/linux/input-event-codes.h

Assignment for the gpio pin.
  /github.com/torvalds/linux/tree/master/
  Documentation/devicetree/
  bindings/gpio/gpio.txt
*/


/*
Explanation and general instructions.

Makeup an arbitrary name for each gpio pin,
and assign an input event code to that gpio pin.

There typically is always a flow, so activity is detected
when the voltage level changes between high and low.
A pin usually without power (starts low) is considered
activated (triggered) when it receives more: active-high.
A pin usually receiving power (starts high) is considered
activated (triggered) when it loses it: active-low.

"0" means start low, therefore the pin will be active-high,
f.e. activated when button leads power to the pin.
"1" means start high, therefore the pin will be active-low,
f.e. activated when button leads power away from the pin.

For example, assign the input event code for KEY_A
(which is 30) to GPIO 21 (pin 40), with the intent of
connecting it to a button that when pressed permits
power to the pin (active-high, because it starts low).
  another_button
  {
  label="This shows up in /sys/kernel/debug/gpio"
  linux,code=<30>;
  gpios=<&gpio 21 0>;
  };

Or, for pin 21 use "1" when it will be considered
activated when the power to the pin is diverted away by
the button: active-low, because it starts high.
  gpios=<&gpio 21 1>;


Consider a circuit when a 3V3 power source is used
(t.i. followed by a resistor regulating its flow rate to
the pin, f.e. a 10k ohm resistor means 0.33 mA, milliamps)
by forking the wire lead after the resistor
to the assigned pin and to a NO button leading to ground.
That means the pin loses power when pressing the button.

[3V3 power]
     |
[10k ohm resistor]
     |
     |---[button: SPST-NO]---[ground]
     |
[gpio pin]

To clarify, a "NO" button is "normally open" (t.i. off),
because it is a gap in the circuit before it is pressed.
A button that is normally closed (NC) completes the circuit,
because there is no gap before the button is pressed.
A single-pole single-throw (SPST) switch is for managing
one power source to one destination, like a light switch.

Flow rate to the pin decreases when the button is activated,
because the flow is led to ground.  The activity happening
at the pin is the lowering of the flow rate: active-low.
In other words: constantly triggered when no power.

123456789 123456789 123456789 123456789 123456789 123456789 
On the other hand, attach the button to the GPIO pin and
then the role is reversed, and with no need for ground.
The NO button prevents flow to the pin, therefore the pin
will be triggered only when it receives flow: active-high.
*/


/*
Beginning.
*/

/* Required header for DTS document. */
/dts-v1/;

/* Needed, but unsure about this... */
/plugin/;

/* The root node: "/". */
/
{
/*
Declaring device compatibility with only RPi 4,
because no other devices available for testing.
Use "brcm,bcm2835" for all other RPi, or both:
 compatible="brcm,bcm2711","brcm,bcm2835";
*/
compatible="brcm,bcm2711";

/*
Fragments are named with "fragment@" and start at zero.
Only one is needed for this.
*/
fragment@0
{
/*
Identify the intended node for this overlay.
Sometimes this is just "target", but unsure when.
*/
target-path="/";

/*
Declare the overlay.
Note the double-underscore before and after "overlay".
*/
__overlay__
{
/* "keypad:" is an arbitrary name for a label, like in C. */
keypad:
/* "breadboard_keys" is an arbitrary name for the device. */
breadboard_keys
{
/* Declaring compatibility with feature: gpio-keys. */
compatible="gpio-keys";
#address-cells=<1>;
#size-cells=<0>;
/*
Option for the typical "key-repeat" feature: autorepeat.
That is when keeping a button pressed.
*/
autorepeat;

/*
First button.
"button@11" is an arbitrary name for this button.
The "11" is just a reference to the GPIO pin number.
(GPIO 11 is pin 23.)
*/
button@11
{
label="breadboard KEY_A";
linux,code=<30>;
gpios=<&gpio 11 0>;
};// end: button@11
};// end: breadboard_keys
};// end: __overlay__
};// end: fragment@0
};// end: root node "/"