Getting Started

Welcome

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.

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.

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.

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.

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).

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.