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 looks like this and comes 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 that all out.
Instead, we are flashing 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 slight-left of 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.
On some forks such as FrogPilot, the keyboard can also be used to press optional on-screen widgets such as distance adjustment which happens to also be in the bottom-left. This useful for vehicles lacking equivalent physical buttons such as Non-ACC Bolts or Volts. Traffic Mode in FrogPilot can also be activated by a long touch and as this keyboard can faithfully translate touch down and touch up from button presses down and button presses up, the keyboard can do that too.
These keyboards are built around the CH552G microcontroller. By shorting two pads together on initial power, the keyboard can be put into bootloader mode, and the new touchscreen-emulation firmware can then be flashed over USB. It is very easy to take apart the keyboard and to short these two pads.
Restoring the original vendor firmware is not possible without the original manufacturer's firmware which I haven't been able to find yet. That said, somewhat similar functional firmwares 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 as a macro keyboard:
- https://github.com/biemster/3keys_1knob
- https://github.com/eccherda/ch552g_mini_keyboard/
- https://github.com/semickolon/fak (This one is pretty hardcore!)
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.
- A link to a sketchy file hosting site for configuration software, "email us for software" call to action, or even no instruction
- Has a black or white variant. Color doesn't matter, choose your preference.
- Tends to come with red switches
These will usually guarantee you get a keyboard with the CH552G microcontroller present in the manner we need.
The keyboard will also come with a 1 meter long male USB-A to male USB-C cable.
It is a mechanical keyboard! You can replace the stock red switches with whatever you like along with the keycaps. Tactile or clickly switch replacement is popular. Keycaps/Switches are also sold on Amazon, AliExpress, and wherever you want to buy them. You might spend more on switches and keycaps than the keyboard.
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
Some tape can be helpful in covering up stuff you don't want to short out on the keyboard. This is optional.
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.
If you still have issues, try other machines, Macs, Linux machines, Chromebooks, or even an Android phone.
You will need to create a udev rule to allow your user account to access the device when it is in bootloader mode.
- Open a terminal and enter the following commands to create the udev rule:
sudo tee /etc/udev/rules.d/50-ch552-flash.rules <<EOF
# CH552G Bootloader
SUBSYSTEMS=="usb", ATTRS{idVendor}=="4348", ATTRS{idProduct}=="55e0", GROUP="plugdev", MODE="0666"
EOF- Reload the udev rules:
sudo udevadm control --reload-rules- Ensure your user account is part of the
plugdevgroup:
sudo usermod -a -G plugdev $USER- Log out and log back in for the group change to take effect.
You can flash from an Android device too. No special instructions are needed but things are a tad less visible.
No special instructions are needed. macOS readily makes USB devices available to Chromium browsers with no permissions required.
- Prepare the cable from your computer or phone to the keyboard. Make sure that you have a female USB-A port coming out of your computer or phone from which you can plug in the keyboard's included male USB-A to USB-C cable. Without this, the keyboard will not power on. You should have these materials from the Bill of Materials section.
- Put the USB-C end of that setup next to the keyboard.
- Disassemble the bottom of the keyboard. There are 4 screws on the back of the keyboard. Keep one of the screws handy for the next steps.
- 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
- Put the keyboard on its back atop a soft surface like a mousepad or a towel.
- Ensure you can can see
R12resistor pad. - If you'll like, you can also tape up the other pads and components around the
R12resistor pad to prevent shorting them out. This is optional. - Using one of the 4 screws you unscrewed from the bottom, put the screw's head atop where the
R12resistor would have been. See these photos as a reference:
- My pushing position
- Another user's pushing. They chose to tape up the other unrelated components/pads for extra safety.
- Push the screw down hard so the keyboard isn't moving atop the soft surface.
- While the
R12pads are shorted together, plug the USB-C cable into the keyboard. - Remove the shorting screw after the keyboard is plugged in.
- Check if the keyboard shows up in Device Manager as a
WinChipHeadorCH552or whatever device you've named it as in Zadig. On Linux, uselsusbto check for aWinChipHeaddevice. On macOS, open theSystem Informationapp and check the USB section. You can check on Android by visiting the web flasher at https://www.stephenkingston.net/CH55x-WebProgrammer/ and pressing Connect.
The steps above may be tricky, and you may need to do it a few times.
After the keyboard is in bootloader mode, you can flash the firmware.
- Switch to a Chromium-based browser on your computer or phone.
- Download the
touch.hexfirmware to be flashed from the GitHub Releases page. - Visit https://www.stephenkingston.net/CH55x-WebProgrammer/ . If you're on Android, you were already there.
- Press Connect
- Select the device with "Unknown device [4348:55e0]" or "
WinChipHead" or similar in the name from the dropdown.- If you don't see your device, try again with getting the device into bootloader mode.
- Once connected, you should see a message about a "Bootloader Version".
- Press Upload and select the
.hexfile from the file picker or drop the.hexfile into the web page and it'll immediately start flashing. - Once it's done flashing, you should notice that pressing the keys now causes a light to light up on the keyboard.
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.
Put it back together, screw it down, and you're done!
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.
With switch replacements
PXL_20240426_205602199.mp4
On a Chevy Bolt. Custom Keycaps and "Holy Panda" switches.
On a Chevy Volt.
This is my installation, but you should adjust it to your needs.
graph TD
A[comma three's port 2] --> B
B[Straight USB-C Male to Female USB-A] --> C
C[Angle and Twisted USB-C Male to USB-C Female Adapter] --> D
D[Male USB-C to Female USB-A Cable] --> E
E["(Came with Keyboard) Male-USB-A to Male USB-C Cable"] --> F
F[Angled Female USB-C to Male USB-C adapter] --> G
E --> H
H["(Optional) Male USB-C to Female USB-C Extension Cable"] --> F
C --> I
I["(Optional) Male USB-C to Female USB-C Extension Cable"] --> D
G[Keyboard]
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.
- There is iffy support in Windows. Testing the keyboard on Windows may yield weird behaviors but as it is not the target of this project, those bugs are left as-is. Bugs may include touch-down and touch-up emulation. It is best to test on a Linux-based device.
- Do not disconnect the keyboard during normal operation. The C3 itself may crash or kernel panic. It's unknown what causes this but touchscreen hot-removal in the C3 OS and environment might not be as well tested. As this is not a normal thing to do, this is left as-is.
See the Makefile and try to get make flash going. You'll need sdcc, Python with pyusb, and build tools.
sudo libinput debug-events is your friend. You may need to apt update -y and apt install -y libinput-tools to get it.
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. - https://github.com/eccherda/ch552g_mini_keyboard/blob/master/readme.md#setting-up-the-keyboard-in-bootloader-mode - Bootloader mode instructions about the R12 resistor pad come from there
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.