motion-master-client 0.0.55 → 0.0.56

package/src/lib/hardware-description.ts

@@ -0,0 +1,129 @@
+import { isEqual } from 'lodash';
+import semver from 'semver';
+
+export interface HardwareComponent {
+  name: string;
+  version: string;
+  serialNumber: string;
+}
+
+export type AssemblyComponent = HardwareComponent;
+export type DeviceComponent = HardwareComponent;
+
+export interface Assembly {
+  name: string;
+  id: string;
+  version: string;
+  serialNumber: string;
+  components: AssemblyComponent[];
+}
+
+export interface HardwareDevice {
+  name: string;
+  id: string;
+  version: string;
+  keyId: string;
+  serialNumber: string;
+  macAddress: string;
+  components: DeviceComponent[];
+}
+
+/**
+ * @link https://docs.google.com/document/d/1N00-ZjxHkjoWNIsnoTtza9CUHrxm8-e54298DXLuD94
+ */
+export interface HardwareDescription {
+  fileVersion: string;
+  assembly?: Assembly;
+  device: HardwareDevice;
+}
+
+export function getIdFromHardwareDescription(hd: HardwareDescription): string {
+  return hd.assembly
+    ? hd.assembly.id
+    : hd.device.id;
+}
+
+export function getApiIdentifierFromHardwareDescription(hd: HardwareDescription, skipKeyId = false): string {
+  let apiId = hd.assembly
+    ? `${hd.assembly.id}-${hd.assembly.version}`
+    : `${hd.device.id}-${hd.device.version}`;
+
+  if (!skipKeyId && hd.device.keyId) {
+    apiId += `-${hd.device.keyId}`;
+  }
+
+  return apiId;
+}
+
+export function getNameFromHardwareDescription(hd: HardwareDescription): string {
+  return hd.assembly
+    ? hd.assembly.name
+    : hd.device.name;
+}
+
+export function getSerialNumberFromHardwareDescription(hd: HardwareDescription): string {
+  return hd.assembly
+    ? hd.assembly.serialNumber
+    : hd.device.serialNumber;
+}
+
+export function getAllComponentsFromHardwareDescription(hd: HardwareDescription): HardwareComponent[] {
+  return hd.assembly
+    ? [...hd.assembly.components, ...hd.device.components]
+    : hd.device.components;
+}
+
+export function hardwareComponentsMatch(a: HardwareComponent[], b: HardwareComponent[]): boolean {
+  if (a.length === 0 && b.length === 0) {
+    return false; // edge case: when both components are empty they don't match since there are no components to compare
+  }
+
+  const ac = a.map((c) => `${c.name}-${c.version[0]}`.replace(/\s/g, '').toLocaleLowerCase()).sort();
+  const bc = b.map((c) => `${c.name}-${c.version[0]}`.replace(/\s/g, '').toLocaleLowerCase()).sort();
+
+  return isEqual(ac, bc);
+}
+
+export function isHardwareDescriptionCompatibleWithPackageFilename(hardwareDescription: HardwareDescription, packageFilename: string): boolean {
+  const hdApiId = getApiIdentifierFromHardwareDescription(hardwareDescription);
+  const pfApiId = getApiIdentifierFromPackageFilename(packageFilename);
+
+  if (hdApiId && pfApiId) {
+    return hdApiId === pfApiId;
+  } else {
+    const pfComponents = getHardwareComponentsFromPackageFilename(packageFilename);
+    const hdComponents = getAllComponentsFromHardwareDescription(hardwareDescription);
+    return hardwareComponentsMatch(pfComponents, hdComponents);
+  }
+}
+
+export function getHardwareComponentsFromPackageFilename(packageFilename: string): HardwareComponent[] {
+  if (packageFilename.match(/_Com[^_]+_Core[^_]+_Drive/g)) {
+    return packageFilename.split('_').slice(1, 4).map((b) => { // ['ComEtherCAT-b', 'CoreC2X-a', 'Drive400-d']
+      const p = b.split('-'); // ['ComEtherCAT', 'b']
+      return {
+        name: p[0],
+        serialNumber: '',
+        version: p[1],
+      } as HardwareComponent;
+    });
+  } else {
+    // not all package filenames have components,
+    // e.g. 'package_SOMANET-Servo-Node-Circulo-1800_circulo1800_motion-drive_v4.2.0-beta.5.zip'
+    return [];
+  }
+}
+
+export function getVersionFromPackageFilename(packageFilename: string) {
+  const parts = packageFilename.split('_');
+  const version = parts[parts.length - 1].replace(/\.zip$/, '').split(/\s+/)[0];
+  return semver.valid(version) ? version : undefined;
+}
+
+export function getApiIdentifierFromPackageFilename(packageFilename: string) {
+  if (packageFilename.match(/_Com[^_]+_Core[^_]+_Drive/g)) {
+    return undefined;
+  }
+  const [, , apiIdentifier] = packageFilename.split('_');
+  return apiIdentifier;
+}

