unit_Keyboard.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_KEYBOARD_UNIT_KEYBOARD_HPP
#define M5_UNIT_KEYBOARD_UNIT_KEYBOARD_HPP
 
#include <M5UnitComponent.hpp>
#include <vector>
 
#include "../utility/bitwise_state.hpp"
 
namespace m5 {
namespace unit {
 
namespace keyboard {
using key_index_t = uint8_t;  
 
using key_status_bits_t = uint64_t;  
// clang-format off
constexpr key_status_bits_t MODIFIER_SHIFT_BIT   {0x0100000000000000};  
constexpr key_status_bits_t MODIFIER_SYMBOL_BIT  {0x0200000000000000};  
constexpr key_status_bits_t MODIFIER_FUNCTION_BIT{0x0400000000000000};  
constexpr key_status_bits_t MODIFIER_ALT_BIT     {0x0800000000000000};  
constexpr key_status_bits_t MODIFIER_CONTROL_BIT {0x1000000000000000};  
constexpr key_status_bits_t MODIFIER_OPTION_BIT  {0x2000000000000000};  
constexpr key_status_bits_t MODIFIER_MASK{MODIFIER_SHIFT_BIT | MODIFIER_SYMBOL_BIT | MODIFIER_FUNCTION_BIT |
                                          MODIFIER_ALT_BIT | MODIFIER_CONTROL_BIT | MODIFIER_OPTION_BIT};
// clang-format on
 
constexpr inline key_status_bits_t modifier_bits(const key_status_bits_t kbs)
{
    return kbs & (MODIFIER_SHIFT_BIT | MODIFIER_SYMBOL_BIT | MODIFIER_FUNCTION_BIT | MODIFIER_ALT_BIT |
                  MODIFIER_CONTROL_BIT | MODIFIER_OPTION_BIT);
}
 
enum class Mode : uint8_t {
    Conventional,
    M5UnitUnified,
};
 
}  // namespace keyboard
 
class UnitKeyboard : public Component {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitKeyboard, 0x00);
 
public:
    // 0x5F:CardKB 0x08:FacesQWERTY
    explicit UnitKeyboard(const uint8_t addr = DEFAULT_ADDRESS) : Component(addr)
    {
        auto ccfg  = component_config();
        ccfg.clock = 100 * 1000U;
        component_config(ccfg);
    }
    virtual ~UnitKeyboard()
    {
    }
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
    inline virtual char getchar() const
    {
        return released();
    }
 
    inline virtual uint8_t released() const
    {
        return updated() ? _released_key : 0;
    }
 
private:
    uint8_t _released_key{};  // for old firmware
};
 
class UnitKeyboardBitwise : public UnitKeyboard, public PeriodicMeasurementAdapter<UnitKeyboardBitwise, uint8_t> {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitKeyboardBitwise, 0x00);
 
public:
    explicit UnitKeyboardBitwise(const uint8_t addr = DEFAULT_ADDRESS)
        : UnitKeyboard(addr), _data{new m5::container::CircularBuffer<uint8_t>(1)}
    {
    }
    virtual ~UnitKeyboardBitwise()
    {
    }
 
