Brand New Model F and Beam Spring Keyboards Manual

The Model F keyboard, if properly set up and maintained, can provide you with decades of pure typing pleasure and performance, and it can hopefully be something you will use for the rest of your lifetime and maybe pass down to future generations. Check out some excellent Model F overview videos such as this one:  https://www.youtube.com/watch?v=y9Jds326gks

The thing is, before you set up your keyboard, you need to review the manual. This manual will review everything you need to know about the Model F.  It will help you become a responsible steward of the best keyboard technology ever made, so your keyboard does not end up in a landfill after something stops working. The goal of this community-oriented project is to give you a keyboard that you can learn to take care of yourself and that will serve you well for decades to come, long after production has ended. Part of your responsibility is learning how to set up and troubleshoot issues with the keyboard. The most basic recommended maintenance involves checking that each key works reliably and taking off the keys with a wire key cap puller to clean them with mild soap and water every now and then.

What we’re about to go over is not something you can easily figure out on your own, even if you have used a Model F or Model M keyboard before. The time spent reviewing the manual will save you a lot of frustration and spending hours more than you need to. Don’t be the one who stops reading or listening now and starts installing keys, and then spends an hour trying to fix something that would take a minute if you went through the manual beforehand. Please follow exclusively what is written in this manual – do not try to figure something out through hours of your own experimentation. Most issues can be fixed within minutes, not hours. If it takes an hour to fix something, you are probably not following the manual.

Why does the Model F outlast just about every other keyboard?  The Model F keyboard is a robust design. Every part is 100% user-replaceable / user-repairable, often needing just a couple tools: screwdrivers, tweezers, pliers, and at most a soldering iron. Compared to other consumer electronics products, Model F repair is easy and even a complete beginner can get up to speed quickly. If you are unable to solve an issue after you have reviewed the manual, please direct all questions and support requests to the project thread on the mechanical keyboard forums such as Deskthority – please do not email me or post on the Q&A page for technical support. The great communities of mechanical keyboard fans on sites like Deskthority, geekhack, and reddit are great at sorting out all types of issues. You will never be out of reach of someone who can offer you advice and help in the coming years. While the project philosophy encourages you to be self-reliant and responsible for set up and maintenance, you are not alone and no one who buys a keyboard here will be left with a non-working keyboard.

The current state of low-quality manufactured goods encourages a culture of just throwing something away or bringing it back to the store if anything is wrong with it. For something complicated like a motherboard or graphics card that’s probably the best option, but the new Model F project philosophy is for the users to be able to fix small issues themselves due to the simplicity and full repairability of the Model F design (many buyers come from the world of the original IBM keyboards that are decades old and almost certainly require some maintenance work, so they expect it and are used to it).

There are two essential requirements to help your Model F keyboard last a long time:  educating yourself on how to set up and maintain your keyboard and also making sure you have plenty of spare parts on hand now, so they will be available to you long after production has shut down and this project has ended.  Buying spare parts is essential to help keep your keyboard operational in the decades to come. Please check out all the other items in the store. The most important extras are the First Aid Kit of spare parts for future repairs once production has long shut down (over 1000 kits ordered so far!), spare flippers with springs, spare barrels, key pullers, extra key sets (the key tops do wear down over time and you won’t be able to buy more XT quality one-piece keys after the end of the project) and also a spare custom made 3-meter USB cable. I hope to be able to manufacture as many First Aid Kits and spare parts as possible to keep all these great Model F keyboards running decades from now.

If you like using Model F and Model M buckling spring keyboards, the best way to help the project is to tell other “tech-minded” people you know about the project. That would be greatly appreciated. And please do share some photos of your newly set up Model F Keyboard on the Deskthority and geekhack project threads! 

Key (pun intended) features of the new Model F – why is it different from other keyboards

• The Model F technology features heavy duty metal parts contributing to the 5- to 10-pound weight of each keyboard, including a metal top and metal bottom inner “sandwich” plates with interlocking tabs, and a powdercoated metal case for this project and for some of the original models. The Model F design is robust and easy to clean and self-repair with nothing more than a screwdriver, pliers, tweezers, and a key puller.
• High-quality parts contribute to its long life, with many Model F’s still in operation after decades of continuous usage. Still the best technology keyboard out there. Will possibly outlast all other parts of every computer you will buy from now until the end of your life.
• Capacitive sensing buckling spring technology – long life enhanced by no metal-on-metal key contact
• Dye-sublimated PBT keycaps: text does not wear off like most keyboards.
• Individual injection molded barrels for each key made of premium plastic for enhanced smoothness and key travel
• Large injection molded capacitive flippers for a solid sounding click

Model F Reproduction Keyboards specific features:

• Factory customizable with dozens of possible combinations of case color, key layout, key language, and custom birth date/serial number availability to choose from
• New available layouts not possible with the original Model F’s – HHKB style split right shift, split spacebar. Can split keys like the original F’s (split back space, left shift, right shift, enter)
• Leverages the new open-source, full N Key Rollover xwhatsit software and hardware built from the ground up as a Model F keyboard controller replacement. Fully programmable with multiple firmware options including QMK and Via
• Parts made from brand new tooling and molds – like getting a Model F from the early 1980s right when they were introduced!
• Metal stabilizer tabs – Metal tabs attached to the top inner assembly for the Model M style spacebar stabilizer wire – upgraded from the plastic tabs in the original Model F keyboards

A. Safety precautions:  Always consult the booklet included with your new Model F keyboard for safety precautions and other important information. Severe harm or even death can occur with any product if safety precautions are not followed. Model F Labs does not condone using these heavy, solid metal keyboards as weapons of defense in the event of a zombie apocalypse. Always use the right tools for the job – you will need a wire key puller to properly set up your new Model F keyboard as one or more keys may require more than one try to install it correctly. Only use the USB cable that came with the keyboard, as not all USB cables are compatible or safe, especially the “smart,” Apple, or “E-Marked” USB-C cables.

B. Parts identification for Model F Keyboards

1. Keys (from left to right:  Pebble, Pearl, Black, Industrial SSK Blue, 60% Dark Gray)
2. Barrel
3. Flipper with spring
4. Top inner assembly
5. Bottom inner assembly
6. Inner foam
7. Controller PCB with ribbon cable
8. Large capacitive PCB (green or yellow)
9. Top and bottom case
10. Solenoid (optional)
11. Solenoid driver (optional)

C. Initial setup steps:

1. Very important: please study this entire section and go through everything step-by-step. Otherwise, you will miss something and it could cost you hours of your time to fix it and you may even need to start over completely!
2. First up after your keyboard arrives in the mail, inspect the keyboard’s flippers, springs, and layout. Make sure you received everything you ordered and that nothing is damaged. Part of a keycap may have snapped off in shipping. Check all the various bags as parts may be mixed inside other bags.
3. Before installing any keys, make sure all springs on their flippers are present and move freely – a stuck flipper might require taking apart the keyboard if it cannot be loosened from the top side of the keyboard (if you have to open up and slide apart the keyboard’s inner assembly plates, be sure to remove the keys first!). If you see a nub without a spring, the spring may have fallen off in shipping and needs to be replaced (refer to the key installation section for details, and then come back to this section).
4. You may notice some barrels without any flippers and springs. This is intentional!  The extra wide keys have stabilizer inserts which go inside these barrels. It is best to use new Model F stabilizer inserts with new Model F project keys and other stabilizer inserts with other keys.
5. It is also important to make sure the layout you ordered is the layout you received. For key sets with full size Left and Right Shift keys, there should be no flipper and spring in the right barrel of the Left Shift, and nothing in the Left Barrel of the Right Shift. For standard horizontal Enter (example:  US) and 2U backspace keys, there should be no flipper in the left barrel. For ISO Enter, there should be no flipper in the top barrel of that key.
6. If your layout is not the one you wanted, head over now to the section on opening the inner assembly. It is easy to change it if you haven’t skipped ahead to installing keys – it only takes a few minutes without keys installed. The only thing you can’t change is going between HHKB-style split right shift and regular right shift.

D. The next step is to install the stabilizer inserts:

1. Horizontal inserts (white stabilizers) are used for the 2U and wider keys in the barrels that do not contain a flipper and spring, with exceptions for two keys: the ISO Enter key uses the black/vertical stabilizer and the spacebar does not use stabilizer inserts. You can’t put an insert in a barrel if there is a flipper or spring in that barrel already – you’d have to open up the inner assembly to remove the flipper.
2. Push the insert all the way in the barrel so that it is flush with the top of the barrel. Install horizontal inserts (white inserts) as pictured below, with the “ears” on the left and right sides. The vertical stabilizer inserts are installed also as pictured for the number pad 2U Vertical keys, but must be installed differently for ISO Enter! 
3. The product photo shows each photo in the “right side up” orientation so for ISO Enter you’d just install the vertical (black) insert 180 degrees rotated from the photo, so that the larger “ear” of the insert is on the left.
4. If you mistakenly install the stabilizer incorrectly, or install the incorrect stabilizer, you will need to take apart the keyboard to push out the stabilizer insert from the other side. An alternative to this would be to use straight tip lock ring / snap ring pliers, though not all of them would fit. I personally use Wilde Tool G407 lock ring pliers to remove stuck inserts without having to take apart the keyboard. Another alternative:  Check out this great method to safely remove horizontal and vertical stabilizer inserts without having to open up your new Model F keyboard to push out the insert!  https://deskthority.net/viewtopic.php?p=477651#p477651
5. Another way to remove a stuck stabilizer insert:  Quoted from a Model F owner: “If one of those little white plastic stabilizer inserts gets stuck in a barrel, a 1/4-20 inch thread tap (and tap wrench) will grip it well enough to get it out without damaging the barrel.”  

