International keycode cannot be sent or received by macOS host

[henoya]

I'm working on a prototype customized keyboard using a Raspberry Pi Pico. This is a Japanese keyboard.

When the host is macOS, keycodes above 0x80 are not being sent or received.
Normal keycodes are sent to the host without any problem, and modifier keys such as SHIFT ALT CMD seem to work fine.
Normal keys with keycode 0x80 and above are not reaching the host.

When the same Pico is connected to a Windows host, all keycodes are received.

I noticed this when using KMK_Firmware as keyboard middleware for CircuitPython and configuring it for a Japanese environment.
For testing purposes, a simple code written using only CircuitPython + adafruit_hid is as follows

import board
import time
import usb_hid
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode

kbd = Keyboard(usb_hid.devices)

KC_INT1 = 135 # 0x87 \ Keyboard International1
KC_INT2 = 136 # 0x88 KANA Keyboard International2
KC_INT3 = 137 # 0x89 _ Keyboard International3
KC_INT4 = 138 # 0x8A HENK Keyboard International4
KC_INT5 = 139 # 0x8B MHEN Keyboard International5

codes = [Keycode.A, Keycode.B, Keycode.C, KC_INT1, KC_INT3, KC_INT2, KC_INT4, KC_INT5]
for code in codes:
    kbd.press(code)
    time.sleep(0.1)
    kbd.release(code)
    time.sleep(0.1)

If you run this code for a Japanese keyboard layout, the host should have the input "abc_￥". Keycode 135 will be the input for _. Keycode 137 will be the Japanese currency symbol ￥.
The last three keycodes, 137, 138, and 139, are the start and end keys for Japanese input conversion.

If you start the program under macOS, it will detect up to "abc", but not "_(INT1)³(INT3)", and the functions assigned to INT2, INT4, and INT5 will not work.

In the Windows environment, all the keycodes were entered.
It seems that keycodes above 0x80 are excluded when the host is macOS, but I don't know the cause.

To check the keycode, I use EventViewer, which comes with karabiner-element for macOS.
When I press a key, the keycode and the up down event are displayed, but when the keycode is 0x80 or higher, neither of the events are displayed.

In the Windows environment, the corresponding character was actually typed. Also, I was able to confirm that the INT2, INT4, and INT5 keys were pressed in the soft keyboard display.

My experimental environment is as follows. Unfortunately, I have not been able to test in other environments.

• macOS Big Sur 11.5.1 AppleSilicon and Intel i9 chip
  • Intel machines are near mint.
• Windows 10 Pro 21H1

CircuitPython was tested with versions 6.3.0 and 7.0.0-Alpha5. Both worked the same.

If I type the same key from an off-the-shelf keyboard against macOS, the keycode is received and works correctly.

Is there a solution?

Thanks.

[dhalbert]

The code in the library is not the problem, but there might be a problem in the default keyboard report descriptor, so I have transferred this issue to https://github.com/adafruit/circuitpython/. If there is a problem, it might be that MacOS is more sensitive to this than Windows. It is a signed/unsigned-value problem.

Could you try this UF2 and see if it makes a difference? Unzip it before uploading, of course.

pico-kbd-report-desc-logical-maximum-fix.uf2.zip

[henoya]

Dan-san
I tried UF2 and got the following error.

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.
code.py output:
Traceback (most recent call last):
  File "code.py", line 17, in <module>
  File "/lib/adafruit_hid/keyboard.py", line 91, in press
OSError: USB busy

The code in code.py is the same as the first.

[dhalbert]

I would be interested in seeing the HID report descriptor for your off-the-shelf Japanese keyboard. On the Mac, you can dump it using this tool: https://github.com/todbot/mac-hid-dump. A precompiled version of this is in https://github.com/todbot/mac-hid-dump/releases/tag/0.1, in the zip file. Thanks.

[henoya]

Thank you. I will try to get the HID report descriptor now.

[henoya]

Got the HID report descriptor, ARCHISS PTR91 is the off-the-shelf one.
I don't know why two are shown, but one is connected.
Here is the URL of the product page in Japanese.
https://archisite.co.jp/products/archiss/progres-touch/retro-tiny-jp/

