dualsense-ts 6.2.0 → 6.4.0

package/src/dualsense.ts

@@ -23,6 +23,10 @@ import {
   InputId,
   ChargeStatus,
   PulseOptions,
+  FirmwareInfo,
+  FactoryInfo,
+  DualsenseColor,
+  DualsenseColorMap,
 } from "./hid";
 import { Intensity } from "./math";
 
@@ -96,23 +100,48 @@ export class Dualsense extends Input<Dualsense> {
   public readonly accelerometer: Accelerometer;
   /** Battery level and charging status */
   public readonly battery: Battery;
+  /** Whether a microphone is connected (e.g. headset mic or USB mic) */
+  public readonly microphone: Momentary;
+  /** Whether headphones are connected to the controller's 3.5mm jack */
+  public readonly headphone: Momentary;
   /** The RGB light bar at the top of the controller */
   public readonly lightbar = new Lightbar();
   /** The 5 white player indicator LEDs */
   public readonly playerLeds = new PlayerLeds();
 
-  /** Buffered battery reading, sampled on a slow cadence */
+  /**
+   * Buffered battery reading, sampled on a slow cadence
+   * Battery readings are prone to flip-flopping, so we buffer them
+   */
   private readonly pendingBattery = {
     peakLevel: 0,
     status: ChargeStatus.Discharging as ChargeStatus,
   };
 
-  /** Represents the underlying HID device. Provides input events */
+  /** Represents the underlying HID device. Provides input events. */
   public readonly hid: DualsenseHID;
 
+  /**
+   * Firmware and hardware information.
+   * Contains sensible defaults until the device reports its actual values.
+   */
+  public get firmwareInfo(): FirmwareInfo {
+    return this.hid.firmwareInfo;
+  }
+
+  /**
+   * Factory information (serial number, body color, board revision).
+   * Contains sensible defaults until the device reports its actual values.
+   * On Linux over Bluetooth the defaults persist (kernel limitation).
+   */
+  public get factoryInfo(): FactoryInfo {
+    return this.hid.factoryInfo;
+  }
+
   /** A virtual button representing whether or not a controller is connected */
   public readonly connection: Momentary;
 
+  /** True if any input at all is active or changing */
   public get active(): boolean {
     return Object.values(this).some(
       (input) => input !== this && input instanceof Input && input.active,
@@ -124,14 +153,16 @@ export class Dualsense extends Input<Dualsense> {
     return this.hid.wireless;
   }
 
-  /** Unique identifier for the connected device (path or fingerprint) */
-  public get deviceId(): string | undefined {
-    return this.hid.provider.deviceId;
+  /** Body color of the controller */
+  public get color(): DualsenseColor {
+    const { colorCode } = this.hid.factoryInfo;
+    if (colorCode in DualsenseColorMap) return DualsenseColorMap[colorCode];
+    return DualsenseColor.Unknown;
   }
 
-  /** Hardware serial number of the connected device, if available */
-  public get serialNumber(): string | undefined {
-    return this.hid.provider.serialNumber;
+  /** Factory-stamped serial number of the controller */
+  public get serialNumber(): string {
+    return this.hid.factoryInfo.serialNumber;
   }
 
   constructor(params: DualsenseParams = {}) {
@@ -147,6 +178,8 @@ export class Dualsense extends Input<Dualsense> {
       name: "Mute",
       ...(params.mute ?? {}),
     });
+    this.microphone = new Momentary({ icon: "🎤", name: "Microphone" });
+    this.headphone = new Momentary({ icon: "🎧", name: "Headphone" });
     this.options = new Momentary({
       icon: "⋯",
       name: "Options",
@@ -221,6 +254,10 @@ export class Dualsense extends Input<Dualsense> {
     });
 
     this.connection[InputSet](false);
+    // If a HID instance was supplied externally (e.g. by DualsenseManager),
+    // the owner is responsible for driving discovery + reconnection. Otherwise
+    // construct a default platform provider and run our own discovery loop.
+    const externallyManaged = params.hid != null;
     this.hid = params.hid ?? new DualsenseHID(new PlatformHIDProvider());
     this.hid.register((state: DualsenseHIDState) => {
       this.processHID(state);
@@ -231,24 +268,32 @@ export class Dualsense extends Input<Dualsense> {
     const lightbarMemo = { key: "" };
     const playerLedsMemo = { key: "" };
 
-    /** Refresh connection state */
-    let lastConnected = false;
-    setInterval(() => {
-      const {
-        provider: { connected },
-      } = this.hid;
-
+    // Mirror transport-level connect/disconnect into the connection Momentary,
+    // and invalidate output memos on rising-edge connect so the output loop
+    // re-pushes desired state to the new device.
+    this.hid.onConnectionChange((connected) => {
       this.connection[InputSet](connected);
-      if (connected && !lastConnected) {
-        // Invalidate memos so the output loop restores desired state on reconnect.
+      if (connected) {
         triggerFeedbackMemo.left = "";
         triggerFeedbackMemo.right = "";
         lightbarMemo.key = "";
         playerLedsMemo.key = "";
       }
-      lastConnected = connected;
-      if (!connected) this.hid.provider.connect();
-    }, 200);
+    });
+    // Seed the initial state in case the provider was already attached.
+    this.connection[InputSet](this.hid.provider.connected);
+
+    // Standalone mode: poll for devices and reconnect on drop. In managed
+    // mode the manager owns this and we must NOT race with it.
+    if (!externallyManaged) {
+      setInterval(() => {
+        if (!this.hid.provider.connected) {
+          void Promise.resolve(this.hid.provider.connect()).catch(() => {
+            /* surfaced via onError */
+          });
+        }
+      }, 200);
+    }
 
     /** Refresh battery state on a slow cadence to filter transient glitches */
     setInterval(() => {
@@ -308,13 +353,16 @@ export class Dualsense extends Input<Dualsense> {
 
       const playerLedsKey = this.playerLeds.toKey();
       if (playerLedsKey !== playerLedsMemo.key) {
-        this.hid.setPlayerLeds(this.playerLeds.bitmask, this.playerLeds.brightness);
+        this.hid.setPlayerLeds(
+          this.playerLeds.bitmask,
+          this.playerLeds.brightness,
+        );
         playerLedsMemo.key = playerLedsKey;
       }
-
     }, 1000 / 30);
   }
 
+  /** Average rumble strength across both halves of the controller. */
   private get rumbleIntensity(): number {
     return (this.left.rumble() + this.right.rumble()) / 2;
   }
@@ -332,7 +380,7 @@ export class Dualsense extends Input<Dualsense> {
     return this.rumbleIntensity;
   }
 
-  /** Distributes HID event values to the controller's inputs */
+  /** Distributes HID event values to the controller's public inputs. */
   private processHID(state: DualsenseHIDState): void {
     this.ps[InputSet](state[InputId.Playstation]);
     this.options[InputSet](state[InputId.Options]);
@@ -340,6 +388,8 @@ export class Dualsense extends Input<Dualsense> {
 
     this.mute[InputSet](state[InputId.Mute]);
     this.mute.status[InputSet](state[InputId.MuteLed]);
+    this.microphone[InputSet](state[InputId.Microphone]);
+    this.headphone[InputSet](state[InputId.Headphone]);
 
     this.triangle[InputSet](state[InputId.Triangle]);
     this.circle[InputSet](state[InputId.Circle]);

package/src/hid/bt_checksum.ts

@@ -56,3 +56,42 @@ export function computeBluetoothReportChecksum(buffer: Uint8Array): number {
   return result >>> 0;
 }
 
+/** Standard CRC-32 lookup table (polynomial 0xEDB88320) */
+const crc32Table: number[] = (() => {
+  const table: number[] = [];
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+/**
+ * Compute CRC-32 for a Bluetooth feature report.
+ * The CRC covers the HID transaction header (0x53), the report ID,
+ * and all payload bytes except the last 4 (which hold the CRC itself).
+ * Uses standard CRC-32 with final inversion.
+ */
+export function computeFeatureReportChecksum(
+  reportId: number,
+  buffer: Uint8Array,
+): number {
+  let crc = 0xffffffff >>> 0;
+
+  // Feed prefix bytes: 0x53 (SET_REPORT feature) + report ID
+  crc = (crc >>> 8) ^ crc32Table[(crc ^ 0x53) & 0xff];
+  crc = (crc >>> 8) ^ crc32Table[(crc ^ reportId) & 0xff];
+
+  // Feed payload data (exclude last 4 bytes reserved for CRC)
+  const dataLen = buffer.length - 4;
+  for (let i = 0; i < dataLen; i++) {
+    crc = (crc >>> 8) ^ crc32Table[(crc ^ buffer[i]) & 0xff];
+  }
+
+  // Final XOR (standard CRC-32 finalization)
+  return (crc ^ 0xffffffff) >>> 0;
+}
+

package/src/hid/dualsense_hid.ts

@@ -5,9 +5,14 @@ import {
   DefaultDualsenseHIDState,
 } from "./hid_provider";
 import { computeBluetoothReportChecksum } from "./bt_checksum";
+import { FirmwareInfo, DefaultFirmwareInfo, readFirmwareInfo } from "./firmware_info";
+import { FactoryInfo, DefaultFactoryInfo, readFactoryInfo } from "./factory_info";
+import { readMacAddress } from "./pairing_info";
 
 export type HIDCallback = (state: DualsenseHIDState) => void;
 export type ErrorCallback = (error: Error) => void;
+export type ReadyCallback = () => void;
+export type ConnectionCallback = (connected: boolean) => void;
 
 const SCOPE_A = 1;
 const SCOPE_B = 2;
@@ -28,10 +33,26 @@ export class DualsenseHID {
   private readonly subscribers = new Set<HIDCallback>();
   /** Subscribers waiting for error updates */
   private readonly errorSubscribers = new Set<ErrorCallback>();
+  /** Subscribers waiting for firmware/factory info to become available */
+  private readonly readySubscribers = new Set<ReadyCallback>();
+  /** Subscribers tracking transport-level connect/disconnect events */
+  private readonly connectionSubscribers = new Set<ConnectionCallback>();
+  /** True once firmware/factory info has been loaded for the current connection */
+  private identityResolved = false;
+  /** Pending retry timer for identity loading after a transient failure */
+  private identityRetryTimer?: ReturnType<typeof setTimeout>;
+  /** Number of identity-load attempts made for the current connection */
+  private identityRetryCount = 0;
   /** Queue of pending HID commands */
   private pendingCommands: CommandEvent[] = [];
   /** Most recent HID state of the device */
   public state: DualsenseHIDState = { ...DefaultDualsenseHIDState };
+  /** Firmware and hardware information, populated after connection */
+  public firmwareInfo: FirmwareInfo = DefaultFirmwareInfo;
+  /** Factory information (serial, color, board revision), populated after connection */
+  public factoryInfo: FactoryInfo = DefaultFactoryInfo;
+  /** Bluetooth MAC address from Feature Report 0x09, populated after connection */
+  public macAddress?: string;
 
   constructor(
     readonly provider: HIDProvider,
@@ -39,6 +60,24 @@ export class DualsenseHID {
   ) {
     provider.onData = this.set.bind(this);
     provider.onError = this.handleError.bind(this);
+    provider.onConnect = () => {
+      // Keep cached firmware/factory info from the prior session so that
+      // consumers see identity details immediately on a reconnection
+      // event. The background loadIdentity() call will verify and refresh
+      // the cache — if the hardware identity turns out different (e.g. a
+      // different controller grabbed the same slot), the fields get
+      // overwritten then.
+      this.firmwareFetch = undefined;
+      this.factoryFetch = undefined;
+      this.identityResolved = false;
+      this.cancelIdentityRetry();
+      this.connectionSubscribers.forEach((cb) => cb(true));
+      void this.loadIdentity();
+    };
+    provider.onDisconnect = () => {
+      this.cancelIdentityRetry();
+      this.connectionSubscribers.forEach((cb) => cb(false));
+    };
 
     setInterval(() => {
       if (this.pendingCommands.length > 0) {
@@ -79,6 +118,56 @@ export class DualsenseHID {
     if (type === "error") this.errorSubscribers.add(callback);
   }
 
+  /**
+   * Subscribe to notification when firmware/factory info finishes loading
+   * after a connect. Fires once per connection — either when identity has
+   * been resolved, or when we've given up retrying. If identity is already
+   * resolved at the time of subscription, the callback fires synchronously.
+   */
+  public onReady(callback: ReadyCallback): () => void {
+    if (this.identityResolved) {
+      callback();
+      return () => {};
+    }
+    this.readySubscribers.add(callback);
+    return () => this.readySubscribers.delete(callback);
+  }
+
+  /** True if firmware/factory info has been loaded (or given up on) for the current connection */
+  public get ready(): boolean {
+    return this.identityResolved;
+  }
+
+  /**
+   * Subscribe to transport-level connect/disconnect events. Useful for
+   * mirroring connection state into an Input without polling. Returns
+   * an unsubscribe function.
+   */
+  public onConnectionChange(callback: ConnectionCallback): () => void {
+    this.connectionSubscribers.add(callback);
+    return () => this.connectionSubscribers.delete(callback);
+  }
+
+  /**
+   * Stable hardware identity for this controller, derived from the most
+   * trustworthy info available. Prefers the Bluetooth MAC address (from
+   * Feature Report 0x09, works on every transport and platform), then
+   * falls back to the factory serial, then firmware deviceInfo.
+   * Returns undefined until identity info has been read.
+   */
+  public get identity(): string | undefined {
+    if (this.macAddress) {
+      return `mac:${this.macAddress}`;
+    }
+    if (this.factoryInfo.serialNumber !== DefaultFactoryInfo.serialNumber) {
+      return `serial:${this.factoryInfo.serialNumber}`;
+    }
+    if (this.firmwareInfo.deviceInfo !== DefaultFirmwareInfo.deviceInfo) {
+      return `device:${this.firmwareInfo.deviceInfo}`;
+    }
+    return undefined;
+  }
+
   /** Update the HID state and pass it along to all state subscribers */
   private set(state: DualsenseHIDState): void {
     this.state = state;
@@ -90,6 +179,147 @@ export class DualsenseHID {
     this.errorSubscribers.forEach((callback) => callback(error));
   }
 
+  /** Maximum identity-load retry attempts per connection */
+  private static readonly IDENTITY_MAX_ATTEMPTS = 5;
+  /** Backoff schedule (ms) for identity-load retries */
+  private static readonly IDENTITY_BACKOFF_MS = [500, 1500, 3000, 5000];
+
+  /**
+   * Attempt to read firmware + factory info for the current connection,
+   * with retry on failure. Marks identity as resolved on success or after
+   * exhausting all attempts (so consumers don't wait forever).
+   *
+   * If cached firmware/factory info exists from a prior session, identity
+   * is resolved immediately (so the connection event has full details),
+   * then a background verification re-reads the device to confirm.
+   */
+  private async loadIdentity(): Promise<void> {
+    if (!this.provider.connected) return;
+
+    // Fast path: if we already have cached identity from a prior session,
+    // mark resolved immediately so consumers see it on the connection event.
+    // Then continue to the verification read below.
+    const hadCachedIdentity = this.identity !== undefined;
+    if (hadCachedIdentity) {
+      this.markIdentityResolved();
+    }
+
+    this.identityRetryCount += 1;
+
+    try {
+      // Read MAC address first — simple feature report, no firmware gate.
+      const mac = await readMacAddress(this.provider);
+      if (mac) this.macAddress = mac;
+
+      // Always read fresh from the device (bypass the idempotency cache).
+      const fw = await readFirmwareInfo(this.provider);
+      if (fw) {
+        this.firmwareInfo = fw;
+        this.firmwareFetch = Promise.resolve(fw);
+
+        const fi = await readFactoryInfo(
+          this.provider,
+          fw.hardwareInfo,
+          fw.mainFirmwareVersionRaw,
+        );
+        this.factoryInfo = fi ?? DefaultFactoryInfo;
+        this.factoryFetch = Promise.resolve(this.factoryInfo);
+
+        if (!hadCachedIdentity) {
+          this.markIdentityResolved();
+        }
+        return;
+      }
+    } catch {
+      // Treat throws the same as undefined — fall through to retry logic.
+    }
+
+    // Failure — clear in-flight promises so the next attempt can retry.
+    this.firmwareFetch = undefined;
+    this.factoryFetch = undefined;
+
+    if (
+      this.identityRetryCount >= DualsenseHID.IDENTITY_MAX_ATTEMPTS ||
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      !this.provider.connected
+    ) {
+      this.markIdentityResolved();
+      return;
+    }
+
+    const delay =
+      DualsenseHID.IDENTITY_BACKOFF_MS[
+        Math.min(
+          this.identityRetryCount - 1,
+          DualsenseHID.IDENTITY_BACKOFF_MS.length - 1,
+        )
+      ];
+    this.identityRetryTimer = setTimeout(() => {
+      this.identityRetryTimer = undefined;
+      void this.loadIdentity();
+    }, delay);
+  }
+
+  /** Mark identity loading as complete and notify subscribers */
+  private markIdentityResolved(): void {
+    if (this.identityResolved) return;
+    this.identityResolved = true;
+    this.identityRetryCount = 0;
+    const callbacks = Array.from(this.readySubscribers);
+    this.readySubscribers.clear();
+    callbacks.forEach((cb) => cb());
+  }
+
+  /** Cancel any pending identity-load retry */
+  private cancelIdentityRetry(): void {
+    if (this.identityRetryTimer) {
+      clearTimeout(this.identityRetryTimer);
+      this.identityRetryTimer = undefined;
+    }
+    this.identityRetryCount = 0;
+  }
+
+  /** In-flight firmware info fetch, deduped across callers within a connection */
+  private firmwareFetch?: Promise<FirmwareInfo>;
+  /** In-flight factory info fetch, deduped across callers within a connection */
+  private factoryFetch?: Promise<FactoryInfo>;
+
+  /**
+   * Read firmware info from the controller (Feature Report 0x20).
+   * Idempotent: returns the cached value if already fetched, or the
+   * in-flight promise if a fetch is already underway.
+   */
+  public fetchFirmwareInfo(): Promise<FirmwareInfo> {
+    if (this.firmwareInfo !== DefaultFirmwareInfo) return Promise.resolve(this.firmwareInfo);
+    if (this.firmwareFetch) return this.firmwareFetch;
+    this.firmwareFetch = readFirmwareInfo(this.provider).then((info) => {
+      this.firmwareInfo = info ?? DefaultFirmwareInfo;
+      return this.firmwareInfo;
+    });
+    return this.firmwareFetch;
+  }
+
+  /**
+   * Read factory info (serial number, body color, board revision) from the controller.
+   * Requires firmware info to be fetched first for feature gating.
+   * Idempotent across the lifetime of a single connection.
+   */
+  public fetchFactoryInfo(): Promise<FactoryInfo> {
+    if (this.factoryInfo !== DefaultFactoryInfo) return Promise.resolve(this.factoryInfo);
+    if (this.factoryFetch) return this.factoryFetch;
+    if (this.firmwareInfo === DefaultFirmwareInfo) return Promise.resolve(DefaultFactoryInfo);
+    const fwInfo = this.firmwareInfo;
+    this.factoryFetch = readFactoryInfo(
+      this.provider,
+      fwInfo.hardwareInfo,
+      fwInfo.mainFirmwareVersionRaw,
+    ).then((info) => {
+      this.factoryInfo = info ?? DefaultFactoryInfo;
+      return this.factoryInfo;
+    });
+    return this.factoryFetch;
+  }
+
   /** Condense all pending commands into one HID feature report */
   private static buildFeatureReport(
     events: CommandEvent[],