@keyboard-hub/adapter-common

Shared firmware adapter contracts for Keyboard Abyss.

Use this package to implement or consume firmware adapters that exchange KeyboardHub keymaps with ZMK, VIA, Vial, or custom firmware.

import {
  compareKeyboardHubKeymaps,
  type FirmwareAdapter,
  type FirmwareLoadedConnection,
} from "@keyboard-hub/adapter-common";

export async function importFromFirmware(adapter: FirmwareAdapter) {
  const connection = await adapter.connect("usb");
  const loaded = await adapter.load(connection, { keyCount: 42 });

  return loaded.state.preview;
}

export async function writeChangedKeys(
  adapter: FirmwareAdapter,
  loaded: FirmwareLoadedConnection,
  target: typeof loaded.state.currentKeymap,
) {
  const diff = compareKeyboardHubKeymaps(target, loaded.state.currentKeymap);

  await adapter.writeKeymapDiff?.(loaded, {
    ...diff,
    comboChanges: [],
    macroChanges: [],
    moduleChanges: [],
  });
}

Adapter Flow

1. Import a firmware package adapter such as viaAdapter, vialAdapter, or zmkAdapter, or provide a custom object implementing FirmwareAdapter.
2. Call adapter.connect("usb") to open the browser/device transport.
3. If adapter.load(connection) throws FirmwareLockedError, ask the user to unlock the keyboard and call adapter.requestUnlock?.(connection).
4. Call adapter.load(connection, options) to build a FirmwareLoadedConnection.
5. Pass loaded.state.preview to Keyboard Abyss import UI.
6. For writeback, compare the target KeyboardHub keymap with loaded.state.currentKeymap, filter the selected sections, then call adapter.writeKeymapDiff.

See HELPERS for helper function examples and ADAPTER_GUIDE for a concrete custom adapter implementation.