ota-hub-reactjs 0.0.7 → 0.0.9

package/README.md

@@ -1,14 +1,15 @@
 # OTA Hub ReactJS
 
-**ReactJS tools for interacting with MCUs such as ESP32 over OTA.**  
+**ReactJS tools for interacting with Microprocessors and IoT devices (such as ESP32) over various transports.**
 
 `ota-hub-reactjs` provides a set of React-friendly utilities to:
 
-- Flash firmware to microcontrollers (ESP32 and similar)
-- Read from multiple MCUs over serial **in parallel**
-- Connect to MCUs via wireless transport stacks such as WebSockets for real-time streaming
-- Handle Protobuf and other message layer wrappers 
-
+-   Read from multiple MCUs **in parallel** over a range of transports, including:
+    -   Serial (USB)
+    -   MQTT (e.g. with AWS IoT Core)
+    -   Websockets
+-   Flash firmware to ESP32 directly in browser
+-   Handle Protobuf and other message layer wrappers
 
 ## Installation
 
@@ -18,7 +19,7 @@ npm install ota-hub-reactjs
 yarn add ota-hub-reactjs
 ```
 
-Peer dependencies:
+This is a react lib, so you will need the peer dependencies:
 
 ```bash
 npm install react react-dom
@@ -28,9 +29,9 @@ npm install react react-dom
 
 ## Transport layers
 
-- All transport layers are designed to support multiple connections (thus devices) in parallel
-- You can mix and match tranport layers within your applications
-- All ConnectionStates are extendible, e.g.
+-   All transport layers are designed to support multiple connections (thus devices) in parallel
+-   You can mix and match tranport layers within your applications as separate dedicated `Device Whisperers`
+-   All ConnectionStates are extendible, e.g.
     ```ts
     export type EnhancedSerialConnectionState = SerialConnectionState & {
         dataPoints: DataPoint[];
@@ -43,7 +44,8 @@ npm install react react-dom
     ```
 
 ### Serial Communication
-Read and write to multiple MCUs concurrently over serial connections.
+
+Read and write to multiple MCUs in parallel over multiple serial connections.
 
 ```tsx
 import { SerialMultiDeviceWhisperer, SerialConnectionState } from "ota-hub-reactjs";
@@ -58,45 +60,122 @@ serialDeviceWhisperer.addConnection(); // Web browser will prompt for which Seri
 }/>
 ```
 
+## MQTT AWS IoT Core Streaming
+
+Connect to MCUs that expose WebSocket interfaces for live data streaming.<br />
+_Currently this is for a server that allows multiple devices as clients to connect through, rather than one device as a server itself_
+
+```ts
+import { MQTTMultiDeviceWhisperer } from "ota-hub-reactjs";
+
+import { Sha256 } from "@aws-crypto/sha256-js";
+import { SignatureV4 } from "@aws-sdk/signature-v4";
+import { HttpRequest } from "@aws-sdk/protocol-http";
+
+// Get your AWS IoT Core Signed URL
+const createAwsIotWssUrl = async () => {
+    const endpoint = process.env.IOT_ENDPOINT!; // Your IoT Core Endpoint
+    const region = process.env.IOT_REGION!; // Your IoT Core Region
+
+    const signer = new SignatureV4({
+        service: "iotdevicegateway",
+        region,
+        credentials: {
+            accessKeyId: process.env.IOT_ACCESS_KEY_ID!,
+            secretAccessKey: process.env.IOT_SECRET_ACCESS_KEY!,
+        },
+        sha256: Sha256,
+    });
+
+    const request = new HttpRequest({
+        protocol: "wss:",
+        hostname: endpoint,
+        method: "GET",
+        path: "/mqtt",
+        headers: { host: endpoint },
+    });
+
+    const signed = await signer.presign(request, { expiresIn: 60 });
+    const qs = new URLSearchParams(signed.query as Record<string, string>).toString();
+
+    return {
+        url: `${signed.protocol}//${signed.hostname}${signed.path}?${qs}`,
+        clientId: `web-${Date.now()}`,
+    };
+};
+
+const { url, clientId } = await createAwsIotWssUrl(); // Best done on a backend
+
+const whisperer = MQTTMultiDeviceWhisperer<EnhancedMQTTConnectionState>({
+    serverUrl: url,
+    clientId: clientId,
+    serverPort: 443, // Mosquito etc. are often 8883. IoT Core is MQTT over WS, so 443.
+    subTopicFromUuid: (uuid) => `${uuid}/sub_topic`,
+    pubTopicFromUuid: (uuid) => `${uuid}/pub_topic`,
+    uuidFromMessage: (topic, _p) => topic.split("/")[0],
+    autoConnect: false,
+    connectOn: true, // connect to MQTT boker on .. can also have this state managed, i.e. when a user clicks a button
+});
+
+// Then as normal:
+const uuid = "Thingname on AWS"
+await whisperer.addConnection({ uuid });
+const given_connection = await whisperer.getConnection(uuid)
+given_connection.send("hello there"); // or stringified JSON or bytes. Sends on default pubTopic (from UUID)
+```
+
 ## WebSocket Streaming
+
 Connect to MCUs that expose WebSocket interfaces for live data streaming.<br />
 _Currently this is for a server that allows multiple devices as clients to connect through, rather than one device as a server itself_
 
 ```tsx
 import { WebsocketMultiDeviceWhisperer } from "ota-hub-reactjs";
 
