Help to support Halo75

[ijverig]

Hello, how can I reverse engineer USB comm for the Halo75? I'd like to submit a patch to support it, if possible.

Another question: does nudelta save the remappings on the keyboard itself?

[yujinlin0224]

Also waiting for Halo75

[donn]

@ijverig First of all, yes, Nudelta's changes are written to the keyboard itself.

P.S. @adokitkat - I think you might be interested in this writeup as well.

---

At a basic level:

• You need the NuPhy Console (which requires either Windows or a Windows Virtual Machine.)
• You'll need to setup Wireshark for USB capture: See https://wiki.wireshark.org/CaptureSetup/USB.
  • Capturing USB does work through virtual machines if you're using USB forwarding.
• You need to set up a capture of USB packets to and from the keyboard- then run the NuPhy Console and press "Write."

I documented the interaction between the NuPhy Console and the Air75 in this file: https://github.com/donn/nudelta/blob/main/util/usb/docs.md. What it boils down to is an exchange of "USB reports": basically the computer requests something with a specific report ID (part of it is technically an offset but don't worry about that) and the keyboard replies. See https://www.usb.org/hid for technical details if you're into that.

The following parts may be different for Halo75 (but not likely):

For Air75, there are three reports read and three corresponding reports written (same general data), one of which I identified to be the keymap. The other two I assume are RGB and Macros, but I'm unsure. There's a lot of guesswork. I had to guess which one is the keymap by just basically changing the keys around a bit and seeing which one of the three reports changes. You'll find some of the scripts I used to help with that in https://github.com/donn/nudelta/tree/main/util/usb.

-- I found the Mac keymap via total guesswork, by the way, as that's not supported in the Nudelta console. I just kept changing the report ID until I found it.

The keymaps are essentially 1024 byte files containing of 256 4-byte keycodes: See https://github.com/donn/nudelta/tree/main/res for YAML files representing this data. This is the core target of my reverse engineering. You need the following pieces of data:

• The default keymap: i.e. just the binary keymap of the keyboard after a factory reset
• Indices: Where each physical key (or Fn-layer key) resides in the keymap. As far as I can tell right now, there are a few keys in the Fn layer with their own index, but not all of them.
• Keycodes: A piece of data sent by the keyboard to the computer when a key is pressed, which the keyboard's driver on the computer is then responsible for translating into a software keypress.
  • Modifiers: Something cool nudelta did is that most keys have a dedicated byte just for modifiers: Ctrl, Alt, Meta and Shift, so any key can be assigned modifiers to be sent along with it.

I have a whole section on keycodes and modifiers in https://github.com/donn/nudelta/blob/main/util/usb/docs.md.

What Nudelta's job is, essentially, to be able to generate the write report for a given keymap and write it to the keyboard using the hidapi library, which simplifies reading and writing to HID devices such as the NuPhy Air75.

And well, to support another keyboard? We'd need that same data: keymap report IDs (for both win and mac modes), default keymaps, indices, keycodes and modifiers.

---

Sorry for the wall of text- this is what happens when I have a presentation to procrastinate. But yeah. Hope that helps. Me personally, I have no plans to buy a Halo75, so I can't do this myself. :slightly_smiling_face:

[nocturne1]

It seems that they haven't even released a Windows console yet for Halo75, so we're delayed until well after that happens. While we wait, has anyone had success getting USB passthrough working for they keyboard on a Mac? I've tried both Virtualbox and VMWare Fusion, without any luck. Trying to get at least that part out of the way, to potentially help later.

[donn]

@nocturne1 I used USB passthrough for the Air75 on Linux with Virt-Manager for this particular effort.

One annoying aspect is that the keyboard "reboots" when you're trying to upgrade the firmware (and changes device name), so you'll have to pass it through again. But otherwise it should work fine..?

[ijverig]

Thanks a lot @donn for the detailed writeup and explanations. My keyboard hasn't arrived yet, so will wait for it and for NuConsole's update (they told me it's happening soon).

Hope I can soon help!

[donn]

Alpha Halo75 support should be in the latest release- can you all try it?

[ijverig]

Mine has just arrived. Will test it today and get back here.

Your alpha code is in the main branch, correct?

Seems to me you abstracted the code but the underlying communication is the same for both the Air75 and Halo75, right?

[donn]

@ijverig Pretty much- the only difference between the two is the keymaps.

[donn]

Finalized in 0.6.4. Welcome Halo75