E. Next up is getting the spacebar right. Model F keyboard spacebars are highly adjustable so you can dial in the kind of spacebar you want, to some degree. This is a key you will be pressing a lot so it is a good idea to get it right before proceeding because it is tricker to adjust the spacebar after you have proceeded to install all the keys.

1. Sometimes the spacebar requires adjustment after the keyboards are bounced around in shipping – sometimes they are bounced so much that people have found the spacebar separated from its keyboard barrel! It’s a matter of slightly bending the spacebar wire so it performs optimally. Definitely more of an art than a science. When the spacebar gets stuck in my QC process, I usually take the wire with two hands, with the long part of the wire closest to my thumbs, and use both thumbs to very slightly push up the wire – I do this about 4-5 times but not too hard that the bend becomes noticeable. That way the wire is pushed out of the way enough of the metal stabilizer tabs so that there is a little room, maybe 0.5mm to 1mm. If they’re too close to the back of the metal tabs, the spacebar wire can get in the way of normal operation. This will also make the spacebar stabilizer wire ever so slightly wider in the two places where it connects to the spacebar itself – this also helps adjust the looseness vs. tightness of the spacebar while in operation. Check if the spacebar wire is underneath the top of the metal tab – for both tabs! 
2. You can also tighten up the spacebar actuation and reduce rattle by removing the spacebar wire and tightening the left and right parts of the wire so that they are moved inwards, but not too much that the bar cannot be reinstalled! If you need to separate the stabilizer wire from the spacebar, always hold the spacebar upside down and make sure the spacebar wire is flat against the spacebar; then you can pull the spacebar wire from one end in order to separate it from its hole in the spacebar. Always remove the spacebar wire stabilizer from the spacebar before adjusting it. If you just try to pull the wire straight off (or push on to) the spacebar, you may break the spacebar’s little tabs.
3. The metallic twang / reverberation / ringing is definitely the sound I am going for (!) but there are ways of reducing it. The bigger the thud of the spacebar, the better in my view! One can also carefully push down the metal spacebar tabs for a reduction in rattling sound. Always push the side of the spacebar whose tab you want to adjust towards the metal tab in order to get that wire nearly touching the back of the metal tab before you push down that tab, then repeat for the other side. Pushed down even more and it may make the spacebar require “heavier” force to actuate (push down too much and the spacebar will get stuck frequently!), though this may result in some damage when trying to remove or adjust the spacebar. “Applying a single layer of electrical tape where the stabilizer met the clips, as suggested by dotcom, helped immensely. I haven’t tried clickclack’s spacebar heat shrink mod but might do that someday. As it is, the spacebar is now the best sounding key on the keyboard.”
4. If the spacebar is not actuating, test with a 1U key to make sure spring is good. Please carefully remove and reseat the spacebar. For keyboards shipped in 2020 or earlier: if spacebar gets stuck, push down a little on the metal tabs. The updated production rounds shortened the metal tabs slightly to eliminate that issue of the tab end making contact with the spacebar.
5. If your spacebar lags a bit, just need to loosen the clips a touch with a screw driver, or you may need to bend the stabilizer wire a bit. I believe that the nice spacebar thud sound (and minimizing rattle) is highly contingent on the proper placement of the metal tabs relative to the stabilizer wire– bending the stabilizer wire slightly away from the metal tab ends results in a more rattly spacebar with a lighter actuation force that some people prefer, while pushing too much towards the metal tab ends can slightly increase actuation force for the spacebar. Excellent spacebar stability and sound is most likely to occur when the wire is directly against the back of the metal tab, or very close to it. Another way of reducing the spacebar force slightly is to squeeze the stems of the key as described later on in the “wiggle method” section.
6. Regarding squeaky spacebars: that is nearly always the case of adjusting/slightly stretching or replacing the spring rather than due to the spacebar stabilizer wire. A “squeaking” or stuck spacebar is often due to a bad spring combined with the need to slightly adjust the bend of the spacebar stabilizer wire – you can replace the spring without opening up the keyboard by using tweezers as shown later on. Spacebar seating issues: Likely the spacebar tabs have been pushed down too much, or not enough. or the spacebar wire is bent out of shape (should be precisely rectangular as a starting point). Also the spacebar should be installed as shown (space bar end up but a 45 degree angle).
7. Some prefer putting a clear plastic tube where the metal stabilizer wire touches the metal tabs.
8. One Deskthority member recommends automotive “silicone grease lightly applied (to the outsides of the barrels and the friction points for the stab wire).”
9. Another user: “try putting thin adhesive neoprene under the stabilizer wire next to the tabs on the barrel frame. This has made the spacebar quieter and more solid, without making it mushy.”
10. To quote another DT member: “Regarding spacebar rattle on the F62, I did several things, and the rattle has disappeared. Not sure which of these items worked or if it is the combination: Put strips of self-adhesive rubber inside the spacebar. I used strips intended as non-skid feet for the undersides of various things, such as keyboards. Applied a dab of silicone-base grease to the spacebar stabilizer clips on the top plate of the keyboard and on the spacebar itself. Put strips of ultra-thin self-adhesive foam on the top plate of the keyboard where the spacebar stabilizer wire hits the top plate. I used Poron ThinStik polyurethane foam. Put an O-ring at the base of the two spacebar barrels. The dimensions of the O-rings are 16mm OD, 12mm ID, 2mm thickness.”

F. After that, you can install the keys. Do not plug in the keyboard to your computer until instructed to!

1. The steps in this section will describe everything you need to know about how to install the keys, how to evaluate the sound of the spring as you test each key to make sure the key actuates properly when it is pressed, and how to reduce the buzzing sound of a key and/or fix a key whose spring does not click/buckle as it is pressed down.
2. It is completely normal for many keys not to function on your first try. Removing and reinstalling a nonworking key a few dozen times is not the way to go about setting up your new Model F! Keep reading to avoid frustration and reduce your setup time.
3. Proper key installation involves holding the keyboard vertically, spacebar side up.
4. See the main setup video linked at the top to see how I install each key and make sure it is properly installed, and how to adjust things if the key does not actuate properly.
5. Don’t let the keyboard rest horizontally until each key has been fully pressed in.
6. Do not connect the keyboard to a computer until you have installed the keys. Per a DT user: “When there are no keycaps, all the flippers will rest on the pcb giving you pressed keys all over.” 
7. It is important to test the Model F before you start using it on your computer: Even though there is strong protective packaging, Model F springs are often dislodged during shipping which can result in a bad click sound or no click at all, and keys (and sometimes springs) may need to be reseated. Test each key to make sure it buckles properly. There is a Quality Control Secrets portion of the setup video that will show you step by step how to fix a nonworking key as well as help you determine what keypress sounds good vs. what is a potential issue. The fix for each key takes less than one minute per key – you should not spend more time than that. The last step is to replace the spring or switch it with another key’s spring – often springs may be damaged during installation and once damaged, a spring may no longer be usable.
8. The first keys you should install are the ones 2U and larger. Due to the design of buckling spring keycaps, these keys are most likely to become stuck when pressed all the way down and require following these steps to fix such instances of key binding.
9. “The Wiggle Method” – the best Method if a key is stuck:  you have to do some of the below steps several times in some instances of binding. Do the steps, install the key and test with 10-20 key presses, then remove and do the steps again if needed.
   • Start with this step for keys with the stabilizer posts:  Gently pinch the affected key’s outer stem/ear and stabilizer insert pole between your thumb and forefinger and wiggle side to side about 20-30 times. Your fingers should be positioned so as to squeeze deeply into the key, as deep as possible, not just at the very end of the key stem. See the main setup video above which has a chapter on the wiggle method.
   • After squeezing, gently wiggle the key post (the part that goes into the stabilizer insert) 10 times in the direction of the left and right sides of the key if you were to look at the key as oriented on a keyboard – seems to eliminate binding when the extreme edges of a key are pressed. Be very gentle as this is the easiest part to break on a key!  Do not touch the stabilizer insert itself or add any lubrication to it.
   • If it is still stuck but maybe a little better, repeat the prior two steps and test again. Sometimes the two “wings” of the stem get stuck too close together so you have to gently spread them apart maybe a total of 1 mm or so. For 2U height keys like 2U Vertical (num pad area) and ISO Enter, some folks have reported that the horizontal/white stabilizer insert works better with the vertical keys instead of the vertical/black insert.
10. Best Method if the key is too loose and pops off:  you just need to gently widen the stem a bit without breaking it. The stem consists of the two “legs” that go into the barrel. It’s common for the larger key stems to be slightly too narrow or too wide. Please use the other keys’ stems for reference on the proper width. 
11. Other potential fixes – not necessary or recommended:
    • Burnish back side of the key stem – use model m nut driver.  This seems to improve key binding/resistance.
    • Keep stabilizer insert 1mm above top of barrel and there is no binding. Alternatively maybe add a 1mm piece of foam under side of key where stabilizer insert goes. Example story:  “It seems like the left barrel (the empty one) on the spacebar was binding a bit. I solved it by cutting a thin foam disk (about 2mm thick) and sticking that into the outer barrel on the bottom of the spacebar. This limited the travel just enough to avoid binding. Once that was done, the keyboard was perfect.” 
    • And one last method that worked: “I did add a little bit of Syncro Superlube and that did it.”
