ota-hub-reactjs 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [OTA Hub and the Hard Stuff team]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/base/device-whisperer.d.ts

@@ -0,0 +1,42 @@
+export type LogMessage = string | number | boolean | Record<string, any> | any[];
+export type LogLine = {
+    level: number;
+    message: LogMessage;
+    timestamp?: string | Date;
+};
+type PropCreatorProps<T> = (uuid: string) => Partial<T> | undefined;
+export interface AddConnectionProps<T> {
+    uuid?: string;
+    propCreator?: PropCreatorProps<T>;
+}
+export type DeviceConnectionState = {
+    uuid: string;
+    deviceMac?: string;
+    name: string;
+    send: (data: string | Uint8Array) => void | Promise<void>;
+    onReceive?: (data: string | Uint8Array) => boolean;
+    onConnect?: () => void | Promise<void>;
+    onDisconnect?: () => void | Promise<void>;
+    autoConnect: boolean;
+    isConnected: boolean;
+    isConnecting: boolean;
+    logs: LogLine[];
+    readBufferLeftover: string;
+};
+export declare function createDefaultInitialDeviceState<T extends DeviceConnectionState>(uuid: string, props?: any): T;
+export type DeviceWhispererProps<T extends DeviceConnectionState> = {
+    createInitialConnectionState?: (uuid: string) => T;
+};
+export declare function MultiDeviceWhisperer<T extends DeviceConnectionState>({ createInitialConnectionState, }?: DeviceWhispererProps<T>): {
+    connections: T[];
+    connectionsRef: import("react").RefObject<T[]>;
+    addConnection: ({ uuid, propCreator }: AddConnectionProps<T>) => Promise<string>;
+    removeConnection: (uuid: string) => void;
+    connect: (_uuid: string) => void;
+    disconnect: (_uuid: string) => void;
+    updateConnection: (uuid: string, updater: (c: T) => T) => void;
+    reconnectAll: () => void;
+    updateConnectionName: (uuid: string, name: string) => void;
+    appendLog: (uuid: string, log: LogLine) => void;
+};
+export {};

