@zimo-elektronik/zcan 1.0.0

package/src/MX10.ts

@@ -0,0 +1,351 @@
+/* eslint-disable no-bitwise */
+
+import {Buffer} from 'buffer';
+import {interval, Subject} from 'rxjs';
+
+import {
+  AccessoryCommandGroup,
+  DataGroup,
+  FileControlGroup,
+  FileTransferGroup,
+  InfoGroup,
+  LanDataGroup,
+  LanInfoGroup,
+  LanNetworkGroup,
+  LanZimoProgrammableScriptGroup,
+  NetworkGroup,
+  PropertyConfigGroup,
+  RailwayControlGroup,
+  SystemControlGroup,
+  TrackCfgGroup,
+  TrainControlGroup,
+  VehicleGroup,
+  ZimoProgrammableScriptGroup,
+} from './zcan';
+import {
+  CreateSocketFunction,
+  NIDGenerator,
+  Socket,
+  ZcanDataArray,
+} from './@types/communication';
+import {delay} from './internal/utils';
+import ExtendedASCII from './util/extended-ascii';
+
+/**
+ *
+ * @category Entrypoint
+ */
+export default class MX10 {
+  myNID = 0;
+  mx10NID = 0;
+  mx10IP: string | undefined;
+  connected = false;
+
+  readonly systemControl = new SystemControlGroup(this);
+  readonly accessoryCommand = new AccessoryCommandGroup(this);
+  readonly vehicle = new VehicleGroup(this);
+  readonly trainControl = new TrainControlGroup(this);
+  readonly trackCfg = new TrackCfgGroup(this);
+  readonly data = new DataGroup(this);
+  readonly info = new InfoGroup(this);
+  readonly propertyConfig = new PropertyConfigGroup(this);
+  readonly network = new NetworkGroup(this);
+  readonly railwayControl = new RailwayControlGroup(this);
+  readonly zimoProgrammableScript = new ZimoProgrammableScriptGroup(this);
+  readonly fileControl = new FileControlGroup(this);
+  readonly fileTransfer = new FileTransferGroup(this);
+  readonly lanInfo = new LanInfoGroup(this);
+  readonly lanData = new LanDataGroup(this);
+  readonly lanNetwork = new LanNetworkGroup(this);
+  readonly lanZimoProgrammableScript = new LanZimoProgrammableScriptGroup(this);
+
+  readonly errors = new Subject<string>();
+
+  private mx10Socket: Socket | null = null;
+  private incomingPort = 14521;
+  private outgoingPort = 14520;
+
+  private lastPing = 0;
+  private interval: NodeJS.Timeout | undefined = undefined;
+
+  private readonly nidGeneratorFunction: NIDGenerator;
+  private readonly debugCommunication: boolean;
+  private readonly reconnectionTime: number = 0;
+
+  readonly connectionTimeout: number;
+
+  constructor(
+    nidGeneratorFunction: NIDGenerator,
+    connectionTimeout = 1000,
+    debugCommunication = false,
+  ) {
+    this.nidGeneratorFunction = nidGeneratorFunction;
+    this.connectionTimeout = connectionTimeout;
+    this.debugCommunication = debugCommunication;
+    this.reconnectionTime = connectionTimeout * 4;
+
+    const pingIntervalMs = 1000;
+
+    if (this.connected) {
+      this.network.ping();
+    }
+    interval(pingIntervalMs).subscribe(() => {
+      if (this.connected) {
+        this.network.ping();
+      }
+    });
+  }
+
+  async initSocket(
+    createSocketFunction: CreateSocketFunction,
+    ipAddress: string,
+    incomingPort = 14521,
+    outgoingPort = 14520,
+  ) {
+    this.mx10IP = ipAddress;
+    this.incomingPort = incomingPort;
+    this.outgoingPort = outgoingPort;
+
+    if (this.mx10Socket == null) {
+      const socket = (this.mx10Socket = createSocketFunction({
+        type: 'udp4',
+      }) as Socket);
+
+      await new Promise((resolve) => {
+        socket.bind(incomingPort, () => {
+          resolve(null);
+        });
+      });
+
+      this.mx10Socket.on('message', this.readRawData.bind(this));
+
+      this.myNID = await this.nidGeneratorFunction();
+      this.lanNetwork.portOpen();
+
+      await delay(this.connectionTimeout);
+
+      if (!this.connected) {
+        this.closeSocket();
+        throw new Error('mx10.connection.timeout');
+      }
+    }
+  }
+
+  reconnectLogic() {
+    const date = Date.now();
+    if (
+      date - this.lastPing < this.reconnectionTime &&
+      this.interval !== undefined
+    ) {
+      clearInterval(this.interval);
+      this.interval = undefined;
+    }
+
+    if (this.interval === undefined) {
+      this.interval = setInterval(() => {
+        if (!this.connected) {
+          // eslint-disable-next-line no-console
+          console.log('Reconnecting...');
+          this.network.portClose();
+          this.lanNetwork.portOpen();
+          this.network.ping(0b00);
+        }
+      }, this.reconnectionTime);
+    }
+
+    this.lastPing = date;
+  }
+
+  closeSocket(callMx10: boolean = true) {
+    if (this.mx10Socket != null) {
+      if (this.connected && callMx10) {
+        this.network.portClose();
+      }
+      this.mx10Socket?.close();
+      this.mx10Socket = null;
+      this.connected = false;
+    }
+  }
+
+  sendData(
+    group: number,
+    cmd: number,
+    data: ZcanDataArray = [],
+    mode = 0b01,
+    nid = this.myNID,
+    force = false,
+  ) {
+    const buffer = this.formatData(group, cmd, mode, nid, data);
+    this.send(buffer, force);
+  }
+
+  private formatData(
+    group: number,
+    cmd: number,
+    mode: number,
+    nid: number,
+    data: ZcanDataArray = [],
+  ) {
+    //Datagram Structure: Size(16) (Hex) (of Data), Unused(16) (Hex), Group(8) (Hex), Cmd+Mode(8) (command bit (Hex) shifted by mode (Binary)), NID(16) (Hex), Data(0...x) (Format: [{value: HEX, length: (1,2,4)}, {...}])
+
+    const size = data.reduce((sum, obj) => sum + obj.length, 0);
+    const buffer = Buffer.alloc(size + 8);
+
+    const cmd_md = (cmd << 2) | mode;
+
+    buffer.writeUInt16LE(size, 0);
+    buffer.writeUInt16LE(0, 2); // unused
+    buffer.writeUInt8(group, 4);
+    buffer.writeUInt8(cmd_md, 5);
+    buffer.writeUInt16LE(nid, 6);
+
+    let offset = 8;
+
+    data.forEach((element) => {
+      if (typeof element.value === 'string') {
+        ExtendedASCII.str2byte(element.value, buffer, offset, element.length);
+        offset += element.length;
+      } else {
+        switch (element.length) {
+          case 1:
+            buffer.writeUInt8(element.value, offset);
+            offset += 1;
+            break;
+
+          case 2:
+            buffer.writeUInt16LE(element.value, offset);
+            offset += 2;
+            break;
+
+          case 4:
+            buffer.writeUInt32LE(element.value, offset);
+            offset += 4;
+            break;
+
+          default:
+            // eslint-disable-next-line no-console
+            console.warn(`ELEMENT LENGTH NOT DEFINED, ${element}`);
+        }
+      }
+    });
+
+    this.printReadout(group, cmd, mode, nid, size, buffer.slice(8));
+
+    return buffer;
+  }
+
+  private send(message: Buffer, force = false) {
+    if (this.connected || force) {
+      this.mx10Socket?.send(
+        message,
+        0,
+        message.length,
+        this.outgoingPort,
+        this.mx10IP,
+        (err) => {
+          if (err && this.debugCommunication) {
+            // eslint-disable-next-line no-console
+            console.log(err);
+          }
+        },
+      );
+    } else {
+      this.errors.next('mx10.connection.not_connected');
+    }
+  }
+
+  private readRawData(message: Buffer) {
+    const size = message.readUInt16LE(0);
+    const group = message.readUInt8(4);
+    const commandAndMode = message.readUInt8(5);
+
+    const command = commandAndMode >> 2;
+    const mode = commandAndMode & 0x03;
+
+    const nid = message.readUInt16LE(6);
+
+    const buffer = message.slice(8); //Remove first 8 bytes; left only with data
+    this.printReadout(group, command, mode, nid, size, buffer, false);
+
+    switch (group) {
+      case 0x00:
+        this.systemControl.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x01:
+        this.accessoryCommand.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x02:
+        this.vehicle.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x05:
+        this.trainControl.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x06:
+      case 0x16:
+        this.trackCfg.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x07:
+        this.data.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x08:
+        this.info.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x09:
+        this.propertyConfig.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x0a:
+        this.network.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x0b:
+        this.railwayControl.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x0c:
+        this.zimoProgrammableScript.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x0e:
+        this.fileControl.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x0f:
+        this.fileTransfer.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x17:
+        this.lanData.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x18:
+        this.lanInfo.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x1a:
+        this.lanNetwork.parse(size, command, mode, nid, buffer);
+        break;
+      case 0x1c:
+        this.lanZimoProgrammableScript.parse(size, command, mode, nid, buffer);
+        break;
+      default:
+        // eslint-disable-next-line no-console
+        console.warn('Unknown group: ' + Number(group).toString(16));
+    }
+  }
+
+  private printReadout(
+    group: number,
+    cmd: number,
+    mode: number,
+    nid: number | undefined,
+    size: number,
+    raw_data: Buffer,
+    out = true,
+  ) {
+    if (this.debugCommunication) {
+      const data = JSON.stringify(Array.apply([], [...raw_data]));
+      const f = (obj: unknown) => Number(obj).toString(16);
+      const arrow = '|' + (out ? '→' : '←');
+
+      // eslint-disable-next-line no-console
+      console.debug(
+        `${arrow} g=${f(group)} c=${f(cmd)} m=${f(mode)} n=${f(nid)} l=${f(
+          size,
+        )} : ${data}`,
+      );
+    }
+  }
+}

