Debian Codegraph @

pymeasure/instruments/mksinst/mksinst.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 from re import compile
26
27 from pymeasure.instruments import Channel, Instrument
28 from pymeasure.instruments.validators import strict_discrete_set
29
30
31 class RelayChannel(Channel):
32 """
33 Settings of the optionally included setpoint relay.
34
35 The relay is energized either below or above the setpoint depending on the
36 'direction' property. The relay is de-energized when the reset value is
37 crossed in the opposite direction.
38
39 Note that device by default uses an auto hysteresis setting of 10% of the
40 setpoint value that overwrites the current reset value whenever the setpoint
41 value or direction is changed. If other hysteresis value than 10% is
42 required, first set the setpoint value and direction before setting the
43 reset value.
44 """
45 status = Channel.measurement(
46 "SS{ch}?",
47 """Get the setpoint relay status""",
48 values={True: "SET", False: "CLEAR"},
49 )
50
51 setpoint = Channel.control(
52 "SP{ch}?", "SP{ch}!%s",
53 """Control the relay switch setpoint""",
54 check_set_errors=True,
55 )
56
57 resetpoint = Channel.control(
58 "SH{ch}?", "SH{ch}!%s",
59 """Control the relay switch off value""",
60 check_set_errors=True,
61 )
62
63 direction = Channel.control(
64 "SD{ch}?", "SD{ch}!%s",
65 """Control the switching direction""",
66 validator=strict_discrete_set,
67 values=["ABOVE", "BELOW"],
68 check_set_errors=True,
69 )
70
71
72 class MKSInstrument(Instrument):
73 """Abstract MKS Instrument
74
75 Connection to the device is made through an RS232/RS485 serial connection.
76 The communication protocol of these devices is as follows:
77
78 Query: '@<aaa><Command>?;FF' with the response '@<aaa>ACK<Response>;FF'
79 Set command: '@<aaa><Command>!<parameter>;FF' with the response '@<aaa>ACK<Response>;FF'
80 Above <aaa> is an address from 001 to 254 which can be specified upon
81 initialization. Since ';FF' is not supported by pyvisa as terminator this
82 class overloads the device communication methods.
83
84 :param adapter: pyvisa resource name of the instrument or adapter instance
85 :param string name: The name of the instrument.
86 :param address: device address included in every message to the instrument
87 (default=253)
88 :param kwargs: Any valid key-word argument for Instrument
89 """
90
91 def __init__(self, adapter, name="MKS Instrument", address=253, **kwargs):
92 super().__init__(
93 adapter,
94 name,
95 includeSCPI=False,
96 read_termination=";", # in reality its ";FF"
97 # which is, however, invalid for pyvisa. Therefore extra bytes have to
98 # be read in the read() method and the terminators are hardcoded here.
99 write_termination=";FF",
100 **kwargs
101 )
102 self.address = address
103 # compiled regular expression for finding numerical values in reply strings
104 self._re_response = compile(fr"@{self.address:03d}(?P<ack>ACK)?(?P<msg>.*)")
105
106 def _extract_reply(self, reply):
107 """ preprocess_reply function which tries to extract <Response> from
108 '@<aaa>ACK<Response>;FF'. If <Response> can not be identified the orignal string
109 is returned.
110 :param reply: reply string
111 :returns: string with only the response, or the original string
112 """
113 rvalue = self._re_response.search(reply)
114 if rvalue:
115 return rvalue.group('msg')
116 return reply
117
118 def _prepend_address(self, cmd):
119 """
120 create command string by including the device address
121 """
122 return f"@{self.address:03d}{cmd}"
123
124 def _check_extra_termination(self):
125 """
126 Check the read termination to correspond to the protocol
127 """
128 t = super().read_bytes(2) # read extra termination chars 'FF'
129 if t != b'FF':
130 raise ValueError(f"unexpected termination string received {t}")
131
132 def read(self):
133 """
134 Reads from the instrument including the correct termination characters
135 """
136 ret = super().read()
137 self._check_extra_termination()
138 return self._extract_reply(ret)
139
140 def write(self, command):
141 """
142 Write to the instrument including the device address.
143
144 :param command: command string to be sent to the instrument
145 """
146 super().write(self._prepend_address(command))
147
148 def check_set_errors(self):
149 """
150 Check reply string for acknowledgement string.
151 """
152 ret = super().read() # use super read to get raw reply
153 reply = self._re_response.search(ret)
154 if reply:
155 if reply.group('ack') == 'ACK':
156 self._check_extra_termination()
157 return []
158 # no valid acknowledgement message found
159 raise ValueError(f"invalid reply '{ret}' found in check_errors")