package/dist/base/device-whisperer.js

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { useEffect, useRef, useState } from "react";
+import { uniqueNamesGenerator, animals } from "unique-names-generator";
+;
+// Initial, generic state for the generic device
+export function createDefaultInitialDeviceState(uuid, props) {
+    return {
+        uuid,
+        autoConnect: true,
+        isConnected: false,
+        isConnecting: false,
+        logs: [],
+        readBufferLeftover: "",
+        ...props
+    };
+}
+/* One Device Whisperer is used for all like-devices, such as all Serial with Protobuf.
+   Any e.g. Serial without Protobuf, or LoRaWAN etc. devices would be handled via a separate device whisperer
+*/
+export function MultiDeviceWhisperer({ createInitialConnectionState = createDefaultInitialDeviceState, } = {}) {
+    const [connections, setConnections] = useState([]);
+    const connectionsRef = useRef(connections);
+    const updateConnection = (uuid, updater) => {
+        setConnections(prev => {
+            const updated = prev.map((c) => c.uuid === uuid ? updater(c) : c);
+            connectionsRef.current = updated;
+            return updated;
+        });
+    };
+    const updateConnectionName = (uuid, name) => {
+        setConnections((prev) => prev.map((c) => (c.uuid === uuid ? { ...c, name } : c)));
+    };
+    const appendLog = (uuid, log) => {
+        if (!log.timestamp) {
+            log.timestamp = new Date();
+        }
+        updateConnection(uuid, (c) => ({
+            ...c,
+            logs: [...c.logs.slice(-199), log],
+        }));
+    };
+    const addConnection = async ({ uuid, propCreator }) => {
+        uuid = uuid ?? uniqueNamesGenerator({ dictionaries: [animals] });
+        const props = propCreator?.(uuid);
+        const newConnection = {
+            ...createInitialConnectionState(uuid),
+            ...props
+        };
+        connectionsRef.current = [...connectionsRef.current, newConnection];
+        setConnections(prev => [...prev, newConnection]);
+        const anyUpdatedConnection = connectionsRef.current.find(c => c.uuid === uuid);
+        if (!anyUpdatedConnection) {
+            return "";
+        }
+        return uuid;
+    };
+    const removeConnection = (uuid) => {
+        setConnections((prev) => prev.filter((c) => c.uuid !== uuid));
+    };
+    useEffect(() => {
+        connectionsRef.current = connections;
+    }, [connections]);
+    return {
+        connections,
+        connectionsRef,
+        addConnection,
+        removeConnection,
+        connect: (_uuid) => { },
+        disconnect: (_uuid) => { },
+        updateConnection,
+        reconnectAll: () => { },
+        updateConnectionName,
+        appendLog
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "@/base/device-whisperer.js";
+export * from "@/message_layers/protobuf-wrapper.js";
+export * from "@/transport_layers/serial-device-whisperer.js";
+export * from "@/transport_layers/websocket-device-whisperer.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+// Re-export core types/classes
+export * from "@/base/device-whisperer.js";
+// Message layer exports
+export * from "@/message_layers/protobuf-wrapper.js";
+// Transport layers
+export * from "@/transport_layers/serial-device-whisperer.js";
+export * from "@/transport_layers/websocket-device-whisperer.js";

package/dist/message_layers/protobuf-wrapper.d.ts

@@ -0,0 +1,31 @@
+import { AddConnectionProps, DeviceConnectionState, MultiDeviceWhisperer } from "@/base/device-whisperer.js";
+export type TopicHandlerContext<AppLayer extends DeviceConnectionState> = {
+    base: ReturnType<typeof MultiDeviceWhisperer<AppLayer>>;
+    uuid: string;
+};
+export type TopicHandlerMap<AppLayer extends DeviceConnectionState, Topic extends string | number, Message = any> = {
+    [K in Topic]?: (message: Message, context: TopicHandlerContext<AppLayer>) => void;
+};
+export type ProtobufDeviceWhispererProps<AppLayer extends DeviceConnectionState, Topic extends string | number, MessageRX = any, MessageTX = any> = {
+    transportLayer: ReturnType<typeof MultiDeviceWhisperer<AppLayer>>;
+    encodeRX: (message: MessageTX) => Uint8Array;
+    decodeTX: (bytes: Uint8Array) => MessageRX;
+    messageTypeField: keyof MessageRX;
+    rxTopicHandlerMap: TopicHandlerMap<AppLayer, Topic, MessageRX>;
+    HEADER?: Uint8Array;
+    expectLength?: boolean;
+};
+export declare function ProtobufMultiDeviceWhisperer<AppLayer extends DeviceConnectionState, Topic extends string | number, MessageRX = any, MessageTX = any>({ transportLayer, encodeRX, decodeTX, messageTypeField, rxTopicHandlerMap, HEADER, }: ProtobufDeviceWhispererProps<AppLayer, Topic, MessageRX, MessageTX>): {
+    addConnection: ({ uuid, propCreator }: AddConnectionProps<AppLayer>) => Promise<string>;
+    sendProtobuf: (uuid: string, message: MessageTX) => void;
+    protoBufOnReceiveHandler: (uuid: string, data: string | Uint8Array) => void;
+    connections: AppLayer[];
+    connectionsRef: import("react").RefObject<AppLayer[]>;
+    removeConnection: (uuid: string) => void;
+    connect: (_uuid: string) => void;
+    disconnect: (_uuid: string) => void;
+    updateConnection: (uuid: string, updater: (c: AppLayer) => AppLayer) => void;
+    reconnectAll: () => void;
+    updateConnectionName: (uuid: string, name: string) => void;
+    appendLog: (uuid: string, log: import("@/base/device-whisperer.js").LogLine) => void;
+};

package/dist/message_layers/protobuf-wrapper.js

@@ -0,0 +1,142 @@
+export function ProtobufMultiDeviceWhisperer({ transportLayer, encodeRX, decodeTX, messageTypeField, rxTopicHandlerMap, HEADER = new Uint8Array([]), }) {
+    // --- Utils ---
+    const concatUint8Arrays = (a, b) => {
+        const result = new Uint8Array(a.length + b.length);
+        result.set(a);
+        result.set(b, a.length);
+        return result;
+    };
+    const wrapLengthPrefixed = (payload) => {
+        const length = payload.length;
+        const header = new Uint8Array([
+            (length >> 8) & 0xff, // Most significant byte first
+            length & 0xff // Least significant byte second
+        ]);
+        return concatUint8Arrays(header, payload);
+    };
+    const tryDecodeLengthPrefixed = (buffer) => {
+        if (HEADER.length) {
+            const findHeader = (buf) => {
+                for (let i = 0; i < buf.length - 1; i++) {
+                    if (buf[i] === HEADER[0] && buf[i + 1] === HEADER[1])
+                        return i;
+                }
+                return -1;
+            };
+            const headerIndex = findHeader(buffer);
+            if (headerIndex === -1)
+                return [null, buffer];
+            buffer = buffer.slice(headerIndex);
+        }
+        const st_msg = HEADER.length + 2;
+        if (buffer.length < st_msg)
+            return [null, buffer];
+        const length = (buffer[HEADER.length] << 8) | buffer[HEADER.length + 1];
+        if (buffer.length < st_msg + length)
+            return [null, buffer];
+        const messageBytes = buffer.slice(st_msg, st_msg + length);
+        const leftover = buffer.slice(st_msg + length);
+        try {
+            const decoded = decodeTX(messageBytes);
+            return [decoded, leftover];
+        }
+        catch {
+            return [null, buffer.slice(1)];
+        }
+    };
+    // --- New outbound API ---
+    const sendProtobuf = (uuid, message) => {
+        const encoded = encodeRX(message);
+        const wrapped = wrapLengthPrefixed(encoded);
+        const conn = transportLayer.connectionsRef.current.find(c => c.uuid === uuid);
+        console.log("Sending Protobuf:", message, "bytes: ", [...wrapped]);
+        conn?.send?.(wrapped);
+    };
+    // --- Inbound buffering ---
+    const buffers = {};
+    const protoBufOnReceiveHandler = (uuid, data) => {
+        const bytes = typeof data === "string"
+            ? new TextEncoder().encode(data)
+            : data;
+        buffers[uuid] = concatUint8Arrays(buffers[uuid] || new Uint8Array(), bytes);
+        let buffer = buffers[uuid];
+        while (buffer.length > 0) {
+            const [msg, remaining] = tryDecodeLengthPrefixed(buffer);
+            if (msg) {
+                buffers[uuid] = remaining;
+                const topic = msg[messageTypeField];
+                const handler = rxTopicHandlerMap[topic];
+                if (handler) {
+                    try {
+                        handler(msg, { base: transportLayer, uuid });
+                    }
+                    catch (err) {
+                        transportLayer.appendLog(uuid, {
+                            level: 0,
+                            message: `[!] Error in handler for topic "${topic}": ${err}`
+                        });
+                    }
+                }
+                else {
+                    transportLayer.appendLog(uuid, {
+                        level: 1,
+                        message: `[!] Unknown Protobuf topic: "${topic}"`
+                    });
+                }
+                buffer = buffers[uuid];
+                continue;
+            }
+            // If not protobuf, see if we can log a line of text
+            const newlineIdx = buffer.indexOf(10); // '\n'
+            const headerIdx = buffer.findIndex((_, i) => HEADER.every((h, idx) => buffer[i] + idx === h));
+            if (newlineIdx !== -1 && (headerIdx === -1 || newlineIdx < headerIdx)) {
+                const line = buffer.slice(0, newlineIdx);
+                buffer = buffer.slice(newlineIdx + 1);
+                buffers[uuid] = buffer;
+                const text = new TextDecoder().decode(line).trim();
+                if (text) {
+                    transportLayer.appendLog(uuid, {
+                        level: 2,
+                        message: text
+                    });
+                }
+                continue;
+            }
+            if (headerIdx > 0) {
+                const garbage = buffer.slice(0, headerIdx);
+                buffer = buffer.slice(headerIdx);
+                buffers[uuid] = buffer;
+                const preview = Array.from(garbage)
+                    .slice(0, 16)
+                    .map(b => b.toString(16).padStart(2, '0'))
+                    .join(' ');
+                transportLayer.appendLog(uuid, {
+                    level: 1,
+                    message: `[!] Skipped invalid bytes before Protobuf header: ${preview}... (${garbage.length} bytes)`
+                });
+                continue;
+            }
+            break;
+        }
+        buffers[uuid] = buffer;
+    };
+    // --- Override addConnection to wrap onReceive ---
+    const addConnection = async ({ uuid, propCreator }) => {
+        return await transportLayer.addConnection({
+            uuid,
+            propCreator: (id) => {
+                const props = propCreator?.(id);
+                return {
+                    onReceive: (data) => protoBufOnReceiveHandler(id, data),
+                    ...props
+                };
+            }
+        });
+    };
+    return {
+        ...transportLayer,
+        addConnection,
+        sendProtobuf,
+        protoBufOnReceiveHandler
+    };
+}

package/dist/transport_layers/serial-device-whisperer.d.ts

@@ -0,0 +1,31 @@
+import { FlashOptions, Transport } from "esptool-js";
+import { DeviceConnectionState, AddConnectionProps } from "@/base/device-whisperer.js";
+export type SerialConnectionState = DeviceConnectionState & {
+    port?: SerialPort;
+    baudrate?: number;
+    transport?: Transport;
+    isFlashing: boolean;
+    flashProgress: number;
+    flashError: string;
+};
+export type FlashFirmwareProps = {
+    uuid: string;
+    firmwareBlob?: Blob;
+    fileArray?: FlashOptions["fileArray"];
+};
+export declare function SerialMultiDeviceWhisperer<AppOrMessageLayer extends SerialConnectionState>({ ...props }?: {}): {
+    addConnection: ({ uuid, propCreator }: AddConnectionProps<AppOrMessageLayer>) => Promise<string>;
+    removeConnection: (uuid: string) => Promise<void>;
+    connect: (uuid: string, baudrate?: number, restart_on_connect?: boolean) => Promise<void>;
+    disconnect: (uuid: string, timeout?: number) => Promise<void>;
+    handleFlashFirmware: (uuid: string, assetsToFlash: {
+        blob: Blob;
+        address: number;
+    }[]) => Promise<void>;
+    reconnectAll: (...connectionProps: any) => Promise<void>;
+    connections: AppOrMessageLayer[];
+    connectionsRef: import("react").RefObject<AppOrMessageLayer[]>;
+    updateConnection: (uuid: string, updater: (c: AppOrMessageLayer) => AppOrMessageLayer) => void;
+    updateConnectionName: (uuid: string, name: string) => void;
+    appendLog: (uuid: string, log: import("@/base/device-whisperer.js").LogLine) => void;
+};

package/dist/transport_layers/serial-device-whisperer.js

@@ -0,0 +1,290 @@
+import { ESPLoader, Transport } from "esptool-js";
+import { MultiDeviceWhisperer } from "@/base/device-whisperer.js";
+export function SerialMultiDeviceWhisperer({ ...props } = {}) {
+    const base = MultiDeviceWhisperer(props);
+    const defaultOnReceive = (uuid, data) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn)
+            return;
+        const decoder = new TextDecoder();
+        let bytes;
+        if (typeof data === "string") {
+            bytes = new TextEncoder().encode(data);
+        }
+        else if (data instanceof ArrayBuffer) {
+            bytes = new Uint8Array(data);
+        }
+        else {
+            bytes = data;
+        }
+        const asText = decoder.decode(bytes);
+        const combined = conn.readBufferLeftover + asText;
+        const lines = combined.split("\r\n");
+        base.updateConnection(uuid, (c) => ({
+            ...c,
+            readBufferLeftover: lines.pop() || ""
+        }));
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed) {
+                base.appendLog(uuid, {
+                    level: 2,
+                    message: trimmed,
+                });
+            }
+        }
+    };
+    const defaultSend = async (uuid, data) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn)
+            return;
+        const asString = typeof data === "string"
+            ? data
+            : btoa(String.fromCharCode(...data));
+        base.appendLog(uuid, {
+            level: 3,
+            message: asString,
+        });
+        const bytes = typeof data === "string"
+            ? new TextEncoder().encode(data)
+            : data;
+        console.log("conn.transport?.write:", conn.transport?.write, bytes);
+        await conn.transport?.write(bytes);
+    };
+    const readLoop = async (uuid, transport) => {
+        try {
+            while (true) {
+                const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+                if (!transport?.rawRead || !conn) {
+                    console.log("Transport failed to load!", conn, conn?.transport, transport?.rawRead);
+                    break;
+                }
+                ;
+                const reader = transport?.rawRead();
+                const { value, done } = await reader.next();
+                if (done || !value)
+                    break;
+                conn.onReceive?.(value);
+            }
+        }
+        catch (e) {
+            base.appendLog(uuid, {
+                level: 0,
+                message: `[!] Read loop error: ${e}`
+            });
+            await disconnect(uuid);
+        }
+        finally {
+            base.updateConnection(uuid, (c) => ({
+                ...c,
+                transport: null,
+                isConnected: false,
+                isConnecting: false,
+                autoConnect: false,
+            }));
+            base.appendLog(uuid, {
+                level: 0,
+                message: "[!] Serial disconnected"
+            });
+        }
+    };
+    const restartDevice = async (uuid, default_transport) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const transport = default_transport ?? conn?.transport;
+        if (transport) {
+            await transport.setRTS(false);
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            await transport.setRTS(true);
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        else {
+            console.log("No transport yet");
+        }
+    };
+    const connect = async (uuid, baudrate, restart_on_connect = true) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn?.port)
+            return;
+        if (!conn?.transport) {
+            await disconnect(uuid);
+        }
+        ;
+        base.updateConnection(uuid, (c) => ({ ...c, isConnecting: true }));
+        const use_baudrate = baudrate ?? conn.baudrate ?? 115200;
+        const transport = new Transport(conn.port, false, false);
+        try {
+            await transport.connect(use_baudrate);
+            if (restart_on_connect) {
+                await restartDevice(uuid, transport);
+            }
+            ;
+            base.updateConnection(uuid, (c) => ({
+                ...c,
+                transport,
+                baudrate: use_baudrate,
+                isConnected: true,
+                isConnecting: false,
+            }));
+            base.appendLog(uuid, {
+                level: 2,
+                message: "[✓] Serial connected"
+            });
+            await conn.onConnect?.();
+            await readLoop(uuid, transport);
+        }
+        catch (err) {
+            base.updateConnection(uuid, (c) => ({
+                ...c,
+                isConnected: false,
+                isConnecting: false
+            }));
+            base.appendLog(uuid, {
+                level: 0,
+                message: `[x] Serial connection error: ${err?.message || "Unknown error"}`
+            });
+            await disconnect(uuid);
+        }
+    };
+    const disconnect = async (uuid, timeout = 2000) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (conn?.transport) {
+            try {
+                // Attempt disconnect, but don’t hang if the port is crashed
+                await Promise.race([
+                    conn.transport.disconnect(),
+                    new Promise((resolve) => setTimeout(resolve, timeout)),
+                ]);
+            }
+            catch (e) {
+                console.warn(`[${uuid}] Serial Disconnect error:`, e);
+            }
+        }
+        // Always clear the transport and reset connection state
+        base.updateConnection(uuid, (c) => ({
+            ...c,
+            transport: null,
+            isConnected: false,
+            isConnecting: false,
+            autoConnect: false,
+        }));
+        await conn?.onDisconnect?.();
+    };
+    const addConnection = async ({ uuid, propCreator }) => {
+        const port = await navigator.serial.requestPort({
+            filters: [{ usbVendorId: 0x303a }]
+        });
+        return await base.addConnection({
+            uuid,
+            propCreator: (id) => {
+                const props = propCreator?.(id);
+                return {
+                    send: props?.send || ((d) => defaultSend(id, d)),
+                    onReceive: props?.onReceive || ((d) => defaultOnReceive(id, d)),
+                    port,
+                    ...props
+                };
+            }
+        });
+    };
+    const removeConnection = async (uuid) => {
+        try {
+            await disconnect(uuid);
+        }
+        catch (e) { }
+        ;
+        base.removeConnection(uuid);
+    };
+    // This function now handles an entire device flashing session
+    const handleFlashFirmware = async (uuid, assetsToFlash) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn || !conn.port || assetsToFlash.length === 0)
+            return;
+        await disconnect(uuid);
+        base.updateConnection(uuid, (c) => ({ ...c, isFlashing: true, flashProgress: 0, flashError: undefined }));
+        try {
+            // --- Connect ONCE ---
+            const transport = new Transport(conn.port, true);
+            const esploader = new ESPLoader({
+                transport,
+                baudrate: 921600,
+                enableTracing: false
+            });
+            try {
+                await esploader.main();
+            }
+            catch (e) {
+                console.log("failed to esploader.main()", e);
+                return;
+            }
+            ;
+            // --- Prepare an ARRAY of files for the library ---
+            const fileArray = await Promise.all(assetsToFlash.map(async ({ blob, address }) => {
+                const arrayBuffer = await blob.arrayBuffer();
+                const binaryString = Array.from(new Uint8Array(arrayBuffer))
+                    .map((b) => String.fromCharCode(b))
+                    .join("");
+                return { data: binaryString, address };
+            }));
+            const flashOptions = {
+                fileArray, // Pass the whole array here
+                flashSize: "keep",
+                flashMode: "qio",
+                flashFreq: "80m",
+                eraseAll: fileArray.length > 1, // Writing more than 1 thing, so likely writing partitions.
+                compress: true,
+                reportProgress: (fileIndex, written, total) => {
+                    // You can enhance progress reporting to show which file is being flashed
+                    const progress = (written / total) * 100;
+                    console.log(`Flashing file ${fileIndex + 1}/${fileArray.length}: ${progress.toFixed(1)}%`);
+                    base.updateConnection(uuid, (c) => ({ ...c, flashProgress: progress }));
+                },
+            };
+            // --- Call writeFlash ONCE with all files ---
+            try {
+                base.updateConnection(uuid, (c) => ({ ...c, flashProgress: -1 }));
+                await esploader.writeFlash(flashOptions);
+            }
+            catch (e) {
+                console.log("failed to esploader.writeFlash", e);
+            }
+            ;
+            // --- Disconnect ---
+            await esploader.after();
+            try {
+                await transport.disconnect();
+            }
+            catch (e) {
+                console.log("failed to transport.disconnect", e);
+                await conn.port?.readable?.cancel();
+                await conn.port?.writable?.close();
+                await conn.port?.close();
+            }
+            base.updateConnection(uuid, (c) => ({ ...c, isFlashing: false, flashProgress: 100 }));
+        }
+        catch (e) {
+            console.error(`[${uuid}] Flashing failed:`, e);
+            base.updateConnection(uuid, (c) => ({
+                ...c,
+                isFlashing: false,
+                flashError: e?.message ?? "Unknown error",
+            }));
+        }
+    };
+    const reconnectAll = async (...connectionProps) => {
+        const connections = [...base.connectionsRef.current]; // snapshot first
+        await Promise.all(connections.map(async (c) => {
+            await disconnect(c.uuid);
+            await new Promise((res) => setTimeout(res, 250));
+            return connect(c.uuid, ...connectionProps);
+        }));
+    };
+    return {
+        ...base,
+        addConnection,
+        removeConnection,
+        connect,
+        disconnect,
+        handleFlashFirmware,
+        reconnectAll
+    };
+}

