pytrms 0.9.2__py3-none-any.whl → 0.9.5__py3-none-any.whl

pytrms/clients/modbus.py

@@ -1,528 +1,532 @@
-"""Module modbus.py
-
-"""
-import os
-import struct
-import time
-import logging
-from collections import namedtuple
-from functools import lru_cache
-from itertools import tee
-
-import pyModbusTCP.client
-
-from . import _par_id_file
-from .._base.ioniclient import IoniClientBase
-
-log = logging.getLogger(__name__)
-
-__all__ = ['IoniconModbus']
-
-
-def _patch_is_open():
-    # Note: the .is_open and .timeout attributes were changed
-    #  from a function to a property!
-    # 
-    # 0.2.0 2022-06-05
-    # 
-    #  - ModbusClient: parameters are now properties instead of methods (more intuitive).
-    # 
-    # from the [changelog](https://github.com/sourceperl/pyModbusTCP/blob/master/CHANGES):
-    major, minor, patch = pyModbusTCP.__version__.split('.')
-    if int(minor) < 2:
-        return lambda mc: mc.is_open()
-    else:
-        return lambda mc: mc.is_open
-
-_is_open = _patch_is_open()
-
-with open(_par_id_file) as f:
-    it = iter(f)
-    assert next(it).startswith('ID\tName'), ("Modbus parameter file is corrupt: "
-            + f.name
-            + "\n\ntry re-installing the PyTRMS python package to fix it!")
-    _id_to_descr = {int(id_): name for id_, name, *_ in (line.strip().split('\t') for line in it)}
-
-# look-up-table for c_structs (see docstring of struct-module for more info).
-# Note: almost *all* parameters used by IoniTOF (esp. AME) are 'float', with
-#  some exceptions that are 'short' (alive_counter, n_parameters) or explicitly
-#  marked to be 'int' (AME_RunNumber, et.c.):
-_fmts = dict([
-    ('float', '>f'),
-    ('double', '>d'),
-    ('short', '>h'),
-    ('int', '>i'),
-    ('long', '>q'),
-])
-
-_register = namedtuple('register_info', ['n_registers', 'c_format', 'reg_format'])
-_timecycle = namedtuple('timecycle_info', ('rel_cycle', 'abs_cycle', 'abs_time', 'rel_time'))
-_parameter = namedtuple('parameter_info', ('set', 'act', 'par_id', 'state'))
-
-
-def _get_fmt(c_format):
-    if c_format in _fmts:
-        c_format = _fmts[c_format]
-
-    n_registers = max(struct.calcsize(c_format) // 2, 1)
-    reg_format = '>' + 'H' * n_registers
-
-    return _register(n_registers, c_format, reg_format)
-
-
-def _unpack(registers, format='>f'):
-    """Convert a list of register values to a numeric Python value.
-
-    Depending on 'c_type', the value is packed into two or four
-    8-bit registers, for 2-byte (single) and 4-byte (double)
-    representation, respectively.
-
-    >>> _unpack([17448, 0], 'float')
-    672.0
-
-    >>> _unpack([17446, 32768], 'float')
-    666.0
-    
-    >>> _unpack([16875, 61191, 54426, 37896], 'double')
-    3749199524.83057
-    
-    >>> _unpack([16875, 61191, 54426, 37896], 'long')
-    4750153048903029768
-    
-    """
-    n, c_format, reg_format = _get_fmt(format)
-    assert n == len(registers), f"c_format '{c_format}' needs [{n}] registers (got [{len(registers)}])"
-
-    return struct.unpack(c_format, struct.pack(reg_format, *registers))[0]
-
-def _pack(value, format='>f'):
-    """Convert floating point 'value' to registers.
-
-    Depending on 'c_type', the value is packed into two or four
-    8-bit registers, for 2-byte (single) and 4-byte (double)
-    representation, respectively.
-    """
-    _, c_format, reg_format = _get_fmt(format)
-
-    return struct.unpack(reg_format, struct.pack(c_format, value))
-
-
-class IoniconModbus(IoniClientBase):
-
-    address = dict([
-        ('server_state',     (    0, '>f', True)),  # 0: Not ready, 1: Ready, 2: Startup
-        ('measure_state',    (    2, '>f', True)),  # 0: Not running | 1: running | 2: Just Started | 3: Just Stopped
-        ('instrument_state', (    4, '>f', True)),  # 0: Not Ok, 1: Ok, 2: Error, 3: Warning
-        ('alive_counter',    (    6, '>H', True)),  # (updated every 500 ms)
-        ('n_parameters',     ( 2000, '>H', True)),
-        ('tc_raw',           ( 4000, '>f', True)),
-        ('tc_conc',          ( 6000, '>f', True)),
-        ('n_masses',         ( 8000, '>f', True)),
-        # ('n_corr',         ( 7000, '>i', True)),  # not implemented?
-        ('tc_components',    (10000, '>f', True)),
-        ('ame_alarms',       (12000, '>f', True)),
-        ('user_number',      (13900, '>i', True)),
-        ('step_number',      (13902, '>i', True)),
-        ('run_number',       (13904, '>i', True)),
-        ('use_mean',         (13906, '>i', True)),
-        ('action_number',    (13912, '>i', True)),
-        ('version_major',    (13918, '>h', True)),
-        ('version_minor',    (13919, '>h', True)),
-        ('version_patch',    (13920, '>h', True)),
-        ('ame_state',        (13914, '>i', True)),  # Running 0=Off; 1=On (not implemented!)
-        ('n_components',     (14000, '>f', True)),
-        ('component_names',  (14002, '>f', True)),
-        ('ame_mean_data',    (26000, '>f', True)),
-        ('n_ame_mean',       (26002, '>d', True)),
-    ])
-
-    @classmethod
-    def use_legacy_input_registers(klaas, use_input_reg = True):
-        """Read from input- instead of holding-registers (legacy method to be compatible with AME1.0)."""
-        use_holding = not use_input_reg
-        modded = dict()
-        for key, vals in klaas.address.items():
-            modded[key] = vals[0], vals[1], use_holding
-        klaas.address.update(modded)
-
-    @property
-    def _alive_counter(self):
-        return self._read_reg(*self.address['alive_counter'])
-
-    @property
-    def is_connected(self):
-        if not _is_open(self.mc):
-            return False
-
-        # wait for the IoniTOF alive-counter to change (1 second max)...
-        initial_count = self._alive_counter
-        timeout_s = 3  # counter should increase every 500 ms, approximately
-        started_at = time.monotonic()
-        while time.monotonic() < started_at + timeout_s:
-            if initial_count != self._alive_counter:
-                return True
-
-            time.sleep(10e-3)
-        return False
-
-    @property
-    def is_running(self):
-        return 1.0 == self._read_reg(*self.address['measure_state'])
-
-    @property
-    def error_state(self):
-        value = self._read_reg(*self.address['instrument_state'])
-        return IoniconModbus._instrument_states.get(value, value)
-
-    _instrument_states = {
-            0.0: "Not Okay",
-            1.0: "Okay",
-            2.0: "Error",
-            3.0: "Warning",
-    }
-
-    @property
-    def server_state(self):
-        value = self._read_reg(*self.address['server_state'])
-        return IoniconModbus._server_states.get(value, value)
-
-    _server_states = {
-            0.0: "Not Ready",
-            1.0: "Ready",
-            2.0: "Startup",
-    }
-
-    def __init__(self, host='localhost', port=502):
-        super().__init__(host, port)
-        # Note: we patch the behaviour such, that it behaves like pre-0.2
-        #  (from the time of development of this module), BUT we skip the
-        #  auto_close-feature for the sake of speed:
-        # 
-        # 0.2.0 2022-06-05
-        # 
-        #  - ModbusClient: now TCP auto open mode is active by default (auto_open=True, auto_close=False).
-        #
-        # from the [changelog](https://github.com/sourceperl/pyModbusTCP/blob/master/CHANGES)
-        self.mc = pyModbusTCP.client.ModbusClient(host=self.host, port=self.port,
-                auto_open = False, auto_close = False
-        )
-        # try connect immediately:
-        try:
-            self.connect()
-        except TimeoutError as exc:
-            log.warn(f"{exc} (retry connecting when the Instrument is set up)")
-        self._addresses = {}
-
-    def connect(self, timeout_s=10):
-        log.info(f"[{self}] connecting to Modbus server...")
-        # Note: .timeout-attribute changed to a property with 0.2.0 (see comments above)
-        if callable(self.mc.timeout):
-            self.mc.timeout(timeout_s)
-        else:
-            self.mc.timeout = timeout_s
-        if not self.mc.open():
-            raise TimeoutError(f"[{self}] no connection to modbus socket")
-
-        started_at = time.monotonic()
-        while time.monotonic() < started_at + timeout_s:
-            if self.is_connected:
-                break
-
-            time.sleep(10e-3)
-        else:
-            self.disconnect()
-            raise TimeoutError(f"[{self}] no connection to IoniTOF");
-
-    def disconnect(self):
-        if _is_open(self.mc):
-            self.mc.close()
-
-    @property
-    @lru_cache
-    def n_parameters(self):
-        return int(self._read_reg(*self.address['n_parameters']))
-
-    @property
-    @lru_cache
-    def n_masses(self):
-        return int(self._read_reg(*self.address['n_masses']))
-
-    @property
-    @lru_cache
-    def n_components(self):
-        return int(self._read_reg(*self.address['n_components']))
-
-    def read_parameter(self, par_name):
-        """Read any previously loaded parameter by name.
-
-        For example, after calling `.read_components()`, one can call
-        `.read_parameter('DPS_Udrift')` to get only this value with no overhead.
-        """
-        try:
-            return self._read_reg(*self.address[par_name])
-        except KeyError as exc:
-            raise KeyError("did you call one of .read_instrument_data(), .read_traces(), et.c. first?")
-
-    def read_instrument_data(self):
-
-        # Each block consists of 6 registers:
-        # Register 1: Parameter ID
-        # Register 2-3: Parameter Set Value as float(real)
-        # Register 4-5: Parameter Act Value as float(real)
-        # Register 6: Parameter state
-        start_register = 2001
-        blocksize = 6
-        superblocksize = 20*blocksize
-
-        rv = dict()
-        # read 20 parameters at once to save transmission..
-        for superblock in range(0, blocksize*self.n_parameters, superblocksize):
-            offset = start_register + superblock
-            # always using input_register
-            input_regs = self.mc.read_input_registers(offset, superblocksize)
-            # ..and handle one block per parameter:
-            for block in range(0, superblocksize, blocksize):
-                par_id, set1, set2, act1, act2, state = input_regs[block:block+6]
-                par_id = _unpack([par_id], '>H')
-                if len(rv) >= self.n_parameters or par_id == 0:
-                    break
-
-                try:
-                    descr = _id_to_descr[par_id]
-                except KeyError as exc:
-                    log.error("par Id %d not in par_ID_list!" % (par_id))
-                    continue
-
-                # save the *act-value* in the address-space for faster lookup:
-                self.address[descr] = (start_register + superblock + block + 1 + 2, '>f')
-                vset = _unpack([set1, set2], '>f')
-                vact = _unpack([act1, act2], '>f')
-                rv[descr] = _parameter(vset, vact, par_id, state)
-
-        return rv
-
-    def write_instrument_data(self, par_id, new_value, timeout_s=10):
-
-        # Each command-block consists of 3 registers:
-        # Register 1: Parameter ID
-        # Register 2-3: Parameter Set Value as float(real)
-        start_register = 40000
-        blocksize = 3
-
-        if isinstance(par_id, str):
-            try:
-                par_id = next(k for k, v in _id_to_descr.items() if v == par_id)
-            except StopIteration as exc:
-                raise KeyError(str(par_id))
-        par_id = int(par_id)
-        if par_id not in _id_to_descr:
-            raise IndexError(str(par_id))
-
-        start_register += blocksize * par_id
-
-        retry_time = 0
-        while retry_time < timeout_s:
-            # a value of 0 indicates ready-to-write:
-            if self.mc.read_holding_registers(start_register) == [0]:
-                break
-            retry_time += 0.5
-            time.sleep(0.5)
-        else:
-            raise TimeoutError(f'register {start_register} timed out after {timeout_s}s')
-
-        reg_values = [start_register] + list(_pack(new_value))
-        self.mc.write_multiple_registers(start_register, reg_values)
-
-    @lru_cache
-    def read_masses(self, update_address_at=None, with_format='>f'):
-        start_reg, c_fmt, _ = self.address['n_masses']
-        start_reg += 2  # number of components as float..
-        masses = self._read_reg_multi(start_reg, c_fmt, self.n_masses)  # input_register
-        if update_address_at:
-            n_bytes, c_fmt, _ = _get_fmt(with_format)
-            self.address.update({
-                "{0:.4}".format(mass): (update_address_at + i * n_bytes, c_fmt)
-                for i, mass in enumerate(masses)
-            })
-
-        return masses
-
-    def read_traces(self, kind='conc'):
-        """Returns the current traces, where `kind` is one of 'conc', 'raw', 'components'.
-        """
-        start_reg, c_fmt, _is_holding = self.address['tc_' + kind]
-        start_reg += 14  # skipping timecycles..
-
-        # update the address-space with the current kind
-        #  for later calls to `.read_parameter()`:
-        masses = self.read_masses(update_address_at=start_reg)
-        values = self._read_reg_multi(start_reg, c_fmt, self.n_masses, _is_holding)
-
-        return dict(zip(
-            ("{0:.4}".format(mass) for mass in masses), values
-        ))
-
-    def read_timecycle(self, kind='conc'):
-        """Returns the current timecycle, where `kind` is one of conc|raw|components.
-
-        Absolute time as double (8 bytes), seconds since 01.01.1904, 01:00 am.
-        Relative time as double (8 bytes) in seconds since measurement start.
-        """
-        start_reg, _, _is_holding = self.address['tc_' + kind]
-
-        return _timecycle(
-            int(  self._read_reg(start_reg +  2, '>f', _is_holding)),
-            int(  self._read_reg(start_reg +  4, '>f', _is_holding)),
-            float(self._read_reg(start_reg +  6, '>d', _is_holding)),
-            float(self._read_reg(start_reg + 10, '>d', _is_holding)),
-        )
-
-    @lru_cache
-    def read_component_names(self):
-        # 14002 ff: Component Names (maximum length per name:
-        # 32 chars (=16 registers), e.g. 14018 to 14033: "Isoprene")
-        name_start_reg, _, _is_holding = self.address['component_names']
-        data_start_reg, c_fmt, _       = self.address['tc_components']
-        data_start_reg += 14  # skip timecycle info..
-
-        _read = self.mc.read_holding_registers if _is_holding else self.mc.read_input_registers
-        rv = []
-        for index in range(self.n_components):
-            n_bytes, c_format, reg_format = _get_fmt('>16H')
-            register = _read(name_start_reg + index * 16, n_bytes)
-            chars = struct.pack(reg_format, *register)
-            decoded = chars.decode('latin-1').strip('\x00')
-            self.address[decoded] = (data_start_reg + index * 2, c_fmt, _is_holding)
-            rv.append(decoded)
-
-        return rv
-
-    def read_components(self):
-        start_reg, c_fmt, _is_holding = self.address['tc_components']
-        start_reg += 14  # skipping timecycles...
-        values = self._read_reg_multi(start_reg, c_fmt, self.n_components, _is_holding)
-
-        return dict(zip(self.read_component_names(), values))
-
-    def read_ame_version(self):
-        start_reg, c_fmt, _is_holding = self.address['version_major']
-        major, minor, patch = self._read_reg_multi(start_reg, c_fmt, 3, _is_holding)
-
-        return f"{major}.{minor}.{patch}"
-
-    def read_ame_alarms(self):
-        start_reg, c_fmt, _is_holding = self.address['ame_alarms']
-        n_alarms = int(self._read_reg(start_reg, c_fmt, _is_holding))
-        values = self._read_reg_multi(start_reg + 2, c_fmt, n_alarms, _is_holding)
-
-        return dict(zip(self.read_component_names(), map(bool, values)))
-
-    def read_ame_timecycle(self):
-        return self.read_timecycle(kind='components')
-
-    _ame_parameter = namedtuple('ame_parameter', [
-        'step_number',
-        'run_number',
-        'use_mean',
-        'action_number',
-        'user_number'
-    ])
-
-    def read_ame_numbers(self):
-        return IoniconModbus._ame_parameter(
-            int(self._read_reg(*self.address['step_number'])),
-            int(self._read_reg(*self.address['run_number'])),
-            int(self._read_reg(*self.address['use_mean'])),
-            int(self._read_reg(*self.address['action_number'])),
-            int(self._read_reg(*self.address['user_number'])),
-        )
-
-    _ame_mean = namedtuple('ame_mean_info', [
-        'data_ok',
-        'mod_time',
-        'start_cycle',
-        'stop_cycle',
-        'mean_values',
-        'std_error',
-    ])
-
-    def write_ame_action(self, action_number):
-        start_reg, c_fmt, _ = self.address['action_number']
-        set_value = _pack(action_number, c_fmt)
-        self.mc.write_multiple_registers(start_reg, set_value)
-
-    def read_ame_mean(self, step_number=None):
-        start_reg, c_fmt, _is_holding = self.address['ame_mean_data']
-        data_ok = int(self._read_reg(start_reg, c_fmt, _is_holding))
-        if not data_ok:
-            return IoniconModbus._ame_mean(data_ok, 0, 0, 0, [], [])
-
-        n_masses = int(self._read_reg(start_reg + 6, c_fmt, _is_holding))
-        n_steps  = int(self._read_reg(start_reg + 8, c_fmt, _is_holding))
-
-        if step_number is None:
-            step_number = int(self._read_reg(*self.address['step_number']))
-        elif not (0 < step_number <= n_steps):
-            raise IndexError(f"step_number [{step_number}] out of bounds: 0 < step <= [{n_steps}]")
-
-        datablock_size = 1 + 1 + n_masses + n_masses
-        start_addr = (start_reg
-                + 10
-                + n_masses * 2  # skip the masses, same as everywhere
-                + (step_number-1) * datablock_size * 2)  # select datablock
-
-        return IoniconModbus._ame_mean(
-            data_ok,
-            self._read_reg(*self.address['n_ame_mean']),
-            self._read_reg(start_addr + 0, c_fmt, _is_holding),
-            self._read_reg(start_addr + 2, c_fmt, _is_holding),
-            self._read_reg_multi(start_addr + 4,                c_fmt, n_masses, _is_holding),
-            self._read_reg_multi(start_addr + 4 + n_masses * 2, c_fmt, n_masses, _is_holding),
-        )
-
-    def _read_reg(self, addr, c_format, is_holding_register=False):
-        n_bytes, c_format, reg_format = _get_fmt(c_format)
-        _read = self.mc.read_holding_registers if is_holding_register else self.mc.read_input_registers
-        
-        register = _read(addr, n_bytes)
-        if register is None and _is_open(self.mc):
-            raise IOError(f"unable to read ({n_bytes}) registers at [{addr}] from connection")
-        elif register is None and not _is_open(self.mc):
-            raise IOError("trying to read from closed Modbus-connection")
-
-        return _unpack(register, c_format)
-
-    def _read_reg_multi(self, addr, c_format, n_values, is_holding_register=False):
-        rv = []
-        if not n_values > 0:
-            return rv
-
-        _read = self.mc.read_holding_registers if is_holding_register else self.mc.read_input_registers
-
-        n_bytes, c_format, reg_format = _get_fmt(c_format)
-        n_regs = n_bytes * n_values
-
-        # Note: there seems to be a limitation of modbus that
-        #  the limits the number of registers to 125, so we
-        #  read input-registers in blocks of 120:
-        blocks = ((addr + block, min(120, n_regs - block))
-                    for block in range(0, n_regs, 120))
-
-        for block in blocks:
-            register = _read(*block)
-            if register is None and self.is_connected:
-                raise IOError(f"unable to read ({block[1]}) registers at [{block[0]}] from connection")
-            elif register is None and not self.is_connected:
-                raise IOError("trying to read from closed Modbus-connection")
-
-            # group the register-values by n_bytes, e.g. [1,2,3,4,..] ~> [(1,2),(3,4),..]
-            # this is a trick from the itertools-recipes, see
-            # https://docs.python.org/3.8/library/itertools.html?highlight=itertools#itertools-recipes
-            # note, that the iterator is cloned n-times and therefore 
-            # all clones advance in parallel and can be zipped below:
-            batches = [iter(register)] * n_bytes
-
-            rv += [_unpack(reg, c_format) for reg in zip(*batches)]
-
-        return rv
-
+"""Module modbus.py
+
+"""
+import os
+import struct
+import time
+import logging
+from collections import namedtuple
+from functools import lru_cache
+from itertools import tee
+
+import pyModbusTCP.client
+
+from . import _par_id_file
+from .._base.ioniclient import IoniClientBase
+
+log = logging.getLogger(__name__)
+
+__all__ = ['IoniconModbus']
+
+
+def _patch_is_open():
+    # Note: the .is_open and .timeout attributes were changed
+    #  from a function to a property!
+    # 
+    # 0.2.0 2022-06-05
+    # 
+    #  - ModbusClient: parameters are now properties instead of methods (more intuitive).
+    # 
+    # from the [changelog](https://github.com/sourceperl/pyModbusTCP/blob/master/CHANGES):
+    major, minor, patch = pyModbusTCP.__version__.split('.')
+    if int(minor) < 2:
+        return lambda mc: mc.is_open()
+    else:
+        return lambda mc: mc.is_open
+
+_is_open = _patch_is_open()
+
+with open(_par_id_file) as f:
+    it = iter(f)
+    assert next(it).startswith('ID\tName'), ("Modbus parameter file is corrupt: "
+            + f.name
+            + "\n\ntry re-installing the PyTRMS python package to fix it!")
+    _id_to_descr = {int(id_): name for id_, name, *_ in (line.strip().split('\t') for line in it)}
+
+# look-up-table for c_structs (see docstring of struct-module for more info).
+# Note: almost *all* parameters used by IoniTOF (esp. AME) are 'float', with
+#  some exceptions that are 'short' (alive_counter, n_parameters) or explicitly
+#  marked to be 'int' (AME_RunNumber, et.c.):
+_fmts = dict([
+    ('float', '>f'),
+    ('double', '>d'),
+    ('short', '>h'),
+    ('int', '>i'),
+    ('long', '>q'),
+])
+
+_register = namedtuple('register_info', ['n_registers', 'c_format', 'reg_format'])
+_timecycle = namedtuple('timecycle_info', ('rel_cycle', 'abs_cycle', 'abs_time', 'rel_time'))
+_parameter = namedtuple('parameter_info', ('set', 'act', 'par_id', 'state'))
+
+
+def _get_fmt(c_format):
+    if c_format in _fmts:
+        c_format = _fmts[c_format]
+
+    n_registers = max(struct.calcsize(c_format) // 2, 1)
+    reg_format = '>' + 'H' * n_registers
+
+    return _register(n_registers, c_format, reg_format)
+
+
+def _unpack(registers, format='>f'):
+    """Convert a list of register values to a numeric Python value.
+
+    Depending on 'c_type', the value is packed into two or four
+    8-bit registers, for 2-byte (single) and 4-byte (double)
+    representation, respectively.
+
+    >>> _unpack([17448, 0], 'float')
+    672.0
+
+    >>> _unpack([17446, 32768], 'float')
+    666.0
+    
+    >>> _unpack([16875, 61191, 54426, 37896], 'double')
+    3749199524.83057
+    
+    >>> _unpack([16875, 61191, 54426, 37896], 'long')
+    4750153048903029768
+    
+    """
+    n, c_format, reg_format = _get_fmt(format)
+    assert n == len(registers), f"c_format '{c_format}' needs [{n}] registers (got [{len(registers)}])"
+
+    return struct.unpack(c_format, struct.pack(reg_format, *registers))[0]
+
+def _pack(value, format='>f'):
+    """Convert floating point 'value' to registers.
+
+    Depending on 'c_type', the value is packed into two or four
+    8-bit registers, for 2-byte (single) and 4-byte (double)
+    representation, respectively.
+    """
+    _, c_format, reg_format = _get_fmt(format)
+
+    return struct.unpack(reg_format, struct.pack(c_format, value))
+
+
+class IoniconModbus(IoniClientBase):
+
+    address = dict([
+        ('server_state',     (    0, '>f', True)),  # 0: Not ready, 1: Ready, 2: Startup
+        ('measure_state',    (    2, '>f', True)),  # 0: Not running | 1: running | 2: Just Started | 3: Just Stopped
+        ('instrument_state', (    4, '>f', True)),  # 0: Not Ok, 1: Ok, 2: Error, 3: Warning
+        ('alive_counter',    (    6, '>H', True)),  # (updated every 500 ms)
+        ('n_parameters',     ( 2000, '>H', True)),
+        ('tc_raw',           ( 4000, '>f', True)),
+        ('tc_conc',          ( 6000, '>f', True)),
+        ('n_masses',         ( 8000, '>f', True)),
+        # ('n_corr',         ( 7000, '>i', True)),  # not implemented?
+        ('tc_components',    (10000, '>f', True)),
+        ('ame_alarms',       (12000, '>f', True)),
+        ('user_number',      (13900, '>i', True)),
+        ('step_number',      (13902, '>i', True)),
+        ('run_number',       (13904, '>i', True)),
+        ('use_mean',         (13906, '>i', True)),
+        ('action_number',    (13912, '>i', True)),
+        ('version_major',    (13918, '>h', True)),
+        ('version_minor',    (13919, '>h', True)),
+        ('version_patch',    (13920, '>h', True)),
+        ('ame_state',        (13914, '>i', True)),  # Running 0=Off; 1=On (not implemented!)
+        ('n_components',     (14000, '>f', True)),
+        ('component_names',  (14002, '>f', True)),
+        ('ame_mean_data',    (26000, '>f', True)),
+        ('n_ame_mean',       (26002, '>d', True)),
+    ])
+
+    @classmethod
+    def use_legacy_input_registers(klaas, use_input_reg = True):
+        """Read from input- instead of holding-registers (legacy method to be compatible with AME1.0)."""
+        use_holding = not use_input_reg
+        modded = dict()
+        for key, vals in klaas.address.items():
+            modded[key] = vals[0], vals[1], use_holding
+        klaas.address.update(modded)
+
+    @property
+    def _alive_counter(self):
+        return self._read_reg(*self.address['alive_counter'])
+
+    @property
+    def is_connected(self):
+        if not _is_open(self.mc):
+            return False
+
+        # wait for the IoniTOF alive-counter to change (1 second max)...
+        initial_count = self._alive_counter
+        timeout_s = 3  # counter should increase every 500 ms, approximately
+        started_at = time.monotonic()
+        while time.monotonic() < started_at + timeout_s:
+            if initial_count != self._alive_counter:
+                return True
+
+            time.sleep(10e-3)
+        return False
+
+    @property
+    def is_running(self):
+        return 1.0 == self._read_reg(*self.address['measure_state'])
+
+    @property
+    def error_state(self):
+        value = self._read_reg(*self.address['instrument_state'])
+        return IoniconModbus._instrument_states.get(value, value)
+
+    _instrument_states = {
+            0.0: "Not Okay",
+            1.0: "Okay",
+            2.0: "Error",
+            3.0: "Warning",
+    }
+
+    @property
+    def server_state(self):
+        value = self._read_reg(*self.address['server_state'])
+        return IoniconModbus._server_states.get(value, value)
+
+    _server_states = {
+            0.0: "Not Ready",
+            1.0: "Ready",
+            2.0: "Startup",
+    }
+
+    def __init__(self, host='localhost', port=502):
+        super().__init__(host, port)
+        # Note: we patch the behaviour such, that it behaves like pre-0.2
+        #  (from the time of development of this module), BUT we skip the
+        #  auto_close-feature for the sake of speed:
+        # 
+        # 0.2.0 2022-06-05
+        # 
+        #  - ModbusClient: now TCP auto open mode is active by default (auto_open=True, auto_close=False).
+        #
+        # from the [changelog](https://github.com/sourceperl/pyModbusTCP/blob/master/CHANGES)
+        self.mc = pyModbusTCP.client.ModbusClient(host=self.host, port=self.port,
+                auto_open = False, auto_close = False
+        )
+        # try connect immediately:
+        try:
+            self.connect()
+        except TimeoutError as exc:
+            log.warn(f"{exc} (retry connecting when the Instrument is set up)")
+        self._addresses = {}
+
+    def connect(self, timeout_s=10):
+        log.info(f"[{self}] connecting to Modbus server...")
+        # Note: .timeout-attribute changed to a property with 0.2.0 (see comments above)
+        if callable(self.mc.timeout):
+            self.mc.timeout(timeout_s)
+        else:
+            self.mc.timeout = timeout_s
+        if not self.mc.open():
+            raise TimeoutError(f"[{self}] no connection to modbus socket")
+
+        started_at = time.monotonic()
+        while time.monotonic() < started_at + timeout_s:
+            if self.is_connected:
+                break
+
+            time.sleep(10e-3)
+        else:
+            self.disconnect()
+            raise TimeoutError(f"[{self}] no connection to IoniTOF");
+
+    def disconnect(self):
+        if _is_open(self.mc):
+            self.mc.close()
+
+    @property
+    @lru_cache
+    def n_parameters(self):
+        return int(self._read_reg(*self.address['n_parameters']))
+
+    @property
+    @lru_cache
+    def n_masses(self):
+        return int(self._read_reg(*self.address['n_masses']))
+
+    @property
+    @lru_cache
+    def n_components(self):
+        return int(self._read_reg(*self.address['n_components']))
+
+    def read_parameter(self, par_name):
+        """Read any previously loaded parameter by name.
+
+        For example, after calling `.read_components()`, one can call
+        `.read_parameter('DPS_Udrift')` to get only this value with no overhead.
+        """
+        try:
+            return self._read_reg(*self.address[par_name])
+        except KeyError as exc:
+            raise KeyError("did you call one of .read_instrument_data(), .read_traces(), et.c. first?")
+
+    def read_instrument_data(self):
+
+        # Each block consists of 6 registers:
+        # Register 1: Parameter ID
+        # Register 2-3: Parameter Set Value as float(real)
+        # Register 4-5: Parameter Act Value as float(real)
+        # Register 6: Parameter state
+        start_register = 2001
+        blocksize = 6
+        superblocksize = 20*blocksize
+
+        rv = dict()
+        # read 20 parameters at once to save transmission..
+        for superblock in range(0, blocksize*self.n_parameters, superblocksize):
+            offset = start_register + superblock
+            # always using input_register
+            input_regs = self.mc.read_input_registers(offset, superblocksize)
+            # ..and handle one block per parameter:
+            for block in range(0, superblocksize, blocksize):
+                par_id, set1, set2, act1, act2, state = input_regs[block:block+6]
+                par_id = _unpack([par_id], '>H')
+                if len(rv) >= self.n_parameters or par_id == 0:
+                    break
+
+                try:
+                    descr = _id_to_descr[par_id]
+                except KeyError as exc:
+                    log.error("par Id %d not in par_ID_list!" % (par_id))
+                    continue
+
+                # save the *act-value* in the address-space for faster lookup:
+                self.address[descr] = (start_register + superblock + block + 1 + 2, '>f')
+                vset = _unpack([set1, set2], '>f')
+                vact = _unpack([act1, act2], '>f')
+                rv[descr] = _parameter(vset, vact, par_id, state)
+
+        return rv
+
+    def write_instrument_data(self, par_id, new_value, timeout_s=10):
+
+        # This command-structure is written as an array:
+        # Register 0: number of command-blocks to write
+        # Each command-block consists of 3 registers:
+        # Register 1: Parameter ID
+        # Register 2-3: Parameter Set Value as float(real)
+        start_register = 41000
+        blocksize = 3
+
+        if isinstance(par_id, str):
+            try:
+                par_id = next(k for k, v in _id_to_descr.items() if v == par_id)
+            except StopIteration as exc:
+                raise KeyError(str(par_id))
+        par_id = int(par_id)
+        if par_id not in _id_to_descr:
+            raise IndexError(str(par_id))
+
+        # Note: we use only the first command-block for writing:
+        n_blocks = 1
+        reg_values = list(_pack(n_blocks, '>h'))
+        # ...although we could add more command-blocks here:
+        reg_values += list(_pack(par_id, '>h')) + list(_pack(new_value, '>f'))
+
+        # wait for instrument to receive...
+        retry_time = 0
+        while retry_time < timeout_s:
+            # a value of 0 indicates ready-to-write:
+            if self.mc.read_holding_registers(start_register) == [0]:
+                break
+            retry_time += 0.5
+            time.sleep(0.5)
+        else:
+            raise TimeoutError(f'instrument not ready for writing after ({timeout_s}) seconds')
+
+        self.mc.write_multiple_registers(start_register, reg_values)
+
+    @lru_cache
+    def read_masses(self, update_address_at=None, with_format='>f'):
+        start_reg, c_fmt, _ = self.address['n_masses']
+        start_reg += 2  # number of components as float..
+        masses = self._read_reg_multi(start_reg, c_fmt, self.n_masses)  # input_register
+        if update_address_at:
+            n_bytes, c_fmt, _ = _get_fmt(with_format)
+            self.address.update({
+                "{0:.4}".format(mass): (update_address_at + i * n_bytes, c_fmt)
+                for i, mass in enumerate(masses)
+            })
+
+        return masses
+
+    def read_traces(self, kind='conc'):
+        """Returns the current traces, where `kind` is one of 'conc', 'raw', 'components'.
+        """
+        start_reg, c_fmt, _is_holding = self.address['tc_' + kind]
+        start_reg += 14  # skipping timecycles..
+
+        # update the address-space with the current kind
+        #  for later calls to `.read_parameter()`:
+        masses = self.read_masses(update_address_at=start_reg)
+        values = self._read_reg_multi(start_reg, c_fmt, self.n_masses, _is_holding)
+
+        return dict(zip(
+            ("{0:.4}".format(mass) for mass in masses), values
+        ))
+
+    def read_timecycle(self, kind='conc'):
+        """Returns the current timecycle, where `kind` is one of conc|raw|components.
+
+        Absolute time as double (8 bytes), seconds since 01.01.1904, 01:00 am.
+        Relative time as double (8 bytes) in seconds since measurement start.
+        """
+        start_reg, _, _is_holding = self.address['tc_' + kind]
+
+        return _timecycle(
+            int(  self._read_reg(start_reg +  2, '>f', _is_holding)),
+            int(  self._read_reg(start_reg +  4, '>f', _is_holding)),
+            float(self._read_reg(start_reg +  6, '>d', _is_holding)),
+            float(self._read_reg(start_reg + 10, '>d', _is_holding)),
+        )
+
+    @lru_cache
+    def read_component_names(self):
+        # 14002 ff: Component Names (maximum length per name:
+        # 32 chars (=16 registers), e.g. 14018 to 14033: "Isoprene")
+        name_start_reg, _, _is_holding = self.address['component_names']
+        data_start_reg, c_fmt, _       = self.address['tc_components']
+        data_start_reg += 14  # skip timecycle info..
+
+        _read = self.mc.read_holding_registers if _is_holding else self.mc.read_input_registers
+        rv = []
+        for index in range(self.n_components):
+            n_bytes, c_format, reg_format = _get_fmt('>16H')
+            register = _read(name_start_reg + index * 16, n_bytes)
+            chars = struct.pack(reg_format, *register)
+            decoded = chars.decode('latin-1').strip('\x00')
+            self.address[decoded] = (data_start_reg + index * 2, c_fmt, _is_holding)
+            rv.append(decoded)
+
+        return rv
+
+    def read_components(self):
+        start_reg, c_fmt, _is_holding = self.address['tc_components']
+        start_reg += 14  # skipping timecycles...
+        values = self._read_reg_multi(start_reg, c_fmt, self.n_components, _is_holding)
+
+        return dict(zip(self.read_component_names(), values))
+
+    def read_ame_version(self):
+        start_reg, c_fmt, _is_holding = self.address['version_major']
+        major, minor, patch = self._read_reg_multi(start_reg, c_fmt, 3, _is_holding)
+
+        return f"{major}.{minor}.{patch}"
+
+    def read_ame_alarms(self):
+        start_reg, c_fmt, _is_holding = self.address['ame_alarms']
+        n_alarms = int(self._read_reg(start_reg, c_fmt, _is_holding))
+        values = self._read_reg_multi(start_reg + 2, c_fmt, n_alarms, _is_holding)
+
+        return dict(zip(self.read_component_names(), map(bool, values)))
+
+    def read_ame_timecycle(self):
+        return self.read_timecycle(kind='components')
+
+    _ame_parameter = namedtuple('ame_parameter', [
+        'step_number',
+        'run_number',
+        'use_mean',
+        'action_number',
+        'user_number'
+    ])
+
+    def read_ame_numbers(self):
+        return IoniconModbus._ame_parameter(
+            int(self._read_reg(*self.address['step_number'])),
+            int(self._read_reg(*self.address['run_number'])),
+            int(self._read_reg(*self.address['use_mean'])),
+            int(self._read_reg(*self.address['action_number'])),
+            int(self._read_reg(*self.address['user_number'])),
+        )
+
+    _ame_mean = namedtuple('ame_mean_info', [
+        'data_ok',
+        'mod_time',
+        'start_cycle',
+        'stop_cycle',
+        'mean_values',
+        'std_error',
+    ])
+
+    def write_ame_action(self, action_number):
+        self.write_instrument_data(596, action_number, timeout_s=10)
+
+    def read_ame_mean(self, step_number=None):
+        start_reg, c_fmt, _is_holding = self.address['ame_mean_data']
+        data_ok = int(self._read_reg(start_reg, c_fmt, _is_holding))
+        if not data_ok:
+            return IoniconModbus._ame_mean(data_ok, 0, 0, 0, [], [])
+
+        n_masses = int(self._read_reg(start_reg + 6, c_fmt, _is_holding))
+        n_steps  = int(self._read_reg(start_reg + 8, c_fmt, _is_holding))
+
+        if step_number is None:
+            step_number = int(self._read_reg(*self.address['step_number']))
+        elif not (0 < step_number <= n_steps):
+            raise IndexError(f"step_number [{step_number}] out of bounds: 0 < step <= [{n_steps}]")
+
+        datablock_size = 1 + 1 + n_masses + n_masses
+        start_addr = (start_reg
+                + 10
+                + n_masses * 2  # skip the masses, same as everywhere
+                + (step_number-1) * datablock_size * 2)  # select datablock
+
+        return IoniconModbus._ame_mean(
+            data_ok,
+            self._read_reg(*self.address['n_ame_mean']),
+            self._read_reg(start_addr + 0, c_fmt, _is_holding),
+            self._read_reg(start_addr + 2, c_fmt, _is_holding),
+            self._read_reg_multi(start_addr + 4,                c_fmt, n_masses, _is_holding),
+            self._read_reg_multi(start_addr + 4 + n_masses * 2, c_fmt, n_masses, _is_holding),
+        )
+
+    def _read_reg(self, addr, c_format, is_holding_register=False):
+        n_bytes, c_format, reg_format = _get_fmt(c_format)
+        _read = self.mc.read_holding_registers if is_holding_register else self.mc.read_input_registers
+        
+        register = _read(addr, n_bytes)
+        if register is None and _is_open(self.mc):
+            raise IOError(f"unable to read ({n_bytes}) registers at [{addr}] from connection")
+        elif register is None and not _is_open(self.mc):
+            raise IOError("trying to read from closed Modbus-connection")
+
+        return _unpack(register, c_format)
+
+    def _read_reg_multi(self, addr, c_format, n_values, is_holding_register=False):
+        rv = []
+        if not n_values > 0:
+            return rv
+
+        _read = self.mc.read_holding_registers if is_holding_register else self.mc.read_input_registers
+
+        n_bytes, c_format, reg_format = _get_fmt(c_format)
+        n_regs = n_bytes * n_values
+
+        # Note: there seems to be a limitation of modbus that
+        #  the limits the number of registers to 125, so we
+        #  read input-registers in blocks of 120:
+        blocks = ((addr + block, min(120, n_regs - block))
+                    for block in range(0, n_regs, 120))
+
+        for block in blocks:
+            register = _read(*block)
+            if register is None and self.is_connected:
+                raise IOError(f"unable to read ({block[1]}) registers at [{block[0]}] from connection")
+            elif register is None and not self.is_connected:
+                raise IOError("trying to read from closed Modbus-connection")
+
+            # group the register-values by n_bytes, e.g. [1,2,3,4,..] ~> [(1,2),(3,4),..]
+            # this is a trick from the itertools-recipes, see
+            # https://docs.python.org/3.8/library/itertools.html?highlight=itertools#itertools-recipes
+            # note, that the iterator is cloned n-times and therefore 
+            # all clones advance in parallel and can be zipped below:
+            batches = [iter(register)] * n_bytes
+
+            rv += [_unpack(reg, c_format) for reg in zip(*batches)]
+
+        return rv
+