-const websocketDeviceWhisperer = new WebsocketMultiDeviceWhisperer<EnhancedWebsocketConnectionState>("ws://192.168.1.100:8080");
+const websocketDeviceWhisperer = new WebsocketMultiDeviceWhisperer<EnhancedWebsocketConnectionState>(
+    "ws://192.168.1.100:8080"
+);
 
 // then as Serial
 ```
 
 ## Flash Firmware
-Flash multiple MCUs with firmware images using esptool-js under the hood. - Currently only implemented in Serial, more to come!
+
+**Currently Firmware flashing is only available on Serial connections.** Flash multiple MCUs with firmware images using esptool-js under the hood.
 
 ```ts
 await Promise.all(
-    serialDeviceWhisperer.connections
-      .map(c => serialDeviceWhisperer.handleFlashFirmware({ uuid: c.uuid, firmwareBlob: blobToFlash! }))
+    serialDeviceWhisperer.connections.map((c) =>
+        serialDeviceWhisperer.handleFlashFirmware({ uuid: c.uuid, firmwareBlob: blobToFlash! })
+    )
 );
 ```
 
 # Message Layer Wrappers
-Supports Protobuf and other custom message layers for structured communication.
+
+Supports Protobuf and other custom message layers for structured communication. **Experimental feature, and those with familiarity with Protobuf might want to handle this themselves and call `.send` and `.onReceive` themselves.**
 
 ```ts
 import { ProtobufMultiDeviceWhisperer } from "ota-hub-reactjs";
 
