Mastodawn

Gonçalo Ribeiro Apr 13, 2024

Trying to reverse a bit of the USB configuration protocol for my #8bitdo #retro #keyboad, the bad boy in the picture. I want to configure some of its keys to something I can't with their #proprietary software, that's why.

The protocol is based on #USBHID. I've captured packets and think I understand the basics of what I would need to send it. Capturing these packets had to involve a Windows VM, since the configuration software is not available for #Linux.

Now I want to replay some packets to test the protocol. Struggling a bit with that, on how to do it. Explored #usbrply as an option but it seems not to be looking at the HID data. A bit weird.

I think I'll try to write a simple thing in #python for testing next.

And I hope not no brick the thing...

Gonçalo Ribeiro

I don't know if I'll succeed, maybe I won't. But I think it's important to document this anyway.

Gonçalo Ribeiro Apr 14, 2024

OMG! Managed to change the mapping of a key just by writing some bytes to stdout and redirecting them to a /dev/hidraw !

This was after trying to replicate the protocol message with python-hidapi and failing (I want interrupts, and it seems that not what that library does...?).

Also had to battle a bit with #udev rules, which I hadn't for a while now.

Gonçalo Ribeiro Apr 14, 2024

I did it! Mapped the key I wanted to the red B hardware key.

I had to brute force this by looping config messages until the key outputted what I wanted.

Now I could try to have a full mapping on what to send to output a specific key on any hardware key. But I've essentially finished what I wanted already.

Gonçalo Ribeiro Apr 20, 2024

Yesterday I reversed the byte in the protocol that corresponds to each hardware key.

I want to write a simple CLI program to map any hardware key to any desired key.

Gonçalo Ribeiro Apr 22, 2024

Oh no. I am now browsing the #USB "HID Usage Tables" specification 😱

After some testing and looking things up, it seems the values sent to the #8BitDo keyboard to map keys are essentially those. So here I am...

https://usb.org/sites/default/files/hut1_3_0.pdf

Gonçalo Ribeiro Apr 23, 2024

I'm trying to write a simple #python utility to configure mappings that I can publish for others to use.

Previously all the tests I did were by directly writing data to /dev/hidraw.

I'm having a hard time understanding how I can replicate this with some python library and not writing to a /dev/hidraw file directly...

Gonçalo Ribeiro Apr 23, 2024

Gee... Succeeded to finally send what I wanted to the keyboard. It seems the kernel was holding the interface. Maybe hidraw, I dunno... I have to figure this out properly.

Gonçalo Ribeiro Apr 23, 2024

That was exactly it. If I call "detach_kernel_driver()" (this is #pyusb) on the interface of interest it will no longer show in /dev/hidraw devices.

Then I can send data to the interface without getting "resource busy" errors.

Gonçalo Ribeiro Apr 26, 2024

First usable version of the program is written, but needs improvements, such as checking replies are what is expected.

Gonçalo Ribeiro Apr 27, 2024

The 8BitDo Retro Mechanical Keyboard configuration program is ready with all the basic features I wanted it to have.

Now I'm doing some refactoring and want to package it and write a #readme before I publish it.

#8BitDo #retro #keyboard #linux #foss #openSource

Gonçalo Ribeiro Apr 28, 2024

Struggling to package the thing. When I run __main__.py directly things work. However, when I install the module and run the script that it installs, imports do not work correctly.

Having a hard time figuring it out or finding a good reference.

Gonçalo Ribeiro Apr 28, 2024

Was able to implement a workaround. But it's something that could probably land me in Python prison 😐 not sure.

Now... I have another problem though... A circular dependency 😕

Gonçalo Ribeiro Apr 28, 2024

Looking at a few projects as examples to help me understand how this is usually done and in retrospective this is probably why Flask has its main class in app.py (not flask.py) and has all manner of weird looking imports.

Gonçalo Ribeiro Apr 28, 2024

It's working! Both packaged and not packaged! 😁

Gonçalo Ribeiro Apr 28, 2024

Okay, my 8BitDo Retro Mechanical Keyboard configuration utility is ready and published!

If you know someone who uses one of these keyboards on Linux, please spread the word as they may find it useful 😄

https://github.com/goncalor/8bitdo-kbd-mapper/

#8BitDo #retro #mechanical #keyboard #linux #foss #openSource

GitHub - goncalor/8bitdo-kbd-mapper: Key mapper for 8BitDo's Retro Mechanical Keyboard

Key mapper for 8BitDo's Retro Mechanical Keyboard. Contribute to goncalor/8bitdo-kbd-mapper development by creating an account on GitHub.

GitHub

Gonçalo Ribeiro May 5, 2024

Today, after reading the #udev #manpage and some other references I managed to write a udev rule to automatically unbind the USB interface of the keyboard, the one used to program it.

It was an interesting challenge because the keyboard has multiple interfaces under the same #USB vendor and product IDs and I only wanted to touch that specific interface.

There's something not quite right yet for my objective of manking my #8bdkbd utility able to run rootless though. Will keep experimenting later.

Gonçalo Ribeiro May 5, 2024

Just figured it out.

I had to unbind usbhid, not only hid-generic (PS: unbinding usbhid will also unbind hid-generic). And set the right permissions at the SUBSYSTEM=="usb" level.

Now when the keyboard is connected interface no. 2 gets unbound and permissions are correct such that python can read/write to that #USB interface. Without affecting the remaining interfaces.

Rules for reference (PROGRAM is just for debugging, RUN has the unbind action):

SUBSYSTEM=="usb", ATTRS{idVendor}=="2dc8", ATTRS{idProduct}=="5200", MODE="0660", TAG+="uaccess"

ACTION=="bind", SUBSYSTEM=="usb", ATTR{bInterfaceNumber}=="02", ATTRS{idVendor}=="2dc8", ATTRS{idProduct}=="5200", PROGRAM="/usr/bin/sh -c 'logger -p user.info usb matched! kernel=$kernel, number=$number, devpath=$devpath, id=$id, driver=$driver, major=$major, minor=$minor, result=$result, parent=$parent, name=$name, links=$links, root=$root, sys=$sys, devnode=$devnode'", RUN+="/usr/bin/sh -c 'echo $kernel > /sys/bus/usb/drivers/usbhid/unbind'"

#udev #8BitDo #8bdkbd

Gonçalo Ribeiro Jan 14, 2025

No idea why my 8BitDo Retro Mechanical Keyboard configuration utility (#8bdkbd) #GitHub repository has been increasing starts a bit faster lately. Actually quite surprised it has this "many" stars.

I'm glad, since I put it out there so that it could help someone else. But since I've published it and configured my own keyboard, it's been pretty much fire and forget.

(Theory: maybe people got keyboards for Christmas and found the repo as they started using the keyboard?)

https://github.com/goncalor/8bitdo-kbd-mapper/

#8BitDo #retro #mechanical #keyboard #linux #foss #openSource

GitHub - goncalor/8bitdo-kbd-mapper: Key mapper for 8BitDo's Retro Mechanical Keyboard

Key mapper for 8BitDo's Retro Mechanical Keyboard. Contribute to goncalor/8bitdo-kbd-mapper development by creating an account on GitHub.

GitHub

Gonçalo Ribeiro Mar 2

Just found out by accident that someone created an #AUR repo for my keyboard mapper!

https://aur.archlinux.org/packages/8bitdo-kbd-mapper

#8bitdo #8bdkbd

AUR (en) - 8bitdo-kbd-mapper