unit_Tab5Keyboard.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_KEYBOARD_UNIT_TAB5_KEYBOARD_HPP
#define M5_UNIT_KEYBOARD_UNIT_TAB5_KEYBOARD_HPP
 
#include "unit_Keyboard.hpp"
 
// Forward declaration for test access to protected members
class TestTab5Keyboard;
 
#include <array>
#include <bitset>
#include <memory>  // for std::unique_ptr
#include <string>
 
#include "../utility/bitwise_state.hpp"
 
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP_PLATFORM)
#include "driver/gpio.h"
#endif
 
namespace m5 {
namespace unit {
 
namespace tab5_keyboard {
 
namespace command {
constexpr uint8_t REG_INT_CFG{0x00};   // INT_CFG   (R/W) Interrupt enable: [2]=char [1]=HID [0]=normal, default 0x07
constexpr uint8_t REG_INT_STAT{0x01};  // INT_STAT  (R/W) Interrupt status: same bit layout; write 0 to clear
constexpr uint8_t REG_EVENT_NUM{
    0x02};  // EVENT_NUM (R/W) Queue length 0-32; auto-decrements on read; write 0 clears queue + INT
constexpr uint8_t REG_BRIGHTNESS{0x03};     // Brightness (R/W) RGB global brightness 0-100, default 20
constexpr uint8_t REG_MODE_KEYBOARD{0x10};  // Keyboard mode (R/W) 0=Normal 1=HID 2=Character, default 0
constexpr uint8_t REG_MODE_RGB{0x11};       // RGB mode      (R/W) 0=Bind  1=Custom,           default 0
constexpr uint8_t REG_KEY_EVENT{0x20};      // KEY_EVENT         (R) Normal mode: 1 byte
constexpr uint8_t REG_HID_EVENT{0x30};      // HID_EVENT         (R) HID mode: Modifier(0x30) + Key_code(0x31), 2 bytes
constexpr uint8_t REG_CHAR_EVENT_LENGTH{0x40};  // CHAR_EVENT_LENGTH (R) Char mode: queue-head string length
constexpr uint8_t REG_CHAR_EVENT{0x50};  // CHAR_EVENT        (R) Char mode: Modifier(0x50) + char0(0x51)..char8(0x59)
constexpr uint8_t REG_RGB1_B{0x60};      // RGB1 Blue  component (R/W) 0-255, default 0
constexpr uint8_t REG_RGB1_G{0x61};      // RGB1 Green component (R/W) 0-255, default 0
constexpr uint8_t REG_RGB1_R{0x62};      // RGB1 Red   component (R/W) 0-255, default 0
constexpr uint8_t REG_RGB2_B{0x64};      // RGB2 Blue  component (R/W) 0-255, default 0
constexpr uint8_t REG_RGB2_G{0x65};      // RGB2 Green component (R/W) 0-255, default 0
constexpr uint8_t REG_RGB2_R{0x66};      // RGB2 Red   component (R/W) 0-255, default 0
constexpr uint8_t REG_FIRMWARE_VERSION{0xFE};  // Firmware Version (R) Software version byte
constexpr uint8_t REG_I2C_ADDRESS{0xFF};       // I2C Address (R/W) 0x08-0x77, default 0x6D
}  // namespace command
 
constexpr uint8_t KEY_EVENT_EMPTY{0xFF};
 
constexpr uint8_t CHAR_EVENT_MAX_CHARS{9};
 
constexpr uint32_t I2C_ADDRESS_WRITE_DELAY_MS{50};
 
constexpr uint8_t RGB_LED_COUNT{2};
 
constexpr uint8_t MODIFIER_KEY_ROW_SYM{3};   
constexpr uint8_t MODIFIER_KEY_COL_SYM{0};   
constexpr uint8_t MODIFIER_KEY_ROW_AA{3};    
constexpr uint8_t MODIFIER_KEY_COL_AA{1};    
constexpr uint8_t MODIFIER_KEY_ROW_CTRL{4};  
constexpr uint8_t MODIFIER_KEY_COL_CTRL{0};  
constexpr uint8_t MODIFIER_KEY_ROW_ALT{4};   
constexpr uint8_t MODIFIER_KEY_COL_ALT{1};   
 
inline bool isModifierKey(const uint8_t row, const uint8_t col)
{
    return (row == MODIFIER_KEY_ROW_SYM && col == MODIFIER_KEY_COL_SYM) ||
           (row == MODIFIER_KEY_ROW_AA && col == MODIFIER_KEY_COL_AA) ||
           (row == MODIFIER_KEY_ROW_CTRL && col == MODIFIER_KEY_COL_CTRL) ||
           (row == MODIFIER_KEY_ROW_ALT && col == MODIFIER_KEY_COL_ALT);
}
 
constexpr uint8_t KEY_COUNT{70};
 
constexpr uint8_t KEY_COL_COUNT{14};
 
using key_status_bits_t = std::bitset<KEY_COUNT>;
 
inline uint8_t toKeyIndex(const uint8_t row, const uint8_t col)
{
    return static_cast<uint8_t>(row * KEY_COL_COUNT + col);
}
 
constexpr uint8_t KIDX_SYM  = MODIFIER_KEY_ROW_SYM * KEY_COL_COUNT + MODIFIER_KEY_COL_SYM;    
constexpr uint8_t KIDX_AA   = MODIFIER_KEY_ROW_AA * KEY_COL_COUNT + MODIFIER_KEY_COL_AA;      
constexpr uint8_t KIDX_CTRL = MODIFIER_KEY_ROW_CTRL * KEY_COL_COUNT + MODIFIER_KEY_COL_CTRL;  
constexpr uint8_t KIDX_ALT  = MODIFIER_KEY_ROW_ALT * KEY_COL_COUNT + MODIFIER_KEY_COL_ALT;    
 
struct HidMapping {
    uint8_t keycode;   
    uint8_t modifier;  
};
 
HidMapping keyMatrixToHidBase(const uint8_t row, const uint8_t col);
 
HidMapping keyMatrixToHidSym(const uint8_t row, const uint8_t col);
 
enum class EventType : uint8_t {
    None      = 0,  
    Key       = 1,  
    Hid       = 2,  
    Character = 3,  
};
 
struct Event {
    EventType type{EventType::None};
    uint8_t modifier{};  
    bool repeat{false};
 
