Hardpoint

Devices / Keyboard / ZSA

ZSA Moonlander Mark I

Split ergonomic keyboard with a light under every key and an open control protocol.

zsa/moonlander-mk1 · Model match: A named public model or model identifier; this does not verify every configuration or operation.

What it can do

AbilityLabelChecked
Firmware version or layout identifier the device reports.identity.firmware
Details
Checked on
macos 27.2 Oryx protocol v4 · 2026-11-12
Note
Reports the Oryx layout id and revision id that were flashed.
Route
oryx-hid (implemented)
Value
reading, string
Needs firmware
zsa-oryx
readtested commit
Let me answer my agent by pressing a spare key.keys.position_events
Details
Checked on
macos 27.2 Oryx protocol v4 · 2026-11-12
What was checked
A press on a physical key was received and acted on.
Note
Reported for every key, including keys with nothing assigned, so unused keys can be given meaning without reflashing.
Route
oryx-hid (implemented)
Value
event, key position, down or up
Privacy
aggregate
Needs firmware
zsa-oryx
readtested commit
The active keymap layer, reported when it changes.keys.layer
Details
Checked on
macos 27.2 Oryx protocol v4 · 2026-11-12
What was checked
The layer reported on connecting was received. A layer change was not exercised.
Route
oryx-hid (implemented)
Value
event, layer number
Needs firmware
zsa-oryx
readtested commit
Light up a key when my agent needs me.light.per_key
Details
Checked on
macos 27.2 Oryx protocol v4 · 2026-11-13
What was checked
Six keys confirmed by eye. The order of the other 66 follows QMK's published table.
Note
While the host controls lighting it must set every key; there is no overlay on the keyboard's own effects.
Route
oryx-hid (implemented)
Value
control, rgb per key
Needs firmware
zsa-oryx
reversibletested commit
Glow amber whenever an agent is waiting on me.light.global
Details
Checked on
macos 27.2 Oryx protocol v4 · 2026-11-12
What was checked
Taking and releasing control was confirmed by the keyboard's own reply.
Route
oryx-hid (implemented)
Value
control, rgb
Needs firmware
zsa-oryx
reversibletested commit
Switch the device's separate indicator lights.light.status
Details
Checked on
macos
What was checked
In the published protocol. Not tried.
Route
oryx-hid (implemented)
Value
control, on or off per indicator
Needs firmware
zsa-oryx
reversibleunverified commit
Switch the active keymap layer from the host.keys.layer_set
Details
Checked on
macos
What was checked
In the published protocol. Not tried.
If done carelessly
Every key suddenly types something else, including the keys you would use to switch back.
Route
oryx-hid (implemented)
Value
control, layer number
Needs firmware
zsa-oryx
guardedunverified commit
Update its software.firmware.flash
Details
Checked on
macos
What was checked
Taken from ZSA's documentation. Not tried.
Note
You put the keyboard into update mode with its reset button, and ZSA's app writes the firmware. Hardpoint explains the steps.
If done carelessly
If an update fails part-way, the device may not start again.
Route
manual (implemented)
Value
action, firmware image
gatedunverified commit

Key numbers

Oryx key index: left half first, then right; within a half, row by row, then the thumb cluster.

key 00key 11key 22key 33key 44key 55key 66key 77key 88key 99key 1010key 1111key 1212key 1313key 1414key 1515key 1616key 1717key 1818key 1919key 2020key 2121key 2222key 2323key 2424key 2525key 2626key 2727key 2828key 2929key 3030key 3131key 3232key 3333key 3434key 3535key 3636key 3737key 3838key 3939key 4040key 4141key 4242key 4343key 4444key 4545key 4646key 4747key 4848key 4949key 5050key 5151key 5252key 5353key 5454key 5555key 5656key 5757key 5858key 5959key 6060key 6161key 6262key 6363key 6464key 6565key 6666key 6767key 6868key 6969key 7070key 7171

72 keys

Before it will work

PlatformNeeds
anySole use of the keyboard's control channelZSA's Keymapp holds the same channel, so it has to be closed. Checked on macOS.

How it is recognised

BusIdentifiers
usbvendor_id=3297 product_id=1969

Sources

In a standard form

The same card as a W3C Web of Things Thing Model, for tools that read that standard. Hardpoint's added terms.

The card

This page is made from catalog/devices/zsa/moonlander-mk1.toml. If something is wrong, or you have checked more of it, edit that file.

card = 1

[device]
id = "zsa/moonlander-mk1"
vendor = "ZSA"
name = "Moonlander Mark I"
identity = "model"
aliases = ["Moonlander MK1", "Moonlander"]
kind = "keyboard"
summary = "Split ergonomic keyboard with a light under every key and an open control protocol."
links = ["https://www.zsa.io/moonlander"]

[[match]]
bus = "usb"
vendor_id = 0x3297
product_id = 0x1969

