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
| Ability | Label | Checked |
|---|---|---|
Firmware version or layout identifier the device reports.identity.firmwareDetails
| read | tested commit |
Let me answer my agent by pressing a spare key.keys.position_eventsDetails
| read | tested commit |
The active keymap layer, reported when it changes.keys.layerDetails
| read | tested commit |
Light up a key when my agent needs me.light.per_keyDetails
| reversible | tested commit |
Glow amber whenever an agent is waiting on me.light.globalDetails
| reversible | tested commit |
Switch the device's separate indicator lights.light.statusDetails
| reversible | unverified commit |
Switch the active keymap layer from the host.keys.layer_setDetails
| guarded | unverified commit |
Update its software.firmware.flashDetails
| gated | unverified commit |
Key numbers
Oryx key index: left half first, then right; within a half, row by row, then the thumb cluster.
Before it will work
| Platform | Needs |
|---|---|
| any | Sole 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
| Bus | Identifiers |
|---|---|
| usb | vendor_id=3297 product_id=1969 |
Sources
- ZSA: Moonlander product family
- Oryx raw-HID protocol (zsa/qmk_modules)
- QMK keyboard definition, including LED order
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"