feat(cli): add RFC 2217 serial port forwarding support #44

close #44

Author: urish

packages/cli/package.json

@@ -54,6 +54,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@wokwi/client": "workspace:*",
     "@wokwi/diagram-lint": "workspace:*",
+    "@wokwi/rfc2217": "workspace:*",
     "commander": "^12.1.0",
     "chalk": "^5.3.0",
     "chalk-template": "^1.1.0",

packages/cli/src/WokwiConfig.ts

@@ -9,6 +9,7 @@ export interface WokwiTOML {
     firmware: string;
     elf?: string;
     gdbServerPort?: number;
+    rfc2217ServerPort?: number;
   };
   chip?: WokwiTOMLChip[];
 }

packages/cli/src/commands/simulate.ts

@@ -5,6 +5,7 @@ import {
   type SerialMonitorDataPayload,
 } from '@wokwi/client';
 import { DiagramLinter } from '@wokwi/diagram-lint';
+import { RFC2217Server } from '@wokwi/rfc2217';
 import chalkTemplate from 'chalk-template';
 import type { Command } from 'commander';
 import { createWriteStream, existsSync, readFileSync, writeFileSync } from 'fs';
@@ -208,6 +209,7 @@ async function runSimulation(projectPath: string, options: SimulateOptions, comm
     displayLintResults(lintResult, { quiet });
   }
 
+  const rfc2217ServerPort = config?.wokwi.rfc2217ServerPort;
   const chips = loadChips(config?.chip ?? [], rootDir);
 
   const resolvedScenarioFile = scenarioFile ? path.resolve(rootDir, scenarioFile) : null;
@@ -248,6 +250,8 @@ async function runSimulation(projectPath: string, options: SimulateOptions, comm
     process.exit(1);
   };
 
+  let rfc2217Server: RFC2217Server | undefined;
+
   try {
     await client.connected;
     await client.fileUpload('diagram.json', diagram);
@@ -313,13 +317,38 @@ async function runSimulation(projectPath: string, options: SimulateOptions, comm
 
     await client.serialMonitorListen();
 
+    if (rfc2217ServerPort) {
+      rfc2217Server = new RFC2217Server();
+      rfc2217Server.on('error', (err) => {
+        console.error(`RFC 2217 server error: ${err}`);
+      });
+      rfc2217Server.on('connected', () => {
+        if (!quiet) {
+          console.log('RFC 2217 client connected');
+        }
+      });
+      rfc2217Server.on('data', (data) => {
+        void client.serialMonitorWrite(data);
+      });
+      rfc2217Server.listen(rfc2217ServerPort);
+      if (!quiet) {
+        console.log(`RFC 2217 server listening on port ${rfc2217ServerPort}`);
+      }
+    }
+
     client.listen('serial-monitor:data', (event: APIEvent<SerialMonitorDataPayload>) => {
       let { bytes } = event.payload;
       bytes = scenario?.processSerialBytes(bytes) ?? bytes;
       process.stdout.write(new Uint8Array(bytes));
 
       serialLogStream?.write(Buffer.from(bytes));
       expectEngine.feed(bytes);
+
+      if (rfc2217Server) {
+        for (const byte of bytes) {
+          rfc2217Server.write(byte);
+        }
+      }
     });
 
     client.listen('chips:log', (event: APIEvent<ChipsLogPayload>) => {
@@ -384,6 +413,7 @@ async function runSimulation(projectPath: string, options: SimulateOptions, comm
       }
     }
 
+    rfc2217Server?.dispose();
     client.close();
   }
 }

packages/rfc2217/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023-2026 Uri Shaked
+
+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.

packages/rfc2217/README.md

@@ -0,0 +1,58 @@
+# @wokwi/rfc2217
+
+RFC 2217 (Telnet Com Port Control) server implementation. Enables serial port forwarding over TCP, allowing tools like PySerial and `socat` to connect to simulated devices via `rfc2217://localhost:<port>`.
+
+## Installation
+
+```bash
+npm install @wokwi/rfc2217
+```
+
+## Usage
+
+```typescript
+import { RFC2217Server } from '@wokwi/rfc2217';
+
+const server = new RFC2217Server();
+
+server.on('connected', () => {
+  console.log('Client connected');
+});
+
+server.on('data', (data) => {
+  // Handle incoming serial data from the client
+  console.log('Received:', data);
+});
+
+server.on('control', ({ dtr, rts }) => {
+  console.log('Control signals:', { dtr, rts });
+});
+
+server.on('error', (err) => {
+  console.error('Server error:', err);
+});
+
+server.listen(4000);
+
+// Send data to all connected clients
+server.write(0x48); // 'H'
+
+// Clean up
+server.dispose();
+```
+
+## Connecting
+
+Once the server is listening, connect with any RFC 2217-compatible client:
+
+```bash
+# PySerial
+python -c "import serial; s = serial.serial_for_url('rfc2217://localhost:4000')"
+
+# socat
+socat - TCP:localhost:4000
+```
+
+## License
+
+[The MIT License (MIT)](LICENSE)

packages/rfc2217/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@wokwi/rfc2217",
+  "version": "1.0.0",
+  "description": "RFC 2217 (Telnet Com Port Control) server implementation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "vitest --run",
+    "test:watch": "vitest --watch"
+  },
+  "author": "Uri Shaked",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wokwi/wokwi-cli"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.2",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.2.2",
+    "vitest": "^3.0.5"
+  }
+}

packages/rfc2217/src/RFC2217Server.spec.ts