package/src/docs_entrypoint.ts

@@ -0,0 +1,34 @@
+export {default as MX10} from './MX10';
+
+export {
+  AccessoryCommandGroup,
+  DataGroup,
+  FileControlGroup,
+  FileTransferGroup,
+  InfoGroup,
+  LanDataGroup,
+  LanInfoGroup,
+  LanNetworkGroup,
+  LanZimoProgrammableScriptGroup,
+  NetworkGroup,
+  PropertyConfigGroup,
+  RailwayControlGroup,
+  SystemControlGroup,
+  TrackCfgGroup,
+  TrainControlGroup,
+  VehicleGroup,
+  ZimoProgrammableScriptGroup,
+} from './zcan';
+
+export {
+  Direction as Direction,
+  ExternalController,
+  FunctionMode,
+  OperatingMode,
+  SystemStateMode,
+} from './util/enums';
+
+export * from './@types/models';
+export * from './@types/communication';
+
+export {Subject, Observable} from 'rxjs';

package/src/index.ts

@@ -0,0 +1,8 @@
+import MX10 from './MX10';
+
+export default MX10;
+export * from './util/enums';
+export * from './@types/models';
+export * from './@types/communication';
+
+export * from 'rxjs';

package/src/internal/bites.ts

@@ -0,0 +1,11 @@
+export const speedBites____ = 0b0000001111111111; // 0-9
+export const directionBites = 0b0000010000000000; // 10
+export const directACKBites = 0b0000100000000000; // 11
+export const eastWestBites_ = 0b0011000000000000; // 12-13
+export const emergencyStopB = 0b1000000000000000; // 15
+
+export const speedStepBites = 0b00001111;
+export const modeBites_____ = 0b11110000;
+
+export const shuntingFunctionB = 0b1111;
+export const manualModeB = 0b110000;

