motion-master-client 0.0.1 → 0.0.2

package/package.json

@@ -1,9 +1,6 @@
-{
-  "name": "motion-master-client",
-  "version": "0.0.1",
-  "type": "module",
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts",
-  "dependencies": {},
-  "peerDependencies": {}
-}
+{
+  "name": "motion-master-client",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "A library and CLI program used for communicating with Motion Master."
+}

package/src/{index.d.ts → index.ts}

@@ -1,4 +1,5 @@
 export * from './lib/device-log-line';
+export * from './lib/device-parameter';
 export * from './lib/hardware-description';
 export * from './lib/monitoring-config';
 export * from './lib/monitoring-entry';

package/src/lib/device-log-line.ts

@@ -0,0 +1,5 @@
+export interface DeviceLogLine {
+  time: string;
+  level: string;
+  message: string;
+}

package/src/lib/device-parameter.spec.ts

@@ -0,0 +1,85 @@
+import { makeDeviceParameterId, splitDeviceParameterId } from "./device-parameter";
+
+describe('deviceParameter', () => {
+
+  describe('makeDeviceParameterId', () => {
+
+    const serialNumber = '8502-03-0001353-2115';
+
+    test.each<[string, [(number | null | undefined), (number | null | undefined)], string]>([
+      [serialNumber, [0x1234, 123], '0x1234:7B.8502-03-0001353-2115'],
+      [serialNumber, [23, 23], '0x0017:17.8502-03-0001353-2115'],
+      [serialNumber, [0, 0], '0x0000:00.8502-03-0001353-2115'],
+      [serialNumber, [0x2000, undefined], '0x2000:00.8502-03-0001353-2115'],
+      [serialNumber, [0x2003, null], '0x2003:00.8502-03-0001353-2115'],
+      [serialNumber, [0x10000, 3], '0x00010000:03.8502-03-0001353-2115'],
+      [serialNumber, [0x100F0, undefined], '0x000100F0:00.8502-03-0001353-2115'],
+    ])('should for device serial number "%s" and tuple %j return "%s"', (serialNumber, tuple, expected) => {
+      const result = makeDeviceParameterId(serialNumber, tuple);
+
+      expect(result).toBe(expected);
+    });
+
+    test.each([
+      [serialNumber, {}, '0x0000:00.8502-03-0001353-2115'],
+      [serialNumber, { index: 0x2004, subindex: 4 }, '0x2004:04.8502-03-0001353-2115'],
+      [serialNumber, { index: 0x1024 }, '0x1024:00.8502-03-0001353-2115'],
+    ])('should for device serial number "%s" and parameter %j return "%s"', (serialNumber, parameter, expected) => {
+      const result = makeDeviceParameterId(serialNumber, parameter);
+
+      expect(result).toBe(expected);
+    });
+
+    test.each([
+      [serialNumber, 0x1234, 123, '0x1234:7B.8502-03-0001353-2115'],
+      [serialNumber, 23, 23, '0x0017:17.8502-03-0001353-2115'],
+      [serialNumber, 0, 0, '0x0000:00.8502-03-0001353-2115'],
+      [serialNumber, 0x2000, undefined, '0x2000:00.8502-03-0001353-2115'],
+      [serialNumber, 0x2003, null, '0x2003:00.8502-03-0001353-2115'],
+      [serialNumber, 0x10000, 3, '0x00010000:03.8502-03-0001353-2115'],
+      [serialNumber, 0x100F0, undefined, '0x000100F0:00.8502-03-0001353-2115'],
+    ])('should for device serial number "%s" and index %d and subindex %d return "%s"', (serialNumber, index, subindex, expected) => {
+      const result = makeDeviceParameterId(serialNumber, index, subindex);
+
+      expect(result).toBe(expected);
+    });
+
+    it('should throw if index is less than 0', () => {
+      expect(() => {
+        makeDeviceParameterId(serialNumber, -123, 0);
+      }).toThrow();
+    });
+
+    it('should throw if subindex is less than 0', () => {
+      expect(() => {
+        makeDeviceParameterId(serialNumber, 0x1024, -3);
+      }).toThrow();
+    });
+
+  });
+
+  describe('splitDeviceParameterId', () => {
+
+    test.each([
+      ['0x1234:7B.8502-03-0001353-2115', ['8502-03-0001353-2115', 4660, 123]],
+      ['0x000100F0:00.8502-03-0001353-2115', ['8502-03-0001353-2115', 65776, 0]],
+    ])('should for id "%s" return tuple %j', (id, expected) => {
+      const result = splitDeviceParameterId(id);
+
+      expect(result).toEqual(expected);
+    });
+
+    test.each([
+      ['0x12:7B.8502-03-0001353-2115'],
+      ['0x1234:F.8502-03-0001353-2115'],
+      ['0x1234:FG.8502-03-0001353-2115'],
+      ['0x1234:7B.8502-03-ABC1353-2115'],
+      ['0x1234:7B.8502_03_0001353_2115'],
+      ['0x1H34:7B.8502-03-0001353-2115'],
+    ])('should throw error for id "%s"', (id) => {
+      expect(() => splitDeviceParameterId(id)).toThrow();
+    });
+
+  });
+
+});

