@keyboard-hub/adapter-zmk

ZMK Studio import and writeback adapter for Keyboard Abyss.

Use zmkAdapter to connect to a ZMK Studio-enabled keyboard, load the current device keymap and runtime metadata into the common KeyboardHub preview format, and write supported keymap diffs back through ZMK Studio RPC.

import { zmkAdapter } from "@keyboard-hub/adapter-zmk";

const connection = await zmkAdapter.connect("usb");

try {
  const loaded = await zmkAdapter.load(connection);
  console.log(loaded.state.preview.keymap.layers);
  console.log(loaded.state.preview.layout);
  console.log(loaded.state.preview.modules);
} finally {
  await connection.disconnect?.();
}

Pass "ble" instead of "usb" to use the ZMK Studio Bluetooth transport. USB uses Web Serial, and BLE uses Web Bluetooth/GATT, so browser support and a user gesture are required.

The adapter imports device name, layers, supported bindings, active physical layout, and available runtime module metadata. Known ZMK behaviors become structured KeyboardHub bindings. Unsupported or custom behaviors are preserved as raw ZMK expressions so imported keymaps remain inspectable.

If the keyboard reports a locked Studio state, load() throws FirmwareLockedError. Callers can prompt the user to trigger their firmware unlock binding, then retry loading.

Writeback accepts KeyboardHubKeymapDiff values from @keyboard-hub/adapter-common. The current writer supports layer names, key bindings, supported runtime module settings, and supported custom settings dialect values.

Embedding in an existing ZMK Studio session

An editor that already holds a ZMK Studio connection can hand it to the adapter instead of calling connect() — ZMK Studio allows one connection at a time, so opening a second would mean disconnecting the user first. Build a ZmkConnection around the live RpcConnection and pass it to load().

Two things to get right in that setup:

• Notifications. RpcConnection.notification_readable allows a single reader, and a long-lived editor UI normally keeps one so it can react to lock-state and keymap-change notifications. The adapter then cannot take a reader of its own, and notification-driven imports — trackball and other runtime input processors — come back empty rather than failing loudly. Set ZmkConnection.notificationSource to a fan-out over the notifications the app already receives:

  const connection: ZmkConnection = {
    // ...
    notificationSource: {
      subscribe(listener) {
        myNotificationBus.on("notification", listener);
        return () => myNotificationBus.off("notification", listener);
      },
    },
  };

• One copy of the Studio client. @keyboard-hub/zmk-studio-ts-client serializes every call_rpc through a module-level mutex. If the app bundles its own copy of the ZMK Studio client, one RpcConnection ends up guarded by two independent mutexes and concurrent calls corrupt the request/response streams. Alias this package's client to the copy the app already ships.

See MAPPING.md for ZMK import and writeback field coverage, and the generated TypeDoc reference for API details.