# How key numbers, switch positions and lights line up. Each list has one
# entry per key, in key-number order.
[keys]
numbering = "Oryx key index: left half first, then right; within a half, row by row, then the thumb cluster"
matrix = [
  [0, 0], [0, 1], [0, 2], [0, 3], [0, 4], [0, 5], [0, 6], [1, 0], [1, 1], [1, 2], [1, 3], [1, 4],
  [1, 5], [1, 6], [2, 0], [2, 1], [2, 2], [2, 3], [2, 4], [2, 5], [2, 6], [3, 0], [3, 1], [3, 2],
  [3, 3], [3, 4], [3, 5], [4, 0], [4, 1], [4, 2], [4, 3], [4, 4], [5, 3], [5, 0], [5, 1], [5, 2],
  [6, 0], [6, 1], [6, 2], [6, 3], [6, 4], [6, 5], [6, 6], [7, 0], [7, 1], [7, 2], [7, 3], [7, 4],
  [7, 5], [7, 6], [8, 0], [8, 1], [8, 2], [8, 3], [8, 4], [8, 5], [8, 6], [9, 1], [9, 2], [9, 3],
  [9, 4], [9, 5], [9, 6], [10, 2], [10, 3], [10, 4], [10, 5], [10, 6], [11, 3], [11, 4], [11, 5], [11, 6],
]
leds = [
  0, 5, 10, 15, 20, 25, 29, 1, 6, 11, 16, 21, 26, 30, 2, 7, 12, 17,
  22, 27, 31, 3, 8, 13, 18, 23, 28, 4, 9, 14, 19, 24, 35, 32, 33, 34,
  65, 61, 56, 51, 46, 41, 36, 66, 62, 57, 52, 47, 42, 37, 67, 63, 58, 53,
  48, 43, 38, 64, 59, 54, 49, 44, 39, 60, 55, 50, 45, 40, 71, 70, 69, 68,
]
grid = [
  [0, 0], [1, 0], [2, 0], [3, 0], [4, 0], [5, 0], [6, 0], [0, 1], [1, 1], [2, 1], [3, 1], [4, 1],
  [5, 1], [6, 1], [0, 2], [1, 2], [2, 2], [3, 2], [4, 2], [5, 2], [6, 2], [0, 3], [1, 3], [2, 3],
  [3, 3], [4, 3], [5, 3], [0, 4], [1, 4], [2, 4], [3, 4], [4, 4], [6, 5], [3, 5], [4, 5], [5, 5],
  [8, 0], [9, 0], [10, 0], [11, 0], [12, 0], [13, 0], [14, 0], [8, 1], [9, 1], [10, 1], [11, 1], [12, 1],
  [13, 1], [14, 1], [8, 2], [9, 2], [10, 2], [11, 2], [12, 2], [13, 2], [14, 2], [9, 3], [10, 3], [11, 3],
  [12, 3], [13, 3], [14, 3], [10, 4], [11, 4], [12, 4], [13, 4], [14, 4], [8, 5], [9, 5], [10, 5], [11, 5],
]

[[requires]]
platform = "any"
what = "Sole use of the keyboard's control channel"
note = "ZSA's Keymapp holds the same channel, so it has to be closed. Checked on macOS."

[[capability]]
id = "identity.firmware"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "read"
note = "Reports the Oryx layout id and revision id that were flashed."
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12 }]

[[capability]]
id = "keys.position_events"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "read"
privacy = "aggregate"
note = "Reported for every key, including keys with nothing assigned, so unused keys can be given meaning without reflashing."
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12, note = "A press on a physical key was received and acted on." }]

[[capability]]
id = "keys.layer"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "read"
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12, note = "The layer reported on connecting was received. A layer change was not exercised." }]

[[capability]]
id = "light.per_key"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "reversible"
note = "While the host controls lighting it must set every key; there is no overlay on the keyboard's own effects."
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-13, note = "Six keys confirmed by eye. The order of the other 66 follows QMK's published table." }]

[[capability]]
id = "light.global"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "reversible"
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12, note = "Taking and releasing control was confirmed by the keyboard's own reply." }]

[[capability]]
id = "light.status"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "reversible"
verification = [{ status = "unverified", platform = "macos", note = "In the published protocol. Not tried." }]

[[capability]]
id = "keys.layer_set"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "guarded"
verification = [{ status = "unverified", platform = "macos", note = "In the published protocol. Not tried." }]

[[capability]]
id = "firmware.flash"
adapter = "manual"
risk = "gated"
note = "You put the keyboard into update mode with its reset button, and ZSA's app writes the firmware. Hardpoint explains the steps."
verification = [{ status = "unverified", platform = "macos", note = "Taken from ZSA's documentation. Not tried." }]

[[sources]]
title = "ZSA: Moonlander product family"
url = "https://www.zsa.io/moonlander"

[[sources]]
title = "Oryx raw-HID protocol (zsa/qmk_modules)"
url = "https://github.com/zsa/qmk_modules/blob/main/oryx/oryx.h"

[[sources]]
title = "QMK keyboard definition, including LED order"
url = "https://github.com/qmk/qmk_firmware/blob/master/keyboards/zsa/moonlander/keyboard.json"