package/src/lib/device-parameter.ts

@@ -0,0 +1,69 @@
+import { makeParameterId, Parameter } from "./parameter";
+
+export interface DeviceParameter extends Parameter {
+  id: string;
+}
+
+/**
+ * Make device parameter id by providing a device serial number and tuple of index and subindex.
+ *
+ * @param serialNumber - device serial number from the hardware description file
+ * @param tuple - an array of index and subindex
+ * @throws {Error} if index or subindex are less than 0
+ * @returns combined index and subindex in uppercase hexadecimal format, e.g. "0x60FE:02"
+ */
+export function makeDeviceParameterId(serialNumber: string, tuple: [(number | null | undefined), (number | null | undefined)]): string;
+
+/**
+ * Make device parameter id by providing a device serial number and object which has index and subindex properties.
+ *
+ * @param serialNumber - device serial number from the hardware description file
+ * @param parameter - an object with optional index and subindex properties
+ * @throws {Error} if index or subindex are less than 0
+ * @returns combined index and subindex in uppercase hexadecimal format, e.g. "0x60FE:02"
+ */
+export function makeDeviceParameterId(serialNumber: string, parameter: { index?: (number | null), subindex?: (number | null) }): string;
+
+/**
+ * Make parameter id by providing a device serial number and index and subindex.
+ *
+ * @param serialNumber - device serial number from the hardware description file
+ * @param index - from 0x0000 to 0xFFFF for objects defined in ESI and >0xFFFF for custom object
+ * @param subindex - defaults to 0 if not provided
+ * @throws {Error} if index or subindex are less than 0
+ * @returns combined index and subindex in uppercase hexadecimal format, e.g. "0x60FE:02"
+ */
+export function makeDeviceParameterId(serialNumber: string, index?: (number | null), subindex?: (number | null)): string;
+
+export function makeDeviceParameterId(serialNumber: string, a?: (number | null) | { index?: (number | null), subindex?: (number | null) } | [(number | null | undefined), (number | null | undefined)], b?: (number | null)): string {
+  const parameterId = makeParameterId(a, b);
+  return `${parameterId}.${serialNumber}`;
+}
+
+/**
+ * Example of device parameter id is "0x2110:1A.8502-03-0001353-2115" where:
+ * - 0x2110 is object index in hexadecimal format
+ * - 1A is subindex in hexadecimal format
+ * - 8502-03-0001353-2115 is device serial number from hardware description file
+ */
+export const deviceParameterIdRegExp = /^0x([0-9a-fA-F]{4,}):([0-9a-fA-F]{2})\.([\d-]+)$/;
+
+/**
+ * Split device parameter id into parts.
+ *
+ * @param id - device parameter id like "0x2110:1A.8502-03-0001353-2115"
+ * @returns tuple of device serial number, index, and subindex
+ */
+export function splitDeviceParameterId(id: string): [string, number, number] {
+  const match = id.match(deviceParameterIdRegExp);
+
+  if (!match) {
+    throw new Error(`Device parameter id "${id}" doesn't match the regular expression: ${deviceParameterIdRegExp}`);
+  }
+
+  return [
+    match[3], // device serial number
+    parseInt(match[1], 16), // index
+    parseInt(match[2], 16), // subindex
+  ];
+}