12. Remove and re-seat any loose/non-working keys. Regarding re-seating springs, in nearly all cases you do not need to take apart the keyboard to fix keys that do not click or spend a few minutes pressing a troublesome key. Reattach the key as shown in these videos, with the keyboard positioned as shown in the videos (vertically, with the spacebar row up).
13. Often re-seating a key is not enough to make the key work or to reduce or eliminate a buzzing sound when a key is pressed, and you need to remove and reattach the spring as shown in the QC secrets video. I have found that carefully removing and flipping the spring upside down can fix most spring issues, and replacing the spring with another spring is a last, but often necessary step. Springs must always be removed with a gentle twisting motion (it should come off easily – otherwise you’re twisting the wrong way), never pulled straight up. Twist counterclockwise looking at the spring straight down, like in the below picture. The goal is (1) to have the spring touch the 12 o’clock position of the barrel when the keyboard is positioned that way, and (2) have the end of the spring in the 12 o’clock position relative to the flipper, as pictured below. If the spring end is not positioned at 12 o’clock (per the video) and the spring does not touch the barrel, buckling error is more likely to occur.
14. The main Model F setup video above includes Quality Control Secrets chapter showing how to remove and re-seat a key using key puller and fix a buzzing spring.
15. Some folks report that after setting up the keyboard and connecting it to your computer to test each key with a keyboard tester program or web site, you should unplug the keyboard for at least 15 minutes while following the QC secrets video above to adjust any keys and springs that are flaky. Sometimes unplugging the keyboard and plugging it back in fixes a random issue you may be having.
16. If the key doesn’t press because the spring can’t move, the flipper may be stuck. Remove the key. Do the flipper and spring move freely in the barrel if you flick it?  Sometimes in shipping the keyboard is jolted so much that the flipper gets stuck and can’t move, and I have to carefully use tweezers to push the flipper back up into position to match the other flippers. Sometimes moving the flipper carefully with tweezers does the trick. Otherwise, you have to open up the keyboard to reposition the flipper (there’s a 2-minute video on that process embedded later in the manual). I am sure you checked every flipper to make sure it moved freely, before installing the first keycap, as noted earlier! If you didn’t, now you may have to remove all the keys, open up the keyboard inner assembly, and reposition the flipper. 
17. I strongly recommend tightening the two controller screws that ground the controller as they may have loosened as these keyboards are bounced around in shipping (if you see issues with holding down a modifier key and another key, or issues with key presses being out of sequence from what you typed when typing fast, fixing the grounding screws will likely solve the issue). Do not use the Keypress Monitor part of the pandrew utility as it does not function correctly.
18. If the spacebar is making contact with the keys above it: it is a matter of adjusting the shape of the spacebar stabilizer wire, and maybe putting some scrap foam or other material between the spacebar stabilizer wire and the back of the metal tab so that the stabilizer is moved upwards a bit – the spacebar needs to be moved farther away from the key it is making contact with, and that can be done by bending the spacebar and/or putting some material as noted above. Do not sand away parts of the keycap or do anything else on your own as it is unnecessary. “Putting a rectangular piece card stock vertically between the inner face of the tab and the wire did the trick” for one DT member.
19. There is definitely a break-in period with Model F keyboards – especially with the springs. There’s a good chance that the springs will sound even better over time with usage! Also pressing a key many times may fix an initially flaky key.
20. Now that the keys are all installed and you tested each key several times before this step, we are going to connect the keyboard to the computer for the first time!  Do one more check before plugging in your keyboard. Be sure you can hear the snap of the flipper when pressing each and every key. I like to press each key a few times to be sure of a reliable actuation. If you are just feeling the pressure of a spring when a key is pressed, but without a snap, that means you have not installed a key properly and many keys on the keyboard will not work, due to the way a pressed key confuses the autocalibration when a keyboard is plugged in. Many errors are from folks with one improperly installed key and they think there is a major hardware problem, when in fact it is user error with installation.
21. Open a keyboard tester web site. Be sure to plug the keyboard directly into the computer, not into a USB hub, and make sure there are no other connected USB devices besides the mouse (just for troubleshooting, to check for conflicts). Sometimes you may need to try other USB ports for some reason.  An important note on USB hubs and docking stations from one new Model F user: “Key presses would register or not register. Random text would appear while typing. Unusable. Turns out I was using a 4 port non-powered Anker USB hub. Works fine for my model M’s, and the rest of my keyboards BUT not the F77. I then plugged the F77 into a powered USB hub and all is good.”
22. If the keyboard is not detected – check that the USB cable is plugged in fully on the controller end of the USB cable as well. If you see “ATMEGA32 DFU” in your device manager (Windows), System Information (Mac), or “hardinfo” on Linux, you may have accidentally cleared the firmware and need to reflash it – see the advanced topics section to fix this. Also, try on another port and on another computer. 

23. This point is specific to Apple/Mac:  there is usually a pop up the first time you plug in a new keyboard on a Mac that lets you configure the keyboard (I have linked to it below).  If this does not show up, the other option is to go into Mac settings, keyboard, and switch the modifier keys (for command, select Option in the drop down menu, and for option, select command in the drop down menu). No extra software like Karabiner is required unless you want to make other remappings.  https://iboysoft.com/wiki/keyboard-setup-assistant-mac.html  Also, one key such as the right Ctrl key may be factory programmed as the Fn key even though it says Ctrl, so it will not show up on any keyboard testers.  This key cannot be remapped in software; you need to make a new firmware to change this (follow the steps in the Intermediate Topics section).

24. Test each key with the keyboard tester web site. An important note:  refer to the product page for the factory default layout. For example, the right Ctrl key may be factory programmed as the Fn key, so when you press this key it will not register as a Ctrl key and it will appear that the key is broken! 

25. One less common issue you may find is inconsistent key registration – double presses, key ghosting, keys not recognized, key spamming (extra keys when one key is pressed). Double presses and other issues could be related to the two controller ground screws not being tight enough, the seating of the spring on the flipper nub, or some kind of damage to the spring (the tops of the springs can get caught on something and bend out of shape – spring damage can’t be 100% fixed in my experience without replacing the spring itself), or the debounce filter and threshold (these two are xwhatsit firmware issues only-xwhatsit firmware stopped being used in early 2020). This is usually an issue with the way that the keys were installed (did you follow every step so far? If the keyboard wasn’t held upright and each key tested for the proper click beforehand, that may be the cause). For example, you may see double presses if the spring is not properly reinstalled, especially if it is not pushed down all the way onto the flipper nub or if the spring is not reinstalled with its end between 12 and 1 o’clock.  Don’t forget that one of the steps to fixing keys involves replacing the spring itself as shown earlier.  Sometimes, just restarting your computer (or a cold boot – turning it on from a powered off state) fixes the issue.
26. When testing, always make sure the xwhatsit controller is attached to the gold-colored bottom inner assembly with both ground screws. If, after you have followed these instructions completely and many keys in a row or column do not work, please follow the section on additional diagnostics through the pandrew utility. If one or a few scattered keys do not work, it is most certainly not a hardware error but instead a user installation error or debris that entered the keyboard and moved between the flipper and capacitive PCB, thereby interfering with the keypress signal.  That is why opening up the keyboard to check for debris is the last step to fix a nonworking key.
27. Does the rightmost row of keys get stuck when you press the key? Sometimes all of the keys on the leftmost or rightmost side may be stuck because they are too close to the case. Things may have shifted in shipping; all you need to do is loosen the 4 screws on the bottom and slide the mechanism away from the edge it is too close to, and of course tighten it back again when done. Also check to make sure the inner plates slide in fully so the sides of the tabs touch the sides of the bottom inner assembly (see photo below). If there is some space in between the tabs, then there could be issues with keyboard functionality.   The top left tab should be folded down a little to lock everything in place.

Next up, we will install the solenoid: 

Safety warnings:  It is very easy to permanently damage the solenoid and driver by doing something another way. If your solenoid does not work after installing it, you may need to update the firmware as a recent bug prevented the solenoid from working. Most importantly, do not overtighten the screw that attaches the L bracket to your keyboard case or it might puncture the solenoid. You may destroy your controller, solenoid driver, and/or solenoid by not following xwhatsit’s solenoid driver instructions as well as the below instructions.

The solenoid and required solenoid driver are optional add-on products not included with any keyboard. There is a built-in firmware shortcut to easily turn on and off the solenoid so you don’t have to keep the solenoid on all the time. They can be purchased through this link and are definitely recommended: https://www.modelfkeyboards.com/product/xwhatsit-beam-spring-or-model-f-controller/

