TKeyboard.h

Go to the documentation of this file.

//------------------------------------------------------------------------------
// Module:        CTKeyboard
// Description:   Handles USB keyboard input and manages keyboard state.
// Author:        R. Zuehlsdorff, ralf.zuehlsdorff@t-online.de
// Created:       2026-01-21
// License:       MIT License (https://opensource.org/license/mit/)
//------------------------------------------------------------------------------
// Change Log:
// 2026-01-21     R. Zuehlsdorff        Initial creation
//------------------------------------------------------------------------------
 
#pragma once
 
// Include Circle core components
#include <circle/sched/task.h>
#include <circle/usb/usbkeyboard.h>
#include <circle/usb/usbhcidevice.h>
#include <circle/devicenameservice.h>
#include <circle/logger.h>
#include <circle/types.h>
#include <circle/timer.h>
 
// Forward declarations
class CKernel;
 
 
class CTKeyboard : public CTask
{
public:
    using TKeyPressedHandler = void (*)(const char *pString);
    using TKeyStatusHandlerRaw = void (*)(unsigned char ucModifiers, const unsigned char RawKeys[6]);
    static CTKeyboard *Get(void);
 
    CTKeyboard(void);
    void Configure(TKeyPressedHandler pKeyPressedHandler,
                   TKeyStatusHandlerRaw pKeyStatusHandlerRaw = nullptr,
                   CUSBHCIDevice *pUSBHost = nullptr,
                   unsigned keyRepeatDelayMs = KeyRepeatDelayDefaultMs,
                   unsigned keyRepeatRateCps = KeyRepeatRateDefaultCps);
    ~CTKeyboard(void);
 
    boolean Initialize(void);
 
    boolean UpdateKeyboard(boolean bDevicesUpdated);
 
    void UpdateLEDs(void);
 
    boolean IsKeyboardConnected(void) const;
 
    void OnConfigUpdated();
 
    void Update();
 
    void Run(void) override;
 
    void SetKeyPressedHandler(TKeyPressedHandler handler);
    void SetKeyStatusHandlerRaw(TKeyStatusHandlerRaw handler);
    TKeyPressedHandler GetKeyPressedHandler() const;
    TKeyStatusHandlerRaw GetKeyStatusHandlerRaw() const;
 
private:
    // Static callback handlers
    static void KeyboardRemovedHandler(CDevice *pDevice, void *pContext);
    static void KeyPressedTrampoline(const char *pString);
    static void KeyStatusTrampoline(unsigned char ucModifiers, const unsigned char RawKeys[6]);
 
    // Internal methods
    void OnKeyboardRemoved(void);
    void HandleKeyPressed(const char *pString, boolean fromAutoRepeat);
    void HandleRawKeyStatus(unsigned char ucModifiers, const unsigned char RawKeys[6]);
    void ServiceAutoRepeat();
    void StopAutoRepeat();
    void TryActivateAutoRepeat();
    void QueueAutoRepeat(const char *pString);
    boolean ShouldQueueAutoRepeat(const char *pString) const;
 
private:
    static constexpr unsigned KeyRepeatDelayDefaultMs = 500;
    static constexpr unsigned KeyRepeatRateDefaultCps = 20;
    CUSBKeyboardDevice *volatile m_pKeyboardDevice{nullptr};
    CUSBHCIDevice *m_pUSBHost;
 
    static constexpr size_t AutoRepeatMaxSequence = 8;
    struct AutoRepeatState
    {
        boolean active;
        boolean pendingStart;
        unsigned char rawKeyCode;
        char sequence[AutoRepeatMaxSequence + 1];
        unsigned sequenceLength;
        u64 pressStartUs;
        u64 nextRepeatUs;
        u64 delayUs;
        u64 intervalUs;
    } m_AutoRepeat;
    unsigned char m_PreviousRawKeys[6];
    unsigned char m_PendingAutoRepeatRawKey;
    unsigned m_KeyRepeatDelayMs;
    unsigned m_KeyRepeatRateCps;
 
    TKeyPressedHandler m_pKeyPressedHandler;
    TKeyStatusHandlerRaw m_pKeyStatusHandlerRaw;
};