package/dist/transport_layers/websocket-device-whisperer.d.ts

@@ -0,0 +1,24 @@
+import { DeviceConnectionState, AddConnectionProps } from "@/base/device-whisperer.js";
+export type WebsocketConnectionState = DeviceConnectionState & {
+    ws?: WebSocket;
+};
+export type DeviceObjectResponse = {
+    id: string;
+    deviceState: string;
+    uiState: string;
+    deviceConnectedTime: Date | null;
+    deviceLastCommTime: Date | null;
+};
+export declare function WebsocketMultiDeviceWhisperer<AppOrMessageLayer extends WebsocketConnectionState>(server_url: string, server_port: number, { ...props }?: {}): {
+    addConnection: ({ uuid, propCreator }: AddConnectionProps<AppOrMessageLayer>) => Promise<string>;
+    removeConnection: (uuid: string) => Promise<void>;
+    connect: (uuid: string, attempt?: number) => Promise<void>;
+    disconnect: (uuid: string) => Promise<void>;
+    checkForNewDevices: () => Promise<DeviceObjectResponse[]>;
+    reconnectAll: () => Promise<void>;
+    connections: AppOrMessageLayer[];
+    connectionsRef: import("react").RefObject<AppOrMessageLayer[]>;
+    updateConnection: (uuid: string, updater: (c: AppOrMessageLayer) => AppOrMessageLayer) => void;
+    updateConnectionName: (uuid: string, name: string) => void;
+    appendLog: (uuid: string, log: import("@/base/device-whisperer.js").LogLine) => void;
+};

