z21-client 1.1.0 → 1.1.2

package/README.md

@@ -1,5 +1,13 @@
 # z21-client
 
+[![npm version](https://img.shields.io/npm/v/z21-client)](https://www.npmjs.com/package/z21-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Tests](https://github.com/nmeunier/z21-client/workflows/Tests%20%26%20Build/badge.svg)](https://github.com/nmeunier/z21-client/actions)
+[![codecov](https://codecov.io/gh/nmeunier/z21-client/branch/main/graph/badge.svg)](https://codecov.io/gh/nmeunier/z21-client)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+
 z21-client is a Node.js library written in TypeScript that implements 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.
 Connection to the Z21 command station is performed over the LAN (Ethernet/UDP).

package/dist/Z21Client.d.ts

@@ -14,5 +14,8 @@ export declare class Z21Client extends EventEmitter {
      * @param debug Enable debug mode (default: false).
      */
     constructor(host: string, port?: number, debug?: boolean);
+    /**
+     * Close the Z21Client connection.
+     */
     close(): Promise<void>;
 }

package/dist/Z21Client.js

@@ -34,11 +34,15 @@ class Z21Client extends events_1.EventEmitter {
         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("feedback", (msg) => this.emit("feedback", msg));
         this.transport.on("error", (err) => this.emit("error", err));
         if (debug) {
-            console.log(`[Z21Client] Init`);
+            console.log("[Z21Client] Init");
         }
     }
+    /**
+     * Close the Z21Client connection.
+     */
     async close() {
         await this.system.logout();
         await this.transport.close();

package/dist/controllers/EngineController.js

@@ -48,7 +48,7 @@ class EngineController {
             steps = 0x10; // DCC14 for 14-speed
         }
         // XpressNet frame: E4 = drive engine command
-        let xpressNetFrame = [0xE4, steps, addrH, addrL, speedByte];
+        const xpressNetFrame = [0xE4, steps, addrH, addrL, speedByte];
         // --- Calculate XOR checksum ---
         let xor = 0;
         for (const byte of xpressNetFrame) {
@@ -86,10 +86,13 @@ class EngineController {
                 functionByte = 0x80;
                 break;
             default:
-                throw new Error('state must be "on", "off" or "toggle"');
+                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
+        // Set function number in bits 0-5 per Z21 LAN protocol specification
+        // See: Z21 LAN Protocol v1.13, Section 4.2 (LAN_X_SET_LOCO_FUNCTION)
+        // DB3 byte format: bits 7-6 = switch type (00=off, 01=on, 10=toggle), bits 5-0 = function index
+        // Reference: https://www.z21.eu/media/Kwc_Basic_DownloadTag_Component/root-en-main_47-702/default/69bad87e/1712141518/z21-lan-protokoll-en.pdf
+        functionByte |= (functionNumber & 0x3F);
         // Build the command payload
         // E4 = set function command, 0x40 = LAN_X header, 0x00 = XpressNet command
         // Payload format: [0x40, 0x00, 0xE4, addrH, addrL, functionByte]
@@ -113,16 +116,36 @@ class EngineController {
             xpressNetFrame.push(xor);
             // LAN_X header: [0x40, 0x00]
             const payload = [0x40, 0x00, ...xpressNetFrame];
-            this.transport.sendCommand(payload);
-            this.transport.on("cvResult", (msg) => {
+            const timeoutMs = 30000; // 30 seconds
+            let timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("cvRead timeout"));
+            }, timeoutMs);
+            const onCv = (msg) => {
                 if (msg.cv === cv) {
+                    cleanup();
                     resolve(msg);
                 }
-            });
-            this.transport.on("error", (msg) => {
+            };
+            const onError = (msg) => {
                 if (msg.code === "nack" || msg.code === "nack-sc") {
+                    cleanup();
                     reject(msg);
                 }
+            };
+            const cleanup = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+                this.transport.removeListener("cvResult", onCv);
+                this.transport.removeListener("error", onError);
+            };
+            this.transport.on("cvResult", onCv);
+            this.transport.on("error", onError);
+            this.transport.sendCommand(payload).catch((err) => {
+                cleanup();
+                reject(err);
             });
         });
     }
@@ -146,16 +169,36 @@ class EngineController {
             xpressNetFrame.push(xor);
             // LAN_X header: [0x40, 0x00]
             const payload = [0x40, 0x00, ...xpressNetFrame];
-            this.transport.sendCommand(payload);
-            this.transport.on("cvResult", (msg) => {
+            const timeoutMs = 30000; // 30 seconds
+            let timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("cvWrite timeout"));
+            }, timeoutMs);
+            const onCv = (msg) => {
                 if (msg.cv === cv) {
+                    cleanup();
                     resolve(msg);
                 }
-            });
-            this.transport.on("error", (msg) => {
+            };
+            const onError = (msg) => {
                 if (msg.code === "nack" || msg.code === "nack-sc") {
+                    cleanup();
                     reject(msg);
                 }
+            };
+            const cleanup = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+                this.transport.removeListener("cvResult", onCv);
+                this.transport.removeListener("error", onError);
+            };
+            this.transport.on("cvResult", onCv);
+            this.transport.on("error", onError);
+            this.transport.sendCommand(payload).catch((err) => {
+                cleanup();
+                reject(err);
             });
         });
     }

