- Updated 14 September 2023
- Est. Reading Time: ~17-21 minutes
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.
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
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:
- There was no open-source toolchain available for those chips.
- Those chips don't have a built-in USB bootloader to facilitate easy firmware reflashing, thus you'd need specialist programming hardware to reflash them.
- QMK only supports 3 platforms (AVR, Chibios and Massdrop Ctrl) and neither of those includes Cypress support.
This chip was recently discontinued
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
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
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
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 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:
- On Windows 11, going to Settings > Bluetooth & devices > Devices should show the name of the keyboard. If you don't see a specific model name or only see "HID Keyboard Device" (or you're using an older version of Windows that doesn't have a convenient way to see the proper device name), NirSoft's USBDeview is a convenient tool to find this out. The
Device Namefield when looking at a USB device will tell you what you need.
- On Linux,
lsusbcan be used to find this out. Running the command without any parameters should be sufficient, but you may want to run
lsusb -vto get more information (in which case, look for the
- On macOS, System Profiler can be used to find this out. Alternatively, you should be able to find out running
ioreg -p IOUSB -l -w 0in Terminal as well.
Below is a table of known USB device/product strings you can refer to.
Indicates the value may be different based on the keyboard's layout or firmware revision.
|USB device/product string||Product - controller card (type)|
|AP1_4_8*k_Kbrd_v7_5*||Mini M - "AP1" (Cypress)|
|Aristides 2862||101-122-key - Aristides (Pico)|
|Mini M||Mini M - Justify/Mike Smith (Pico)|
|R*_*_10x_Kbrd_v*_*||101-122-key - Ruffian (Cypress)|
|Ruffian*_x Kbrd v*_xx||101-122-key - Ruffian (Cypress)|
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:
- Any Unicomp New Model M (the product, not new Model Ms in general) should support Aristides as (being released in 2020) they're new enough that there haven't been any major membrane assembly or barrel plate design changes that could break compatibility since then.
- Any post-2013* Unicomp 103, 104, 105 or 122 key keyboard should support Aristides (including keyboards originally configured as PS/2).
- Post-2013* Unicomp 101/102 key keyboards may support Aristides.
- Pre-2013* 104/105 key Unicomp SpaceSaver (old name for Ultra Classic) and SpaceSaver M keyboards should support Aristides.
- Pre-2013* 101/102 key Unicomp keyboards likely don't support Aristides.
- Any IBM or Lexmark branded 101/102 key keyboard regardless of year will not support Aristides.
*Pre and post 2013 refers to when in July 2013 Unicomp updated its bottom row of keys for 104/105 key keyboards and was believed to have implemented a subsequent membrane assembly design change for most of their then-current keyboards for consistency. Besides the date of manufacture, the easiest way to tell if your 104/105-key Unicomp keyboard is pre or post 2013 is to check if the left GUI (aka, Windows) key matches the size of any letter key (post-2013) or not (pre-2013).
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:
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.
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:
- If there are 8 contiguous thick traces visible on the right-hand side, your membrane assembly is compatible with the new controller card.
- If there are thick traces visible that aren't contiguous, your membrane assembly is not compatible with the new controller card.
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.
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:
- Even for early Unicomp keyboards and IBM/Lexmark P/N 42H1292 like "overnumpad style" keyboards, you may require a new barrel plate since the method in which the controller card is secured has changed - as aforementioned, the holes on the controller card used to be smaller, and they didn't used to be secured with screws.
- For 104/105 key Unicomp keyboards made before the new bottom row style was adopted (the pre-2013 keyboards), a new membrane assembly will not align correctly with the old layout. Thus, you'd need a new barrel plate and bottom-row keycaps.
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.
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:
Unicomps Classic, Ultra Classic and New Model M share the same controller card and default firmware, so either of those three names should be orderable and produce the same result.
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.
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:
- Open the keyboard.
- Unplug the keyboard cable from the existing controller card.
- Unscrew the existing controller card and lift it up from the top edge until it's easy to slide out from the barrel plate.
- Insert Aristides into the barrel plate and align one of the screw holes. The one closest to the keyboard edge seems to go in easier.
- Push the PCB down until roughly flat.
- Start screwing whilst holding the PCB in place. Eventually, the other side should align.
- Plug the keyboard cable back in.
- If you plan on flashing Vial-QMK right away, don't close the keyboard now since you will need access to the Raspberry Pi Pico's BOOTSEL button.
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.
- Open the keyboard.
- Gently slide the two membrane flex cables out of the "AP1"'s Triomate sockets. You may want to lift up the keyboard assembly and hold it at an angle where the membrane flex cables are more flat.
- Remove the two plastic caps on the plastic posts on either side of the USB port. You can use a flathead screwdriver for this, but a tack lifter would be ideal.
- Lift "AP1" out of the keyboard.
- Gently slide the two membrane flex cables into the Justify/Mike Smith's Triomate sockets. It may be easier to do this before you place the controller card down.
- Place Justify/Mike Smith down (taking care to align the plastic posts through the two holes on either side of the USB port) and (technically optional but recommended) place the two plastic caps back on.
- If you plan on flashing Vial-QMK right away, don't close the keyboard now since you will need access to the Raspberry Pi Pico's BOOTSEL button.
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:
For Linux, you may need to run the command with
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.
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:
unicomp_mini_m_justify_mike_smith_vial.uf2- standard firmware.
unicomp_mini_m_justify_mike_smith_vial_debug.uf2- debug firmware that allows you to monitor the matrix' status via PJRC's HID Listen.
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.
If you're unfamiliar with Raspberry Pi Picos, note that you cannot use this storage as if it were real removable flash media. The Pico only has 2MB storage and it's only for flashing firmware - the reported "128MB" reading is erroneous.
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:
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!
- /u/_pandrew's "A new era of reprogrammable OEM controllers on Unicomp keyboards is beginning. Exciting!" /r/ModelM post
- /u/iyute's "Raspberry Pi Controller Mini M only Supports 2 Key Rollover for Certain Key Combinations" /r/ModelM post
- /u/plazman30's "You can now order the Raspberry Pi Pico based Mini-M Controller from Unicomp" /r/ModelM post
- My thread for this guide on Deskthority (the replies may be helpful)
Corrections & changes
- 2023-09-11: "How to get them" section has been reduced to form the "Compatibility with..." and "Can I make my incompatible keyboard compatible?" sections to make reading the content that used to be all within that section easier, expanded info in "Can I make my incompatible keyboard compatible?" section, and created "How to fit them" and "How do I find out if new Unicomp already has one?" sections.
- 2023-09-14: "How to get them" section has been revised to include the reason why the Justify/Mike Smith controller card isn't being shipped worldwide at time of writing.
- Wikipedia - Ruffian (horse) [accessed 2023-06-18].
- Radionics Ltd. - Cypress Semiconductor CY8C24493-24LTXI, CMOS System-On-Chip for USB, 48-Pin QFN [accessed 2023-02-21].
- Wikipedia - Aristides (horse) [accessed 2023-06-18].
- Wikipedia - Justify (horse) [accessed 2023-06-18].
- Wikipedia - Mike E. Smith [accessed 2023-06-18].
- Purdea Andrei - donated photo.
- zhinu - donated photo.