@openmouse/protocol 0.1.0

package/dist/logitech/hosts.js

@@ -0,0 +1,80 @@
+/**
+ * Features 0x1815 (Hosts Info) and 0x1814 (Change Host) — Easy-Switch.
+ *
+ * Read from an MX Master 4 (WPID B042) over a Logi Bolt receiver. 0x1815
+ * fn 0x00 answers [capabilities(2), hostCount, currentHost]: the two leading
+ * capability bytes matter, because reading the counts one byte earlier reports
+ * eight slots on a device whose slots 3 and up refuse outright. That device
+ * reports three slots with two paired, itself on slot 0.
+ *
+ * Slot indices are zero-based on the wire. The button on the underside of the
+ * mouse and its indicator both count from one, so anything user-facing has to
+ * add one or it disagrees with the hardware in the user's hand.
+ */
+export const LOGITECH_HOSTS = {
+    /** getHostsInfo: [capabilities(2), hostCount, currentHost]. */
+    info: 0x00,
+    /** getHostInfo(slot): [slot, status, ..., nameLength, maxNameLength]. */
+    host: 0x10,
+    /**
+     * getHostFriendlyName(slot, offset). NOT the host's label: on an MX Master 4
+     * this answers six non-text bytes per slot regardless of the reported name
+     * length, which is an address rather than a name. Where the label actually
+     * lives is unknown, and the remaining function ids on this feature are
+     * reportedly set-name, move and delete-host — a blind call to the last would
+     * unpair one of the user's computers, so it was left alone.
+     */
+    hostName: 0x20,
+};
+export const LOGITECH_CHANGE_HOST = {
+    /** getCurrentHost. */
+    current: 0x00,
+    /** setCurrentHost(slot) — disconnects this host on success. */
+    set: 0x10,
+};
+/** Status 1 means a computer is paired to the slot; 0 means it is empty. */
+export const LOGITECH_HOST_STATUS_PAIRED = 0x01;
+export function decodeHostsInfo(payload) {
+    const capabilityHigh = payload[0];
+    const capabilityLow = payload[1];
+    const hostCount = payload[2];
+    const currentHost = payload[3];
+    if (capabilityHigh === undefined || capabilityLow === undefined)
+        return null;
+    if (hostCount === undefined || currentHost === undefined || hostCount === 0)
+        return null;
+    if (currentHost >= hostCount)
+        return null;
+    return {
+        hostCount,
+        currentHost,
+        capabilities: (capabilityHigh << 8) | capabilityLow,
+    };
+}
+export function decodeHostPaired(payload) {
+    const status = payload[1];
+    return status === undefined ? null : status === LOGITECH_HOST_STATUS_PAIRED;
+}
+/**
+ * Why a host switch must not be sent, or null when it may be.
+ *
+ * Refusing an empty slot is the important one. Switching into a slot with no
+ * computer paired leaves the mouse unreachable until someone presses the
+ * button on its underside, and no warning text makes that an acceptable thing
+ * for a misclick to do.
+ */
+export function rejectHostSwitch(slot, info, paired) {
+    if (!info)
+        return "no-hosts";
+    if (!Number.isInteger(slot) || slot < 0 || slot >= info.hostCount)
+        return "out-of-range";
+    if (slot === info.currentHost)
+        return "already-current";
+    if (paired[slot] !== true)
+        return "empty-slot";
+    return null;
+}
+export function buildHostSwitchWrite(slot) {
+    return [slot & 0xff];
+}
+//# sourceMappingURL=hosts.js.map

