Debian Codegraph @

pymeasure/instruments/temptronic/temptronic_base.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 """Implementation of an interface driver for ThermoStream® (TS) Systems devices.
26
27 # Reference Document for implementation:
28 ATS-515/615, ATS 525/625 & ATS 535/635 ThermoStream® Systems
29 Interface & Applications Manual
30 Revision E
31 September, 2019
32
33 # Safety hints
34 In case of script error, make sure thermostream will be shut down.
35 This can be established by e.g. means of try, finally statements.
36 Another way is by polling ``error_code`` integer status flags.
37 No automatic safety measures are part of this driver implementation.
38
39 """
40 import logging
41 import time
42 from pymeasure.instruments import Instrument, SCPIUnknownMixin
43 from pymeasure.instruments.validators import (strict_discrete_set,
44 truncated_range,
45 strict_range
46 )
47
48 from enum import IntFlag
49
50 log = logging.getLogger(__name__) # https://docs.python.org/3/howto/logging.html#library-config
51 log.addHandler(logging.NullHandler())
52
53
54 class TemperatureStatusCode(IntFlag):
55 """Temperature status enums based on ``IntFlag``
56
57 Used in conjunction with :attr:`~.temperature_condition_status_code`.
58
59 ====== ======
60 Value Enum
61 ====== ======
62 32 CYCLING_STOPPED
63 16 END_OF_ALL_CYCLES
64 8 END_OF_ONE_CYCLE
65 4 END_OF_TEST
66 2 NOT_AT_TEMPERATURE
67 1 AT_TEMPERATURE
68 0 NO_STATUS
69 ====== ======
70
71 """
72
73 CYCLING_STOPPED = 32 # bit 5 -- cycling stopped("stop on fail" signal was received)
74 END_OF_ALL_CYCLES = 16 # bit 4 -- end of all cycles
75 END_OF_ONE_CYCLE = 8 # bit 3 -- end of one cycle
76 END_OF_TEST = 4 # bit 2 -- end of test (test time has elapsed)
77 NOT_AT_TEMPERATURE = 2 # bit 1 -- not at temperature
78 AT_TEMPERATURE = 1 # bit 0 -- at temperature (soak time has elapsed)
79 NO_STATUS = 0 # bit 0 -- no temperature status indication
80
81
82 class ErrorCode(IntFlag):
83 """Error code enums based on ``IntFlag``.
84
85 Used in conjunction with :attr:`~.error_code`.
86
87 ====== ======
88 Value Enum
89 ====== ======
90 16384 NO_DUT_SENSOR_SELECTED
91 4096 BVRAM_FAULT
92 2048 NVRAM_FAULT
93 1024 NO_LINE_SENSE
94 512 FLOW_SENSOR_HARDWARE_ERROR
95 128 INTERNAL_ERROR
96 32 AIR_SENSOR_OPEN
97 16 LOW_INPUT_AIR_PRESSURE
98 8 LOW_FLOW
99 2 AIR_OPEN_LOOP
100 1 OVERHEAT
101 0 OK
102 ====== ======
103
104 """
105 # bit 15 – reserved
106 NO_DUT_SENSOR_SELECTED = 16384 # bit 14 – no DUT sensor selected
107 # bit 13 – reserved
108 BVRAM_FAULT = 4096 # bit 12 – BVRAM fault
109 NVRAM_FAULT = 2048 # bit 11 – NVRAM fault
110 NO_LINE_SENSE = 1024 # bit 10 – No Line Sense
111 FLOW_SENSOR_HARDWARE_ERROR = 512 # bit 9 – flow sensor hardware error
112 # bit 8 – reserved
113 INTERNAL_ERROR = 128 # bit 7 – internal error
114 # bit 6 – reserved
115 AIR_SENSOR_OPEN = 32 # bit 5 – air sensor open
116 LOW_INPUT_AIR_PRESSURE = 16 # bit 4 – low input air pressure
117 LOW_FLOW = 8 # bit 3 – low flow
118 # bit 2 – reserved
119 AIR_OPEN_LOOP = 2 # bit 1 – air open loop
120 OVERHEAT = 1 # bit 0 – overheat
121 OK = 0 # ok state
122
123
124 class ATSBase(SCPIUnknownMixin, Instrument):
125 """The base class for Temptronic ATSXXX instruments.
126 """
127
128 def __init__(self, adapter, name="ATSBase", **kwargs):
129 super().__init__(adapter, name=name, **kwargs)
130
131 def wait_for(self, query_delay=None):
132 super().wait_for(0.05 if query_delay is None else query_delay)
133
134 remote_mode = Instrument.setting(
135 "%s",
136 """``True`` disables TS GUI but displays a “Return to local" switch.""",
137 validator=strict_discrete_set,
138 values={True: "%RM", False: r"%GL"},
139 map_values=True
140 )
141
142 maximum_test_time = Instrument.control(
143 "TTIM?", "TTIM %g",
144 """Control maximum allowed test time (s).
145
146 :type: float
147
148 This prevents TS from staying at a single temperature forever.
149 Valid range: 0 to 9999
150 """,
151 validator=truncated_range,
152 values=[0, 9999]
153 )
154
155 dut_mode = Instrument.control(
156 "DUTM?", "DUTM %g",
157 """ ``On`` enables DUT mode, ``OFF`` enables air mode
158
159 :type: string
160
161 """,
162 validator=strict_discrete_set,
163 values={'ON': 1, 'OFF': 0},
164 map_values=True
165 )
166
167 dut_type = Instrument.control(
168 "DSNS?", "DSNS %g",
169 """Control DUT sensor type.
170
171 :type: string
172
173 Possible values are:
174
175 ====== ======
176 String Meaning
177 ====== ======
178 '' no DUT
179 'T' T-DUT
180 'K' K-DUT
181 ====== ======
182
183 Warning: If in DUT mode without DUT being connected, TS flags DUT error
184
185 """,
186 validator=strict_discrete_set,
187 values={None: 0, 'T': 1, 'K': 2},
188 map_values=True
189 )
190
191 dut_constant = Instrument.control(
192 "DUTC?", "DUTC %g",
193 """Control thermal constant (default 100) of DUT.
194
195 :type: float
196
197 Lower values indicate lower thermal mass, higher values indicate higher
198 thermal mass respectively.
199 """,
200 validator=truncated_range,
201 values=[20, 500]
202 )
203
204 head = Instrument.control(
205 "HEAD?", "HEAD %s",
206 """Control TS head position.
207
208 :type: string
209
210 ``down``: transfer head to lower position
211 ``up``: transfer head to elevated position
212 """,
213 validator=strict_discrete_set,
214 values={'up': 0, 'down': 1},
215 map_values=True
216 )
217
218 enable_air_flow = Instrument.setting(
219 "FLOW %g",
220 """Set TS air flow.
221
222 ``True`` enables air flow, ``False`` disables it
223
224 :type: bool
225
226 """,
227 validator=strict_discrete_set,
228 map_values=True,
229 values={True: 1, False: 0}
230 )
231
232 temperature_limit_air_low = Instrument.control(
233 "LLIM?", "LLIM %g",
234 """Control lower air temperature limit.
235
236 :type: float
237
238 Valid range between -99 to 25 (°C). Setpoints below current value cause
239 “out of range” error in TS.
240 """,
241 validator=truncated_range,
242 values=[-99, 25],
243 dynamic=True
244 )
245
246 temperature_limit_air_high = Instrument.control(
247 "ULIM?", "ULIM %g",
248 """upper air temperature limit.
249
250 :type: float
251
252 Valid range between 25 to 255 (°C). Setpoints above current value cause
253 “out of range” error in TS.
254 """,
255 validator=truncated_range,
256 values=[25, 225]
257 )
258
259 temperature_limit_air_dut = Instrument.control(
260 "ADMD?", "ADMD %g",
261 """Air to DUT temperature limit.
262
263 :type: float
264
265 Allowed difference between nozzle air and DUT temperature during
266 settling. Valid range between 10 to 300 °C in 1 degree increments.
267 """,
268 validator=truncated_range,
269 values=[10, 300]
270 )
271
272 temperature_setpoint = Instrument.control(
273 "SETP?", "SETP %g",
274 """Set or get selected setpoint's temperature.
275
276 :type: float
277
278 Valid range is -99.9 to 225.0 (°C) or as indicated by
279 :attr:`~.temperature_limit_air_high`
280 and :attr:`~.temperature_limit_air_low`.
281 Use convenience function :meth:`~ATSBase.set_temperature`
282 to prevent unexpected behavior.
283 """,
284 validator=truncated_range,
285 values=[-99.9, 225]
286 )
287
288 temperature_setpoint_window = Instrument.control(
289 "WNDW?", "WNDW %g",
290 """Setpoint's temperature window.
291
292 :type: float
293
294 Valid range is between 0.1 to 9.9 (°C). Temperature status register
295 flags ``at temperature`` in case soak time elapsed while temperature
296 stays in between bounds given by this value around the current setpoint.
297 """,
298 validator=truncated_range,
299 values=[0.1, 9.9]
300 )
301
302 temperature_soak_time = Instrument.control(
303 "SOAK?", "SOAK %g",
304 """
305 Set the soak time for the currently selected setpoint.
306
307 :type: float
308
309 Valid range is between 0 to 9999 (s). Lower values shorten cycle times.
310 Higher values increase cycle times, but may reduce settling errors.
311 See :attr:`~.temperature_setpoint_window` for further information.
312 """,
313 validator=truncated_range,
314 values=[0.0, 9999]
315 )
316
317 temperature = Instrument.measurement(
318 "TEMP?",
319 """Read current temperature with 0.1 °C resolution.
320
321 :type: float
322
323 Temperature readings origin depends on :attr:`dut_mode` setting.
324 Reading higher than 400 (°C) indicates invalidity.
325 """
326 )
327
328 temperature_condition_status_code = Instrument.measurement(
329 "TECR?",
330 """Temperature condition status register.
331
332 :type: :class:`.TemperatureStatusCode`
333 """,
334 values=[0, 255],
335 get_process=lambda v: TemperatureStatusCode(int(v)),
336 )
337
338 set_point_number = Instrument.control(
339 "SETN?", "SETN %g",
340 """Select a setpoint to be the current setpoint.
341
342 :type: int
343
344 Valid range is 0 to 17 when on the Cycle screen or
345 or 0 to 2 in case of operator screen (0=hot, 1=ambient, 2=cold).
346 """,
347 validator=truncated_range,
348 values=[0, 17]
349 )
350
351 local_lockout = Instrument.setting(
352 "%s",
353 """``True`` disables TS GUI, ``False`` enables it.
354 """,
355 validator=strict_discrete_set,
356 values={True: r"%LL", False: r"%GL"},
357 map_values=True
358 )
359
360 auxiliary_condition_code = Instrument.measurement(
361 "AUXC?",
362 """Read out auxiliary condition status register.
363
364 :type: int
365
366 Relevant flags are:
367
368 ====== ======
369 Bit Meaning
370 ====== ======
371 10 None
372 9 Ramp mode
373 8 Mode: 0 programming, 1 manual
374 7 None
375 6 TS status: 0 start-up, 1 ready
376 5 Flow: 0 off, 1 on
377 4 Sense mode: 0 air, 1 DUT
378 3 Compressor: 0 on, 1 off (heating possible)
379 2 Head: 0 lower, upper
380 1 None
381 0 None
382 ====== ======
383
384 Refer to chapter 4 in the manual
385
386 """,
387 )
388
389 copy_active_setup_file = Instrument.setting(
390 "CFIL %g",
391 """Copy active setup file (0) to setup n (1 - 12).
392
393 :type: int
394 """,
395 validator=strict_range,
396 values=[1, 12]
397 )
398
399 compressor_enable = Instrument.setting(
400 "COOL %g",
401 """ ``True`` enables compressors, ``False`` disables it.
402
403 :type: Boolean
404
405 """,
406 validator=strict_discrete_set,
407 map_values=True,
408 values={True: 1, False: 0}
409 )
410
411 total_cycle_count = Instrument.control(
412 "CYCC?", "CYCC %g",
413 """Set or read current cycle count (1 - 9999).
414
415 :type: int
416
417 Sending 0 will stop cycling
418
419 """,
420 validator=truncated_range,
421 values=[0, 9999]
422 )
423
424 cycling_enable = Instrument.setting(
425 "CYCL %g",
426 """CYCL Start/stop cycling.
427
428 :type: bool
429
430 cycling_enable = True (start cycling)
431 cycling_enable = False (stop cycling)
432 """,
433 validator=strict_discrete_set,
434 map_values=True,
435 values={True: 1, False: 0}
436 )
437
438 current_cycle_count = Instrument.measurement(
439 "CYCL?",
440 """Read the number of cycles to do
441
442 :type: int
443
444 """,
445 )
446
447 error_code = Instrument.measurement(
448 "EROR?", # it is indeed EROR
449 """Read the device-specific error register (16 bits).
450
451 :type: :class:`ErrorCode`
452 """,
453 get_process=lambda v: ErrorCode(int(v)),
454 )
455
456 nozzle_air_flow_rate = Instrument.measurement(
457 "FLWR?",
458 """Read main nozzle air flow rate in scfm.
459 """
460 )
461
462 main_air_flow_rate = Instrument.measurement(
463 "FLRL?",
464 """Read main nozzle air flow rate in liters/sec.
465 """
466 )
467
468 learn_mode = Instrument.control(
469 "LRNM?", "LRNM %g",
470 """Control DUT automatic tuning (learning).
471
472 :type: bool
473 ``False``: off
474 ``True``: automatic tuning on
475
476 """,
477 validator=strict_discrete_set,
478 map_values=True,
479 values={True: 1, False: 0}
480 )
481
482 ramp_rate = Instrument.control(
483 "RAMP?", "RAMP %g",
484 """Control ramp rate (K / min).
485
486 :type: float
487
488 allowed values:
489 nn.n: 0 to 99.9 in 0.1 K per minute steps.
490 nnnn: 100 to 9999 in 1 K per minute steps.
491 """,
492 validator=strict_discrete_set,
493 values={i/10 for i in range(1000)} | {i for i in range(100, 10000)}
494 )
495
496 dynamic_temperature_setpoint = Instrument.measurement(
497 "SETD?",
498 """Read the dynamic temperature setpoint.
499
500 :type: float
501 """
502 )
503
504 load_setup_file = Instrument.setting(
505 "SFIL %g",
506 """loads setup file SFIL.
507
508 Valid range is between 1 to 12.
509
510 :type: int
511 """,
512 validator=strict_range,
513 values=[1, 12]
514 )
515
516 temperature_event_status = Instrument.measurement(
517 "TESR?",
518 """ temperature event status register.
519
520 :type: :class:`.TemperatureStatusCode`
521
522 Hint: Reading will clear register content.
523
524 """,
525 )
526
527 air_temperature = Instrument.measurement(
528 "TMPA?",
529 """Read air temperature in 0.1 °C increments.
530
531 :type: float
532 """
533 )
534
535 dut_temperature = Instrument.measurement(
536 "TMPD?",
537 """Read DUT temperature, in 0.1 °C increments.
538
539 :type: float
540
541 """
542 )
543
544 mode = Instrument.measurement(
545 "WHAT?",
546 """Returns a string indicating what the system is doing at the time the query is processed.
547
548 :type: string
549
550 """,
551 values={'manual': 5,
552 'program': 6,
553 },
554 map_values=True,
555 dynamic=True
556 )
557
558 def reset(self):
559 """Reset (force) the System to the Operator screen.
560
561 :returns: self
562
563 """
564 self.write("RSTO")
565
566 return self
567
568 def enter_cycle(self):
569 """Enter Cycle by sending ``RMPC 1``.
570
571 :returns: self
572
573 """
574 self.write("RMPC 1")
575
576 return self
577
578 def enter_ramp(self):
579 """Enter Ramp by sending ``RMPS 0``.
580
581 :returns: self
582 """
583 self.write("RMPS 0")
584
585 return self
586
587 def clear(self):
588 """Clear device-specific errors.
589
590 See :attr:`~.error_code` for further information.
591 """
592 self.write("CLER")
593
594 return self
595
596 def next_setpoint(self):
597 """Step to the next setpoint during temperature cycling.
598 """
599 self.write("NEXT")
600
601 def configure(self,
602 temp_window=1,
603 dut_type='T',
604 soak_time=30,
605 dut_constant=100,
606 temp_limit_air_low=-60,
607 temp_limit_air_high=220,
608 temp_limit_air_dut=50,
609 maximum_test_time=1000
610 ):
611 """Convenience method for most relevant configuration properties.
612
613 :param dut_type:
614 string: indicating which DUT type to use
615 :param soak_time:
616 float: elapsed time in soak_window before settling is indicated
617 :param soak_window:
618 float: Soak window size or temperature settlings bounds (K)
619 :param dut_constant:
620 float: time constant of DUT, higher values indicate higher thermal mass
621 :param temp_limit_air_low:
622 float: minimum flow temperature limit (°C)
623 :param temp_limit_air_high:
624 float: maximum flow temperature limit (°C)
625 :param temp_limit_air_dut:
626 float: allowed temperature difference (K) between DUT and Flow
627 :param maximum_test_time:
628 float: maximum test time (seconds) for a single temperature point (safety)
629
630 :returns: self
631 """
632
633 self.temperature_setpoint_window = temp_window
634
635 self.temperature_limit_air_low = temp_limit_air_low
636
637 self.temperature_limit_air_high = temp_limit_air_high
638
639 self.dut_type = dut_type
640
641 self.maximum_test_time = maximum_test_time
642
643 if dut_type is None:
644 self.dut_mode = 'OFF'
645 else:
646 self.dut_constant = dut_constant
647 self.dut_mode = 'ON'
648
649 self.temperature_limit_air_dut = temp_limit_air_dut
650
651 self.temperature_soak_time = soak_time
652
653 # logging:
654
655 wd = self.temperature_setpoint_window
656
657 airflwlimlow = self.temperature_limit_air_low
658
659 airflwlimhigh = self.temperature_limit_air_high
660
661 dut = self.dut_type
662
663 tst_time = self.maximum_test_time
664
665 airdutlim = self.temperature_limit_air_dut
666
667 sktime = self.temperature_soak_time
668
669 message = (
670 "Configuring TS finished, reading back:\n"
671 f"DUT type: {dut}\n"
672 f"Temperature Window: {wd} K\n"
673 f"Maximum test time: {tst_time} s\n"
674 f"Air flow temperature limit low: {airflwlimlow:.1f} K\n"
675 f"Air flow temperature limit high: {airflwlimhigh:.1f} K\n"
676 f"Air to DUT temperature limit: {airdutlim} degC\n"
677 f"Soak time {sktime} s\n"
678 )
679
680 log.info(message)
681
682 return self
683
684 def set_temperature(self, set_temp):
685 """sweep to a specified setpoint.
686
687 :param set_temp:
688 target temperature for DUT (float)
689
690 :returns: self
691 """
692 if self.mode == 'manual':
693 message = f"new set point temperature: {set_temp:.1f} Deg"
694 log.info(message)
695
696 if set_temp <= 20:
697 self.set_point_number = 2 # cold
698 elif set_temp < 30:
699 self.set_point_number = 1 # ambient
700 elif set_temp >= 30:
701 self.set_point_number = 0 # hot
702 else:
703 raise ValueError(f"Temperature {set_temp} is impossible to set!")
704
705 self.temperature_setpoint = set_temp # fixed typo in attr name
706
707 return self
708
709 def wait_for_settling(self, time_limit=300):
710 """block script execution until TS is settled.
711
712 :param time_limit:
713 set the maximum blocking time within TS has to settle (float).
714
715 :returns: self
716
717 Script execution is blocked until either TS has settled
718 or time_limit has been exceeded (float).
719 """
720
721 time.sleep(1)
722 t = 0
723 t_start = time.time()
724 while not self.at_temperature(): # assert at temperature
725 time.sleep(1)
726 t = time.time() - t_start
727
728 tstatus = self.temperature_condition_status_code
729
730 message = ("temp_set= %4.1f deg, "
731 "temp= %4.1f deg, "
732 "time= %.2f s, "
733 "status= %s"
734 )
735
736 log.info(message,
737 self.temperature_setpoint,
738 self.temperature,
739 t,
740 tstatus)
741
742 if t > time_limit:
743 log.info('no settling achieved')
744 break
745 log.info('finished this temperature point')
746
747 return self
748
749 def shutdown(self, head=False):
750 """Turn down TS (flow and remote operation).
751
752 :param head: Lift head if ``True``
753
754 :returns: self
755 """
756
757 self.enable_air_flow = 0
758 self.remote_mode = False
759 if head:
760 self.head = 'up'
761 super().shutdown()
762
763 return self
764
765 def start(self, enable_air_flow=True):
766 """start TS in remote mode.
767
768 :param enable_air_flow: flow starts if ``True``
769
770 :returns: self
771 """
772
773 self.remote_mode = 1
774 self.enable_air_flow = enable_air_flow # enable TS
775
776 return self
777
778 def error_status(self):
779 """Returns error status code (maybe used for logging).
780
781 :returns: :class:`ErrorCode`
782 """
783 code = self.error_code
784 if not code == 0:
785 log.warning('%s', code)
786 return code
787
788 def cycling_stopped(self):
789 """:returns: ``True`` if cycling has stopped.
790 """
791 return TemperatureStatusCode.CYCLING_STOPPED in self.temperature_condition_status_code
792
793 def end_of_all_cycles(self):
794 """:returns: ``True`` if cycling has stopped.
795 """
796 return TemperatureStatusCode.END_OF_ALL_CYCLES in self.temperature_condition_status_code
797
798 def end_of_one_cycle(self):
799 """:returns: ``True`` if TS is at end of one cycle.
800 """
801 return TemperatureStatusCode.END_OF_ONE_CYCLE in self.temperature_condition_status_code
802
803 def end_of_test(self):
804 """:returns: ``True`` if TS is at end of test.
805 """
806 return TemperatureStatusCode.END_OF_TEST in self.temperature_condition_status_code
807
808 def not_at_temperature(self):
809 """:returns: ``True`` if not at temperature.
810 """
811 return TemperatureStatusCode.NOT_AT_TEMPERATURE in self.temperature_condition_status_code
812
813 def at_temperature(self):
814 """:returns: ``True`` if at temperature.
815 """
816 return TemperatureStatusCode.AT_TEMPERATURE in self.temperature_condition_status_code