MatrixKeypad.h

#include "Arduino.h"

#define TBUF_LEN                8
#define INPUT_EVENTS_FIFO_SIZE  32
#define MATRIX_ROWS_MAX         8

typedef enum {
    MATRIX_SWITCH_ON_OFF = 0,/* events for ON and OFF (8XX and 4XX)*/
    MATRIX_SWITCH_ON,        /* events for ON only (1XX)*/
    MATRIX_SWITCH_ON_DBLFUNC /* events for ON and long pressing >1.5 sec (1XX and (1XX + 0x80))*/
} matrix_node_type;

typedef struct {
    char id;
    matrix_node_type mode;
    char debounce;
    short long_pressing_time;
    char counter;
    char signal;
    short long_pressing_timer;
} KEY_SETTINGS;

class MatrixKeypad
{
public:
    typedef struct {
        volatile int push_indx;
        volatile int pop_indx;
        uint16_t buff[INPUT_EVENTS_FIFO_SIZE];
    } INPUT_EVENTS_FIFO;

    INPUT_EVENTS_FIFO fifo;

    typedef struct {
       uint8_t* port; 
       uint8_t mask;
    } LINES_DESCRIPTION;
   
    MatrixKeypad(KEY_SETTINGS *settings_table, int keys_number, uint8_t *rows_pins, uint8_t rows_number, uint8_t *columns_pins, uint8_t columns_number)
    {
        table = settings_table;
        keys_max = keys_number;
        fifo.push_indx = 0;
        fifo.pop_indx = 0;
        rows_num = rows_number;
        columns_num = columns_number;

        // Initialize rows as inputs with internal pull-ups
        for(int i = 0; i < rows_num; i++) {
            pinMode(rows_pins[i], INPUT_PULLUP);
            rows[i].port = portInputRegister(digitalPinToPort(rows_pins[i]));
            rows[i].mask = digitalPinToBitMask(rows_pins[i]);
        }

        // Initialize columns as outputs, set them default to HIGH
        for(int i = 0; i < columns_num; i++) {
            pinMode(columns_pins[i], OUTPUT);
            columns[i].port = portOutputRegister(digitalPinToPort(columns_pins[i]));
            columns[i].mask = digitalPinToBitMask(columns_pins[i]);
            *columns[i].port |= columns[i].mask; // Idle state for active-low scanning is HIGH
            keys_raw_state[i] = 0x00;
        }
        scan_index = 0;
    }

    ~MatrixKeypad() {}

    // SAFE TO CALL INSIDE HIGH-FREQUENCY INTERRUPTS (Takes ~1 microsecond)
    // Progresses the active-low hardware scanning matrix by exactly one column
    void scan_step(void)
    {
        uint8_t result = 0;
        uint8_t mask = 1;
        
        // 1. Read all rows for the CURRENT active column
        for(int i = 0; i < rows_num; i++) {  
            if ((*rows[i].port & rows[i].mask) == 0) {
                result |= mask;
            }
            mask <<= 1;
        }
        keys_raw_state[scan_index] = result;
        
        // 2. Deactivate the current column (return it to HIGH)
        *columns[scan_index].port |= columns[scan_index].mask;
        
        // 3. Move onto the next column index
        scan_index++;
        if (scan_index >= columns_num) scan_index = 0;
        
        // 4. Activate the next column (pull it to LOW)
        *columns[scan_index].port &= ~columns[scan_index].mask;
    }