package/src/lib/logger.ts

@@ -0,0 +1,5 @@
+import { Roarr } from 'roarr';
+
+export const logger = Roarr.child({
+  package: '@synapticon/motion-master-client'
+});

package/src/lib/monitoring-config.ts

@@ -0,0 +1,6 @@
+export interface MonitoringConfig {
+  readonly bufferSize?: number;
+  readonly distinct?: boolean;
+  readonly messageId?: string;
+  readonly topic: string;
+}

package/src/lib/{monitoring-entry.d.ts → monitoring-entry.ts}

@@ -1,9 +1,10 @@
-import { Observable } from "rxjs";
-import { MonitoringConfig } from "./monitoring-config";
-import { MotionMasterMessage, ParameterValueType } from "./types";
-export interface MonitoringEntry {
-    config: Required<MonitoringConfig>;
-    interval: number;
-    values$: Observable<ParameterValueType[]>;
-    parameters: MotionMasterMessage.Request.GetDeviceParameterValues.IParameter[];
-}
+import { Observable } from "rxjs";
+import { MonitoringConfig } from "./monitoring-config";
+import { MotionMasterMessage, ParameterValueType } from "./types";
+
+export interface MonitoringEntry {
+  config: Required<MonitoringConfig>;
+  interval: number;
+  values$: Observable<ParameterValueType[]>;
+  parameters: MotionMasterMessage.Request.GetDeviceParameterValues.IParameter[];
+}

package/src/lib/motion-master-client.ts