    virtual void update(const bool force = false) override;
 
 
    inline virtual char getchar() const override
    {
        return (_mode == keyboard::Mode::M5UnitUnified) ? pressed() : released();
    }
    inline uint8_t pressed() const
    {
        return !empty() ? oldest() : 0x00;
    }
    inline virtual uint8_t released() const override
    {
        return (_mode == keyboard::Mode::Conventional) ? UnitKeyboard::released() : 0x00;
    }
 
 
    inline bool startPeriodicMeasurement(const uint32_t interval)
    {
        return PeriodicMeasurementAdapter<UnitKeyboardBitwise, uint8_t>::startPeriodicMeasurement(interval);
    }
    inline bool startPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitKeyboardBitwise, uint8_t>::startPeriodicMeasurement();
    }
    inline bool stopPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitKeyboardBitwise, uint8_t>::stopPeriodicMeasurement();
    }
 
    inline keyboard::key_status_bits_t nowBits() const
    {
        return _state.now.to_ullong();
    }
    inline keyboard::key_status_bits_t previousBits() const
    {
        return _state.prev.to_ullong();
    }
    inline keyboard::key_status_bits_t pressedBits() const
    {
        return _state.pressed.to_ullong();
    }
    inline keyboard::key_status_bits_t releasedBits() const
    {
        return _state.released.to_ullong();
    }
    inline keyboard::key_status_bits_t holdingBits() const
    {
        return _state.holding.to_ullong();
    }
    inline keyboard::key_status_bits_t wasHoldBits() const
    {
        return _state.was_hold.to_ullong();
    }
    inline keyboard::key_status_bits_t repeatingBits() const
    {
        return _state.repeating.to_ullong();
    }
    inline keyboard::key_status_bits_t modifierBits() const
    {
        return modifier_bits();
    }
 
    inline bool isModifier() const
    {
        return modifier_bits() != 0;
    }
    inline bool isShift() const
    {
        return modifier_bits() & keyboard::MODIFIER_SHIFT_BIT;
    }
    inline bool isSymbol() const
    {
        return modifier_bits() & keyboard::MODIFIER_SYMBOL_BIT;
    }
    inline bool isFunction() const
    {
        return modifier_bits() & keyboard::MODIFIER_FUNCTION_BIT;
    }
    inline bool isAlt() const
    {
        return modifier_bits() & keyboard::MODIFIER_ALT_BIT;
    }
    inline bool isControl() const
    {
        return modifier_bits() & keyboard::MODIFIER_CONTROL_BIT;
    }
    inline bool isOption() const
    {
        return modifier_bits() & keyboard::MODIFIER_OPTION_BIT;
    }
 
    inline bool isShiftEqual() const
    {
        return modifier_bits() == keyboard::MODIFIER_SHIFT_BIT;
    }
    inline bool isSymbolEqual() const
    {
        return modifier_bits() == keyboard::MODIFIER_SYMBOL_BIT;
    }
    inline bool isFunctionEqual() const
    {
        return modifier_bits() == keyboard::MODIFIER_FUNCTION_BIT;
    }
    inline bool isAltEqual() const
    {
        return modifier_bits() == keyboard::MODIFIER_ALT_BIT;
    }
    inline bool isControlEqual() const
    {
        return modifier_bits() == keyboard::MODIFIER_CONTROL_BIT;
    }
    inline bool isOptionEqual() const
    {
        return modifier_bits() == keyboard::MODIFIER_OPTION_BIT;
    }
 
    inline bool isPressed() const
    {
        return _state.now.any();
    }
    inline bool isReleased() const
    {
        return !isPressed();
    }
    inline bool wasPressed() const
    {
        return _state.pressed.any();
    }
    inline bool wasReleased() const
    {
        return _state.released.any();
    }
    inline bool isHolding() const
    {
        return _state.holding.any();
    }
    inline bool wasHold() const
    {
        return _state.was_hold.any();
    }
    inline bool isRepeating() const
    {
        return _state.repeating.any();
    }
 
 
    // inline
    bool isPressed(const keyboard::key_index_t kidx) const
    {
        return (kidx < 64) && _state.now.test(kidx);
    }
    inline bool isReleased(const keyboard::key_index_t kidx) const
    {
        return !isPressed(kidx);
    }
    inline bool wasPressed(const keyboard::key_index_t kidx) const
    {
        return (kidx < 64) && _state.pressed.test(kidx);
    }
    inline bool wasReleased(const keyboard::key_index_t kidx) const
    {
        return (kidx < 64) && _state.released.test(kidx);
    }
    inline bool isHolding(const keyboard::key_index_t kidx) const
    {
        return (kidx < 64) && _state.holding.test(kidx);
    }
    inline bool wasHold(const keyboard::key_index_t kidx) const
    {
        return (kidx < 64) && _state.was_hold.test(kidx);
    }
    inline bool isRepeating(const keyboard::key_index_t kidx) const
    {
        return (kidx < 64) && _state.repeating.test(kidx);
    }
 
 
    inline virtual keyboard::key_index_t toKeyIndex(const char) const
    {
        return 0xFF;
    }
    inline bool isPressed(const char ch) const
    {
        auto kidx = toKeyIndex(ch);
        return kidx != 0xFF && isPressed(kidx) && permitted_mode(to_mode_bits(ch));
    }
    inline bool isReleased(const char ch) const
    {
        return !isPressed(ch);
    }
    inline bool wasPressed(const char ch) const
    {
        auto kidx = toKeyIndex(ch);
        return kidx != 0xFF && wasPressed(kidx) && permitted_mode(to_mode_bits(ch));
    }
    inline bool wasReleased(const char ch) const
    {
        auto kidx = toKeyIndex(ch);
        return kidx != 0xFF && wasReleased(kidx) && permitted_mode(to_mode_bits(ch));
    }
    inline bool isHolding(const char ch) const
    {
        auto kidx = toKeyIndex(ch);
        return kidx != 0xFF && isHolding(kidx) && permitted_mode(to_mode_bits(ch));
    }
    inline bool wasHold(const char ch) const
    {
        auto kidx = toKeyIndex(ch);
        return kidx != 0xFF && wasHold(kidx) && permitted_mode(to_mode_bits(ch));
    }
    inline bool isRepeating(const char ch) const
    {
        auto kidx = toKeyIndex(ch);
        return kidx != 0xFF && isRepeating(kidx) && permitted_mode(to_mode_bits(ch));
    }
 
 
    inline uint8_t firmwareVersion() const
    {
        return _firmware_version;
    }
    virtual bool readFirmwareVersion(uint8_t& ver);
 
    inline uint32_t holdingThreshold() const
    {
        return _state.holding_threshold_ms;
    }
    inline uint32_t repeatingThreshold() const
    {
        return _state.repeat_initial_ms;
    }
    inline void setHoldingThreshold(const uint32_t ms)
    {
        _state.holding_threshold_ms = ms;
    }
    inline void setRepeatingThreshold(const uint32_t ms)
    {
        _state.repeat_initial_ms = ms;
        _state.repeat_rate_ms    = ms;  // CardKB-style: rate == initial (legacy single-threshold behavior)
    }
 
 
    virtual bool readMode(keyboard::Mode& mode);
    virtual bool writeMode(const keyboard::Mode mode);
 
