[Devices](https://dotcipher.github.io/hardpoint/devices.html) / [Keyboard](https://dotcipher.github.io/hardpoint/devices.html?kind=keyboard) / [ZSA](https://dotcipher.github.io/hardpoint/devices.html?maker=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

| Ability | Label | Checked |
| --- | --- | --- |
| 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  | read | tested [commit](https://github.com/dotCipher/hardpoint/commit/28ddef25a53296ecc6bcb0d5ccb9a6547b53542c) |
| 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  | read | tested [commit](https://github.com/dotCipher/hardpoint/commit/28ddef25a53296ecc6bcb0d5ccb9a6547b53542c) |
| 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  | read | tested [commit](https://github.com/dotCipher/hardpoint/commit/28ddef25a53296ecc6bcb0d5ccb9a6547b53542c) |
| 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  | reversible | tested [commit](https://github.com/dotCipher/hardpoint/commit/28ddef25a53296ecc6bcb0d5ccb9a6547b53542c) |
| 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  | reversible | tested [commit](https://github.com/dotCipher/hardpoint/commit/28ddef25a53296ecc6bcb0d5ccb9a6547b53542c) |
| 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  | reversible | unverified [commit](https://github.com/dotCipher/hardpoint/commit/094daa00965059b455636cc3ab4a1eaae2898a42) |
| 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  | guarded | unverified [commit](https://github.com/dotCipher/hardpoint/commit/094daa00965059b455636cc3ab4a1eaae2898a42) |
| 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  | gated | unverified [commit](https://github.com/dotCipher/hardpoint/commit/621f8f2455dc219c2935caef0f772605972814b6) |

## Key numbers

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

72 keys

## Before it will work

| Platform | Needs |
| --- | --- |
| any | Sole use of the keyboard's control channel ZSA'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](https://www.zsa.io/moonlander)
- [Oryx raw-HID protocol (zsa/qmk_modules)](https://github.com/zsa/qmk_modules/blob/main/oryx/oryx.h)
- [QMK keyboard definition, including LED order](https://github.com/qmk/qmk_firmware/blob/master/keyboards/zsa/moonlander/keyboard.json)

## In a standard form

The same card as a [W3C Web of Things Thing Model](https://dotcipher.github.io/hardpoint/models/zsa-moonlander-mk1.tm.jsonld), for tools that read that standard. [Hardpoint's added terms](https://dotcipher.github.io/hardpoint/ns.html).

## The card

This page is made from [catalog/devices/zsa/moonlander-mk1.toml](https://github.com/dotCipher/hardpoint/blob/main/catalog/devices/zsa/moonlander-mk1.toml). If something is wrong, or you have checked more of it, [edit that file](https://dotcipher.github.io/hardpoint/add.html).

```
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"

```