@@ -0,0 +1,266 @@
+import { combineLatest, defer, distinctUntilChanged, filter, first, firstValueFrom, map, mergeMap, Observable, Subscription, timeout } from "rxjs";
+import { v4 } from "uuid";
+import { MonitoringConfig } from "./monitoring-config";
+import { MotionMasterPubSubClient } from "./motion-master-pub-sub-client";
+import { MotionMasterPubSubSocket } from "./motion-master-pub-sub-socket";
+import { MotionMasterPubSubWebSocket } from "./motion-master-pub-sub-web-socket";
+import { MotionMasterReqResClient } from "./motion-master-req-res-client";
+import { MotionMasterReqResSocket } from "./motion-master-req-res-socket";
+import { MotionMasterReqResWebSocket } from "./motion-master-req-res-web-socket";
+import { mapMonitoringParameterValuesStatusMessageToDeviceParameters, mapMonitoringParameterValuesStatusMessageToParameterValues, selectMotionMasterMessageByTopic } from "./operators";
+import { DeviceParameterIds, DeviceRef, MotionMasterMessage, ParameterValueType } from "./types";
+import { DeviceParameter } from "./device-parameter";
+
+export function createMotionMasterClient(hostname: string) {
+  const reqResSocket = new MotionMasterReqResWebSocket();
+  const pubSubSocket = new MotionMasterPubSubWebSocket();
+
+  const client = new MotionMasterClient(reqResSocket, pubSubSocket);
+
+  const clientId = v4();
+  reqResSocket.open(`ws://${hostname}:63524?clientId=${clientId}`);
+  pubSubSocket.open(`ws://${hostname}:63525?clientId=${clientId}`);
+
+  return client;
+}
+
+export class MotionMasterClient {
+
+  readonly request: MotionMasterReqResClient;
+  readonly monitor: MotionMasterPubSubClient;
+
+  private systemEventSubscription?: Subscription;
+
+  constructor(
+    readonly reqResSocket: MotionMasterReqResSocket,
+    readonly pubSubSocket: MotionMasterPubSubSocket,
+  ) {
+    this.request = new MotionMasterReqResClient(this.reqResSocket);
+    this.monitor = new MotionMasterPubSubClient(this.pubSubSocket);
+
+    this.subscribeToSystemEvent();
+  }
+
+  /**
+   * This observable will emit true when both req/res and pub/sub sockets are opened.
+   * If any socket gets closed, this observable will emit false.
+   * This is a hot observable that will on subscription emit the last value of sockets opened.
+   */
+  socketsOpened$ = combineLatest([this.reqResSocket.opened$, this.pubSubSocket.opened$]).pipe(
+    map(([reqResSocketOpened, pubSubSocketOpened]) => reqResSocketOpened && pubSubSocketOpened),
+  );
+
+  /**
+   * Client is ready when both req/res and pub/sub sockets are opened.
+   * This observable will emit whenever the sockets opened property changes to true.
+   */
+  ready$ = this.socketsOpened$.pipe(
+    filter(Boolean),
+  );
+
+  /**
+   * This observable will emit only once when both req/res and pub/sub sockets are opened.
+   * NOTE: This observable might never emit and it doesn't timeout.
+   */
+  onceReady$ = this.ready$.pipe(
+    first(),
+  );
+
+  /**
+   * Client is ready when both req/res and pub/sub sockets are opened.
+   * If both sockets are already opened, this function will immediately resolve to true.
+   * Otherwise, it will wait up to requestTimeout for both sockets to open, or throw an error.
+   */
+  whenReady(requestTimeout = 5000): Promise<true> {
+    return firstValueFrom(
+      this.ready$.pipe(
+        timeout(requestTimeout),
+      ),
+    );
+  }
+
+  startMonitoring(
+    ids: DeviceParameterIds,
+    monitoringInterval: number,
+    config?: MonitoringConfig,
+    requestTimeout = 5000,
+  ): Observable<ParameterValueType[]> {
+    return defer(() => {
+      const topic = config?.topic ?? v4();
+      const messageId = config?.messageId ?? v4();
+
+      if (!config) {
+        config = { messageId, topic, bufferSize: 1, distinct: false };
+      }
+
+      this.request.resolveGetParameterValuesIds(ids).pipe(
+        mergeMap((refs) => {
+          if ((new Set(refs.map(([deviceAddress]) => deviceAddress))).size !== 1) {
+            throw new Error('Start monitoring only supports a single device');
+          }
+
+          // Skipping write-only (wo) parameters is necessary because Motion Master does not initiate monitoring when the requested list contains such parameters.
+          // For now, this serves as a temporary solution until Motion Master is fixed.
+          refs = refs.filter(([, index]) => index !== 0x1024);
+
+          const deviceAddress = refs[0][0];
+
+          const props: MotionMasterMessage.Request.IStartMonitoringDeviceParameterValues = {
+            getDeviceParameterValues: {
+              deviceAddress,
+              parameters: refs.map(([, index, subindex]) => ({ index, subindex, loadFromCache: false })),
+              sendProgress: false,
+            },
+            interval: monitoringInterval,
+            topic,
+          };
+
+          return this.request.startMonitoringDeviceParameterValues(props, requestTimeout, messageId);
+        }),
+      ).subscribe();
+
+      this.monitor.subscribe(config);
+
+      const values$ = this.monitor.socket.data$.pipe(
+        selectMotionMasterMessageByTopic(config.topic),
+        mapMonitoringParameterValuesStatusMessageToParameterValues(),
+      );
+
+      return new Observable<ParameterValueType[]>((subscriber) => {
+        const subscription = values$.subscribe(subscriber);
+        return () => {
+          subscription.unsubscribe();
+          this.stopMonitoring(messageId);
+        };
+      });
+    });
+  }
+
+  /**
+   * TODO: return device parameters instead of just parameters
+   * get parameters from ESI uprfront, and then when parameters are received
+   * from motion master just concatenate (spread operator) props from ESI and props from parameter
+   * assign device parameter id like 0x1018:00.12345
+   * when assembling device parameter, get parameter from device in ESI based on product code, see ESI service
+   * this should probably done for other get parameters functions, get ESI file from device or prepared, get data from it
+   */
+  startMonitoringDeviceParameters(
+    ids: DeviceParameterIds,
+    monitoringInterval: number,
+    config?: MonitoringConfig,
+    requestTimeout = 5000,
+  ): Observable<DeviceParameter[]> {
+    return defer(() => {
+      const topic = config?.topic ?? v4();
+      const messageId = config?.messageId ?? v4();
+
+      if (!config) {
+        config = { messageId, topic, bufferSize: 1, distinct: false };
+      }
+
+      this.request.resolveGetParameterValuesIds(ids).pipe(
+        mergeMap((refs) => {
+          if ((new Set(refs.map(([deviceAddress]) => deviceAddress))).size !== 1) {
+            throw new Error('Start monitoring only supports a single device');
+          }
+
+          // Skipping write-only (wo) parameters is necessary because Motion Master does not initiate monitoring when the requested list contains such parameters.
+          // For now, this serves as a temporary solution until Motion Master is fixed.
+          refs = refs.filter(([, index]) => index !== 0x1024);
+
+          const deviceAddress = refs[0][0];
+
+          const props: MotionMasterMessage.Request.IStartMonitoringDeviceParameterValues = {
+            getDeviceParameterValues: {
+              deviceAddress,
+              parameters: refs.map(([, index, subindex]) => ({ index, subindex, loadFromCache: false })),
+              sendProgress: false,
+            },
+            interval: monitoringInterval,
+            topic,
+          };
+
+          return this.request.startMonitoringDeviceParameterValues(props, requestTimeout, messageId);
+        }),
+      ).subscribe();
+
+      this.monitor.subscribe(config);
+
+      const values$ = this.monitor.socket.data$.pipe(
+        selectMotionMasterMessageByTopic(config.topic),
+        mapMonitoringParameterValuesStatusMessageToDeviceParameters(this.request),
+      );
+
+      return new Observable<DeviceParameter[]>((subscriber) => {
+        const subscription = values$.subscribe(subscriber);
+        return () => {
+          subscription.unsubscribe();
+          this.stopMonitoring(messageId);
+        };
+      });
+    });
+  }
+
+  startMonitoringValue<T extends ParameterValueType = number>(
+    id: string | [DeviceRef, number, number],
+    monitoringInterval: number,
+    config?: MonitoringConfig,
+    requestTimeout = 5000,
+  ): Observable<T> {
+    const ids = typeof id === 'string' ? [id] : [id];
+    return this.startMonitoring(ids, monitoringInterval, config, requestTimeout).pipe(
+      map((parameters) => (parameters[0] ?? 0) as T),
+    );
+  }
+
+  trackTargetReached(deviceRef: DeviceRef, monitoringInterval = 20): Observable<boolean> {
+    return this.startMonitoringValue([deviceRef, 0x6041, 0], monitoringInterval).pipe(
+      map((value) => (value & 0x0400) > 0), // tr = target reached bit
+      distinctUntilChanged(),
+    );
+  }
+
+  waitUntilTargetReached(deviceRef: DeviceRef, monitoringInterval = 20): Observable<true> {
+    return this.trackTargetReached(deviceRef, monitoringInterval).pipe(
+      filter(Boolean),
+      first(),
+    );
+  }
+
+  whenTargetReached(deviceRef: DeviceRef, monitoringInterval = 20): Promise<true> {
+    return firstValueFrom(this.waitUntilTargetReached(deviceRef, monitoringInterval));
+  }
+
+  subscribeToSystemEvent() {
+    this.systemEventSubscription = this.monitor.systemEvent$.subscribe(systemEvent => {
+      if (systemEvent.state === MotionMasterMessage.Status.SystemEvent.State.DEINITIALIZING) {
+        this.request.clearDevicesInformation();
+      }
+    });
+  }
+
+  stopMonitoring(messageId: string): void {
+    this.request.stopMonitoringDeviceParameterValues({ startMonitoringRequestId: messageId });
+    this.monitor.unsubscribe(messageId);
+  }
+
+  stopMonitoringAll(): void {
+    this.monitor.messageIds.forEach(this.stopMonitoring);
+  }
+
+  closeSockets() {
+    this.systemEventSubscription?.unsubscribe();
+    this.request.clearDevicesInformation();
+
+    this.reqResSocket.close();
+    this.pubSubSocket.close();
+  }
+
+  reopenSockets() {
+    this.reqResSocket.reopen();
+    this.pubSubSocket.reopen();
+
+    this.subscribeToSystemEvent();
+  }
+
+}

