feat: v1.0.0 收尾 — 五芯片 DTR/RTS、类型声明、示例、CI

- CP210x / FTDI / PL2303 补齐 setSignals()（编码与各自初始化序列一致） - 新增 index.d.ts（TypeScript 类型声明）、examples/minimal.html（最小接入示例） - 新增 .gitea/workflows/ci.yml（push 时跑离线单测）、.gitattributes（强制 LF）、CHANGELOG.md - package.json 补 repository / homepage / bugs / types / engines - 单测 16 项全部通过：node test/driver.test.mjs
2026-09-23 00:41:29 +08:00
parent f02c0b06b8
commit 6c5e647c8a
9 changed files with 271 additions and 10 deletions
@@ -0,0 +1,116 @@
+/**
+ * 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[]>;
+  }
+}