1. Follow the solenoid setup portion of the main Model F setup video linked above (same physical setup for beam spring keyboards too!).
2. Solenoid drivers help you add a solenoid to your xwhatsit-powered Model F or beam spring keyboard. You need both a solenoid driver and a solenoid; they are not sold together. The solenoid driver does not include the solenoid or screws but it does include the cable to connect to your controller. When installing the solenoid, because the screw that secures the solenoid is at the bottom of the keyboard as shown below, you should use any of the slightly taller bumpers in the back (i.e., any option except the cork bumpers unless you double up and stack two of the cork bumpers, one on top of the other).  The Model M style case screws are countersunk so this would not be an issue for those keyboards.  If you happen to use the 1″ large bumper and its large screw please do not drive the screw so much that it breaks in to the blue tape – it will destroy the solenoid.
3. Why pick this solenoid over other solenoids or over IBM’s original solenoids? The new solenoids are far beefier than IBM’s originals, so your solenoid clicking will be even better! It’s a custom design that you can only order here. The specifications are 6v, 40 ohm, 0.15A, 0.9W, adjustable throw factory set to 1mm but with a user-adjustable range of about 0.5mm to 5mm (there are 2 screws that can be loosened to adjust the distance of the strike bar). This solenoid has the dark blue outer covering, black and white twisted wires and 2.54mm connector like the original IBM solenoids, but with a strike bar so it won’t exactly resemble the IBM solenoid. This solenoid is not the one that’s available elsewhere, though it looks similar and the voltage and resistance specs are the same. Also that other model doesn’t have the adjustable throw – you would have to spend time milling the strike bar to modify it for correct usage with the solenoid drivers. Also, my solenoid is even larger than the other solenoid, the 26mm height dimension on the other one is set to be ~29-30mm on my solenoid (the solenoid goes sideways in F62/F77 so it fits) though all the solenoid specs are subject to change. With a larger metal frame, my solenoid should be a little louder than the other model and far louder than the original IBM! These solenoids are also a great option as an upgrade to IBM’s original solenoids too (I’d always save the originals of course for the sake of completeness).
4. Most important is to match the square on both sides of the ribbon cable connector, so that you connect the squares (voltage line) to each other. The position is different from what is pictured online, from other xwhatsit controllers, and from the photo below. If you install the cable the wrong way you will destroy your equipment. If unsure, do not connect it!  The square pad indicates VCC and that wire should go to the VCC square pin on the solenoid driver itself. Connect square to square – voltage pin to voltage pin. Per orihalcon:

5. Regarding the xwhatsit Model F expansion header pinout: note that it is different from the original xwhatsit controller – you can damage the controller and other hardware by improper connections to the expansion pins. Below is the pinout on the new Model F xwhatsit controllers. Head over to the deskthority and geekhack forums for any and all questions related to the xwhatsit controllers.

6. For the solenoid and solenoid drivers: see the images below for the general installation procedure of solenoid drivers. By default, the solenoids are not set to the maximum throw length: to get the full solenoid experience, slightly loosen the two screws on the solenoid and move the bar as far out as it will go, then tighten the screws.

Adjust screws on solenoid, then slide out the bracket for maximum sound, so it looks like the below photo:

Advanced solenoid configuration – only if using firmware files outside of the project web site.

Due to factory default QMK settings, the solenoid will only be under full power if the dwell time is set properly. If you are using any of my hex files for either QMK or Via, this is done for you automatically. However, if you use the QMK Configurator web site to make your firmware, import my JSON template file for your configuration and flash the firmware (see the firmware section of this manual), and while the keyboard is connected to your computer, hold down the keys Fn+Spacebar++= (the + = key next to backspace) which has been preprogrammed to increase the Solenoid dwell time by 1 ms. Press it 20 to 25 more times to get it to the minimum required amount for full power. You can also press the following options
Fn+Spacebar+T–>Toggle the Solenoid On/Off
Fn+Spacebar+ -_ Decrease Solenoid dwell time HPT_DWLD. Refer to the two solenoid videos at the top of this page for a visual guide. To program this into your own keyboard, for QMK drag the Any key to the key and layer you want, and then type in HPT_TOG to toggle, HPT_DWLI to increase the dwell time 1ms, or HPT_DWLD to decrease it. Each key has to be in its own box of course.

1. Download the latest pandrew utility which is in the comprehensive firmware zip file: https://www.modelfkeyboards.com/wp-content/uploads/2020/07/QMK-layout-files.zip For Mac, please note that the binary is not signed – you’ll need to “Open” manually in Finder. Ctrl+double click maybe?  Per pandrew:  For “Linux – you have to build it:
   git clone http://purdea.ro/qmk_firmware/
   cd qmk_firmware/keyboards/xwhatsit/util/util
   Read README.md for instructions on how to build”
2. With the keyboard in its normal horizontal position with all keys properly installed and tested, plug in the keyboard, load the utility program, and click Signal Level Monitor. Then remove the keys at issue. Use your fingers to move the spring, to make sure it moves freely and make sure the flipper is not stuck. The flippers would then freely make contact with the PCB. If you see the middle number of three numbers for each key being a solid green when the flipper is left alone, very close in numerical value to the bottom number for that key, that means there’s an issue with the installation of the key or of the spring – see if the flipper moves freely and the middle values change when the key is removed, if you rotate the keyboard vertical, spacebar side up, and then flat. Here’s how the matrix should look in the QMK utility after you have pressed each key one time and opened the Signal Level Monitor window in the pandrew utility program. The keys that stay red represent pads without flippers (may vary based on layout). 
3. If the middle row changes to green without an installed key, that means that you need to adjust the spring by following all of the steps detailed earlier. Removing and reseating the key again and again without doing anything else is unlikely to work.
4. 
5. If you see something like the below example (indicating a bad matrix row), then you’ll need to do some touching up of the solder. As you can see further below, the traces in the keyboard controller matrix do not correspond to actual rows of keys.
6. 
7. Now switch to the matrix view:  In the matrix view (screenshot below) you will see 3 pressed signals; these are not actual keys that are pressed. There is one key in the 16th column:  the bottom right physical key on the keyboard. With this view you can more easily see if a row or column is damaged.
8. 
9. If many keys read “0” for the value, then there is possibly a short to ground and it is best to add a couple layers of insulating tape (polyimide/Kapton, electrical, Super 33, etc.) to the bottom of the controller where the ribbon cables are. This is more likely to happen to the ultra-compact cases as they are bounced around in shipping and the ribbon cable may break through the factory-installed tape. If entire areas of the keyboard are not working and you are using an ultra compact case, sometimes the ribbon cable wire has broken through the Kapton / polyimide tape and is touching the case – one or more entire columns or rows would not function. In this situation, you would see the problem go away when the keyboard inner assembly is outside of the case. While the controller is installed and the keyboard is upside down with supports on either side (e.g. a book or something) so that the keys do not get pressed, push down on the part of the controller with the ribbon cable so that the ribbon cable end of the controller moves about 1-2 mm closer to the bottom inner assembly (gold color) plate – so as to move it away from making contact with the bottom of the case.
10. If the row or column reads a value higher than 0 (example: 110) but does not respond to key presses, then maybe the row or column needs more solder applied to the through hole, on the controller and/or on the capacitive PCB. This also unfortunately does happen after these keyboards are bounced around in shipping, but the good thing is you don’t have to open up the inner assembly at this time. It is rare as I confirm each column and row before shipping, but it has been documented a few times. The controller is fine; you just need to add more solder to the holes for the ribbon connections for the missing column, on the PCB side of the components (see red rectangle in second photo below – doesn’t indicate the specific columns for you to solder – just a general photo). Just make sure you don’t touch any of the components themselves, just the column. No need to add solder on any of the other connections unless the connection looks like it needs more solder.
11. If the right ctrl on F62 or the right arrow key on the F77 (bottom right key) is not registering in the pandrew utility with the key removed, that usually means that column 16 needs to be retouched. These keys are special in that only one key is in column 16.  Some folks think the key is broken because it does not register as Ctrl when pressed, but did not read the product page which notes this key is factory programmed to Fn for some layouts.
12. How do you find out which row or column needs more solder?  In the bottommost image below of the PCB traces, you can see the traces that the keys that don’t work are located. For example, left alt, right alt, V, spacebar, M, the < , key, the key between right alt and right ctrl, and right ctrl are all on the same trace even though they are not on the same physical row. You can follow the red line in the image and see that they are all connected to the leftmost trace, which is connected to the third through hole from the left, so that would be the area to touch up. You need to add solder from the side of the controller components, not the bottom of the controller (just unscrew the two controller screws and gently bend the controller back as shown in the below photo). You should carefully add solder to the large capacitive PCB (the other end of the ribbon cable for the same through hole you added solder to on the controller side). Important note:  you should not open up the inner assembly for this procedure:  you should add solder from the side that you can see and access already (the underside of the large capacitive PCB shown in the below photo with the controller). An important note that the row and column numbers shown in the controller image below should be disregarded for this purpose – just follow the traces and solder the one where all keys on that trace do not work.  Only if there is still a problem after following these steps and retesting should you open up the inner assembly and remove the large capacitive PCB to inspect for shorts as shown below.
13. 
14. Do two keys press when you press one key?  Occasionally there will be a solder bridge connecting two rows/column traces together, either somewhere on the PCB or specifically on the 30 through holes at the top of the board. Just remove the bridged material carefully and then all will be well!  Most likely the bridge is on either end of the ribbon cable wires but occasionally it is on the large capacitive PCB itself as shown below.
15. 
16.  
17. For example, if the keys 2 Q W A S Z X and Left Alt do not work, then the second grouping of columns in the matrix below are at issue. You can see that the 14th through hole from the left connects to the column that includes all those keys, so you would solder that through hole on both the front side of the controller (unscrew the controller as shown above) and if that doesn’t solve the issue, also add some solder to the accessible part of the large capacitive PCB-do not take apart the keyboard for this; just add from the bottom side that you can access with the inner assembly upside down.

Firmware adjustment, changing the keymap or layout

• If you so choose to update your firmware, please exclusively follow the instructions below to get started – do not follow any generic guides, use files provided elsewhere, or go to the generic home pages for these keyboard firmware files as they will not work. Other QMK configurator pages will not work with Model F or beam spring keyboards. 