@@ -0,0 +1,92 @@
+import EventEmitter from 'events';
+import { describe, expect, it, vi } from 'vitest';
+import { RFC2217Server } from './RFC2217Server.js';
+
+function createMockSocket() {
+  const socket = Object.assign(new EventEmitter(), {
+    write: vi.fn(),
+    end: vi.fn(),
+    setNoDelay: vi.fn(),
+  });
+  return socket;
+}
+
+describe('RFC2217Server', () => {
+  it('should forward data from sockets to data event', () => {
+    const server = new RFC2217Server();
+    const received: Uint8Array[] = [];
+    server.on('data', (data) => received.push(data));
+
+    const socket = createMockSocket();
+    server.handleConnection(socket as any);
+
+    socket.emit('data', Buffer.from([0x48, 0x65]));
+
+    expect(received).toHaveLength(2);
+    expect(received[0]).toEqual(new Uint8Array([0x48]));
+    expect(received[1]).toEqual(new Uint8Array([0x65]));
+  });
+
+  it('should track DTR/RTS state and deduplicate control events', () => {
+    const server = new RFC2217Server();
+    const controls: { rts: boolean; dtr: boolean }[] = [];
+    server.on('control', (values) => controls.push({ ...values }));
+
+    const socket = createMockSocket();
+    server.handleConnection(socket as any);
+
+    // DTR_ON
+    socket.emit('data', Buffer.from([0xff, 0xfa, 44, 0x05, 0x08, 0xff, 0xf0]));
+    // DTR_ON again (should be deduplicated)
+    socket.emit('data', Buffer.from([0xff, 0xfa, 44, 0x05, 0x08, 0xff, 0xf0]));
+    // RTS_ON
+    socket.emit('data', Buffer.from([0xff, 0xfa, 44, 0x05, 0x0b, 0xff, 0xf0]));
+    // DTR_OFF
+    socket.emit('data', Buffer.from([0xff, 0xfa, 44, 0x05, 0x09, 0xff, 0xf0]));
+
+    expect(controls).toEqual([
+      { rts: false, dtr: true },
+      { rts: true, dtr: true },
+      { rts: true, dtr: false },
+    ]);
+  });
+
+  it('should broadcast write to all connected sockets', () => {
+    const server = new RFC2217Server();
+
+    const socket1 = createMockSocket();
+    const socket2 = createMockSocket();
+    server.handleConnection(socket1 as any);
+    server.handleConnection(socket2 as any);
+
+    server.write(0x42);
+
+    expect(socket1.write).toHaveBeenCalledWith(Buffer.from([0x42]));
+    expect(socket2.write).toHaveBeenCalledWith(Buffer.from([0x42]));
+  });
+
+  it('should remove socket on close', () => {
+    const server = new RFC2217Server();
+
+    const socket = createMockSocket();
+    server.handleConnection(socket as any);
+    expect(server.sockets.size).toBe(1);
+
+    socket.emit('close');
+    expect(server.sockets.size).toBe(0);
+  });
+
+  it('should dispose all sockets and server', () => {
+    const server = new RFC2217Server();
+    const serverClose = vi.fn(() => server.server);
+    server.server.close = serverClose;
+
+    const socket = createMockSocket();
+    server.handleConnection(socket as any);
+
+    server.dispose();
+
+    expect(socket.end).toHaveBeenCalled();
+    expect(serverClose).toHaveBeenCalled();
+  });
+});

packages/rfc2217/src/RFC2217Server.ts

@@ -0,0 +1,99 @@
+import EventEmitter from 'events';
+import { createServer, Socket, type Server } from 'net';
+import { ControlCode, RFC2217Socket } from './RFC2217Socket.js';
+
+export interface IControlPinValues {
+  rts: boolean;
+  dtr: boolean;
+}
+
+export class RFC2217Server extends EventEmitter {
+  readonly sockets = new Set<RFC2217Socket>();
+  readonly server: Server;
+
+  private rts: boolean = false;
+  private dtr: boolean = false;
+  private disposed = false;
+
+  constructor() {
+    super();
+    this.server = createServer();
+    this.server.on('connection', (socket) => this.handleConnection(socket));
+    this.server.on('error', (e: Error) => {
+      this.emit('error', e.toString());
+    });
+  }
+
+  listen(port = 4000) {
+    this.server.listen(port);
+  }
+
+  handleConnection(socket: Socket) {
+    socket.setNoDelay(true);
+    this.emit('connected');
+
+    const rfc2217 = new RFC2217Socket(socket);
+    this.sockets.add(rfc2217);
+
+    rfc2217.on('data', (data) => {
+      this.emit('data', new Uint8Array([data]));
+    });
+
+    rfc2217.on('control', (value) => {
+      if (value === ControlCode.RTS_ON && !this.rts) {
+        this.rts = true;
+        this.controlUpdated();
+      }
+      if (value === ControlCode.RTS_OFF && this.rts) {
+        this.rts = false;
+        this.controlUpdated();
+      }
+      if (value === ControlCode.DTR_ON && !this.dtr) {
+        this.dtr = true;
+        this.controlUpdated();
+      }
+      if (value === ControlCode.DTR_OFF && this.dtr) {
+        this.dtr = false;
+        this.controlUpdated();
+      }
+    });
+
+    socket.on('error', (err) => {
+      console.error('RFC 2217 socket error', err);
+    });
+
+    socket.on('close', () => {
+      this.sockets.delete(rfc2217);
+    });
+  }
+
+  private controlUpdated() {
+    this.emit('control', {
+      rts: this.rts,
+      dtr: this.dtr,
+    });
+  }
+
+  write(byte: number) {
+    for (const socket of this.sockets) {
+      try {
+        socket.write(byte);
+      } catch (err) {
+        console.warn(err);
+        this.sockets.delete(socket);
+      }
+    }
+  }
+
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+
+    for (const socket of this.sockets) {
+      socket.close();
+    }
+    this.server.close();
+    this.disposed = true;
+  }
+}