HID_KEYBOARD BIOS support

[silpakcx]

Hi

To enable the keyboard library in BIOS environment, I have modified the RP2040USB.cpp file usb descriptor as per your instruction. Now the RP2040-based keyboard emulator starts working on the BIOS environment. But when I tested, arrow keys, enter, esc everything was working fine except the alphabet.

During some settings change in the BIOS screen, we need to give YES/NO options, but since the keyboard emulator alphabet are not working, I could not perform some BIOS-related task.

Can you guide me on how to enable the alphabet in the BIOS screen.

[earlephilhower]

Sorry, you've changed the code so there's not much we can do here. My guess is you're either sending the wrong sequence of make/break keypresses, or the keypress codes in BIOS mode are not the standard one. You should check the USB HID implementor's guide for the mappings.

[silpakcx]

I didnt make much changes in the library code. The change that I did is in the RP2040USB.cpp file, inside __SetupUSBDescriptor() function , I made the following changes

GetDescHIDReport(&hid_report_len); uint8_t hid_itf = __USBInstallSerial ? 2 : 0; uint8_t hid_desc[TUD_HID_DESC_LEN] = { // Interface number, string index, protocol, report descriptor len, EP In & Out address, size & polling interval TUD_HID_DESCRIPTOR(hid_itf, 0, HID_ITF_PROTOCOL_KEYBOARD, hid_report_len, EPNUM_HID, CFG_TUD_HID_EP_BUFSIZE, 10) };
instead of HID_ITF_PROTOCOL_NONE , I changed it to HID_ITF_PROTOCOL_KEYBOARD(line no : 266). then the keyboard started working in BIOS environment .

The keycode that I am sending is the corresponding ASCII codes only . The keycodes are working perfectly in the OS mode , but not in BIOS mode.
eg : KEY_A 0x41

Can you please help me to solve this issue.

[thinhthui]

in Keyboard.cpp you can see the function

void Keyboard_::sendReport(KeyReport* keys) {
    CoreMutex m(&__usb_mutex);
    tud_task();
    if (__USBHIDReady()) {
        //tud_hid_n_report(0x00, 0, keys, sizeof(*keys));
       //tud_hid_keyboard_report(__USBGetKeyboardReportID(), keys->modifiers, keys->keys);
        tud_hid_keyboard_report(0, keys->modifiers, keys->keys); //change reportid to 0 to work in bios
    }
    tud_task();
}

note that by changing this, device will not be able to work when you enter os. i had to write a seperate function, descriptor so that it can auto toggle between boot and report protocol.

here're what i changed:

RP2040USB

//RP2040USB.h
extern bool is_not_bios; // add global value when checking what descriptor and function to use
void __USBRestart(); //add custom function to reload descriptor

//RP2040USB.cpp
bool is_not_bios = false;

void __SetupDescHIDReport() {
    uint8_t desc_hid_report_nkro[] = { TUD_HID_REPORT_DESC_NKRO(HID_REPORT_ID(1)), TUD_HID_REPORT_DESC_CONSUMER(HID_REPORT_ID(2)) };
    
    if (__USBInstallKeyboard) {
        if (is_not_bios) {
            size += sizeof(desc_hid_report_nkro);
            Serial.println("NKRO");
        }else{
            size += sizeof(desc_hid_report_keyboard);
            Serial.println("Legacy");
        }
    }
   ...

   //allocate the "real" HID report descriptor
    __hid_report = (uint8_t *)malloc(size);
    if (__hid_report) {
       ...
        if (__USBInstallKeyboard) {
            
            if (is_not_bios) {
                memcpy(__hid_report, desc_hid_report_nkro, sizeof(desc_hid_report_nkro));
            }else{
                memcpy(__hid_report, desc_hid_report_keyboard, sizeof(desc_hid_report_keyboard));
            } 
        ...
        }
    }
    ...
}

void __SetupUSBDescriptor(){
    ...
    uint8_t hid_desc[TUD_HID_DESC_LEN] = {
        // Interface number, string index, protocol, report descriptor len, EP In & Out address, size & polling interval
        TUD_HID_DESCRIPTOR(hid_itf, 0, HID_ITF_PROTOCOL_KEYBOARD, hid_report_len, EPNUM_HID, CFG_TUD_HID_EP_BUFSIZE, (uint8_t)usb_hid_poll_interval)
    };
    ...
}

void __USBRestart() {
    if (tusb_inited()){
        tud_disconnect();
        tud_deinit(TUD_OPT_RHPORT);
        delay(1000);
        __hid_report_len = 0;
        __hid_report     = nullptr;

        free(usbd_desc_cfg); 
        usbd_desc_cfg = nullptr;

        __SetupDescHIDReport();
        __SetupUSBDescriptor();
        delay(1000);
        tusb_init();
        tud_connect();
    }
} 

HID_Keyboad
i use hid keycode so i had to modify checking logic, no ascii mapping to hid keycode, also i use bitmap for nkro.

//HID_Keyboad.h

// add nkro type
typedef struct{
  uint8_t modifiers;
  uint8_t reserved;
  uint8_t keys[0x68 / 8];
} NKRO;

class HID_Keyboard : public Print{
protected:
  ...
  virtual void sendReportNKRO(NKRO* keys) = 0;  // add custom function for sending nkro report
  ...
}

//HID_Keyboad.cpp
HID_Keyboard::HID_Keyboard(void){
	_asciimap = KeyboardLayout_en_US;
	_ledCB = nullptr;
}

void HID_Keyboard::begin(const uint8_t *layout){
	if (is_not_bios){
		bzero(&_nkroReport, sizeof(_nkroReport));
	}else{
		bzero(&_keyReport, sizeof(_keyReport));
	}
	_asciimap = layout;
}

void HID_Keyboard::end(void){
	if (is_not_bios)
	{
		bzero(&_nkroReport, sizeof(_nkroReport));
	}
	else
	{
		bzero(&_keyReport, sizeof(_keyReport));
	}
//this function is empty so i just implement my reload code to it
}

size_t HID_Keyboard::press(uint8_t k){
	if (is_not_bios){

		uint8_t *target;

		if (k < 0x68){
			target = &_nkroReport.keys[k / 8];
		}
		else if (k >= 224 && k <= 231){ 
			target = &_nkroReport.modifiers;
		}else{
			return 0;
		}

		uint8_t bit = 1 << (k % 8);
		*target |= bit;

		sendReportNKRO(&_nkroReport);
	}else{
		uint8_t i;
		// k = ascii_conv_table[k][0];
		if (k >= 231){ // it's a non-printing key (not a modifier)
			k = k - 231;
		}else if (k >= 224){ // it's a modifier key
			_keyReport.modifiers |= (1 << (k - 224));
			k = 0;
		}

		if (_keyReport.keys[0] != k && _keyReport.keys[1] != k &&
			_keyReport.keys[2] != k && _keyReport.keys[3] != k &&
			_keyReport.keys[4] != k && _keyReport.keys[5] != k){

			for (i = 0; i < 6; i++){
				if (0 != k && _keyReport.keys[i] == 0x00){
					_keyReport.keys[i] = k;
					break;
				}
			}
			if (i == 6){
				setWriteError();
				return 0;
			}
		}
		sendReport(&_keyReport);
	}

	return 1;
}


size_t HID_Keyboard::release(uint8_t k){
	if (is_not_bios){
		uint8_t *target;

		if (k < 0x68){
			target = &_nkroReport.keys[k / 8];
		}
		else if (k >= 224 && k <= 231){ 
			target = &_nkroReport.modifiers;
		}else{
			return 0;
		}

		uint8_t bit = 1 << (k % 8);
		*target &= ~bit;

		sendReportNKRO(&_nkroReport);
	}else{
		int8_t i;
		
		if (k >= 231){ 
			k = k - 231;
		}else if (k >= 224){ 
			_keyReport.modifiers &= ~(1 << (k - 224));
			k = 0;
		}

		for (i = 0; i < 6; i++){
			if (0 != k && _keyReport.keys[i] == k)
			{
				_keyReport.keys[i] = 0x00;
			}
		}

		sendReport(&_keyReport);
	}
	return 1;
}

Keyboard

//Keyboard.h
class Keyboard_ : public HID_Keyboard {
protected:
    virtual void sendReportNKRO(NKRO* keys) override;
    ...
}

//Keyboard.cpp
void Keyboard_::sendReport(KeyReport* keys) {
    CoreMutex m(&__usb_mutex);
    tud_task();
    if (__USBHIDReady()) {
        tud_hid_n_report(0x00, 0, keys, sizeof(*keys));
        //tud_hid_keyboard_report(__USBGetKeyboardReportID(), keys->modifiers, keys->keys);
    }
    tud_task();
}

void Keyboard_::sendReportNKRO(NKRO* keys) {
    CoreMutex m(&__usb_mutex);
    tud_task();
    if (__USBHIDReady()) {
        tud_hid_n_report(0x00, __USBGetKeyboardReportID(), keys, sizeof(*keys));
    }
    tud_task();
}

hid_device.h
i changed the default keyboard descriptor to match the one in the document here

// also add nkro descriptor
#define TUD_HID_REPORT_DESC_NKRO(...)                \
  HID_USAGE_PAGE(HID_USAGE_PAGE_DESKTOP), \ 
HID_USAGE(HID_USAGE_DESKTOP_KEYBOARD),               \
      \ 
HID_COLLECTION(HID_COLLECTION_APPLICATION),\ 
  /* Report ID if any */\ 
  __VA_ARGS__ \ 
    /* 8 bits Modifier Keys (Shift, Control, Alt) */ \
      HID_USAGE_PAGE(HID_USAGE_PAGE_KEYBOARD),\ 
    HID_USAGE_MIN(224),\ 
    HID_USAGE_MAX(231),\ 
    HID_LOGICAL_MIN(0),\ 
    HID_LOGICAL_MAX(1),\ 
    HID_REPORT_COUNT(8),\ 
    HID_REPORT_SIZE(1),\ 
    HID_INPUT(HID_DATA | HID_VARIABLE | HID_ABSOLUTE),\ 
    /* 8 bit reserved */ \ 
    HID_REPORT_COUNT(1),\ 
    HID_REPORT_SIZE(8),\ 
    HID_INPUT(HID_CONSTANT),\ 
  /* Output 5-bit LED Indicator Kana | Compose | ScrollLock | CapsLock | NumLock */ \ 
  HID_USAGE_PAGE(HID_USAGE_PAGE_LED),\ 
    HID_USAGE_MIN(1),\ 
    HID_USAGE_MAX(5),\ 
    HID_REPORT_COUNT(5),\ 
    HID_REPORT_SIZE(1),\ 
    HID_OUTPUT(HID_DATA | HID_VARIABLE | HID_ABSOLUTE),\ 
    /* led padding */                                \
      HID_REPORT_COUNT(1),\ 
    HID_REPORT_SIZE(3),\ 
    HID_OUTPUT(HID_CONSTANT),\ 
    /* 6-byte Keycodes */                            \
      HID_USAGE_PAGE(HID_USAGE_PAGE_KEYBOARD),\ 
    HID_USAGE_MIN(0),\ 
    HID_USAGE_MAX_N(0x67, 1),\ 
    HID_LOGICAL_MIN(0),\ 
    HID_LOGICAL_MAX_N(1, 1),\ 
    HID_REPORT_COUNT(0x68),\ 
    HID_REPORT_SIZE(1),\ 
    HID_INPUT(HID_DATA | HID_VARIABLE | HID_ABSOLUTE),  \
      HID_COLLECTION_END

and in your project.ino

#include <Keyboard.h>
#include <RP2040USB.h>
#include "Adafruit_TinyUSB_Arduino/src/class/hid/hid_device.h" //from rp2040 libs

void setup() {
  Keyboard.begin();
}

void loop() {
  unsigned long now = millis();
  if (now - check_bios_time >= 100){
    if (__USBHIDReady()){
      if (is_not_bios != tud_hid_get_protocol()){
        
        is_not_bios = tud_hid_get_protocol();
        /* this is just for my indicator
        if (is_not_bios){
          hue = 160;
        }else{
          hue = 0;
        }
        */
        Keyboard.end();
        __USBRestart();
        // Serial.print(is_not_bios);
        // Serial.print(", ");
        // Serial.println(tud_hid_get_protocol());
      }
    }
    check_bios_time = now;
  }
  
  /*
    do something here
 */
}

i was about to use pico sdk to write from scratch but i'm making a wireless keyboard with nrf24 so it's quite a pain to write, so instead i just modified the libs.

[thinhthui]

@earlephilhower I think you could implement those methods to support N-Key roll over and boot descriptor during bios phase. That would be very nice.

[earlephilhower]

Thanks for the writeup. I'll look into it. First, I need to get a more elegant USB/HID descriptor setup...the hardcoded bits now are a PITA and very easy to break with something like this. Maybe something like the SDK is using for chip bringup...