Getting Started


Hello, new Halfmoon user. Thank you for deciding to use our macropad!

The Halfmoon gives you shortcuts unconstrained by operating system or software. There is no local app that can crash or mine your data. Your shortcuts will always work no matter what device you plug into. At its core, the Halfmoon is supremely simple: it sends keystrokes. Where the Halfmoon sets itself apart from an average keyboard is just how much choice you have in how those keystrokes are sent.

With some setup, time, and many iterations, the Halfmoon may become one of the most powerful pieces of hardware on your desk. Let’s get started.

Items in the box neatly arranged

What's in the box

  • Keyboard: The Halfmoon, with the Wing wrist rest attached.
  • Wing Stub: Use this in place of the Wing wrist rest when you want a smaller setup.
  • USB Type-C cable: Use this to plug the keyboard in. It also has a USB-A dongle on the end, in case you need it.
  • Key puller: Use it to remove keycaps and keyswitches, to customize your board over time.
  • Hex key: Use it to loosen the screw on the thumb cluster before you adjust its angle, then tighten it back down.

Got everything? Time to set it up.

Positioning the Halfmoon

Positioning your Halfmoon

Where you put the Halfmoon is up to you. For the Moonlander, we recommend positioning each half of the board at about shoulder width. Macropads are much more freeform, though. You could position it like a Moonlander, put it in the center of your desk, or off to the side -- whatever works best for you.

How to tent your Halfmoon

We'd suggest trying the Halfmoon flat for a while first, but you may end up finding it more comfortable to tent it.

Important note on screw direction:
The Halfmoon's thumb cluster screw tightens left. Turn it right to loosen.

This is so the thumb cluster doesn't come loose when you place weight on it.

The leg acts as you'd expect; It's righty-tighty, lefty-loosey.

The leg needs to be fully loosened before trying to adjust. If you leave the leg tight and then move it, you may grind down the leg "nubs" and damage them.

Using the Halfmoon

Once you've got your Halfmoon in position, simply plug it in with the included USB-C cable. You'll also notice a smaller port, shaped like a headphone jack (remember those?). This is for a TRRS cable to connect the right half of a Moonlander if you later decide you'd like the complete keyboard.

When you connect everything up, the status LEDs on the board should briefly light up in a ripple effect to show that the keyboard is connected.

Operating system setup

If you're running Windows or Linux, just plug the keyboard in and go. On macOS, even though you probably won't be doing much normal typing with the Halfmoon, there are a couple of steps to go through.

When you want to connect the keyboard for flashing or training, if you're on Windows or Linux, a little extra extra setup is required, detailed below.

Sending your first keystrokes

Your Halfmoon comes preloaded with the default layout shown below. Watch a video tour showing what you get out of the box:

Click around on your own or start a guided tour by clicking the Tour this layout button above the layout!

It's important to note that this default layout is only meant to demo what is possible with the Halfmoon. You will likely want to start customizing things right away for your own apps and workflow.

Customizing your layout

As you’ve seen above, the default layout the Halfmoon ships with isn’t going to work for you: There’s no way it’s suited to your particular apps, operating system, and personal comfort. So, let’s start customizing!

To customize and load your layout you’ll be using Oryx, our online layout configurator. You’ve seen a glimpse of it in the screencast above. Oryx is visual and simple to use, and is what allows for Halfmoon to become whatever sort of macro-companion fits you best. Here’s a tour of Oryx itself, just to get you acquainted (you can also work through this tour interactively in your browser):

Customizing your layout is easy — this is the process at its most basic:

  1. Make changes using the online configurator.
  2. Compile your layout.
  3. Download your layout and flash it to the keyboard or flash directly from Oryx.

The Halfmoon is different from most macro pads: it requires no extra software to work. All the configuration remains on the board itself. You just have to set up which shortcuts you'd like, load your layout on to your board, and you're ready to go.

To help this setup process go faster, we created a feature in Oryx called Layer Templates. If you have a layer for an app that you think others would find useful, please let us know!

When configuring shortcuts for your apps, the most important thing to remember is, "base character, then modifiers". To save a document, we commonly refer to that shortcut at "Ctrl + S", so we think of Ctrl, then S. Really, Ctrl is modifying S, so S is the main character here, and Ctrl changes how it works. That's how shortcuts are created in Oryx: first assign S, then choose the Ctrl modifier for it, and now you have a single key that saves your work.

Customizing Halfmoon

The other feature you’ll use a lot with the Halfmoon is layers. Layers in Oryx work much the same as they do in a program like Photoshop: each key is like a canvas and a layer lets each key do something different. Layers also stack like in Photoshop. Whatever is assigned on your highest active layer will be what the board does, and any keys that aren’t assigned will take their function from your base layer. This is called transparency. In the default layout, each app gets its own layer, but you can create multiple layers per app or use one layer for multiple apps if the shortcuts are consistent.

This should be enough to get you started, but here's even more customization you can do with your Halfmoon. For more information about what's possible in Oryx, check out the Moonlander's getting started guide.

There are two ways to save your layout to your keyboard:

With our native app (called Wally), or right from Chrome. You can’t use Firefox or Safari because of those browsers’ own limitations, not because we don’t like them (we do, especially Firefox).

You can use either Keymapp or Chrome.

Here’s how you do it with Keymapp.
Here’s how you do it with Chrome.

Training: Think it then trigger it, instantly

The potential of the Halfmoon is practically limitless, but that won’t matter if you have to spend precious seconds thinking about where each shortcut is. Using the Halfmoon should feel as effortless as choosing a tool from your toolbox or a color from your palette. That’s where Oryx’s Live Training comes in, especially Whack-a-Key. Whack-a-Key helps you link keypresses to the tools you’ll be using and is a great Live Training mode for mastering macros and system shortcuts. You can read the full blog post to learn more and watch a screencast of Erez trying to master a layer below.

Once you’ve got a layout you’re ready to try, spend some time with Whack-a-Key to start memorizing your shortcuts. You can also always return to Live Training after any layout changes or just for more practice.

What does this button do?

“What does this button do?” — with Keymapp, you never have to wonder.

Keymapp allows you to view your keyboard's layout right on your screen, in real-time. When you switch a layer, Keymapp shows you the keys active on this layer.

Dark mode Keymapp screen showing a layoutFind out more about Keymapp

What else is possible

The Halfmoon is half of a Moonlander; anything that's possible with the Moonlander is also possible with the Halfmoon. That means you can customize your lighting, change your switches, and access our full selection of training exercises to help you get comfortable with your Halfmoon.

Expect to change your layout a whole lot. It's hard to plan for everything you might do ahead of time, so simply give it a try, wait until you run into a shortcut you need, and make changes. Feel free to flash dozens, hundreds, or even thousands of times. You may never stop changing how your Halfmoon works -- it's ready to adapt to your needs.

Best of luck! And remember: We are always just an email away. Write us at [email protected] — Tisha, Robin, Mike, and Erez would love to hear from you.