package/src/lib/hardware-description.spec.ts

@@ -0,0 +1,223 @@
+import {
+  getAllComponentsFromHardwareDescription,
+  getApiIdentifierFromHardwareDescription,
+  getNameFromHardwareDescription,
+  getSerialNumberFromHardwareDescription,
+  hardwareComponentsMatch,
+  HardwareDescription,
+} from './hardware-description';
+
+describe('getApiIdentifierFromHardwareDescription', () => {
+  it('should return api identifier from assembly', () => {
+    const result = getApiIdentifierFromHardwareDescription({
+      assembly: { id: 'foo', version: '01', serialNumber: 'foo-sn' }, // prefer assembly over device
+      device: { id: 'bar', version: '02', serialNumber: 'bar-sn' },
+      fileVersion: '',
+    } as HardwareDescription);
+
+    expect(result).toBe('foo-01');
+  });
+
+  it('should return api identifier from device', () => {
+    const result = getApiIdentifierFromHardwareDescription({
+      device: { id: 'bar', version: '02', serialNumber: 'bar-sn' },
+      fileVersion: '',
+    } as HardwareDescription);
+
+    expect(result).toBe('bar-02');
+  });
+});
+
+describe('getNameFromHardwareDescription', () => {
+  it('should return name from assembly', () => {
+    const result = getNameFromHardwareDescription({
+      assembly: { id: 'foo', version: '01', serialNumber: 'foo-sn', name: 'Assembly' }, // prefer assembly over device
+      device: { id: 'bar', version: '02', serialNumber: 'bar-sn', name: 'Device' },
+      fileVersion: '',
+    } as HardwareDescription);
+
+    expect(result).toBe('Assembly');
+  });
+
+  it('should return name from device', () => {
+    const result = getNameFromHardwareDescription({
+      device: { id: 'bar', version: '02', serialNumber: 'bar-sn', name: 'Device' },
+      fileVersion: '',
+    } as HardwareDescription);
+
+    expect(result).toBe('Device');
+  });
+});
+
+describe('getSerialNumberFromHardwareDescription', () => {
+  it('should return serial number from assembly', () => {
+    const result = getSerialNumberFromHardwareDescription({
+      assembly: { id: 'foo', version: '01', serialNumber: 'foo-sn' }, // prefer assembly over device
+      device: { id: 'bar', version: '02', serialNumber: 'bar-sn' },
+      fileVersion: '',
+    } as HardwareDescription);
+
+    expect(result).toBe('foo-sn');
+  });
+
+  it('should return serial number from device', () => {
+    const result = getSerialNumberFromHardwareDescription({
+      device: { id: 'bar', version: '02', serialNumber: 'bar-sn' },
+      fileVersion: '',
+    } as HardwareDescription);
+
+    expect(result).toBe('bar-sn');
+  });
+});
+
+describe('getAllComponentsFromHardwareDescription', () => {
+  it('should return components only from device when assembly is undefined', () => {
+    const deviceComponents = [
+      {
+        name: 'Com EtherCAT',
+        serialNumber: '3333-33-3333333-3333',
+        version: 'B.2',
+      },
+      {
+        name: 'Core C2X',
+        serialNumber: '1111-11-1111111-1111',
+        version: 'A.5',
+      },
+      {
+        name: 'Drive 400',
+        serialNumber: '2222-22-2222222-2222',
+        version: 'E.1',
+      },
+    ];
+
+    const hardwareDescription: HardwareDescription = {
+      device: {
+        components: deviceComponents,
+        id: '8503',
+        macAddress: '01-23-45-67-89-AB',
+        name: 'Circulo 9 1800 Encoder Pos 1 & 2',
+        serialNumber: '8506-01-040595-4023',
+        version: '02',
+      },
+      fileVersion: '1.0.0',
+    };
+
+    const result = getAllComponentsFromHardwareDescription(hardwareDescription);
+
+    expect(result).toEqual(deviceComponents);
+  });
+
+  it('should return combined components from assembly and device', () => {
+    const assemblyComponents = [
+      {
+        name: 'Heidrive HMP04',
+        serialNumber: '79137447',
+        version: 'REV-2',
+      },
+      {
+        name: 'KEB gearbox',
+        serialNumber: '12344234',
+        version: 'REV-3',
+      },
+    ];
+
+    const deviceComponents = [
+      {
+        name: 'Com EtherCAT',
+        serialNumber: '3333-33-3333333-3333',
+        version: 'B.2',
+      },
+      {
+        name: 'Core C2X',
+        serialNumber: '1111-11-1111111-1111',
+        version: 'A.5',
+      },
+      {
+        name: 'Drive 400',
+        serialNumber: '2222-22-2222222-2222',
+        version: 'E.1',
+      },
+    ];
+
+    const hardwareDescription: HardwareDescription = {
+      assembly: {
+        components: assemblyComponents,
+        id: 'ASM',
+        name: 'Assembly',
+        serialNumber: '12345',
+        version: '01',
+      },
+      device: {
+        components: deviceComponents,
+        id: '8503',
+        macAddress: '01-23-45-67-89-AB',
+        name: 'Circulo 9 1800 Encoder Pos 1 & 2',
+        serialNumber: '8506-01-040595-4023',
+        version: '02',
+      },
+      fileVersion: '1.0.0',
+    };
+
+    const result = getAllComponentsFromHardwareDescription(hardwareDescription);
+
+    expect(result).toEqual([...assemblyComponents, ...deviceComponents]);
+  });
+});
+
+describe('hardwareComponentsMatch', () => {
+  it('should return false when both arrays are empty', () => {
+    expect(hardwareComponentsMatch([], [])).toBe(false);
+  });
+
+  it('should return false when components don\'t match', () => {
+    const components1 = [
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'B.2' },
+      { name: 'Core C2X', serialNumber: '1111-11-1111111-1111', version: 'A.5' },
+    ];
+    const components2 = [
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'A.2' },
+      { name: 'Core C22', serialNumber: '1111-11-1111111-1111', version: 'A.1' },
+    ];
+
+    expect(hardwareComponentsMatch(components1, components2)).toBe(false);
+  });
+
+  it('should return true when components match', () => {
+    const components1 = [
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'B.2' },
+      { name: 'Core C2X', serialNumber: '1111-11-1111111-1111', version: 'A.5' },
+    ];
+    const components2 = [
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'B.2' },
+      { name: 'Core C2X', serialNumber: '1111-11-1111111-1111', version: 'A.5' },
+    ];
+
+    expect(hardwareComponentsMatch(components1, components2)).toBe(true);
+  });
+
+  it('should return true when components match but are not ordered the same', () => {
+    const components1 = [
+      { name: 'Core C2X', serialNumber: '1111-11-1111111-1111', version: 'A.5' },
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'B.2' },
+    ];
+    const components2 = [
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'B.2' },
+      { name: 'Core C2X', serialNumber: '1111-11-1111111-1111', version: 'A.5' },
+    ];
+
+    expect(hardwareComponentsMatch(components1, components2)).toBe(true);
+  });
+
+  it('should return true when revision numbers don\'t match', () => {
+    const components1 = [
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'B.2' },
+      { name: 'Core C2X', serialNumber: '1111-11-1111111-1111', version: 'A.5' },
+    ];
+    const components2 = [
+      { name: 'Com EtherCAT', serialNumber: '3333-33-3333333-3333', version: 'B.7' },
+      { name: 'Core C2X', serialNumber: '1111-11-1111111-1111', version: 'A.2' },
+    ];
+
+    expect(hardwareComponentsMatch(components1, components2)).toBe(true);
+  });
+});

