z21-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nicolas Meunier
+
+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,162 @@
+# z21-client
+
+z21-client is a Node.js library written in TypeScript that implements the UDP protocol of the Roco/Fleischmann Z21 DCC command station.
+It provides a strongly-typed, event-driven API to control locomotives and accessories, read and write CVs, and monitor system events in real time.
+
+---
+
+## Features
+
+- Send and receive UDP commands to/from a Z21 command station
+- Control track power, emergency stop, turnouts, and engine functions
+- Drive engines with speed and direction
+- Read and write CVs (configuration variables)
+- Query status, serial number, and broadcast flags
+- Subscribe to feedback and status updates
+- Fully typed API for Node.js
+- Extensive unit tests
+
+---
+
+## Installation
+
+```sh
+npm install z21-client
+```
+
+---
+
+## Usage Example
+
+```typescript
+import { Z21Client } from "z21-client";
+
+const z21 = new Z21Client("192.168.0.111", 21105);
+
+z21.on("status", (status) => {
+  console.log("Z21 status:", status);
+});
+
+(async () => {
+  await z21.system.setTrackPowerOn();
+  await z21.system.getStatus();
+  z21.engines.setDriveEngine(3, 50, true); // address, speed, forward
+  await z21.engines.setEngineFunctions(3, 1, "on");
+  await z21.engines.cvWrite(17, 192);
+  const cvResult = await z21.engines.cvRead(17);
+  await z21.accessories.switchTurnout(5, true); // address 5, output 2 (true), activate (default)
+})();
+```
+
+---
+
+## API
+
+### Constructor
+
+```typescript
+new Z21Client(host: string, port?: number, debug?: boolean)
+```
+
+- `host`: IP address of your Z21 (e.g. `"192.168.0.111"`)
+- `port`: UDP port (default: `21105`)
+- `debug`: Enable debug logs (default: `false`)
+
+---
+
+### System Controller
+
+- `system.setTrackPowerOn()`: Turn track power on
+- `system.setTrackPowerOff()`: Turn track power off
+- `system.emergencyStop()`: Emergency stop
+- `system.setBroadcastFlags(engine?: boolean, accessory?: boolean, feedback?: boolean)`: Set broadcast flags
+- `system.getBroadcastFlags()`: Get broadcast flags
+- `system.getSerialNumber()`: Get Z21 serial number
+- `system.getStatus()`: Get Z21 status
+
+---
+
+### Engine Controller
+
+- `engines.getEngineInfo(address: number)`: Request information about an engine and subscribe to updates
+- `engines.setDriveEngine(address: number, speed: number, forward: boolean, engineSpeedSteps?: number)`: Drive an engine with speed and direction (speed steps: 14, 28, or 128)
+- `engines.setEngineFunctions(address: number, functionNumber: number, state: "on" | "off" | "toggle")`: Set a function state on an engine (F1-F28)
+- `engines.cvRead(cv: number)`: Read a CV in direct mode
+- `engines.cvWrite(cv: number, value: number)`: Write a CV in direct mode
+
+---
+
+### Accessory Controller
+
+- `accessories.switchTurnout(address: number, output?: boolean, activate?: boolean, queue?: boolean)`: Switch turnout/accessory
+
+---
+
+### General
+
+- `close()`: Close UDP socket and logout
+
+---
+
+## Events
+
+- `"status"`: Z21 status updates
+- `"broadcastFlags"`: Broadcast flags updates
+- `"serialNumber"`: Serial number received
+- `"trackPower"`: Track power state
+- `"programmingMode"`: Programming mode state
+- `"shortCircuit"`: Short circuit detected
+- `"engineInfo"`: Engine info updates
+- `"cvResult"`: CV read/write result
+- `"accessoryInfo"`: Accessory/turnout info
+- `"unknownBroadcast"`: Unknown broadcast received
+- `"error"`: UDP or protocol errors
+- `"debug"`: Debug messages
+
+---
+
+## TypeScript
+
+This library is fully typed. All types and interfaces are included automatically.
+
+---
+
+## Development & Testing
+
+- Run all tests:  
+  ```sh
+  npm test
+  ```
+- Run tests with coverage:  
+  ```sh
+  npm run test:coverage
+  ```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Author
+
+Nicolas Meunier
+
+---
+
+## Contributing
+
+Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
+
+---
+
+## Links
+
+- [Roco Z21 Documentation (EN)](https://www.z21.eu/en/downloads)
+- [Node.js](https://nodejs.org/)
+- [TypeScript](https://www.typescriptlang.org/)
+
+---
+

package/dist/Z21Client.d.ts

@@ -0,0 +1,18 @@
+import { EventEmitter } from "events";
+import { EngineController } from "./controllers/EngineController";
+import { AccessoryController } from "./controllers/AccessoryController";
+import { SystemController } from "./controllers/SystemController";
+export declare class Z21Client extends EventEmitter {
+    readonly engines: EngineController;
+    readonly accessories: AccessoryController;
+    readonly system: SystemController;
+    private readonly transport;
+    /**
+     * Create a new Z21Client instance.
+     * @param host The hostname or IP address of the Z21 device.
+     * @param port The port number to connect to (default: 21105).
+     * @param debug Enable debug mode (default: false).
+     */
+    constructor(host: string, port?: number, debug?: boolean);
+    close(): Promise<void>;
+}

package/dist/Z21Client.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Z21Client = void 0;
+// src/Z21Client.ts
+const events_1 = require("events");
+const Z21UdpTransport_1 = require("./transport/Z21UdpTransport");
+const EngineController_1 = require("./controllers/EngineController");
+const AccessoryController_1 = require("./controllers/AccessoryController");
+const SystemController_1 = require("./controllers/SystemController");
+const feedbackParser_1 = require("./parsers/feedbackParser");
+class Z21Client extends events_1.EventEmitter {
+    /**
+     * Create a new Z21Client instance.
+     * @param host The hostname or IP address of the Z21 device.
+     * @param port The port number to connect to (default: 21105).
+     * @param debug Enable debug mode (default: false).
+     */
+    constructor(host, port = 21105, debug = false) {
+        super();
+        this.transport = new Z21UdpTransport_1.Z21UdpTransport(host, port, debug, new feedbackParser_1.FeedbackParser());
+        // Initialize controllers
+        this.engines = new EngineController_1.EngineController(this.transport);
+        this.accessories = new AccessoryController_1.AccessoryController(this.transport);
+        this.system = new SystemController_1.SystemController(this.transport);
+        // Forward transport events to Z21Client
+        this.transport.on("debug", (msg) => this.emit("debug", msg));
+        this.transport.on("serialNumber", (msg) => this.emit("serialNumber", msg));
+        this.transport.on("broadcastFlags", (msg) => this.emit("broadcastFlags", msg));
+        this.transport.on("status", (msg) => this.emit("status", msg));
+        this.transport.on("trackPower", (msg) => this.emit("trackPower", msg));
+        this.transport.on("programmingMode", (msg) => this.emit("programmingMode", msg));
+        this.transport.on("shortCircuit", (msg) => this.emit("shortCircuit", msg));
+        this.transport.on("engineInfo", (msg) => this.emit("engineInfo", msg));
+        this.transport.on("cvResult", (msg) => this.emit("cvResult", msg));
+        this.transport.on("accessoryInfo", (msg) => this.emit("accessoryInfo", msg));
+        this.transport.on("unknownBroadcast", (err) => this.emit("unknownBroadcast", err));
+        this.transport.on("error", (err) => this.emit("error", err));
+        if (debug) {
+            console.log(`[Z21Client] Init`);
+        }
+    }
+    async close() {
+        await this.system.logout();
+        await this.transport.close();
+    }
+}
+exports.Z21Client = Z21Client;

package/dist/Z21Commands.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Commands payloads (no length)
+ */
+export declare const commands: {
+    LAN_LOGOFF: number[];
+    LAN_GET_SERIAL_NUMBER: number[];
+    LAN_GET_BROADCAST_FLAGS: number[];
+    LAN_SET_BROADCAST_FLAGS: number[];
+    LAN_X_GET_STATUS: number[];
+    LAN_X_GET_VERSION: number[];
+    LAN_X_TRACK_POWER_OFF: number[];
+    LAN_X_TRACK_POWER_ON: number[];
+    LAN_X_SET_STOP: number[];
+};

package/dist/Z21Commands.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commands = void 0;
+/**
+ * Commands payloads (no length)
+ */
+exports.commands = {
+    LAN_LOGOFF: [0x40, 0x00, 0x30, 0x00],
+    LAN_GET_SERIAL_NUMBER: [0x10, 0x00],
+    LAN_GET_BROADCAST_FLAGS: [0x51, 0x00],
+    LAN_SET_BROADCAST_FLAGS: [0x50, 0x00],
+    LAN_X_GET_STATUS: [0x40, 0x00, 0x21, 0x24, 0x05],
+    LAN_X_GET_VERSION: [0x40, 0x00, 0x21, 0x21, 0x00],
+    LAN_X_TRACK_POWER_OFF: [0x40, 0x00, 0x21, 0x80, 0xa1],
+    LAN_X_TRACK_POWER_ON: [0x40, 0x00, 0x21, 0x81, 0xa0],
+    LAN_X_SET_STOP: [0x80, 0x80],
+};

package/dist/controllers/AccessoryController.d.ts

@@ -0,0 +1,13 @@
+import { Z21UdpTransport } from "../transport/Z21UdpTransport";
+export declare class AccessoryController {
+    private transport;
+    constructor(transport: Z21UdpTransport);
+    /**
+       * Switch a turnout (accessory) using LAN_X_SET_TURNOUT.
+       * @param address Turnout address (1-2047)
+       * @param output Output: false = output 1, true = output 2 (default: false)
+       * @param activate true to activate, false to deactivate (default: true)
+       * @param queue Set to true to queue the command (default: false)
+       */
+    switchTurnout(address: number, output?: boolean, activate?: boolean, queue?: boolean): Promise<void>;
+}

package/dist/controllers/AccessoryController.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessoryController = void 0;
+class AccessoryController {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+       * Switch a turnout (accessory) using LAN_X_SET_TURNOUT.
+       * @param address Turnout address (1-2047)
+       * @param output Output: false = output 1, true = output 2 (default: false)
+       * @param activate true to activate, false to deactivate (default: true)
+       * @param queue Set to true to queue the command (default: false)
+       */
+    async switchTurnout(address, output = false, activate = true, queue = false) {
+        address = address - 1; // Convert to 0-based address
+        // Address split
+        const FAdr_MSB = (address >> 8) & 0xFF;
+        const FAdr_LSB = address & 0xFF;
+        // 10Q0A00P
+        // Bit 7: 1 (always)
+        // Bit 6: 0 (always)
+        // Bit 5: Q (queue)
+        // Bit 4: 0 (always)
+        // Bit 3: A (activate, 1=activate, 0=deactivate)
+        // Bits 2-1: 0 (always)
+        // Bit 0: P (output)
+        let db2 = 0x80; // Bit 7 set
+        if (queue)
+            db2 |= 0x20; // Q = bit 5
+        if (activate)
+            db2 |= 0x08; // A = bit 3
+        if (output)
+            db2 |= 0x01; // P = bit 0 (true = output 2, false = output 1)
+        // Build XpressNet frame: [0x53, FAdr_MSB, FAdr_LSB, db2]
+        const xpressNetFrame = [0x53, FAdr_MSB, FAdr_LSB, db2];
+        // XOR checksum for XpressNet frame
+        let xor = 0;
+        for (const byte of xpressNetFrame)
+            xor ^= byte;
+        xpressNetFrame.push(xor);
+        // LAN_X header: [0x40, 0x00]
+        const payload = [0x40, 0x00, ...xpressNetFrame];
+        await this.transport.sendCommand(payload);
+    }
+}
+exports.AccessoryController = AccessoryController;

package/dist/controllers/EngineController.d.ts

@@ -0,0 +1,36 @@
+import { CvResultData, ErrorResultData } from "../parsers/parserResult";
+import { Z21UdpTransport } from "../transport/Z21UdpTransport";
+export declare class EngineController {
+    private transport;
+    constructor(transport: Z21UdpTransport);
+    /**
+     * Request information about an engine and subscribe to updates for this address.
+     * @param address Engine address (1-10239)
+     */
+    getEngineInfo(address: number): Promise<void>;
+    /**
+     * Drive an engine with speed and direction.
+     * @param address Engine address (1-10239)
+     * @param speed Speed value (0-127)
+     * @param forward Direction (true=forward, false=backward)
+     */
+    setDriveEngine(address: number, speed: number, forward: boolean, engineSpeedSteps?: number): void;
+    /**
+     * Set a function state on an engine.
+     * @param address Engine address (1-10239)
+     * @param functionNumber Function number (1-28)
+     * @param state Function state (on, off, toggle)
+     */
+    setEngineFunctions(address: number, functionNumber: number, state: string): Promise<void>;
+    /**
+     * Read a CV in direct mode.
+     * @param cv CV number (1-1024)
+     */
+    cvRead(cv: number): Promise<ErrorResultData | CvResultData>;
+    /**
+     * Write a CV in direct mode.
+     * @param cv CV number (1-1024)
+     * @param value Value to write (0-255)
+     */
+    cvWrite(cv: number, value: number): Promise<ErrorResultData | CvResultData>;
+}

package/dist/controllers/EngineController.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngineController = void 0;
+class EngineController {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Request information about an engine and subscribe to updates for this address.
+     * @param address Engine address (1-10239)
+     */
+    async getEngineInfo(address) {
+        // Split address into MSB and LSB
+        let addrMsb = (address >> 8) & 0x3F;
+        const addrLsb = address & 0xFF;
+        // For addresses >= 128, set the two highest bits in MSB
+        if (address >= 128) {
+            addrMsb = 0xC0 | addrMsb;
+        }
+        // Build XpressNet frame: [0xE3, 0xF0, Adr_MSB, Adr_LSB]
+        const xpressNetFrame = [0xE3, 0xF0, addrMsb, addrLsb];
+        // XOR checksum for XpressNet frame
+        let xor = 0;
+        for (const byte of xpressNetFrame)
+            xor ^= byte;
+        xpressNetFrame.push(xor);
+        // LAN_X header: [0x40, 0x00]
+        const payload = [0x40, 0x00, ...xpressNetFrame];
+        await this.transport.sendCommand(payload);
+    }
+    /**
+     * Drive an engine with speed and direction.
+     * @param address Engine address (1-10239)
+     * @param speed Speed value (0-127)
+     * @param forward Direction (true=forward, false=backward)
+     */
+    setDriveEngine(address, speed, forward, engineSpeedSteps = 128) {
+        // --- Build XpressNet engine control frame ---
+        const addrL = address & 0xFF; // Low byte of engine address
+        const addrH = (address >> 8) & 0x3F; // High byte (14-bit address max)
+        const directionBit = forward ? 0x80 : 0x00; // Set direction bit if forward
+        const speedByte = directionBit | (speed & 0x7F); // Combine direction and speed
+        let steps = 0x13; // Default to DCC128
+        if (engineSpeedSteps === 28) {
+            steps = 0x12; // DCC27 for 27-speed
+        }
+        else if (engineSpeedSteps === 14) {
+            steps = 0x10; // DCC14 for 14-speed
+        }
+        // XpressNet frame: E4 = drive engine command
+        let xpressNetFrame = [0xE4, steps, addrH, addrL, speedByte];
+        // --- Calculate XOR checksum ---
+        let xor = 0;
+        for (const byte of xpressNetFrame) {
+            xor ^= byte;
+        }
+        xpressNetFrame.push(xor);
+        // --- Wrap in LAN_X payload (0x40 0x00 = LAN_X header, 0x24 = XpressNet command) ---
+        const payload = [0x40, 0x00, ...xpressNetFrame];
+        // --- Build complete Z21 frame and send ---
+        this.transport.sendCommand(payload);
+    }
+    /**
+     * Set a function state on an engine.
+     * @param address Engine address (1-10239)
+     * @param functionNumber Function number (1-28)
+     * @param state Function state (on, off, toggle)
+     */
+    async setEngineFunctions(address, functionNumber, state) {
+        const addrL = address & 0xFF; // Low byte of engine address
+        const addrH = (address >> 8) & 0x3F; // High byte (14-bit address max)
+        // Generation of functionByte according to functionNumber (1-28) and state
+        let functionByte = 0x00;
+        if (functionNumber < 0 || functionNumber > 28) {
+            throw new Error("functionNumber must be between 0 and 28");
+        }
+        // define functionByte based on state
+        switch (state) {
+            case "on":
+                functionByte = 0x40;
+                break;
+            case "off":
+                functionByte = 0x00;
+                break;
+            case "toggle":
+                functionByte = 0x80;
+                break;
+            default:
+                throw new Error('state must be "on", "off" or "toggle"');
+        }
+        // Set the specific function bit
+        functionByte |= (1 << (functionNumber - 1)); // Set the bit corresponding to the function number
+        // Build the command payload
+        // E4 = set function command, 0x40 = LAN_X header, 0x00 = XpressNet command
+        // Payload format: [0x40, 0x00, 0xE4, addrH, addrL, functionByte]
+        const payload = [0x40, 0x00, 0xE4, 0xF8, addrH, addrL, functionByte];
+        await this.transport.sendCommand(payload);
+    }
+    /**
+     * Read a CV in direct mode.
+     * @param cv CV number (1-1024)
+     */
+    async cvRead(cv) {
+        return new Promise((resolve, reject) => {
+            const cvAddr = cv - 1;
+            const cvMsb = (cvAddr >> 8) & 0xFF;
+            const cvLsb = cvAddr & 0xFF;
+            // Build XpressNet frame: [0x23, 0x11, cvMsb, cvLsb]
+            const xpressNetFrame = [0x23, 0x11, cvMsb, cvLsb];
+            let xor = 0;
+            for (const byte of xpressNetFrame)
+                xor ^= byte;
+            xpressNetFrame.push(xor);
+            // LAN_X header: [0x40, 0x00]
+            const payload = [0x40, 0x00, ...xpressNetFrame];
+            this.transport.sendCommand(payload);
+            this.transport.on("cvResult", (msg) => {
+                if (msg.cv === cv) {
+                    resolve(msg);
+                }
+            });
+            this.transport.on("error", (msg) => {
+                if (msg.code === "nack" || msg.code === "nack-sc") {
+                    reject(msg);
+                }
+            });
+        });
+    }
+    /**
+     * Write a CV in direct mode.
+     * @param cv CV number (1-1024)
+     * @param value Value to write (0-255)
+     */
+    async cvWrite(cv, value) {
+        return new Promise((resolve, reject) => {
+            // CVs are 1-based in docs, but 0-based in protocol
+            const cvAddr = cv - 1;
+            const cvMsb = (cvAddr >> 8) & 0xFF;
+            const cvLsb = cvAddr & 0xFF;
+            // Build XpressNet frame: [0x24, 0x12, cvMsb, cvLsb, value]
+            const xpressNetFrame = [0x24, 0x12, cvMsb, cvLsb, value];
+            // XOR checksum for XpressNet frame
+            let xor = 0;
+            for (const byte of xpressNetFrame)
+                xor ^= byte;
+            xpressNetFrame.push(xor);
+            // LAN_X header: [0x40, 0x00]
+            const payload = [0x40, 0x00, ...xpressNetFrame];
+            this.transport.sendCommand(payload);
+            this.transport.on("cvResult", (msg) => {
+                if (msg.cv === cv) {
+                    resolve(msg);
+                }
+            });
+            this.transport.on("error", (msg) => {
+                if (msg.code === "nack" || msg.code === "nack-sc") {
+                    reject(msg);
+                }
+            });
+        });
+    }
+}
+exports.EngineController = EngineController;

package/dist/controllers/SystemController.d.ts

@@ -0,0 +1,22 @@
+import { Z21UdpTransport } from "../transport/Z21UdpTransport";
+export declare class SystemController {
+    private transport;
+    constructor(transport: Z21UdpTransport);
+    /** Enable engine, accessory and feedback broadcast info */
+    setBroadcastFlags(engine?: boolean, accessory?: boolean, feedback?: boolean): Promise<void>;
+    /** Request Z21 serial number */
+    getSerialNumber(): Promise<void>;
+    /** Request current broadcast flags */
+    getBroadcastFlags(): Promise<void>;
+    /** Request Z21 status */
+    getStatus(): Promise<void>;
+    /** Turn track power on */
+    setTrackPowerOn(): Promise<void>;
+    /** Turn track power off */
+    setTrackPowerOff(): Promise<void>;
+    /** Emergency stop all engines */
+    emergencyStop(): Promise<void>;
+    /** Logout from Z21 */
+    logout(): Promise<void>;
+    delay(ms: number): Promise<unknown>;
+}

package/dist/controllers/SystemController.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemController = void 0;
+const Z21Commands_1 = require("../Z21Commands");
+class SystemController {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Enable engine, accessory and feedback broadcast info */
+    async setBroadcastFlags(engine = true, accessory = true, feedback = true) {
+        let flags = 0;
+        if (engine)
+            flags |= 0x01;
+        if (accessory)
+            flags |= 0x02;
+        if (feedback)
+            flags |= 0x04;
+        // Flags on 4 bytes (Little Endian)
+        const payload = [
+            ...Z21Commands_1.commands.LAN_SET_BROADCAST_FLAGS,
+            flags, 0x00, 0x00, 0x00
+        ];
+        await this.transport.sendCommand(payload);
+    }
+    /** Request Z21 serial number */
+    async getSerialNumber() {
+        await this.transport.sendCommand(Z21Commands_1.commands.LAN_GET_SERIAL_NUMBER);
+    }
+    /** Request current broadcast flags */
+    async getBroadcastFlags() {
+        await this.transport.sendCommand(Z21Commands_1.commands.LAN_GET_BROADCAST_FLAGS);
+    }
+    /** Request Z21 status */
+    async getStatus() {
+        await this.transport.sendCommand(Z21Commands_1.commands.LAN_X_GET_STATUS);
+    }
+    /** Turn track power on */
+    async setTrackPowerOn() {
+        await this.transport.sendCommand(Z21Commands_1.commands.LAN_X_TRACK_POWER_ON);
+    }
+    /** Turn track power off */
+    async setTrackPowerOff() {
+        await this.transport.sendCommand(Z21Commands_1.commands.LAN_X_TRACK_POWER_OFF);
+    }
+    /** Emergency stop all engines */
+    async emergencyStop() {
+        await this.transport.sendCommand(Z21Commands_1.commands.LAN_X_SET_STOP);
+    }
+    /** Logout from Z21 */
+    async logout() {
+        await this.transport.sendCommand(Z21Commands_1.commands.LAN_LOGOFF);
+        this.delay(500); // Wait for logoff to complete
+    }
+    async delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.SystemController = SystemController;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { Z21Client } from "./Z21Client";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Z21Client = void 0;
+var Z21Client_1 = require("./Z21Client");
+Object.defineProperty(exports, "Z21Client", { enumerable: true, get: function () { return Z21Client_1.Z21Client; } });

package/dist/parsers/commandStationStatus.d.ts

@@ -0,0 +1,7 @@
+export declare const CS_STATUS: {
+    readonly CS_EMERGENCY_STOP: 1;
+    readonly CS_TRACK_VOLTAGE_OFF: 2;
+    readonly CS_SHORT_CIRCUIT: 4;
+    readonly CS_PROGRAMMING_MODE_ACTIVE: 32;
+};
+export type CommandStationStatusFlag = typeof CS_STATUS[keyof typeof CS_STATUS];

package/dist/parsers/commandStationStatus.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CS_STATUS = void 0;
+exports.CS_STATUS = {
+    CS_EMERGENCY_STOP: 0x01, // The emergency stop is switched on
+    CS_TRACK_VOLTAGE_OFF: 0x02, // The track voltage is switched off
+    CS_SHORT_CIRCUIT: 0x04, // Short-circuit
+    CS_PROGRAMMING_MODE_ACTIVE: 0x20 // The programming mode is active
+};

package/dist/parsers/feedbackParser.d.ts

@@ -0,0 +1,7 @@
+import { ParserResult } from "./parserResult";
+export declare class FeedbackParser {
+    private lanParser;
+    private lanXParser;
+    constructor();
+    parse(payload: Buffer): ParserResult | null;
+}

package/dist/parsers/feedbackParser.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeedbackParser = void 0;
+const lanXParser_1 = require("./lanXParser");
+const lanParser_1 = require("./lanParser");
+class FeedbackParser {
+    constructor() {
+        this.lanParser = new lanParser_1.LanParser();
+        this.lanXParser = new lanXParser_1.LanXParser();
+    }
+    parse(payload) {
+        if (!Buffer.isBuffer(payload) || payload.length < 2) {
+            return {
+                type: "error",
+                value: {
+                    code: "invalid-payload",
+                    message: "Invalid payload length"
+                }
+            };
+        }
+        // Expected length is indicated in the first two bytes
+        const expectedLength = payload.readUInt16LE(0);
+        if (payload.length < expectedLength) {
+            return {
+                type: "error",
+                value: {
+                    code: "invalid-payload",
+                    message: "Payload shorter than expected length"
+                }
+            };
+        }
+        // Buffer without the first 2 bytes (length)
+        const data = Buffer.from(payload.subarray(2));
+        if (data[0] === 0x40) {
+            // LAN_X command: remove first 2 bytes of LAN_X header
+            return this.lanXParser.parse(Buffer.from(data.subarray(2)));
+        }
+        else if (data[0] === 0x10 || data[0] === 0x51) {
+            // LAN command
+            return this.lanParser.parse(data[0], data.subarray(2));
+        }
+        return null;
+    }
+}
+exports.FeedbackParser = FeedbackParser;

package/dist/parsers/lanParser.d.ts

@@ -0,0 +1,11 @@
+import { ParserResult } from "./parserResult";
+export declare class LanParser {
+    /**
+     * Parse Z21 LAN commands (0x40 command class).
+     * These are non-LAN_X commands like serial number, hardware info, etc.
+     * @param opcode - LAN command opcode
+     * @param payload - Data after the opcode
+     * @returns Parsed object or undefined if payload is invalid/unknown opcode
+     */
+    parse(opcode: number, payload: Buffer): ParserResult | null;
+}

package/dist/parsers/lanParser.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LanParser = void 0;
+class LanParser {
+    /**
+     * Parse Z21 LAN commands (0x40 command class).
+     * These are non-LAN_X commands like serial number, hardware info, etc.
+     * @param opcode - LAN command opcode
+     * @param payload - Data after the opcode
+     * @returns Parsed object or undefined if payload is invalid/unknown opcode
+     */
+    parse(opcode, payload) {
+        switch (opcode) {
+            case 0x10: // GET_SERIAL_NUMBER
+                if (payload.length === 4) {
+                    const serialNumber = payload.readUInt32LE(0);
+                    return { type: "serialNumber", value: { "serialNumber": serialNumber } };
+                }
+                else {
+                    console.log("[LAN Parser] Wrong Payload for GET_SERIAL_NUMBER");
+                    return null;
+                }
+            case 0x51: // GET_BROADCAST_FLAGS
+                if (payload.length >= 4) {
+                    const flags = payload.readUInt32LE(0);
+                    return {
+                        type: "broadcastFlags",
+                        value: {
+                            raw: flags,
+                            engine: !!(flags & 0x01),
+                            accessory: !!(flags & 0x02),
+                            feedback: !!(flags & 0x04),
+                        },
+                    };
+                }
+                else {
+                    console.log("[LAN Parser] Payload too short for GET_BROADCAST_FLAGS");
+                    return null;
+                }
+            default:
+                return null;
+        }
+    }
+}
+exports.LanParser = LanParser;

package/dist/parsers/lanXParser.d.ts

@@ -0,0 +1,11 @@
+import { ParserResult } from "./parserResult";
+/**
+ * Parser for LAN_X commands (0x40 command class).
+ * Handles status changes, broadcasts, turnout info, and engine info.
+ */
+export declare class LanXParser {
+    parse(payload: Buffer): ParserResult | null;
+    private parseTurnoutInfo;
+    private parseEngineInfo;
+    private parseCV;
+}

package/dist/parsers/lanXParser.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LanXParser = void 0;
+const lanXReturnCodes_1 = require("./lanXReturnCodes");
+const commandStationStatus_1 = require("./commandStationStatus");
+/**
+ * Parser for LAN_X commands (0x40 command class).
+ * Handles status changes, broadcasts, turnout info, and engine info.
+ */
+class LanXParser {
+    parse(payload) {
+        const opcode = payload[0];
+        switch (opcode) {
+            case 0x62: // LAN_X_STATUS_CHANGED
+                if (payload[1] === 0x22) {
+                    const statusMap = {
+                        [commandStationStatus_1.CS_STATUS.CS_EMERGENCY_STOP]: "Emergency Stop Activated",
+                        [commandStationStatus_1.CS_STATUS.CS_TRACK_VOLTAGE_OFF]: "Track Voltage Off",
+                        [commandStationStatus_1.CS_STATUS.CS_SHORT_CIRCUIT]: "Short Circuit",
+                        [commandStationStatus_1.CS_STATUS.CS_PROGRAMMING_MODE_ACTIVE]: "Programming Mode Active",
+                    };
+                    const status = statusMap[payload[2]] ?? "Unknown Status";
+                    return { type: "status", value: status };
+                }
+                break;
+            case 0x61: // LAN_X_BROADCAST
+                switch (payload[1]) {
+                    case lanXReturnCodes_1.LAN_X_BC_CODES.LAN_X_BC_TRACK_POWER_OFF:
+                        return { type: "trackPower", value: "off" };
+                    case lanXReturnCodes_1.LAN_X_BC_CODES.LAN_X_BC_TRACK_POWER_ON:
+                        return { type: "trackPower", value: "on" };
+                    case lanXReturnCodes_1.LAN_X_BC_CODES.LAN_X_BC_PROGRAMMING_MODE:
+                        return { type: "programmingMode", value: "active" };
+                    case lanXReturnCodes_1.LAN_X_BC_CODES.LAN_X_BC_TRACK_SHORT_CIRCUIT:
+                        return { type: "shortCircuit", value: "detected" };
+                    case lanXReturnCodes_1.LAN_X_BC_CODES.LAN_X_CV_NACK:
+                        return {
+                            type: "error", value: {
+                                code: "nack",
+                                message: "CV Read/Write NACK"
+                            }
+                        };
+                    case lanXReturnCodes_1.LAN_X_BC_CODES.LAN_X_CV_NACK_SC:
+                        return {
+                            type: "error", value: {
+                                code: "nack-sc",
+                                message: "CV Read/Write NACK due to short-circuit"
+                            }
+                        };
+                    default:
+                        console.warn(`[LAN_X Parser] Unknown broadcast code: 0x${payload[1].toString(16)}`);
+                        return { type: "unknownBroadcast", value: payload[1] };
+                }
+            case 0x64: // LAN_X_CV_RESULT
+                if (payload[1] === 0x14) {
+                    return this.parseCV(payload);
+                }
+                break;
+            case 0x43: // LAN_X_TURNOUT_INFO
+                return this.parseTurnoutInfo(payload.subarray(1));
+            case 0xEF: // LAN_X_ENGINE_INFO
+                return this.parseEngineInfo(payload.subarray(1));
+            default:
+                console.warn(`[LAN_X Parser] Unknown opcode: 0x${opcode.toString(16)}`);
+                return null;
+        }
+        return null;
+    }
+    parseTurnoutInfo(payload) {
+        const adrMsb = payload[0] & 0x3F;
+        const adrLsb = payload[1];
+        const turnoutAddress = ((adrMsb << 8) + adrLsb) + 1;
+        const turnoutStatus = payload[2] & 0b11;
+        let position;
+        switch (turnoutStatus) {
+            case 0b00:
+                position = "not_switched";
+                break;
+            case 0b01:
+                position = "P0";
+                break;
+            case 0b10:
+                position = "P1";
+                break;
+            default:
+                position = "invalid";
+        }
+        return { type: "accessoryInfo", value: { address: turnoutAddress, position } };
+    }
+    parseEngineInfo(payload) {
+        const adrMsb = payload[0] & 0x3F;
+        const adrLsb = payload[1];
+        const engineAddress = (adrMsb << 8) + adrLsb;
+        const db2 = payload[2];
+        const busy = (db2 & 0b00001000) !== 0;
+        const kkk = db2 & 0b00000111;
+        let speedSteps;
+        switch (kkk) {
+            case 0:
+                speedSteps = 14;
+                break;
+            case 2:
+                speedSteps = 28;
+                break;
+            case 4:
+                speedSteps = 128;
+                break;
+            default:
+                speedSteps = "unknown";
+        }
+        const db3 = payload[3];
+        const direction = (db3 & 0x80) ? "forward" : "reverse";
+        const speed = db3 & 0x7F;
+        const db4 = payload[4];
+        const doubleTraction = (db4 & 0b01000000) !== 0;
+        const functions = {
+            F0: (db4 & 0b00010000) !== 0,
+            F1: (db4 & 0b00000001) !== 0,
+            F2: (db4 & 0b00000010) !== 0,
+            F3: (db4 & 0b00000100) !== 0,
+            F4: (db4 & 0b00001000) !== 0,
+        };
+        if (payload.length > 5) {
+            for (let i = 0; i < 8; i++)
+                functions[`F${5 + i}`] = (payload[5] & (1 << i)) !== 0;
+        }
+        if (payload.length > 6) {
+            for (let i = 0; i < 8; i++)
+                functions[`F${13 + i}`] = (payload[6] & (1 << i)) !== 0;
+        }
+        if (payload.length > 7) {
+            for (let i = 0; i < 8; i++)
+                functions[`F${21 + i}`] = (payload[7] & (1 << i)) !== 0;
+        }
+        if (payload.length > 8) {
+            for (let i = 0; i < 3; i++)
+                functions[`F${29 + i}`] = (payload[8] & (1 << i)) !== 0;
+        }
+        return {
+            type: "engineInfo",
+            value: {
+                address: engineAddress,
+                busy,
+                speedSteps,
+                direction,
+                speed,
+                doubleTraction,
+                functions,
+            },
+        };
+    }
+    parseCV(payload) {
+        const cvMsb = payload[2];
+        const cvLsb = payload[3];
+        const value = payload[4];
+        const cvAddress = (cvMsb << 8) + cvLsb;
+        return {
+            type: "cvResult",
+            value: {
+                cv: cvAddress + 1, // CVs are 1-based for user
+                value,
+            },
+        };
+    }
+}
+exports.LanXParser = LanXParser;

package/dist/parsers/lanXReturnCodes.d.ts

@@ -0,0 +1,9 @@
+export declare const LAN_X_BC_CODES: {
+    readonly LAN_X_BC_TRACK_POWER_OFF: 0;
+    readonly LAN_X_BC_TRACK_POWER_ON: 1;
+    readonly LAN_X_BC_PROGRAMMING_MODE: 2;
+    readonly LAN_X_BC_TRACK_SHORT_CIRCUIT: 8;
+    readonly LAN_X_CV_NACK_SC: 18;
+    readonly LAN_X_CV_NACK: 19;
+};
+export type LanXBCCode = typeof LAN_X_BC_CODES[keyof typeof LAN_X_BC_CODES];

package/dist/parsers/lanXReturnCodes.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAN_X_BC_CODES = void 0;
+exports.LAN_X_BC_CODES = {
+    LAN_X_BC_TRACK_POWER_OFF: 0x00, // Track power off
+    LAN_X_BC_TRACK_POWER_ON: 0x01, // Track power on
+    LAN_X_BC_PROGRAMMING_MODE: 0x02, // Programming mode active
+    LAN_X_BC_TRACK_SHORT_CIRCUIT: 0x08, // Track short-circuit
+    LAN_X_CV_NACK_SC: 0x12, // CV Read Write NACK short-circuit
+    LAN_X_CV_NACK: 0x13, // CV Read Write NACK
+};

package/dist/parsers/parserResult.d.ts

@@ -0,0 +1,80 @@
+export interface ErrorResult {
+    type: "error";
+    value: ErrorResultData;
+}
+export interface ErrorResultData {
+    code: "invalid-payload" | "nack" | "nack-sc";
+    message: string;
+}
+export interface SerialNumberResult {
+    type: "serialNumber";
+    value: SerialNumberResultData;
+}
+export interface SerialNumberResultData {
+    serialNumber: number;
+}
+export interface BroadcastFlagsResult {
+    type: "broadcastFlags";
+    value: BroadcastFlagsResultData;
+}
+export interface BroadcastFlagsResultData {
+    raw: number;
+    engine: boolean;
+    accessory: boolean;
+    feedback: boolean;
+}
+export type StatusValue = "Emergency Stop Activated" | "Track Voltage Off" | "Short Circuit" | "Programming Mode Active" | "Unknown Status";
+export type SpeedSteps = 14 | 28 | 128 | "unknown";
+export interface StatusResult {
+    type: "status";
+    value: StatusValue;
+}
+export interface TrackPowerResult {
+    type: "trackPower";
+    value: "on" | "off";
+}
+export interface ProgrammingModeResult {
+    type: "programmingMode";
+    value: "active" | "inactive";
+}
+export interface ShortCircuitResult {
+    type: "shortCircuit";
+    value: "detected";
+}
+export interface UnknownBroadcastResult {
+    type: "unknownBroadcast";
+    value: number;
+}
+export interface AccessoryInfoResult {
+    type: "accessoryInfo";
+    value: AccessoryInfoResultData;
+}
+export interface AccessoryInfoResultData {
+    address: number;
+    position: "not_switched" | "P0" | "P1" | "invalid";
+}
+export interface EngineInfoResult {
+    type: "engineInfo";
+    value: EngineInfoResultData;
+}
+export interface EngineInfoResultData {
+    address: number;
+    busy: boolean;
+    speedSteps: SpeedSteps;
+    direction: "forward" | "reverse";
+    speed: number;
+    doubleTraction: boolean;
+    functions: Record<string, boolean>;
+}
+export interface CvResult {
+    type: "cvResult";
+    value: CvResultData;
+}
+export interface CvResultData {
+    cv: number;
+    value: number;
+}
+/**
+ * Union type for all possible results
+ */
+export type ParserResult = ErrorResult | SerialNumberResult | BroadcastFlagsResult | StatusResult | TrackPowerResult | ProgrammingModeResult | ShortCircuitResult | UnknownBroadcastResult | AccessoryInfoResult | EngineInfoResult | CvResult;

package/dist/parsers/parserResult.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/transport/Z21UdpTransport.d.ts

@@ -0,0 +1,34 @@
+import { EventEmitter } from "events";
+import { FeedbackParser } from "../parsers/feedbackParser";
+export declare class Z21UdpTransport extends EventEmitter {
+    private socket;
+    private host;
+    private port;
+    private debug;
+    private feedbackParser;
+    constructor(host: string, port: number | undefined, debug: boolean | undefined, feedbackParser: FeedbackParser);
+    /**
+     * Handle incoming UDP messages, parse and emit events.
+     * @param msg Incoming UDP message buffer
+     */
+    private handleMessage;
+    /**
+     * Build a Z21 frame.
+     * Frame format: [length (2 bytes LE)+[payload...]
+     * Length includes entire frame length (header + payload).
+     * @param payload Command bytes after header
+     * @returns Buffer frame to send
+     */
+    private buildFrame;
+    /**
+     * Send a command frame asynchronously.
+     * @param payload Command payload bytes
+     */
+    sendCommand(payload: number[]): Promise<void>;
+    /**
+     * Send UDP frame and return Promise.
+     * @param frame Buffer to send
+     */
+    private sendFrame;
+    close(): void;
+}

package/dist/transport/Z21UdpTransport.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Z21UdpTransport = void 0;
+const dgram_1 = __importDefault(require("dgram"));
+const events_1 = require("events");
+class Z21UdpTransport extends events_1.EventEmitter {
+    constructor(host, port = 21105, debug = false, feedbackParser) {
+        super();
+        this.host = host;
+        this.port = port;
+        this.debug = debug;
+        this.socket = dgram_1.default.createSocket("udp4");
+        this.feedbackParser = feedbackParser;
+        // Listen to incoming UDP messages
+        this.socket.on("message", (msg) => this.handleMessage(msg));
+        // Handle UDP errors
+        this.socket.on("error", (err) => {
+            console.log(`[Z21UdpTransport] UDP socket error: ${err.message}`);
+            this.emit("error", err);
+            this.close();
+        });
+        if (this.debug) {
+            console.log(`[Z21UdpTransport] Init`);
+        }
+    }
+    /**
+     * Handle incoming UDP messages, parse and emit events.
+     * @param msg Incoming UDP message buffer
+     */
+    handleMessage(msg) {
+        if (this.debug) {
+            this.emit("debug", msg);
+        }
+        const parsed = this.feedbackParser.parse(msg);
+        if (parsed) {
+            this.emit(parsed.type, parsed.value);
+        }
+    }
+    /**
+     * Build a Z21 frame.
+     * Frame format: [length (2 bytes LE)+[payload...]
+     * Length includes entire frame length (header + payload).
+     * @param payload Command bytes after header
+     * @returns Buffer frame to send
+     */
+    buildFrame(payload) {
+        const length = payload.length + 2; // 2 bytes length
+        const buffer = Buffer.alloc(length);
+        buffer.writeUInt16LE(length, 0);
+        for (let i = 0; i < payload.length; i++) {
+            buffer[2 + i] = payload[i];
+        }
+        return buffer;
+    }
+    /**
+     * Send a command frame asynchronously.
+     * @param payload Command payload bytes
+     */
+    async sendCommand(payload) {
+        const frame = this.buildFrame(payload);
+        console.log(frame);
+        await this.sendFrame(frame);
+    }
+    /**
+     * Send UDP frame and return Promise.
+     * @param frame Buffer to send
+     */
+    sendFrame(frame) {
+        return new Promise((resolve, reject) => {
+            this.socket.send(frame, this.port, this.host, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    close() {
+        this.socket.close();
+    }
+}
+exports.Z21UdpTransport = Z21UdpTransport;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "z21-client",
+  "version": "1.0.0",
+  "description": "TypeScript UDP client for Roco/Fleischmann Z21 DCC command station",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nmeunier/z21-client.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node-dev --respawn exemples/index.ts",
+    "test": "jest",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "dcc",
+    "z21",
+    "roco",
+    "fleischmann",
+    "model-railway",
+    "model-train",
+    "railroad",
+    "train-control",
+    "locomotive",
+    "turnout",
+    "accessory",
+    "decoder",
+    "cv",
+    "udp",
+    "typescript",
+    "nodejs"
+  ],
+  "author": "Nicolas Meunier",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.39.0",
+    "@typescript-eslint/parser": "^8.39.0",
+    "eslint": "^9.33.0",
+    "eslint-plugin-jest": "^29.0.1",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.0.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}