esp-web-tools
Version:
Web tools for ESP devices
226 lines (225 loc) • 9.1 kB
JavaScript
const DEFAULT_BUFFER_SIZE = 255;
/** Fill defaults and validate Web Serial options, like native Web Serial. */
export const toLineConfig = (options) => {
const { baudRate, dataBits = 8, stopBits = 1, parity = "none" } = options;
if (!Number.isInteger(baudRate) || baudRate <= 0) {
throw new RangeError(`invalid Baud Rate ${baudRate}`);
}
if (![5, 6, 7, 8].includes(dataBits)) {
throw new RangeError(`invalid dataBits ${dataBits}`);
}
if (stopBits !== 1 && stopBits !== 2) {
throw new RangeError(`invalid stopBits ${stopBits}`);
}
if (!["none", "even", "odd"].includes(parity)) {
throw new RangeError(`invalid parity ${parity}`);
}
return { baudRate, dataBits, stopBits, parity };
};
/**
* Web Serial `SerialPort` on top of a WebUSB device, for any registered
* driver. Implements the surface esptool-js, the Improv SDK and the console
* use. It is not structurally identical to the DOM `SerialPort` type.
*
* Behaviours that mirror native Web Serial (and that those consumers rely on):
* - `readable` hands out a fresh stream after the previous one was cancelled,
* and a read that was in flight at cancel time is delivered to the next
* stream so no bytes get lost.
* - Zero-length USB packets are skipped, never enqueued.
* - DTR and RTS are deasserted after `open()`.
*/
export class UsbSerialPort {
constructor(_device, _createDriver) {
this._device = _device;
this._createDriver = _createDriver;
this._readable = null;
this._writable = null;
this._signals = { dataTerminalReady: false, requestToSend: false };
this._break = false;
}
get _bufferSize() {
var _a;
var _b;
return (_b = (_a = this._options) === null || _a === void 0 ? void 0 : _a.bufferSize) !== null && _b !== void 0 ? _b : DEFAULT_BUFFER_SIZE;
}
get readable() {
if (this._readable || !this._device.opened || !this._endpoints) {
return this._readable;
}
const stream = new ReadableStream({
pull: async (controller) => {
var _a;
(_a = this._pendingRead) !== null && _a !== void 0 ? _a : (this._pendingRead = this._read(controller.desiredSize));
this._pendingRead.catch(() => undefined);
let chunk;
try {
chunk = await this._pendingRead;
}
catch (err) {
this._pendingRead = undefined;
if (this._readable === stream) {
this._readable = null;
}
controller.error(err);
return;
}
if (this._readable !== stream) {
// Cancelled while reading, keep the chunk for the next stream.
return;
}
this._pendingRead = undefined;
controller.enqueue(chunk);
},
cancel: () => {
if (this._readable === stream) {
this._readable = null;
}
},
}, new ByteLengthQueuingStrategy({ highWaterMark: this._bufferSize }));
this._readable = stream;
return stream;
}
get writable() {
if (this._writable || !this._device.opened || !this._endpoints) {
return this._writable;
}
const stream = new WritableStream({
write: async (chunk) => {
if (!chunk.byteLength) {
return;
}
try {
const result = await this._device.transferOut(this._endpoints.out.endpointNumber, chunk);
if (result.status !== "ok") {
throw new Error(`USB error: ${result.status}`);
}
}
catch (err) {
if (this._writable === stream) {
this._writable = null;
}
throw err;
}
},
}, new ByteLengthQueuingStrategy({ highWaterMark: this._bufferSize }));
this._writable = stream;
return stream;
}
/** Read one non-empty, driver-processed chunk from the IN endpoint. */
async _read(desiredSize) {
var _a;
const endpoint = this._endpoints.in;
const driver = this._driver;
const packetSize = endpoint.packetSize;
const length = Math.max(1, Math.ceil((desiredSize !== null && desiredSize !== void 0 ? desiredSize : packetSize) / packetSize)) *
packetSize;
for (;;) {
const result = await this._device.transferIn(endpoint.endpointNumber, length);
if (result.status !== "ok") {
throw new Error(`USB error: ${result.status}`);
}
if (!((_a = result.data) === null || _a === void 0 ? void 0 : _a.byteLength)) {
continue;
}
let chunk = new Uint8Array(result.data.buffer, result.data.byteOffset, result.data.byteLength);
if (driver.processRead) {
chunk = driver.processRead(chunk);
}
// Skip empty packets (nothing to deliver).
if (chunk.byteLength) {
return chunk;
}
}
}
async open(options) {
const config = toLineConfig(options);
this._options = options;
try {
await this._device.open();
if (this._device.configuration === null) {
await this._device.selectConfiguration(1);
}
const driver = this._createDriver(this._device);
this._driver = driver;
this._endpoints = await driver.open();
await driver.setLineConfig(config);
// Start with DTR and RTS low like native Web Serial. On ESP boards they
// drive IO0 and EN, so a stray DTR boots the ROM bootloader instead of
// the firmware.
this._signals = { dataTerminalReady: false, requestToSend: false };
this._break = false;
await driver.setSignals(false, false);
}
catch (err) {
this._driver = undefined;
this._endpoints = undefined;
if (this._device.opened) {
await this._device.close().catch(() => undefined);
}
throw new Error(`Error setting up device: ${err}`);
}
}
async close() {
var _a, _b, _c, _d, _e;
// Streams may be locked by a consumer, which makes cancel/abort reject.
await Promise.all([
(_a = this._readable) === null || _a === void 0 ? void 0 : _a.cancel().catch(() => undefined),
(_b = this._writable) === null || _b === void 0 ? void 0 : _b.abort().catch(() => undefined),
]);
this._readable = null;
this._writable = null;
this._pendingRead = undefined;
if (!this._device.opened) {
return;
}
// The device may already be gone, closing must still succeed.
try {
await ((_c = this._driver) === null || _c === void 0 ? void 0 : _c.setSignals(false, false));
await ((_e = (_d = this._driver) === null || _d === void 0 ? void 0 : _d.close) === null || _e === void 0 ? void 0 : _e.call(_d));
}
catch {
// ignore
}
this._driver = undefined;
this._endpoints = undefined;
await this._device.close();
}
forget() {
return this._device.forget();
}
getInfo() {
return {
usbVendorId: this._device.vendorId,
usbProductId: this._device.productId,
};
}
/** Change line settings (baud rate, ...) of an open port. */
async reconfigure(options) {
const merged = { ...this._options, ...options };
const config = toLineConfig(merged);
this._options = merged;
await this._requireDriver().setLineConfig(config);
}
async setSignals(signals) {
var _a, _b;
const driver = this._requireDriver();
if (signals.dataTerminalReady !== undefined ||
signals.requestToSend !== undefined) {
this._signals = {
dataTerminalReady: (_a = signals.dataTerminalReady) !== null && _a !== void 0 ? _a : this._signals.dataTerminalReady,
requestToSend: (_b = signals.requestToSend) !== null && _b !== void 0 ? _b : this._signals.requestToSend,
};
await driver.setSignals(this._signals.dataTerminalReady, this._signals.requestToSend);
}
if (signals.break !== undefined && driver.setBreak) {
this._break = signals.break;
await driver.setBreak(this._break);
}
}
_requireDriver() {
if (!this._driver) {
throw new DOMException("The port is not open.", "InvalidStateError");
}
return this._driver;
}
}