Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
State of the Analog SDK #14
There’s a lot happening in the Analog keyboard world. Outside of Wooting there’s a new player on the market and there are rumours of even more coming. Wooting’s goal is to make that analog doesn’t go the way as RGB for games did, a painfully divided closed system.
This Analog SDK should be the answer towards a simple, compatible solution. Sadly I feel like the current state of the analog SDK is not able to provide this, so I want to start a discussion about how we can make it better.
Goal of the Analog SDK
The analog SDK wants to be as close as possible to an ideal USB driver. It’s important to distinguish between a user side (somebody that buys an analog keyboard) and application side (the developer that adds code to support analog keyboard in an application).
Ideally a user should be able to buy an analog keyboard, plug it in and be done with it. Drivers will be installed automatically. Once the user enters an application it will just follow normal keyboard mappings, but there’s analog support.
On the developer side it should work like interfacing with a normal keyboard with an analog edge. After an analog keyboard is detected the API can mirror how it works in most applications:
Why not just develop a USB driver?
USB driver are notoriously hard to develop. It requires deep understanding of the OS and even if you down one, you have two other to go. Besides that having plug and play install requires certification for every USB device. This hurts adaption, especially for smaller / community sized keyboard makers.
Requirements of the Analog SDK
Can the current way fit the requirements?
Currently the SDK builds to a DLL which a developer adds to the application. This makes the developer responsible to keep up to date with new devices and/or new updates to the SDK.
We could make it possible to improve the current way and add better interfacing and read custom key codes. Requirement 3 could even be met by having some separate device database. That adds a whole new layer of complications though.
What else can we do?
Making the developer responsible can really hurt adoption. We’re already asking developers to add support for our SDK, so we should make it as easy as possible for them.
I think we should move to the user installing the SDK. The install can be part of the configuration software of the keyboard vendor and/or a separate install.
Making this move also allows us to reconsider how we want the SDK to look like. I think we should revisit the concept and design a new system that will fit all the requirements.
I think I’ve written enough for now. I’ll come back with a definition of the firmware side, specifically for requirement 4. The current DLL setup just feels like it’s missing the mark now and I’m very curious what your suggestions are.
In short I think that the hardware layer has to be separated from the analog interface at all. Now the interface is only capable of using the vendor id and product id from wooting. I think the best way should be to have a unique identifier that it is not vendor or product based.
I would prefer a special HID usage and usage page code for this along with a standardised report. So the interfaces can see every product that are offer this. Additional the interface has to be capable of handling multiple devices that are connected.
With that a other vendor has just to offer the same HID Descriptor and a vaild Report for the interface like any generic mouse, keyboard or joystick / gamepad are handling it today. Later the report can be different through vendors as long the interface would be updated for newer report types. So write an interface that scans only for a special usage and usage page and interpret the report from it.
To have a special standardised usage and usage page for it, it would be maybe the best to claim one from the USB Implementers Forum, I guess.
This would be a really big step to unify all analog keyboards and create a standardised interface for all.
But in order to make this real you have to talk to the other vendors so all parties agree with that. Otherwise it would be a standard which no one uses it...
With that I have in mind there are no back services. The new Analog SDK would be just an interface like Direct Input from Mirosoft. It would scan for the special usage and usage page, would scan the report from it and would listen to the data that is send from the device. Everytime it would receive data it would update an internal structur that other programs can read from it. So even when other vendors creates a new / different report for it, the interface has just be updated for this to interpret it correctly.
Like Direct Input from Microsoft, this interface just reads the reports for joysticks and gamepads (usage page "Generic Desktop" and usage "Joystick") and interpret the report so it's regardless if the joystick send only positive values or negatives too, or sends 8 bit values or 12 bit ones. The output will be always between 0 and 65536 there the center is 32767.
This defines a real travel range from 1.5 mm to 3.6 mm where the value zero is below 1.5 mm, one is at 1.5 mm, two hundred fifty four is at 3.6 mm and two hundred fifty five is above 3.6 mm.
I think we have already covered this in Discord, but I will repeat it here for completeness.
I wrote Scancode and not Keycode, so there is the problem? But if you mean for the currect SDK I agree with you :-)
And the language of the keyboard doesn't matter in my opinion. Windows translate it for the normal keyboard, so it would be the same here. The application has to check if a Scancode is a "Y" or a "Z", or a "Q" or a "A". The keyboard itself don't has to deal with the layout, you have to set the layout in Windows or the application itself. Because maybe you have an english ISO but want to act it as a german layout, because you change the keycaps.
This is incorrect / ambiguous.
Wrt disabling the analog API while in password boxes, I do agree that is a potentially scary attack vector however.
I agree it is problematic but at least more elegant than now, because the problem exist now too. A killswitch (special mode or key) would be a good idea to toggle the analog mode.
But if there is a special usage for an analog keyboard in the future the operation systems would know about it and it can handle it the way like a normal one. The main goal is to have an analog keyboard in the future just like a normal one. But in order to achieve this there has to be a standard. Think about it if every vendor has to carry about this his own way, this would be terrible.
I don't think we need something running in the background, as long as there is a clear install path an application (or our own interface application) can find.
@Rocky04 Even though I agree with that a special usage page is the best solution, it is out of reach for us for now. Even just being part of the USB elite club is thousands of dollars. I would much rather start in a "hacking" way and demonstrate interest first. What's the use of setting up a complicated system if nobody uses it?
Plus even if we set up a custom report, we need to write the software to parse the reports on the PC side anyway.
We do need to setup a standard on how to define and use USB reports, I would just use as much out-of-the-box as possible. We could use a customer usage page in the FFxx range, but then we risk opening other devices. Maybe we can combine it with an enumeration, which we can also use to ask for analog device information.
@evilC Yes definitely, that's one of the first things to change in the API. It's what I meant with that example, use a standard keycode, same way as any game engine does it. I'm still thinking how to handle custom keys though.
I don't see that we need USB-IF membership, and we don't need a "logo" option (I don't even remember seeing a USB logo on your packaging), so we surely just need a one off VID or PID allocation.
The way that browsers implement this at the moment is that all the "code" values are tied to the QWERTY layout, and the "key" values are tied to the keyboard layout on the OS. E.g. If I had a QWERTY keyboard but had DVORAK as the layout in my OS and then hit the physical Q key, the "key" value would be ' and the "code" value would be KeyQ.
Basically, you can pay $5000 (soon to be $6000) for a VID.
Reference: I got Input Club setup with a VID last year so we could have as many PIDs as we want.
Thanks for the input @haata. In general I think we shouldn't reach for the maximum straight away and prove there's interest for it first. Make something good, prove that games and users want it, then do it perfect.
Ideally we combine it by designing the SDK in a way to will allow it to grow into a standard that follows USB standards.