    union {
        struct {
            uint8_t length;                        
            char chars[CHAR_EVENT_MAX_CHARS + 1];  
        } chr{};                                   
        struct {
            uint8_t row;
            uint8_t col;
            bool pressed;
        } key;  
        struct {
            uint8_t keycode;
        } hid;  
    };
 
    inline bool isCtrl() const
    {
        return (modifier & 0x11U) != 0U;
    }
    inline bool isShift() const
    {
        return (modifier & 0x22U) != 0U;
    }
    inline bool isAlt() const
    {
        return (modifier & 0x44U) != 0U;
    }
};
 
constexpr uint32_t DEFAULT_STORED_SIZE{16};
 
enum class Mode : uint8_t {
    Normal    = 0,  
    HID       = 1,  
    Character = 2,  
};
 
enum class RgbMode : uint8_t {
    Bind = 0,
    Custom = 1,
};
 
namespace command {
constexpr uint8_t CMD_INT_CFG{REG_INT_CFG};
constexpr uint8_t CMD_INT_STAT{REG_INT_STAT};
constexpr uint8_t CMD_EVENT_NUM{REG_EVENT_NUM};
constexpr uint8_t CMD_BRIGHTNESS{REG_BRIGHTNESS};
constexpr uint8_t CMD_MODE_KEYBOARD{REG_MODE_KEYBOARD};
constexpr uint8_t CMD_MODE_RGB{REG_MODE_RGB};
constexpr uint8_t CMD_KEY_EVENT{REG_KEY_EVENT};
constexpr uint8_t CMD_HID_EVENT{REG_HID_EVENT};
constexpr uint8_t CMD_CHAR_EVENT_LENGTH{REG_CHAR_EVENT_LENGTH};
constexpr uint8_t CMD_CHAR_EVENT{REG_CHAR_EVENT};
constexpr uint8_t CMD_RGB1_B{REG_RGB1_B};
constexpr uint8_t CMD_FIRMWARE_VERSION{REG_FIRMWARE_VERSION};
constexpr uint8_t CMD_I2C_ADDRESS{REG_I2C_ADDRESS};
}  // namespace command
 
}  // namespace tab5_keyboard
 
class UnitTab5Keyboard : public UnitKeyboard,
                         public PeriodicMeasurementAdapter<UnitTab5Keyboard, tab5_keyboard::Event> {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitTab5Keyboard, 0x6D);
    M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(UnitTab5Keyboard, tab5_keyboard::Event);
    friend class ::TestTab5Keyboard;
 
public:
    struct config_t {
        bool start_periodic{true};
        tab5_keyboard::Mode mode{tab5_keyboard::Mode::Normal};
        int8_t irq_pin{50};
        uint32_t interval_ms{50};
        bool software_repeat{false};
        uint32_t repeat_initial_ms{400};
        uint32_t repeat_rate_ms{80};
        uint32_t holding_threshold_ms{800};
    };
 
