@openmouse/protocol 0.1.0

package/dist/drivers/logitech/bolt.d.ts

@@ -0,0 +1,41 @@
+/** Index probe on empty Bolt slots should fail fast; feature I/O keeps longer. */
+export declare const BOLT_INDEX_PROBE_TIMEOUT_MS = 800;
+/** Short-report HID++ collection (Lightspeed, Bolt receiver registers). */
+export declare function hasHidppShortCollection(device: HIDDevice): boolean;
+/** Long-report HID++ collection (required for Bolt device feature traffic). */
+export declare function hasHidppLongCollection(device: HIDDevice): boolean;
+/**
+ * HID++ over Bluetooth, which lives on its own vendor page instead of the
+ * 0xFF00 short/long pair. Kept separate from those two so Bolt peer collapsing
+ * and report-device selection keep reasoning only about 0xFF00 interfaces.
+ *
+ * @see HIDPP_BLUETOOTH_USAGE_PAGE
+ */
+export declare function hasHidppBluetoothCollection(device: HIDDevice): boolean;
+/**
+ * Prefer Bolt's long-report collection when both HID++ endpoints are present
+ * so feature traffic lands on the interface that can carry it.
+ */
+export declare function boltSupportScore(device: HIDDevice, supported: boolean): number;
+/**
+ * Collapse Bolt short+long peers to one sidebar entry (the long collection
+ * when both are authorized).
+ */
+export declare function collapseBoltPeers(devices: readonly HIDDevice[]): HIDDevice[];
+/**
+ * HID++ device-index probe order. Bolt may place the mouse on any of six
+ * pairing slots; Lightspeed stays 0x01 then 0xFF; unknown endpoints try self
+ * first so wired mice are not addressed as receivers.
+ */
+export declare function hidppIndexCandidates(productId: number, knownReceiverIds: ReadonlySet<number>): number[];
+/**
+ * Classify a root getFeature probe: only HID++ 2.0 replies mean a mouse is on
+ * that index. Bolt receivers answer HID++ 1.0 errors on empty slots / 0xFF.
+ */
+export declare function classifyHidpp20Probe(error: unknown, isTimeout: boolean): "hidpp20" | "absent";
+/**
+ * Bolt device features answer on the long-report collection (usage 2). The
+ * picker may hand us the short collection; use an already-authorized peer.
+ */
+export declare function resolveBoltReportDevice(device: HIDDevice, peers: readonly HIDDevice[]): HIDDevice;
+//# sourceMappingURL=bolt.d.ts.map

package/dist/drivers/logitech/bolt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bolt.d.ts","sourceRoot":"","sources":["../../../src/drivers/logitech/bolt.ts"],"names":[],"mappings":"AAeA,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAW/C,2EAA2E;AAC3E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAGlE;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAGjE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAGtE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAI9E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,EAAE,CAY5E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,MAAM,EAAE,CAIV;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,CAI7F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,SAAS,EAAE,GAC1B,SAAS,CAgBX"}

package/dist/drivers/logitech/bolt.js

