@zimo-elektronik/zcan 1.0.0

package/.dockerignore

@@ -0,0 +1,7 @@
+.vscode/
+.git/
+.idea/
+dist/
+node_modules
+.docusaurus
+build/

package/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

package/.eslintignore

@@ -0,0 +1,7 @@
+dist/
+scripts/
+cmd/
+tools/
+docs
+protocol_docs
+*.d.ts

package/.eslintrc.cjs

@@ -0,0 +1,17 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint/eslint-plugin', 'import', 'eslint-plugin-tsdoc'],
+  extends: ['plugin:@typescript-eslint/recommended'],
+  env: {
+    jest: true,
+    node: true,
+  },
+  rules: {
+    'no-console': 'error',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-dupe-class-members': ['error'],
+    '@typescript-eslint/no-useless-constructor': ['error'],
+    '@typescript-eslint/no-inferrable-types': ['off'],
+  },
+}

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto

package/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: docs
+
+on:
+  push:
+    branches: [master]
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.11.0'
+
+      - run: npm ci --ignore-scripts
+      - run: cd protocol_docs && npm ci --ignore-scripts
+      - run: npm run docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: protocol_docs/build
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/library.yml

@@ -0,0 +1,59 @@
+name: Publish Package to npmjs
+
+on:
+  push:
+    branches: [master]
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "library"
+  cancel-in-progress: false
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      should_skip: ${{ steps.check.outputs.should_skip }}
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          fetch-depth: 0
+      - id: check
+        run: echo "should_skip=no" >> $GITHUB_OUTPUT
+#        run: |
+#          PUBLISHED_VERSION=$(npm show @zimo-elektronik/zcan version)
+#          VERSION=$(npm pkg get version | tr -d '"')
+#
+#          if [ "$PUBLISHED_VERSION" = "$VERSION" ];
+#          then
+#            echo "Version didn't change, skipping"
+#            echo "should_skip=yes" >> $GITHUB_OUTPUT
+#          else
+#            echo "should_skip=no" >> $GITHUB_OUTPUT
+#          fi
+
+
+  build:
+    runs-on: ubuntu-latest
+    needs:
+      - check
+    if:  ${{needs.check.outputs.should_skip == 'no'}}
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.11.0'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

package/.nvmrc

@@ -0,0 +1 @@
+v20.11.0

package/.prettierignore

@@ -0,0 +1,14 @@
+.github
+.yarn
+coverage
+build
+docs
+dist
+out
+temp
+
+*.yml
+*.html
+*.md
+*.json
+*.d.ts

