Unicomp's RP2040/Pico controller purchasing & Vial-QMK guide

For many years, enthusiasts have been asking for reprogrammable Model M keyboards from Unicomp. Thanks to the unfortunate 2022 discontinuation of the Cypress microcontroller Unicomp previously used for its USB keyboards, Unicomp keyboards are now [mostly] reflashable thanks to their selection of the RP2040-based Raspberry Pi Pico as the heart of its new generation of USB controller cards. Members of the /r/ModelM subreddit and Discord community led quick documentation and utilisation of these new controller cards, which has resulted in Vial-QMK firmware being ported during May and June 2023! This ASK Guide will provide background on why Unicomp has finally changed its controller design, how you can get your hands on them for your existing Unicomp keyboard(s), and how to reflash the new controller cards with Vial-QMK.

Special thanks to Purdea Andrei (aka, purdeaandrei or /u/_pandrew) for all their effort in porting Vial-QMK to these new Unicomp controllers and for their assistance in writing this guide! Also thanks to /u/DoublePlusGood23 for their assistance to Purdea and /u/plazman30 for their contributions to the community during this time.

Contents

Background

Until 2023, Unicomp's controller cards for their USB keyboards used Cypress chips such as the common CY8C24493-24 programmable embedded system-on-chip that Unicomp's immediate predecessor controller cards used. The two previous controller cards that used this chip were Unicomp's Ruffian and "AP1". The Ruffian (named after a '70s Kentucky racehorse^[1][1]
Wikipedia - Ruffian (horse) [accessed 2023-06-18].) was intended for all major Unicomp keyboards that require pressure-fit connection to the membrane assembly and has been in production for many years. "AP1" was specifically designed for the Mini M and was introduced in 2021 alongside it.

Whilst these old Cypress chips were functional for standard keyboard usage, there were several reasons why custom keyboard firmware (such as Vial-QMK) was never developed for or ported for them as described by Purdea for the most recent Cypress chips:

This chip was recently discontinued^[2][2]
Radionics Ltd. - Cypress Semiconductor CY8C24493-24LTXI, CMOS System-On-Chip for USB, 48-Pin QFN [accessed 2023-02-21]., prompting Unicomp to redesign all of its USB controllers. Unicomp settled on using Raspberry Pi Picos (powered by the modern RP2040 microcontroller) due to their affordability and widespread availability. But this also opened up opportunities for reprogramming and modding. The two new Unicomp controller cards are Aristides as a replacement for Ruffian and Justify/Mike Smith as a replacement for "AP1".

