0
# PyVISA-py
1

2
A pure Python implementation of the Virtual Instrument Software Architecture (VISA) library that provides comprehensive backend functionality for PyVISA without requiring proprietary VISA drivers. PyVISA-py enables developers to communicate with test and measurement instruments through multiple interfaces including Serial, USB, GPIB, and Ethernet connections using only Python and cross-platform libraries.
3

4
## Package Information
5

6
- **Package Name**: PyVISA-py
7
- **Language**: Python  
8
- **Installation**: `pip install pyvisa-py`
9
- **Dependencies**: pyvisa (≥1.15.0)
10

11
## Core Imports
12

13
```python
14
import pyvisa_py
15
```
16

17
Standard usage through PyVISA:
18

19
```python
20
import pyvisa
21

22
# Use PyVISA-py as the backend
23
rm = pyvisa.ResourceManager('@py')
24
```
25

26
Direct backend access:
27

28
```python
29
from pyvisa_py import PyVisaLibrary
30

31
# Create the backend directly
32
backend = PyVisaLibrary()
33
```
34

35
## Basic Usage
36

37
```python
38
import pyvisa
39

40
# Initialize PyVISA with PyVISA-py backend
41
rm = pyvisa.ResourceManager('@py')
42

43
# List available resources
44
resources = rm.list_resources()
45
print("Available resources:", resources)
46

47
# Open connection to an instrument
48
# Example resource strings:
49
# - Serial: "ASRL/dev/ttyUSB0::INSTR" 
50
# - USB: "USB0::0x1234::0x5678::12345::INSTR"
51
# - TCP/IP: "TCPIP::192.168.1.100::INSTR"
52
# - GPIB: "GPIB0::10::INSTR"
53

54
try:
55
    # Open instrument connection
56
    inst = rm.open_resource("ASRL/dev/ttyUSB0::INSTR")
57
    
58
    # Configure communication parameters
59
    inst.timeout = 2000  # 2 second timeout
60
    inst.read_termination = '\\n'
61
    inst.write_termination = '\\n'
62
    
63
    # Send commands and read responses
64
    response = inst.query("*IDN?")
65
    print("Instrument ID:", response)
66
    
67
    # Write commands
68
    inst.write("*RST")  # Reset instrument
69
    
70
    # Read data
71
    data = inst.read()
72
    print("Data:", data)
73
    
74
finally:
75
    # Always close connections
76
    inst.close()
77
    rm.close()
78
```
79

80
## Architecture
81

82
PyVISA-py implements a session-based architecture that dispatches communication operations to specialized session classes:
83

84
- **PyVisaLibrary**: Main backend that manages sessions and dispatches VISA operations
85
- **Session Classes**: Protocol-specific implementations for different interface types
86
- **Protocol Layers**: Low-level communication protocols (VXI-11, HiSLIP, USBTMC, etc.)
87
- **Resource Discovery**: Automatic enumeration of available instruments per interface type
88

89
This design enables PyVISA-py to serve as a drop-in replacement for proprietary VISA implementations while providing the same high-level abstraction and supporting cross-platform deployment.
90

91
## Capabilities
92

93
### Core Backend Functionality
94

95
The main PyVisaLibrary class that provides the VISA backend implementation with session management, resource operations, and protocol dispatching.
96

97
```python { .api }
98
class PyVisaLibrary:
99
    def open(self, session, resource_name, access_mode=0, open_timeout=0): ...
100
    def close(self, session): ...
101
    def read(self, session, count): ...
102
    def write(self, session, data): ...
103
    def list_resources(self, session, query="?*::INSTR"): ...
104
    def get_attribute(self, session, attribute): ...
105
    def set_attribute(self, session, attribute, attribute_state): ...
106
```
107

108
[Core Backend](./core-backend.md)
109

110
### Serial Communication
111

112
Communication with instruments via serial ports, USB-to-serial adapters, and virtual COM ports with configurable parameters and termination handling.
113

114
```python { .api }
115
class SerialSession:
116
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
117
    def read(self, count): ...
118
    def write(self, data): ...
119
    @staticmethod
120
    def list_resources(): ...
121
```
122

123
[Serial Communication](./serial-communication.md)
124

125
### USB Communication
126

127
Direct USB device communication supporting both USBTMC (USB Test & Measurement Class) protocol for instruments and raw USB device access.
128

129
```python { .api }
130
class USBInstrSession:
131
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
132
    def read(self, count): ...
133
    def write(self, data): ...
134
    def clear(self): ...
135
    @staticmethod
136
    def list_resources(): ...
137

138
class USBRawSession:
139
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
140
    def read(self, count): ...
141
    def write(self, data): ...
142
```
143