package/dist/logitech/hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.js","sourceRoot":"","sources":["../../src/logitech/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,+DAA+D;IAC/D,IAAI,EAAE,IAAI;IACV,yEAAyE;IACzE,IAAI,EAAE,IAAI;IACV;;;;;;;OAOG;IACH,QAAQ,EAAE,IAAI;CACN,CAAC;AAEX,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,sBAAsB;IACtB,OAAO,EAAE,IAAI;IACb,+DAA+D;IAC/D,GAAG,EAAE,IAAI;CACD,CAAC;AAEX,4EAA4E;AAC5E,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAQhD,MAAM,UAAU,eAAe,CAAC,OAAuC;IACrE,MAAM,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjC,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,cAAc,KAAK,SAAS,IAAI,aAAa,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC7E,IAAI,SAAS,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzF,IAAI,WAAW,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO;QACL,SAAS;QACT,WAAW;QACX,YAAY,EAAE,CAAC,cAAc,IAAI,CAAC,CAAC,GAAG,aAAa;KACpD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAuC;IACtE,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,2BAA2B,CAAC;AAC9E,CAAC;AAID;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,IAA8B,EAC9B,MAA0B;IAE1B,IAAI,CAAC,IAAI;QAAE,OAAO,UAAU,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,IAAI,IAAI,CAAC,SAAS;QAAE,OAAO,cAAc,CAAC;IACzF,IAAI,IAAI,KAAK,IAAI,CAAC,WAAW;QAAE,OAAO,iBAAiB,CAAC;IACxD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IAC/C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AACvB,CAAC"}

package/dist/logitech/index.d.ts

