You’re the proud owner of a new Moonlander. Thank you for picking our keyboard! If you’ve only ever used traditional keyboards, this tool can seem a bit intimidating, but don’t worry: This guide will take you through everything you need to start your journey towards a more ergonomic writing experience.
Remember, this is a journey — a typing adventure if you will. You’ve been typing with staggered, old-style keyboards for years; you’ll quickly notice your bad habits when starting with a Moonlander. Don’t fret: With this guide and practice, you’ll be able to regain your typing speed and enjoy a keyboard that’s perfectly customized for your individual needs. Soon you’ll be left wondering why this isn't the standard layout!
Here‘s a video that goes over what‘s in the box in greater detail:
Connecting the keyboard is simple. First, connect both halves using the 3.5mm TRRS cable. Then plug the USB cable into the keyboard’s left half, and connect it to your computer.
When you connect everything up, the status LEDs on the board should light up in a ripple effect to show that the keyboard is connected.
If you’re running Windows or Linux, just plug the keyboard in and go. On macOS, there are a couple of steps to go through.
You want to avoid having the two pieces too close to each other: Don’t replicate what you do with your normal keyboard. Instead, we recommend that you begin by placing the two pieces at shoulder width, ensuring that the home row aligns with your fingers. Your posture should be completely relaxed — just extend your arms naturally at shoulder width, note where your hands fall, and put the keyboard there. Let the board come to you, not the other way around.
Note the angle of rotation of both halves relative to your body. They don’t have to be straight — you can angle them outwards slightly, so that your wrist does not have to flex in any direction at all.
At this point, without typing, your position should feel completely relaxed and natural. You’re just laying your hands on the desk in a very comfortable way… and there happens to be a keyboard right under your fingers.
Pro tip: Start flat. Yes, the Moonlander has an exciting tilting system. It's fun to use. And yet, when you start the board, our advice is to spend at least a month with the board completely flat. This allows you to experiment with layouts and get used to the ergonomics of the board. The board is extremely comfortable flat, and using it like this reduces the initial learning curve (which is quite steep, as it is). So, one less thing to worry about. Just use it flat for a month.
This is so the thumb cluster doesn‘t come loose when you place weight on it.
The legs act as you‘d expect. Both sides are righty-tighty, lefty-loosey.
If you'd like, you can now tent the unit by adjusting the angle of the thumb cluster and the support leg. The wrist rest will self-adjust to lie against the table, no matter the angle. You don't need to choose the exact same angle for both hands — one can be more extreme than the other.
Watch the following video for tips on how to tilt and tent your keyboard:
Now that you have your Moonlander in place, it’s time to start typing!
Your keyboard comes preloaded with the default layout shown below, explore on your own or start a guided tour by clicking the Tour this layout button above the layout!
Note: If you don’t like it, jump straight into the configurator to make your very own!
One of the best ways to get started with your new keyboard is to use the Live Training mode. This feature shows your keymap dynamically on your screen, in real-time, including all layer changes. Here's how it works:
This is one of the first things you should try with your new keyboard, especially as you follow along the next section on typing.
Remember: You’re relearning how to type, so it’s going to take some time before you get back to your normal typing speeds. It might be frustrating at first, but with practice, you’ll improve.
If this is your first serious ergonomic keyboard, you’re going to find yourself discovering some of those bad habits you acquired with your old keyboard. That’s okay, you’ll get there! Just keep on practicing until you’re back to your normal speeds.
We recommend training daily for the first three weeks, using the typing lessons from Live Training. Ten minutes per day will get you far. Here‘s a video showing a guided typing lesson:
Making this a daily habit over the first few weeks will help you tremendously.
There are also some third-party options you could try out:
For regular typing practice, we recommend KeyHero.com.
For coding typing practice, we recommend typing.io. It lets you work with real code in several languages, so you get to practice parentheses and curlies, etc.
For focusing on the exact keys that need work, check out keybr, a typing tutor that dynamically generates lessons matching your skills.
If you’ve been typing for years, suddenly practicing it may feel awkward at first. It’s all good — deliberate practice is an important thing and it will help you improve rapidly.
You can turn on the LED Lighting of your keyboard by pressing the “Lights on” switch located on Layer #1 (if using the default layout). Here’s a quick GIF:
There are two ways to control the lights on your Moonlander: Manually, or automatically per key/layer.
Manual LED control allows you to tweak lighting in the moment, by pressing keys on your keyboard. There are keys to change the current hue and brightness, and flip between all the various animations.
Per-key/per-layer ("smart") LED control allows you to set colors for certain keys and layers ahead of time. You can use per-key LED control to highlight just the media control keys on layer 2, for example. So every time you flip to layer 2, your media control keys can glow blue, while your mouse control keys can glow green.
Each of these modes has its own toggle, and they have a hierarchy:
With both manual and per-key lighting on, when you switch to a layer that has per-key lighting rules (specific colors you've pre-defined for certain keys or the whole layer), those rules take precedence over any manual settings you've defined in the moment.
In other words, let's say you don't have any predefined per-key colors for layer 0, but you do have some rules for layer 1. So you have a cool animation running on layer 0, and then you switch to layer 1. The animation stops, and the keys you wanted highlighted on layer 1 start glowing in the colors you set.
If you want the animation to keep running even in layer 1, simply hit Toggle layer colors and the automatic lighting rules will be suspended across all of your layers.
Your Moonlander requires no software to work. All the customization is done on your board, at firmware level. This means that nothing you do here will burden your machine, and it’s all cross-platform and portable. Just plug your keyboard into any random computer, and your familiar custom layout is right there, zero installation needed.
The layout that comes pre-loaded on your unit is not perfect for you — it can’t be, because in ergonomics, one size does not fit all. It’s time to unleash the power of the Moonlander and truly make it your own.
Before we get started on the firmware side of things, let’s get some terms out of the way.
Changing the keyboard layout is easy — at a high level the process is as follows:
Following are text and screenshot explanations, but we also have an entire YouTube channel full of tutorials.
You can create a new layout by clicking “Modify layout”.
This will take you to a new view where you will be able to add new layers, modify individual keys, and more.
After clicking Modify Layout you’ll get a very similar view to the one that you saw before, only now you can actually change things.
Let’s begin by explaining the main elements on the screen:
You can specify a name that describes your Layout. Our users sometimes append a version to this field, for their own reference, though if you‘re logged in, we will keep track of your layout revisions for you.
Here you can add or remove layers.
This is where you’ll spend most of your time. You can click any key to modify its function.
Assigning unique color for a specific layer or specific keys has never been this easy, follow the instructions in the configurator and let the show begin.
For example, let’s say that you want to modify the “M” key. You can go ahead and click the key, and a box will appear which will show as follows:
From here you can press another key to override the keycode that is assigned to that key; however, you can always click the dropdown and search for the available options. In this example, let’s say that we want to have the “M” key send the “M” keycode if tapped, but momentarily switch layers if you hold the key.
So we begin by searching for “Layer”. This will show us all the Layer related functionality. You can read what the available functions do by reading the description in the dropdown.
Based on what we want and the description on the search results, we can see that “TG” is a perfect fit, so we go ahead and select it. This action will add a couple of options to the box, Layer and Command. We select Layer 1 as we want to momentarily switch to said layer, and we select “M” as the command.
After doing this we can click outside of the box, and your keybind will be displayed:
You can repeat this process as many times as you want to build your own layout. We recommend that you take your time to explore the multiple options that are offered to you. Remember: This is a journey keyboard. This won’t be the last time you edit your layout!
Once you’re happy with your layout, hit the ‘Compile this layout’ button. This will lock your changes and generate a .hex file which can be understood by the chip on the keyboard.
The process of installing a new firmware is called ‘flashing’. To do this you’ll need to download a small flashing application called Wally. You can read all about Wally here. This application will guide you step by step through the process of flashing your keyboard.
The firmware running on the Moonlander is the Quantum Mechanical Keyboard Firmware (or QMK, for short), which we actively support. It’s a third-party open-source project running on multiple keyboards, with over 300 contributors and thousands of forks.
If you enjoy working directly with the code driving the keyboard, you can dig right into QMK on GitHub, compile it locally, and customize your keyboard at the deepest levels possible. This is a good starting point — QMK is extensively documented.
We understand that keyboard is a serious investment in your future well being, and our warranty reflects this.
Basically, any reasonable use. If a keyswitch starts chattering, we’ve got your back. If the board stops working one day without you having done anything to it (never happened so far, but it is covered). It’s a two-year warranty, and we really care, so just email us.
Any damage that is caused by accident, abuse, misuse, liquid contact, fire or environmental causes. Don’t spill coffee on your keyboard; it doesn’t need it.
Please note that your warranty is non transferrable. Our keyboards are not marked with serial numbers — we use your original proof of purchase. If you didn’t buy a keyboard directly from us, it is unfortunately not covered by our warranty.
We publish a magazine.
It comes out once a month, and it‘s great. Called The Ergo, our magazine features user stories, links worth your time, and subscriber-only goodies.
Subscribe now, and get a 20% discount coupon for the Satellite, our awesome desk toy. And of course, you can unsubscribe at any time.