Implemented the enhanced keypad changes and README.adoc (#3)

* Implemented the enhanced keypad changes

* Create README.adoc file (#4)

* Change wiring to make it easier

* Include first version of README.adoc

* Fix image syntax

* Fix number of columns in table

* Remove 'Installation' section

* Put terminal output as a note

* Remove NOTE

* Use plain text Code Block instead

* Fix URLs to LICENSE and CONTRIBUTING

* Another attempt of fixing contributing and licensing

* Put links in line

Author: jcarranz97

gpio/keypad/README.adoc

@@ -0,0 +1,120 @@
+= Keypad Example for Raspberry Pi Pico
+
+This document provides details about the 4x4 keypad example included in the larger repository of examples for Raspberry Pi Pico. This example demonstrates how to interface a 4x4 matrix keypad with the Pico and includes both simple and enhanced key detection modes.
+
+== Introduction
+
+This example shows how to use a 4x4 matrix keypad with the Raspberry Pi Pico. It has been enhanced to support detecting multiple key presses simultaneously, alongside the original single key press functionality.
+
+== Features
+
+* Simple key detection (one key press at a time)
+* Enhanced key detection (multiple keys pressed simultaneously)
+* Configurable maximum number of simultaneous key presses
+* Mode switching via macro definition
+
+== Hardware Requirements
+
+* Raspberry Pi Pico
+* 4x4 matrix keypad
+* Connecting wires
+
+== Wiring Instructions
+
+Follow these wiring instructions to connect the 4x4 matrix keypad to the Raspberry Pi Pico:
+
+[image2]
+image::pico_keypad_connection.png[Keypad Connection Diagram]
+
+=== Wiring Table
+
+The following table shows the GPIO pins used for the rows and columns of the keypad:
+
+[width="50%",cols="1,1,1",options="header"]
+|===
+| Keypad Row/Column | GPIO Pin | Pin Number
+
+| Row 0 | GP9  | 9
+| Row 1 | GP8  | 8
+| Row 2 | GP7  | 7
+| Row 3 | GP6  | 6
+
+| Column 0 | GP5  | 5
+| Column 1 | GP4  | 4
+| Column 2 | GP2  | 2
+| Column 3 | GP1  | 1
+|===
+
+Ensure that the keypad rows and columns are connected to the GPIO pins on the Pico as indicated in the table.
+
+== Usage
+
+This example can be compiled and run to interact with the keypad. 
+
+=== Simple Mode
+
+In simple mode, the `get_keypad_value` function returns a single character corresponding to the pressed key. If no key is pressed, it returns a constant value indicating no key press.
+
+[source,c]
+----
+char get_keypad_value();
+----
+
+=== Enhanced Mode
+
+In enhanced mode, the `get_keypad_result` function returns a `KeypadResult` structure containing the count of pressed keys and a list of those keys.
+
+[source,c]
+----
+KeypadResult get_keypad_result();
+----
+
+The `KeypadResult` structure is defined as follows:
+
+[source,c]
+----
+typedef struct {
+    int count;                   // Number of pressed keys
+    char keys[MAX_MULTI_KEYS];   // Pressed keys
+} KeypadResult;
+----
+
+== Example Output
+
+=== Simple Mode
+
+If a key is pressed, the output will be:
+
+[source, plain]
+----
+Key 'A' pressed
+----
+
+If no key is pressed, the output will be:
+
+[source, plain]
+----
+No key pressed
+----
+
+=== Enhanced Mode
+
+If multiple keys are pressed, the output will be:
+
+[source, plain]
+----
+Bang!!! '2' key(s) are pressed. Keys: A, B
+----
+
+If no keys are pressed, the output will be:
+
+[source, plain]
+----
+No key pressed
+----
+
+== Additional Information
+
+For contributing to the repository, refer to the link:../../CONTRIBUTING.md[CONTRIBUTING.md] file.
+
+For licensing information, see the link:../../LICENSE.TXT[LICENSE.TXT] file.

gpio/keypad/keypad.c

@@ -15,20 +15,41 @@
                                      // to determine if no key is pressed.
 #define READ_MS_DELAY            10  // Delay between read to avoid noise
 
+// Enable enhanced mode to allow reading multiple keys simultaneously.
+#define ENHANCED_KEYPAD
+
+
+#ifdef ENHANCED_KEYPAD
+/*
+ * When using the Enhanced Keypad mode, the get_keypad_value function
+ * returns a KeypadResult structure instead of a single character.
+ *
+ * KeypadResult includes:
+ * - count: The number of keys pressed (up to MAX_MULTI_KEYS).
+ * - keys: An array containing the pressed keys (up to MAX_MULTI_KEYS).
+ */
+#define MAX_MULTI_KEYS 6  // Maximum number of keys that can be pressed simultaneously.
+
+typedef struct {
+    int count;                  // Number of keys pressed.
+    char keys[MAX_MULTI_KEYS];  // Array of pressed keys.
+} KeypadResult;
+#endif  // ENHANCED_KEYPAD
+
 
 const uint8_t keypad_rows_pins[KEYPAD_NUM_ROWS] = {
-    10,
-    11, 
-    12,
-    13,
+    9,      // GP9
+    8,      // GP8
+    7,      // GP7
+    6,      // GP6
 };
 
 
 const uint8_t keypad_columns_pins[KEYPAD_NUM_COLUMNS] = {
-    18,  // GP18
-    19,  // GP19
-    20,  // GP20
-    21,  // GP21
+    5,      // GP5
+    4,      // GP4
+    3,      // GP2
+    2,      // GP1
 };
 
 
@@ -58,39 +79,100 @@ void pico_keypad_init(void) {
 }
 
 
-char get_keypad_value(void) {
+#ifdef ENHANCED_KEYPAD
+KeypadResult get_keypad_result(void) {
+    KeypadResult result;        // Define the result structure.
+    result.count = 0;           // Initialize count to 0.
+
+    // Iterate over key and rows to identify which key(s) are pressed.
+    for (int row=0; row < KEYPAD_NUM_ROWS; row++) {
+        gpio_put(keypad_rows_pins[row], 1);
+        for (int column=0; column < KEYPAD_NUM_COLUMNS; column++) {
+            sleep_ms(READ_MS_DELAY);
+            if(gpio_get(keypad_columns_pins[column])) {
+                // If the column pin is HIGH, a key is pressed.
+                // Save the key in the KeypadResult structure and increase
+                // count.
+                result.keys[result.count] = keypad_keys[row][column];
+                result.count++;
+            }
+        }
+        gpio_put(keypad_rows_pins[row], 0);
+    }
+
+    // Return the structure containing all pressed keys.
+    return result;
+}
+#else
+char get_keypad_result(void) {
     // Iterate over key and rows to identify which key is pressed.
-    // When iterating rows, the GPIO_OUT associted to the row needs to be set
+    // When iterating rows, the GPIO_OUT associated to the row needs to be set
     // to HIGH, and then iterate the columns to determine the GPIO_IN.
     for (int row=0; row < KEYPAD_NUM_ROWS; row++) {
         gpio_put(keypad_rows_pins[row], 1);
         for (int column=0; column < KEYPAD_NUM_COLUMNS; column++) {
             sleep_ms(READ_MS_DELAY);
             if(gpio_get(keypad_columns_pins[column])) {
-                // If the pin is HIGH, this means this is a matching row and
-                // column, so we put the row pin to LOW and return the pressed
-                // key by using the bidimensional array keypad_keys.
+                // If the column pin is HIGH, a key is pressed.
+                // Put the row pin to low and return the pressed key.
                 gpio_put(keypad_rows_pins[row], 0);
                 return keypad_keys[row][column];
             }
         }
         gpio_put(keypad_rows_pins[row], 0);
     }
+
+    // Return a constant indicating no key was pressed
     return NO_KEY_PRESSED;
 }
+#endif  //ENHANCED_KEYPAD
 
 
 int main() {
     stdio_init_all();
     pico_keypad_init();
     while (true) {
-        char key = get_keypad_value();
+        #ifdef ENHANCED_KEYPAD
+        // Call the enhanced function to get the result structure
+        // containing the number of keys pressed and the keys themselves.
+        KeypadResult result = get_keypad_result();
+
+        // Check if no keys are pressed.
+        if (result.count == 0) {
+            // Inform the user that no keys are pressed.
+            printf("No key pressed\n");
+        }
+        else{
+            // If one or more keys are pressed, print the number of pressed keys.
+            printf("Bang!!! '%d' key(s) are pressed. Keys: ", result.count);
+
+            // Iterate through the pressed keys and print them.
+            for (int i = 0; i < result.count; i++) {
+                printf("%c", result.keys[i]);
+
+                //  If it's not the last key, print a comma separator.
+                if (i != (result.count - 1)) {
+                    printf(", ");
+                } else {
+                    // If it's the last key, move to the next line.
+                    printf("\n");
+                }
+            }
+        }
+        #else
+        // Call the simple function to get a single pressed key.
+        char key = get_keypad_result();
+
+        // Check if no key is pressed.
         if (key == NO_KEY_PRESSED) {
+            // Inform the user that no keys are pressed.
             printf("No key pressed\n");
         }
         else{
+            // If a key is pressed, print the key.
             printf("Key '%c' pressed\n", key);
         }
+        #endif
         sleep_ms(500);
     }
 }