    explicit UnitTab5Keyboard(const uint8_t addr = DEFAULT_ADDRESS)
        : UnitKeyboard(addr),
          _data{new m5::container::CircularBuffer<tab5_keyboard::Event>(tab5_keyboard::DEFAULT_STORED_SIZE)}
    {
        auto ccfg        = component_config();
        ccfg.clock       = 400 * 1000U;  // Tab5 keyboard supports I2C Fast mode (400 kHz).
        ccfg.stored_size = tab5_keyboard::DEFAULT_STORED_SIZE;
        component_config(ccfg);
    }
    virtual ~UnitTab5Keyboard();
 
    inline config_t config() const
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
 
    bool writeInterruptEnable(const bool normal, const bool hid, const bool character);
 
    bool readInterruptEnable(bool& normal, bool& hid, bool& character);
 
    bool readInterruptStatus(bool& normal, bool& hid, bool& character);
 
    bool clearInterrupt();
 
    bool clearEventQueue();
 
 
    bool readFirmwareVersion(uint8_t& ver);
 
    bool readI2CAddress(uint8_t& addr);
 
    bool changeI2CAddress(const uint8_t i2c_address);
 
 
    bool readMode(tab5_keyboard::Mode& mode);
 
    bool writeMode(const tab5_keyboard::Mode mode);
 
    bool readRgbMode(tab5_keyboard::RgbMode& mode);
 
    bool writeRgbMode(const tab5_keyboard::RgbMode mode);
 
 
    bool readEventCount(uint8_t& count);
 
 
    bool writeRgb(const uint8_t idx, const uint8_t r, const uint8_t g, const uint8_t b);
 
    bool readRgb(const uint8_t idx, uint8_t& r, uint8_t& g, uint8_t& b);
 
 
    bool writeBrightness(const uint8_t pct);
 
    bool readBrightness(uint8_t& pct);
 
    inline uint8_t firmwareVersion() const
    {
        return _firmware_version;
    }
 
    inline const tab5_keyboard::key_status_bits_t& nowBits() const
    {
        return _state.now;
    }
    inline const tab5_keyboard::key_status_bits_t& previousBits() const
    {
        return _state.prev;
    }
    inline const tab5_keyboard::key_status_bits_t& pressedBits() const
    {
        return _state.pressed;
    }
    inline const tab5_keyboard::key_status_bits_t& releasedBits() const
    {
        return _state.released;
    }
    inline const tab5_keyboard::key_status_bits_t& holdingBits() const
    {
        return _state.holding;
    }
    inline const tab5_keyboard::key_status_bits_t& wasHoldBits() const
    {
        return _state.was_hold;
    }
    inline const tab5_keyboard::key_status_bits_t& repeatingBits() const
    {
        return _state.repeating;
    }
 
    inline bool isPressed() const
    {
        return bitwise_active() && _state.now.any();
    }
    inline bool wasPressed() const
    {
        return bitwise_active() && _state.pressed.any();
    }
    inline bool wasReleased() const
    {
        return bitwise_active() && _state.released.any();
    }
    inline bool isHolding() const
    {
        return bitwise_active() && _state.holding.any();
    }
    inline bool wasHold() const
    {
        return bitwise_active() && _state.was_hold.any();
    }
    inline bool isRepeating() const
    {
        return bitwise_active() && _state.repeating.any();
    }
 
 
    inline bool isPressed(const uint8_t kidx) const
    {
        return bitwise_active() && kidx < tab5_keyboard::KEY_COUNT && _state.now.test(kidx);
    }
    inline bool wasPressed(const uint8_t kidx) const
    {
        return bitwise_active() && kidx < tab5_keyboard::KEY_COUNT && _state.pressed.test(kidx);
    }
    inline bool wasReleased(const uint8_t kidx) const
    {
        return bitwise_active() && kidx < tab5_keyboard::KEY_COUNT && _state.released.test(kidx);
    }
    inline bool isHolding(const uint8_t kidx) const
    {
        return bitwise_active() && kidx < tab5_keyboard::KEY_COUNT && _state.holding.test(kidx);
    }
    inline bool wasHold(const uint8_t kidx) const
    {
        return bitwise_active() && kidx < tab5_keyboard::KEY_COUNT && _state.was_hold.test(kidx);
    }
    inline bool isRepeating(const uint8_t kidx) const
    {
        return bitwise_active() && kidx < tab5_keyboard::KEY_COUNT && _state.repeating.test(kidx);
    }
 