Aristides (in keeping with Unicomp's PCB naming convention) is named after the racehorse that won the first Kentucky Derby in 1875^[3][3]
Wikipedia - Aristides (horse) [accessed 2023-06-18]. and is intended for 101-105 key and 122-key keyboards that require pressure-fit connection to their membrane assemblies. Justify is named after the thirteenth winner of the American Triple Crown^[4][4]
Wikipedia - Justify (horse) [accessed 2023-06-18]. and serves as the motherboard of the new Mini M controller card supporting the Pico, two 74LVC138AD demultiplexers (under the daughterboard), right Triomate (membrane flex cable) socket and USB port. Mike Justify is named after the jockey that rode Justify to the Triple Crown^[5][5]
Wikipedia - Mike E. Smith [accessed 2023-06-18]. and is a daughterboard attached to Justify that has the left Triomate socket and four LVC125A quadruple bus buffer gates.

How to get them

As of June 2023, all consumer Unicomp keyboards except the EnduraPro (which hasn't returned to sale) ship with Aristides controller cards and all Mini Ms shipping to locations in the U.S. ship with Justify/Mike Smith controller cards. Mini Ms being shipped internationally are currently shipping with reserves of the older "AP1" controller cards, but international customers should be able to contact Unicomp before ordering to request the "new Mini M logic card with Pico" with some conditions. If you already own old Unicomp keyboards, it may be possible to upgrade them by fitting in these new controller cards yourself depending on model and era.

Compatibility with older keyboards

All current Mini Ms are capable of using the Justify/Mike Smith controller card. You should not need to worry about compatibility with those. For other Unicomp keyboards and Aristides, there are some general rules of thumb regarding compatibility:

There may be edge cases not considered above, so it's recommended that you check if your keyboard is compatible yourself regardless. You can do this by opening up the keyboard to check three things:

Controller card style

You can quickly dismiss incompatible keyboards by looking at the style of controller card present. If your keyboard is not a Mini M and it has a controller card located underneath the keyboard assembly and/or has two long black sockets for the membrane flex cables, it will not be compatible. Whilst that style of controller card is primarily associated with early IBM and Lexmark made keyboards, some early Unicomp keyboards still used that controller card style. If your keyboard has a pressure-fit controller card fitted on the top-right corner of the keyboard assembly (aka, "overnumpad style"), it may be compatible. You may move to the next point to check, but generally, controller cards of this style that have IBM or Lexmark markings are not compatible as well.

Thick membrane trace contacts

To further confirm compatibility, you can remove the controller card to observe the membrane assembly's contacts. The controller card is usually screwed on modern Unicomp keyboards, though some older Unicomp keyboards may still simply sit guided by two plastic stalks and clipped in from the left-hand side like their IBM/Lexmark era 42H1292-style basis. Once removed, you can look at the contact traces as shown in the first photo above to see:

zhinu20230709DonatedPhoto

For context, these thick traces are used for passing key-matrix row signals from the one membrane layer to the other that makes contact with the controller card. Aristides has an I/O limitation that requires the row pins to be where they are on current Unicomp keyboards.

Hole sizes

The final thing to check would be the diameter of the mounting holes near the bottom of the controller card. Originally, Unicomp inherited 3.2mm-sized holes from the IBM/Lexmark 42H1292-style controller card, but at some point, they enlarged the holes to 4.3mm. The Aristides controller card is only available with 4.3mm holes. This means that the controller card will be unable to secure properly on older keyboards. Whilst your keyboard's membrane assembly may yet still be compatible with the new controller card, you would need to get creative to design your own way of securing the Aristides.

Can I make my incompatible keyboard compatible?

For Unicomp keyboards (or IBM/Lexmark Model Ms such as P/N 42H1292 with overnumpad-style controllers) that aren't compatible with Aristides, the only way to make them compatible would be to also replace the membrane assembly with a brand-new one from Unicomp. For old 104/105 keyboards with pre-2013 bottom row style, you may also need to purchase a new barrel plate (frame as per Unicomp's terminology) and keycaps to compensate for the difference between it and modern Unicomp 104/105 key keyboards. Regardless, this would require a bolt mod to replace the rivets after you've removed them to access the membrane assembly. As such, it's advisable to use a different replacement controller card such as Purdea's OverNumpad Controller instead.

Purchasing

Once you've decided to purchase one of the controller cards for your keyboard, you can do so by ordering two Customization Fee on Unicomp's website and provide the applicable comment as the following:

(Unicomps Classic, Ultra Classic and New Model M share the same controller card and default firmware)

As of June 2023, the total price will be $24 USD + shipping. It's still advisable to contact Unicomp before ordering to make sure they have stock and that the ordering process hasn't changed.

Backing-up original firmware

Whilst not strictly necessary, you may want to save a copy of the original closed-source firmware so you can restore your keyboard's controller to factory settings. You can do this with the official Raspberry Pi Foundation's picotool. You will need to compile picotool yourself on Linux, but for Windows, Purdea has precompiled picotool for you and listed some prerequisites to install. For macOS, you can either compile picotool yourself or install Homebrew then run brew install picotool.

Once you have picotool compiled or downloaded, you can run the following command to dump the Pico's current firmware:

Windows/macOS

Linux

For Linux, you may need to run the command with sudo.

Downloading & flashing Vial-QMK

Purdea's Vial-QMK firmware is available from his GitHub repositories as .uf2 (USB Flashing Format) binary files. UF2 is a file format developed by Microsoft specifically for flashing microcontrollers easily.

For Aristides (101-122 key)

For the new controller card for Unicomp 101-122 key keyboards, you need to download firmware from the vial-qmk-overnumpad-and-aristides-2862 repository. Click "Releases" then click the latest release, then download the _aristides_2862_vial.uf2 file that matches your keyboard.

Note that unicomp_classic_ultracl_post_2013_aristides_2862_vial.uf2 is also applicable for Unicomp New Model M keyboards as well as Classics and Ultra Classics.

For Justify/Mike Smith (Mini M)

For the new controller card for Unicomp Mini M keyboards, you need to download firmware from the vial-qmk-mini-m repository. Click "Releases" then click the latest release, and you can download either:

Flashing

To flash your keyboard's controller card, you will need to follow the standard Raspberry Pi Pico flashing procedure. You will need to disconnect your keyboard and open it up to access the controller card. You will then need to hold the "BOOTSEL" button down whilst you reconnect the keyboard, which will put the Pico into USB mass storage device mode and your PC's operating system should then detect the Pico as if it was a 128MB USB flash or hard drive.

Then all you need to do is copy and paste the relevant .uf2 file into the new storage drive and the Pico should take care of the rest. You should then be able to use Vial to detect the keyboard and begin customising your layout. You can download or access Vial from:

Summary

We have entered an exciting new era where new Unicomp keyboards are natively compatible with supporting popular keyboard firmware such as Vial-QMK. It's also possible to retrofit some existing Unicomp keyboards with this new capability as well for just $24 plus shipping. If you think anything needs to be further clarified, feel free to contact me. If you have any problems or want further advice, also feel free to make a post on /r/ModelM or join our Discord server!

Further reading & resources

External

Sources

ASK. Admiral Shark's Keyboards original content. License/note: CC BY-NC-SA 4.0.