$ ~/Downloads/mac-hid-dump
mac-hid-dump:
2BE8 0001: ARCHISS - ARCHISS PTR91
DESCRIPTOR:
  05  01  09  06  a1  01  05  07  19  e0  29  e7  15  00  25  01
  75  01  95  08  81  02  95  01  75  08  81  01  95  05  75  01
  05  08  19  01  29  05  91  02  95  01  75  03  91  01  95  06
  75  08  15  00  26  ff  00  05  07  19  00  2a  ff  00  81  00
  c0
  (65 bytes)
239A 80F4: Raspberry Pi - Pico
DESCRIPTOR:
  05  01  09  06  a1  01  85  01  05  07  19  e0  29  e7  15  00
  25  01  75  01  95  08  81  02  81  01  19  00  29  dd  15  00
  25  dd  75  08  95  06  81  00  05  08  19  01  29  05  15  00
  25  01  75  01  95  05  91  02  95  03  91  01  c0  05  01  09
  02  a1  01  09  01  a1  00  85  02  05  09  19  01  29  05  15
  00  25  01  95  05  75  01  81  02  95  01  75  03  81  01  05
  01  09  30  09  31  15  81  25  7f  75  08  95  02  81  06  09
  38  15  81  25  7f  75  08  95  01  81  06  c0  c0  05  0c  09
  01  a1  01  85  03  75  10  95  01  15  01  26  8c  02  19  01
  2a  8c  02  81  00  c0
  (150 bytes)
2BE8 0001: ARCHISS - ARCHISS PTR91
DESCRIPTOR:
  05  01  09  06  a1  01  85  08  05  07  19  e0  29  e7  15  00
  25  01  75  01  95  08  81  02  09  2b  09  2c  09  4f  19  04
  29  28  15  00  25  01  75  01  95  28  81  02  09  2d  19  59
  29  63  15  00  25  01  75  01  95  0c  81  02  09  67  19  50
  29  58  15  00  25  01  75  01  95  0a  81  02  09  65  09  2e
  09  29  09  2f  09  64  09  2a  15  00  25  01  75  01  95  06
  81  02  19  90  29  95  15  00  25  01  75  01  95  06  81  02
  19  30  29  4e  15  00  25  01  75  01  95  1f  81  02  09  68
  09  69  19  87  29  8b  15  00  25  01  75  01  95  07  81  02
  c0  05  0c  09  01  a1  01  85  01  19  00  2a  3c  02  15  00
  26  3c  02  95  01  75  10  81  00  c0
  (170 bytes)

[dhalbert]

Sorry for the delay, I am getting back to this now.

[dhalbert]

OK, I have another UF2 for you to test:
pico-kbd-0-255.uf2.zip

I tested this with karabiner-elements-EventViewer (nice program, by the way), and now I see the KC_INTx codes showing up, which did not happen with alpha.6. The version above has a keyboard descriptor that should allow 0-255 (it was adapter from a US commercial keyboard).

Incidentally, I was never able to actually see a ￥ produced, but I may not have the input methods, etc., set up right. I have some familiarity with Japanese input methods for historical reasons but know no Japanese to speak of. I tried on both Linux, Windows, and Mac, and never saw a ￥, but on Linux and Mac, I was able to verify that a code is being sent.

I did some searching and saw that 165 is sometimes the code for ￥, but that did not work either.

[henoya]

Dan-san

Thanks!
I have tried pico-kbd-0-255.uf2.zip and it works fine.
I have confirmed that keycodes that were not entered in the previous version are now entered!
The ￥ character is assigned to the same character code as / (backslash) in ASCII code, but it is not supposed to be displayed unless you have a Japanese display environment.
In my computer environment, INT1 (135) was correctly entered and the ￥ character was displayed.

I can now use the keyboard without resorting to the trick of using karabiner-elements.
I hope this fix will be merged into the main branch.

[dhalbert]

Great! Thank you for testing. This fix has already been merged as part of #5151, since I felt that the descriptor needed improvement in any case. It is already available in any "Absolute Newest" release, and will be in the next release, which will probalby be 7.0.0-beta.0.

The specific commit is 38f4281.