ch340-webusb/index.d.ts

/**
 * ch340-webusb 类型声明（UMD：<script> 全局 / ESM / CJS 均可）
 */
export = TamaCh340;
export as namespace TamaCh340;

declare const TamaCh340: TamaCh340.Api;

declare namespace TamaCh340 {
  interface OpenOptions {
    /** 波特率，默认 460800 */
    baudRate?: number;
    dataBits?: 8;
    stopBits?: 1;
    parity?: 'none';
    flowControl?: 'none';
    /** 单次 bulk 读的字节数，默认 = 端点 wMaxPacketSize（CH340 是 32） */
    readTransferSize?: number;
    /** 预排队读请求数，默认取驱动的 readQueueDepth（CH340 是 32） */
    readQueueDepth?: number;
  }

  interface Signals {
    dataTerminalReady?: boolean;
    requestToSend?: boolean;
  }

  interface Info {
    usbVendorId: number;
    usbProductId: number;
  }

  interface Endpoint {
    endpointNumber: number;
    direction: 'in' | 'out';
    type: string;
    packetSize: number;
  }

  interface Layout {
    claimedInterfaces: number[];
    controlInterface: number;
    input: Endpoint;
    output: Endpoint;
  }

  interface Diagnostics {
    transfers: number;
    bytes: number;
    transferSize: number;
  }

  /** 与 Web Serial 的 SerialPort 对齐，另加驱动相关扩展 */
  interface BrowserSerialPort {
    open(options?: OpenOptions): Promise<BrowserSerialPort>;
    close(): Promise<void>;
    getInfo(): Info;
    /** open() 之后才有值 */
    readonly readable: ReadableStream<Uint8Array> | null;
    readonly writable: WritableStream<Uint8Array> | null;
    /** 便捷读：timeoutMs 内无数据返回 null（会持有内部 reader） */
    read(timeoutMs?: number): Promise<Uint8Array | null>;
    /** 便捷写（会持有内部 writer） */
    write(data: Uint8Array | ArrayBuffer | number[]): Promise<void>;
    setSignals(signals: Signals): Promise<void>;
    forget(): Promise<void>;
    getDiagnostics(): Diagnostics;
    addEventListener(type: 'disconnect', fn: (ev: { type: string; target: BrowserSerialPort }) => void): void;
    removeEventListener(type: 'disconnect', fn: (ev: unknown) => void): void;
    readonly device: USBDevice;
    readonly chip: string;
    readonly opened: boolean;
    readonly layout?: Layout;
  }

  interface Driver {
    name: string;
    readQueueDepth?: number;
    filters: USBDeviceFilter[];
    supports(device: USBDevice): boolean;
    layout(configuration: USBConfiguration): Layout;
    initialize(ctx: unknown, options: OpenOptions & { baudRate: number }): Promise<void>;
    shutdown?(ctx: unknown): Promise<void>;
    setSignals?(ctx: unknown, signals: Signals): Promise<void>;
  }

  interface Api {
    version: string;
    /** 调试日志钩子 / 打开 console 输出 */
    onLog: ((...args: unknown[]) => void) | null;
    debug: boolean;
    drivers: Driver[];
    UsbSerialPort: new (device: USBDevice, driver: Driver, defaults?: OpenOptions) => BrowserSerialPort;

    hasWebUSB(): boolean;
    hasWebSerial(): boolean;
    isAndroid(): boolean;
    /** 全部驱动的 filters（去重） */
    supportedFilters(): USBDeviceFilter[];
    /** 只筛 CH340/CH341 */
    ch34xFilters(): USBDeviceFilter[];
    chipName(vendorId: number, productId: number): string;
    pickDriver(device: USBDevice): Driver | null;
    /** CH34x 波特率分频，与 Linux ch341.c 一致 */
    calcCh34xBaud(baudRate: number): { factor: number; divisor: number };
    calcFtdiBaud(baudRate: number): { value: number; fractionalIndex: number };

    /** 弹设备选择框 → 返回未打开的端口 */
    requestPort(options?: OpenOptions & { filters?: USBDeviceFilter[]; allDrivers?: boolean }): Promise<BrowserSerialPort>;
    /** 选择 + 打开 */
    connect(options?: OpenOptions & { allDrivers?: boolean }): Promise<BrowserSerialPort>;
    fromDevice(device: USBDevice, options?: OpenOptions): BrowserSerialPort;
    getAuthorizedDevices(options?: { allDrivers?: boolean }): Promise<USBDevice[]>;
    getAuthorizedPorts(options?: { allDrivers?: boolean }): Promise<BrowserSerialPort[]>;
  }
}