esp-controller
Version:
Typescript package for connecting and flashing images to your ESP device.
269 lines (256 loc) • 9.13 kB
TypeScript
/**
* Copyright 2025 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
interface Partition {
binary: Uint8Array;
readonly offset: number;
readonly filename: string;
}
/**
* Copyright 2025 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
declare class ESPImage {
partitions: Array<Partition>;
addBootloader(fileName: string): void;
addPartitionTable(fileName: string): void;
addApp(fileName: string): void;
addPartition(partition: Partition): void;
}
/**
* Copyright 2025 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Known chip families and their magic values.
*/
declare enum ChipFamily {
ESP32 = 15736195,
ESP32S2 = 1990,
ESP32S3 = 9,
ESP32C3 = 1763790959,
ESP32C6 = 752910447,
ESP32H2 = 3389177967,
ESP8266 = 4293968129,
UNKNOWN = 4294967295
}
/**
* Interface defining the properties of a serial connection.
*/
interface SerialConnection {
/** The underlying SerialPort object. Undefined if no port is selected. */
port: SerialPort | undefined;
/** Indicates if the serial port is currently open and connected. */
connected: boolean;
/** Indicates if the connection has been synchronized with the device. */
synced: boolean;
/** The detected chip family. Null if not yet detected. */
chip: ChipFamily | null;
/** The readable stream for receiving data from the serial port. Null if not connected. */
readable: ReadableStream<Uint8Array> | null;
/** The writable stream for sending data to the serial port. Null if not connected. */
writable: WritableStream<Uint8Array> | null;
/** An AbortController to signal termination of stream operations. Undefined if not connected. */
abortStreamController: AbortController | undefined;
/** A readable stream that contains the slipstream decoded responses from the esp. */
commandResponseStream: ReadableStream<Uint8Array> | undefined;
}
declare class SerialController extends EventTarget {
connection: SerialConnection;
constructor();
private createSerialConnection;
requestPort(): Promise<void>;
createLogStreamReader(): () => AsyncGenerator<string | undefined, void, unknown>;
openPort(options?: SerialOptions): Promise<void>;
disconnect(): Promise<void>;
sendResetPulse(): Promise<void>;
writeToConnection(data: Uint8Array): Promise<void>;
sync(): Promise<boolean>;
detectChip(): Promise<ChipFamily>;
loadToRam(binary: Uint8Array, offset: number, execute?: boolean, entryPoint?: number): Promise<void>;
/**
* Fetches the stub for the given chip family from the local file system.
* @param chip The chip family to fetch the stub for.
* @returns A promise that resolves to the Stub object.
*/
private getStubForChip;
private uploadStub;
private awaitOhaiResponse;
private readResponse;
flashPartition(partition: Partition): Promise<void>;
/**
* Main method to flash a complete image.
* @param image The ESPImage to flash.
*/
flashImage(image: ESPImage): Promise<void>;
}
/**
* Copyright 2025 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
declare class BinFilePartition implements Partition {
readonly offset: number;
readonly filename: string;
binary: Uint8Array;
constructor(offset: number, filename: string);
load(): Promise<boolean>;
}
/**
* Copyright 2025 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
declare class NVSPartition implements Partition {
readonly offset: number;
readonly filename: string;
size: number;
private namespaces;
private pages;
constructor(offset: number, filename: string, size?: number);
private newPage;
private getLastPage;
private getNameSpaceIndex;
get binary(): Uint8Array;
writeEntry(namespace: string, key: string, data: string | number): void;
private write;
}
/**
* Copyright 2025 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
declare enum PartitionType {
APP = 0,
DATA = 1
}
declare enum AppPartitionSubType {
FACTORY = 0,
OTA_0 = 16,
OTA_1 = 17,
OTA_2 = 18,
OTA_3 = 19,
OTA_4 = 20,
OTA_5 = 21,
OTA_6 = 22,
OTA_7 = 23,
OTA_8 = 24,
OTA_9 = 25,
OTA_10 = 26,
OTA_11 = 27,
OTA_12 = 28,
OTA_13 = 29,
OTA_14 = 30,
OTA_15 = 31,
TEST = 32
}
declare enum DataPartitionSubType {
OTA = 0,
PHY = 1,
NVS = 2,
NVS_KEYS = 4,
SPIFFS = 130
}
interface PartitionFlags {
encrypted: boolean;
readonly: boolean;
}
interface PartitionDefinition {
name: string;
type: PartitionType;
subType: AppPartitionSubType | DataPartitionSubType;
offset?: number;
size: number;
flags?: Partial<PartitionFlags>;
}
/**
* Copyright 2025 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
declare class PartitionTable implements Partition {
private entries;
readonly offset = 32768;
readonly filename = "partition-table.bin";
constructor(definitions: PartitionDefinition[]);
private processDefinitions;
get binary(): Uint8Array;
toBinary(enableMD5?: boolean): Uint8Array;
static singleFactoryAppNoOta(): PartitionTable;
static factoryAppTwoOtaDefinitions(): PartitionTable;
}
export { AppPartitionSubType, BinFilePartition, DataPartitionSubType, ESPImage, NVSPartition, type Partition, type PartitionDefinition, type PartitionFlags, PartitionTable, PartitionType, type SerialConnection, SerialController };