package/src/lib/hardware-description.ts

@@ -0,0 +1,79 @@
+import { isEqual } from 'lodash';
+
+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;
+  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(hardwareDescription: HardwareDescription): string {
+  return hardwareDescription.assembly
+    ? hardwareDescription.assembly.id
+    : hardwareDescription.device.id;
+}
+
+export function getApiIdentifierFromHardwareDescription(hardwareDescription: HardwareDescription): string {
+  return hardwareDescription.assembly
+    ? `${hardwareDescription.assembly.id}-${hardwareDescription.assembly.version}`
+    : `${hardwareDescription.device.id}-${hardwareDescription.device.version}`;
+}
+
+export function getNameFromHardwareDescription(hardwareDescription: HardwareDescription): string {
+  return hardwareDescription.assembly
+    ? hardwareDescription.assembly.name
+    : hardwareDescription.device.name;
+}
+
+export function getSerialNumberFromHardwareDescription(hardwareDescription: HardwareDescription): string {
+  return hardwareDescription.assembly
+    ? hardwareDescription.assembly.serialNumber
+    : hardwareDescription.device.serialNumber;
+}
+
+export function getAllComponentsFromHardwareDescription(hardwareDescription: HardwareDescription): HardwareComponent[] {
+  if (hardwareDescription.assembly) {
+    return [...hardwareDescription.assembly.components, ...hardwareDescription.device.components];
+  } else {
+    return hardwareDescription.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);
+}

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.ts

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

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

