@blueyerobotics/blueye-ts 3.10.0 → 3.12.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/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,29 +28,39 @@ 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>;
     getTelemetry<T extends Tel>(type: T): Promise<DecodedTelOutput<T>>;
+    waitForTelemetry<T extends Tel>(type: T, timeout?: number | null): Promise<DecodedTelOutput<T>>;
     sendControl<T extends Ctrl>(ctrl: T, opts?: CreateArgs<T>): Promise<void>;
 }
 export {};

package/dist/src/client.js

@@ -1,102 +1,227 @@
 "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);
-                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);
+            this.handleTelemetryMessage("sub", topic, msg);
+        });
+        this.sonarSub.on("message", (topic, msg) => {
+            this.handleTelemetryMessage("sonar", topic, msg);
         });
+        this.emit(this.state);
+        this.logger.info(`[client] ${this.state}`);
         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;
         }
-        if (this.state === "connecting") {
-            this.logger.warn("[client] already connecting");
+        const oldState = this.state;
+        this.socketState[name] = newState;
+        this.logger.info(`[${name}] ${newState}`);
+        this.emit(`${name}-${newState}`);
+        // If all sockets are connected, emit "connected"
+        this.emit(this.state);
+        if (oldState !== this.state) {
+            this.logger.info(`[client] ${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;
+        }
+        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.socketState[operation] !== "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.once("connected", async () => {
+            const msg = await this.waitForTelemetry("DroneInfoTel");
+            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 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");
+                this.isSonarDetected = true;
+                this.sonarSub.connect(this.sonarUrl);
+            }
+        });
         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"]) {
+            this.updateSocketState(name, "connecting");
+        }
+        this.logger.info(`[client] ${this.state}`);
+        this.emit(this.state);
         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("rpc");
         if (!(0, exports.isInProtocol)(req) || !req.endsWith("Req")) {
             throw new Error(`[rpc] unknown protocol: ${req}`);
         }
@@ -132,6 +257,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")) {
@@ -141,7 +269,33 @@ class BlueyeClient extends strict_event_emitter_1.Emitter {
         this.logger.debug("[rpc] result:", result);
         return result;
     }
+    async waitForTelemetry(type, timeout = null) {
+        // Tries to get the latest telemetry via RPC first, in case we already have it cached in Blunux
+        try {
+            return await this.getTelemetry(type);
+        }
+        catch (error) {
+            this.logger.trace(`[client] failed to get latest ${type} via RPC:`, error);
+        }
+        // If that fails, wait for the next telemetry message to arrive via SUB
+        return new Promise((resolve, reject) => {
+            const listener = (...data) => {
+                this.off(type, listener);
+                if (timer)
+                    clearTimeout(timer);
+                resolve(data[0]);
+            };
+            const timer = timeout
+                ? setTimeout(() => {
+                    this.off(type, listener);
+                    reject(new Error(`[client] timed out waiting for ${type} telemetry`));
+                }, timeout)
+                : null;
+            this.on(type, listener);
+        });
+    }
     async sendControl(ctrl, opts = {}) {
+        this.ensureConnected("pub");
         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.10.0",
+  "version": "3.12.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 --experimental-test-isolation=none --test-concurrency=1 test/**/*.test.js",
+    "test:one": "node --test --test-concurrency=1"
   }
 }