feat: vcd export for logic analyzer data

Author: urish

README.md

@@ -36,6 +36,14 @@ cd esp-idf-hello-world
 wokwi-cli .
 ```
 
+### Logic Analyzer VCD Export
+
+If your diagram includes a [logic analyzer](https://docs.wokwi.com/parts/wokwi-logic-analyzer), you can export the captured signals to a VCD file:
+
+```bash
+wokwi-cli . --vcd-file logic.vcd
+```
+
 ## Configuration Wizard
 
 To generate a `wokwi.toml` and a default `diagram.json` files for your project, run:

packages/cli/src/commands/simulate.ts

@@ -46,6 +46,7 @@ interface SimulateOptions {
   screenshotFile?: string;
   timeoutExitCode?: string;
   quiet?: boolean;
+  vcdFile?: string;
 }
 
 export function simulateCommand(program: Command): void {
@@ -64,6 +65,7 @@ export function simulateCommand(program: Command): void {
     .option('--screenshot-file <path>', 'Screenshot output file', 'screenshot.png')
     .option('--timeout-exit-code <code>', 'Exit code on timeout', '42')
     .option('-q, --quiet', 'Suppress status messages')
+    .option('--vcd-file <path>', 'Output path for VCD (logic analyzer) file')
     .action((projectPath: string, options: SimulateOptions, command: Command) => {
       return runSimulation(projectPath, options, command);
     });
@@ -96,6 +98,7 @@ async function runSimulation(projectPath: string, options: SimulateOptions, comm
   const screenshotFile = options.screenshotFile ?? 'screenshot.png';
   const timeoutExitCode = parseInt(options.timeoutExitCode ?? '42', 10);
   const timeoutNanos = timeout * millis;
+  const vcdFile = options.vcdFile;
 
   const token = requireToken();
 
@@ -351,6 +354,23 @@ async function runSimulation(projectPath: string, options: SimulateOptions, comm
     // wait for the screenshot to be saved, if any
     await screenshotPromise;
   } finally {
+    // Export VCD if requested
+    if (vcdFile) {
+      try {
+        const result = await client.readVCD();
+        if (result.sampleCount > 0) {
+          writeFileSync(vcdFile, result.vcd);
+          if (!quiet) {
+            console.log(`VCD file written to: ${vcdFile}`);
+          }
+        } else if (!quiet) {
+          console.log('No logic analyzer data to export');
+        }
+      } catch (err) {
+        console.error('Error exporting VCD:', (err as Error).message);
+      }
+    }
+
     client.close();
   }
 }

packages/cli/src/mcp/SimulationManager.ts

@@ -1,5 +1,5 @@
-import { APIClient, SerialMonitorDataPayload, type APIEvent } from '@wokwi/client';
-import { existsSync, readFileSync } from 'fs';
+import { APIClient, SerialMonitorDataPayload, type APIEvent, type VCDReadResponse } from '@wokwi/client';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import path from 'path';
 import { parseConfig } from '../config.js';
 import { DEFAULT_SERVER } from '../constants.js';
@@ -209,6 +209,18 @@ export class SimulationManager {
     return result.png;
   }
 
+  async exportVCD(outputPath: string): Promise<VCDReadResponse> {
+    if (!this.client) {
+      throw new Error('Not connected to simulation');
+    }
+
+    const result = await this.client.readVCD();
+    if (result.sampleCount > 0) {
+      writeFileSync(outputPath, result.vcd);
+    }
+    return result;
+  }
+
   async cleanup(): Promise<void> {
     if (this.client) {
       this.client.close();

packages/cli/src/mcp/WokwiMCPTools.ts

@@ -133,6 +133,20 @@ export class WokwiMCPTools {
           required: ['partId'],
         },
       },
+      {
+        name: 'wokwi_export_vcd',
+        description: 'Export logic analyzer data as VCD (Value Change Dump) file',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            outputPath: {
+              type: 'string',
+              description: 'Path where VCD file will be saved',
+            },
+          },
+          required: ['outputPath'],
+        },
+      },
     ];
   }
 
@@ -229,6 +243,20 @@ export class WokwiMCPTools {
           };
         }
 
+        case 'wokwi_export_vcd': {
+          const result = await this.simulationManager.exportVCD(args.outputPath);
+          return {
+            content: [
+              {
+                type: 'text',
+                text: result.sampleCount > 0
+                  ? `VCD exported to: ${args.outputPath} (${result.sampleCount} samples, ${result.channelCount} channels)`
+                  : 'No logic analyzer data to export',
+              },
+            ],
+          };
+        }
+
         default:
           throw new Error(`Unknown tool: ${name}`);
       }

packages/client/src/APIClient.ts

@@ -7,6 +7,7 @@ import type {
   APIResultError,
   APISimStartParams,
   PinReadResponse,
+  VCDReadResponse,
 } from './APITypes.js';
 import { base64ToByteArray, byteArrayToBase64 } from './base64.js';
 import { PausePoint, type PausePointParams } from './PausePoint.js';
@@ -131,6 +132,10 @@ export class APIClient {
     });
   }
 
+  async readVCD() {
+    return await this.sendCommand<VCDReadResponse>('sim:read-vcd');
+  }
+
   async addPausePoint(params: PausePointParams, resume = false) {
     const id = `pp${this.lastPausePointId++}_${params.type}`;
     const commands = [this.sendCommand('pause-point:add', { id, ...params })];

packages/client/src/APITypes.ts

@@ -59,3 +59,9 @@ export interface PinReadResponse {
   value: number;
   voltage: number;
 }
+
+export interface VCDReadResponse {
+  vcd: string;
+  channelCount: number;
+  sampleCount: number;
+}

packages/client/src/index.ts

@@ -26,6 +26,7 @@ export type {
   ChipsLogPayload,
   PinReadResponse,
   SerialMonitorDataPayload,
+  VCDReadResponse,
 } from './APITypes.js';
 
 // Utilities