package/src/lib/motion-master-pub-sub-client.ts

@@ -0,0 +1,100 @@
+import { bufferCount, distinctUntilChanged, filter, map, Observable, Subject, Subscription } from "rxjs";
+import { v4 } from "uuid";
+import { MonitoringConfig } from "./monitoring-config";
+import { MotionMasterPubSubSocket } from "./motion-master-pub-sub-socket";
+import { selectMotionMasterMessageByTopic, selectMotionMasterMessageStatusByKey } from "./operators";
+import { IMotionMasterMessage, MotionMasterMessage } from "./types";
+import * as equal from "fast-deep-equal";
+import { MotionMasterPubSubWorkerSocket } from "./motion-master-pub-sub-worker-socket";
+
+export class MotionMasterPubSubClient {
+
+  readonly data$ = new Subject<[string, IMotionMasterMessage[]]>();
+
+  private subscriptions = new Map<string, Subscription>();
+
+  readonly notification$ = this.socket.data$.pipe(
+    selectMotionMasterMessageByTopic('notification'),
+  );
+
+  readonly systemEvent$ = this.notification$.pipe(
+    selectMotionMasterMessageStatusByKey<MotionMasterMessage.Status.ISystemEvent>('systemEvent'),
+  );
+
+  readonly deviceEvent$ = this.notification$.pipe(
+    selectMotionMasterMessageStatusByKey<MotionMasterMessage.Status.IDeviceEvent>('deviceEvent'),
+  );
+
+  constructor(
+    public readonly socket: MotionMasterPubSubSocket,
+  ) { }
+
+  get messageIds(): string[] {
+    return Array.from(this.subscriptions.keys());
+  }
+
+  subscribe(config: MonitoringConfig): string {
+    const messageId = config.messageId ?? v4();
+    if (!config.messageId) {
+      config = { ...config, messageId };
+    }
+
+    if (this.socket instanceof MotionMasterPubSubWorkerSocket) {
+      this.socket.worker.postMessage({ subscribe: config });
+    } else {
+      const { bufferSize = 1, distinct = false, topic } = config;
+
+      let observable: Observable<IMotionMasterMessage> = this.socket.data$.pipe(
+        filter((data) => data[0] === topic),
+        map((data) => data[1]),
+      );
+
+      if (distinct) {
+        observable = observable.pipe(
+          distinctUntilChanged((prev, curr) => {
+            if (prev?.status?.monitoringParameterValues?.deviceParameterValues?.parameterValues
+              && curr?.status?.monitoringParameterValues?.deviceParameterValues?.parameterValues) {
+              return equal(
+                prev.status.monitoringParameterValues.deviceParameterValues.parameterValues,
+                curr.status.monitoringParameterValues.deviceParameterValues.parameterValues,
+              )
+            }
+            return false;
+          }),
+        );
+      }
+
+      const subscription = observable.pipe(
+        bufferCount(bufferSize),
+      ).subscribe((data) => {
+        this.data$.next([topic, data]);
+      });
+
+      this.subscriptions.set(messageId, subscription);
+    }
+
+    return messageId;
+  }
+
+  unsubscribe(messageId: string): void {
+    if (this.socket instanceof MotionMasterPubSubWorkerSocket) {
+      this.socket.worker.postMessage({ unsubcribe: { messageId } });
+    } else {
+      const subscription = this.subscriptions.get(messageId);
+      if (subscription) {
+        subscription.unsubscribe();
+        this.subscriptions.delete(messageId);
+      }
+    }
+  }
+
+  unsubscribeAll(): void {
+    if (this.socket instanceof MotionMasterPubSubWorkerSocket) {
+      this.socket.worker.postMessage({ unsubscribeAll: true });
+    } else {
+      this.subscriptions.forEach((subscription) => subscription.unsubscribe());
+      this.subscriptions.clear();
+    }
+  }
+
+}