@@ -0,0 +1,94 @@
+import { Observable } 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 { MotionMasterReqResClient } from "./motion-master-req-res-client";
+import { MotionMasterReqResSocket } from "./motion-master-req-res-socket";
+import { mapStatusMessageToParameterValues, selectMotionMasterMessageByTopic } from "./operators";
+import { MotionMasterMessage, ParameterAddress } from "./types";
+
+export class MotionMasterClient {
+
+  readonly request: MotionMasterReqResClient;
+  readonly monitor: MotionMasterPubSubClient;
+
+  constructor(
+    private readonly reqResSocket: MotionMasterReqResSocket,
+    private readonly pubSubSocket: MotionMasterPubSubSocket,
+  ) {
+    this.request = new MotionMasterReqResClient(this.reqResSocket);
+    this.monitor = new MotionMasterPubSubClient(this.pubSubSocket);
+  }
+
+  startMonitoringDeviceParameterValues(
+    deviceAddress: number,
+    parameters: MotionMasterMessage.Request.GetDeviceParameterValues.IParameter[],
+    interval: number,
+    config: MonitoringConfig,
+    requestTimeout = 5000,
+  ): [string, Observable<MotionMasterMessage>] {
+    const props: MotionMasterMessage.Request.IStartMonitoringDeviceParameterValues = {
+      interval,
+      topic: config.topic,
+      getDeviceParameterValues: { deviceAddress, parameters },
+    };
+
+    this.monitor.subscribe(config);
+
+    this.request.startMonitoringDeviceParameterValues(props, requestTimeout, config.messageId);
+
+    const message$ = this.monitor.socket.data$.pipe(
+      selectMotionMasterMessageByTopic(config.topic),
+    );
+
+    return [config.messageId, message$];
+  }
+
+  startMonitoringValues<T = number[]>(
+    deviceAddress: number,
+    parameterAddresses: ParameterAddress[],
+    interval: number,
+    config?: MonitoringConfig,
+    requestTimeout = 5000,
+  ): [string, Observable<T>] {
+    const parameters = parameterAddresses.map((addr) => ({ index: addr[0], subindex: addr[1], loadFromCache: false }));
+
+    if (!config) {
+      config = { messageId: v4(), topic: v4(), bufferSize: 1, distinct: false };
+    }
+
+    const [messageId, message$] = this.startMonitoringDeviceParameterValues(deviceAddress, parameters, interval, config, requestTimeout);
+
+    const values$ = message$.pipe(
+      mapStatusMessageToParameterValues(),
+    ) as unknown as Observable<T>;
+
+    return [messageId, values$];
+  }
+
+  startMonitoring<T = number[]>(
+    deviceAddress: number,
+    parameterAddresses: [number, number][],
+    interval: number,
+    config?: MonitoringConfig,
+    requestTimeout = 5000,
+  ): Observable<T> {
+    return new Observable<T>((subscriber) => {
+      const [messageId, values$] = this.startMonitoringValues<T>(deviceAddress, parameterAddresses, interval, config, requestTimeout);
+
+      const subscription = values$.subscribe(subscriber);
+
+      return () => {
+        subscription.unsubscribe();
+        this.stopMonitoring(messageId);
+      };
+    });
+  }
+
+  stopMonitoring(messageId: string): void {
+    this.request.stopMonitoringDeviceParameterValues({ startMonitoringRequestId: messageId });
+    this.monitor.unsubscribe(messageId);
+  }
+
+}