    // CALL ONLY INSIDE THE MAIN loop() (Asynchronous debouncing logic)
    // Processes state machines, edge detection, and pushes new events to FIFO
    void periodic(void)
    {
        uint16_t utmp16;

        for(int i = 0; i < keys_max; i++)
        {
            // Process critical delayed timers for rotary/delayed switches
            if(table[i].long_pressing_timer) 
            {
                if(--table[i].long_pressing_timer == 0) 
                {
                  if(table[i].mode == MATRIX_SWITCH_ON_DBLFUNC)
                  {
                    utmp16 = 0x180 | table[i].id;
                    fifo_push(utmp16);
                  }  
                }
            }

            uint8_t b = get_raw_key_state(i);
            if(b) // Key is physically pressed
            {
                if(table[i].counter < table[i].debounce) 
                {
                    if(++(table[i].counter) >= table[i].debounce) {
                        if(table[i].signal == 0) {
                            // Rising edge detected (__0__/--1--)
                            if(table[i].long_pressing_timer) {
                                table[i].long_pressing_timer = table[i].long_pressing_time;
                            }

                            if(table[i].mode == MATRIX_SWITCH_ON) 
                            {
                               utmp16 = 0x100 | table[i].id; // Triggers {1XX}
                               fifo_push(utmp16);
                            } 
                            else if(table[i].mode == MATRIX_SWITCH_ON_OFF)
                            {
                               utmp16 = 0x800 | table[i].id; // Triggers {8XX}
                               fifo_push(utmp16);
                            }
                            
                        }
                        table[i].signal = 1;
                    }
                }
            }
            else // Key is physically released
            {
                if(table[i].counter > 0) {
                    if(--(table[i].counter) <= 0) {
                        if(table[i].signal) 
                        {
                            // Falling edge detected (--1--\___0___)
                            if(table[i].mode == MATRIX_SWITCH_ON_OFF) 
                            {
                                utmp16 = 0x400 | table[i].id; // Triggers {4XX}
                                fifo_push(utmp16);
                            } 
                            else if((table[i].mode == MATRIX_SWITCH_ON_DBLFUNC) && table[i].long_pressing_timer) 
                            {
                                utmp16 = 0x100 | table[i].id; // Multi-position switch fallback
                                fifo_push(utmp16);
                            }
                            table[i].long_pressing_timer = 0;
                        }
                        table[i].signal = 0;
                    }
                }
            }
        }
    }

    int fifo_pop(uint16_t *data)
    {
        int indx;
        if (fifo.push_indx == fifo.pop_indx) return 0;
        indx = (fifo.pop_indx + 1) % INPUT_EVENTS_FIFO_SIZE;
        *data = fifo.buff[indx];
        fifo.pop_indx = indx;
        return 1;
    }

    // CALL ONLY INSIDE loop() (Streams queued matrix actions out to XPIOHUB)
    void manage_events(void) 
    {
      uint16_t event;
      if(fifo_pop(&event)) 
      {
        tbuf[0] = '{';
        tbuf[1] = nibble_to_hex((event >> 8) & 0x0F);
        tbuf[2] = nibble_to_hex((event >> 4) & 0x0F);
        tbuf[3] = nibble_to_hex(event & 0x0F);
        tbuf[4] = '}';
        Serial.write(tbuf, 5); // Emits the parsed operational frame instantly
      }
    }

private:
    uint8_t tbuf[TBUF_LEN];
    KEY_SETTINGS *table;
    int keys_max;
    LINES_DESCRIPTION rows[MATRIX_ROWS_MAX];
    LINES_DESCRIPTION columns[MATRIX_ROWS_MAX];
    uint8_t rows_num;
    uint8_t columns_num;
    uint8_t keys_raw_state[MATRIX_ROWS_MAX];
    uint8_t scan_index;

    // Resolves linear key index to its row/column bit position inside state buffer
    int get_raw_key_state(uint8_t index)
    {
        uint8_t row = index % rows_num;
        uint8_t col = index / rows_num;
        return ((keys_raw_state[col] & (1 << row)) != 0);
    } 

    int fifo_push(uint16_t data)
    {
        int indx = (fifo.push_indx + 1) % INPUT_EVENTS_FIFO_SIZE;
        if (indx == fifo.pop_indx) return 0; 
        fifo.buff[indx] = data;
        fifo.push_indx = indx;
        return 1;
    }

    int8_t nibble_to_hex(int8_t nibble)
    {
       static const char hex_table[] = "0123456789ABCDEF";
       return hex_table[nibble & 0x0F];
    }
};