@@ -0,0 +1,105 @@
+/**
+ * Logi Bolt transport helpers.
+ *
+ * Kept out of hidpp.ts so Bolt/MX work can land without rewriting the shared
+ * Lightspeed / direct-connect driver paths that other PRs touch often.
+ */
+import { BOLT_PAIRING_SLOTS, DEVICE_INDEX_DIRECT, DEVICE_INDEX_RECEIVER, HIDPP_BLUETOOTH_USAGE_PAGE, HIDPP_USAGE_PAGE, isBoltReceiverProduct, } from "@openmouse/protocol/logitech";
+/** Index probe on empty Bolt slots should fail fast; feature I/O keeps longer. */
+export const BOLT_INDEX_PROBE_TIMEOUT_MS = 800;
+/** True when a collection, or any nested child, matches. */
+function anyCollection(collections, matches) {
+    return collections.some((collection) => matches(collection) || anyCollection(collection.children, matches));
+}
+/** Short-report HID++ collection (Lightspeed, Bolt receiver registers). */
+export function hasHidppShortCollection(device) {
+    return anyCollection(device.collections, (collection) => collection.usagePage === HIDPP_USAGE_PAGE && collection.usage === 0x0001);
+}
+/** Long-report HID++ collection (required for Bolt device feature traffic). */
+export function hasHidppLongCollection(device) {
+    return anyCollection(device.collections, (collection) => collection.usagePage === HIDPP_USAGE_PAGE && collection.usage === 0x0002);
+}
+/**
+ * HID++ over Bluetooth, which lives on its own vendor page instead of the
+ * 0xFF00 short/long pair. Kept separate from those two so Bolt peer collapsing
+ * and report-device selection keep reasoning only about 0xFF00 interfaces.
+ *
+ * @see HIDPP_BLUETOOTH_USAGE_PAGE
+ */
+export function hasHidppBluetoothCollection(device) {
+    return anyCollection(device.collections, (collection) => collection.usagePage === HIDPP_BLUETOOTH_USAGE_PAGE);
+}
+/**
+ * Prefer Bolt's long-report collection when both HID++ endpoints are present
+ * so feature traffic lands on the interface that can carry it.
+ */
+export function boltSupportScore(device, supported) {
+    if (!supported)
+        return 0;
+    if (isBoltReceiverProduct(device.productId) && hasHidppLongCollection(device))
+        return 8;
+    return 6;
+}
+/**
+ * Collapse Bolt short+long peers to one sidebar entry (the long collection
+ * when both are authorized).
+ */
+export function collapseBoltPeers(devices) {
+    const boltLongPresent = new Set();
+    for (const device of devices) {
+        if (isBoltReceiverProduct(device.productId) && hasHidppLongCollection(device)) {
+            boltLongPresent.add(device.productId);
+        }
+    }
+    return devices.filter((device) => {
+        if (!isBoltReceiverProduct(device.productId) || !hasHidppShortCollection(device))
+            return true;
+        if (hasHidppLongCollection(device))
+            return true;
+        return !boltLongPresent.has(device.productId);
+    });
+}
+/**
+ * HID++ device-index probe order. Bolt may place the mouse on any of six
+ * pairing slots; Lightspeed stays 0x01 then 0xFF; unknown endpoints try self
+ * first so wired mice are not addressed as receivers.
+ */
+export function hidppIndexCandidates(productId, knownReceiverIds) {
+    if (isBoltReceiverProduct(productId))
+        return [...BOLT_PAIRING_SLOTS];
+    if (knownReceiverIds.has(productId))
+        return [DEVICE_INDEX_RECEIVER, DEVICE_INDEX_DIRECT];
+    return [DEVICE_INDEX_DIRECT, DEVICE_INDEX_RECEIVER];
+}
+/**
+ * Classify a root getFeature probe: only HID++ 2.0 replies mean a mouse is on
+ * that index. Bolt receivers answer HID++ 1.0 errors on empty slots / 0xFF.
+ */
+export function classifyHidpp20Probe(error, isTimeout) {
+    if (isTimeout)
+        return "absent";
+    if (error instanceof Error && /HID\+\+ 1\.0/.test(error.message))
+        return "absent";
+    return "hidpp20";
+}
+/**
+ * Bolt device features answer on the long-report collection (usage 2). The
+ * picker may hand us the short collection; use an already-authorized peer.
+ */
+export function resolveBoltReportDevice(device, peers) {
+    if (!isBoltReceiverProduct(device.productId))
+        return device;
+    if (hasHidppLongCollection(device))
+        return device;
+    const longPeer = peers.find((candidate) => candidate !== device
+        && candidate.vendorId === device.vendorId
+        && candidate.productId === device.productId
+        && hasHidppLongCollection(candidate));
+    if (!longPeer) {
+        throw new Error("Logi Bolt needs the HID++ long-report interface (usage 2). "
+            + "Reconnect and authorize both Bolt HID++ collections, or pick the usage-2 interface. "
+            + "Close Logi Options+ if the browser cannot open the device.");
+    }
+    return longPeer;
+}
+//# sourceMappingURL=bolt.js.map