package/src/lib/motion-master-pub-sub-socket.ts

@@ -0,0 +1,46 @@
+import { BehaviorSubject, Observable } from "rxjs";
+import { IMotionMasterMessage } from "./types";
+
+export interface MotionMasterPubSubSocket {
+  /**
+   * Emits a boolean value when socket gets opened or closed.
+   */
+  readonly opened$: BehaviorSubject<boolean>;
+
+  /**
+   * Emits close events with code and reason data.
+   * @link https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close_event
+   */
+  readonly close$: Observable<{ code: number; reason: string; }>
+
+  /**
+   * Incoming data is a tuple of topic and decoded message.
+   */
+  readonly data$: Observable<[string, IMotionMasterMessage]>;
+
+  /**
+   * URL set in call to open.
+   */
+  get url(): string | undefined;
+
+  /**
+   * Open socket.
+   *
+   * The connected$ and eventually alive$ observables will emit true values.
+   */
+  open(url: string): void;
+
+  /**
+   * Reopen socket.
+   *
+   * Reopen if closed using the same url previously set in open.
+   */
+  reopen(): void;
+
+  /**
+   * Close socket.
+   *
+   * The opened$ and alive$ observables will emit false values.
+   */
+  close(): void;
+}

package/src/lib/motion-master-pub-sub-web-socket.ts

