For those not already aware, I’ve been working on a straightforward protocol that you can use to control the Keyglove. This (or at least the initial version of it) is now complete. This Keyglove API, or “KGAPI”, is made up of the following basic types of communication:
- Commands: sent to the Keyglove to make stuff happen
- Responses: sent back from the Keyglove after commands are sent, acknowledging or reporting errors
- Events: sent from the Keyglove when things happen that aren’t directly triggered by commands, such as touch sensor changes or new motion data
This is the same kind of structure that you will find in many protocols used by hardware peripherals, so there’s nothing particularly special here.
However, one important point to mention is that while you can use the KGAPI protocol from an external device like the PC to which you’ve connected the Keyglove, you can also use exactly the same “vocabulary” of commands, responses, and events right in your custom application code in the firmware. This gives you a lot of power and flexibility that you won’t find in other similar devices; rather than just making external control possible, the Keyglove implementation makes it as easy and intuitive as possible to tweak the firmware itself (remember application.h?), even going so far as to use the same command names, parameters, etc.
What does this mean practically? Let’s say that you write a Python script which talks to the Keyglove using KGAPI, and handles the “touch_status” event (which happens whenever any touch sensor changes state), and inside that event handler you use the “motion_set_mode” command to turn on and off the motion sensor based on the touch status. Rather than making the PC do that work, you could use the exact same set of commands and events to make that behavior part of the firmware itself.
You could further offload basically anything from the PC onto the Keyglove itself–touch interpretation, motion processing, Bluetooth connection automation, feedback, you name it–so the only thing the connected host sees is the actual control signals over the human input device (HID) interface. This is in fact how I assume many people will want to use the Keyglove, but this alone is too limiting. Not everyone has the same implementation vision as I do, and I want to empower as many different use cases as I possibly can with this platform. My last visit to Maker Faire powerfully communicated the importance of that goal to me, and now, it has become a reality.
Another feature worth mentioning is the ability to extend the KGAPI protocol with your own commands, responses, and events if desired. This is more than most people will want to mess with, probably, but for those who do, I’ve made every effort to make it easy. You can find reference code and comments in the custom_protocol.h file.
I am still working on a KGAPI reference manual, but it isn’t quite ready yet. It’s coming along, but it’s still too bare. In the meantime, the previously linked documentation includes descriptions for all of the commands (functions beginning with “kg_cmd_…“), and there is a handy reference file for all of the possible event handlers you might need (the application_stubs.h file).
I also have a Python implementation of the whole API including a parser and a few test scripts, and I am working on a simple cross-platform graphical testing application, also written in Python and using the wxPython GUI toolkit:
This will be published as soon as I consider it to be stable. There are only a few fixes and additions remaining before it will reach that point. However, the core KGLib parser library and a console-based test script are already available on the Github repo.
The API itself is fundamentally defined in its entirety in JSON format, which should make it as easy as possible to work with the protocol and integrate in any way you choose into custom host applications.
Leave a Reply