144
[USB Communication](./usb-communication.md)
145

146
### TCP/IP Communication
147

148
Network-based instrument communication supporting multiple protocols including VXI-11, HiSLIP, VICP, and raw TCP sockets.
149

150
```python { .api }
151
class TCPIPInstrSession:
152
    def __new__(cls, resource_manager_session, resource_name, parsed, open_timeout): ...
153
    @staticmethod
154
    def list_resources(): ...
155

156
class TCPIPInstrVxi11:
157
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
158
    def read(self, count): ...
159
    def write(self, data): ...
160

161
class TCPIPInstrHiSLIP:
162
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
163
    def read(self, count): ...
164
    def write(self, data): ...
165

166
class TCPIPSocketSession:
167
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
168
    def read(self, count): ...
169
    def write(self, data): ...
170
```
171

172
[TCP/IP Communication](./tcpip-communication.md)
173

174
### GPIB Communication
175

176
General Purpose Interface Bus communication for controlling GPIB instruments with support for bus management, addressing, and control operations.
177

178
```python { .api }
179
class GPIBSessionDispatch:
180
    def __new__(cls, resource_manager_session, resource_name, parsed, open_timeout): ...
181

182
class GPIBSession:
183
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
184
    def read(self, count): ...
185
    def write(self, data): ...
186
    def gpib_command(self, command_byte): ...
187
    @staticmethod
188
    def list_resources(): ...
189
```
190

191
[GPIB Communication](./gpib-communication.md)
192

193
### Prologix Adapter Support
194

195
Support for Prologix GPIB-USB and GPIB-Ethernet adapters that provide GPIB functionality through USB and TCP/IP interfaces.
196

197
```python { .api }
198
class PrologixTCPIPIntfcSession:
199
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
200
    def read(self, count): ...
201
    def write(self, data): ...
202

203
class PrologixASRLIntfcSession:
204
    def __init__(self, resource_manager_session, resource_name, parsed, open_timeout): ...
205
    def read(self, count): ...
206
    def write(self, data): ...
207
```
208

209
[Prologix Adapters](./prologix-adapters.md)
210

211
## Resource String Formats
212

213
PyVISA-py supports standard VISA resource string formats:
214

215
- **Serial**: `ASRL<port>::INSTR` (e.g., `ASRL/dev/ttyUSB0::INSTR`, `ASRLCOM1::INSTR`)
216
- **USB INSTR**: `USB<board>::<vendor_id>::<product_id>::<serial>::<interface>::INSTR`
217
- **USB RAW**: `USB<board>::<vendor_id>::<product_id>::<serial>::<interface>::RAW`
218
- **TCP/IP Socket**: `TCPIP::<hostname>::<port>::SOCKET`
219
- **TCP/IP VXI-11**: `TCPIP::<hostname>::INSTR`
220
- **TCP/IP HiSLIP**: `TCPIP::<hostname>::hislip<session>::INSTR`
221
- **VICP**: `VICP::<hostname>::INSTR`
222
- **GPIB**: `GPIB<board>::<primary_address>[::secondary_address]::INSTR`
223
- **Prologix TCP/IP**: `PRLGX-TCPIP::<hostname>::<port>::INTFC`
224
- **Prologix Serial**: `PRLGX-ASRL::<port>::INTFC`
225

226
## Optional Dependencies
227

228
PyVISA-py functionality can be extended with optional packages:
229

230
- **pyserial** (≥3.0): Serial communication support
231
- **pyusb**: USB device communication
232
- **gpib-ctypes** (≥0.3.0): GPIB communication via ctypes
233
- **psutil**: Enhanced network interface discovery
234
- **zeroconf**: HiSLIP and VICP device discovery
235
- **pyvicp**: VICP protocol support for LeCroy oscilloscopes
236

237
Install with specific features:
238

239
```bash
240
pip install pyvisa-py[serial,usb,gpib-ctypes]
241
```
242

243
## Error Handling
244

245
PyVISA-py provides comprehensive error handling with VISA-compliant status codes:
246

247
```python { .api }
248
class OpenError(Exception):
249
    """Exception raised when failing to open a resource."""
250
    def __init__(self, error_code=StatusCode.error_resource_not_found): ...
251

252
class UnknownAttribute(Exception):
253
    """Exception raised for unsupported VISA attributes."""
254
    def __init__(self, attribute): ...
255
```
256

257
Common error scenarios:
258
- Resource not found or unavailable
259
- Permission denied for device access
260
- Timeout during communication
261
- Invalid resource string format
262
- Missing optional dependencies for specific interfaces