@@ -0,0 +1,127 @@
+export * from "./controls.js";
+export * from "./friendly-name.js";
+export * from "./haptics.js";
+export * from "./hosts.js";
+export * from "./wheel.js";
+/** Add this client's HID++ software ID while preserving the function nibble. */
+export declare function withSoftwareId(functionId: number): number;
+/**
+ * Usage page carrying HID++ over USB: a receiver, or a mouse's own wired
+ * vendor interface. Usage 1 is the short-report collection, usage 2 the long.
+ */
+export declare const HIDPP_USAGE_PAGE = 65280;
+/**
+ * Usage page carrying HID++ over Bluetooth. BLE devices do not expose the
+ * 0xFF00 pair at all: Logitech moves the protocol to its own vendor page
+ * (usage 0x0202) and carries long reports only, which is why an MX Master
+ * paired over Bluetooth shows a single `Vendor (0xFF43)` interface and was
+ * never offered by a 0xFF00-only picker filter.
+ *
+ * The page is Logitech's alone, so both the filter and the support check match
+ * the whole page rather than a single usage, keeping firmware that numbers the
+ * collection differently within reach.
+ */
+export declare const HIDPP_BLUETOOTH_USAGE_PAGE = 65347;
+/** Receiver-attached mice answer on the receiver's first pairing slot. */
+export declare const DEVICE_INDEX_RECEIVER = 1;
+/** A mouse addressed over its own USB interface answers on 0xFF. */
+export declare const DEVICE_INDEX_DIRECT = 255;
+/** Bolt receivers expose up to six pairing slots (HID++ device indices 1..6). */
+export declare const BOLT_PAIRING_SLOTS: readonly [1, 2, 3, 4, 5, 6];
+/**
+ * Logitech mice whose vendor interface is the mouse itself rather than a
+ * receiver. They answer HID++ on device index 0xFF and keep their writable
+ * settings in an onboard profile.
+ *
+ * G203 / G102 generation (HID++ 2.0, legacy DPI feature 0x2201):
+ * - 0xc084 — G203 PRODIGY (wired)
+ * - 0xc089 — G102 LIGHTSYNC (wired)
+ * - 0xc092 — G203 LIGHTSYNC (wired)
+ *
+ * G303 / G402 generation:
+ * - 0xc07d — G502 / G502 Proteus Core (wired)
+ * - 0xc07e — G402 / G402 Hyperion Fury (wired)
+ * - 0xc080 — G303 Daedalus Apex (wired)
+ *
+ * G Pro / G502 / G403 HERO generation (HID++ 2.0, DPI feature 0x2202):
+ * - 0xc085 — G Pro (wired, 2017)
+ * - 0xc087 — G703 (wired)
+ * - 0xc08b — G502 HERO (wired)
+ * - 0xc08c — G Pro Hero (wired)
+ * - 0xc08e — G903 HERO (wired)
+ * - 0xc08f — G403 HERO (wired)
+ * - 0xc095 — G502 X PLUS (USB cable)
+ * - 0xc098 — G502 X LIGHTSPEED (USB cable, direct-connect mode)
+ * - 0xc099 — G502 X (wired)
+ *
+ * G Pro X Superlight generation:
+ * - 0xc094 — G Pro X Superlight (wired)
+ *
+ * This module deliberately imports nothing, so both the driver and the WebHID
+ * filters in ../vendors can read it without a cycle.
+ */
+export declare const LOGITECH_DIRECT_PRODUCT_IDS: readonly [49284, 49289, 49298, 49277, 49278, 49280, 49285, 49287, 49291, 49292, 49294, 49295, 49300, 49301, 49304, 49305];
+/**
+ * Logi Bolt receivers. Unlike Lightspeed, device HID++ 2.0 rides long reports
+ * (report id 0x11) on usage `ff00:2`, and the mouse may sit on any pairing
+ * slot — not only 0x01.
+ *
+ * - 0xc548 — Logi Bolt USB receiver (MX Master 3S and other Bolt mice)
+ */
+export declare const LOGITECH_BOLT_PRODUCT_IDS: readonly [50504];
+export declare function isDirectConnectProduct(productId: number): boolean;
+export declare function isBoltReceiverProduct(productId: number): boolean;
+/**
+ * Whether this HID++ endpoint is the mouse itself rather than a receiver.
+ * Runtime device-index probing is authoritative; product IDs do not decide it.
+ */
+export declare function isDirectConnection(resolvedDeviceIndex: number | null): boolean;
+/**
+ * Device indices to probe when discovering which one answers.
+ *
+ * A receiver forwards to its pairing slots, and G HUB merging a keyboard onto
+ * the same receiver can push the mouse off the first one — so all six slots
+ * are probed before the direct index. A direct connection is its own single
+ * endpoint and answers as itself, with the receiver slot only a fallback for
+ * product ids that are on neither list.
+ */
+export declare function hidppDeviceIndexCandidates(isKnownReceiver: boolean): readonly number[];
+export declare function hidppErrorMessage(code: number): string;
+export declare function hidpp10ErrorMessage(code: number): string;
+/**
+ * Decodes an error only when it echoes the request being awaited.
+ *
+ * HID++ 1.0: [device, 0x8f, sub-id, address, error]
+ * HID++ 2.0: [device, 0xff, feature-index, function+software-id, error]
+ */
+export declare function hidppErrorForRequest(report: Uint8Array, requestFirstByte: number, requestSecondByte: number): string | null;
+/**
+ * Decode the legacy Report Rate (0x8060) supported-rate bitmap, where bit i
+ * marks an interval of (i + 1) ms. The G402 generation reports 0x8b, meaning
+ * 1, 2, 4 and 8 ms — 1000, 500, 250 and 125 Hz.
+ */
+export declare function decodeReportRateBitmap(bitflags: number): number[];
+export type BatteryChargeState = "Charging" | "Charging slowly" | "Almost full" | "Full" | "Discharging" | "Unknown";
+/**
+ * 0x1004 UNIFIED_BATTERY chargingStatus.
+ *
+ * Deliberately separate from the 0x1000 mapping below: the two features number
+ * their states differently, and decoding one with the other's table reports a
+ * slow charge as "almost full".
+ */
+export declare function decodeUnifiedBatteryState(chargingStatus: number): BatteryChargeState;
+/** 0x1000 BATTERY_LEVEL_STATUS batteryStatus. */
+export declare function decodeBatteryLevelState(batteryStatus: number): BatteryChargeState;
+/**
+ * The mouse keeps its settings in onboard memory and will not hand control to
+ * software, so the only way to change anything is to write its profile — which
+ * needs a decoded layout for that profile format.
+ *
+ * Its own type because it is not a fault: it is a mouse that cannot be
+ * supported yet, and the way forward is a capture from whoever owns one.
+ */
+export declare class OnboardOnlyError extends Error {
+    readonly profileFormatId: number | null;
+    constructor(profileFormatId: number | null);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/logitech/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logitech/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAM3B,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,IAAO,CAAC;AAC1C,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,MAAO,CAAC;AACxC,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,6BAAgD,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,2BAA2B,2HAW9B,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,kBAAoB,CAAC;AAK3D,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAE9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,eAAe,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAItF;AA+BD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,gBAAgB,EAAE,MAAM,EACxB,iBAAiB,EAAE,MAAM,GACxB,MAAM,GAAG,IAAI,CAKf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAMjE;AAED,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GAAG,iBAAiB,GAAG,aAAa,GAAG,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;AAExF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,kBAAkB,CAUpF;AAED,iDAAiD;AACjD,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,kBAAkB,CAUjF;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;gBAE5B,eAAe,EAAE,MAAM,GAAG,IAAI;CAU3C"}

package/dist/logitech/index.js

@@ -0,0 +1,233 @@
+export * from "./controls.js";
+export * from "./friendly-name.js";
+export * from "./haptics.js";
+export * from "./hosts.js";
+export * from "./wheel.js";
+// HID++ reserves software ID 0 for device-originated notifications. Using a
+// nonzero ID keeps command replies distinct from asynchronous mouse events.
+const SOFTWARE_ID = 0x05;
+/** Add this client's HID++ software ID while preserving the function nibble. */
+export function withSoftwareId(functionId) {
+    return (functionId & 0xf0) | SOFTWARE_ID;
+}
+/**
+ * Usage page carrying HID++ over USB: a receiver, or a mouse's own wired
+ * vendor interface. Usage 1 is the short-report collection, usage 2 the long.
+ */
+export const HIDPP_USAGE_PAGE = 0xff00;
+/**
+ * Usage page carrying HID++ over Bluetooth. BLE devices do not expose the
+ * 0xFF00 pair at all: Logitech moves the protocol to its own vendor page
+ * (usage 0x0202) and carries long reports only, which is why an MX Master
+ * paired over Bluetooth shows a single `Vendor (0xFF43)` interface and was
+ * never offered by a 0xFF00-only picker filter.
+ *
+ * The page is Logitech's alone, so both the filter and the support check match
+ * the whole page rather than a single usage, keeping firmware that numbers the
+ * collection differently within reach.
+ */
+export const HIDPP_BLUETOOTH_USAGE_PAGE = 0xff43;
+/** Receiver-attached mice answer on the receiver's first pairing slot. */
+export const DEVICE_INDEX_RECEIVER = 0x01;
+/** A mouse addressed over its own USB interface answers on 0xFF. */
+export const DEVICE_INDEX_DIRECT = 0xff;
+/** Bolt receivers expose up to six pairing slots (HID++ device indices 1..6). */
+export const BOLT_PAIRING_SLOTS = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06];
+/**
+ * Logitech mice whose vendor interface is the mouse itself rather than a
+ * receiver. They answer HID++ on device index 0xFF and keep their writable
+ * settings in an onboard profile.
+ *
+ * G203 / G102 generation (HID++ 2.0, legacy DPI feature 0x2201):
+ * - 0xc084 — G203 PRODIGY (wired)
+ * - 0xc089 — G102 LIGHTSYNC (wired)
+ * - 0xc092 — G203 LIGHTSYNC (wired)
+ *
+ * G303 / G402 generation:
+ * - 0xc07d — G502 / G502 Proteus Core (wired)
+ * - 0xc07e — G402 / G402 Hyperion Fury (wired)
+ * - 0xc080 — G303 Daedalus Apex (wired)
+ *
+ * G Pro / G502 / G403 HERO generation (HID++ 2.0, DPI feature 0x2202):
+ * - 0xc085 — G Pro (wired, 2017)
+ * - 0xc087 — G703 (wired)
+ * - 0xc08b — G502 HERO (wired)
+ * - 0xc08c — G Pro Hero (wired)
+ * - 0xc08e — G903 HERO (wired)
+ * - 0xc08f — G403 HERO (wired)
+ * - 0xc095 — G502 X PLUS (USB cable)
+ * - 0xc098 — G502 X LIGHTSPEED (USB cable, direct-connect mode)
+ * - 0xc099 — G502 X (wired)
+ *
+ * G Pro X Superlight generation:
+ * - 0xc094 — G Pro X Superlight (wired)
+ *
+ * This module deliberately imports nothing, so both the driver and the WebHID
+ * filters in ../vendors can read it without a cycle.
+ */
+export const LOGITECH_DIRECT_PRODUCT_IDS = [
+    // G203 / G102 generation
+    0xc084, 0xc089, 0xc092,
+    // G303 / G402 generation
+    0xc07d, 0xc07e, 0xc080,
+    // G Pro / G502 / G403 HERO / G703 generation
+    0xc085, 0xc087, 0xc08b, 0xc08c, 0xc08e, 0xc08f,
+    // G Pro X Superlight generation
+    0xc094,
+    // G502 X generation
+    0xc095, 0xc098, 0xc099,
+];
+/**
+ * Logi Bolt receivers. Unlike Lightspeed, device HID++ 2.0 rides long reports
+ * (report id 0x11) on usage `ff00:2`, and the mouse may sit on any pairing
+ * slot — not only 0x01.
+ *
+ * - 0xc548 — Logi Bolt USB receiver (MX Master 3S and other Bolt mice)
+ */
+export const LOGITECH_BOLT_PRODUCT_IDS = [0xc548];
+const DIRECT_PRODUCT_ID_SET = new Set(LOGITECH_DIRECT_PRODUCT_IDS);
+const BOLT_PRODUCT_ID_SET = new Set(LOGITECH_BOLT_PRODUCT_IDS);
+export function isDirectConnectProduct(productId) {
+    return DIRECT_PRODUCT_ID_SET.has(productId);
+}
+export function isBoltReceiverProduct(productId) {
+    return BOLT_PRODUCT_ID_SET.has(productId);
+}
+/**
+ * Whether this HID++ endpoint is the mouse itself rather than a receiver.
+ * Runtime device-index probing is authoritative; product IDs do not decide it.
+ */
+export function isDirectConnection(resolvedDeviceIndex) {
+    return resolvedDeviceIndex === DEVICE_INDEX_DIRECT;
+}
+/**
+ * Device indices to probe when discovering which one answers.
+ *
+ * A receiver forwards to its pairing slots, and G HUB merging a keyboard onto
+ * the same receiver can push the mouse off the first one — so all six slots
+ * are probed before the direct index. A direct connection is its own single
+ * endpoint and answers as itself, with the receiver slot only a fallback for
+ * product ids that are on neither list.
+ */
+export function hidppDeviceIndexCandidates(isKnownReceiver) {
+    return isKnownReceiver
+        ? [DEVICE_INDEX_RECEIVER, 0x02, 0x03, 0x04, 0x05, 0x06, DEVICE_INDEX_DIRECT]
+        : [DEVICE_INDEX_DIRECT, DEVICE_INDEX_RECEIVER];
+}
+/** HID++ 2.0 error codes, reported in byte 4 of a 0xFF error response. */
+const HIDPP20_ERRORS = {
+    0x01: "unknown request",
+    0x02: "invalid argument",
+    0x03: "value out of range",
+    0x04: "hardware error",
+    0x05: "Logitech internal error",
+    0x06: "invalid feature index",
+    0x07: "invalid function",
+    0x08: "device busy",
+    0x09: "unsupported",
+};
+/** HID++ 1.0 error codes, reported in byte 4 of a 0x8F error response. */
+const HIDPP10_ERRORS = {
+    0x01: "invalid command",
+    0x02: "invalid address",
+    0x03: "invalid value",
+    0x04: "connection request failed",
+    0x05: "too many devices",
+    0x06: "already exists",
+    0x07: "device busy",
+    0x08: "unknown device",
+    0x09: "resource error",
+    0x0a: "request unavailable",
+    0x0b: "unsupported parameter value",
+    0x0c: "wrong PIN code",
+};
+export function hidppErrorMessage(code) {
+    const reason = HIDPP20_ERRORS[code];
+    return reason
+        ? `The mouse rejected that setting (${reason}).`
+        : `The mouse rejected that setting (HID++ 2.0 error 0x${code.toString(16).padStart(2, "0")}).`;
+}
+export function hidpp10ErrorMessage(code) {
+    const reason = HIDPP10_ERRORS[code];
+    return reason
+        ? `The mouse rejected that setting (HID++ 1.0: ${reason}).`
+        : `The mouse rejected that setting (HID++ 1.0 error 0x${code.toString(16).padStart(2, "0")}).`;
+}
+/**
+ * Decodes an error only when it echoes the request being awaited.
+ *
+ * HID++ 1.0: [device, 0x8f, sub-id, address, error]
+ * HID++ 2.0: [device, 0xff, feature-index, function+software-id, error]
+ */
+export function hidppErrorForRequest(report, requestFirstByte, requestSecondByte) {
+    if (report[2] !== requestFirstByte || report[3] !== withSoftwareId(requestSecondByte))
+        return null;
+    if (report[1] === 0x8f)
+        return hidpp10ErrorMessage(report[4] ?? 0);
+    if (report[1] === 0xff)
+        return hidppErrorMessage(report[4] ?? 0);
+    return null;
+}
+/**
+ * Decode the legacy Report Rate (0x8060) supported-rate bitmap, where bit i
+ * marks an interval of (i + 1) ms. The G402 generation reports 0x8b, meaning
+ * 1, 2, 4 and 8 ms — 1000, 500, 250 and 125 Hz.
+ */
+export function decodeReportRateBitmap(bitflags) {
+    const rates = [];
+    for (let bit = 0; bit < 8; bit += 1) {
+        if ((bitflags & (1 << bit)) !== 0)
+            rates.push(Math.round(1000 / (bit + 1)));
+    }
+    return rates.sort((left, right) => left - right);
+}
+/**
+ * 0x1004 UNIFIED_BATTERY chargingStatus.
+ *
+ * Deliberately separate from the 0x1000 mapping below: the two features number
+ * their states differently, and decoding one with the other's table reports a
+ * slow charge as "almost full".
+ */
+export function decodeUnifiedBatteryState(chargingStatus) {
+    switch (chargingStatus) {
+        case 0x00: return "Discharging";
+        case 0x01: return "Charging";
+        case 0x02: return "Charging slowly";
+        case 0x03: return "Full";
+        // 4 is a charging fault. There is no state for it, and calling it charging
+        // would be worse than admitting we do not know.
+        default: return "Unknown";
+    }
+}
+/** 0x1000 BATTERY_LEVEL_STATUS batteryStatus. */
+export function decodeBatteryLevelState(batteryStatus) {
+    switch (batteryStatus) {
+        case 0x00: return "Discharging";
+        case 0x01: return "Charging";
+        case 0x02: return "Almost full";
+        case 0x03: return "Full";
+        case 0x04: return "Charging slowly";
+        // 5 invalid battery, 6 thermal error, 7 other charging error.
+        default: return "Unknown";
+    }
+}
+/**
+ * The mouse keeps its settings in onboard memory and will not hand control to
+ * software, so the only way to change anything is to write its profile — which
+ * needs a decoded layout for that profile format.
+ *
+ * Its own type because it is not a fault: it is a mouse that cannot be
+ * supported yet, and the way forward is a capture from whoever owns one.
+ */
+export class OnboardOnlyError extends Error {
+    profileFormatId;
+    constructor(profileFormatId) {
+        super("This mouse keeps its settings in onboard memory and will not hand control to software. "
+            + `Writing ${profileFormatId === null ? "its profile format" : `profile format ${profileFormatId}`} `
+            + 'is not supported yet. Open Diagnostics, then HID++ capture, and use "Copy verification data" — '
+            + "sending that is what lets the layout be added.");
+        this.name = "OnboardOnlyError";
+        this.profileFormatId = profileFormatId;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/logitech/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logitech/index.ts"],"names":[],"mappings":"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"}

package/dist/logitech/wheel.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Scroll-wheel features on the MX line: 0x2111 (SmartShift Enhanced),
+ * 0x2121 (Hi-Res Wheel) and 0x2150 (Thumb Wheel).
+ *
+ * Byte layouts were established on an MX Master 4 by pressing the physical
+ * wheel-mode button and diffing dumps — exactly two bytes moved — and by
+ * moving Logi Options+'s own sliders and watching which value followed.
+ */
+export declare const LOGITECH_SMART_SHIFT: {
+    /** getCapabilities: [?, min, max, ...] on an MX Master 4, 01 0A 4B 0E. */
+    readonly capabilities: 0;
+    /** getRatchetControlMode: [mode, threshold, defaultThreshold]. */
+    readonly get: 16;
+    /** setRatchetControlMode(mode, threshold, defaultThreshold). */
+    readonly set: 32;
+};
+/**
+ * 0x2111 byte 0 is the wheel's ratchet mode — the same thing the button behind
+ * the wheel toggles, and NOT SmartShift on/off. It was first shipped labelled
+ * "SmartShift / Always ratchet", which was naming a control after inferred
+ * behaviour rather than demonstrated behaviour.
+ */
+export declare const LOGITECH_WHEEL_MODE: {
+    readonly freespin: 1;
+    readonly ratchet: 2;
+};
+/**
+ * Byte 1 is the SmartShift threshold: 255 disables it, and a lower value
+ * releases the ratchet on a gentler flick. Proven by moving the Options+
+ * sensitivity slider — 9% wrote 46 and 75% wrote 15, with the mode byte stuck
+ * at 2 throughout.
+ */
+export declare const LOGITECH_SMART_SHIFT_OFF = 255;
+export declare const LOGITECH_HIRES_WHEEL: {
+    /** getCapabilities: [multiplier, flags, ...]. */
+    readonly capabilities: 0;
+    /** getMode / setMode, a single bitmask byte. */
+    readonly get: 16;
+    readonly set: 32;
+    /** getRatchetSwitchState: byte 0 is 1 while the wheel is ratcheted. */
+    readonly ratchetState: 48;
+};
+/**
+ * Bits of the 0x2121 mode byte.
+ *
+ * NEVER set divert. It routes wheel movement to HID++ instead of ordinary HID
+ * scrolling, and unless something is consuming those notifications the wheel
+ * simply stops working. Writes read-modify-write a single bit and carry this
+ * one through untouched.
+ */
+export declare const LOGITECH_HIRES_WHEEL_BIT: {
+    readonly divert: 1;
+    readonly hiRes: 2;
+    readonly invert: 4;
+};
+/** Byte 1 of getCapabilities; bit 3 is set when inversion is supported. */
+export declare const LOGITECH_HIRES_WHEEL_SUPPORTS_INVERT = 8;
+export declare const LOGITECH_THUMB_WHEEL: {
+    /** getThumbwheelInfo: [nativeRes(2), divertedRes(2), capabilities(2), ...]. */
+    readonly info: 0;
+    /** getThumbwheelStatus: [diverted, inverted]. */
+    readonly get: 16;
+    /** setThumbwheelReporting(diverted, inverted). */
+    readonly set: 32;
+};
+/** Bit 0 of the two-byte capability field at payload[4..5]. */
+export declare const LOGITECH_THUMB_WHEEL_SUPPORTS_INVERT = 1;
+export type LogitechWheelMode = "Freespin" | "Ratchet";
+export interface LogitechRatchetControl {
+    mode: LogitechWheelMode | null;
+    threshold: number;
+    defaultThreshold: number;
+}
+export declare function decodeRatchetControl(payload: Uint8Array | readonly number[]): LogitechRatchetControl | null;
+/**
+ * A 0x2111 write carries all three bytes, so each setter reads the trio first
+ * and changes only its own field. A write that drops the companion silently
+ * discards a setting it was never asked to touch.
+ */
+export declare function buildRatchetControlWrite(current: LogitechRatchetControl, change: {
+    mode?: LogitechWheelMode;
+    threshold?: number;
+}): number[];
+/**
+ * getCapabilities is [multiplier, flags]. Reading those two the other way
+ * round yields a nonsense multiplier of 28 on a wheel whose real multiplier
+ * is 15.
+ */
+export declare function decodeHiresWheelCapabilities(payload: Uint8Array | readonly number[]): {
+    multiplier: number;
+    supportsInvert: boolean;
+} | null;
+export declare function decodeHiresWheelMode(modeByte: number): {
+    hiRes: boolean;
+    inverted: boolean;
+    diverted: boolean;
+};
+/** Sets one bit and carries every other through, diversion included. */
+export declare function encodeHiresWheelMode(modeByte: number, bit: number, on: boolean): number;
+/**
+ * Thumb-wheel capabilities are the TWO-byte field at payload[4..5] — an
+ * MX Master 4 answers 0x0003 there and demonstrably honours inversion, which
+ * reading the single byte at payload[4] would have reported as unsupported.
+ */
+export declare function decodeThumbWheelSupportsInvert(payload: Uint8Array | readonly number[]): boolean | null;
+export declare function decodeThumbWheelStatus(payload: Uint8Array | readonly number[]): {
+    diverted: boolean;
+    inverted: boolean;
+} | null;
+/**
+ * Logi Options+ sets the diversion bit to implement horizontal scrolling, so a
+ * write that clears it takes that away. Diversion is preserved from the read.
+ */
+export declare function buildThumbWheelWrite(current: {
+    diverted: boolean;
+}, inverted: boolean): number[];
+//# sourceMappingURL=wheel.d.ts.map

package/dist/logitech/wheel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wheel.d.ts","sourceRoot":"","sources":["../../src/logitech/wheel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,oBAAoB;IAC/B,0EAA0E;;IAE1E,kEAAkE;;IAElE,gEAAgE;;CAExD,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;CAAuC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,MAAO,CAAC;AAE7C,eAAO,MAAM,oBAAoB;IAC/B,iDAAiD;;IAEjD,gDAAgD;;;IAGhD,uEAAuE;;CAE/D,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;;CAAuD,CAAC;AAE7F,2EAA2E;AAC3E,eAAO,MAAM,oCAAoC,IAAO,CAAC;AAEzD,eAAO,MAAM,oBAAoB;IAC/B,+EAA+E;;IAE/E,iDAAiD;;IAEjD,kDAAkD;;CAE1C,CAAC;AAEX,+DAA+D;AAC/D,eAAO,MAAM,oCAAoC,IAAO,CAAC;AAEzD,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GAAG,sBAAsB,GAAG,IAAI,CAW3G;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,iBAAiB,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,MAAM,EAAE,CAIV;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GACtC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAKxD;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAM/G;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,MAAM,CAEvF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GAAG,OAAO,GAAG,IAAI,CAKtG;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,GACtC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAKjD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAEhG"}