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).
Binaries are not code-signed, so Windows SmartScreen will warn on first run.
Each asset ships a .sha256 checksum and a .build-info.json recording the
version, platform, and exact dependency versions it was built from:
sha256sum -c vmsg-linux-amd64.sha256Get-FileHash vmsg-windows-amd64.exe -Algorithm SHA256See CODE_SIGNING_POLICY.md for the full release provenance.
pip install -r requirements-release.txt
python build_binary.pyThis runs static analysis and the offline protocol suite, builds from the
tracked vmsg.spec, writes dist/build-info.json plus a checksum, then
launches the packaged executable and verifies it behaves like the source tree.
It refuses to report success if any stage fails. --skip-checks and
--no-verify exist for throwaway builds and are labelled as not shippable.
| Variable | Purpose |
|---|---|
VMSG_CONFIG_FILE |
Use a specific config instead of the default location |
VMSG_BIND_HOST |
Bind address for all listeners (default 0.0.0.0) |
VMSG_SOCKET_PORT |
Prologix control socket (default 1234) |
VMSG_HTTP_PORT |
Dashboard and REST API (default 8080) |
VMSG_API_TOKEN |
Override the control-API token |
VMSG_CORS_ORIGINS |
Extra allowed origins, comma-separated |
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.
Measured against direct NI-VISA on the same instruments: ~1 ms per query, and nothing measurable for address switching β including the interleaved round-robin case that TestController produces when several devices log together. Per-query cost is set by the instrument, not the gateway; it varied 10Γ between instruments on the same bus. See PERFORMANCE.md, reproducible with tools/vmsg_overhead.py.



