Modding the Microsoft Sculpt Ergonomic keyboard to run QMK (and make it wired)
QMK is a very powerful open source keyboard firmware that gives you complete control over what the keys on your keyboard do. It adds numerous new features to traditional keyboard firmware that can improve efficiency, productivity, and the overall ergonomic situation of your typing setup.
Whilst it’s not without it’s learning curve, the amount of keystrokes, awkward finger positioning/combinations and mouse movement it can potentially save you over a career is tremendous.
But QMK is, at least in my own findings, only really available in mechanical keyboards that you either build yourself or buy off shelf.
I’ve been using a Microsoft Sculpt Ergonomic keyboard for years now, and I attribute it as one of the primary factors in getting my RSI under control. I would go as far as to say that it’s the most crucial tool I own after the computer itself. It seems to have become an RSI “safety net” for me. Unfortunately, however, it is not able to run QMK (spoiler: yet).
But QMK’s potential got me so excited, that for the first time since the peak of my RSI ordeal, I started looking outside the Sculpt for new possibilities.
I decided to trial integrating a QMK powered mechanical keyboard for a few weeks. It’s expensive and time consuming to buy just to try, so after some research I had determined the Moonlander would be the closest to “home” for me. It’s a very nice keyboard, beautifully built, and my hat is off to ZSA. However after a few weeks I still couldn’t find the comfort or ease of typing that I was now accustomed to on the Sculpt *
* I have thoughts and ideas as to why this is, but won’t add them to this article as it’s already quite long. Good to point out that they’re more related to mechanical keyboards in general, as opposed to the Moonlander itself.
What to do.
Do I force myself to get used to a mechanical keyboard in order to benefit from QMK? Maybe spending more time and money trialling different key caps and switches to find something that works. Or do I accept that I’m stuck with the Sculpt and it’s default firmware?
Or, what if despite my current lack of knowledge about how keyboards work under the hood, I could figure out how to get QMK running on the Sculpt itself?
If that was possible I’d potentially have my ultimate keyboard.
Well… it was possible.
The rest of this article explains how I created my ultimate keyboard by giving the Microsoft Sculpt’s out of the box microcontroller it’s eviction notice, and modded the keyboard with a custom QMK powered microcontroller.
Overview
This article is split into two sections:
- Hardware — physically modifying the hardware itself. This will require obtaining components, pulling things apart, and putting them together by soldering and other methods.
- Software — the configuration of QMK to be able to interface with the sculpt’s physical key matrix, and creating our own custom layouts. This will require some understanding of programming in C, but not too much.
Before you start
This article isn’t a set of instructions, more than it is a guide. I wrote it as a way to avoid forgetting anything when I inevitably replicate this mod again.
If you want to follow this guide, please note that I don’t offer any kind of guarantee this will work for you, as things could change between Sculpt models.
If you choose to proceed, you should apply an appropriate level of appraisal and investigation of your own.
Potential caveats
These aren’t caveats in my particular situation, but maybe they are for you.
- You’ll lose wireless capability, but I consider this an improvement. I’ve owned at least 10 of these keyboards over the years. The wireless is always flakey at best. Adding the wire eliminates the regular key stuttering and delays. What’s more, I’ve lost or broken the dongles a few times, and they can’t be replaced. A wire eliminates that problem also.
- The function switch will become redundant, but QMK provides the same functionality anyway, one thousand fold.
- You’ll need to drill holes in the chassis of the keyboard to house the cable. You’ll also need to route channels in the internal supports of the keyboard. It’s pretty easy, but it’s a destructive operation.
- This initial keyboard mod was a prototype. For example, the wiring was not done with the care that you’d take in a more polished project. Mistakes were made when routing out a channel for the wires whilst I figured out what would work best. Now that I’ve done one, next time I mod a Sculpt, I’ll take more of a finished product approach. So, don’t take the images you see as gospel — you may want to come up with improvements of your own.
Acknowledgements
Turns out that I’m not the first person to attempt to do this, and I’ve been lucky to be able to leverage some of the work that was previously done by GitHub user blttll in this TMK version of the sculpt mod.
The PCB schematic for example, came from this repo and was a huge leg up in getting my mod completed quickly. Therefore, I decided to stick with the Teensy 2.0 microcontroller that blttll used, despite a few very small short comings (namely loss of space bar LED use, no function switch use. I may rectify this in a later revision).
What you’ll need
Other than patience and a somewhat steady soldering arm for the FFC connector, you’ll need the following.
Tools
- Screw driver
- Soldering iron
- Solder and flux
- Stanley knife, or equivalent
- Optional — solder wick. It can help clean things up if you need to reverse some soldering issues. Might be helpful particuarly around the FFC connector.
Components
- Microsoft Sculpt Ergonomic keyboard
- Printed PCB — it so happens someone else had already printed blttll’s PCB at Osh Park, so I opted for that. You’ll get a few copies, they’re cheap and fast to ship. I really liked my experience with this company.
- FFC 30 Pin Connector — I used a Molex, but any 1mm pitch 30 pin connector should do the job.
- Teensy 2.0 — this board uses an ATmega32U4 microcontroller, which is one of the supported microcontrollers for QMK, and it’s just small enough to fit in the keyboard chassis with further modifications than I already had to take.
- USB Mini B to USB A or C cable — Then Teensy needs the mini B, the other end is up to you. I used a 1.5 metre cable, and opted to use the USB A end with an Apple USB A to C adapter. You will be severing this cable, so don’t spend a lot of money on a fancy one.
Let’s get started.
PART 1 — HARDWARE MODIFICATION
Dismantle the Sculpt chassis
This is easier than you think, but it feels a bit “wrong” as you do it. Don’t be deterred, it comes apart easy enough.
1. Unscrew the bottom plate
- Take the padded feet off (use a screwdriver)
- Unscrew all the small screws. Put them in a safe place and not where they’re from.
2. Remove the wrist pad
- Using the tips of your fingers, you can (slowly) unclip the wrist pad. Use a screw driver to get leverage if you need.
- Start on one side and slow pry it up across to the other side, in small increments.
3. Remove all screws that are under the wrist pad
- You’ll now see the exposed chassis.
- Remove all the screws. Be careful to check each hole, there are some screws hidden.
- Again, store the screws safely and label where they were from.
4. Separate the top from the bottom plate
- If you’ve remove all the screws correctly, you’ll now be able to separate the top and bottom half of the keyboard. Note, this is still clipped in, it won’t just come off.
- Using your fingers, or a wide screw driver, carefully go around the edges of the keyboard and pull the top half off. You’ll hear clicking as the clips detach, that’s ok. Again, be gentle.
Detach the existing microcontroller
With the keyboard dismantled, you’ll see something like this.
This is the default Microsoft PCB which houses the microcontroller that processes keypresses and sends them to the computer via the wireless dongle. The flat ribbon cable with the long lines is the connection to the keyboard matrix, and this is the part we keep.
- First, unscrew the small screws that are holding the the PCB down. Keep these safe, you’ll need them again to attach the new PCB.
- Gently pull the thin black clamp on the FFC connector towards the ribbon cable, which will release it from the connector.
- Now, lift the PCB up out of the chassis, and gently pull the ribbon cable out of the FFC.
You can now put the PCB aside, we don’t need it anymore.
Next, we’ll start assembling our new PCB to replace the one we’ve just removed.
Solder the Teensy to your PCB
The PCB is a simple board that provides traces that connect the FFC connector through to the Teensy. Once soldered, we can just plug the ribbon cable in and the keyboard matrix will be connected directly to the microcontroller on the Teensy (which is where QMK will be running).
I won’t be addressing proper soldering technique (especially when I didn’t really take too much care during the prototyping of this mod). However, here are some key take aways I have when soldering the Teensy onto the PCB…
- File the edges of the PCB before attaching components. The manufacture of the PCB will leave some small sharp joints around the PCB. Shave these off with a file before you do any soldering. This is essential for the board to fit in the pre moulded mount in the chassis.
- Don’t solder using header pins — it won’t leave enough room for the chassis to come back together.
- Solder the Teensy flat to the PCB itself, pin hole to pin hole. I initially started using raw metal pins to make the connection, but it’s not necessary.
- Use flux to ensure good soldering joints. I didn’t bother cleaning it up considering this was a prototyping board, but if you use something like no-clean flux it won’t matter.
- Perform a continuity test using a multimeter during or after soldering the pins. Put one terminal of the multimeter on the solder on the top of the Teensy, and the other in the corresponding pin where the FFC connector will go. This is a little tricky and time consuming, but it’s worth it to be sure that you have a proper connection. Address any soldering issues.
Solder the FFC connector to your PCB
This is tricky to do, especially because these pins have a fairly small pitch of 1mm.
Again, this isn’t an article on soldering technique, but here’s how I made the soldering connections:
- User a narrow iron tip, and solder each connector one by one. You can of course use a wider tip and use a drag solder technique, up to you, but I find doing each individually helps me avoid bridges easier on a pitch this size.
- Use very little solder. Too much solder will cause bridges across pins that you have to clean up. If you get in a mess with bridging, you can use solder wick to bring up the solder and start again.
- Use a hot iron — I had mine at about 360 degrees Celsius from memory.
- Perform a continuity test across adjacent pins, but this time we do not want to hear sound from the multimeter. If you hear sound, you have a soldered bridge and will need to clean it up. Take your time with this — the pins are so close together it’s easy to hit the multimeter terminals together.
Attach the PCB to the keyboard matrix
You can now reattach the the flat ribbon cable to your new PCB.
Screw the the PCB back in to keep everything together against the top part of the chassis. We’re not putting the chassis back together yet though.
Route the cable through the chassis
At this point, you could opt to get the software running. However, in order to keep the “construction” phase of the article together, I’ll explain how to route the cable channel now, but it’s fine to skip forward now to part 2 and come back to this once QMK is running.
This is where we’ll need power tools. I only had a drill at hand, but if you have a Dremel, that could make your life easier when breaking down the internal supports to make way for the cable.
Route the channel and drill the exterior hole
The key goals are:
- Keep the outside of the chassis clean and tidy.
- Have the cable run out of the keyboard without altering the stability of it on the desk.
- Have the keyboard chassis close perfectly, and remain as stable as before.
- Create enough friction to secure the cable so that we can treat the keyboard as meanly as we like, and not have to worry about the robustness of the connection of the cable to the PCB.
Looking at the picture below, you can see the path way in which I found the cable should take to achieve the above goals. Ignore the cable for now, I’ll explain that next.
Breaking the internal supports didn’t have any noticeable effect on the structural integrity of the keyboard chassis. The structural support “walls” are fairly weak and easy to drill through or cut through with a stanley knife. A Dremel would have no trouble with it. Choose your own method, just of course do it safely. If you create dust, wear a mask. The drill and knife method I used produced no dust, so I didn’t need to.
Severing and rejoining the cable.
We have to sever the cable so that it can enter the small hole in the exterior of the keyboard. This keeps it looking neat.
I’ll let the photos above and below explain mostly what I did, but effectively:
- cut the Mini B terminal off, but leave enough wire to rejoin to the main cable later.
- Use a technique of your choice to remove the plastic moulding around the plug. I used a stanley knife blade.
- Run the long end of the cable through the hole you drilled, and route enough length through the channel you made so that you can rejoin the terminal end, leaving just enough wiring in the chassis to make a connection to the PCB and still be able to join the chassis back together tightly. This is a bit tricky to do, take your time.
The result, if done well will, be that when the keyboard is back together you should be able to hold it like this and have no concerns what so ever about the integrity of the cable connection.
Optional — drill a hole to access the reset button on the Teensy
As you’ll soon see, when we want to flash our QMK firmware to the Teensy, we have to enter the microcontroller into bootloader mode.
Initially, I had set a key on the keyboard to do this myself via the QMK software. However, I accidently removed it one time whilst configuring my keyboard layout, and ended up having to dismantle the keyboard again to press the physical button. That was annoying!
Whilst doing that, i decided to drill a hole on the underside of the keyboard so that if I ever made that mistake again, I could use something thin to press the hardware button on the microcontroller. An added bonus, is you can see the orange LED if you need to confirm it’s getting power.
At this point, you could put the chassis back together, however I’d recommend waiting till you finish getting the software running in part 2, just in case you run into problems and need to access the hardware again.
PART 2 — SOFTWARE CONFIGURATION
In this part, I’ll show you how to create a custom QMK configuration so that the firmware will work with the keyboard.
To do so, we’ll first need to understand how the keyboard matrix is actually connected through to QMK via the Teensy 2.0.
If you’d rather skip this, it’s not essential, and you can continue to the Creating the QMK configuration section. But of course, then you’d not really know what’s going on under the hood, and what’s the fun in that.
Understanding the ribbon cable
The sculpt uses a 30 pin ribbon cable. Most of these pins are used to represent the rows and columns of the keyboard matrix. If you don’t know about keyboard matrixes yet, might be best to read this first.
The cable on the sculpt looks something like this — I have numbered the pins to the right.
Once again, I can tip my hat to blttll who had already gone to the effort of determining how the keyboard matrix corresponds to the traces on the keyboard ribbon connector. You can see his original representation of this here.
I’ve included his work in my own repo for completeness and to represent the matrix in hex. For convenience, here’s my version of blttl’s table.
Next, I’ve highlighted the traces in the cable that correspond to the rows and columns.
How this works is that when a given key is pressed, one row and one column trace will be high (meaning they have electrical current present). This is because the keypress effectively closes a circuit on these lines.
So for example, if row 2 is high and column 11 is high, then it means that the caps lock key is being pressed down. When that key is released, that row and column will both be off (well, as long as no other key on that row or column are pressed, but let’s not complicate things).
Another example, if I press down the p key on the keyboard, then row 2 and column 4 would be high.
It’s these currents on these traces that QMK uses to determine what physical key is being pressed.
Next we’ll look at how this cable connects to the microcontroller, which is what QMK will be running on.
Connecting Microsoft’s keyboard matrix to QMK
Things get slightly more complex when we want to connect the matrix (via the ribbon) to our Teensy.
As we saw above, the keyboard matrix in the Sculpt has 8 rows and 18 columns, totalling 26 lines in the ribbon. However, the Teensy only has 25 general use input/output pins that we can use.
Luckily for us, the custom PCB we printed has already handled this for us.
If you look in the table above, columns 6 and 2 have a single key each (rsft and ralt). Because these keys don’t overlap on a single row, these two columns can actually be merged, reducing the total number of columns to 25.
This has been done by bridging the FFC pins that correlate to these columns in the PCB.
By doing this, the matrix table loses a column, and now looks like this. Column six was removed, and the following columns are now shifted down. Notice that rsft and ralt both now sit in column 2 but they’ve preserved their original rows.
With that bridging done, we can now fit all of the matrix rows and columns into the Teensy.
This is what that looks like in the schematic.
All that is left now is to create the QMK configuration, and flash it to the microcontroller!
Creating the QMK configuration
Well done for getting this far! We’re near the end now.
QMK makes it really easy to create new configurations. For brevity (in an already humungous article), I won’t explain QMK’s configuration structure. Instead I’ll highlight the key things you’ll need to do in particular files and you can reference my source code to get the full picture. You can use this as a bases for yours, or just compile it directly to your own modded sculpt.
rules.mk
Firstly, we need to tell QMK what microcontroller to build for, and how to flash it onto the microcontroller.
Teensy uses ATmega32U4 as the microcontroller, and halfkay as the bootloader.
# MCU name
MCU = atmega32u4# Bootloader selection
BOOTLOADER = halfkay
config.h
This file configures some key parameters, such as USB HID values that are used to identify your keyboard to the host. In this file we also tell QMK how to consume the keyboard matrix.
The rows and columns of the matrix have a path way from the ribbon as you saw above, through the PCB traces, into the pins of the Teensy 2.0. The Teensy then has traces of it’s own which connects the pins into the ATMega32U4 microcontroller. It’s inside this controller where the QMK magic happens.
But before the magic occurs, we first need to specify which pins on the Teensy correspond to which rows and columns in the matrix.
#define MATRIX_ROW_PINS { C7, C6, D3, D2, D1, D0, B7, B3 }
#define MATRIX_COL_PINS { B2, B1, B0, E6, D5, D4, D6, D7, B4, B5, B6, F7, F6, F5, F4, F1, F0 }
#define DIODE_DIRECTION COL2ROWThe DIODE_DERICTION variable is a topic for another time, but let’s quickly elaborate on the rows and columns.
You’ll notice that the values C7, D4, D3 etc correspond to the schematic we have above. Let’s zoom in on the key part (match the black boxes in the diagram up with the code above).
At this point you should be able to see how we have completed the path from the physical keyboard matrix, through all the hardware, and now into the software.
We’re not done yet though, we have on final thing to do before we can start to create our own custom layouts.
<keyboardname>.h
This is the file in your keyboard configuration which specifies how the keys in the matrix are physically layed out on the keyboard. Effectively, we’re creating a construct here that makes it easier for us to define our own custom keyboard layouts.
I called my keyboard configuration Sculpter, so my file is called sculptor.h
It looks like this.
It might take a bit to get your head around what’s going on here, but let me help a bit.
This part below is effictively laying out the keys in their actual physical representation on the keyboard.
This is just a single comma separate list of values, but I have used spacing to abstractly layout out the keys in code (the large blocks of space indicate the bigger keys). If you look at the physical keyboard you can see how this loosely maps onto it.
The right arrow key is in the bottom right (in our matrix table above Row 6 / Column 1). The escape key is top left (in our table above that is in Row 4 / Column C), which we designate as K4C in code (the K means “key”, followed by the row and column).
This bottom part, shown below, is basically our exact mapping table above, except we’ve used KC_NO to indicate where we don’t have a key.
What we’ve done here now is created a helper in C, which we can use to layout keys as we like, and the helper will properly map them to the correct key presses in the matrix.
QMK does most of the heavy lifting here, and you could just copy and paste this verbatim and forget about it (unless you’re using a non ANSI keyboard, more on that below). But it’s worth pondering this a bit because if you can grasp this, you will be able to intuitively understand how the key presses themselves arrive into the software.
Finally — creating the actual layout
Congratulations, you’ve made it to the rewarding end. You can now make your Microsoft Sculpt do anything you want it to, all thanks to it now being powered by QMK.
Here’s an exceprt of how one could create the basic QWERTY layout in QMK. You will see usage of the LAYOUT helper we created above. We can put any of the QMK defined key codes here, and they will be mapped correctly into our keyboard matrix so that QMK can match up the physical keypresses with the virtual keymaps that we define.
The sky is the limit here, and I encourage to check out all the different layouts that are possible with QMK in their repo.
Put the chassis back together
At this point, you’re done! If you hadn’t put the chassis back together yet, now is the time.
It’s pretty much just reversing what you did before, except now you have the cable to work around.
If you’re routing has been done correctly, the cable should be able to fit snuggly into the chassis, and it should close up correctly. However, you may need to do some wrangling here to get everything back in place.
Conclusion
The Sculpt is now running QMK as if it was always meant to. If you hadn’t put the chassis back together yet, now is the time.
For me, it’s the ultimate blend of ergonomic form factor and functionality.
There’s still a lot to the keyboard maker movement that I want to tap into. I’m still keen to see if mechanical keys can work for me. I’m also really keen to try and make columnar work, as my initial experiences with the Moonlander were quite nice.
A last word for non ANSI Sculpt owners
If you’re using a non ANSI version of the Sculpt, such as ISO or JIS, the above will still be applicable. It just means that you are going to have some extra keys in the matrix table. However, I’m not sure if the Sculpt itself has the same matrix table across ANSI, ISO and JIS. I’m happy to provide guidance if you are a user of one of these Sculpts and would like to try this.