package/src/internal/speedUtils.ts

@@ -0,0 +1,36 @@
+import {Direction} from "../util/enums";
+import {directACKBites, directionBites, eastWestBites_, emergencyStopB, speedBites____, speedStepBites} from "./bites";
+
+export const combineSpeedAndDirection = (speed: number, forward: boolean, eastWest = Direction.UNDEFINED, emergencyStop = false) => {
+  const direction = Number(!forward);
+  const stop = Number(emergencyStop);
+
+  return speed | (direction << 10) | (eastWest << 12) | (stop << 15);
+};
+
+export const parseSpeed = (speedAndDirection: number) => {
+  const speedStep = speedAndDirection & speedBites____;
+  const direction = (speedAndDirection & directionBites) === directionBites;
+  const directionACK = (speedAndDirection & directACKBites) === directACKBites;
+  const sideways = (speedAndDirection & eastWestBites_) >> 12;
+  const emergencyStop = (speedAndDirection & emergencyStopB) === emergencyStopB;
+
+  const forward = !direction && !directionACK;
+
+  return {
+    speedStep,
+    forward,
+    eastWest: sideways,
+    emergencyStop
+  };
+}
+
+export const getSpeedSteps = (val: number) => {
+  const steps = val & speedStepBites;
+
+  if (steps == 0 || steps >= 6) {
+    return undefined;
+  }
+
+  return  steps;
+}