• Safety note:  updating firmware is done at your own risk. From what I have seen, it is nearly impossible to brick the keyboard controller. At the very worst you have to open up the keyboard to short PROG on the actual xwhatsit controller (unscrew the 2 controller screws to see the components side of the board, make a connection with a conductive metal object like an uncoated metal paper clip, then connect the USB cable to the controller and within a split second remove the paper clip). Per pandrew:  “You might think that a screwdriver is gonna be enough, but due to surface oxidation it is likely not gonna be good enough. I like to use sharp metal tweezers, because they can dig into the pad a little bit, breaking up the surface oxidation, and I can actually be sure it’s shorting. Apply constant strong pressure on the pads while plugging in the keyboard to make sure they’re perfectly shorted. If you hear the windows USB plug-in sound (assuming the sound effect is enabled), then you know you have succeeded. I’ve even seen people tell me they tried everything to short the pads with, and then I asked them to solder the pads together and it suddenly works. There’s something about the size of those pads, or about the fact that they need to be shorted in the perfect moment when the chip leaves reset, that make people think they are perfectly shorted and yet they aren’t. This affects me too, sometimes it takes me up to 3 tries to get it into bootloader mode. Another thing to double check that you are indeed shorting the PROG pad and not the reset pad. I believe in some versions of the wcass controller there is a reset pad on the opposite side of the board. So don’t be like ‘I see some pads, those must be it’, make sure to be shorting the correct ones.”

Download the firmware and pandrew utility files (Vial and old QMK): 

Please note that all files are provided AS IS, without warranty. 

https://www.modelfkeyboards.com/wp-content/uploads/2020/07/QMK-layout-files.zip

The Linux version can be compiled from here, among other sources (the utility must be run as a super user):  http://purdea.ro/qmk_firmware/

Regarding the Mac utility, please note that the binary is not signed – you’ll need to “Open” manually in Finder.  Ctrl+click, then Open.

Vial may not be preinstalled on your keyboard.  You will have to flash the firmware for Vial before you can use Vial.  All firmware is in beta.  After you flash Vial, you are able to update the firmware whenever you want, without needing to reflash the firmware every time.

Flashing in Windows:  open the pandrew utility and click Enter Bootloader. 

This paragraph of steps only needs to be done one time, if this is your first time flashing atmel firmware on a particular computer:  After clicking enter bootloader, install atmel flip 3.4.7 (or extract its contents with 7zip), then go into the device manager to install the driver for the atmel device.  During the wizard, point the location of the driver files as the Atmel folder in your program files folder (or to the atmel folder you extracted).

Then double click the bat file for your keyboard, from the above linked layout files.  For example, if you have the F77, double click the file “flash-allpads-f77.bat”

Using Vial:  two options

After loading the Vial firmware (if it is not pre-loaded), you can go to the website vial.rocks with any Chrome, Opera, or Edge and you can edit the layout that you want, no software needed.

If you use another browser or prefer the downloaded version of the Vial software, you can also use that.  The keyboards are all recognized right away with either option.

Currently Vial is preloaded on the Round 1 F104/FSSK and on the F15, F50 and F Split Ortho keyboards, with more to follow.

To flash firmware on Apple/Mac computers:  Use the QMK Toolbox https://github.com/qmk/qmk_toolbox/releases

And follow this guide: https://www.instructables.com/DFU-programmer-on-Mac-OS-X/

Flashing firmware on Linux:

A guide from a geekhack forum member:

Follow the directions in the YouTube video for using the beta QMK configurator site to customize the layout and compile new firmware, up to downloading the new firmware.
Install dfu-programmer. For Fedora 34:

dnf install dfu-programmer

Enter keyboard bootloader. On the keyboard, hit: + + 

Check if bootloader is detected. Look for a USB device listed as “atmega32u2 DFU bootloader” (using another keyboard):

lsusb

Erase and flash new firmware (the hex file downloaded from configurator site):

sudo dfu-programmer atmega32u2 erase
sudo dfu-programmer atmega32u2 flash /path/to/fw.hex
sudo dfu-programmer atmega32u2 launch

Disconnect, then reconnect keyboard.

Building the pandrew utility on Linux:  
git clone http://purdea.ro/qmk_firmware/
cd qmk_firmware/keyboards/xwhatsit/util/util
Read README.md for instructions on how to build

Current preprogrammed keypress commands in Vial and QMK:

Hold down the keys Fn+Spacebar+
T–>Toggle the Solenoid On/Off Any key HPT_TOG
+= Increase Solenoid dwell time HPT_DWLI
-_ Decrease Solenoid dwell time HPT_DWLD
E–>EEPROM Reset (erases all settings like if you adjusted a dwell time for solenoid)
R–>Reset (enter bootloader)
D–>Debug

Command keys: hold Left Shift + Right Shift +
Esc–>Enter Bootloader
B–>Enter Bootloader (alternative)

N–>Toggle N-Key Rollover (NKRO) (off by default to maximize compatibility)
Others: https://beta.docs.qmk.fm/using-qmk/advanced-keycodes/feature_command

For Beam Spring Keyboards:  QMK configurator web site method – no longer recommended for models with Vial support (currently all new Model F keyboards) but still the best way to update your new beam spring keyboard.  The beta QMK configurator is the only one that currently works with Model F keyboards – the main QMK Configurator site is not yet working with Model F keyboards. Please join the Deskthority.net forum for any questions (they currently do not accept certain free email addresses such as Gmail). When using the QMK configurator, always select the “wcass” controller version in the list – do not select the universal or xwhatsit version as those are for other controller variations. Beta QMK configurator link:  http://35.164.28.200:5000/#/xwhatsit/brand_new_model_f/f62/wcass/LAYOUT_all

Opening up the keyboard inner assembly, changing case styles, etc.

1. Here is the project’s YouTube channel which has a lot of videos on assembly and disassembly, quality control secrets, troubleshooting, solenoid installation, etc. https://www.youtube.com/@Brand_New_Model_F_Keyboards
2. Make sure all the keys are removed from the keyboard before opening up the inner assembly! See this two-minute video of mine:  https://www.youtube.com/watch?v=81RnxtdIExc
3. Keyboard disassembly note: if you are not applying enough pressure on each screw, it is possible to strip the screws. With the correct driver and pressure, the screws should not be an issue. If driver is not a tight fit, do not use the driver and purchase the correct driver-otherwise the screw will strip and you may not be able to remove the case except by drilling into the screw.
4. Some layout changes are possible (open up inner assembly and move flippers around so they correspond with the layout you want) – e.g. change from ISO to ANSI or vice versa, split or unsplit the backspace, Left Shift, Right Shift, Enter, spacebar keys.
5. You probably want to bend the larger tabs outwards a bit before clamping down as this may make it easier to close.
6. When opening the inner assembly, the important thing is to first widen the top inner assembly’s taller tabs so they are farther away from the bottom inner assembly plate.  Then slide the bottom tabs together until they can’t slide any further (at this point the top tabs should not be engaged – the plate should stick out and not be fully pressed down).  Then you can use one pair of pliers to press down near one tab, and use another pair of pliers to bend the tab inward to lock it in place, and then repeat for the others.  The last tab (the rightmost one when the part is upside down) is the locking tab so pay extra attention to securing this tab.
7.  
8. You can also change cases for most models. To change from the large case to the small case or vice versa: remove keys, open up keyboard case and bottom inner assembly while keeping keyboard upside down, then switch to the alternative bottom inner assembly metal plate.
9. You can’t change HHKB style split right shift to standard or vice versa unless you purchase another PCB, top inner assembly, and inner foam as the keys are in slightly different physical location.

• As noted in the Model F Project Philosophy, the Model F is designed to be your keyboard for decades, just like many of the originals still clicking after nearly 40 years!
• Model F Cleaning:
  • There are many Model F cleaning videos.  Always keep your keyboard unplugged during cleaning and while things are drying.  Always let your keycaps air dry overnight in a non-humid place with a good amount of air flow.  Never reinstall keycaps after only a few hours of drying as there will still be some small droplets that will interfere with keyboard operation later on.  Here’s the first result from a YouTube search:  https://www.youtube.com/watch?v=wPOe0Pmd3gs
  • The important thing is to use only mild dish soap and lukewarm water.  I clean my Model F and Model M keys and barrels, but not springs/flippers, in an ultrasonic cleaner just like what was done in the above video posted by someone else.  I almost never clean the flippers/springs unless there is a residue that cannot be removed with a dry cloth.  Always wait a day before putting the keys back on.  There are so many crevices inside the keys for water to get stuck and this will cause operational issues if they do not air dry.  A fan blowing on the keys, all on a large towel works well.  I gently clean the case with soap and water, and sometimes very carefully with a melamine sponge (be careful as this can take the paint right off and cause damage).
  • Don’t get the controller wet or you will damage it or potentially cause a fire.