-
-const protobufSerialDeviceWhisperer = ProtobufMultiDeviceWhisperer<EnhancedSerialConnectionState, TXType, TXFromESP, RXToESP>({
-  transportLayer: serialDeviceWhisperer,
-  encodeRX: (msg) => RXToESP.encode(msg).finish(),
-  decodeTX: (bytes) => TXFromESP.decode(bytes),
-  messageTypeField: "txType",
-  rxTopicHandlerMap: logHandlerMap
+const protobufSerialDeviceWhisperer = ProtobufMultiDeviceWhisperer<
+    EnhancedSerialConnectionState,
+    TXType,
+    TXFromESP,
+    RXToESP
+>({
+    transportLayer: serialDeviceWhisperer,
+    encodeRX: (msg) => RXToESP.encode(msg).finish(),
+    decodeTX: (bytes) => TXFromESP.decode(bytes),
+    messageTypeField: "txType",
+    rxTopicHandlerMap: logHandlerMap,
 });
 ```
+
 # Contributing
+
 Contributions are welcome! Please submit issues or pull requests via the GitHub repository.
 
 # License
-MIT License © 2025 OTA Hub
+
+MIT License © 2026 OTA-Hub

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

@@ -14,7 +14,7 @@ export type DeviceConnectionState = {
     deviceMac?: string;
     name: string;
     send: (data: string | Uint8Array) => void | Promise<void>;
-    onReceive?: (data: string | Uint8Array) => boolean;
+    onReceive?: (data: string | Uint8Array) => void;
     onConnect?: () => void | Promise<void>;
     onDisconnect?: () => void | Promise<void>;
     autoConnect: boolean;
@@ -22,10 +22,12 @@ export type DeviceConnectionState = {
     isConnecting: boolean;
     logs: LogLine[];
     readBufferLeftover: string;
+    readBufferLeftoverAsBytes: Uint8Array;
 };
 export declare function createDefaultInitialDeviceState<T extends DeviceConnectionState>(uuid: string, props?: any): T;
 export type DeviceWhispererProps<T extends DeviceConnectionState> = {
     createInitialConnectionState?: (uuid: string) => T;
+    connectOn?: boolean;
 };
 export declare function MultiDeviceWhisperer<T extends DeviceConnectionState>({ createInitialConnectionState, }?: DeviceWhispererProps<T>): {
     connections: T[];
@@ -37,6 +39,9 @@ export declare function MultiDeviceWhisperer<T extends DeviceConnectionState>({
     updateConnection: (uuid: string, updater: (c: T) => T) => void;
     reconnectAll: () => void;
     updateConnectionName: (uuid: string, name: string) => void;
+    getConnection: (uuid: string) => T | undefined;
     appendLog: (uuid: string, log: LogLine) => void;
+    isReady: boolean;
+    setIsReady: import("react").Dispatch<import("react").SetStateAction<boolean>>;
 };
 export {};

package/dist/base/device-whisperer.js

@@ -11,6 +11,7 @@ export function createDefaultInitialDeviceState(uuid, props) {
         isConnecting: false,
         logs: [],
         readBufferLeftover: "",
+        readBufferLeftoverAsBytes: new Uint8Array([]),
         ...props
     };
 }
@@ -20,6 +21,8 @@ export function createDefaultInitialDeviceState(uuid, props) {
 export function MultiDeviceWhisperer({ createInitialConnectionState = createDefaultInitialDeviceState, } = {}) {
     const [connections, setConnections] = useState([]);
     const connectionsRef = useRef(connections);
+    const [isReady, setIsReady] = useState(false);
+    const getConnection = (uuid) => connectionsRef.current.find(c => c.uuid === uuid);
     const updateConnection = (uuid, updater) => {
         setConnections(prev => {
             const updated = prev.map((c) => c.uuid === uuid ? updater(c) : c);
@@ -48,7 +51,7 @@ export function MultiDeviceWhisperer({ createInitialConnectionState = createDefa
         };
         connectionsRef.current = [...connectionsRef.current, newConnection];
         setConnections(prev => [...prev, newConnection]);
-        const anyUpdatedConnection = connectionsRef.current.find(c => c.uuid === uuid);
+        const anyUpdatedConnection = getConnection(uuid);
         if (!anyUpdatedConnection) {
             return "";
         }
@@ -70,6 +73,9 @@ export function MultiDeviceWhisperer({ createInitialConnectionState = createDefa
         updateConnection,
         reconnectAll: () => { },
         updateConnectionName,
-        appendLog
+        getConnection,
+        appendLog,
+        isReady,
+        setIsReady
     };
 }

package/dist/index.d.ts

@@ -2,4 +2,5 @@ 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";
+export * from "./transport_layers/mqtt-device-whisperer.js";
 export * from "./types/builds.js";

package/dist/index.js

@@ -5,5 +5,6 @@ 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";
+export * from "./transport_layers/mqtt-device-whisperer.js";
 // Specific types
 export * from "./types/builds.js";

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

@@ -27,5 +27,8 @@ export declare function ProtobufMultiDeviceWhisperer<AppLayer extends DeviceConn
     updateConnection: (uuid: string, updater: (c: AppLayer) => AppLayer) => void;
     reconnectAll: () => void;
     updateConnectionName: (uuid: string, name: string) => void;
+    getConnection: (uuid: string) => AppLayer | undefined;
     appendLog: (uuid: string, log: import("../base/device-whisperer.js").LogLine) => void;
+    isReady: boolean;
+    setIsReady: import("react").Dispatch<import("react").SetStateAction<boolean>>;
 };

package/dist/message_layers/protobuf-wrapper.js

@@ -48,7 +48,7 @@ export function ProtobufMultiDeviceWhisperer({ transportLayer, encodeRX, decodeT
     const sendProtobuf = (uuid, message) => {
         const encoded = encodeRX(message);
         const wrapped = wrapLengthPrefixed(encoded);
-        const conn = transportLayer.connectionsRef.current.find(c => c.uuid === uuid);
+        const conn = transportLayer.getConnection(uuid);
         console.log("Sending Protobuf:", message, "bytes: ", [...wrapped]);
         conn?.send?.(wrapped);
     };

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

@@ -0,0 +1,31 @@
+import { FlashOptions } from "esptool-js";
+import { SerialConnectionState } from "./serial-device-whisperer.js";
+export type ESP32ConnectionState = SerialConnectionState & {
+    isFlashing: boolean;
+    flashProgress: number;
+    flashError: string;
+};
+export type FlashFirmwareProps = {
+    uuid: string;
+    firmwareBlob?: Blob;
+    fileArray?: FlashOptions["fileArray"];
+};
+export declare function ESP32MultiDeviceWhisperer<AppOrMessageLayer extends ESP32ConnectionState>({ ...props }?: {}): {
+    handleFlashFirmware: (uuid: string, assetsToFlash: {
+        blob: Blob;
+        address: number;
+    }[]) => Promise<void>;
+    addConnection: ({ uuid, propCreator }: import("../index.js").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>;
+    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;
+    getConnection: (uuid: string) => AppOrMessageLayer | undefined;
+    appendLog: (uuid: string, log: import("../index.js").LogLine) => void;
+    isReady: boolean;
+    setIsReady: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+};

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

@@ -0,0 +1,89 @@
+import { useEffect } from "react";
+import { ESPLoader, Transport } from "esptool-js";
+import { SerialMultiDeviceWhisperer } from "./serial-device-whisperer.js";
+export function ESP32MultiDeviceWhisperer({ ...props } = {}) {
+    const base = SerialMultiDeviceWhisperer(props);
+    // This function now handles an entire device flashing session
+    const handleFlashFirmware = async (uuid, assetsToFlash) => {
+        const conn = base.getConnection(uuid);
+        if (!conn || !conn.port || assetsToFlash.length === 0)
+            return;
+        await base.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",
+            }));
+        }
+    };
+    useEffect(() => {
+        base.setIsReady(true); // Ready on page load by default
+    }, []);
+    return {
+        ...base,
+        handleFlashFirmware,
+    };
+}

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

@@ -0,0 +1,31 @@
+import { DeviceConnectionState, AddConnectionProps, DeviceWhispererProps } from "../base/device-whisperer.js";
+export type MQTTConnectionState = DeviceConnectionState & {
+    pingFunction?: (props?: any) => void;
+    touchHeartbeat?: () => void;
+};
+export declare function MQTTMultiDeviceWhisperer<AppOrMessageLayer extends MQTTConnectionState>({ serverUrl, uuidFromMessage, subTopicFromUuid, pubTopicFromUuid, serverPort, clientId, username, password, autoConnect, ...props }: {
+    serverUrl: string;
+    uuidFromMessage: (topic: string, payload: Buffer<ArrayBufferLike>) => string;
+    subTopicFromUuid?: (uuid: string) => string;
+    pubTopicFromUuid?: (uuid: string) => string;
+    serverPort?: number;
+    clientId?: string;
+    username?: string;
+    password?: string;
+    autoConnect?: boolean;
+} & DeviceWhispererProps<AppOrMessageLayer>): {
+    addConnection: ({ uuid, propCreator }: AddConnectionProps<AppOrMessageLayer>) => Promise<string | undefined>;
+    removeConnection: (uuid: string) => Promise<void>;
+    connect: (uuid: string) => Promise<void>;
+    disconnect: (uuid: string) => Promise<void>;
+    reconnectAll: () => Promise<void>;
+    connectToMQTTServer: () => (() => void) | undefined;
+    connections: AppOrMessageLayer[];
+    connectionsRef: import("react").RefObject<AppOrMessageLayer[]>;
+    updateConnection: (uuid: string, updater: (c: AppOrMessageLayer) => AppOrMessageLayer) => void;
+    updateConnectionName: (uuid: string, name: string) => void;
+    getConnection: (uuid: string) => AppOrMessageLayer | undefined;
+    appendLog: (uuid: string, log: import("../base/device-whisperer.js").LogLine) => void;
+    isReady: boolean;
+    setIsReady: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+};

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

@@ -0,0 +1,239 @@
+import { useEffect, useRef } from "react";
+import { MultiDeviceWhisperer } from "../base/device-whisperer.js";
+import mqtt from "mqtt";
+export function MQTTMultiDeviceWhisperer({ serverUrl, uuidFromMessage, subTopicFromUuid = undefined, pubTopicFromUuid = undefined, serverPort = 8883, clientId = undefined, username = undefined, password = undefined, autoConnect = true, ...props }) {
+    const base = MultiDeviceWhisperer(props);
+    const clientRef = useRef(null);
+    const isUnmountedRef = useRef(false);
+    const watchdogTimers = useRef({});
+    const addingConnections = new Set();
+    const connectToMQTTServer = () => {
+        isUnmountedRef.current = false;
+        if (clientRef.current) {
+            if (clientRef.current.connected) {
+                base.setIsReady(true);
+                return;
+            }
+            clientRef.current.end(true);
+        }
+        try {
+            const new_client = mqtt.connect(serverUrl, {
+                port: serverPort,
+                clientId: clientId,
+                username,
+                password,
+                clean: true,
+                keepalive: 30,
+                reconnectPeriod: 3000,
+            });
+            new_client.on("connect", () => {
+                console.log("MQTT Whisperer Connected");
+                base.setIsReady(true);
+            });
+            new_client.on("reconnect", () => {
+                console.log("MQTT Whisperer Reconnecting...");
+                base.setIsReady(false);
+            });
+            new_client.on("close", () => {
+                console.log("MQTT Whisperer Closed");
+                base.setIsReady(false);
+            });
+            new_client.on("error", (err) => {
+                base.setIsReady(false);
+                console.error("MQTT Whisperer Error:", err);
+            });
+            new_client.on("message", (topic, payload) => {
+                if (isUnmountedRef.current)
+                    return;
+                const uuid = uuidFromMessage(topic, payload);
+                const bytes = payload instanceof Uint8Array ? payload : new Uint8Array(payload);
+                if (!uuid)
+                    return;
+                const conn = base.getConnection(uuid);
+                if (!conn) {
+                    console.warn("Received message for unknown connection:", uuid);
+                    return;
+                }
+                conn.touchHeartbeat?.();
+                conn.onReceive?.(bytes);
+            });
+            clientRef.current = new_client;
+        }
+        catch (err) {
+            console.error("MQTT init failed:", err);
+            base.setIsReady(false);
+        }
+        return () => {
+            isUnmountedRef.current = true;
+            base.setIsReady(false);
+            Object.keys(watchdogTimers.current).forEach((uuid) => {
+                const timers = watchdogTimers.current[uuid];
+                if (timers) {
+                    clearTimeout(timers.ping);
+                    clearTimeout(timers.warn);
+                    clearTimeout(timers.fail);
+                }
+            });
+            watchdogTimers.current = {};
+            if (clientRef.current) {
+                clientRef.current.removeAllListeners();
+                clientRef.current.end(true);
+            }
+            clientRef.current = null;
+        };
+    };
+    const connect = async (uuid) => {
+        const conn = base.getConnection(uuid);
+        if (!clientRef.current || isUnmountedRef.current || !conn)
+            return;
+        const topic = subTopicFromUuid?.(uuid) ?? uuid;
+        if (clientRef.current.connected && !clientRef.current.disconnecting) {
+            clientRef.current.subscribe(topic, { qos: 1 }, async (err) => {
+                if (err)
+                    console.error("Subscribe failed:", err);
+                else {
+                    console.log("MQTT Subscribed:", topic);
+                    conn.onConnect?.();
+                }
+            });
+        }
+        else {
+            console.warn("Skipped subscribe - client disconnected or unmounted");
+        }
+    };
+    const disconnect = async (uuid) => {
+        if (!clientRef.current || isUnmountedRef.current)
+            return;
+        const topic = subTopicFromUuid?.(uuid) ?? uuid;
+        if (clientRef.current.connected && !clientRef.current.disconnecting) {
+            clientRef.current.unsubscribe(topic, async (err) => {
+                if (err)
+                    console.error("Unsubscribe failed:", err);
+                else {
+                    console.log("MQTT Unsubscribed:", topic);
+                }
+            });
+        }
+        else {
+            console.warn("Skipped subscribe - client disconnected or unmounted");
+        }
+    };
+    function touchHeartbeat(uuid) {
+        if (isUnmountedRef.current)
+            return; // Stop if unmounted
+        clearTimeout(watchdogTimers.current[uuid]?.ping);
+        clearTimeout(watchdogTimers.current[uuid]?.warn);
+        clearTimeout(watchdogTimers.current[uuid]?.fail);
+        const currentConn = base.getConnection(uuid);
+        base.updateConnection(uuid, (c) => ({
+            ...c,
+            isConnected: true,
+            isConnecting: false
+        }));
+        const ping = setTimeout(() => {
+            if (isUnmountedRef.current)
+                return;
+            currentConn?.pingFunction?.();
+        }, 25000);
+        const warn = setTimeout(() => {
+            if (isUnmountedRef.current)
+                return;
+            base.updateConnection(uuid, (c) => ({ ...c, isConnected: false, isConnecting: true }));
+        }, 30000);
+        const fail = setTimeout(() => {
+            if (isUnmountedRef.current)
+                return;
+            base.updateConnection(uuid, (c) => ({ ...c, isConnected: false, isConnecting: false }));
+        }, 60000);
+        watchdogTimers.current[uuid] = { ping, warn, fail };
+    }
+    const defaultOnReceive = (uuid, data) => {
+        const conn = base.getConnection(uuid);
+        if (!conn)
+            return;
+        conn.touchHeartbeat?.();
+        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);
+        base.appendLog(uuid, {
+            level: 2,
+            message: asText,
+        });
+    };
+    const defaultSend = async (uuid, data) => {
+        const conn = base.getConnection(uuid);
+        if (!conn)
+            return;
+        const payload = typeof data === 'string'
+            ? new TextEncoder().encode(data)
+            : data;
+        base.appendLog(uuid, {
+            level: 5,
+            message: payload,
+        });
+        clientRef.current?.publish(pubTopicFromUuid?.(uuid) ?? uuid, payload); // TS is wrong here!
+    };
+    const addConnection = async ({ uuid, propCreator }) => {
+        if (!clientRef.current || isUnmountedRef.current)
+            return;
+        if (!uuid) {
+            Error("In MQTT you MUST define a UUID otherwise we don't know what device we're connecting to!");
+            return;
+        }
+        if (base.connectionsRef.current.some(c => c.uuid === uuid) || addingConnections.has(uuid)) {
+            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)),
+                    touchHeartbeat: props?.touchHeartbeat || (() => touchHeartbeat(id)),
+                    ...props
+                };
+            }
+        });
+        // Delete this adding connections item
+        addingConnections.delete(uuid);
+        // Connect immediately
+        connect(uuid);
+        return uuid;
+    };
+    const removeConnection = async (uuid) => {
+        await disconnect(uuid);
+        base.removeConnection(uuid);
+    };
+    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);
+        }
+    };
+    useEffect(() => {
+        if (autoConnect || props.connectOn)
+            connectToMQTTServer();
+    }, [serverUrl, props.connectOn]);
+    return {
+        ...base,
+        addConnection,
+        removeConnection,
+        connect,
+        disconnect,
+        reconnectAll,
+        connectToMQTTServer
+    };
+}

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

@@ -1,31 +1,23 @@
-import { FlashOptions, Transport } from "esptool-js";
+import { 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"];
+    slipReadWrite?: boolean;
 };
 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;
+    getConnection: (uuid: string) => AppOrMessageLayer | undefined;
     appendLog: (uuid: string, log: import("../base/device-whisperer.js").LogLine) => void;
+    isReady: boolean;
+    setIsReady: import("react").Dispatch<import("react").SetStateAction<boolean>>;
 };

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

@@ -1,9 +1,10 @@
-import { ESPLoader, Transport } from "esptool-js";
+import { Transport } from "esptool-js";
 import { MultiDeviceWhisperer } from "../base/device-whisperer.js";
+import { useEffect } from "react";
 export function SerialMultiDeviceWhisperer({ ...props } = {}) {
     const base = MultiDeviceWhisperer(props);
     const defaultOnReceive = (uuid, data) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         if (!conn)
             return;
         const decoder = new TextDecoder();
@@ -35,42 +36,106 @@ export function SerialMultiDeviceWhisperer({ ...props } = {}) {
         }
     };
     const defaultSend = async (uuid, data) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         if (!conn)
             return;
-        const asString = typeof data === "string"
-            ? data
-            : btoa(String.fromCharCode(...data));
+        // Convert to bytes
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        // Log for debugging
         base.appendLog(uuid, {
             level: 3,
-            message: asString,
+            message: typeof data === "string" ? data : btoa(String.fromCharCode(...bytes)),
         });
-        const bytes = typeof data === "string"
-            ? new TextEncoder().encode(data)
-            : data;
-        console.log("conn.transport?.write:", conn.transport?.write, bytes);
-        await conn.transport?.write(bytes);
+        if (!conn.transport)
+            return;
+        await conn.transport.write(bytes);
+        return;
     };
     const readLoop = async (uuid, transport) => {
+        const conn = base.getConnection(uuid);
+        if (!conn)
+            return;
+        let readBuffer = ""; // accumulate ASCII/lines
+        let slipBuffer = []; // accumulate SLIP frames
+        let inSlipFrame = false; // are we inside a SLIP frame?
+        let escapeNext = false;
         try {
+            const reader = transport.rawRead();
             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);
+                const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+                for (let i = 0; i < bytes.length; i++) {
+                    const b = bytes[i];
+                    if (inSlipFrame) {
+                        // SLIP decoding
+                        if (b === 0xC0) {
+                            if (slipBuffer.length > 0) {
+                                // complete SLIP frame received
+                                const payload = new Uint8Array(slipBuffer);
+                                try {
+                                    conn.onReceive?.(payload);
+                                }
+                                catch (e) {
+                                    console.error("Failed to decode SLIP frame", e);
+                                    base.appendLog(uuid, {
+                                        level: 1,
+                                        message: "Failed to decode message",
+                                        timestamp: new Date(),
+                                    });
+                                }
+                                slipBuffer = [];
+                            }
+                            inSlipFrame = false;
+                            escapeNext = false;
+                        }
+                        else if (escapeNext) {
+                            if (b === 0xDC)
+                                slipBuffer.push(0xC0);
+                            else if (b === 0xDD)
+                                slipBuffer.push(0xDB);
+                            else {
+                                // protocol violation: discard frame
+                                slipBuffer = [];
+                                inSlipFrame = false;
+                            }
+                            escapeNext = false;
+                        }
+                        else if (b === 0xDB) {
+                            escapeNext = true;
+                        }
+                        else {
+                            slipBuffer.push(b);
+                        }
+                        continue;
+                    }
+                    if (b === 0xC0 && conn.slipReadWrite) {
+                        // start of a SLIP frame
+                        inSlipFrame = true;
+                        slipBuffer = [];
+                        escapeNext = false;
+                        continue;
+                    }
+                    // treat as normal ASCII text
+                    const char = String.fromCharCode(b);
+                    readBuffer += char;
+                    // check for newline
+                    let newlineIndex;
+                    while ((newlineIndex = readBuffer.indexOf("\n")) >= 0) {
+                        const line = readBuffer.slice(0, newlineIndex).replace(/\r$/, "");
+                        readBuffer = readBuffer.slice(newlineIndex + 1);
+                        if (line.trim()) {
+                            conn.onReceive?.(line);
+                        }
+                    }
+                }
             }
         }
         catch (e) {
             base.appendLog(uuid, {
                 level: 0,
-                message: `[!] Read loop error: ${e}`
+                message: `[!] Read loop error: ${e}`,
             });
             await disconnect(uuid);
         }
@@ -84,12 +149,12 @@ export function SerialMultiDeviceWhisperer({ ...props } = {}) {
             }));
             base.appendLog(uuid, {
                 level: 0,
-                message: "[!] Serial disconnected"
+                message: "[!] Serial disconnected",
             });
         }
     };
     const restartDevice = async (uuid, default_transport) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         const transport = default_transport ?? conn?.transport;
         if (transport) {
             await transport.setRTS(false);
@@ -102,7 +167,7 @@ export function SerialMultiDeviceWhisperer({ ...props } = {}) {
         }
     };
     const connect = async (uuid, baudrate, restart_on_connect = true) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         if (!conn?.port)
             return;
         if (!conn?.transport) {
@@ -146,7 +211,7 @@ export function SerialMultiDeviceWhisperer({ ...props } = {}) {
         }
     };
     const disconnect = async (uuid, timeout = 2000) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         if (conn?.transport) {
             try {
                 // Attempt disconnect, but don’t hang if the port is crashed
@@ -194,82 +259,6 @@ export function SerialMultiDeviceWhisperer({ ...props } = {}) {
         ;
         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) => {
@@ -278,13 +267,15 @@ export function SerialMultiDeviceWhisperer({ ...props } = {}) {
             return connect(c.uuid, ...connectionProps);
         }));
     };
+    useEffect(() => {
+        base.setIsReady(true); // Ready on page load by default
+    }, []);
     return {
         ...base,
         addConnection,
         removeConnection,
         connect,
         disconnect,
-        handleFlashFirmware,
         reconnectAll
     };
 }

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

@@ -9,7 +9,10 @@ export type DeviceObjectResponse = {
     deviceConnectedTime: Date | null;
     deviceLastCommTime: Date | null;
 };
-export declare function WebsocketMultiDeviceWhisperer<AppOrMessageLayer extends WebsocketConnectionState>(server_url: string, server_port: number, { ...props }?: {}): {
+export declare function WebsocketMultiDeviceWhisperer<AppOrMessageLayer extends WebsocketConnectionState>({ server_url, server_port, ...props }: {
+    server_url: string;
+    server_port: number;
+}): {
     addConnection: ({ uuid, propCreator }: AddConnectionProps<AppOrMessageLayer>) => Promise<string>;
     removeConnection: (uuid: string) => Promise<void>;
     connect: (uuid: string, attempt?: number) => Promise<void>;
@@ -20,5 +23,8 @@ export declare function WebsocketMultiDeviceWhisperer<AppOrMessageLayer extends
     connectionsRef: import("react").RefObject<AppOrMessageLayer[]>;
     updateConnection: (uuid: string, updater: (c: AppOrMessageLayer) => AppOrMessageLayer) => void;
     updateConnectionName: (uuid: string, name: string) => void;
+    getConnection: (uuid: string) => AppOrMessageLayer | undefined;
     appendLog: (uuid: string, log: import("../base/device-whisperer.js").LogLine) => void;
+    isReady: boolean;
+    setIsReady: import("react").Dispatch<import("react").SetStateAction<boolean>>;
 };

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

@@ -1,7 +1,9 @@
+import { useEffect } from "react";
 import { MultiDeviceWhisperer } from "../base/device-whisperer.js";
-export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...props } = {}) {
+export function WebsocketMultiDeviceWhisperer({ server_url, server_port, ...props }) {
+    const base = MultiDeviceWhisperer(props);
     const defaultOnReceive = (uuid, data) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         if (!conn)
             return;
         const decoder = new TextDecoder();
@@ -33,7 +35,7 @@ export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...prop
         }
     };
     const defaultSend = async (uuid, data) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         if (!conn || !conn.ws)
             return;
         const asString = typeof data === "string"
@@ -48,7 +50,7 @@ export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...prop
     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);
+        const conn = base.getConnection(uuid);
         if (!conn)
             return;
         if (conn.ws && conn.ws.readyState === WebSocket.OPEN) {
@@ -98,7 +100,7 @@ export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...prop
                     ws: undefined
                 }));
                 base.appendLog(uuid, { level: 0, message: "[!] WS disconnected" });
-                const updated_conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+                const updated_conn = base.getConnection(uuid);
                 if (!updated_conn) {
                     base.appendLog(uuid, { level: 0, message: "[!] Connection lost!" });
                     return;
@@ -124,7 +126,7 @@ export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...prop
         }
     };
     const disconnect = async (uuid) => {
-        const conn = base.connectionsRef.current.find((c) => c.uuid === uuid);
+        const conn = base.getConnection(uuid);
         if (!conn?.ws)
             return;
         base.updateConnection(uuid, (c) => ({
@@ -138,7 +140,6 @@ export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...prop
         conn.ws.close();
         await conn?.onDisconnect?.();
     };
-    const base = MultiDeviceWhisperer(props);
     const addConnection = async ({ uuid, propCreator }) => {
         return await base.addConnection({
             uuid,
@@ -181,6 +182,9 @@ export function WebsocketMultiDeviceWhisperer(server_url, server_port, { ...prop
             await connect(c.uuid);
         }
     };
+    useEffect(() => {
+        base.setIsReady(true); // Ready on page load by default
+    }, []);
     return {
         ...base,
         addConnection,

package/package.json

@@ -1,53 +1,52 @@
-{
-  "name": "ota-hub-reactjs",
-  "version": "0.0.7",
-  "description": "ReactJS tools for building web apps to flash MCU devices such as esp32, brought to you by OTA Hub.",
-  "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.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"
-
-  }
-}
+{
+  "name": "ota-hub-reactjs",
+  "version": "0.0.9",
+  "description": "ReactJS tools for building web apps to flash MCU devices such as esp32, brought to you by OTA Hub.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.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.1",
+    "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"
+  }
+}