@blueyerobotics/blueye-ts 3.9.0 → 3.11.0

package/README.md

@@ -35,3 +35,33 @@ client.on("BatteryTel", data => {
 
 client.connect();
 ```
+
+## Connection states
+
+`BlueyeClient` manages four sockets: `sub`, `rpc`, `pub`, and `sonar`. Global state events (`connecting`, `connected`, `disconnected`) are emitted when the derived state changes. Per-socket events use the `${socket}-${state}` format (e.g. `sonar-connected`, `rpc-connecting`):
+
+```ts
+client.on("connected", () => {
+  console.log("all required sockets ready");
+});
+
+client.on("sonar-connected", () => {
+  console.log("sonar socket ready");
+});
+```
+
+The derived `client.state` reflects the aggregate of the core sockets (`sub`, `rpc`, `pub`). If a multibeam sonar is detected via `DroneInfoTel`, the sonar socket is also required for `connected`.
+
+- `disconnected`: `connect()` has not been called.
+- `connecting`: one or more required sockets are not yet ready.
+- `connected`: all required sockets are ready — safe to call `sendRequest()`, `getTelemetry()`, and `sendControl()`.
+
+`client.sonarState` reflects the sonar socket independently. If the client loses one or more sockets after being connected, the derived state moves back to `connecting`. `sendRequest()` and `sendControl()` reject unless the client is in the `connected` state.
+
+## Sonar support
+
+`BlueyeClient` connects the sonar websocket endpoint at `ws://192.168.1.101:9988` when a supported multibeam device is detected in a `DroneInfoTel` message.
+
+- On `connect()`, the sonar socket subscribes but only connects when a known multibeam device ID is found in the guest-port device list.
+- Once detected, the sonar socket connects and the global `connected` state requires it to be ready.
+- Sonar telemetry such as `MultibeamPingTel`, `MultibeamConfigTel`, and `MultibeamDiscoveryTel` is emitted through the same typed event interface as other telemetry messages.

package/dist/example.js

@@ -4,14 +4,24 @@ const index_1 = require("./index");
 const main = async () => {
     const client = new index_1.BlueyeClient();
     client.on("connected", async () => {
-        // request battery information
-        const batteryRep = await client.sendRequest("GetBatteryReq");
-        console.log("batteryRep:", batteryRep);
-        // get latest battery telemetry
-        const batteryTel = await client.getTelemetry("BatteryTel");
-        console.log("batteryTel:", batteryTel);
-        // send a control message to change the light intensity to 1
-        await client.sendControl("LightsCtrl", { lights: { value: 1 } });
+        try {
+            // request battery information
+            const batteryRep = await client.sendRequest("GetBatteryReq");
+            console.log("batteryRep:", batteryRep);
+            // get latest battery telemetry
+            const batteryTel = await client.getTelemetry("BatteryTel");
+            console.log("batteryTel:", batteryTel);
+        }
+        catch (error) {
+            // console.error("Error:", error);
+        }
+        // send a control message to change the light intensity to 0.1
+        console.log("setting light intensity to 0.1 for 1 second...");
+        await client.sendControl("LightsCtrl", { lights: { value: 0.1 } });
+        setTimeout(async () => {
+            console.log("setting light intensity back to 0...");
+            await client.sendControl("LightsCtrl", { lights: { value: 0 } });
+        }, 1000);
     });
     // subscribe to battery telemetry updates
     client.on("BatteryTel", (data) => {

package/dist/sonar-example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sonar-example.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const main = async () => {
+    const client = new index_1.BlueyeClient();
+    client.on("connected", () => {
+        console.log("client connected");
+    });
+    client.on("connecting", () => {
+        console.log("client connecting...");
+    });
+    client.on("disconnected", () => {
+        console.log("client disconnected");
+    });
+    client.on("sonar-connected", () => {
+        console.log("sonar connected");
+    });
+    client.on("sonar-connecting", () => {
+        console.log("sonar connecting...");
+    });
+    client.on("MultibeamDiscoveryTel", (data) => {
+        console.log("received MultibeamDiscoveryTel:", data.discovery);
+    });
+    client.on("MultibeamConfigTel", (data) => {
+        console.log("received MultibeamConfigTel:", data.config);
+    });
+    client.on("MultibeamPingTel", (data) => {
+        const ping = data.ping;
+        if (!ping) {
+            return;
+        }
+        console.log("received MultibeamPingTel:", {
+            deviceId: ping.deviceId,
+            range: ping.range,
+            beams: ping.numberOfBeams,
+            ranges: ping.numberOfRanges,
+        });
+    });
+    client.connect();
+};
+main();

package/dist/src/binlog-parser.d.ts

@@ -35,4 +35,18 @@ export declare const parseMessages: (decompressed: Uint8Array, fixTimes?: boolea
  * @param messages The messages to fix the times for.
  * @returns The messages with corrected times.
  */
+/**
+ * Parse a single varint-prefixed BinlogRecord from raw (uncompressed) bytes.
+ * Used for streaming playback where individual frames are fetched via HTTP Range requests.
+ * @param bytes Raw bytes containing a single varint-length-prefixed BinlogRecord.
+ * @returns The parsed message, or null if the record is not a known protocol type.
+ */
+export declare const parseFrame: (bytes: Uint8Array) => Message | null;
+/**
+ * Parse multiple contiguous varint-prefixed BinlogRecords from raw (uncompressed) bytes.
+ * Used for streaming playback where frame batches are fetched via HTTP Range requests.
+ * @param bytes Raw bytes containing one or more varint-length-prefixed BinlogRecords.
+ * @returns An array of parsed messages.
+ */
+export declare const parseFrames: (bytes: Uint8Array) => Message[];
 export declare const fixMessageTimes: (messages: Message[]) => Message[];

package/dist/src/binlog-parser.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fixMessageTimes = exports.parseMessages = exports.decompress = exports.parse = void 0;
+exports.fixMessageTimes = exports.parseFrames = exports.parseFrame = exports.parseMessages = exports.decompress = exports.parse = void 0;
 const protocol_definitions_1 = require("@blueyerobotics/protocol-definitions");
 const wire_1 = require("@bufbuild/protobuf/wire");
 const buffer_1 = require("buffer");
@@ -115,6 +115,27 @@ exports.parseMessages = parseMessages;
  * @param messages The messages to fix the times for.
  * @returns The messages with corrected times.
  */
+/**
+ * Parse a single varint-prefixed BinlogRecord from raw (uncompressed) bytes.
+ * Used for streaming playback where individual frames are fetched via HTTP Range requests.
+ * @param bytes Raw bytes containing a single varint-length-prefixed BinlogRecord.
+ * @returns The parsed message, or null if the record is not a known protocol type.
+ */
+const parseFrame = (bytes) => {
+    const messages = (0, exports.parseFrames)(bytes);
+    return messages.length > 0 ? messages[0] : null;
+};
+exports.parseFrame = parseFrame;
+/**
+ * Parse multiple contiguous varint-prefixed BinlogRecords from raw (uncompressed) bytes.
+ * Used for streaming playback where frame batches are fetched via HTTP Range requests.
+ * @param bytes Raw bytes containing one or more varint-length-prefixed BinlogRecords.
+ * @returns An array of parsed messages.
+ */
+const parseFrames = (bytes) => {
+    return (0, exports.parseMessages)(bytes, false);
+};
+exports.parseFrames = parseFrames;
 const fixMessageTimes = (messages) => {
     if (messages.length === 0)
         return messages;

package/dist/src/client.d.ts

@@ -1,6 +1,7 @@
 import { blueye } from "@blueyerobotics/protocol-definitions";
 import { type LogLevel } from "consola";
 import { Emitter } from "strict-event-emitter";
+export declare const MULTIBEAM_DEVICE_IDS: number[];
 export type Protocol = typeof blueye.protocol;
 export type ProtocolType = "Req" | "Rep" | "Tel" | "Ctrl";
 export type ProtocolKey = Extract<keyof Protocol, `${string}${ProtocolType}`>;
@@ -14,8 +15,11 @@ export type CreateArgs<T extends Req | Ctrl> = Parameters<MsgHandler<T>["create"
 export type DecodedOutput<T extends Req> = ReturnType<ReqToRep<T>["decode"]>;
 export type DecodedTelOutput<T extends Tel> = ReturnType<Protocol[T]["decode"]>;
 type State = "connecting" | "connected" | "disconnected";
+export type SocketName = "sub" | "rpc" | "pub" | "sonar";
 export type Events = {
     [K in State]: [];
+} & {
+    [K in `${SocketName}-${State}`]: [];
 } & {
     [K in Tel]: [DecodedTelOutput<K>];
 };
@@ -24,25 +28,34 @@ type Options = Partial<{
     subUrl: string;
     rpcUrl: string;
     pubUrl: string;
+    sonarUrl: string;
     timeout: number;
     reconnectInterval: number;
     logLevel: LogLevel;
     autoConnect: boolean;
 }>;
 export declare class BlueyeClient extends Emitter<Events> {
-    state: State;
     timeout: number;
     reconnectInterval: number;
     private subUrl;
     private rpcUrl;
     private pubUrl;
+    private sonarUrl;
     private sub;
     private rpc;
     private pub;
+    private sonarSub;
     private queue;
     private logger;
-    constructor({ subUrl, rpcUrl, pubUrl, timeout, reconnectInterval, logLevel, autoConnect, }?: Options);
-    private updateState;
+    private shouldBeConnected;
+    private isSonarDetected;
+    private socketState;
+    constructor({ subUrl, rpcUrl, pubUrl, sonarUrl, timeout, reconnectInterval, logLevel, autoConnect, }?: Options);
+    get state(): State;
+    private updateSocketState;
+    private handleTelemetryMessage;
+    private bindSocketLifecycle;
+    private ensureConnected;
     connect(): void;
     disconnect(): void;
     sendRequest<T extends Req>(req: T, opts?: CreateArgs<T>): Promise<DecodedOutput<T> | null>;

package/dist/src/client.js

@@ -1,102 +1,218 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BlueyeClient = exports.isInProtocol = void 0;
+exports.BlueyeClient = exports.isInProtocol = exports.MULTIBEAM_DEVICE_IDS = void 0;
 const protocol_definitions_1 = require("@blueyerobotics/protocol-definitions");
 const buffer_1 = require("buffer");
 const consola_1 = require("consola");
-const jszmq_1 = require("jszmq");
+const jszmq_1 = require("@blueyerobotics/jszmq");
 const strict_event_emitter_1 = require("strict-event-emitter");
 const async_queue_1 = require("./async-queue");
 const schema_1 = require("./schema");
+const semver = __importStar(require("semver"));
 const DEFAULT_SUB_URL = "ws://192.168.1.101:9985";
 const DEFAULT_RPC_URL = "ws://192.168.1.101:9986";
 const DEFAULT_PUB_URL = "ws://192.168.1.101:9987";
+const DEFAULT_SONAR_URL = "ws://192.168.1.101:9988";
+exports.MULTIBEAM_DEVICE_IDS = [13, 16, 18, 20, 29, 30, 41, 42];
 const isInProtocol = (key) => {
     return key in protocol_definitions_1.blueye.protocol;
 };
 exports.isInProtocol = isInProtocol;
+const hasSonarEndpoint = (version) => {
+    const coercedVersion = semver.coerce(version);
+    return coercedVersion
+        ? semver.satisfies(coercedVersion, ">=4.7.0") || version.endsWith("-dev")
+        : false;
+};
 class BlueyeClient extends strict_event_emitter_1.Emitter {
-    state = "disconnected";
     timeout;
     reconnectInterval;
     subUrl;
     rpcUrl;
     pubUrl;
+    sonarUrl;
     sub;
     rpc;
     pub;
+    sonarSub;
     queue;
     logger;
-    constructor({ subUrl = DEFAULT_SUB_URL, rpcUrl = DEFAULT_RPC_URL, pubUrl = DEFAULT_PUB_URL, timeout = 2000, reconnectInterval = 2000, logLevel = consola_1.LogLevels.info, autoConnect = false, } = {}) {
+    shouldBeConnected = false;
+    isSonarDetected = false;
+    socketState = {
+        sub: "disconnected",
+        rpc: "disconnected",
+        pub: "disconnected",
+        sonar: "disconnected",
+    };
+    constructor({ subUrl = DEFAULT_SUB_URL, rpcUrl = DEFAULT_RPC_URL, pubUrl = DEFAULT_PUB_URL, sonarUrl = DEFAULT_SONAR_URL, timeout = 2000, reconnectInterval = 2000, logLevel = consola_1.LogLevels.info, autoConnect = false, } = {}) {
         super();
         this.timeout = timeout;
         this.reconnectInterval = reconnectInterval;
         this.subUrl = subUrl;
         this.rpcUrl = rpcUrl;
         this.pubUrl = pubUrl;
+        this.sonarUrl = sonarUrl;
         this.sub = new jszmq_1.Sub();
         this.rpc = new jszmq_1.Req();
         this.pub = new jszmq_1.Pub();
+        this.sonarSub = new jszmq_1.Sub();
         this.queue = new async_queue_1.AsyncQueue();
         this.logger = (0, consola_1.createConsola)({
             level: logLevel,
             formatOptions: { colors: true, compact: false },
         });
+        this.bindSocketLifecycle("sub", this.sub);
+        this.bindSocketLifecycle("rpc", this.rpc);
+        this.bindSocketLifecycle("pub", this.pub);
+        this.bindSocketLifecycle("sonar", this.sonarSub);
         this.sub.on("message", (topic, msg) => {
-            const { key, data } = schema_1.responseSchema.parse({ key: topic, data: msg });
-            if (!(0, exports.isInProtocol)(key) || !key.endsWith("Tel")) {
-                this.logger.warn("[sub] unknown protocol:", key);
+            this.handleTelemetryMessage("sub", topic, msg);
+        });
+        this.sonarSub.on("message", (topic, msg) => {
+            this.handleTelemetryMessage("sonar", topic, msg);
+        });
+        this.once("DroneInfoTel", (msg) => {
+            const version = msg.droneInfo?.blunuxVersion;
+            if (!hasSonarEndpoint(version ?? "")) {
+                this.logger.warn(`[sonar] incompatible Blunux version detected in DroneInfoTel: ${version}; sonar telemetry may not be available`);
                 return;
             }
-            const protocol = protocol_definitions_1.blueye.protocol[key];
-            const message = protocol.decode(data);
-            this.logger.verbose("[sub] message:", key, message);
-            this.emit(key, message);
+            const devices = [
+                ...(msg.droneInfo?.gp?.gp1?.deviceList?.devices ?? []),
+                ...(msg.droneInfo?.gp?.gp2?.deviceList?.devices ?? []),
+                ...(msg.droneInfo?.gp?.gp3?.deviceList?.devices ?? []),
+            ].map((device) => device.deviceId);
+            if (devices.some((deviceId) => exports.MULTIBEAM_DEVICE_IDS.includes(deviceId))) {
+                this.logger.info("[sonar] multibeam device detected in DroneInfoTel:", devices);
+                this.isSonarDetected = true;
+                this.sonarSub.connect(this.sonarUrl);
+            }
         });
         if (autoConnect) {
             this.connect();
         }
     }
-    updateState(newState) {
-        this.state = newState;
-        this.logger.info(`[client] ${newState}`);
-        this.emit(newState);
+    get state() {
+        if (!this.shouldBeConnected)
+            return "disconnected";
+        const { sub, rpc, pub } = this.socketState;
+        if (sub === "connected" &&
+            rpc === "connected" &&
+            pub === "connected" &&
+            (this.isSonarDetected ? this.socketState.sonar === "connected" : true)) {
+            return "connected";
+        }
+        return "connecting";
     }
-    connect() {
-        if (this.state === "connected") {
-            this.logger.warn("[client] already connected");
+    updateSocketState(name, newState) {
+        if (this.socketState[name] === newState) {
+            return;
+        }
+        this.socketState[name] = newState;
+        this.logger.info(`[${name}] ${newState}`);
+        this.emit(`${name}-${newState}`);
+        // If all sockets are connected, emit "connected"
+        this.emit(this.state);
+    }
+    handleTelemetryMessage(socketName, topic, msg) {
+        const { key, data } = schema_1.responseSchema.parse({ key: topic, data: msg });
+        if (!(0, exports.isInProtocol)(key) || !key.endsWith("Tel")) {
+            this.logger.warn(`[${socketName}] unknown protocol:`, key);
             return;
         }
-        if (this.state === "connecting") {
-            this.logger.warn("[client] already connecting");
+        const protocol = protocol_definitions_1.blueye.protocol[key];
+        const message = protocol.decode(data);
+        this.logger.verbose(`[${socketName}] message:`, key, message);
+        this.emit(key, message);
+    }
+    bindSocketLifecycle(name, socket) {
+        socket.on("ready", () => {
+            if (!this.shouldBeConnected)
+                return;
+            this.updateSocketState(name, "connected");
+        });
+        socket.on("lost", () => {
+            if (!this.shouldBeConnected)
+                return;
+            this.updateSocketState(name, "connecting");
+        });
+    }
+    ensureConnected(operation) {
+        if (this.state !== "connected") {
+            throw new Error(`[client] cannot send ${operation} while ${this.state}; call connect() and wait for "connected"`);
+        }
+    }
+    connect() {
+        if (this.shouldBeConnected) {
+            this.logger.warn("[client] already connecting or connected");
             return;
         }
         this.sub.options.reconnectInterval = this.reconnectInterval;
         this.rpc.options.reconnectInterval = this.reconnectInterval;
         this.pub.options.reconnectInterval = this.reconnectInterval;
-        this.updateState("connecting");
+        this.sonarSub.options.reconnectInterval = this.reconnectInterval;
+        this.shouldBeConnected = true;
+        for (const name of ["sub", "rpc", "pub", "sonar"]) {
+            this.updateSocketState(name, "connecting");
+        }
         this.sub.subscribe("");
         this.sub.connect(this.subUrl);
         this.rpc.connect(this.rpcUrl);
         this.pub.connect(this.pubUrl);
-        this.updateState("connected");
+        this.sonarSub.subscribe("");
     }
     disconnect() {
-        if (this.state === "disconnected") {
+        if (!this.shouldBeConnected) {
             this.logger.warn("[client] already disconnected");
             return;
         }
-        if (this.state === "connecting") {
-            this.logger.warn("[client] cannot disconnect while connecting");
-            return;
-        }
+        this.shouldBeConnected = false;
         this.sub.unsubscribe("");
         this.sub.disconnect(this.subUrl);
         this.rpc.disconnect(this.rpcUrl);
         this.pub.disconnect(this.pubUrl);
-        this.updateState("disconnected");
+        this.sonarSub.unsubscribe("");
+        this.sonarSub.disconnect(this.sonarUrl);
+        for (const name of ["sub", "rpc", "pub", "sonar"]) {
+            this.updateSocketState(name, "disconnected");
+        }
     }
     async sendRequest(req, opts = {}) {
+        this.ensureConnected("request");
         if (!(0, exports.isInProtocol)(req) || !req.endsWith("Req")) {
             throw new Error(`[rpc] unknown protocol: ${req}`);
         }
@@ -132,6 +248,9 @@ class BlueyeClient extends strict_event_emitter_1.Emitter {
         const response = await this.sendRequest("GetTelemetryReq", {
             messageType: type,
         });
+        if (!response) {
+            throw new Error(`[rpc] no response for telemetry request: ${type}`);
+        }
         const { payload } = schema_1.telemetrySchema.parse(response);
         const { typeUrl, value } = payload;
         if (!(0, exports.isInProtocol)(typeUrl) || !typeUrl.endsWith("Tel")) {
@@ -142,6 +261,7 @@ class BlueyeClient extends strict_event_emitter_1.Emitter {
         return result;
     }
     async sendControl(ctrl, opts = {}) {
+        this.ensureConnected("control");
         if (!(0, exports.isInProtocol)(ctrl) || !ctrl.endsWith("Ctrl")) {
             throw new Error(`[pub] unknown protocol: ${ctrl}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueyerobotics/blueye-ts",
-  "version": "3.9.0",
+  "version": "3.11.0",
   "description": "A TypeScript client for interacting with Blueye underwater drones.",
   "repository": {
     "type": "git",
@@ -15,22 +15,27 @@
   "author": "Blueye <contact@blueye.no> (https://blueye.no/)",
   "license": "LGPL-3.0-only",
   "dependencies": {
+    "@blueyerobotics/jszmq": "^0.2.0",
     "@blueyerobotics/protocol-definitions": "3.2.0-98aafe92",
     "@bufbuild/protobuf": "^2.11.0",
     "buffer": "^6.0.3",
     "consola": "^3.4.2",
     "fflate": "^0.8.2",
-    "jszmq": "^0.1.2",
+    "semver": "^7.7.4",
     "strict-event-emitter": "^0.5.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.14",
     "@types/node": "^25.4.0",
+    "@types/semver": "^7.7.1",
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "start": "node dist/example.js",
-    "build": "tsc"
+    "start": "pnpm build && node dist/example.js",
+    "start:sonar": "pnpm build && node dist/sonar-example.js",
+    "build": "tsc",
+    "test": "pnpm build && node --test --test-concurrency=1 test/**/*.test.js",
+    "test:one": "node --test --test-concurrency=1"
   }
 }