protected:
    bool start_periodic_measurement();
    bool start_periodic_measurement(const uint32_t interval);
    bool stop_periodic_measurement();
 
    bool update_new_firmware(const types::elapsed_time_t at);
    void push_back(m5::container::CircularBuffer<uint8_t>* container, const uint8_t kidx, const uint8_t alt);
 
    inline keyboard::key_status_bits_t modifier_bits() const
    {
        return keyboard::modifier_bits(_state.now.to_ullong());
    }
 
    inline virtual uint8_t to_mode_bits(const char) const
    {
        return 0x00;
    }
 
    inline virtual uint8_t scan_reg_addr() const
    {
        return 0x10;
    }
    inline virtual uint8_t mode_reg_addr() const
    {
        return 0x20;
    }
    inline virtual uint8_t firmware_version_reg_addr() const
    {
        return 0xFE;
    }
 
    bool permitted_mode(const uint8_t mbits) const
    {
        uint8_t mod8 = static_cast<uint8_t>(_state.now.to_ullong() >> 56);
        // mod8 bit0=Shift→mbits bit1, bit1=Sym→bit2, bit2=Fn→bit3
        return mbits & (mod8 ? (mod8 << 1) : 0x01);
    }
 
    M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(UnitKeyboardBitwise, uint8_t);
 
protected:
    std::unique_ptr<m5::container::CircularBuffer<uint8_t>> _data{};  // was Pressed keys
    m5::unit::keyboard_bitwise::BitwiseState<64> _state;
    uint8_t _firmware_version{};
    keyboard::Mode _mode{keyboard::Mode::Conventional};
};
 
namespace keyboard {
namespace command {
constexpr uint8_t CMD_SCAN_REG{0x10};
constexpr uint8_t CMD_MODE_REG{0x20};
constexpr uint8_t CMD_FIRMWARE_VERSION_REG{0xFE};
}  // namespace command
 
}  // namespace keyboard
 
}  // namespace unit
}  // namespace m5
#endif