What is it?

This is a replacement controller for the famous IBM Model M keyboard based on the STM32F072 micro-controller.

It runs the well known feature rich QMK open source firmware for keyboards.

Assembly Instructions

Follow this guide to install a ctrl-M kit.

The full replacement process, from opening the keyboard to testing your finished modification is described in the assembly instructions.

Why did you make it?

Why do you want to replace your controller and have a modern Model M:

• Includes modern keycodes like Windows/menu button, multimedia/volume/brightness keys
• Fully customizable keyboard layout with up to 16 layers (Add keys for Mac, SUN, emojis etc.)
• Includes mouse and mouse wheel emulation
• Create, store and run macros directly from your keyboard
• Caps word: Double tap left shift to activate CAPS lock until a non-character key is pressed (like dot, space, a number)
• Fully open source software and hardware
• No fiddling with PS/2 to USB adapters that are harder to get these days

What makes it special?

To my knowledge all IBM Model M's with 101/102 keys are supported as well as the older Lexmark models. Or speaking in production years all Model M's from 1986 to 1994 are supported.

Connector variants supported:

• 16+8+4 wide, wired LEDs
• 16+8+4 wide
• 16+8+4 narrow
• 16+12 narrow
• 16+12 wide

Software

This controller runs QMK a well known feature rich open source firmware for keyboards used by many mechanical keyboard enthusiasts and also keyboard manufacturers.

Work in progress to get ctrl-M into mainline. The current fork is maintained here:

https://github.com/nuess0r/qmk_firmware/tree/ctrl_m/keyboards/ibm/model_m/ctrl_m

One of the nice features of QMK is, that you can dynamically edit your keymap and up to 16 layers in your browser.

nuess0r Keymap

The default keymap in QMK is minimal and functions as a starting point to define for your own.

The nuess0r keymap included in the ctrl-M software already adds a lot of useful additions compared to a stock Model M like windows and multimedia keys, mouse wheel support etc. This is the pre-flashed keymap when you buy a ctrl-M. How it works

The nuess0r keymap consists of three layers: base layer, special function layer and mouse key layer

To switch between the base layer and the special function layer press and hold the Esc key.

Base layer

The base layer is exactly what you expect from your normal Model M except that you have a Windows key instead of CapsLock.

When you press and release Esc you get a escape key code, press and hold Esc to switch to the special functions layer.

Double “click” the left Shift key to activate the Caps Word feature. Caps Word is a modern alternative to Caps Lock:

• While active, letters are capitalized. This makes it easier to type constant names (eg ‘PROGRAM_CONSTANTS’).
• Caps Word automatically disables itself at the end of the word. It stops once a space or any key other than A-Z, 0-9, Insert, Delete, Backspace is pressed. It's disabled also when the keyboard is idle for 5 seconds.

Special Functions Layer

When you press and hold Esc you temporarily switch to the special functions layer. Practically this means that you have Esc + other key short cuts for all the special functions added to the Model M default keymap.

Available special functions:

• F1: dynamic macro 1 play
• F2: dynamic macro 2 play
• F3: dynamic macro 1 record
• F4: dynamic macro 2 record
• F5: dynamic macro record stop
• Capslock: CapsLock (really!)
• ~: Key Lock
• Cursor: Media Pref / Next / Volume Up / Volume Down
• Space: Media Play / Pause
• Page Up: Brightness Up
• Page Down: Brightness Down
• Number pad arrow keys: Mouse wheel
• m: Enter mouse layer

Here you can find the documentation about the QMK dynamic macros.

Mouse Layer

When you pressed Esc + m you entered the mouse layer. Now you can move around your cursor, click buttons etc.

• Cursor keys: move mouse
• Insert/Home/Page Up: Mouse acceleration (Make the mouse move slower/faster)
• Del, End, Page Dn: Mouse buttons
• Number pad arrow keys: Mouse wheel

Hardware

The controller is based on a STM32F072 chip and is designed with KiCAD.

To make the controller as compatible as possible there are four possible LED and earth cable connectors.

Also the PCB can be cut into a smaller variant that fits the later IBM/Lexmark variant.

The four LED connector variants are:

• J8 is a 12 pin connector for both LEDs and keys
• J8 is a 8 pin connector for keys and J9 is a 4 pin connector for LEDs
• J8 is a 8 pin connector for keys and J12 is a 4 pin connector for LEDs
• J8 is a 8 pin connector for keys and J10 is a 4 pin header for LEDs

To fill the gap between the USB connector and the case and also to make it easier to press the bootloader button a small plastic part (button_lever.amf) was designed with FreeCAD that can be 3D printed.

All design files are released here:

https://github.com/nuess0r/ctrl-M

Configuration

The easiest way to configure your keymap is using a Chrome/Chromium based browser and the VIA app.

Go to: https://usevia.app/

The browser should ask you for permission to access your ctrl-M keyboard. Then you can inspect and configure your keymap, make backups etc. All changes are immediately sent to your keyboard so you can test them straight away.

Linux udev rule

In Linux a normal user and therefore the web browser doesn't have access to raw HID devices by default. You have to set the proper permissions first.

Make sure your user is member of the group plugdev then create a new udev rule:

sudo nano /etc/udev/rules.d/ctrl-M.rules

Enter the following string:

KERNEL==“hidraw” ATTRS{idVendor}==“1d50”, ATTRS{idProduct}==“6180”, GROUP=“plugdev”, MODE=“0660”*

Save and exit nano then load your new udev rule:

sudo udevadm control –reload-rules && udevadm trigger

Go to the VIA app and test it.

Flashing

The STM32F072 contains a USB DFU bootloader to load software onto it without additional special hardware.

Detailed instructions how to build your firmware and flash it can be found in the QMK flashing manual.

There are two ways to enter the bootloader:

1) If you get a ctrl-M from me or bought it somewhere, it should be pre-loaded with QMK:

• Unplug the USB cable
• Press and hold the Esc key
• Plug in the USB cable
• Release the Esc key

2) If you built it yourself or somehow QMK was deleted or is corrupt:

• Unplug the USB cable
• Press and hold the bootloader button next to the USB connector (With the 3D printed button lever or a small flat headed screw driver)
• Plug in the USB cable
• Release the button