package/dist/drivers/logitech/bolt.js.map

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

package/dist/drivers/logitech/hidpp.d.ts

@@ -0,0 +1,525 @@
+import type { MouseLighting, MouseStatus } from "../mouse-types.ts";
+import { type LogitechReprogrammableControl, type LogitechWheelMode } from "@openmouse/protocol/logitech";
+export { collapseBoltPeers, hasHidppBluetoothCollection, hasHidppLongCollection, hasHidppShortCollection, } from "./bolt.ts";
+import { type GamingSurfaceMode, type LightforceSwitchMode } from "./mode-status.ts";
+import { type DpiStagePlan, type LogitechButtonAction, type LogitechButtonBinding, type LogitechMacroStep, parseProfilesInfo, type OnboardProfile } from "./onboard-profiles.ts";
+export type { OnboardProfile };
+/** Raw, read-only evidence used to confirm an onboard-profile format. */
+export interface OnboardProfileVerification {
+    info: ReturnType<typeof parseProfilesInfo>;
+    infoReply: Uint8Array;
+    mode: "Onboard" | "Host" | "Unknown";
+    modeValue: number;
+    modeReply: Uint8Array;
+    currentSector: number;
+    currentProfileReply: Uint8Array;
+    directory: Uint8Array;
+    directoryCrcValid: boolean;
+    profiles: OnboardProfile[];
+    dpiCapabilities: VerificationCapability | null;
+    reportRateCapabilities: VerificationCapability | null;
+}
+export interface VerificationCapability {
+    featureId: number;
+    featureIndex: number;
+    featureVersion: number;
+    kind: "legacy" | "extended";
+    replies: Array<{
+        name: string;
+        bytes: Uint8Array;
+    }>;
+    decodedValues: number[];
+    error: string | null;
+}
+/**
+ * Master switch for writing DPI slots into profile flash.
+ *
+ * Enabled after probeProfileWriteSequence passed on a Pro X Superlight 2
+ * (format 7): writing a changed byte to sector 0x0002 appeared on read-back,
+ * and restoring it appeared too, both with valid checksums. That proves the
+ * memoryAddrWrite/memoryWrite/memoryWriteEnd sequence lands rather than being
+ * silently dropped. Run the probe again before trusting a new format.
+ */
+export declare const PROFILE_DPI_WRITES_ENABLED = true;
+export interface ProfileWriteProbeMismatch {
+    offset: number;
+    expected: number;
+    actual: number;
+}
+export interface ProfileWriteProbeStep {
+    name: string;
+    ok: boolean;
+    checksumValid: boolean;
+    mismatches: ProfileWriteProbeMismatch[];
+}
+export interface ProfileWriteProbe {
+    sector: number;
+    sectorSize: number;
+    offset: number;
+    originalByte: number;
+    probeByte: number;
+    steps: ProfileWriteProbeStep[];
+    ok: boolean;
+    restored: boolean;
+}
+export interface ProfileContentWriteProbeBackup {
+    formatId: number;
+    sector: number;
+    sectorSize: number;
+    originalMode: "Onboard" | "Host";
+    originalCurrentSector: number;
+    directory: Uint8Array;
+    profile: Uint8Array;
+    dpiOptions: number[];
+    reportRates: number[];
+}
+export interface ProfileContentWriteProbeStep {
+    setting: "name" | "dpi" | "polling";
+    intended: string;
+    storedExactly: boolean;
+    liveConfirmed: boolean | null;
+    restored: boolean;
+    error: string | null;
+}
+export interface ProfileContentWriteProbeReport {
+    backup: ProfileContentWriteProbeBackup;
+    steps: ProfileContentWriteProbeStep[];
+    restored: boolean;
+    modeRestored: boolean;
+    ok: boolean;
+}
+export declare class NotAMouseError extends Error {
+    constructor(name: string);
+}
+/** Whether 0x8090 on this model is the power-mode-only variant. */
+export declare function isPowerOnlyModeStatus(modelId: string | null | undefined): boolean;
+/**
+ * Whether the mouse exposes lift-off levels it can drive: only extended DPI
+ * (0x2202) carries one, and its byte 0 is the "no lift-off control" value, so
+ * a legacy-DPI mouse or a sensor reporting 0 advertises no levels.
+ */
+export declare function hasLiftOffControl(legacyDpi: boolean, lodByte: number | null): boolean;
+export type LogitechMouseStatus = MouseStatus;
+/**
+ * Extended DPI alone does not imply adjustable lift-off distance. Some mice,
+ * including the G309, expose 0x2202 but return the protocol's "no LOD control"
+ * value. Legacy DPI never carries LOD either.
+ */
+export declare function supportsLiveLiftOffControl(legacyDpi: boolean, liftOffDistance: LogitechMouseStatus["liftOffDistance"]): boolean;
+/**
+ * Resolves the active physical link from HID++ identity transport IDs. A
+ * receiver's USB PID does not match the paired mouse's Wireless transport ID;
+ * a mouse connected by cable matches its own USB transport ID. Direct-index
+ * probing remains the fallback for older devices that omit identity data.
+ */
+export declare function isWiredHidppConnection(productId: number, transportIds: Record<string, string>, directIndex: boolean): boolean;
+export declare class LogitechHidppClient {
+    private dpiOptionsCache;
+    private dpiFeatureResolved;
+    private rateFeatureResolved;
+    private reportRateFeatureIndex;
+    private supportedPollingRatesCache;
+    private livePollingRateHz;
+    /** Discovered by resolveDeviceIndex; null until the mouse has answered. */
+    private resolvedDeviceIndex;
+    /** Last format read from 0x8100, so a refusal can name it. */
+    private profileFormatId;
+    private wiredConnection;
+    /** Lift-off levels this device advertised; the single source of truth for both UI and validation. */
+    private lodCapabilities;
+    private supportedLods;
+    private rgbZone;
+    private colorLedZones;
+    private rgbLighting;
+    private rgbClaimed;
+    private rgbOriginalMode;
+    private readonly rateChangeWaiters;
+    /**
+     * Device used for HID++ feature sendReport. On Bolt this is the long-report
+     * collection (usage 2); elsewhere it is `device` itself.
+     */
+    private ioDevice;
+    private listeningDevices;
+    private readonly onInputReport;
+    private readonly waiters;
+    readonly device: HIDDevice;
+    constructor(device: HIDDevice);
+    /**
+     * True when the vendor interface belongs to the mouse itself instead of a
+     * receiver. Written as a getter because `useDefineForClassFields` runs
+     * field initializers before the `device` parameter property is assigned.
+     */
+    private get isDirectConnect();
+    private get isBoltReceiver();
+    /** @see hasHidppBluetoothCollection */
+    private get isBluetooth();
+    /** HID++ device index: a receiver pairing slot, or the mouse itself. */
+    private get deviceIndex();
+    private get reportDevice();
+    /**
+     * Finds which HID++ device index this connection answers on.
+     *
+     * A mouse reached through its receiver answers on a pairing slot (usually
+     * 0x01 on Lightspeed; any of 1..6 on Bolt). The same mouse plugged in by
+     * cable answers as itself (0xFF). That cannot be read from the descriptors.
+     *
+     * Only a HID++ 2.0 reply (success or 2.0 error) counts. Bolt receivers answer
+     * HID++ 1.0 errors on empty slots and on 0xFF; treating those as "answered"
+     * made OpenMouse lock onto the receiver and report "invalid command".
+     * A G HUB merge can also push the mouse off slot 0x01, so receivers probe
+     * every pairing slot, not just the first.
+     *
+     * So ask. The root feature query is the cheapest request there is, and the
+     * wrong index simply times out.
+     */
+    private resolveDeviceIndex;
+    /** Root getFeature(firmware) distinguishes HID++ 2.0 from receiver noise. */
+    private probeHidpp20Root;
+    /**
+     * Whether the slot currently probed exposes a DPI feature — the same sensor
+     * check readStatus uses, so a keyboard paired to a merged receiver is never
+     * mistaken for the mouse.
+     */
+    private hasDpiFeature;
+    /**
+     * Any Logitech device speaking HID++, not just the receivers we happen to
+     * have listed. Whether it is a *mouse* cannot be told from descriptors —
+     * keyboards and headsets use the same transport — so that is decided after
+     * connecting, by asking for a DPI feature. See readStatus.
+     */
+    static isSupported(device: HIDDevice): boolean;
+    /**
+     * Prefer Bolt's long-report collection when both HID++ endpoints are present
+     * so feature traffic lands on the interface that can carry it.
+     */
+    static supportScore(device: HIDDevice): number;
+    /** @see collapseBoltPeers */
+    static collapseBoltPeers(devices: readonly HIDDevice[]): HIDDevice[];
+    /** Known receivers, kept as the fast path for the WebHID picker's filters. */
+    static isKnownReceiver(device: HIDDevice): boolean;
+    static requestReceiver(): Promise<LogitechHidppClient | null>;
+    static reconnectAuthorizedReceiver(): Promise<LogitechHidppClient | null>;
+    readStatus(): Promise<LogitechMouseStatus>;
+    close(): Promise<void>;
+    setLighting(lighting: MouseLighting): Promise<MouseLighting>;
+    private readColorLedLighting;
+    setPollingRate(pollingRateHz: number): Promise<number>;
+    private setExtendedReportRate;
+    getDpiOptions(): Promise<number[]>;
+    setDpi(dpi: number, dpiY?: number): Promise<number>;
+    setLiftOffDistance(liftOffDistance: NonNullable<LogitechMouseStatus["liftOffDistance"]>): Promise<NonNullable<LogitechMouseStatus["liftOffDistance"]>>;
+    setAnalogButtonTuning(button: 0 | 1, tuning: {
+        actuation: number;
+        rapidTrigger: number;
+        haptics: number;
+    }): Promise<void>;
+    /**
+     * Switches the mouse between running from profile flash and being driven live
+     * by software. This is what G HUB's "Onboard Memory Mode" toggle does.
+     */
+    setOnboardMode(mode: "Onboard" | "Host"): Promise<"Onboard" | "Host">;
+    /** Switches which stored profile the mouse runs. Volatile — no flash write. */
+    setCurrentProfile(sector: number): Promise<void>;
+    /**
+     * Enables or disables a profile slot.
+     *
+     * WRITES FLASH. The directory sector is read, one flag byte changed, the
+     * checksum recomputed and the whole sector written back — one erase/write
+     * cycle per call. See docs/logitech-onboard-profiles.md. The write sequence
+     * itself has not been verified on hardware; callers should confirm with the
+     * user first.
+     */
+    setProfileEnabled(sector: number, enabled: boolean): Promise<void>;
+    /**
+     * Restores every onboard profile byte-for-byte to the vendor's captured
+     * defaults, then leaves only the first profile enabled and running.
+     *
+     * WRITES FLASH. Support is deliberately limited to a profile format and
+     * sector geometry for which a complete vendor reset was captured. Using a
+     * decoded subset here would leave unknown button or lighting settings behind.
+     */
+    resetAllOnboardProfiles(): Promise<void>;
+    /**
+     * Sets the bunny-hop timeout on the active profile.
+     *
+     * WRITES FLASH — one erase/write cycle. Stored as ms / 10, with 0 meaning
+     * off; G HUB's range is 100-1000 ms. The encoding is confirmed on hardware,
+     * but the write sequence itself is not, so callers should confirm first.
+     */
+    /**
+     * Reads the active profile and the context needed to write it back. Every
+     * profile write starts here so the format check, the checksum check and the
+     * sector-size fallback cannot drift apart between settings.
+     */
+    private openActiveProfile;
+    /**
+     * Writes every changed setting of the active profile in one sector write.
+     *
+     * Flash is erased a whole sector at a time, so settings that share the sector
+     * must be applied together: writing them one at a time would cost an erase
+     * cycle each, and each write would be built from a read the previous one had
+     * already invalidated.
+     */
+    writeActiveProfile(values: {
+        bunnyHoppingMs?: number | null;
+        dpiStages?: DpiStagePlan | null;
+        reportRateWirelessHz?: number | null;
+        reportRateWiredHz?: number | null;
+        name?: string | null;
+        buttonAssignments?: Array<{
+            layer: "primary" | "g-shift";
+            button: number;
+            binding: LogitechButtonAction | LogitechButtonBinding;
+        }>;
+        buttonMacros?: Array<{
+            layer: "primary" | "g-shift";
+            button: number;
+            steps: LogitechMacroStep[];
+        }>;
+        /** Defaults to the running profile when omitted. */
+        sector?: number;
+    }): Promise<void>;
+    setBunnyHoppingMs(milliseconds: number): Promise<void>;
+    setProfileDpiStages(plan: DpiStagePlan): Promise<void>;
+    /**
+     * memoryAddrWrite declares the destination and length, memoryWrite streams
+     * 16 bytes at a time, memoryWriteEnd commits and validates the checksum.
+     */
+    private writeProfileSector;
+    /**
+     * Proves the profile write sequence on hardware.
+     *
+     * A no-op rewrite would be useless: writing a sector's own bytes back reads
+     * identical whether the write landed or was silently ignored. So this flips
+     * one byte, checks the change actually appears, then restores it and checks
+     * the restore appears too. Both halves must pass.
+     *
+     * The target is an unused sector — disabled, and never the active profile —
+     * so nothing the user relies on is at risk, and the original bytes are held
+     * in memory for restore if a step fails midway. Cost is two erase cycles of
+     * roughly 100,000, on a sector that is not in use.
+     */
+    probeProfileWriteSequence(): Promise<ProfileWriteProbe>;
+    /**
+     * Reads and retains everything required to recover a legacy format-2/3/4 profile before
+     * the semantic write probe starts. The UI copies this object first.
+     */
+    prepareProfileContentWriteProbe(): Promise<ProfileContentWriteProbeBackup>;
+    /**
+     * Applies temporary format-2/3/4 name, DPI and rate values, confirms each sector
+     * read-back, confirms live DPI/rate, and restores the original after every
+     * step. The caller must copy the backup before invoking this method.
+     */
+    runProfileContentWriteProbe(backup: ProfileContentWriteProbeBackup): Promise<ProfileContentWriteProbeReport>;
+    /**
+     * Reads and decodes every onboard profile. Deliberately not part of
+     * readStatus: a full pass is ~80 HID++ round trips, far too slow for the
+     * refresh loop, so the UI loads it on demand.
+     */
+    readOnboardProfiles(): Promise<OnboardProfile[]>;
+    /**
+     * Collects a self-contained, read-only dump for validating any profile
+     * format. Unlike readOnboardProfiles, this keeps the full directory and the
+     * raw protocol replies so a maintainer can verify geometry and parsing rather
+     * than trusting OpenMouse's current assumptions.
+     */
+    readOnboardProfileVerification(): Promise<OnboardProfileVerification>;
+    private verificationFeature;
+    private readDpiVerificationCapability;
+    private readReportRateVerificationCapability;
+    /**
+     * memoryRead returns 16 bytes per call and rejects a read running past the
+     * end of the sector, so a sector length that is not a multiple of 16 needs its
+     * tail fetched from `length - 16`, overlapping the previous chunk.
+     */
+    private readProfileSector;
+    /**
+     * Haptic configuration, or null on a device without feature 0x19B0. Only the
+     * MX Master 4 is known to carry it.
+     */
+    private readHapticConfig;
+    /**
+     * Read-modify-write of the two-byte pair, then verify. Both fields share the
+     * write, so a caller changing one has to supply the other exactly as the
+     * device reports it, and bits 2-7 of the flag byte ride through untouched.
+     */
+    private writeHapticConfig;
+    /**
+     * Scroll-wheel state across 0x2111, 0x2121 and 0x2150. Every field stays
+     * absent rather than guessed when its feature is missing, so a mouse
+     * without a thumb wheel does not get a control that can only fail.
+     */
+    private readWheelState;
+    private readThumbWheelState;
+    /** 0x2111 carries all three bytes, so each setter changes only its field. */
+    private writeRatchetControl;
+    setWheelMode(mode: LogitechWheelMode): Promise<LogitechWheelMode>;
+    /** Passing null disables SmartShift; the ratchet mode is preserved either way. */
+    setSmartShiftThreshold(threshold: number | null): Promise<number>;
+    /**
+     * Flips one bit of the 0x2121 mode byte. Diversion is read and carried
+     * through: setting it routes the wheel to HID++ and stops it scrolling, and
+     * clearing it would take that away from whatever set it.
+     */
+    private writeWheelModeBit;
+    setHiResScroll(enabled: boolean): Promise<boolean>;
+    setInvertScroll(inverted: boolean): Promise<boolean>;
+    /**
+     * Inverts the thumb wheel. Logi Options+ sets the diversion bit to implement
+     * horizontal scrolling, so it is read and preserved rather than rewritten.
+     */
+    setThumbWheelInverted(inverted: boolean): Promise<boolean>;
+    /** The editable name, or null on a device without feature 0x0007. */
+    private readFriendlyName;
+    /**
+     * Renames the device, then reads the name back. The read-back is not
+     * ceremony: firmware that acknowledges a write and quietly keeps its old
+     * value would otherwise look like a successful rename.
+     */
+    setFriendlyName(name: string): Promise<string>;
+    /**
+     * Easy-Switch slots, or null without feature 0x1815. Slot indices are
+     * zero-based here as they are on the wire; the button under the mouse counts
+     * from one, so anything user-facing has to add one.
+     */
+    private readHostState;
+    /**
+     * Asks the mouse to move to another Easy-Switch slot.
+     *
+     * Named for what it can prove. A successful switch disconnects this host, so
+     * there is no state left to read back and no way to confirm the mouse
+     * arrived — disconnection IS the expected success path, not a failure.
+     * Resolving means the command reached the device: either it acknowledged, or
+     * it left before an acknowledgement could be observed and the report was
+     * accepted by the transport.
+     *
+     * An empty slot is refused outright. Switching there leaves the mouse
+     * unreachable until someone presses the button on its underside.
+     */
+    requestHostSwitch(slot: number): Promise<void>;
+    /**
+     * Reads every reprogrammable control, what it currently does, and where it
+     * may legally be pointed.
+     *
+     * Two round-trips per control, which is why this is not part of readStatus:
+     * on an MX Master 4 that is eighteen more exchanges, enough on a wireless
+     * link to start timing other reads out. Call it on connect and after a
+     * write, not on a poll.
+     *
+     * The control table itself never changes for a given device, so it is read
+     * once per connection; only the reporting is re-read.
+     */
+    readButtons(): Promise<LogitechReprogrammableControl[]>;
+    /**
+     * Points one button at another control's action.
+     *
+     * The device is asked what is legal before anything is written, and the
+     * result is read back afterwards — firmware that acknowledges a remap and
+     * keeps its old mapping would otherwise look like a success.
+     */
+    setButtonMapping(controlId: number, targetControlId: number): Promise<LogitechReprogrammableControl[]>;
+    /**
+     * Hands every diverted button back to the hardware.
+     *
+     * A diverted button sends HID++ notifications instead of acting, which is
+     * how a vendor application implements behaviours of its own. Logi Options+
+     * uses the temporary flag and the mouse clears that itself once Options+
+     * stops — but the persistent flag survives, so a button left that way stays
+     * dead until something clears it. That something has to exist somewhere.
+     */
+    clearButtonDiversion(): Promise<LogitechReprogrammableControl[]>;
+    /** Sets haptic strength, leaving the flag byte as the device reports it. */
+    setHapticIntensity(intensity: number): Promise<number>;
+    setHapticEnabled(enabled: boolean): Promise<boolean>;
+    setHapticBatterySaving(enabled: boolean): Promise<boolean>;
+    /**
+     * Fires the motor once at whatever strength is set. Nothing persists, so
+     * this is safe to use as feedback. The reply reports whether the motor was
+     * already running, which says nothing about the effect itself.
+     */
+    playHapticEffect(effect?: number): Promise<void>;
+    setGamingSurfaceMode(mode: GamingSurfaceMode): Promise<GamingSurfaceMode>;
+    setLightforceSwitchMode(mode: LightforceSwitchMode): Promise<LightforceSwitchMode>;
+    /**
+     * Read-modify-write of modeStatus1, then verify. Both fields share the byte,
+     * so passing them together writes once instead of twice; the change mask
+     * stops the firmware touching bits neither field names.
+     * Reading first keeps this correct if a future field spans bits we do not know about.
+     */
+    setModeStatus(values: {
+        gamingSurface?: GamingSurfaceMode | null;
+        lightforce?: LightforceSwitchMode | null;
+    }): Promise<void>;
+    /** Byte 4 of getModeStatus, carrying both the surface and LightForce fields. */
+    private readModeStatus;
+    private open;
+    private bindBoltIoDevice;
+    /** Prefer extended DPI (0x2202); fall back to legacy Adjustable DPI (0x2201). */
+    private resolveDpiFeature;
+    /** Prefer extended report rate (0x8061); fall back to legacy Report Rate (0x8060). */
+    private resolveReportRateFeature;
+    private readLegacyDpi;
+    private readLegacyDpiList;
+    private setLegacyDpi;
+    private readLegacyReportRates;
+    private getSupportedPollingRateOptions;
+    private readLegacyReportRate;
+    private setLegacyReportRate;
+    /**
+     * Values that cannot change while a connection is open. Easy-Switch is the
+     * clearest case: the slot count is fixed and the current slot changing IS
+     * the connection ending, because that is what switching host does. The
+     * friendly name only moves when something renames it, and this client drops
+     * the entry after its own write.
+     *
+     * Re-reading these was costing six round-trips of radio every refresh, on
+     * top of a feature lookup per read. On a wireless mouse that is enough for
+     * some reads to time out, which surfaces as controls vanishing and coming
+     * back a few seconds later.
+     */
+    private hostStateCache;
+    private controlInfoCache;
+    private friendlyNameCache;
+    private wheelCapabilityCache;
+    private getFeature;
+    private readName;
+    /**
+     * 0x1004 UNIFIED_BATTERY getStatus: [stateOfCharge, batteryLevel,
+     * chargingStatus, externalPower].
+     *
+     * The charging enum here is NOT the one 0x1000 uses, which is what this
+     * previously decoded: on 0x1004, 2 means charging slowly and 4 means a
+     * charging fault, where on 0x1000 those are "almost full" and "charging
+     * slowly". A slow charge was therefore reported as almost full.
+     */
+    private readBattery;
+    /**
+     * 0x1000 BATTERY_LEVEL_STATUS getBatteryLevelStatus:
+     * [dischargeLevel, nextLevel, batteryStatus].
+     *
+     * Older mice expose only this. Without it they reported no battery at all,
+     * because the driver probed 0x1004, 0x1001 and 0x1f20 and nothing else.
+     */
+    private readBatteryLevelStatus;
+    private readBatteryVoltage;
+    private readAdcMeasurement;
+    private estimateBatteryPercent;
+    private readDpi;
+    private readAnalogButtonTuning;
+    private readDpiCapabilities;
+    private readRgbLighting;
+    private readPerLedLighting;
+    private readDpiConfiguration;
+    private readSupportedPollingRates;
+    private readPollingRate;
+    private waitForRateChange;
+    private readProfileState;
+    private readIdentity;
+    private ensureHostControl;
+    private readFirmware;
+    private request;
+    private requestWithOptions;
+    private requestLong;
+    private waitForResponse;
+}
+//# sourceMappingURL=hidpp.d.ts.map