Long arms for those of us with short arms from birth or those who can't afford arm extension surgery!
These are instructions and firmware for a relatively cheap off-the-shelf macro keyboard off AliExpress/Amazon (that has many copies/clones) to control a comma three running openpilot from an accessible and comfortable driver's position.
No more this and reaching out when you want to bookmark a segment or toggle experimental mode:
The macro keyboard we will be using look like this and come in this configuration:
The default configuration software and firmware on these kinds of keyboards is notoriously bad, sketchy in origin, and may not be trustworthy. Most importantly, it won't work for our use case where we need to send touchscreen input. So, don't bother downloading and don't install the configuration software. We will be throwing it all out.
Instead, we flash the keyboard's microprocessor to pretend to be a USB touchscreen digitizer, and the buttons to send touch events to the comma three. The new firmware touch areas are currently hardcoded to the bottom left corner for bookmark, the center for hide/show menu, and the top right corner for experimental mode toggling. The knob is used to control the LEDs to be a "lamp" light for night driving use and pressing down on it is an alternative button for the top right corner button pressing.
These keyboards are built arount the CH552G microcontroller. By shorting two pins together on initial power, the keyboard can be put into bootloader mode, and the new touchscreen-emulation firmware can then be flashed over USB.
Restoring the original vendor firmware is not possible without the original vendor firmware which I haven't been able to find yet. That said, somewhat similar functional firmware to the original functionality without the sketchy vendor software can be found here if you want to "reverse" the process and restore the keyboard to something like its original functionality:
https://github.com/biemster/3keys_1knob
Cost: Expect the cost to be about $3-20 for the keyboard, $2-10 for the male USB-C to female USB-A adapter, and an optional $6-10 for nicities like 90 degree USB-C angle adapters for a cleaner look. You may also need a USB-C extension cable. The rest of the materials you probably have lying around. The cost can be $14 to $40 depending on how long you want to wait for the materials to arrive from AliExpress, if you're in a hurry and want to buy from Amazon, or how clean you want the install to look.
A specific type of mass-produced macro keyboard with a CH552G microcontroller. The one this project supports and what I used was this:
-
https://www.aliexpress.us/item/3256806441586710.html
- Note that sometimes these keyboards are on sale for $5 from vendors.
- https://www.aliexpress.us/item/3256806441586710.html
-
Go for AliExpress if you want to save money and don't mind waiting. Go for Amazon if you want it faster and have Prime.
As there are many vendors of this keyboard, there is no steady name other than a similar look, so keep an eye for these traits when looking for an equivalent keyboard:
- Looks like the keyboard in those links I have above.
- Shows up when you search for "3 keys 1 knob keyboard"
- 3 keys in a row
- 1 knob, metal-looking usually
- Acryllic layered construction with rounded corners
- Exposed screws heads on bottom and top
- Multi-color LEDs
- USB-C is offset a bit torwards the knob side of the keyboard and not in the center.
- Comes with a male USB-A to male USB-C cable
- No wireless.
- Has a black or white variant. Color doesn't matter, choose your preference.
These will usually guarantee you get a keyboard with the CH552G microcontroller present in the manner we need.
Unfortunately, the keyboard is not perfect. It is missing two resistors in it that allow it to be powered by a USB-C port in a USB-C to USB-C setup. However, we need to power it from the comma three's USB-C port. While it is theoretically possible to solder in the right resistors, it is easier to just use a cable to convert the comma three USB-C port to a USB-A port. The longer, the better and here are some examples:
These are optional, but they help reduce cable strain on the cable at the comma three's USB-C port and clean up the cables in the area with the keyboard attached to your car.
- https://amzn.to/3U3WtSu - This is a pack of 5 adapters with 3 of them being useful to get the angles right to reduce strain and clean up the cables.
- https://www.aliexpress.us/item/3256805061903701.html
- Purchase "Color": 1, 4, 5
This is optional. Without it, the setup barely fits in my Corolla. If you got the 5 pack of adapters from Amazon above, there's a female to female adapter you can use to extend the cable with a male USB-C to male USB-C cable alternatively if you'll like.
Search on Amazon or AliExpress for "USB-C extension cable".
You can attach the keyboard to your car however you like. I used large 3M Command Picture Hanging Strips to attach the keyboard in front of my gear shifter. They are strong enough to hold the keyboard in place and can be fully removed without damaging the car. The strips are also velcro-like so you can remove the keyboard to change it or reprogram it away from the car without disturbing the tape too.
Of course, you can use whatever else you like for mounting.
AliExpress has command strip-like products as well, but I haven't tried them yet:
https://www.aliexpress.us/w/wholesale-3m-command-picture-hanging-strips.html
You'll need to short two pins on the CH552G microcontroller to put it into bootloader mode. You can do this with a paperclip or a metal conductor, but it is easier to do with test hooks.
- A paperclip or metal conductor to short the pins on some chip on the off-the-shelf keyboard for the initial flashing.
- Steady hands or tape or whatever to mask off pins that aren't to be shorted together.
- Or YOLO it and short the pins with a paperclip or metal conductor with no tape. Good luck!
You can use these hooks to precisely clip onto the pins to and then connect the two hooks of the pins to short them together. This is useful if you have shaky hands or need to do this multiple times.
https://www.aliexpress.us/item/3256805244460946.html - Get the 2pcs male option.
You will need to use Zadig to make the device when it is in bootloader mode available to flashing software.
- Download Zadig from https://zadig.akeo.ie/
- Run Zadig
- Under devices, select
Create New Device. - Fill in three fields. The first field is just a description and you can fill in anything. The next two fields are very important. Fill them in with 4348 and 55e0 respectively. Press "Install Driver" and give it a few minutes to install.
- Disassemble the keyboard. There are 4 screws on the back of the keyboard.
- Unscrew them and take off the bottom. There will be an acrylic cut out. You will see the
CH552Gmicrocontroller. - Take out the acrylic cut out so you have a bit more space
- Short these two pins on the
CH552Gmicrocontroller. Technical info: These pull USB D+ up to 3.3V from the chip's 3.3V supply. -
- While these two pins are shorted together, plug the keyboard into your computer.
- Download the
touch.hexfirmware to be flashed from the GitHub Releases page. - Connect the macro keyboard to your computer with the USB-C to USB-A cable while shorting the pins to have it in bootloader mode.
- Visit https://www.stephenkingston.net/CH55x-WebProgrammer/
- Press Connect
- Select the device with "
WinChipHead" in the name from the dropdown. - Drop the
.hexfile into the web page and it'll flash.
Put it back together, screw it down, and you're done!
Connect the keyboard to the comma three and test the buttons and knob. Start the car, with the engine not running. The bottom left corner should bookmark, the center should hide/show the side menu, and the top right corner should toggle experimental mode (if available). The knob should control the LEDs and pressing down on the knob should act as an alternative button for the top right corner.
Pretend it's like a dashcam install, which you should have done with the comma three. Use the mounting tape to attach the keyboard to a convenient location. I put mine in front of the gear shifter. Connect the cables. Use the right angle adapters to clean up the cable routing, reduce strain on the comma three's USB-C port and minimize any weird blocking of the cameras or interior.
I ran my cable down the passenger side A pillar under the trim.
If you ever need to update the firmware with the new firmware, the old firmware can be put into bootloader mode by holding the key furthest away from the knob while plugging it into the computer. All the LEDs should light up in full white when this is done. The new firmware can then be flashed without shorting the pins using the web flasher.
See the Makefile and try to get make flash going. You'll need sdcc, Python with pyusb, and build tools.
This firmware is based on the work of the following projects:
- https://github.com/biemster/3keys_1knob/ - Showed me the possibility of flashing these keyboards and some implementation reference.
- https://github.com/wagiminator/MCU-Templates - the basis for
3keys_1knoband a good reference for clean CH55X code.
CC-BY-SA 3.0 as it is mostly based on https://github.com/wagiminator/MCU-Templates/blob/main/CH552/LICENSE . See LICENSE.md for more details.