ctrl-M Controller for Model M

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

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.

If you have a question or struggle at a building step you can in the ctrl-M Github project open a new discussion.

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

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.

16+8+4 wide, wired LED Manufacturing year 1986? - 1989?	16+8+4 wide Manufacturing year 1988? - 1990
16+8+4 narrow Manufacturing year 1991?	16+12 narrow Manufacturing year 1991 - 1992
16+12 wide Manufacturing year 1992 - 1994?

For the 4th generation Model M from Lexmark/Unicomp (Controller mounted under the LEDs) there is another replacement controller:
OverNumpad controller v1.Xb

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.

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.

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.

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.

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.

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

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

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.

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 && sudo udevadm trigger

Go to the VIA app and test it.

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