• Liquid spill: First thing to do is take apart the keyboard.  You need to take it apart and dry out everything.  Spilling anything probably requires scrubbing each flipper and the PCB with mild dish soap and water and letting them air dry for a day.
• Floss mod:
  • https://geekhack.org/index.php?topic=9761.0
  • https://deskthority.net/wiki/Dental_floss_mod
  • https://deskthority.net/viewtopic.php?p=468281#p468281
  • https://geekhack.org/index.php?topic=79141.msg2941878#msg2941878
  • Key sound reduction discussion – floss mod, etc.: https://deskthority.net/viewtopic.php?p=463382#p463382
  • “Floss mod can increase key weight (especially if the floss is longish, but not long enough to prevent actuation).” https://deskthority.net/viewtopic.php?f=2&t=22175
  • Example floss mod YouTube sound test
  • Example floss mod YouTube 2022 test
  Grease mod/Soft Touch mod
  • In addition to the floss mod described on the Geekhack/Deskthority keyboard forums, another mod to consider is the grease mod, researched and described by the below YouTube user.  Also in my research I have found that pressing the springs down all the way on the flipper (normally there is a 0.2 to 0.3mm gap) reduces the ringing.  I do not offer and have not tried any of these mods but below is some information to consider.
  • The purpose of the grease mod is to reduce the reverberation/ringing after each key is pressed.
  • His comments are copied directly below.
  • Apply Synco Superlube on the inside of the spring with a metal probe…just enough to dampen the vibration
  • As an experiment, I tried a few switches on an XT F. I did nothing to the first XT F in the video…you can hear the sound I’m referring to…it’s like a super-loud, much more intense, sharper and “drier” version of what my (in superb condition) 1988-1989 Model M boards sound like. Then on the second board, I did the Alps spring lube trick on the keypad only. The feel is the same, the click sounds great (to me), the actuation force is ever so slightly less. But the annoying (to me) spring noise virtually disappears.
  • video 1 – detailed key sound (lubed keypad; unmodified other keys):  https://www.youtube.com/watch?v=Kha_cvhZBp8
  • video 2 – typing demo of the unmodified F:  https://www.youtube.com/watch?v=d1j1g-xLF6k
  • video 3 – typing demo of the fully spring lubed F:  https://www.youtube.com/watch?v=yqvr-U9CEuY

  Dab of glue in barrel mod: (placed approximately in the spot of the number 7 mold cavity number below; so that the return of the flipper does not make as much noise)

  Great series of videos showing different new Model F keyboard mods by DT user Twst (floss mod vs. no floss, buzzers, beepers, different solenoids, etc.):  https://www.youtube.com/channel/UCh7FbPSydoafCYMgLrCfk1w/videos
   

  Trackpoint mod – adding a trackpoint to your New Model F keyboard

  SUCCESS Trackpoint MOD!

  Here’s a link to the photos from silentbob’s Brand New Model F trackpoint mod.

  https://imgur.com/a/Sp7sfYO

  “I used the Unicomp M13 trackpoint but the others I mentioned will also work. I used the unicomp controller and have two USB cables running out the back. If the current controller has any extra inputs that handle PS2 or some unused GPIO pins then it could be integrated into the existing controller with the stand alone SK8702 trackpoint controller. I plan on going bluetooth in which case I can join the two controllers through a hub internally and not have to worry about two controllers and cables. I used the Unicomp GHB keys with the cutout to clear the trackpoint.”

  Additional non-Model F trackpoint guide:  https://deskthority.net/viewtopic.php?f=7&t=16643&start=

• Bluetooth wireless mod:  see additional information here – https://www.modelfkeyboards.com/a-bluetooth-wireless-model-f-keyboard/

Project Philosophy: Full user control of product maintenance and repairs

Goal:  the best quality product at the lowest price point, with a focus on the end user being able to stockpile spare parts as well as set up and fix their Brand New Model F. There are definitely markets for hardware with service contracts. Not sure about a market for a +$100 more costly keyboard with full maintenance and technical support though. IBM’s 1980s price guides mentioned they would require charging banking customers a minimum of about $100 per year (not adjusted for inflation) for each original Model F keyboard in maintenance costs as part of a service contract. However, if I had to hire staff to deal with “free” returns, more personalized technical support / phone support, and doing even the most minor repairs (re-seating keys, replacing springs and barrels, changing the USB cable, etc.), each keyboard would cost a lot more because of overhead costs, and these keyboards are already not inexpensive to begin with. And it would slow me down even further mailing out these great keyboards. I believe that this direct to consumer, community type project is the best way to bring the Model F to as many people as possible and at the lowest possible cost.

Read more about the mission statement of the project on the About page:  https://www.modelfkeyboards.com/about/

Original Model F Topics; 12 Misconceptions about the Model F Keyboard – what initially scares many people away

• All the ways to make your IBM Model F work with USB
  • I strongly recommend using the original F122 controller with Soarer’s converter (plugs into the IBM controller). It’s what I’m using on all my F122 keyboards. See the attached ZIP file here for some helpful tips gathered from my own experiences and from others.
  • Removing the original controller is not a good idea as the traces are at risk of damage during the desoldering process (has happened to me) and it is completely unnecessary for the F122. Controller removal is only required for the metal case Model F Keyboards (F50, F62, F77, F107).
  • Instead of a $25 teensy I also use an ATmega328 / ATmega32U4 style Pro Micro which is readily available under $10 shipped on eBay.
• What is the foam for, and do I need to replace it
  • The foam probably served two purposes: first to reduce the possibility of dust and debris entering the inner assembly and affecting the capacitive key sensing, and second, to reduce wobbling of barrels and ensure they are tightly against the capacitive PCB (the large PCB underneath all the keys).
  • New inner foam is strongly recommended to restore all Model F Keyboards (I have foam available for all Model F keyboards except the XT style). I recommend ordering an extra 1-2 pieces as the foam has a limited installed life (while compressed inside the keyboard it loses its resiliency over time and develops compression set, meaning the foam does not rebound to its original thickness). The extra foam should last for years if stored not in a keyboard, in a sealed plastic bag in a climate controlled area. Once production shuts down you won’t be able to purchase it and I’m the only maker of new factory cut Model F foam.

• 12 Misconceptions about the Model F Keyboard – what initially scares many people away:  https://www.modelfkeyboards.com/misconceptions-about-the-model-f-keyboard-what-initially-scares-many-people-away/

A beginner’s guide to full configuration of QMK/Via:

Note:  this is completely unnecessary to do unless you want to change options that cannot be changed in the QMK GUI / Vial GUI. It is a local way of compiling the firmware through the command line to update the factory default solenoid dwell times, add in darkcruix’s patch for excluding certain keys for the solenoid, allow NKRO but disable it by default, etc.

July 2023 note:  given major changes to QMK recently, it is best to use an older version until the Model F QMK is refactored, if you are compiling your own QMK instead of using the QMK configurator.  Per a DT forum member:  “I found that I need to go to ./qmk_firmware and “git checkout 0.18.10″, or well, presumably 0.18.17 or prior, because on the qmk_firmware github the next version is marked as breakpoint”

pandrew’s Model F QMK documentation / manual can be found here: https://deskthority.net/viewtopic.php?p=480196#p480196

Note:  xwhatsit firmware is now deprecated in favor of the newer QMK firmware which was ported over to the Model F xwhatsit controller in 2020. To see whether you are currently running QMK or xwhatsit firmware, go to Devices and Printers (Windows) and it should say ibm_capsense_util for xwhatsit firmware and “Brand New Model F Keyboard” for QMK firmware.

New procedure from scratch Ubuntu install:
download and install Ubuntu in a Virtual Machine

open Terminal program and enter one line at a time:

sudo apt update && sudo apt upgrade -y
sudo apt install python3-pip
sudo python3 -m pip install qmk
echo “PATH=$PATH:$HOME/.local/bin” >> ./.bashrc
sudo apt install git
qmk setup

git checkout 0.18.10 –recurse-submodules
mkdir qmk_firmware_andrei
cd qmk_firmware_andrei
git clone http://purdea.ro/qmk_firmware/

do this action-not a command in terminal
copy keyboards/xwhatsit folder to qmk_firmware/keyboards folder
the xwhatsit folder has all the changes in QMK

code changes to make
config.h in the folder of the keyboard you want to update – for example, keyboards/xwhatsit/brand_new_model_f/f77/wcass
lines ~286-287
#define SOLENOID_DEFAULT_DWELL 20
#define SOLENOID_MIN_DWELL 20

