Debian Codegraph @

pymeasure/instruments/hp/hp3437A.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
25 import ctypes
26 import logging
27 import math
28 from enum import IntFlag
29 import numpy as np
30 from pymeasure.instruments.hp.hplegacyinstrument import HPLegacyInstrument, StatusBitsBase
31
32 from pymeasure.instruments.validators import strict_discrete_set, strict_range
33
34 log = logging.getLogger(__name__)
35 log.addHandler(logging.NullHandler())
36
37 c_uint8 = ctypes.c_uint8
38 c_uint16 = ctypes.c_uint16
39 c_uint32 = ctypes.c_uint32
40
41
42 class Status(StatusBitsBase):
43 """
44 A bitfield structure containing the assignments for the status decoding
45 """
46 _pack_ = 1
47 _fields_ = [
48 # Byte 0: Function, Range and Number of Digits
49 ("Format", c_uint8, 1), # Bit 7
50 ("SRQ", c_uint8, 3), # bit 4..6
51 ("Trigger", c_uint8, 2), # bit 2..3
52 ("Range", c_uint8, 2), # bit 0..1
53 # Byte 1 & 2:
54 ("Number", c_uint16, 16),
55 # Byte 1:
56 # ("NRDGS_MSD", c_uint8, 4),
57 # ("NRDGS_2SD", c_uint8, 4),
58 # Byte 2:
59 # ("NRDGS_3SD", c_uint8, 4),
60 # ("NRDGS_LSD", c_uint8, 4),
61 ("not_used", c_uint8, 4),
62 ("Delay", c_uint32, 28),
63 # Byte 3:
64 # ("Not_Used", c_uint8, 4),
65 # ("Delay_MSD", c_uint8, 4),
66 # Byte 4:
67 # ("Delay_2SD", c_uint8, 4),
68 # ("Delay_3SD", c_uint8, 4),
69 # Byte 5:
70 # ("Delay_4SD", c_uint8, 4),
71 # ("Delay_5SD", c_uint8, 4),
72 # Byte 6:
73 # ("Delay_6SD", c_uint8, 4),
74 # ("Delay_LSD", c_uint8, 4),
75 ]
76
77 @staticmethod
78 def _decode_range(r):
79 """Method to decode current range
80
81 :param range_undecoded: int to be decoded
82 :return cur_range: float value representing the active measurement range
83 :rtype cur_range: float
84
85 """
86 # range decoding
87 # (cf table 3-2, page 3-5 of the manual, HPAK document 9018-05946)
88 decode_map = {
89 0: math.nan,
90 1: 0.1,
91 2: 10.0,
92 3: 1.0,
93 }
94 return decode_map[r]
95
96 @staticmethod
97 def _decode_trigger(t):
98 """Method to decode trigger mode
99
100 :param status_bytes: list of bytes to be decoded
101 :return trigger_mode: string with the current trigger mode
102 :rtype trigger_mode: str
103
104 """
105 decode_map = {
106 0: "INVALID",
107 1: "internal",
108 2: "external",
109 3: "hold/manual"
110 }
111 return decode_map[t]
112
113 _get_process_ = {
114 "Number": StatusBitsBase._convert_from_bcd,
115 "Delay": StatusBitsBase._convert_from_bcd,
116 "Range": _decode_range,
117 "Trigger": _decode_trigger,
118 }
119
120 def __str__(self):
121 """
122 Returns a pretty formatted string showing the status of the instrument
123 """
124 ret_str = ""
125 for field in self._fields_:
126 ret_str = ret_str + f"{field[0]}: {getattr(self, field[0])}\n"
127
128 return ret_str
129
130
131 class PackedBits(ctypes.BigEndianStructure):
132 """
133 A bitfield structure containing the assignments for the data transfer in packed/binary mode
134 """
135 _pack_ = 1
136 _fields_ = [
137 ("range", c_uint8, 2), # bit 0..1
138 ("sign_bit", c_uint8, 1),
139 ("MSD", c_uint8, 1),
140 ("SSD", c_uint8, 4),
141 ("TSD", c_uint8, 4),
142 ("LSD", c_uint8, 4), ]
143
144 def __float__(self):
145 """
146 Return a float value from the packed data of the HP3437A
147
148 """
149 # range decoding
150 # (cf table 3-2, page 3-5 of the manual, HPAK document 9018-05946)
151 decode_map = {
152 1: 0.1,
153 2: 10.0,
154 3: 1.0,
155 }
156 cur_range = decode_map[self.range]
157
158 signbit = 1
159 if self.sign_bit == 0:
160 signbit = -1
161
162 return (
163 cur_range * signbit * (
164 self.MSD + self.SSD / 10 + self.TSD / 100 + self.LSD / 1000
165 )
166 )
167
168
169 class HP3437A(HPLegacyInstrument):
170 """Represents the Hewlett Packard 3737A system voltmeter
171 and provides a high-level interface for interacting
172 with the instrument.
173 """
174 status_desc = Status
175 pb_desc = PackedBits
176
177 def __init__(self, adapter, name="Hewlett-Packard HP3437A", **kwargs):
178 super().__init__(
179 adapter,
180 name,
181 **kwargs,
182 )
183
184 # Definitions for different specifics of this instrument
185 RANGE = {
186 1e-1: "R1",
187 1: "R2",
188 10: "R3",
189 }
190
191 TRIGGERS = {
192 "internal": "T1",
193 "external": "T2",
194 "hold": "T3",
195 "manual": "T3",
196 }
197
198 class SRQ(IntFlag):
199 """Enum element for SRQ mask bit decoding"""
200
201 DATA_READY = 4
202 IGNORE_TRIGGER = 2
203 INVALID_PROGRAM = 1
204
205 def _unpack_data(self, data):
206 """
207 Method to unpack the data from the returned bytes in packed mode
208
209 :param data: list of bytes to be decoded
210 :return ret_data: float value
211
212 """
213 ret_data = PackedBits.from_buffer(bytearray(data))
214 return float(ret_data)
215
216 # commands overwriting the base implementation
217 def read_data(self):
218 """
219 Reads measured data from instrument, returns a np.array.
220
221 (This function also takes care of unpacking the data if required)
222
223 :return data: np.array containing the data
224 """
225 # Adjusting the timeout to match the number of counts and the delay
226
227 current_timeout = self.adapter.connection.timeout
228 time_needed = self.number_readings * self.delay
229 new_timeout = min(1e6, time_needed * 3 * 1000) # safety factor 3
230 if new_timeout > current_timeout:
231 if new_timeout >= 1e6:
232 # Disables timeout if measurement would take more then 1000 sec
233 log.info("HP3437A: timeout deactivated")
234 self.adapter.connection.timeout = new_timeout
235 log.info("HP3437A: timeout changed to %g", new_timeout)
236 read_data = self.read_bytes(-1)
237 # check if data is in packed format format
238 if self.talk_ascii:
239 return_value = np.array(read_data[:-2].decode("ASCII").split(","),
240 dtype=float)
241 else:
242 processed_data = []
243 for i in range(0, len(read_data), 2):
244 processed_data.append(self._unpack_data(read_data[i : i + 2])) # noqa: E203
245 return_value = np.array(processed_data)
246 self.adapter.connection.timeout = current_timeout
247 return return_value
248
249 # commands/properties for instrument control
250 def check_errors(self):
251 """
252 As this instrument does not have a error indication bit,
253 this function always returns an empty list.
254
255 """
256 return []
257
258 @property
259 def talk_ascii(self):
260 """
261 A boolean property, True if the instrument is set to ASCII-based communication.
262 This property can be set.
263 """
264 return bool(self.status.Format)
265
266 @talk_ascii.setter
267 def talk_ascii(self, value):
268 if value:
269 self.write("F1")
270 else:
271 self.write("F2")
272
273 @property
274 def delay(self):
275 """Return the value (float) for the delay between two measurements,
276 this property can be set,
277
278 valid range: 100ns - 0.999999s
279
280 """
281 return self.status.Delay * 1e-7
282
283 @delay.setter
284 def delay(self, value):
285 delay_str = (
286 "D." + format(strict_range(value, [0, 0.9999999]) * 10e6, "07.0f") + "S"
287 )
288 self.write(delay_str)
289
290 @property
291 def number_readings(self):
292 """Return value (int) for the number of consecutive measurements,
293 this property can be set,
294 valid range: 0 - 9999
295
296 """
297 return self.status.Number
298
299 @number_readings.setter
300 def number_readings(self, value):
301 number_str = "N" + str(strict_range(value, [0, 9999])) + "S"
302 self.write(number_str)
303
304 @property
305 def range(self):
306 """Return the current measurement voltage range.
307
308 This property can be set, valid values: 0.1, 1, 10 (V).
309
310 .. Note::
311
312 This instrument does not have autorange capability.
313
314 Overrange will be in indicated as 0.99,9.99 or 99.9
315
316 """
317 return self.status.Range
318
319 @range.setter
320 def range(self, value):
321 range_str = "R" + format(
322 round(math.log10(strict_discrete_set(value, [0.1, 1, 10])) + 2), "d"
323 )
324 self.write(range_str)
325
326 @property
327 def SRQ_mask(self):
328 """Return current SRQ mask, this property can be set,
329
330 bit assignment for SRQ:
331
332 ========= ==========================
333 Bit (dec) Description
334 ========= ==========================
335 1 SRQ when invalid program
336 2 SRQ when trigger is ignored
337 4 SRQ when data ready
338 ========= ==========================
339
340 """
341 mask = self.status.SRQ
342 return self.SRQ(mask)
343
344 @SRQ_mask.setter
345 def SRQ_mask(self, value):
346 mask_str = "E" + format(strict_range(value, [0, 7]), "o") + "S"
347 self.write(mask_str)
348
349 @property
350 def trigger(self):
351 """Return current selected trigger mode, this property can be set,
352
353 Possible values are:
354
355 =========== ===========================================
356 Value Explanation
357 =========== ===========================================
358 internal automatic trigger (internal)
359 external external trigger (connector on back or GET)
360 hold/manual holds the measurement/issues a manual trigger
361 =========== ===========================================
362
363 """
364 return self.status.Trigger
365
366 @trigger.setter
367 def trigger(self, value):
368 trig_set = self.TRIGGERS[strict_discrete_set(value, self.TRIGGERS)]
369 self.write(trig_set)