Debian Codegraph @

pymeasure/adapters/prologix.py

raw
1 #
2 # This file is part of the PyMeasure package.
3 #
4 # Copyright (c) 2013-2024 PyMeasure Developers
5 #
6 # Permission is hereby granted, free of charge, to any person obtaining a copy
7 # of this software and associated documentation files (the "Software"), to deal
8 # in the Software without restriction, including without limitation the rights
9 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 # copies of the Software, and to permit persons to whom the Software is
11 # furnished to do so, subject to the following conditions:
12 #
13 # The above copyright notice and this permission notice shall be included in
14 # all copies or substantial portions of the Software.
15 #
16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 # THE SOFTWARE.
23 #
24 import time
25 from warnings import warn
26
27 from pymeasure.adapters import VISAAdapter
28
29
30 class PrologixAdapter(VISAAdapter):
31 """ Encapsulates the additional commands necessary
32 to communicate over a Prologix GPIB-USB Adapter,
33 using the :class:`VISAAdapter`.
34
35 Each PrologixAdapter is constructed based on a connection to the Prologix device
36 itself and the GPIB address of the instrument to be communicated to.
37 Connection sharing is achieved by using the :meth:`.gpib`
38 method to spawn new PrologixAdapters for different GPIB addresses.
39
40 :param resource_name: A
41 `VISA resource string <https://pyvisa.readthedocs.io/en/latest/introduction/names.html>`__
42 that identifies the connection to the Prologix device itself, for example
43 "ASRL5" for the 5th COM port.
44 :param address: Integer GPIB address of the desired instrument.
45 :param rw_delay: An optional delay to set between a write and read call for
46 slow to respond instruments.
47
48 .. deprecated:: 0.11
49 Implement it in the instrument's `wait_for` method instead.
50
51 :param preprocess_reply: optional callable used to preprocess
52 strings received from the instrument. The callable returns the
53 processed string.
54
55 .. deprecated:: 0.11
56 Implement it in the instrument's `read` method instead.
57
58 :param auto: Enable or disable read-after-write and address instrument to listen.
59 :param eoi: Enable or disable EOI assertion.
60 :param eos: Set command termination string (CR+LF, CR, LF, or "")
61 :param gpib_read_timeout: Set read timeout for GPIB communication in milliseconds from 1..3000
62 :param kwargs: Key-word arguments if constructing a new serial object
63
64 :ivar address: Integer GPIB address of the desired instrument.
65
66 Usage example:
67
68 .. code::
69
70 adapter = PrologixAdapter("ASRL5::INSTR", 7)
71 sourcemeter = Keithley2400(adapter) # at GPIB address 7
72 # generate another instance with a different GPIB address:
73 adapter2 = adapter.gpib(9)
74 multimeter = Keithley2000(adapter2) # at GPIB address 9
75
76
77 To allow user access to the Prologix adapter in Linux, create the file:
78 :code:`/etc/udev/rules.d/51-prologix.rules`, with contents:
79
80 .. code-block:: bash
81
82 SUBSYSTEMS=="usb",ATTRS{idVendor}=="0403",ATTRS{idProduct}=="6001",MODE="0666"
83
84 Then reload the udev rules with:
85
86 .. code-block:: bash
87
88 sudo udevadm control --reload-rules
89 sudo udevadm trigger
90
91 """
92
93 def __init__(self, resource_name, address=None, rw_delay=0, serial_timeout=None,
94 preprocess_reply=None, auto=False, eoi=True, eos="\n", gpib_read_timeout=None,
95 **kwargs):
96 # for legacy rw_delay: prefer new style over old one.
97 if rw_delay:
98 warn(("Parameter `rw_delay` is deprecated. "
99 "Implement in Instrument's `wait_for` instead."),
100 FutureWarning)
101 kwargs['query_delay'] = rw_delay
102 if serial_timeout:
103 warn("Parameter `serial_timeout` is deprecated. Use `timeout` in ms instead",
104 FutureWarning)
105 kwargs['timeout'] = serial_timeout
106 super().__init__(resource_name,
107 asrl={
108 'timeout': 500,
109 'write_termination': "\n",
110 },
111 preprocess_reply=preprocess_reply,
112 **kwargs)
113 self.address = address
114 if not isinstance(resource_name, PrologixAdapter):
115 self.auto = auto
116 self.eoi = eoi
117 self.eos = eos
118
119 if gpib_read_timeout is not None:
120 self.gpib_read_timeout = gpib_read_timeout
121
122 @property
123 def auto(self):
124 """Control whether to address instruments to talk after sending them a command (bool).
125
126 Configure Prologix GPIB controller to automatically address instruments
127 to talk after sending them a command in order to read their response. The
128 feature called, Read-After-Write, saves the user from having to issue read commands
129 repeatedly. This property enables (True) or disables (False) this feature.
130 """
131 self.write("++auto")
132 return bool(int(self.read(prologix=True)))
133
134 @auto.setter
135 def auto(self, value):
136 self.write(f"++auto {int(value)}")
137
138 @property
139 def eoi(self):
140 """Control whether to assert the EOI signal with the last character
141 of any command sent over GPIB port (bool).
142
143 Some instruments require EOI signal to be
144 asserted in order to properly detect the end of a command.
145 """
146 self.write("++eoi")
147 return bool(int(self.read(prologix=True)))
148 self.read(prologix=True)
149
150 @eoi.setter
151 def eoi(self, value):
152 self.write(f"++eoi {int(value)}")
153
154 @property
155 def eos(self):
156 """Control GPIB termination characters (str).
157
158 possible values:
159 - CR+LF
160 - CR
161 - LF
162 - empty string
163
164 When data from host is received, all non-escaped LF, CR and ESC characters are
165 removed and GPIB terminators, as specified by this command, are appended before
166 sending the data to instruments. This command does not affect data from
167 instruments received over GPIB port.
168 """
169 values = {0: "\r\n", 1: "\r", 2: "\n", 3: ""}
170 self.write("++eos")
171 return values[int(self.read(prologix=True))]
172
173 @eos.setter
174 def eos(self, value):
175 values = {"\r\n": 0, "\r": 1, "\n": 2, "": 3}
176 self.write(f"++eos {values[value]}")
177
178 @property
179 def gpib_read_timeout(self):
180 """Control the timeout value for the GPIB communication in milliseconds
181
182 possible values: 1 - 3000
183 """
184 self.write("++read_tmo_ms")
185 return int(self.read(prologix=True))
186
187 @gpib_read_timeout.setter
188 def gpib_read_timeout(self, value):
189 self.write(f"++read_tmo_ms {value}")
190
191 @property
192 def version(self):
193 """Get the version string of the Prologix controller.
194 """
195 self.write('++ver')
196 return self.read(prologix=True)
197
198 def reset(self):
199 """Perform a power-on reset of the controller.
200
201 The process takes about 5 seconds. All input received during this time
202 is ignored and the connection is closed.
203 """
204 self.write('++rst')
205
206 def ask(self, command):
207 """ Ask the Prologix controller.
208
209 .. deprecated:: 0.11
210 Call `Instrument.ask` instead.
211
212 :param command: SCPI command string to be sent to instrument
213 """
214 warn("`Adapter.ask` is deprecated, call `Instrument.ask` instead.", FutureWarning)
215 self.write(command)
216 return self.read()
217
218 def write(self, command, **kwargs):
219 """Write a string command to the instrument appending `write_termination`.
220
221 If the GPIB address in :attr:`address` is defined, it is sent first.
222
223 :param str command: Command string to be sent to the instrument
224 (without termination).
225 :param kwargs: Keyword arguments for the connection itself.
226 """
227 # Overrides write instead of _write in order to ensure proper logging
228 if self.address is not None and not command.startswith("++"):
229 super().write("++addr %d" % self.address, **kwargs)
230 super().write(command, **kwargs)
231
232 def _format_binary_values(self, values, datatype='f', is_big_endian=False, header_fmt="ieee"):
233 """Format values in binary format, used internally in :meth:`.write_binary_values`.
234
235 :param values: data to be written to the device.
236 :param datatype: the format string for a single element. See struct module.
237 :param is_big_endian: boolean indicating endianess.
238 :param header_fmt: Format of the header prefixing the data ("ieee", "hp", "empty").
239 :return: binary string.
240 :rtype: bytes
241 """
242 block = super()._format_binary_values(values, datatype, is_big_endian, header_fmt)
243 # Prologix needs certian characters to be escaped.
244 # Special care must be taken when sending binary data to instruments. If any of the
245 # following characters occur in the binary data -- CR (ASCII 13), LF (ASCII 10), ESC
246 # (ASCII 27), '+' (ASCII 43) - they must be escaped by preceding them with an ESC
247 # character.
248 special_chars = b'\x0d\x0a\x1b\x2b'
249 new_block = b''
250 for b in block:
251 escape = b''
252 if b in special_chars:
253 escape = b'\x1b'
254 new_block += (escape + bytes((b,)))
255
256 return new_block
257
258 def write_binary_values(self, command, values, **kwargs):
259 """ Write binary data to the instrument, e.g. waveform for signal generators.
260
261 values are encoded in a binary format according to
262 IEEE 488.2 Definite Length Arbitrary Block Response Data block.
263
264 :param command: SCPI command to be sent to the instrument
265 :param values: iterable representing the binary values
266 :param kwargs: Key-word arguments to pass onto :meth:`._format_binary_values`
267 :returns: number of bytes written
268 """
269 if self.address is not None:
270 address_command = "++addr %d\n" % self.address
271 self.write(address_command)
272 super().write_binary_values(command, values, "\n", **kwargs)
273
274 def _read(self, prologix=False, **kwargs):
275 """Read up to (excluding) `read_termination` or the whole read buffer.
276
277 :param prologix: Read the prologix adapter itself.
278 :param kwargs: Keyword arguments for the connection itself.
279 :returns str: ASCII response of the instrument (excluding read_termination).
280 """
281 if not prologix:
282 self.write("++read eoi")
283 return super()._read()
284
285 def gpib(self, address, **kwargs):
286 """ Return a PrologixAdapter object that references the GPIB
287 address specified, while sharing the Serial connection with other
288 calls of this function
289
290 :param address: Integer GPIB address of the desired instrument
291 :param kwargs: Arguments for the initialization
292 :returns: PrologixAdapter for specific GPIB address
293 """
294 return PrologixAdapter(self, address, **kwargs)
295
296 def _check_for_srq(self):
297 # it was int(self.ask("++srq"))
298 self.write("++srq")
299 return int(self.read())
300
301 def wait_for_srq(self, timeout=25, delay=0.1):
302 """ Blocks until a SRQ, and leaves the bit high
303
304 :param timeout: Timeout duration in seconds.
305 :param delay: Time delay between checking SRQ in seconds.
306 :raises TimeoutError: "Waiting for SRQ timed out."
307 """
308 stop = time.perf_counter() + timeout
309 while self._check_for_srq() != 1:
310 if time.perf_counter() > stop:
311 raise TimeoutError("Waiting for SRQ timed out.")
312 time.sleep(delay)
313
314 def __repr__(self):
315 if self.address is not None:
316 return (f"<PrologixAdapter(resource_name='{self.connection.resource_name}', "
317 f"address={self.address:d})>")
318 else:
319 return f"<PrologixAdapter(resource_name='{self.connection.resource_name}')>"