package/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "bracketSpacing": false,
+  "bracketSameLine": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "endOfLine": "auto",
+  "tabWidth": 2
+}

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ZIMO-Elektronik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# ZCAN js library
+
+Project bootstrapped using [NodeJS Starter ToolKit](https://github.com/vitorsalgado/create-nodejs-ts).  
+Visit the repository for more details.
+
+## Getting Started
+
+Review the generated code, and it's recommended to run a `npm init` to adjust basic project configurations before start.

package/__tests__/connection.test.ts

@@ -0,0 +1,58 @@
+import {createSocket} from "dgram";
+import {afterAll, beforeAll, it, jest, describe, expect} from "@jest/globals";
+import {createMX10, initConnection} from "./util";
+
+describe('High level tests', () => {
+  const mx10 = createMX10(true);
+  const debug = global.console.debug;
+
+  afterEach(() => {
+    mx10.closeSocket()
+  })
+
+  beforeAll(() => {
+    global.console.debug = jest.fn();
+  })
+
+  afterAll(() => {
+    global.console.debug = debug;
+  })
+
+  it("Correct url test", async () => {
+    expect(mx10.connected).toBe(false);
+
+    return initConnection(mx10).then(() => {
+        expect(mx10.connected).toBe(true);
+
+        mx10.closeSocket();
+        expect(mx10.connected).toBe(false);
+    })
+  });
+
+  it("Incorrect url test", async () => {
+    expect(mx10.connected).toBe(false);
+    const res = mx10.initSocket(createSocket, "192.168.2.145");
+    await expect(res).rejects.toThrow('mx10.connection.timeout')
+
+    expect(mx10.connected).toBe(false);
+  });
+
+  it("Error logger test", (done) => {
+    mx10.errors.subscribe((error: string) => {
+      expect(error).toBe('mx10.connection.not_connected')
+      done();
+    })
+
+    mx10.network.ping();
+  })
+
+  it("Incorrect data format", () => {
+    expect(() => {
+      mx10.sendData(0x00, 0x00, [
+        {length: 1, value: 1,},
+        {length: 4, value: 1234,},
+        {length: 8, value: 0,}
+      ])
+    }).toThrow(/ELEMENT LENGTH NOT DEFINED.*/)
+  })
+});

package/__tests__/dataGroup.test.ts

@@ -0,0 +1,98 @@
+import {createMX10, initConnection} from './util';
+import {afterAll, beforeAll, describe, expect, it} from '@jest/globals';
+import {firstValueFrom} from 'rxjs';
+import {FxInfoType, ImageType, NameType} from '../src';
+
+describe('Data group tests - 0x07', () => {
+  const mx10 = createMX10(true);
+
+  beforeAll(async () => {
+    await initConnection(mx10);
+  });
+
+  afterAll(() => {
+    mx10.closeSocket();
+  });
+
+  it('0x00 - Group count test', (done) => {
+    mx10.data.groupCount();
+
+    const sub = mx10.data.onGroupCount.subscribe((data) => {
+      if (data.objectType === 0x0000) {
+        expect(data.objectType).toBe(0x000);
+        expect(data.number).toBeDefined();
+
+        done();
+        sub.unsubscribe();
+      }
+    });
+  });
+
+  it('0x01 - List item by index test', async () => {
+    mx10.data.listItemsByIndex(0x0000, 3);
+
+    const data = await firstValueFrom(mx10.data.onListItemsByIndex);
+
+    expect(data.index).toBe(3);
+    expect(data.nid).toBe(4);
+  });
+
+  it('0x02 - List item by nid test', async () => {
+    mx10.data.listItemsByNID(3);
+
+    const data = await firstValueFrom(mx10.data.onListItemsByNID);
+    expect(data.nid).toBe(65535);
+    expect(data.index).toBe(65535);
+  });
+
+  it('0x1f - Remove locomotive with nid', async () => {
+    mx10.data.removeLocomotive(3);
+
+    const data = await firstValueFrom(mx10.data.onRemoveLocomotive);
+    expect(data.nid).toBe(3);
+    expect(data.state).toBeDefined();
+  });
+
+  it('0x12 - Image config test', async () => {
+    const promise = firstValueFrom(mx10.data.onItemImageConfig).then((data) => {
+      expect(data.nid).toBe(3);
+      expect(data.type).toBe(ImageType.VEHICLE);
+      expect(data.imageId).toBe(6055);
+    });
+
+    mx10.data.itemImageConfig(3, ImageType.VEHICLE, 6055);
+
+    return promise;
+  });
+
+  test.each<{icon: number; fx: number}>([
+    {icon: 755, fx: 1},
+    {icon: 756, fx: 1},
+    {icon: 700, fx: 1},
+  ])('0x15 - Function image change test', async ({icon, fx}) => {
+    const promise = firstValueFrom(mx10.data.onItemFxInfo).then((data) => {
+      expect(data.nid).toBe(3);
+      expect(data.function).toBe(fx);
+      expect(data.type).toBe(FxInfoType.ICON);
+      expect(data.data).toBe(icon);
+    });
+
+    mx10.data.itemFxInfo(3, fx, FxInfoType.ICON, icon);
+
+    return promise;
+  });
+
+  test.each<{name: string}>([
+    {name: '---'},
+    {name: 'teßt Öf a näme'},
+    {name: 'dodo1'},
+  ])('0x21 - Data name extended test', async ({name}) => {
+    mx10.data.dataNameExtended(3, 0, name);
+
+    const data = await firstValueFrom(mx10.data.onDataNameExtended);
+    expect(data.nid).toBe(3);
+    expect(data.type).toBe(NameType.VEHICLE);
+    expect(data.value1).toBe(undefined);
+    expect(data.name).toBe(name);
+  });
+});

package/__tests__/infoGroup.test.ts

@@ -0,0 +1,30 @@
+import {createMX10, initConnection} from "./util";
+import {afterAll, beforeAll, expect, it} from "@jest/globals";
+
+describe('Info group tests - 0x08', () => {
+  const mx10 = createMX10();
+
+  beforeAll(async () => {
+    await initConnection(mx10)
+  })
+
+  afterAll(() => {
+    mx10.closeSocket();
+  })
+
+  it("0x05 - Bidi info - train speed", (done) => {
+
+    const sub = mx10.info.onBidiInfoChange.subscribe((data) => {
+      if (data.type === 0x0100) {
+
+        expect(data.nid).toBe(3);
+        expect(data.data).toBeDefined();
+        expect(data.data).toBeGreaterThanOrEqual(0);
+
+        done();
+        sub.unsubscribe();
+      }
+    });
+  });
+
+});

package/__tests__/lanDataGroup.test.ts

@@ -0,0 +1,82 @@
+import {createMX10, initConnection} from './util';
+import {afterAll, beforeAll, describe, it, expect} from '@jest/globals';
+import {firstValueFrom} from 'rxjs';
+import {
+  DataValueExtendedData,
+  LocoGuiMXExtended,
+  LocoSpeedTabExtended,
+  OperatingMode,
+  Train,
+} from '../src';
+
+describe('LAN Data group tests - 0x17', () => {
+  const mx10 = createMX10();
+
+  beforeAll(async () => {
+    await initConnection(mx10);
+  });
+
+  afterAll(() => {
+    mx10.closeSocket();
+  });
+
+  it('0x27 - Loco GUI eXtended', async () => {
+    mx10.lanData.locoGuiExtended(211);
+
+    const train: Train = await firstValueFrom(mx10.lanData.onLocoGuiExtended);
+    expect(train).toBeDefined();
+    expect(train.nid).toBe(211);
+    // expect(train.name).toMatch('import loco');
+    expect(train.era).toBeDefined();
+    expect(train.functions).toBeDefined();
+  });
+
+  it('0x28 - Loco GUI MX eXtended', async () => {
+    mx10.lanData.locoGuiMXExtended(211);
+
+    const train: LocoGuiMXExtended = await firstValueFrom(
+      mx10.lanData.onLocoGuiMXExtended,
+    );
+    expect(train).toBeDefined();
+    expect(train.nid).toBe(211);
+    expect(train.functions).toBeDefined();
+  });
+
+  it('0x19 - Loco Speed Tab eXtended', async () => {
+    mx10.lanData.locoSpeedTapExtended(42);
+
+    const locoSpeedTab: LocoSpeedTabExtended = await firstValueFrom(
+      mx10.lanData.onLocoSpeedTabExtended,
+    );
+    expect(locoSpeedTab).toBeDefined();
+    expect(locoSpeedTab.nid).toBe(42);
+    expect(locoSpeedTab.dbat6).toBe(1);
+    if (locoSpeedTab.dbat6 === 5) {
+      expect(locoSpeedTab.speedTab).toBeDefined();
+      expect(locoSpeedTab.speedTab).toHaveLength(4);
+    }
+
+    // mx10.sendData(0x02, 0x01, [{value: 56, length: 2}]);
+    // expect(train.era).toBeDefined();
+    // expect(train.functions).toBeDefined();
+  });
+
+  it('0x8 - Data Value eXtended', async () => {
+    mx10.lanData.dataValueExtended(211);
+
+    const data: DataValueExtendedData = await firstValueFrom(
+      mx10.lanData.onDataValueExtended,
+    );
+
+    expect(data).toBeDefined();
+    expect(data.nid).toBe(211);
+    expect(data.functionCount).toBeDefined();
+    expect(data.operatingMode).toBeDefined();
+    expect(data.operatingMode).toBe(OperatingMode.DCC);
+    expect(data.speedStep).toBeDefined();
+    expect(data.forward).toBeDefined();
+    expect(data.emergencyStop).toBeDefined();
+    expect(data.functionsStates).toBeDefined();
+    expect(data.flags.deleted).toBe(false);
+  });
+});

package/__tests__/lanInfoGroup.test.ts

@@ -0,0 +1,41 @@
+import {createMX10, initConnection} from "./util/";
+import {afterAll, beforeAll, it, describe, expect} from "@jest/globals";
+import {TrackMode} from "../src";
+
+describe('LAN Info group tests - 0x18', () => {
+  const mx10 = createMX10();
+
+  beforeAll(async () => {
+    await initConnection(mx10)
+  })
+
+  afterAll(() => {
+    mx10.closeSocket();
+  })
+
+  it("0x00 - module power info", (done) => {
+    const sub = mx10.lanInfo.onModulePowerInfo.subscribe((data) => {
+      if (data.deviceNID === mx10.mx10NID) {
+
+        expect(data.port1Status).toBeDefined();
+        expect(data.port1Status).toBe(TrackMode.NORMAL);
+        expect(data.port1Voltage).toBeDefined();
+        expect(data.port1Amperage).toBeDefined();
+
+        expect(data.port2Status).toBeDefined();
+        expect(data.port2Status).toBe(TrackMode.NORMAL);
+        expect(data.port2Voltage).toBeDefined();
+        expect(data.port2Amperage).toBeDefined();
+
+        expect(data.amperage32V).toBeDefined();
+        expect(data.amperage12V).toBeDefined();
+        expect(data.voltageTotal).toBeDefined();
+        expect(data.temperature).toBeDefined();
+
+        sub.unsubscribe();
+        done();
+      }
+    })
+  })
+
+});

package/__tests__/systemControlGroup.test.ts

@@ -0,0 +1,42 @@
+import {afterAll, beforeAll, describe, expect, jest} from '@jest/globals';
+import {createMX10, initConnection} from './util';
+import {SystemStateData, SystemStateMode} from '../src';
+import {delay} from '../src/internal/utils';
+
+describe('System Control Group group tests - 0x00', () => {
+  const mx10 = createMX10();
+
+  beforeAll(async () => {
+    await initConnection(mx10);
+  });
+
+  afterAll(() => {
+    mx10.systemControl.systemState(SystemStateMode.NORMAL);
+
+    delay(1000).then(() => {
+      mx10.closeSocket();
+    });
+  });
+
+  test.each<{mode: number}>([
+    {mode: SystemStateMode.SSPe},
+    {mode: SystemStateMode.OFF},
+    {mode: SystemStateMode.SSP0},
+  ])('0x00 - System state test', ({mode}, done) => {
+    mx10.systemControl.systemState(mode);
+
+    const callback = jest.fn((data: SystemStateData) => {
+      if (data.nid === mx10.mx10NID) {
+        expect(data.port).toBeDefined();
+        expect(data.mode).toBe(mode);
+
+        if (callback.mock.calls.length === 3) {
+          sub.unsubscribe();
+          done();
+        }
+      }
+    });
+
+    const sub = mx10.systemControl.onSystemStateChange.subscribe(callback);
+  });
+});

package/__tests__/trackCfgGroup.test.ts

@@ -0,0 +1,43 @@
+import {createMX10, initConnection} from './util';
+import {afterAll, beforeAll, describe, it, expect} from '@jest/globals';
+
+describe('LAN Data group tests - 0x16', () => {
+  const mx10 = createMX10();
+
+  beforeAll(async () => {
+    await initConnection(mx10);
+  });
+
+  afterAll(() => {
+    mx10.closeSocket();
+  });
+
+  it('0x08 - Tse Prog Read Extended', (done) => {
+    mx10.trackCfg.tseProgRead(211, 8);
+
+    const prog = mx10.trackCfg.onTseProgReadExtended.subscribe((data) => {
+      expect(data.cfgNum).toBeDefined();
+      expect(data.cfgNum).toBe(8);
+      expect(data.cvValue).toBeDefined();
+      expect(data.cvValue).toBe(145);
+
+      prog.unsubscribe();
+      done();
+    });
+  });
+
+  it('0x09 - Tse Prog Write Extended', (done) => {
+    // Please be sure if you want to CV write HU value on test
+    // mx10.trackCfg.tseProgWrite(211, 51, 20);
+
+    const prog = mx10.trackCfg.onTseProgWriteExtended.subscribe((data) => {
+      expect(data.cfgNum).toBeDefined();
+      expect(data.cfgNum).toBe(51);
+      expect(data.cvValue).toBeDefined();
+      expect(data.cvValue).toBe(20);
+
+      prog.unsubscribe();
+      done();
+    });
+  });
+});

package/__tests__/util/index.ts

@@ -0,0 +1,14 @@
+import {createSocket} from 'dgram';
+import MX10 from '../../src';
+
+export function createMX10(debug?: boolean) {
+  return new MX10(
+    () => new Promise((resolve) => resolve(23)),
+    1000,
+    debug || false,
+  );
+}
+
+export function initConnection(mx10: MX10) {
+  return mx10.initSocket(createSocket, '192.168.1.145');
+}