package/dist/transport_layers/websocket-device-whisperer.js

@@ -0,0 +1,193 @@
+import { MultiDeviceWhisperer } from "@/base/device-whisperer.js";
+export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...props } = {}) {
+    const defaultOnReceive = (uuid, data) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn)
+            return;
+        const decoder = new TextDecoder();
+        let bytes;
+        if (typeof data === "string") {
+            bytes = new TextEncoder().encode(data);
+        }
+        else if (data instanceof ArrayBuffer) {
+            bytes = new Uint8Array(data);
+        }
+        else {
+            bytes = data;
+        }
+        const asText = decoder.decode(bytes);
+        const combined = conn.readBufferLeftover + asText;
+        const lines = combined.split("\n");
+        base.updateConnection(uuid, (c) => ({
+            ...c,
+            readBufferLeftover: lines.pop() || ""
+        }));
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed) {
+                base.appendLog(uuid, {
+                    level: 2,
+                    message: trimmed,
+                });
+            }
+        }
+    };
+    const defaultSend = async (uuid, data) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn || !conn.ws)
+            return;
+        const asString = typeof data === "string"
+            ? data
+            : btoa(String.fromCharCode(...data));
+        base.appendLog(uuid, {
+            level: 3,
+            message: asString,
+        });
+        conn.ws.send(data);
+    };
+    const connect = async (uuid, attempt = 0) => {
+        const MAX_RETRIES = 5;
+        const RETRY_DELAY_MS = 2000; // 2 seconds
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn)
+            return;
+        if (conn.ws && conn.ws.readyState === WebSocket.OPEN) {
+            console.log(`[client] Closing existing WS before reconnect for ${uuid}`);
+            conn.ws.close();
+        }
+        base.updateConnection(uuid, (c) => ({ ...c, isConnecting: true, autoConnect: true }));
+        try {
+            const pre = server_port !== 443 ? "ws" : "wss";
+            const ws = new WebSocket(`${pre}://${server_url}:${server_port}/ui/${uuid}`);
+            ws.binaryType = "arraybuffer";
+            ws.onopen = () => {
+                base.updateConnection(uuid, (c) => ({
+                    ...c,
+                    ws,
+                    isConnected: true,
+                    isConnecting: false,
+                    lastAttempt: attempt
+                }));
+                base.appendLog(uuid, {
+                    level: 2,
+                    message: "[✓] WebSocket connected"
+                });
+                conn?.onConnect?.();
+            };
+            ws.onmessage = (event) => {
+                let data;
+                if (typeof event.data === "string")
+                    data = event.data;
+                else if (event.data instanceof ArrayBuffer)
+                    data = new Uint8Array(event.data);
+                else
+                    data = event.data;
+                conn.onReceive?.(data);
+            };
+            ws.onerror = (err) => {
+                base.appendLog(uuid, {
+                    level: 0,
+                    message: `[x] WS error: ${err}`
+                });
+            };
+            ws.onclose = async () => {
+                base.updateConnection(uuid, (c) => ({
+                    ...c,
+                    isConnected: false,
+                    isConnecting: false,
+                    ws: undefined
+                }));
+                base.appendLog(uuid, { level: 0, message: "[!] WS disconnected" });
+                const updated_conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+                if (!updated_conn) {
+                    base.appendLog(uuid, { level: 0, message: "[!] Connection lost!" });
+                    return;
+                }
+                // Auto reconnect if enabled
+                if (updated_conn.autoConnect && attempt < MAX_RETRIES) {
+                    base.appendLog(uuid, { level: 2, message: `[~] Reconnecting in ${RETRY_DELAY_MS}ms... (attempt ${attempt + 1})` });
+                    setTimeout(() => connect(uuid, attempt + 1), RETRY_DELAY_MS);
+                }
+            };
+        }
+        catch (err) {
+            base.updateConnection(uuid, (c) => ({
+                ...c,
+                isConnected: false,
+                isConnecting: false,
+                logs: [
+                    ...c.logs,
+                    { level: 0, message: `[x] WS connection error: ${err?.message || "Unknown error"}` }
+                ]
+            }));
+            await disconnect(uuid);
+        }
+    };
+    const disconnect = async (uuid) => {
+        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        if (!conn?.ws)
+            return;
+        base.updateConnection(uuid, (c) => ({
+            ...c,
+            isConnected: false,
+            isConnecting: false,
+            autoConnect: false,
+            ws: undefined,
+            readBufferLeftover: ""
+        }));
+        conn.ws.close();
+        await conn?.onDisconnect?.();
+    };
+    const base = MultiDeviceWhisperer(props);
+    const addConnection = async ({ uuid, propCreator }) => {
+        return await base.addConnection({
+            uuid,
+            propCreator: (id) => {
+                const props = propCreator?.(id);
+                return {
+                    send: props?.send || ((d) => defaultSend(id, d)),
+                    onReceive: props?.onReceive || ((d) => defaultOnReceive(id, d)),
+                    ...props
+                };
+            }
+        });
+    };
+    const removeConnection = async (uuid) => {
+        await disconnect(uuid);
+        base.removeConnection(uuid);
+    };
+    const checkForNewDevices = async () => {
+        try {
+            const url = server_port !== 443
+                ? `http://${server_url}:${server_port}`
+                : `https://${server_url}`;
+            const response = await fetch(`${url}/devices`);
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            console.error("Failed to fetch devices:", error);
+            return [];
+        }
+    };
+    const reconnectAll = async () => {
+        for (const c of base.connectionsRef.current) {
+            await disconnect(c.uuid);
+            await new Promise((res) => setTimeout(res, 250));
+        }
+        for (const c of base.connectionsRef.current) {
+            await connect(c.uuid);
+        }
+    };
+    return {
+        ...base,
+        addConnection,
+        removeConnection,
+        connect,
+        disconnect,
+        checkForNewDevices,
+        reconnectAll
+    };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ota-hub-reactjs",
+  "version": "0.0.1",
+  "description": "ReactJS tools for building web apps to flash MCU devices such as esp32, brought to you by OTA Hub.",
+  "main": "dist/index.js",
+  "type": "module",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hard-Stuff/OTA-Hub-reactjs.git"
+  },
+  "keywords": [
+    "esp32",
+    "ota",
+    "react",
+    "iot",
+    "firmware"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Hard-Stuff/OTA-Hub-reactjs/issues"
+  },
+  "homepage": "https://github.com/Hard-Stuff/OTA-Hub-reactjs#readme",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "esptool-js": "^0.5.5",
+    "mqtt": "^5.14.0",
+    "unique-names-generator": "^4.7.1",
+    "uuid": "^11.1.0"
+  },
+  "peerDependencies": {
+  "react": ">=18.0.0",
+  "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "ts-proto": "^2.7.5",
+    "typescript": "^5.3.0",
+    "@types/w3c-web-serial": "^1.0.8"
+
+  }
+}