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 controller cards and for their assistance in writing this guide! Also thanks to /u/DoublePlusGood23 for their assistance to Purdea, /u/plazman30 for their contributions to the community during this time, and to Deskthority users feltel, jsheradin and NathanA for sharing their experiences with the community after this guide was released and enabled me to improve some content.

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 who 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 do I find out if my new Unicomp already has one?

If you bought a brand-new Unicomp Model M (or bought one second-hand that was made) in June 2023 or after, you may be wondering if you already have a Pico-based controller card. Besides simply opening the keyboard, there are a few ways you can tell what controller card you have if your keyboard is USB. If it's PS/2, then you will not be using one of the new controller cards.

The type of controller card can be determined by looking at the USB Device Name/Product String Descriptor (iProduct) your computer see:

Below is a table of known USB device/product strings you can refer to.

Compatibility with existing Unicomp Mini Ms

All current Unicomp Mini Model Ms are capable of using the Justify/Mike Smith controller card. The Mini M was a new keyboard design anyway, so Unicomp has yet to alter the membrane assembly or create unique variants that may have broken compatibility. As such, the Justify/Mike Smith controller card can serve as a straightforward drop-in replacement for the old "AP1" controller.

Compatibility with existing 101 to 122 key Model Ms

For keyboards other than the Unicomp Mini Model M, compatibility for the new 101 to 122-key controller card (Aristides) is nuanced but there are some general rules of thumb you can follow:

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.

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 to see:

For context, these thick traces are used for passing key-matrix row signals from one membrane layer to the other layer 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 (or replace the barrel plate, as described in the Can I make my incompatible keyboard compatible? section).

Can I make my incompatible keyboard compatible?

For IBM, Lexmark or Unicomp Model Ms that aren't compatible with Aristides, the only way to make them fit and work correctly would be to also replace their membrane assembly and barrel plate ("frame" in Unicomp's terminology) with a brand-new one from Unicomp. There are some specific reasons behind also needing to replace the barrel plate:

For earlier Model Ms that didn't use "overnumpad style" controller cards at all, you will also need to take into consideration the fact the lock-light holes won't align and the cable holes are in different locations. On top of this, you will need to 'screw mod' or 'bolt mod' your keyboard to replace the rivets after you've removed them to access the membrane assembly. If you're not confident with such modification, it's advisable and easier to use a different replacement controller card such as Purdea's OverNumpad Controller for "overnumpad style" Model Ms. If you do wish to pursue such modification; since this guide was first published, Deskthority user jsheradin explained their process for getting an Aristides working with a 1996 Lexmark-made Model M (which will be apt for many early Unicomp 101/102 key keyboards) for those curious.

How to get them

As of September 2023, all consumer USB Unicomp keyboards except the EnduraPro (which hasn't returned to sale) seem to ship with the Aristides controller card regardless of the destination country. The Mini M is currently only shipping with the Justify/Mike Smith controller card as standard to locations within the United States. Mini Ms being shipped internationally are currently shipping with reserves of the older "AP1" controller card. When this guide was first written in June 2023, it was suggested it may be possible to request the "new Mini M logic card with Pico" with some conditions. In mid September 2023, Deskthority user feltel was told by Unicomp that Justify/Mike Smith controller card wasn't being shipped internationally to due import complications.

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 providing an applicable comment such as the following for the "Customization" text input box:

As documented by Deskthority user jsheradin, variants of this comment such as Pi Pico controller card for the New Model M should work and have been ordered successfully. You should not need to specify "Aristides" or "Justify/Mike Smith" in the ordering process. As of September 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.

How to fit them

Fitting Aristides

In the time since orders of the new controller card were first accepted, some concerns regarding whether the Aristides controller card can fit contemporary Unicomp keyboards that previously had Ruffian controller cards have been raised. In early September 2023, Deskthority user NathanA shared their experience struggling to fit an Aristides on a 2018 Unicomp Classic and a 2020 Unicomp Ultra Classic. They noticed the PCB has slightly increased in thickness.

Whilst the change in PCB thickness is observable (and the intent of the change unknown), Aristides was not intended to be incompatible with Ruffian keyboards. More [perhaps disconcerting] force is required to fit it. A possible technique for making fitting easier is:

Fitting Justify/Mike Smith

By comparison, there shouldn't be any fit concerns when replacing a Unicomp Mini Model M's "AP1" controller card with a Justify/Mike Smith controller card.

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. Firstly, 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

Corrections & changes

Sources

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