    inline bool isPressed(const uint8_t row, const uint8_t col) const
    {
        return isPressed(tab5_keyboard::toKeyIndex(row, col));
    }
    inline bool wasPressed(const uint8_t row, const uint8_t col) const
    {
        return wasPressed(tab5_keyboard::toKeyIndex(row, col));
    }
    inline bool wasReleased(const uint8_t row, const uint8_t col) const
    {
        return wasReleased(tab5_keyboard::toKeyIndex(row, col));
    }
    inline bool isHolding(const uint8_t row, const uint8_t col) const
    {
        return isHolding(tab5_keyboard::toKeyIndex(row, col));
    }
    inline bool wasHold(const uint8_t row, const uint8_t col) const
    {
        return wasHold(tab5_keyboard::toKeyIndex(row, col));
    }
    inline bool isRepeating(const uint8_t row, const uint8_t col) const
    {
        return isRepeating(tab5_keyboard::toKeyIndex(row, col));
    }
 
    inline bool isSym() const
    {
        return bitwise_active() && _state.now.test(tab5_keyboard::KIDX_SYM);
    }
    inline bool isAa() const
    {
        return bitwise_active() && _state.now.test(tab5_keyboard::KIDX_AA);
    }
    inline bool isCtrl() const
    {
        return bitwise_active() && _state.now.test(tab5_keyboard::KIDX_CTRL);
    }
    inline bool isAlt() const
    {
        return bitwise_active() && _state.now.test(tab5_keyboard::KIDX_ALT);
    }
 
 
    char keyMatrixToChar(const uint8_t row, const uint8_t col) const;
 
    char keyMatrixToChar(const uint8_t kidx) const;
 
protected:
 
    bool read_key_event(uint8_t& row, uint8_t& col, bool& pressed);
 
    bool read_hid_event(uint8_t& modifier, uint8_t& keycode);
 
    bool read_char_event(uint8_t& modifier, std::string& chars);
 
    bool read_event_for_mode(const tab5_keyboard::Mode mode, tab5_keyboard::Event& evt);
 
    // PeriodicMeasurementAdapter lifecycle (called via startPeriodicMeasurement/stopPeriodicMeasurement)
    bool start_periodic_measurement();
    bool stop_periodic_measurement();
 
    static void IRAM_ATTR isr_handler(void* arg);
 
    bool configure_irq_pin();
 
    void remove_irq_pin(const int8_t pin);
 
private:
    inline bool bitwise_active() const
    {
        return _mode == tab5_keyboard::Mode::Normal;
    }
 
    // update() internals (split out to keep the per-tick flow readable).
    bool ready_to_measure(const bool force);
    bool ready_to_measure_irq(const bool force);
    bool ready_to_measure_polling(const bool force);
    void drain_events(const tab5_keyboard::Mode mode);
    void process_normal_state();
 
    std::unique_ptr<m5::container::CircularBuffer<tab5_keyboard::Event>> _data{};
 
    config_t _cfg{};
    bool _irq_pin_configured{false};
    bool _int_enabled{false};
 
    // Cached active mode. Updated by begin()/writeMode()/readMode(); read by update()
    // to avoid an extra I2C transaction per cycle.
    tab5_keyboard::Mode _mode{tab5_keyboard::Mode::Normal};
 
    // Bitwise key state (Normal mode only)
    m5::unit::keyboard_bitwise::BitwiseState<tab5_keyboard::KEY_COUNT> _state;
 
    uint8_t _firmware_version{};
    volatile bool _irq_pending{false};
};
 
}  // namespace unit
}  // namespace m5
#endif