VISA Mapping TCP/IP Socket Gateway (VMSG). VMSG implements standard Prologix-style commands and control over TCP socket connections (port 1234) and bridges virtual instruments to PyVISA connections. Mapping your VISA connected devices on your computer to a Prologix Ethernet-style service means you can use VISA devices with tools like TestController that only support standard Prologix adapters.
The gateway operates concurrently on two ports:
- Port 1234 (TCP Socket): Handles native, standard Prologix controller commands (
++addr,++auto,++ver,++read, etc.) and routes standard SCPI command traffic to mapped physical or simulated instruments. - Port 8080 (FastAPI Web Server): Hosts a stunning, premium responsive web-based administration dashboard supporting seamless light and dark mode toggling.
| Virtual Patch Panel Grid | Live Instrument SCPI Console |
|---|---|
 |
 |
| Configure Slot Mapping | Live Traffic Snoop Monitor |
|---|---|
 |
 |
Pre-compiled, zero-dependency standalone binaries are available for official releases! You do not need Python installed to run them.
👉 Download Latest Windows & Linux Binaries
- Windows: Download
vmsg-windows-amd64.exeand run. - Linux: Download
vmsg-linux-amd64, add execute permission (chmod +x vmsg-linux-amd64), and run (./vmsg-linux-amd64).
Other than the Python packages in requirements.txt, VMSG relies on a VISA (Virtual Instrument Software Architecture) library backend to talk to physical instruments. Depending on your Operating System and hardware, follow the instructions below:
For the most robust hardware compatibility (especially physical GPIB cards, USB-GPIB adapters, or USBTMC instruments):
- Install NI Package Manager: Download and install the NI Package Manager.
- Install NI-VISA: Use the NI Package Manager to install NI-VISA. This installs the standard shared libraries (
visa32.dll/visa64.dll) that Python binds to automatically. - Install NI-MAX: Install NI-MAX (Measurement & Automation Explorer). This utility allows you to scan the VISA bus, assign aliases, and test communications with your physical devices to verify connection stability.
- Alternative Backends: If you prefer non-NI software, you can install the Keysight IO Libraries Suite or Rohde & Schwarz VISA.
NI-VISA is officially supported on select Linux distributions (see the NI-VISA Linux Download Page). However, Linux setups can also utilize the pure-Python pyvisa-py backend included in requirements.txt:
- Zero External Software for TCP & Serial: Pure-Python
pyvisa-pycommunicates directly with serial ports (/dev/ttyUSB*//dev/ttyS*) and TCP/IP socket connections without requiring any native VISA installation. - USB/USBTMC Permissions (udev rules): If accessing USB instruments via pure Python on Linux, you must grant read/write permissions to the device nodes. Add a custom
udevrule (e.g., in/etc/udev/rules.d/99-usbtmc.rules):(Replace# Example udev rule for USBTMC instruments SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0666", GROUP="plugdev"
XXXXandYYYYwith your instrument's USB Vendor and Product ID).
Ensure you have Python 3.9+ installed, then install the required PyVISA and server packages:
pip install -r requirements.txtRun the main startup script:
./run.sh(Or manually via: python3 vmsg.py)
Once started, open your web browser and navigate to: 👉 http://localhost:8080
With the gateway running, execute the verification suite in a separate terminal:
./run_tests.sh(Or manually via: python3 test_emulator.py)
To help you navigate the codebase, here is what each file does:
| File | Description |
|---|---|
🚀 vmsg.py |
Primary Entry Point (formerly main.py). Boots the unified servers and mounts both the TCP socket server and FastAPI. |
🖥️ web_app.py |
Implements the FastAPI REST endpoints for statuses, configuration backups/restores, scans, and mapping controls. |
🔌 prologix_server.py |
Low-latency TCP socket server (port 1234) implementing standard & extended Prologix command parsers. |
🎛️ visa_manager.py |
Manages pyvisa sessions, resource pooling, unresponsive port cooldown caching, and simulated device mocks. |
📁 config_manager.py |
Thread-safe manager that reads, writes, and persists virtual address mappings in mappings.json. |
📝 logger.py |
Global thread-safe, in-memory circular log feed shared between socket traffic and API clients. |
🧪 test_emulator.py |
Automated integration verification suite checking SCPI queries, timeouts, and multi-address states. |
🛠️ static/index.html |
Single-page premium dashboard with CSS glassmorphism, responsive light/dark themes, and SCPI terminal console modals. |
- Persistent Sessions: PyVISA connections are cached and reused globally instead of opening/closing on every byte transfer, completely eliminating connection overhead.
- Unresponsive Cooldown Caching: Ports that time out or fail to respond are briefly fast-failed so scanning routines cannot lock up the interface. The cooldown escalates with consecutive failures (2s → 5s → 15s → 30s) and is cleared on the first successful access, so a momentarily busy instrument is not taken out of service. Every cooldown is logged with the reason that triggered it.
- Bus-Safe Scanning:
*IDN?probes take the same per-interface lock as client traffic, so a hardware scan cannot interleave with an in-flight transaction on a shared bus (e.g. GPIB).
No physical hardware? No problem. The gateway includes built-in interactive simulated instruments:
- Mock Multimeter (
MOCK::DMM::INSTR): Emulates a Hewlett-Packard 34401A, returning variable voltage/resistance measurements. - Mock Oscilloscope (
MOCK::SCOPE::INSTR): Emulates a Tektronix TDS 2024, responding to trace queries and standard SCPI configurations.
Click ADMIN PANEL in the top right of the dashboard to configure:
- Unmapped Slot Behavior: Set whether unmapped virtual channels return friendly warning messages or simulate a real physical bus timeout (
VI_ERROR_TMO). - Auto-Assignment: Scan the GPIB bus and auto-assign discovered instruments to empty virtual addresses with optional simulated-mock filtering and mapping safety guards.
- Backup & Restore: Export the running configuration as a JSON file and restore it instantly via drag-and-drop.
Use Export TestController Config in the dashboard to generate settingsGPIB.txt and settingsLoad.txt from your live mappings, then drop both into TestController's Settings folder. The export is built so a cold start and a menu Reconnect both work:
- One Controller ID per instrument (
A,B,C, …). A single shared ID trips a startup defect in TestController that stops all but one device thread. settings:++addr Nper controller. TestController re-runs its interface init on every reconnect but does not re-send the address, so without this a Reconnect routes every device to the default slot. This field closes that gap with no changes to either program.- Only known driver names are emitted. An instrument that does not map to a stock TestController driver is excluded and reported, never guessed — TestController abandons every remaining device when it meets a name it cannot resolve.
- Serial scanning is off by default (
ScanSerialPorts:0), keeping TestController on VMSG's sockets. Turn it on and pick per-port exclusions under Host Discovery & TestController in the admin panel.
Off by default — everything runs on the single control port 1234. When enabled (admin panel, the auto-assign dialog, or a per-slot field on any mapping tile), each mapped slot also listens on its own port and the export emits settings:port:NNNN;++addr N. A client arriving on a dedicated port is addressed to that slot automatically and never needs ++addr at all, which makes reconnects correct regardless of client behaviour and works for a remote TestController host.
For the full technical breakdown — decompiled root causes, diagnostic logs, and the defects worth reporting upstream — see TESTCONTROLLER_NOTES.md.