package/src/internal/utils.ts

@@ -0,0 +1,3 @@
+export function delay(ms: number) {
+  return new Promise( resolve => setTimeout(resolve, ms) );
+}

package/src/util/enums.ts

@@ -0,0 +1,147 @@
+export enum OperatingMode {
+  UNKNOWN = '',
+  DCC = 'DCC',
+  MM1 = 'MM1',
+  MM2 = 'MM2',
+  SX = 'SX',
+  MFX = 'mfx',
+  NOT_DEFINED = 'N/A',
+  SYS = 'System',
+}
+
+export const getOperatingMode = (val: number) => {
+  // eslint-disable-next-line no-bitwise
+  const mode = val >> 4;
+  const modes = Object.values(OperatingMode);
+  if (mode >= 1 && mode <= 7) {
+    return modes[mode];
+  }
+  return OperatingMode.UNKNOWN;
+};
+
+export enum MaxSpeedSteps {
+  UNKNOWN,
+  MAX14,
+  MAX27,
+  MAX28,
+  MAX128,
+  MAX1024,
+}
+
+export enum ExternalController {
+  /** external controll: active on another controller */
+  FS = 'FS',
+  /** vehicle intergrated to its own traction T1, T2 */
+  T1 = 'T1',
+  T2 = 'T2',
+  FT = 'FT',
+  /** FT(...) f.e. FT(2) external traction on different controller */
+  FT2 = 'FT(2)',
+  /** external traction active on different controller */
+  FS2 = 'FS(2)',
+}
+
+/**
+ * Enum describing how given functions behaves.
+ */
+export enum FunctionMode {
+  /** Functions needs to be pressed down and held to remain activated */
+  momentary,
+
+  /** Functions works as standart toggle switch */
+  switch,
+}
+
+export enum SystemStateMode {
+  NORMAL = 1,
+  SSP0 = 2,
+  SSPe = 3,
+  OFF = 4,
+  SERVICE = 5,
+  OVERRCURRENT = 10,
+}
+
+export enum TrackMode {
+  OFF = -1,
+  NORMAL = 0,
+  SSP0 = 1,
+  SSPe = 2,
+  SMP = 4,
+  UPDATE = 5,
+  SOUND = 6,
+  ERROR = 8,
+  ERROR_SMP = 9,
+}
+
+export enum Direction {
+  UNDEFINED = 0,
+  EAST = 1,
+  WEST = 2,
+}
+
+export enum NameType {
+  VEHICLE,
+  RAILWAY,
+  CONNECTION,
+  MANUFACTURER,
+  DECODER,
+  DESIGNATION,
+  CFGDB,
+  ICON,
+  ZIMO_PARTNER,
+  LAND,
+  COMPANY_CV,
+}
+
+export enum ImageType {
+  VEHICLE = 1,
+  VEHICLE_CRC32 = 2,
+  TACHO = 3,
+  VEHICLE_INSTRUMENT_BRAKE_BAR = 10,
+  VEHICLE_INSTRUMENT = 0x1f,
+}
+
+export enum FxInfoType {
+  ICON = 0x10,
+}
+
+export enum SpecialFunctionMode {
+  MANUAL = 1,
+  SHUNTING_FUNCTION = 2,
+  DIRECTION_DEFAULT = 3,
+}
+
+export enum Manual {
+  OFF = 0,
+  ON = 1,
+}
+
+export enum ShuntingFunction {
+  OFF = 0,
+  AZBZ = 1,
+  HALF = 2,
+}
+
+export enum DirectionDefault {
+  NO_CHANGE = 0,
+  DIRECTION_EAST = 1,
+  DIRECTION_WEST = 2,
+}
+
+export enum BidiType {
+  RAILCOM_STATISTICS = 0x0000,
+  SPEED_REPORT = 0x0100,
+  TILT_AND_CURVE = 0x0101,
+  CV = 0x0200,
+  QOS = 0x0300,
+  FILL_LEVEL = 0x0400,
+  DIRECTION = 0x0800,
+  TRACK_VOLTAGE = 0x1000,
+  ALARMS = 0x1100,
+}
+
+export enum ForwardOrReverse {
+  UNKNOWN = 0,
+  FORWARD = 1,
+  REVERSE = 2,
+}