comment out (put // in front of) line ~28:
//#define DESCRIPTION QMK firmware for the modelfkeyboards.com reproduction of the IBM Model F keyboards
comment out lines ~199-202:
//#ifndef LINK_TIME_OPTIMIZATION_ENABLE
// #define NO_ACTION_MACRO
// #define NO_ACTION_FUNCTION
//#endif

in config.h, add #define NO_HAPTIC_MOD  – commenting this out should enable the solenoid for modifier keys

in rules.mk:
NKRO_ENABLE = yes # USB Nkey Rollover
add this line at bottom:
LTO_ENABLE = yes # Link Time Optimization – reduces file size
HAPTIC_ENABLE = yes
HAPTIC_DRIVER = SOLENOID
(delete the original haptic_enable line in the rules.mk file before adding the new lines above)

Per BuccoBruce2, “copy the contents of the tmk_core directory from pandrew’s repo into your qmk_firmware folder. Do not overwrite any existing files – they’re probably newer.”

put the json file with your custom layout (the file you created in QMK configurator) in the root of the Home folder
command to set the keyboard – can change F77 to F62 in this example if you have an F62:

qmk config user.keyboard=xwhatsit/brand_new_model_f/f77/wcass
qmk compile “../1.json”
it will give a random name and place the file in the root qmk_firmware folder – not the name of the json file, so if compiling multiple layouts, rename the newly created hex file before proceeding to compile the next layout
../ means go up one folder from qmk_firmware folder

examples:
qmk config user.keyboard=xwhatsit/brand_new_model_f/f77/wcass
qmk compile “../F77_-_ANSI-ISO_-_0-9.json”

to then switch to compiling f62’s:
qmk config user.keyboard=xwhatsit/brand_new_model_f/f62/wcass
qmk compile “../F62_-_ANSI-ISO_-_Regular_2U_or_Split_Backspace.json”
qmk compile “../F62_-_HHKB_-_Regular_2U_Backspace.json”
qmk compile “../F62_-_HHKB_-_Split_Backspace.json”
qmk compile “../zF62_HHKB_split_right_shift_only,_everything_else_ANSI.json”

Compiling/running the xwhatsit capsense utility on Linux:

For Ubuntu:
1. Open the Software & Updates program and select Community-maintained free and open-source software (universe)
2. Extract the precompiled file into a directory
3. Open a terminal and cd into that directory
4. In a terminal run: sudo apt update && sudo apt install gcc gcc-avr avrdude
5. sudo apt install build-essential
6. sudo apt install qtcreator
7. Run sudo ./ibm_capsense_usb_util

The below information was provided by Geekhack member joneslee85 to help with troubleshooting on linux:

* Problem: Linux config tool won’t build with GCC 6.x due to an
intentional breaking change in GCC’s handling of “-Isystem”.
One possible workaround: build the tool and all C++ dependencies with GCC 5.4.x

joneslee85 workaround:  I managed to workaround this issue by sub the -Isystem with -I:

Code:
sed -i ‘s/\-isystem \/usr\/include/\-I\/usr\/include/g’ Makefile

Below is the full code I do on Fedora 32:

Code:
sudo dnf install avr-gcc avr-libc qt5-devel hidapi-devel glibc-headers make gcc
wget https://static.wongcornall.com/ibm-capsense-usb/0.9.0/ibm-capsense-usb_0.9.0.tar.gz
tar xzvf ibm-capsense-usb_0.9.0.tar.gz
cd ibm-capsense-usb_0.9.0/src/util
qmake-qt5 ibm-capsense-usb-util.pro
#replace `-isystem /usr/include` with `-I/usr/include` # Ref: https://bugzilla.redhat.com/show_bug.cgi?id=1835441
sed -i ‘s/\-isystem \/usr\/include/\-I\/usr\/include/g’ Makefile
make

# binary is now in src/ibm_capsense_usb_util

And here are some pandrew utility compiling instructions quoted from Deskthority member NathanA:

pandrew util sources are in his repository, so it all exists under qmk/keyboards/xwhatsit, in a directory called “util”.

At least on Windows, the pandrew util I pretty much build just the same way that he left behind instructions for. (In the “windows_crosscompile” subdirectory.) The main exception is that his instructions encourage you build a docker container, but instead, if you look at the “Dockerfile” file in there, any line that begins with “RUN” you can just copy everything after the word “RUN” and paste it into your Linux shell. The disclaimer is that it assumes a Debian-based Linux distribution is what you are compiling on (which includes Ubuntu). So, apt-get all the packages it says to, then clone the “mxe” repo, and then build the “qtbase” and “hidapi” packages, all as it shows in that Dockerfile. Then run the commands “2a” and “2b” in the README.md file in the “windows_crosscompile” directory.

To update it to support new keyboards, you need to run “python generate_layout.py > kbd_defs.cpp” as it explains in the main README.md that’s in the “util” subdirectory (the one that has all the source code and where you do the build). That command goes through all of the keyboards you have source code for in qmk/keyboards/xwhatsit and automatically learns any new keyboard models and layouts you added there.

Building for Linux is actually extremely tricky, because there isn’t just one “Linux”. There are a whole host of Linux distributions, and you really need to compile a Linux util binary on whatever distribution and version you want to support, if you want it to be guaranteed to run for somebody trying to use the same distribution and version. That means that for Redhat-based Linux distributions, for example, you need to figure out how to install all of the dependencies needed to compile it on that particular distribution…if you compile on Ubuntu, there is no guarantee the result will run on non-Ubuntu. In fact, if you compile on Ubuntu 22.04, there’s no guarantee it will even run on anything but Ubuntu 22.04. It might, it might not. And trying to build Linux versions of pandrew for every conceivable version of Linux that exists out there that someone might be using is likely going to be an exercise in madness.

Additional notes on solenoid configuration in QMK: 

For xwhatsit firmware, you need to follow the xwhatsit manual to turn on the solenoid in the xwhatsit capsense usb utility program. To enable a key to turn it on and off:  as posted by forum members on Deskthority, the solenoid switch is found as “Exp Toggle” in the keymap dropdown in xwhatsit capsense software. I placed it on a layer so I could turn in on and off as I see fit. For QMK you just need to choose the “Any” key and then type HPT_TOG or any of the other QMK options. If you do not know how to do this you’ll need to review the QMK manual for more information.

| Name | Description |
|———–|——————————————————-|
|`HPT_ON` | Turn haptic feedback on |
|`HPT_OFF` | Turn haptic feedback on |
|`HPT_TOG` | Toggle haptic feedback on/off |
|`HPT_RST` | Reset haptic feedback config to default |
|`HPT_FBK` | Toggle feedback to occur on keypress, release or both |
|`HPT_BUZ` | Toggle solenoid buzz on/off |
|`HPT_MODI` | Go to next DRV2605L waveform |
|`HPT_MODD` | Go to previous DRV2605L waveform |
|`HPT_CONT` | Toggle continuous haptic mode on/off |
|`HPT_CONI` | Increase DRV2605L continous haptic strength |
|`HPT_COND` | Decrease DRV2605L continous haptic strength |
|`HPT_DWLI` | Increase Solenoid dwell time |
|`HPT_DWLD` | Decrease Solenoid dwell time |

Buzzer/beeper specifications: per a Deskthority forum member:  “You want to look for a low powered mini speaker rated around 0.5 W (or lower) and maybe 8Ohm.”  And here’s a post on buzzers/beepers mentioning 50 ohm 0.5w seeming to work for one user:  https://deskthority.net/viewtopic.php?p=463031#p463031 
A video of the beeper functioning on a new Model F:  https://www.youtube.com/watch?v=VIwJYRNhpck

NKRO note as relayed to me

Why there is not NKRO by default: When the USB Human Interface Device protocol was designed, they had a limit of 6 keys in there. This is the minimum all systems agree on (including BIOS etc.). NKRO is not standardized and there is a good chance, the keyboard doesn’t work in certain circumstances. In fact, on a Mac you can’t get into the recovery mode or NVRAM. On a PC, it depends on the UEFI designer, but I have seen problems with HP laptops.

Deprecated xwhatsit firmware-specific instructions:

One of the main reasons for the two additional beta firmware options above was that a number of folks had issues with the xwhatsit requirement to manually set the threshold value as the auto setting did not work. If they switched the keyboard around to different computers the threshold value may not always be 100% good with xwhatsit firmware. The other firmwares improved upon xwhatsit by offering a working auto-calibration of the voltage threshold and improving the auto-calibration into many calibration zones on the keyboard as opposed to xwhatsit’s requirement to have one voltage threshold for all keys.

Download the latest xwhatsit firmware

Link to download open source xwhatsit software, firmware, and PCB files

xwhatsit describes the technical underpinnings and background of his project

xwhatsit’s thorough manual and guide to using his controllers

Linux precompiled file (if you have trouble compiling)

How to compile the xwhatsit original firmware hex file on Linux (easier to do than on Windows):

For Ubuntu:
Open the Software & Updates program and select Community-maintained free and open-source software (universe)
In a terminal, run: sudo apt update && sudo apt install make gcc gcc-avr avrdude avr-libc build-essential
To get patch files from GitHub, click on the commit and in the URL, append .patch and then save that as a .patch file. pandrew’s work to create 0.9.2 firmware can be found here: https://github.com/purdeaandrei/ibm_capsense_usb_mods/commits/master
Move the patch files into the src directory
In the terminal cd into the src directory
To change the files based on a patch file, run patch < filename.patch
Run patch files in order from oldest to newest (start with debounce patch, then patch 1, then patch 2, then patch 3 (the latter three patches from pandrew).
Run make and copy the ibm_capsense_usb.hex file that was created
The default debounce is 11. To create the debounce 6 version, edit the scan.h file and change the line with #define SCAN_DB_THRESH_TOP 11 – change to a 6 (I use the debounce 6 version when sending out the Brand New Model F keyboards)
Run make and copy the ibm_capsense_usb.hex file that was created

The open-source controller PCB files used in this project can be downloaded here:  updated_PCB_files.

Important Keycap Removal note (not in the video below):  I use a wire key puller with gentle rocking motion and have no issues removing the caps.  If you are using a lot of strength to pull them straight up or twist them, then you will most certainly break the modules and this will not be covered in the warranty (user damage).

Here is the step-by-step setup video for beam spring keyboards.  Follow this video exclusively to set up your keyboard and perform troubleshooting.

https://www.youtube.com/watch?v=RqZCgUF8RWk

The next two videos show beam spring typing tests (first video link) and testing of beam spring modules (second link below).

https://www.youtube.com/watch?v=Ip-L0e1aBmI

https://www.youtube.com/watch?v=4AywyTyvsAs

This link shows a page from the IBM manual on how to reattach the beam module if the flyplate (beam metal part for beam flipper) detaches.  This is by far the most common issue that comes up.  https://deskthority.net/wiki/images/c/ca/Manual3.gif

This video shows an alternative way to reattach the flyplate.  I find this method to be very helpful.  https://www.youtube.com/watch?v=vc6LwIjzduI

This third party video shows how to assemble and install MX style plate mount stabilizer inserts, just in case yours fell out during setup (not common).  As a note, this part should not snap in firmly for the beam spring keyboards, as it does in the example video.  It should be loose and you should see the stabilizers move as the spacebar is pressed and released.  The wire slides below the top of the plate while the plastic parts are inserted from above the plate.  https://youtu.be/a173Blgfmww

Please note that the keyboard uses Torx T8 screws to prevent the screws from stripping, had they been + / Phillips head.  I recommend getting a screwdriver kit with many bits.

Not required, but to customize your firmware you’d need to use the special beta web site liked to in the firmware section above, and follow the same steps. You would pick the beamspring b104/ssk option, and the wcass sub-option.

Here is a partial script of the setup video for reference.  As an important note, there are things in the video that have been added and/or changed after this script was created, so follow the video primarily and not the below script.

Take everything out of the box and inspect for damage. A washer may have fallen off or become loose, so you probably want to glue it back on. Super glue is what I use. If you need to take apart the module for whatever reason, the washer can be removed. I recommend using the method in my video for bulk removal of beam modules.

Here is a video of how the beam module is assembled, for your reference. The factory has 100% assembled everything for you already. Here are the parts of the beam spring module (show the assembled module as well as each part on screen): beam barrel part A, beam barrel part B, metal part for the beam barrel, metal part for the beam flipper (part of the “flyplate”), flipper, spring, o-ring, and the washer. And here are the rest of the parts: controller, grounding wire, case (there is no separate inner assembly for the round 1 ultra compact beam spring keyboards), capacitive PCB, rubber sheet below the PCB, and the LED lights for the B104s only.

As a note I will refer to beam module and key interchangeably – of course there is no key installed just yet on each beam module. Now we are going to test each key and use the wiggle method to try to fix any of the stuck or sluggish beam spring modules. Some modules may not be fixable this way. Either they may have broken in shipping, or the flyplate may have separated and need to be reattached. For these modules we will write down the ones we will need to adjust. The beam spring wiggle method is performed as shown here, pressing down and using force to push the white part of the beam module clockwise, and then counterclockwise, about 10 times in each direction. If that does not improve things enough, then you can do the same wiggle method but with the key not pressed.

For the ultimate beam spring experience, you could even take off all the key modules to fine tune each one’s sound! Here is the quality control secrets part of this video, to increase the snappiness of the module if you prefer such a sound. The secret is to make slight adjustments to the metal part for beam flipper, which is part of the bottom flyplate part of the beam spring module. This is how the metal part should look like (see the setup video). There should be a fair amount of distance from the metal part’s bent curves to the flipper below it. Also the metal part’s wings should be equally spaced as shown, with about a half inch of space between them. Making them a little bit closer than this will make the beam modules more snappy, though too much may result in the module not working well.

Do not install the keys when doing this test as it will make the rest of the setup very difficult, for reasons you will soon discover.

From left to right, press each module many times. Try pressing it using different amounts of force to try to get it to become stuck, harder to press, or sluggish/slow to return up to the default position. Press with varying angles too. Do not worry if you notice that many keys require adjustments – you may have to adjust a lot more than you would with a Model F keyboard. Be careful with the space bar’s module as that module can only be switched with another trimmed module because the stabilizer wire is in the way.

Now it is time to open up the keyboard and adjust the nonworking keys you could not fix earlier. Put the keyboard upside down on its two foam inserts and open it up. As a note, the controller and capacitive PCB are mounted to the keyboard bottom plate and it is attached by a grounding wire to the rest of the case, so be careful to just flip over the case as shown. Refer to your list and remove each module. Now you can see why we did not install the keycaps earlier, because it would have prevented us from easily removing each module. As a note the keyboard may now be reversed from left to right, so keep that in mind when removing the modules.

Here is the process to fix a stuck module. While you can fix most stuck modules without having to remove the module, it’s easier to fix it with the module outside of the keyboard. Just like the Model F keyboards have a wiggle method to fix stuck keys, the beam spring keyboards also have a wiggle method.

Here’s the process to reattach the flyplate, which consists of a metal part and a capacitive beam flipper. The beam spring mechanism works by lifting up the capacitive flipper when the key is pressed – this is the opposite of how the Model F keyboard works. In the Model F, the flipper is pressed down when a key is pressed. You’ll need to use the included flyplate reattachment tool for this step.

And here’s the process to fine tune the sound of the beam spring module. In my experience the sound can be fine tuned by adjusting the bend of the metal flyplate ever so slightly inwards or outwards, while taking care to replace or move to another key any key whose other inner metal part is permanently bent. For this reason it is very important to carefully remove the flyplate from this other metal part so as not to permanently bend or “crease” that part.

To accommodate MX-style plate mount stabilizer inserts, the beam spring modules of the 2U and larger keys have been trimmed a bit. For all the keys except the space bar, these stabilizer inserts actually hinder operation of the keys and will make them get stuck in almost every instance, though they are there for your experimentation. You should only use the space bar’s stabilizer insert and leave all others uninstalled. With the beam spring module design, even the widest Right Shift key functions fine and can be pressed even in the extreme corners without the stabilizers. The trimming has no effect on keyboard operation but they do not allow the key to “lock in” to the top of the case like all the other keys. For this reason I recommend moving these trimmed modules to keys inside the main block of your keyboard (not in the top or bottom rows of this main section) so that they are packed tightly with other keys. Just switch the keys around as shown. Definitely keep a note of where you put these trimmed modules as you may need to switch one out with the spacebar’s module in the steps coming up.

Each beam spring hole in the case is notched, so be sure to position things correctly when putting everything back into position. The notch should line up with the hole in the module. For reference you can see how your other modules are installed.

Next we are going to install the spacebar, which is the trickiest key to install. To adapt the old beam spring modules to have compatibility with Cherry MX style key sets, the space bar requires an MX plate-mount stabilizer insert and an extra spring to provide enough force for the space bar to return, so it does not get stuck. Without the additional beam spring, the spacebar would get stuck every time. Just like with the Model F keyboards, installing the beam spring space bar is more of an art than a science.

The first step is to make sure your space bar key stem is trimmed about 1mm for the stem corresponding to the beam spring module, because the beam modules sit about 1mm higher than Cherry MX keys. This means that you may want to use this project’s spacebar or another spare space bar instead of one from a rare or expensive set as you would be permanently trimming this key.

Next, this is the “art” part of the spacebar installation. We are going to insert the spare beam spring into the spacebar area shown and twist the spring a few times either clockwise or counterclockwise as needed. The more the spring is visible on top of the keyboard, the more force the spring will require to press it. I like 5 spaced out “rings” or turns of the spring to be visible, plus the 3 rings pressed together at the ends of each spring, so a total of about 8 rings. This gives the space bar a slightly heavier weighting than the other keys while reducing the chances that the force is not enough to have the spring return after it is pressed. If you prefer a lighter spacebar force, you can twist that spring so less of it is visible outside the keyboard, though as mentioned before if you do too little then the spacebar may not operate properly. Please do let me know if you do any experimentation with the spacebar and have any recommendations.

We are not yet ready to test the spacebar just yet. Now we will push the 2 MX stabilizer inserts into the space bar. Be sure to push this as shown, with your finger pressing down on the plastic stabilizer part and your other finger below the spacebar as shown. Be careful with this step as the plastic stabilizer is easy to break, however you can just replace it with a spare as they are interchangeable (the other stabilizers in your kit have been trimmed on one side to accommodate tight placement with a 2U wide key’s beam spring module, though as noted before you should only use MX stabilizers with the spacebar and not with any other keys like backspace, enter, shift, or num pad 0.

Very important – when testing the various keys after putting everything back, never test without screwing in all of the screws and putting the keyboard down on a flat surface. Do not test with the keyboard on top of the foam inserts. You may accidentally use too much force and push a module out of position. If a module falls out of the locked position in the top case, if you cannot nudge it back in place then the best option is to flip the keyboard upside down and put it on the foam inserts, open up the keyboard, and reseat the modules.

At this time we can do an initial test of the spacebar by holding with one hand the space bar’s module in place, pressed down firmly into the case, and with the other hand press down the spacebar and see if it responds well. It should require a little more force to press than the other keys but not too much more force, unless you prefer more force for the spacebar. You may find that one side of the spacebar has separated from its stabilizer, maybe the space bar is not installed firmly onto the module, or maybe the spring needs to be twisted so it is higher or lower. If you find that the space bar is still not responsive or functional, you may need to follow the above wiggle method to fix a sluggish or stuck module, as it may make the module more smooth and fix issues you may be having. As a last troubleshooting step you can always switch the space bar module with another trimmed module from a 2U or wider key.

It is normal for the space bar stabiizer to have some movement as the space bar is pressed – it helps with the space bar’s performance – do not glue or tighten this as you may make the space bar not work. If the space bar buzzes, try adding super glue below the washer so the spring is secured touching the washer. You don’t have to take anything apart – just push the spring out of the way and add the glue. You can also replace the module with another trimmed module, or trim your own module with a Dremel type tool to match the currently trimmed module.

Once the spacebar is good, we can put the bottom plate back. Before doing this, check every module to make sure it is the same height with the other modules. A module that is slightly too high or not seated properly may affect operation of the keyboard. Install all of the screws and make sure everything is tight, but do not overtighten. Torx T8

For best results, cover any holes with black electrical tape except for the LED holes of course. It is best to keep dust out of the beam spring modules by covering the keyboard with a dust cover when not in use. For example, I have used the Fight Computer Dust Antistatic Vinyl Keyboard Cover (Keyboard Cover: 20W x2H x9D-Large). Now we will connect the keyboard to the computer to test each key with the pandrew signal level monitor utility. First, open the utility. Next, connect the keyboard to the computer and click signal level monitor in the utility.

Key installation – never install keys with the keyboard on your lap or another uneven or soft surface, such as the protective foam packaging. Always install it on a hard flat surface like a desk. The reason is that you will be using force to press each key onto the module, and on a soft or uneven surface it could push the module out of place. While you are installing the keys, beam modules may also become stuck, so just follow the wiggle method shown before while the key is installed, but this time be much more gentle.