@@ -0,0 +1,77 @@
+import { BehaviorSubject, Subject } from "rxjs";
+import { webSocket, WebSocketSubject, WebSocketSubjectConfig } from "rxjs/webSocket";
+import { logger } from "./logger";
+import { MotionMasterPubSubSocket } from "./motion-master-pub-sub-socket";
+import { IMotionMasterMessage, MotionMasterMessage } from "./types";
+import { createPlainObjectFromMotionMasterMessage } from "./util";
+
+export class MotionMasterPubSubWebSocket implements MotionMasterPubSubSocket {
+
+  readonly opened$ = new BehaviorSubject<boolean>(false);
+
+  readonly close$ = new Subject<{ code: number; reason: string; }>();
+
+  readonly data$ = new Subject<[string, IMotionMasterMessage]>();
+
+  private webSocket$?: WebSocketSubject<[string, IMotionMasterMessage]>;
+
+  private _url?: string;
+
+  get url(): string | undefined {
+    return this._url;
+  }
+
+  open(url: string): void {
+    this._url = url;
+
+    this.webSocket$ = this.createWebSocket(url);
+
+    this.webSocket$.subscribe({
+      next: (value) => this.data$.next(value),
+      error: () => {
+        // ignore, clients will receive close$ event instead
+      },
+    });
+  }
+
+  close(): void {
+    this.webSocket$?.complete();
+  }
+
+  reopen() {
+    if (this.url && this.opened$.value === false) {
+      this.open(this.url);
+    }
+  }
+
+  private createWebSocket(url: string) {
+    const decoder = new TextDecoder('utf-8');
+
+    const webSocketConfig: WebSocketSubjectConfig<[string, IMotionMasterMessage]> = {
+      binaryType: 'arraybuffer',
+      closeObserver: {
+        next: (ev: CloseEvent) => {
+          this.opened$.next(false);
+          this.close$.next({ code: ev.code, reason: ev.reason });
+          logger.info(`Connection closed ${url}`);
+        },
+      },
+      deserializer: (e: MessageEvent<ArrayBuffer>): [string, IMotionMasterMessage] => {
+        const end = new Uint8Array(e.data, 0, 1)[0] + 1;
+        const topic = decoder.decode(e.data.slice(1, end)); // topic starts from the 2nd byte
+        const message = MotionMasterMessage.decode(new Uint8Array(e.data.slice(end)));
+        return [topic, createPlainObjectFromMotionMasterMessage(message)];
+      },
+      openObserver: {
+        next: () => {
+          this.opened$.next(true);
+          logger.info(`Connection opened ${url}`);
+        },
+      },
+      url,
+    };
+
+    return webSocket(webSocketConfig);
+  }
+
+}