package/dist/parsers/feedbackParser.js

@@ -35,7 +35,7 @@ class FeedbackParser {
             // 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) {
+        else if (data[0] === 0x10 || data[0] === 0x51 || data[0] === 0x80) {
             // LAN command
             return this.lanParser.parse(data[0], data.subarray(2));
         }

package/dist/parsers/lanParser.js

@@ -37,6 +37,31 @@ class LanParser {
                     console.log("[LAN Parser] Payload too short for GET_BROADCAST_FLAGS");
                     return null;
                 }
+            case 0x80: // LAN_RMBUS_DATACHANGED
+                // Structure: [groupIndex (1 byte), feedback status (10 bytes)]
+                if (payload.length >= 11) {
+                    const groupIndex = payload[0];
+                    const feedbackStatus = payload.subarray(1, 11); // 10 bytes
+                    const feedbacks = [];
+                    for (let i = 0; i < 10; i++) {
+                        const moduleAddress = groupIndex * 10 + (i + 1);
+                        const byte = feedbackStatus[i];
+                        if (byte) {
+                            const activeInputs = [];
+                            for (let bit = 0; bit < 8; bit++) {
+                                if (byte & (1 << bit)) {
+                                    activeInputs.push(bit + 1);
+                                }
+                            }
+                            feedbacks.push({ address: moduleAddress, activeInputs });
+                        }
+                    }
+                    return {
+                        type: "feedback",
+                        value: feedbacks
+                    };
+                }
+                return null;
             default:
                 return null;
         }

package/dist/parsers/lanXParser.js

@@ -112,6 +112,7 @@ class LanXParser {
         const direction = (db3 & 0x80) ? "forward" : "reverse";
         const speed = db3 & 0x7F;
         const db4 = payload[4];
+        // Not officially documented in Z21/LAN_X protocol; may always be false
         const doubleTraction = (db4 & 0b01000000) !== 0;
         const functions = {
             F0: (db4 & 0b00010000) !== 0,

package/dist/parsers/parserResult.d.ts

@@ -74,7 +74,15 @@ export interface CvResultData {
     cv: number;
     value: number;
 }
+export interface FeedbackModuleStatus {
+    address: number;
+    activeInputs: number[];
+}
+export interface FeedbackResult {
+    type: "feedback";
+    value: FeedbackModuleStatus[];
+}
 /**
  * Union type for all possible results
  */
-export type ParserResult = ErrorResult | SerialNumberResult | BroadcastFlagsResult | StatusResult | TrackPowerResult | ProgrammingModeResult | ShortCircuitResult | UnknownBroadcastResult | AccessoryInfoResult | EngineInfoResult | CvResult;
+export type ParserResult = ErrorResult | SerialNumberResult | BroadcastFlagsResult | StatusResult | TrackPowerResult | ProgrammingModeResult | ShortCircuitResult | UnknownBroadcastResult | AccessoryInfoResult | EngineInfoResult | CvResult | FeedbackResult;

package/dist/transport/Z21UdpTransport.js

@@ -23,7 +23,7 @@ class Z21UdpTransport extends events_1.EventEmitter {
             this.close();
         });
         if (this.debug) {
-            console.log(`[Z21UdpTransport] Init`);
+            console.log("[Z21UdpTransport] Init");
         }
     }
     /**
@@ -61,7 +61,6 @@ class Z21UdpTransport extends events_1.EventEmitter {
      */
     async sendCommand(payload) {
         const frame = this.buildFrame(payload);
-        console.log(frame);
         await this.sendFrame(frame);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "z21-client",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "TypeScript UDP client for Roco/Fleischmann Z21 DCC command station",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "ts-node-dev --respawn exemples/index.ts",
+    "lint": "eslint 'src/**/*.{ts,js}' --ext .ts",
     "test": "jest",
     "test:coverage": "jest --coverage"
   },