pulsepal.synth_pal

   1"""
   2Python interface for Synth Pal, a waveform synthesizer for Pulse Pal 3.
   3
   4Synth Pal is alternative firmware for Pulse Pal 3 hardware. Each output
   5channel plays a sine, triangle, square or sawtooth wave or white noise, or
   6steps to a fixed voltage, when it is triggered: by a TTL pulse on a trigger
   7channel, from software, or from the thumb joystick. Each channel has its own
   8waveform, peak to peak voltage, mean voltage, resting voltage, play
   9duration, and on and off ramps, and one frequency, 1 Hz to 20 kHz in steps
  10of 0.01 Hz, applies to all four.
  11
  12Everything is accessed through `SynthPalDevice`. Import it, connect to
  13the device's serial port, set the waveforms, and trigger, e.g.
  14
  15```python
  16from pulsepal import SynthPalDevice
  17
  18with SynthPalDevice("COM3") as S:
  19    S.frequency = 440                  # Hz, all channels
  20    S.waveform[1] = "Sine"
  21    S.peak_to_peak[1] = 4              # volts: swings from -2 V to 2 V
  22    S.play_duration[1] = 0.5           # seconds
  23    S.trigger(1)
  24```
  25
  26The device needs Synth Pal firmware, which is in
  27[/Firmware/SynthPal](https://github.com/sanworks/PulsePal/tree/develop/Firmware/SynthPal) in the
  28Pulse Pal repository. Its USB protocol is documented in
  29[PROTOCOL.md](https://github.com/sanworks/PulsePal/blob/develop/Firmware/SynthPal/PROTOCOL.md).
  30
  31## Channel settings
  32
  33Settings that apply to one output channel, such as
  34`SynthPalDevice.peak_to_peak`, are lists indexed by channel number: index
  350 is unused and holds `None`, and indices 1 to 4 hold the settings of
  36output channels 1-4, as in `pulsepal.PulsePalDevice`. Setting an element
  37or a slice programs the device at once. Assigning a whole list sets all
  38four channels, and takes one value per channel: a single value raises an
  39error, because it does not say which channels it is meant for.
  40
  41```python
  42S.peak_to_peak[2] = 5              # channel 2 only
  43S.play_duration[1:5] = [1, 2, 3, 4]
  44S.waveform = ["Square"] * 4        # all four channels
  45```
  46
  47`SynthPalDevice.trigger_mode` is indexed the same way by trigger
  48channel number, 1 or 2.
  49
  50To set several of one channel's settings at once, use
  51`SynthPalDevice.configure`:
  52
  53```python
  54S.configure(2, waveform="Triangle", peak_to_peak=20, mean_voltage=0)
  55```
  56
  57## Units and levels
  58
  59Voltages are in volts, times in seconds, and frequencies in Hz. A periodic
  60waveform, or white noise, swings `peak_to_peak / 2` above and below its
  61`mean_voltage`, and must stay within -10 V to 10 V:
  62`abs(mean_voltage) + peak_to_peak / 2 <= 10`. A `"Fixed Voltage"` channel
  63steps to its `fixed_voltage`, -10 V to 10 V, for its play duration. Between
  64playbacks, a channel outputs its `resting_voltage`, and its
  65`on_ramp_duration` and `off_ramp_duration` fade it in from there and back to
  66it (see "Ramps" below).
  67
  68## Ramps
  69
  70A channel's on ramp follows each trigger, and fades its waveform in from
  71the resting voltage: its peak to peak voltage rises linearly from 0 to
  72its full value, and its mean from the resting voltage to the mean voltage
  73(a fixed voltage ramps from the resting voltage to its voltage). The play
  74duration follows at full amplitude, then the off ramp fades back to the
  75resting voltage. The off ramp also follows a stop: `stop()`, a toggle or
  76gated trigger, or the joystick. So the ramps lengthen playback: from a
  77trigger to rest takes `on_ramp_duration + play_duration +
  78off_ramp_duration`. During its off ramp, a channel counts as stopping: a
  79trigger fades it in again from where it is, without restarting its
  80waveform's cycle, and plays its play duration again. A channel stopped
  81during its on ramp fades out from where it is, at the off ramp's rate.
  82The output never jumps.
  83
  84## Param sync
  85
  86`"Param Sync"`, Pulse Pal's param sync trigger mode, lets the settings of
  87the next trial be sent during the current one, and applied the instant it
  88starts. Change settings in a `SynthPalDevice.batch` block: they are kept
  89here, and sent all at once when it ends. While a trigger channel is in
  90param sync mode, the device stores the whole set, and that channel's next
  91rising edge loads it.
  92
  93```python
  94S.trigger_mode[2] = "Param Sync"   # sent at once
  95with S.batch():
  96    S.frequency = 880
  97    S.peak_to_peak[1] = 2
  98# Stored for trigger channel 2's next rising edge
  99```
 100
 101See `SynthPalDevice.trigger_mode` for what the edge does.
 102
 103## License
 104
 105This file is part of the Sanworks PulsePal repository.
 106Copyright (C) Sanworks LLC, Rochester, New York, USA
 107
 108This program is free software: you can redistribute it and/or modify
 109it under the terms of the GNU General Public License as published by
 110the Free Software Foundation, version 3.
 111
 112This program is distributed WITHOUT ANY WARRANTY and without even the
 113implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 114See the GNU General Public License for more details.
 115
 116You should have received a copy of the GNU General Public License
 117along with this program. If not, see <http://www.gnu.org/licenses/>.
 118"""
 119
 120from dataclasses import dataclass
 121import math
 122import numbers
 123import struct
 124import warnings
 125
 126import numpy as np
 127import serial
 128
 129from . import _common
 130from ._common import ChannelSettings, PulsePalError, to_bool, to_name
 131
 132__all__ = ["SynthPalDevice", "DeviceInfo", "DeviceStatus", "WAVEFORMS", "TRIGGER_MODES"]
 133__docformat__ = "google"
 134
 135WAVEFORMS = ("Sine", "Triangle", "Square", "Sawtooth", "Fixed Voltage", "White Noise")
 136"""Names of the waveforms, in order of their code on the device."""
 137
 138FIXED_VOLTAGE = "Fixed Voltage"
 139
 140TRIGGER_MODES = ("Normal", "Toggle", "Gated", "Param Sync")
 141"""Names of the trigger modes, in order of their code on the device. These
 142are Pulse Pal's trigger modes, with the same codes."""
 143
 144# The output ranges the device chooses from, in order of their index on the
 145# device, with their limits in volts. See "Output ranges" in
 146# /Firmware/SynthPal/PROTOCOL.md.
 147OUTPUT_RANGES = {
 148    "0V:5V": (0.0, 5.0),
 149    "0V:10V": (0.0, 10.0),
 150    "-5V:5V": (-5.0, 5.0),
 151    "-10V:10V": (-10.0, 10.0),
 152}
 153
 154_MAX_VOLTAGE_UV = 10_000_000  # Every output voltage stays within +/-10 V
 155
 156# The settings sync_to_device() sends, in the class's order
 157_CHANNEL_SETTINGS = ("waveform", "peak_to_peak", "fixed_voltage", "mean_voltage", "resting_voltage",
 158                     "play_duration", "on_ramp_duration", "off_ramp_duration", "trigger_mode",
 159                     "link_trigger_channel1", "link_trigger_channel2")
 160_SETTING_NAMES = ("frequency", *_CHANNEL_SETTINGS, "auto_sync")  # The names a script assigns
 161# The ops whose reply _write_command() does not track: those with no reply ('P', 'X', 81 and 89), and the handshake
 162# (72), whose reply read_handshake_reply() reads until the device is quiet
 163_OPS_WITHOUT_TRACKED_REPLY = frozenset({72, 81, 89, ord("P"), ord("X")})
 164
 165
 166def _samples_per_cycle(centihz):
 167    """Samples in one cycle at a frequency, as the device works it out (see SynthPalDevice.samples_per_cycle)."""
 168    return 4 * (2_500_000 // centihz)
 169
 170
 171class _Rejected(PulsePalError):
 172    """The device replied 0: it rejected a command, and changed nothing."""
 173
 174
 175def _is_valid_level(waveform, amplitude_uv, mean_uv):
 176    """Whether the device accepts an output channel's waveform, amplitude and mean voltage together, as
 177    isValidOutputLevel() in /Firmware/SynthPal/Settings.ino checks them. On the device, a channel has one
 178    amplitude: a fixed voltage's voltage, or a periodic waveform's peak to peak voltage."""
 179    if waveform == FIXED_VOLTAGE:
 180        return abs(amplitude_uv) <= _MAX_VOLTAGE_UV
 181    return 0 <= amplitude_uv and 2 * abs(mean_uv) + amplitude_uv <= 2 * _MAX_VOLTAGE_UV
 182
 183
 184def _microvolts(volts):
 185    return round(volts * 1e6)
 186
 187
 188@dataclass
 189class DeviceInfo:
 190    """Properties of the connected Synth Pal.
 191
 192    Populated when `SynthPalDevice` connects, and available as
 193    `SynthPalDevice.info`.
 194    """
 195
 196    firmware_version: int = None
 197    """Synth Pal firmware version running on the device."""
 198
 199    hardware_version: int = None
 200    """Pulse Pal hardware version, e.g. `3`."""
 201
 202    circuit_board_revision: int = None
 203    """Revision of the device's circuit board, 0-31.
 204
 205    The board encodes its revision on five pins, which the firmware reads
 206    at startup. A board that encodes none reports `0`. To record exactly
 207    which hardware ran an experiment, copy `hardware_version` and
 208    `circuit_board_revision` to your data.
 209    """
 210
 211    serial_number: str = None
 212    """USB serial number of the device, e.g. `"20345420"`: the Teensy's,
 213    unique to each Pulse Pal 3, and the same whichever firmware it runs.
 214
 215    Connect by it, wherever the device is plugged in, with
 216    `SynthPalDevice(serial_number="20345420")`. To record exactly which unit ran an
 217    experiment, copy it to your data.
 218    """
 219
 220    n_channels: int = None
 221    """Number of output channels."""
 222
 223    min_frequency: float = None
 224    """Lowest frequency, in Hz."""
 225
 226    max_frequency: float = None
 227    """Highest frequency, in Hz."""
 228
 229    max_sampling_rate: int = None
 230    """Highest sampling rate, in Hz. See `SynthPalDevice.sampling_rate`."""
 231
 232    timer_clock_hz: int = None
 233    """Clock that the sample clock counts, in Hz."""
 234
 235    max_play_duration: float = None
 236    """Longest play duration, in seconds. See
 237    `SynthPalDevice.play_duration`."""
 238
 239    waveforms: tuple = WAVEFORMS
 240    """Names of the waveforms, accepted by `SynthPalDevice.waveform`."""
 241
 242    trigger_modes: tuple = TRIGGER_MODES
 243    """Names of the trigger modes, accepted by
 244    `SynthPalDevice.trigger_mode`."""
 245
 246
 247@dataclass
 248class DeviceStatus:
 249    """A snapshot of the device's playback state, from
 250    `SynthPalDevice.status`."""
 251
 252    playing: list
 253    """Numbers of the output channels that are playing, e.g. `[1, 3]`.
 254
 255    A channel in its off ramp counts as playing until it reaches its
 256    resting voltage."""
 257
 258    samples_per_cycle: int
 259    """Samples in one cycle of the waveform. See
 260    `SynthPalDevice.samples_per_cycle`."""
 261
 262    output_ranges: list
 263    """The output range the device chose for each channel, indexed by
 264    channel number, with index 0 unused, e.g. `"-5V:5V"`.
 265
 266    Each channel uses the range with the finest voltage steps that holds
 267    its whole waveform and its resting voltage: `"0V:5V"` (76 uV steps),
 268    then `"0V:10V"` or `"-5V:5V"` (153 uV), then `"-10V:10V"` (305 uV).
 269    """
 270
 271    longest_interrupt_us: float
 272    """Longest run of the device's sample clock interrupt since the
 273    previous call to `SynthPalDevice.status`, in microseconds.
 274
 275    It must stay below the sample period, `1e6 / sampling_rate`.
 276    """
 277
 278    late_updates: int
 279    """Output updates since the previous call to `SynthPalDevice.status`
 280    that may have come later than their fixed time after a sample clock
 281    tick. It is normally 0; a change of frequency during playback can
 282    make one update late. See "Timing" in the
 283    [Synth Pal protocol](https://github.com/sanworks/PulsePal/blob/develop/Firmware/SynthPal/PROTOCOL.md#timing).
 284    """
 285
 286
 287class SynthPalDevice:
 288    """A class to control a Synth Pal on a USB serial port.
 289
 290    Creating an instance opens the serial port, checks that the device
 291    runs Synth Pal firmware, reads its properties into
 292    `SynthPalDevice.info`, shows "PYTHON Connected" on the device's
 293    screen, stops any playback and programs the default settings (see
 294    `SynthPalDevice.set_default_params`).
 295
 296    ```python
 297    from pulsepal import SynthPalDevice
 298
 299    S = SynthPalDevice("COM3")
 300    S.waveform[1] = "Triangle"
 301    S.trigger(1)
 302    S.close()
 303    ```
 304
 305    Replace "COM3" with the device's USB serial port name, which
 306    `SynthPalDevice.serialportlist` lists. `SynthPalDevice` is also a
 307    context manager, which closes the port on exit.
 308
 309    Closing the connection stops playback, as it does on Pulse Pal (each
 310    channel over its off ramp), and puts the device's own name back on its
 311    screen. The device keeps its settings, so TTL triggers still play the
 312    channels.
 313    """
 314
 315    port: "serial.Serial"
 316    """The open `serial.Serial` port connected to the device."""
 317
 318    info: DeviceInfo
 319    """Properties of the connected device. See `DeviceInfo`."""
 320
 321    _CURRENT_FIRMWARE_VERSION = 1
 322    _BAUD_RATE = 12000000  # USB serial ignores the baud rate
 323
 324    _OP_MENU_BYTE = _common.OP_MENU_BYTE
 325    _OP_HANDSHAKE = _common.OP_HANDSHAKE
 326    _OP_DISCONNECT = 81
 327    _OP_SET_CLIENT_NAME = 89
 328    _OP_SET_SCREEN_SAVER = 99
 329    _OP_HARDWARE_REVISION = 100
 330    _OP_HARDWARE_INFO = ord("N")
 331    _OP_SET_FREQUENCY = ord("F")
 332    _OP_SET_WAVEFORM = ord("W")
 333    _OP_SET_AMPLITUDE = ord("A")
 334    _OP_SET_RESTING_VOLTAGE = ord("V")
 335    _OP_SET_MEAN_VOLTAGE = ord("M")
 336    _OP_SET_PLAY_DURATION = ord("D")
 337    _OP_SET_ON_RAMP_DURATION = ord("B")
 338    _OP_SET_OFF_RAMP_DURATION = ord("E")
 339    _OP_SET_TRIGGER_LINKS = ord("I")
 340    _OP_SET_TRIGGER_MODE = ord("T")
 341    _OP_SET_ALL_SETTINGS = ord("U")
 342    _OP_GET_ALL_SETTINGS = ord("R")
 343    # Every setting, as ops 85 ('U') and 82 ('R') carry them: frequency (centiHz), waveform codes, amplitudes,
 344    # mean and resting voltages (uV), play, on ramp and off ramp durations (us), links, trigger modes
 345    _SETTINGS_FORMAT = "<I4B4i4i4i4I4I4I8B2B"
 346    _OP_TRIGGER = ord("P")
 347    _OP_STOP = ord("X")
 348    _OP_GET_STATUS = ord("G")
 349    _OP_GET_PLAYBACK_CHECKSUMS = ord("Z")
 350
 351    _HANDSHAKE_REPLY = 83  # 'S'
 352    _HARDWARE_INFO_FORMAT = "<BBIIIII"
 353    _STATUS_FORMAT = "<BI4BII"
 354    _ALL_CHANNELS = 0x0F
 355    # The ops that change settings: if the reply to one is lost, they are read back (_discard_lost_reply())
 356    _SETTING_OPS = frozenset(map(ord, "FWAVMDBEITU"))
 357
 358    _reply_pending = None  # The op code of a command whose reply has not been read in full yet (see _write_command())
 359    _unsent = frozenset()  # The settings assigned with auto_sync off since the settings were last sent or read
 360
 361    def __init__(self, port_name=None, *, serial_number=None, timeout=10):
 362        """Open a connection to a Synth Pal.
 363
 364        Args:
 365            port_name: USB serial port of the device, such as `COM3` on
 366                Windows or `/dev/ttyACM0` on Linux.
 367            serial_number: Instead of `port_name`, the device's USB serial
 368                number (`DeviceInfo.serial_number`), which finds its port
 369                wherever it is plugged in.
 370            timeout: Serial read timeout, in seconds.
 371
 372        Firmware newer than this module knows is used with a warning: new
 373        firmware only adds commands. Update the package to use what is new.
 374
 375        Raises:
 376            PulsePalError: If the device does not reply to the handshake, or
 377                runs other firmware.
 378            serial.SerialException: If the serial port cannot be opened,
 379                e.g. because another program has it open (on Linux and
 380                macOS, another session of these classes, which lock it).
 381        """
 382        self._closed = True
 383        self._auto_sync = True
 384        self.info = DeviceInfo()
 385        self._frequency = None
 386        self._samples_per_cycle = None
 387        # What the device holds for each output channel's waveform, amplitude (in microvolts: a periodic
 388        # waveform's peak to peak voltage, or a fixed voltage) and mean voltage (in microvolts), as far as this
 389        # object has programmed them. _send_levels() changes them in an order the device accepts.
 390        self._device_waveform = ["Sine"] * 4
 391        self._device_amplitude_uv = [5_000_000] * 4
 392        self._device_mean_uv = [0] * 4
 393        self._waveform = ChannelSettings(
 394            "waveform", ["Sine"] * 4, self, "_apply_waveform")
 395        self._peak_to_peak = ChannelSettings(
 396            "peak_to_peak", [5.0] * 4, self, "_apply_peak_to_peak")
 397        self._fixed_voltage = ChannelSettings(
 398            "fixed_voltage", [5.0] * 4, self, "_apply_fixed_voltage")
 399        self._mean_voltage = ChannelSettings(
 400            "mean_voltage", [0.0] * 4, self, "_apply_mean_voltage")
 401        self._resting_voltage = ChannelSettings(
 402            "resting_voltage", [0.0] * 4, self, "_apply_resting_voltage")
 403        self._play_duration = ChannelSettings(
 404            "play_duration", [1.0] * 4, self, "_apply_play_duration")
 405        self._on_ramp_duration = ChannelSettings(
 406            "on_ramp_duration", [0.0] * 4, self, "_apply_on_ramp_duration")
 407        self._off_ramp_duration = ChannelSettings(
 408            "off_ramp_duration", [0.0] * 4, self, "_apply_off_ramp_duration")
 409        self._trigger_mode = ChannelSettings(
 410            "trigger_mode", ["Normal"] * 2, self, "_apply_trigger_mode")
 411        self._link_trigger_channel1 = ChannelSettings(
 412            "link_trigger_channel1", [False] * 4, self,
 413            "_apply_trigger_channel1_links")
 414        self._link_trigger_channel2 = ChannelSettings(
 415            "link_trigger_channel2", [False] * 4, self,
 416            "_apply_trigger_channel2_links")
 417
 418        port_name = _common.port_name_from(port_name, serial_number, "SynthPalDevice")
 419        self.port = serial.Serial(
 420            port_name,
 421            self._BAUD_RATE,
 422            timeout=timeout,
 423            rtscts=True,
 424            # Windows opens a port for one program only. Linux and macOS let a second program open it too, and two
 425            # sessions' bytes would then interleave; exclusive locks it (flock), so a second session that also locks
 426            # it, such as another of these classes, gets an error instead
 427            exclusive=True,
 428        )
 429        self._closed = False
 430        try:
 431            # Discard anything left in the buffer by an earlier session
 432            self.port.reset_input_buffer()
 433            self._handshake()
 434            self._read_hardware_info()
 435            # Client name op + "PYTHON" in ASCII, shown as "PYTHON Connected"
 436            self._write_command(self._OP_SET_CLIENT_NAME, b"PYTHON")
 437            self.stop()
 438            self.set_default_params()
 439        except BaseException:
 440            # Op 81 means something else to other devices, so it is sent
 441            # only once the device has identified itself as a Synth Pal
 442            self._close(send_disconnect=self.info.firmware_version is not None)
 443            raise
 444
 445    @staticmethod
 446    def serialportlist(ports_to_list="available"):
 447        """Return the names of the USB serial ports on this computer.
 448
 449        Called on the class, without connecting to a device, to find the
 450        port name to pass to `SynthPalDevice`.
 451
 452        Args:
 453            ports_to_list: `available` to list only the ports that are
 454                not already in use, or `all` to list every USB serial
 455                port. Not case sensitive.
 456
 457        Returns:
 458            Sorted list of port names, such as `["COM3", "COM7"]`.
 459
 460        Raises:
 461            PulsePalError: If `ports_to_list` is not `available` or `all`.
 462        """
 463        return _common.serialportlist(ports_to_list)
 464
 465    # ------------------------------------------------------------------
 466    # Settings
 467    # ------------------------------------------------------------------
 468
 469    def set_default_params(self):
 470        """Program the default settings on the device.
 471
 472        The defaults are a frequency of 100 Hz, and on every output
 473        channel a sine wave of 5 V peak to peak around a mean voltage of
 474        0 V, resting at 0 V, played for 1 second with no ramps, and a
 475        fixed voltage of 5 V for when the waveform is "Fixed Voltage".
 476        Both trigger channels are in normal mode, and no output channel is
 477        linked to a trigger channel, so a TTL starts nothing until a script
 478        links it. They match the settings the device starts with. They are sent at once,
 479        also while `SynthPalDevice.auto_sync` is off.
 480        """
 481        auto_sync = self._auto_sync
 482        self._auto_sync = True
 483        try:
 484            self.frequency = 100
 485            # In this order, each is valid whatever the device holds: a mean of 0 V goes with any
 486            # amplitude, 5 V is then a valid amplitude for any waveform, and a sine wave is then valid
 487            self._send_levels_in_order((("M", [0] * 4), ("A", [5_000_000] * 4), ("W", ["Sine"] * 4)),
 488                                       force=True)
 489            for settings, value in ((self._waveform, "Sine"), (self._peak_to_peak, 5.0),
 490                                    (self._fixed_voltage, 5.0), (self._mean_voltage, 0.0)):
 491                settings._store([value] * 4)
 492            self.resting_voltage = [0] * 4
 493            self.play_duration = [1] * 4
 494            self.on_ramp_duration = [0] * 4
 495            self.off_ramp_duration = [0] * 4
 496            self.trigger_mode = ["Normal"] * 2
 497            self._set_trigger_links([False] * 4, [False] * 4)
 498            self._unsent = frozenset()  # Every setting has been sent
 499        finally:
 500            self._auto_sync = auto_sync
 501
 502    @property
 503    def frequency(self):
 504        """Frequency of all output channels, in Hz.
 505
 506        1 to 20000 Hz, rounded to 0.01 Hz. It can be changed during
 507        playback: playing channels carry on from the same point in their
 508        cycle, at the new frequency, and keep the time they have left to
 509        play. The frequency played is exact: the device's sample clock is a
 510        whole multiple of it (see `SynthPalDevice.sampling_rate`). For
 511        `"White Noise"` it sets only the sampling rate.
 512        """
 513        return self._frequency
 514
 515    @frequency.setter
 516    def frequency(self, value):
 517        if isinstance(value, (bool, np.bool_)) or not isinstance(value, numbers.Real) \
 518                or not math.isfinite(value):
 519            raise PulsePalError(
 520                f"frequency must be a number of Hz. Received {value!r}.")
 521        centihz = round(value * 100)
 522        low = round(self.info.min_frequency * 100)
 523        high = round(self.info.max_frequency * 100)
 524        if not low <= centihz <= high:
 525            raise PulsePalError(
 526                f"frequency must be {self.info.min_frequency:g} to "
 527                f"{self.info.max_frequency:g} Hz. Received {value!r}."
 528            )
 529        if self._auto_sync:
 530            self._write_command(self._OP_SET_FREQUENCY,
 531                                struct.pack("<I", centihz))
 532            confirmed, samples_per_cycle = struct.unpack(
 533                "<BI", self._read_raw(5))
 534            if confirmed != 1:
 535                raise PulsePalError(
 536                    f"Synth Pal rejected the frequency {value!r} Hz.")
 537        else:
 538            samples_per_cycle = _samples_per_cycle(centihz)
 539            self._unsent = self._unsent | {"frequency"}  # Until sync_to_device() sends it (see auto_sync)
 540        self._frequency = centihz / 100
 541        self._samples_per_cycle = samples_per_cycle
 542
 543    @property
 544    def auto_sync(self):
 545        """Whether assigning a setting programs the device at once.
 546
 547        `True` (the default): each assignment, such as
 548        `S.peak_to_peak[1] = 2`, programs the device at once, as the
 549        device's own op for that setting does, also while a trigger
 550        channel is in param sync mode.
 551
 552        `False`: assignments change only this object's copy of the settings,
 553        checking each value; `SynthPalDevice.sync_to_device` then sends all
 554        of them at once. Use it to store the next trial's settings for a
 555        param sync edge (see `SynthPalDevice.trigger_mode`), or to change
 556        several settings in one command. Turning it back on does not send
 557        changes made meanwhile, so it raises `pulsepal.PulsePalError` while
 558        there are any: call `SynthPalDevice.sync_to_device` first to send
 559        them, or `SynthPalDevice.sync_from_device` to discard them. A
 560        `SynthPalDevice.batch` block does it all for you. `close()` warns of
 561        changes never sent. `trigger`, `stop`, `status` and
 562        `set_default_params` act at once either way.
 563        """
 564        return self._auto_sync
 565
 566    @auto_sync.setter
 567    def auto_sync(self, value):
 568        value = to_bool(value, "auto_sync")
 569        if value and self._unsent:
 570            # Turned on, auto_sync would leave them unsent, and the device playing its old settings
 571            raise PulsePalError(
 572                f"Changes made with auto_sync off have not been sent to the device: {self._unsent_names()}. Call "
 573                "sync_to_device() to send them, or sync_from_device() to discard them, before turning auto_sync on."
 574            )
 575        self._auto_sync = value
 576
 577    def batch(self):
 578        """Change several settings, and send them in one command.
 579
 580        Returns a context manager. In its block, assignments change only
 581        this object's copy of the settings (as with
 582        `SynthPalDevice.auto_sync` off), and when the block ends,
 583        `SynthPalDevice.sync_to_device` sends all of them at once. If the
 584        block raises an error, nothing is sent, and the settings go back
 585        to what they were.
 586
 587        ```python
 588        with S.batch():
 589            S.frequency = 880
 590            S.waveform = ["Triangle"] * 4
 591            S.peak_to_peak = [2, 4, 6, 8]
 592        ```
 593
 594        In param sync mode, the device stores the settings for the next
 595        rising edge on the param sync channel (see
 596        `SynthPalDevice.trigger_mode`).
 597        """
 598        return _common.batch(self)
 599
 600    def sync_from_device(self):
 601        """Read every setting from the device into this object.
 602
 603        Use it after settings were changed with the device's joystick, for
 604        example. The device holds one amplitude per channel: a Fixed
 605        Voltage channel's goes to `SynthPalDevice.fixed_voltage`, and any
 606        other channel's to `SynthPalDevice.peak_to_peak`. This object keeps
 607        the other one, reduced if need be to suit the mean voltage read
 608        back. In param sync mode, it reads the settings the device plays
 609        now, not a set waiting for the next edge. Changes made with
 610        `SynthPalDevice.auto_sync` off and not yet sent are discarded.
 611
 612        Raises:
 613            PulsePalError: If the device does not reply.
 614        """
 615        self._write_command(self._OP_GET_ALL_SETTINGS)
 616        values = struct.unpack(self._SETTINGS_FORMAT, self._read_raw(struct.calcsize(self._SETTINGS_FORMAT)))
 617        centihz = values[0]
 618        waveforms = [WAVEFORMS[code] for code in values[1:5]]
 619        amplitudes, means = list(values[5:9]), list(values[9:13])
 620        peak_to_peak, fixed_voltage = list(self._peak_to_peak)[1:], list(self._fixed_voltage)[1:]
 621        for i, (name, amplitude, mean) in enumerate(zip(waveforms, amplitudes, means)):
 622            if name == FIXED_VOLTAGE:
 623                fixed_voltage[i] = amplitude / 1e6
 624                # This object's own peak to peak voltage must still suit the mean voltage (see _check_levels())
 625                peak_to_peak[i] = min(peak_to_peak[i], (2 * _MAX_VOLTAGE_UV - 2 * abs(mean)) / 1e6)
 626            else:
 627                peak_to_peak[i] = amplitude / 1e6
 628        self._frequency = centihz / 100
 629        self._samples_per_cycle = _samples_per_cycle(centihz)
 630        self._waveform._store(waveforms)
 631        self._peak_to_peak._store(peak_to_peak)
 632        self._fixed_voltage._store(fixed_voltage)
 633        self._mean_voltage._store([mean / 1e6 for mean in means])
 634        self._resting_voltage._store([rest / 1e6 for rest in values[13:17]])
 635        self._play_duration._store([d / 1e6 for d in values[17:21]])
 636        self._on_ramp_duration._store([d / 1e6 for d in values[21:25]])
 637        self._off_ramp_duration._store([d / 1e6 for d in values[25:29]])
 638        self._link_trigger_channel1._store([bool(link) for link in values[29:33]])
 639        self._link_trigger_channel2._store([bool(link) for link in values[33:37]])
 640        self._trigger_mode._store([TRIGGER_MODES[code] for code in values[37:39]])
 641        self._device_waveform, self._device_amplitude_uv, self._device_mean_uv = waveforms, amplitudes, means
 642        self._unsent = frozenset()  # Every setting is read
 643
 644    def export_params(self):
 645        """Return every setting, as a dict of plain values and lists.
 646
 647        Keyed by setting name: `"frequency"`, then the channel settings,
 648        each with one value per channel and no unused index 0. It holds
 649        only numbers, booleans and names, so it can be saved with `json`
 650        and logged with your data, to record exactly what the device
 651        played.
 652
 653        ```python
 654        import json
 655        with open("trial_settings.json", "w") as f:
 656            json.dump(S.export_params(), f)
 657        ```
 658        """
 659        params = {"frequency": self._frequency}
 660        params.update({name: list(getattr(self, name))[1:] for name in _CHANNEL_SETTINGS})
 661        return params
 662
 663    def import_params(self, params):
 664        """Program the device with settings exported by `SynthPalDevice.export_params`.
 665
 666        All of them are checked first, and then sent in one command, as
 667        at the end of a `SynthPalDevice.batch` block: in param sync mode,
 668        the device stores them for the next sync edge. The levels
 669        (`waveform`, `peak_to_peak`, `fixed_voltage`, `mean_voltage`) are
 670        checked together, so their order in `params` does not matter.
 671        Settings missing from `params` keep their values. A name that is
 672        not a setting is skipped with a warning, so that settings exported
 673        by a newer version of this package, which may have more, can still
 674        be imported.
 675
 676        ```python
 677        import json
 678        with open("trial_settings.json") as f:
 679            S.import_params(json.load(f))
 680        ```
 681
 682        Args:
 683            params: A dict of setting name to its value: a number for
 684                `"frequency"`, and one value per channel (a list, tuple or
 685                NumPy array) for the others, as `export_params` returns.
 686
 687        Raises:
 688            PulsePalError: If a value is invalid. Nothing is sent, and the
 689                settings keep the values they had.
 690        """
 691        names = {"frequency", *_CHANNEL_SETTINGS}
 692        unknown = [name for name in params if name not in names]
 693        if unknown:
 694            warnings.warn(f"import_params(): skipped {', '.join(map(repr, unknown))}, which this version of "
 695                          "SynthPalDevice does not have.", stacklevel=2)
 696        levels = ("waveform", "peak_to_peak", "fixed_voltage", "mean_voltage")
 697        with self.batch():
 698            for name, values in params.items():
 699                if name in levels:
 700                    # Each is checked alone here, and the levels together when the block ends (_check_sync()):
 701                    # an assignment would check each against the others' old values
 702                    getattr(self, name)._store(
 703                        self._normalize(name, _common.one_value_per_channel(name, values, 4)))
 704                elif name in names:
 705                    setattr(self, name, values)
 706
 707    def sync_to_device(self):
 708        """Send every setting to the device in one command.
 709
 710        While a trigger channel is in param sync mode, the device stores
 711        the set, replacing any set stored before, and that channel's next
 712        rising edge loads it (see `SynthPalDevice.trigger_mode`). Otherwise
 713        the device applies it at once. The settings sent are this object's:
 714        `frequency`, and for each channel `waveform`, `peak_to_peak` or
 715        `fixed_voltage`, `mean_voltage`, `resting_voltage`,
 716        `play_duration`, `on_ramp_duration`, `off_ramp_duration`,
 717        `link_trigger_channel1` and `link_trigger_channel2`, and
 718        `trigger_mode`. They read as sent, including while a set waits for
 719        its edge.
 720
 721        Raises:
 722            PulsePalError: If the device rejects the set.
 723        """
 724        self._check_sync()
 725        self._send_sync()
 726
 727    def configure(self, channels, *, waveform=None, peak_to_peak=None, fixed_voltage=None,
 728                  mean_voltage=None, resting_voltage=None, play_duration=None,
 729                  on_ramp_duration=None, off_ramp_duration=None):
 730        """Set several of the output channels' settings at once.
 731
 732        Settings left out keep their values. The new settings are checked
 733        together, so their order does not matter: for example, a channel
 734        whose sine wave swings 2 V around a mean voltage of 9 V can go
 735        straight to 20 V peak to peak around 0 V. With
 736        `SynthPalDevice.auto_sync` on, the class programs the device in an
 737        order it accepts at every step.
 738
 739        ```python
 740        S.configure(1, waveform="Sine", peak_to_peak=20, mean_voltage=0)
 741        S.configure([2, 3], waveform="Fixed Voltage", fixed_voltage=-2.5,
 742                    play_duration=0.1)
 743        ```
 744
 745        Args:
 746            channels: Output channel number 1-4, or several as a list,
 747                tuple or NumPy array.
 748            waveform, peak_to_peak, fixed_voltage, mean_voltage,
 749                resting_voltage, play_duration, on_ramp_duration,
 750                off_ramp_duration: New values, as for the settings of the
 751                same names: one value for every channel given, or a list
 752                with one value per channel given, in the same order.
 753
 754        Raises:
 755            PulsePalError: If a value is out of range, or the settings do
 756                not go together (nothing is sent), or the device rejects
 757                them.
 758        """
 759        channels = _common.channel_numbers(channels)
 760        if len(set(channels)) != len(channels):
 761            raise PulsePalError(f"configure(): channels must be distinct. Received {channels!r}.")
 762        requested = {"waveform": waveform, "peak_to_peak": peak_to_peak, "fixed_voltage": fixed_voltage,
 763                     "mean_voltage": mean_voltage, "resting_voltage": resting_voltage,
 764                     "play_duration": play_duration, "on_ramp_duration": on_ramp_duration,
 765                     "off_ramp_duration": off_ramp_duration}
 766        new_values = {}
 767        for name, value in requested.items():
 768            if value is None:
 769                continue
 770            values = list(value) if isinstance(value, (list, tuple, np.ndarray)) else [value]
 771            if len(values) == 1:
 772                values = values * len(channels)
 773            if len(values) != len(channels):
 774                raise PulsePalError(
 775                    f"configure(): {name} has {len(values)} values for {len(channels)} channels. Give one "
 776                    "value, or one value per channel."
 777                )
 778            settings = list(getattr(self, name))[1:]
 779            for channel, item in zip(channels, values):
 780                settings[channel - 1] = item
 781            new_values[name] = self._normalize(name, settings)
 782        levels = {name: new_values.get(name, list(getattr(self, name))[1:])
 783                  for name in ("waveform", "peak_to_peak", "fixed_voltage", "mean_voltage")}
 784        self._check_levels(levels["peak_to_peak"], levels["mean_voltage"], "configure")
 785        if self._auto_sync:
 786            self._send_levels(*self._device_levels(**levels))
 787        else:
 788            self._unsent = self._unsent | set(new_values)  # Until sync_to_device() sends them (see auto_sync)
 789        for name in levels:
 790            if name in new_values:
 791                getattr(self, name)._store(new_values[name])
 792        ops = {"resting_voltage": self._OP_SET_RESTING_VOLTAGE, "play_duration": self._OP_SET_PLAY_DURATION,
 793               "on_ramp_duration": self._OP_SET_ON_RAMP_DURATION,
 794               "off_ramp_duration": self._OP_SET_OFF_RAMP_DURATION}
 795        for name, op in ops.items():
 796            if name in new_values:
 797                if self._auto_sync:
 798                    self._send_setting(name, op, new_values[name])
 799                getattr(self, name)._store(new_values[name])
 800
 801    @property
 802    def samples_per_cycle(self):
 803        """Samples in one cycle of the waveform, at `frequency`.
 804
 805        The largest multiple of 4 whose sampling rate is at most
 806        `DeviceInfo.max_sampling_rate` (100 kHz), so that a sample falls
 807        on every edge, peak and trough of every waveform. For example,
 808        332 at 300 Hz and 4 at 20 kHz.
 809        """
 810        return self._samples_per_cycle
 811
 812    @property
 813    def sampling_rate(self):
 814        """The rate at which the device plays samples, in Hz.
 815
 816        `samples_per_cycle` times `frequency`: 100 kHz or just below it,
 817        and at least 50 kHz. For example, 100 kHz at 100 Hz, 99.6 kHz at
 818        300 Hz, and 80 kHz at 20 kHz. The device's timer cannot divide
 819        every rate exactly, so sample periods differ by up to one tick of
 820        its 24 MHz clock (42 ns), arranged so that the frequency is exact.
 821        """
 822        return self._samples_per_cycle * self._frequency
 823
 824    @property
 825    def waveform(self):
 826        """The waveform of each output channel.
 827
 828        Indexed by channel number (see "Channel settings" above). Each
 829        cycle starts at the trigger:
 830
 831        - `"Sine"` and `"Triangle"`: start at the mean voltage, rising.
 832        - `"Square"`: high for the first half of each cycle, then low.
 833        - `"Sawtooth"`: rises from its lowest voltage to its highest, then
 834          falls back at the end of the cycle.
 835        - `"Fixed Voltage"`: steps to the channel's
 836          `SynthPalDevice.fixed_voltage` for the play duration, and
 837          returns to the resting voltage. It is not periodic, so the
 838          frequency does not change it.
 839        - `"White Noise"`: a new random voltage on every sample, uniform
 840          over the peak to peak voltage around the mean voltage. It is
 841          rendered at the sampling rate the frequency sets
 842          (`SynthPalDevice.sampling_rate`), so no claim is made about its
 843          spectrum. Each channel has its own random sequence, which carries
 844          on from one playback to the next: every playback is new noise.
 845          The sequences start from the same point when the device powers
 846          up.
 847
 848        The periodic waveforms and white noise swing
 849        `SynthPalDevice.peak_to_peak` around `SynthPalDevice.mean_voltage`.
 850        Names are not case sensitive. A change applies to playback in
 851        progress.
 852        """
 853        return self._waveform
 854
 855    @waveform.setter
 856    def waveform(self, values):
 857        self._waveform._assign(values)
 858
 859    @property
 860    def peak_to_peak(self):
 861        """The peak to peak voltage of each output channel's waveform, in volts.
 862
 863        Indexed by channel number (see "Channel settings" above). 0 to
 864        20 V: the waveform swings `peak_to_peak / 2` above and below the
 865        channel's `SynthPalDevice.mean_voltage`, so it must stay within
 866        -10 V to 10 V: `abs(mean_voltage) + peak_to_peak / 2 <= 10`. To
 867        raise it beyond what the mean voltage allows, change the mean
 868        voltage first, or set both with `SynthPalDevice.configure`.
 869
 870        A sine wave of 4 V peak to peak swings from -2 V to 2 V around a
 871        mean voltage of 0 V: it is 2 sin(2 pi f t). White noise of 4 V peak
 872        to peak is uniform from -2 V to 2 V. A `"Fixed Voltage"` channel
 873        keeps its peak to peak voltage for when it plays a periodic waveform
 874        again.
 875
 876        Set to the nearest microvolt. A change applies to playback in
 877        progress.
 878        """
 879        return self._peak_to_peak
 880
 881    @peak_to_peak.setter
 882    def peak_to_peak(self, values):
 883        self._peak_to_peak._assign(values)
 884
 885    @property
 886    def fixed_voltage(self):
 887        """The voltage each output channel steps to when its waveform is
 888        `"Fixed Voltage"`, in volts.
 889
 890        Indexed by channel number (see "Channel settings" above). -10 to
 891        10 V, with any resting voltage and mean voltage. A channel playing
 892        another waveform keeps its fixed voltage for when its waveform is
 893        `"Fixed Voltage"` again.
 894
 895        Set to the nearest microvolt. A change applies to playback in
 896        progress.
 897        """
 898        return self._fixed_voltage
 899
 900    @fixed_voltage.setter
 901    def fixed_voltage(self, values):
 902        self._fixed_voltage._assign(values)
 903
 904    @property
 905    def mean_voltage(self):
 906        """The mean voltage of each output channel's waveform, in volts.
 907
 908        Indexed by channel number (see "Channel settings" above). -10 to
 909        10 V. A periodic waveform, or white noise, swings around it at full
 910        amplitude, and must stay within -10 V to 10 V with the
 911        `peak_to_peak` voltage: `abs(mean_voltage) + peak_to_peak / 2 <= 10`.
 912        It may differ from the `resting_voltage`, which the channel
 913        outputs between playbacks: the ramps move the mean between the two
 914        (see "Ramps" above). A `"Fixed Voltage"` ignores it. Set to the
 915        nearest microvolt. A change applies to playback in progress.
 916        """
 917        return self._mean_voltage
 918
 919    @mean_voltage.setter
 920    def mean_voltage(self, values):
 921        self._mean_voltage._assign(values)
 922
 923    @property
 924    def resting_voltage(self):
 925        """The resting voltage of each output channel, in volts.
 926
 927        Indexed by channel number (see "Channel settings" above). -10 to
 928        10 V, with any waveform. The channel outputs it while idle, and
 929        its ramps start and end there (see "Ramps" above). Set to the
 930        nearest microvolt. A change applies to playback in progress.
 931        """
 932        return self._resting_voltage
 933
 934    @resting_voltage.setter
 935    def resting_voltage(self, values):
 936        self._resting_voltage._assign(values)
 937
 938    @property
 939    def play_duration(self):
 940        """How long each output channel plays after a trigger, in seconds.
 941
 942        Indexed by channel number (see "Channel settings" above). Up to
 943        `DeviceInfo.max_play_duration` (3600 s). `0` plays until the
 944        channel is stopped. It counts at full amplitude, after the on
 945        ramp. The channel stops when the duration has elapsed, part way
 946        through a cycle if need be, and returns to its resting voltage,
 947        over its off ramp. Durations are counted in samples, rounded to
 948        the nearest one, and a nonzero duration lasts at least one sample.
 949        A change applies to playback in progress.
 950        """
 951        return self._play_duration
 952
 953    @play_duration.setter
 954    def play_duration(self, values):
 955        self._play_duration._assign(values)
 956
 957    @property
 958    def on_ramp_duration(self):
 959        """How long each output channel fades in after a trigger, in seconds.
 960
 961        Indexed by channel number (see "Channel settings" above). Up to
 962        `DeviceInfo.max_play_duration` (3600 s); `0` (the default) for no
 963        ramp. Over it, the peak to peak voltage rises linearly from 0 V to
 964        `peak_to_peak`, and the mean from the `resting_voltage` to the
 965        `mean_voltage`, before the play duration (see "Ramps" above).
 966        Counted in samples, as `play_duration` is. A change applies to
 967        playback in progress: a ramp under way keeps the level it has
 968        reached, and goes on at the new rate.
 969        """
 970        return self._on_ramp_duration
 971
 972    @on_ramp_duration.setter
 973    def on_ramp_duration(self, values):
 974        self._on_ramp_duration._assign(values)
 975
 976    @property
 977    def off_ramp_duration(self):
 978        """How long each output channel fades out when it stops, in seconds.
 979
 980        Indexed by channel number (see "Channel settings" above). Up to
 981        `DeviceInfo.max_play_duration` (3600 s); `0` (the default) for no
 982        ramp. Over it, the peak to peak voltage falls linearly to 0 V, and
 983        the mean to the `resting_voltage`, after the play duration or a
 984        stop (see "Ramps" above). Counted in samples, as `play_duration`
 985        is. A change applies to playback in progress.
 986        """
 987        return self._off_ramp_duration
 988
 989    @off_ramp_duration.setter
 990    def off_ramp_duration(self, values):
 991        self._off_ramp_duration._assign(values)
 992
 993    @property
 994    def trigger_mode(self):
 995        """How each trigger channel acts on the output channels linked to it.
 996
 997        Indexed by trigger channel number, 1 or 2 (index 0 is unused).
 998        These are Pulse Pal's trigger modes:
 999
1000        - `"Normal"`: a rising edge starts the linked channels. Channels
1001          that are playing ignore it.
1002        - `"Toggle"`: a rising edge starts the linked channels, or stops
1003          those that are playing.
1004        - `"Gated"`: a rising edge starts the linked channels, and a
1005          falling edge stops them, unless the other trigger channel is
1006          also gated, linked to them, and still high. With a play
1007          duration of 0, a channel plays for exactly as long as the TTL is
1008          high.
1009        - `"Param Sync"`: a rising edge starts and stops nothing (the
1010          channel's links are ignored). It loads the settings most recently
1011          sent by `SynthPalDevice.sync_to_device` (or at the end of a
1012          `SynthPalDevice.batch` block), if any. This is how the next
1013          trial's settings are sent during the current trial and applied
1014          the instant it starts.
1015
1016        At a param sync edge, the frequency and both trigger modes change
1017        at once: they are shared by all channels. An output channel at its
1018        resting voltage takes its new settings at once. One that is playing
1019        (off ramp included) finishes on the settings it started with, at
1020        the new frequency, and takes the new ones the moment it reaches its
1021        resting voltage, so the next trigger plays them. A trigger mode
1022        sent by `SynthPalDevice.sync_to_device` applies from the next
1023        edge.
1024
1025        Only `SynthPalDevice.sync_to_device` is held back for the edge:
1026        with `SynthPalDevice.auto_sync` on, every assignment programs the
1027        device at once, also in param sync mode. So leaving param sync mode
1028        means assigning `trigger_mode` with `auto_sync` on. When no trigger
1029        channel is left in the mode, the device discards a stored set.
1030
1031        To start channels on the same edge, wire the TTL to the other
1032        trigger channel too: the settings load first, so the channels it
1033        starts play the new settings. Connecting, and `set_default_params`,
1034        take both trigger channels out of param sync mode.
1035
1036        Names are not case sensitive.
1037        """
1038        return self._trigger_mode
1039
1040    @trigger_mode.setter
1041    def trigger_mode(self, values):
1042        self._trigger_mode._assign(values)
1043
1044    @property
1045    def link_trigger_channel1(self):
1046        """Whether each output channel is triggered by trigger channel 1.
1047
1048        Indexed by channel number (see "Channel settings" above). By
1049        default no output channel is linked to either trigger channel, so
1050        a TTL starts nothing until a script links it.
1051        """
1052        return self._link_trigger_channel1
1053
1054    @link_trigger_channel1.setter
1055    def link_trigger_channel1(self, values):
1056        self._link_trigger_channel1._assign(values)
1057
1058    @property
1059    def link_trigger_channel2(self):
1060        """Whether each output channel is triggered by trigger channel 2.
1061
1062        Indexed by channel number (see "Channel settings" above).
1063        """
1064        return self._link_trigger_channel2
1065
1066    @link_trigger_channel2.setter
1067    def link_trigger_channel2(self, values):
1068        self._link_trigger_channel2._assign(values)
1069
1070    def set_screen_saver(self, enabled, timeout=1800):
1071        """Switch the device's screen saver on or off, and set its timeout.
1072
1073        With the screen saver on, the device dims its screen once it has
1074        been left alone for `timeout` seconds: no command from a computer,
1075        no rising edge on a trigger channel, and no joystick click or
1076        push. The next of these brings the screen back. The device keeps
1077        both settings in its EEPROM, shared with Pulse Pal firmware, and
1078        saves them once no channel is playing. A new device starts with
1079        the screen saver on and 1800 s.
1080
1081        Args:
1082            enabled: `True` to switch the screen saver on, `False` to
1083                switch it off.
1084            timeout: Seconds without activity before the screen dims, 1 to
1085                65535.
1086
1087        Raises:
1088            PulsePalError: If a value is out of range.
1089        """
1090        state = to_bool(enabled, "enabled")
1091        if isinstance(timeout, (bool, np.bool_)) \
1092                or not isinstance(timeout, numbers.Integral) \
1093                or not 1 <= timeout <= 65535:
1094            raise PulsePalError(
1095                "timeout must be a whole number of seconds from 1 to 65535. "
1096                f"Received {timeout!r}."
1097            )
1098        self._write_command(self._OP_SET_SCREEN_SAVER,
1099                            struct.pack("<BH", int(state), int(timeout)))
1100        self._read_ack("set_screen_saver()")
1101
1102    # ------------------------------------------------------------------
1103    # Playback
1104    # ------------------------------------------------------------------
1105
1106    def trigger(self, channels):
1107        """Trigger output channels in software.
1108
1109        Channels that are idle start from the beginning of their waveform
1110        cycle, together. Channels that are playing ignore it, as they
1111        ignore a trigger channel in normal mode.
1112
1113        ```python
1114        S.trigger(1)
1115        S.trigger([2, 4])     # a list, tuple or NumPy array
1116        ```
1117
1118        Args:
1119            channels: Output channel number 1-4, or several as a list,
1120                tuple or NumPy array.
1121        """
1122        self._write_command(self._OP_TRIGGER, bytes([_common.channel_bits(channels)]))
1123
1124    def stop(self, channels=None):
1125        """Stop playback. The stopped channels return to their resting
1126        voltage, over their off ramps.
1127
1128        Args:
1129            channels: Output channel number 1-4, or several as a list,
1130                tuple or NumPy array. `None` stops all channels.
1131        """
1132        bits = self._ALL_CHANNELS if channels is None else _common.channel_bits(channels)
1133        self._write_command(self._OP_STOP, bytes([bits]))
1134
1135    def status(self):
1136        """Read the device's playback state.
1137
1138        Returns:
1139            A `DeviceStatus`, with the channels that are playing, the
1140            samples per cycle, each channel's output range, and timing
1141            figures.
1142        """
1143        self._write_command(self._OP_GET_STATUS)
1144        values = struct.unpack(
1145            self._STATUS_FORMAT,
1146            self._read_raw(struct.calcsize(self._STATUS_FORMAT)),
1147        )
1148        playing_bits = values[0]
1149        range_names = list(OUTPUT_RANGES)
1150        return DeviceStatus(
1151            playing=[ch for ch in range(1, 5)
1152                     if playing_bits & (1 << (ch - 1))],
1153            samples_per_cycle=values[1],
1154            output_ranges=[None, *(range_names[i] if i < len(range_names)
1155                                   else None for i in values[2:6])],
1156            longest_interrupt_us=values[6] / 1000,
1157            late_updates=values[7],
1158        )
1159
1160    def _playback_checksums(self):
1161        """For testing: what each channel played since it last started.
1162
1163        Returns two lists indexed by channel number, with index 0 unused:
1164        the number of samples played, and the sum of their DAC codes
1165        modulo 2**32. `tests/synthpal_hardware_test.py` compares them with
1166        the samples it expects, to check what the device played.
1167        """
1168        self._write_command(self._OP_GET_PLAYBACK_CHECKSUMS)
1169        values = struct.unpack("<8I", self._read_raw(32))
1170        return [None, *values[:4]], [None, *values[4:]]
1171
1172    # ------------------------------------------------------------------
1173    # Connection
1174    # ------------------------------------------------------------------
1175
1176    def close(self):
1177        """Close the connection to the device.
1178
1179        The device stops playback on all channels, each over its off ramp,
1180        and shows its own name on its screen again, in place of "PYTHON
1181        Connected". It keeps its settings, so TTL triggers still play the
1182        channels. Safe to call more than once. Called automatically when
1183        leaving a `with` block and when the object is garbage collected,
1184        so playback also stops when the last reference to the object
1185        goes.
1186
1187        """
1188        self._close(send_disconnect=True)
1189
1190    def _close(self, send_disconnect):
1191        """Close the connection. send_disconnect: tell the device first (op 81). False when the device may not
1192        run this firmware: op 81 means something else to other devices."""
1193        if getattr(self, "_closed", True):
1194            return
1195        self._closed = True
1196        if send_disconnect and self._unsent:
1197            _common.warn(f"SynthPalDevice closed with changes made with auto_sync off that were never sent to the "
1198                         f"device: {self._unsent_names()}.")
1199        self._reply_pending = None  # Nothing more is read, so a reply still to come needs no discarding
1200        try:
1201            if send_disconnect and self.port and self.port.is_open:
1202                self._write_command(self._OP_DISCONNECT)
1203        except Exception:
1204            pass  # The port may already be gone, e.g. the cable was unplugged
1205        finally:
1206            if self.port and self.port.is_open:
1207                self.port.close()
1208
1209    def __enter__(self):
1210        """Enter a `with` block, returning the connected device."""
1211        return self
1212
1213    def __exit__(self, exc_type, exc_value, traceback):
1214        """Close the port when leaving a `with` block.
1215
1216        Returns:
1217            `False`, so any exception raised in the block propagates.
1218        """
1219        self.close()
1220        return False
1221
1222    def __del__(self):
1223        """Close the port when the object is collected."""
1224        try:
1225            self.close()
1226        except Exception:
1227            # Destructors should not raise; the serial object may already be
1228            # gone during interpreter shutdown.
1229            pass
1230
1231    def __setattr__(self, name, value):
1232        """Refuse a public attribute that is not a setting, such as a misspelled one: it would program nothing (see
1233        _common.refuse_unknown_attribute())."""
1234        if name[0] != "_":
1235            _common.refuse_unknown_attribute(self, name, _SETTING_NAMES)
1236        super().__setattr__(name, value)
1237
1238    def __repr__(self):
1239        """Describe the device and its settings, e.g. with `print(S)`."""
1240        port = getattr(getattr(self, "port", None), "port", None)
1241        lines = [
1242            f"SynthPalDevice on {port} (Synth Pal firmware v{self.info.firmware_version})",
1243            f"frequency: {self._frequency} Hz ({self._samples_per_cycle} samples per cycle)",
1244            f"auto_sync: {self._auto_sync}",
1245        ]
1246        lines += [f"{name}: {list(getattr(self, name))}" for name in _CHANNEL_SETTINGS]
1247        return "\n".join(lines)
1248
1249    # ------------------------------------------------------------------
1250    # Internals: settings
1251    # ------------------------------------------------------------------
1252
1253    def _handshake(self):
1254        """Check that the device runs a supported Synth Pal firmware."""
1255        self._write_command(self._OP_HANDSHAKE)
1256        handshake = _common.read_handshake_reply(self.port)  # Skips a reply to an earlier session's command
1257        if handshake is None:
1258            raise PulsePalError(
1259                f"No reply from the device on {self.port.port}. Is it a "
1260                "Pulse Pal 3 running Synth Pal firmware?"
1261                f" {_common.NO_REPLY_HINT}"
1262            )
1263        reply, version = handshake
1264        if reply != self._HANDSHAKE_REPLY:
1265            if reply in _common.FIRMWARE_BY_HANDSHAKE_REPLY:
1266                raise _common.other_firmware_error(reply, version, self.port.port, "Synth Pal")
1267            raise PulsePalError(
1268                "Incorrect handshake returned. Expected "
1269                f"{self._HANDSHAKE_REPLY}, received {reply}."
1270            )
1271        if version > self._CURRENT_FIRMWARE_VERSION:
1272            # New firmware only adds commands (see PROTOCOL.md), so this class still works with it
1273            warnings.warn(
1274                f"Synth Pal firmware v{version} is newer than this pulsepal package knows "
1275                f"(v{self._CURRENT_FIRMWARE_VERSION}). It works with it, but update the package to use what is "
1276                "new.", stacklevel=3)
1277        self.info.firmware_version = version
1278
1279    def _read_hardware_info(self):
1280        self._write_command(self._OP_HARDWARE_INFO)
1281        (
1282            self.info.hardware_version,
1283            self.info.n_channels,
1284            min_centihz,
1285            max_centihz,
1286            self.info.max_sampling_rate,
1287            self.info.timer_clock_hz,
1288            max_duration_us,
1289        ) = struct.unpack(
1290            self._HARDWARE_INFO_FORMAT,
1291            self._read_raw(struct.calcsize(self._HARDWARE_INFO_FORMAT)),
1292        )
1293        self.info.min_frequency = min_centihz / 100
1294        self.info.max_frequency = max_centihz / 100
1295        self.info.max_play_duration = max_duration_us / 1e6
1296        self._write_command(self._OP_HARDWARE_REVISION)
1297        self.info.circuit_board_revision = self._read_raw(1)[0]
1298        self._write_command(_common.OP_SERIAL_NUMBER)
1299        self.info.serial_number = _common.read_serial_number(self._read_raw)
1300
1301    def _normalize(self, name, values):
1302        """Check new values for all four channels of a setting, and return them as its list holds them."""
1303        if name == "waveform":
1304            return [to_name(value, WAVEFORMS, "waveform") for value in values]
1305        if name == "peak_to_peak":
1306            return [self._to_volts(value, name, 0, 20, " peak to peak") for value in values]
1307        if name in ("fixed_voltage", "mean_voltage", "resting_voltage"):
1308            return [self._to_volts(value, name, -10, 10) for value in values]
1309        zero_meaning = "0 (play until stopped)" if name == "play_duration" else "0 (no ramp)"
1310        return [self._to_seconds(value, name, zero_meaning) for value in values]
1311
1312    def _check_levels(self, peak_to_peak, mean_voltage, setting):
1313        """Check that each channel's periodic waveform stays within -10 V to 10 V, as the device does.
1314
1315        Checked on every channel, also one playing a fixed voltage, so that a change of waveform always
1316        suits the levels it finds. `setting` is the one being changed, for the advice in the message.
1317        """
1318        for channel, (pp, mean) in enumerate(zip(peak_to_peak, mean_voltage), start=1):
1319            pp_uv, mean_uv = _microvolts(pp), _microvolts(mean)
1320            if 2 * abs(mean_uv) + pp_uv > 2 * _MAX_VOLTAGE_UV:
1321                advice = {
1322                    "peak_to_peak": "Change mean_voltage first, set both with configure(), or choose a "
1323                                    "smaller peak_to_peak.",
1324                    "mean_voltage": "Change peak_to_peak first, set both with configure(), or choose a "
1325                                    "smaller mean_voltage.",
1326                }.get(setting, "Change peak_to_peak or mean_voltage.")
1327                raise PulsePalError(
1328                    f"On channel {channel}, a mean voltage of {mean:g} V and a peak to peak voltage of "
1329                    f"{pp:g} V would reach {(abs(mean_uv) + pp_uv / 2) / 1e6:g} V. The waveform must "
1330                    f"stay within -10 V to 10 V. {advice}"
1331                )
1332
1333    def _device_levels(self, waveform, peak_to_peak, fixed_voltage, mean_voltage):
1334        """What the device holds for these settings: waveforms, amplitudes in microvolts (a fixed voltage, or a
1335        periodic waveform's peak to peak voltage) and mean voltages in microvolts."""
1336        amplitudes = [_microvolts(fixed if name == FIXED_VOLTAGE else pp)
1337                      for name, pp, fixed in zip(waveform, peak_to_peak, fixed_voltage)]
1338        return list(waveform), amplitudes, [_microvolts(mean) for mean in mean_voltage]
1339
1340    def _apply_levels(self, name, values):
1341        """Apply new values of waveform, peak_to_peak, fixed_voltage or mean_voltage, for all four channels."""
1342        values = self._normalize(name, values)
1343        levels = {level: list(getattr(self, level))[1:]
1344                  for level in ("waveform", "peak_to_peak", "fixed_voltage", "mean_voltage")}
1345        levels[name] = values
1346        self._check_levels(levels["peak_to_peak"], levels["mean_voltage"], name)
1347        if self._auto_sync:
1348            self._send_levels(*self._device_levels(**levels))
1349        else:
1350            self._unsent = self._unsent | {name}  # Until sync_to_device() sends it (see auto_sync)
1351        return values
1352
1353    def _apply_waveform(self, values):
1354        return self._apply_levels("waveform", values)
1355
1356    def _apply_peak_to_peak(self, values):
1357        return self._apply_levels("peak_to_peak", values)
1358
1359    def _apply_fixed_voltage(self, values):
1360        return self._apply_levels("fixed_voltage", values)
1361
1362    def _apply_mean_voltage(self, values):
1363        return self._apply_levels("mean_voltage", values)
1364
1365    def _send_levels(self, waveforms, amplitudes_uv, means_uv):
1366        """Program the device's waveforms, amplitudes and mean voltages, in an order it accepts at every step.
1367
1368        The device checks each op against what it holds for the other two (see _is_valid_level()), and one
1369        order does not suit every change: a sine wave of 20 V peak to peak cannot become a fixed voltage of
1370        -5 V by either op first. So each channel first takes an amplitude that suits both its current and
1371        its new waveform and mean voltage: its current amplitude if it can, else its new one, else 0 V, which
1372        suits any. Then the waveforms, the mean voltages and the new amplitudes follow. If the device
1373        refuses a step, which means this object's record of what it holds is out of date (e.g. a param sync
1374        edge loaded a stored set), the change is made from 0 V, which works from any state.
1375        """
1376        current = (self._device_waveform, self._device_amplitude_uv, self._device_mean_uv)
1377        if (waveforms, amplitudes_uv, means_uv) == tuple(map(list, current)):
1378            return
1379        first_amplitudes = []
1380        for w0, a0, m0, w1, a1, m1 in zip(*current, waveforms, amplitudes_uv, means_uv):
1381            for candidate in (a0, a1, 0):
1382                if all(_is_valid_level(w, candidate, m) for w, m in ((w0, m0), (w1, m0), (w1, m1))):
1383                    first_amplitudes.append(candidate)
1384                    break
1385        steps = (("A", first_amplitudes), ("W", waveforms), ("M", means_uv), ("A", amplitudes_uv))
1386        try:
1387            self._send_levels_in_order(steps)
1388        except _Rejected:
1389            self._send_levels_in_order((("A", [0] * 4), ("W", waveforms), ("M", means_uv),
1390                                        ("A", amplitudes_uv)), force=True)
1391
1392    def _send_levels_in_order(self, steps, force=False):
1393        """Send ops 'A' (amplitudes, uV), 'W' (waveform names) and 'M' (mean voltages, uV), in order, and keep
1394        the record of what the device holds. Unless `force`, an op that would not change what the record says
1395        the device holds is skipped."""
1396        for op, values in steps:
1397            if op == "W":
1398                if values == self._device_waveform and not force:
1399                    continue
1400                self._write_command(self._OP_SET_WAVEFORM, bytes(WAVEFORMS.index(name) for name in values))
1401                self._read_ack("setting waveform")
1402                self._device_waveform = list(values)
1403            elif op == "A":
1404                if values == self._device_amplitude_uv and not force:
1405                    continue
1406                self._write_command(self._OP_SET_AMPLITUDE, struct.pack("<4i", *values))
1407                self._read_ack("setting the amplitude")
1408                self._device_amplitude_uv = list(values)
1409            else:
1410                if values == self._device_mean_uv and not force:
1411                    continue
1412                self._write_command(self._OP_SET_MEAN_VOLTAGE, struct.pack("<4i", *values))
1413                self._read_ack("setting mean_voltage")
1414                self._device_mean_uv = list(values)
1415
1416    def _apply_resting_voltage(self, values):
1417        # Any resting voltage within -10 V to 10 V goes with any waveform
1418        values = self._normalize("resting_voltage", values)
1419        if self._auto_sync:
1420            self._send_setting("resting_voltage", self._OP_SET_RESTING_VOLTAGE, values)
1421        else:
1422            self._unsent = self._unsent | {"resting_voltage"}
1423        return values
1424
1425    def _apply_play_duration(self, values):
1426        return self._apply_duration("play_duration", self._OP_SET_PLAY_DURATION, values)
1427
1428    def _apply_on_ramp_duration(self, values):
1429        return self._apply_duration("on_ramp_duration", self._OP_SET_ON_RAMP_DURATION, values)
1430
1431    def _apply_off_ramp_duration(self, values):
1432        return self._apply_duration("off_ramp_duration", self._OP_SET_OFF_RAMP_DURATION, values)
1433
1434    def _apply_duration(self, name, op, values):
1435        values = self._normalize(name, values)
1436        if self._auto_sync:
1437            self._send_setting(name, op, values)
1438        else:
1439            self._unsent = self._unsent | {name}
1440        return values
1441
1442    def _send_setting(self, name, op, values):
1443        """Send the resting voltages (int32 microvolts) or a duration (uint32 microseconds), for all four
1444        channels."""
1445        if name == "resting_voltage":
1446            data = struct.pack("<4i", *(_microvolts(v) for v in values))
1447        else:
1448            data = struct.pack("<4I", *(round(d * 1e6) for d in values))
1449        self._write_command(op, data)
1450        self._read_ack(f"setting {name}")
1451
1452    def _apply_trigger_mode(self, values):
1453        names = [to_name(value, TRIGGER_MODES, "trigger mode") for value in values]
1454        if self._auto_sync:
1455            self._write_command(
1456                self._OP_SET_TRIGGER_MODE,
1457                bytes(TRIGGER_MODES.index(name) for name in names),
1458            )
1459            self._read_ack("setting trigger_mode")
1460        else:
1461            self._unsent = self._unsent | {"trigger_mode"}
1462        return names
1463
1464    # One op programs both trigger channels' links, so each list is sent
1465    # with the other's current values
1466    def _apply_trigger_channel1_links(self, values):
1467        links1 = [to_bool(v, "link_trigger_channel1") for v in values]
1468        self._send_trigger_links(links1, self._link_trigger_channel2[1:])
1469        if not self._auto_sync:
1470            self._unsent = self._unsent | {"link_trigger_channel1"}
1471        return links1
1472
1473    def _apply_trigger_channel2_links(self, values):
1474        links2 = [to_bool(v, "link_trigger_channel2") for v in values]
1475        self._send_trigger_links(self._link_trigger_channel1[1:], links2)
1476        if not self._auto_sync:
1477            self._unsent = self._unsent | {"link_trigger_channel2"}
1478        return links2
1479
1480    def _set_trigger_links(self, links1, links2):
1481        """Program both trigger channels' links with one command."""
1482        self._send_trigger_links(links1, links2)
1483        self._link_trigger_channel1._store(links1)
1484        self._link_trigger_channel2._store(links2)
1485
1486    def _send_trigger_links(self, links1, links2):
1487        if self._auto_sync:
1488            self._write_command(self._OP_SET_TRIGGER_LINKS,
1489                                bytes([*map(int, links1), *map(int, links2)]))
1490            self._read_ack("setting the trigger channel links")
1491
1492    def _snapshot(self):
1493        """All settings, and which are unsent, for batch() to restore if its block fails."""
1494        settings = {name: list(getattr(self, name))[1:] for name in _CHANNEL_SETTINGS}
1495        return settings, self._frequency, self._samples_per_cycle, self._unsent
1496
1497    def _restore(self, snapshot):
1498        settings, self._frequency, self._samples_per_cycle, self._unsent = snapshot
1499        for name, values in settings.items():
1500            getattr(self, name)._store(values)
1501
1502    def _unsent_names(self):
1503        """The settings assigned with auto_sync off and not yet sent, for messages, in the class's order."""
1504        return ", ".join(name for name in _SETTING_NAMES if name in self._unsent)
1505
1506    def _check_sync(self):
1507        """Check the whole set before sync_to_device() sends it."""
1508        self._check_levels(self._peak_to_peak[1:], self._mean_voltage[1:], "sync")
1509
1510    def _send_sync(self):
1511        """Send every setting with op 85 ('U'). The device checks the whole set, so no order matters."""
1512        self._unsent = frozenset()  # All are sent below
1513        waveforms, amplitudes, means = self._device_levels(
1514            self._waveform[1:], self._peak_to_peak[1:], self._fixed_voltage[1:], self._mean_voltage[1:])
1515        links = [int(link) for link in (*self._link_trigger_channel1[1:],
1516                                        *self._link_trigger_channel2[1:])]
1517        payload = struct.pack(
1518            self._SETTINGS_FORMAT,
1519            round(self._frequency * 100),
1520            *(WAVEFORMS.index(name) for name in waveforms),
1521            *amplitudes, *means, *(_microvolts(v) for v in self._resting_voltage[1:]),
1522            *(round(d * 1e6) for d in self._play_duration[1:]),
1523            *(round(d * 1e6) for d in self._on_ramp_duration[1:]),
1524            *(round(d * 1e6) for d in self._off_ramp_duration[1:]),
1525            *links,
1526            *(TRIGGER_MODES.index(name) for name in self._trigger_mode[1:]),
1527        )
1528        self._write_command(self._OP_SET_ALL_SETTINGS, payload)
1529        self._read_ack("sync_to_device()")
1530        # Applied now, or, in param sync mode, at the next edge. Either way these are the levels the next
1531        # assignments build on; if a stored set has not loaded yet, _send_levels() finds out and recovers.
1532        self._device_waveform, self._device_amplitude_uv, self._device_mean_uv = waveforms, amplitudes, means
1533
1534    @staticmethod
1535    def _to_volts(value, name, low, high, note=""):
1536        if isinstance(value, (bool, np.bool_)) or not isinstance(value, numbers.Real) \
1537                or not math.isfinite(value) or not low <= value <= high:
1538            raise PulsePalError(
1539                f"{name} values must be numbers of volts from {low} to "
1540                f"{high}{note}. Received {value!r}."
1541            )
1542        return float(value)
1543
1544    def _to_seconds(self, value, name, zero_meaning):
1545        if isinstance(value, (bool, np.bool_)) or not isinstance(value, numbers.Real):
1546            raise PulsePalError(
1547                f"{name} must be in seconds. Received {value!r}."
1548            )
1549        duration = float(value)
1550        if not math.isfinite(duration) or not \
1551                0 <= duration <= self.info.max_play_duration:
1552            raise PulsePalError(
1553                f"{name} must be {zero_meaning} or a positive number "
1554                f"of seconds up to {self.info.max_play_duration:g}. "
1555                f"Received {value!r}."
1556            )
1557        return duration
1558
1559    # ------------------------------------------------------------------
1560    # Internals: serial port
1561    # ------------------------------------------------------------------
1562
1563    def _write_command(self, op_code, data=b""):
1564        """Send one command, with its framing byte, in a single write.
1565
1566        A command whose reply was not read in full, because the read timed out or was interrupted (Ctrl-C), leaves
1567        that reply, or the rest of it, to arrive later. Read as the reply to the next command, it would put every
1568        reply after it out of step. So it is discarded first (_discard_lost_reply()), and this command's reply, if it
1569        has one, is pending until _read_raw() has read it, as in PulsePalDevice.
1570        """
1571        if self._reply_pending is not None:
1572            self._discard_lost_reply()
1573        if op_code not in _OPS_WITHOUT_TRACKED_REPLY:
1574            self._reply_pending = op_code  # Before the write: a Ctrl-C can come as soon as it returns
1575        message = bytes([self._OP_MENU_BYTE, op_code]) + data
1576        bytes_written = self.port.write(message)
1577        if bytes_written != len(message):
1578            raise PulsePalError(
1579                f"Wrote {bytes_written} byte(s), expected to write "
1580                f"{len(message)} byte(s)."
1581            )
1582
1583    def _discard_lost_reply(self):
1584        """Discard what arrives of a reply that was not read in full (see _write_command()), and bring this object
1585        back in step with the device.
1586
1587        The command may have changed settings, unknown to this object: an assignment interrupted after its write,
1588        for one, which the device took and this object did not. So after one of _SETTING_OPS, they are read back
1589        (op 'R'), outside param sync mode, where op 'R' returns the settings playing rather than a set stored for the
1590        next sync edge.
1591        """
1592        op = self._reply_pending
1593        self._reply_pending = None
1594        n_late = len(_common.read_until_quiet(self.port))
1595        read_back = op in self._SETTING_OPS and "Param Sync" not in list(self._trigger_mode)[1:]
1596        _common.warn_lost_reply(f"op {chr(op)!r}", n_late,
1597                                ", and the settings were read back from the device" if read_back else "")
1598        if read_back:
1599            try:
1600                self.sync_from_device()
1601            except PulsePalError as exc:
1602                raise PulsePalError(
1603                    f"Synth Pal did not send its settings, read back after the reply to an earlier command was lost. "
1604                    f"{_common.NO_REPLY_HINT}"
1605                ) from exc
1606
1607    def _read_raw(self, n_bytes):
1608        """Read exactly n_bytes from the serial port: the whole reply to the command last sent, which is then no
1609        longer pending (see _write_command()). Only connecting reads a reply in more than one call."""
1610        message = self.port.read(n_bytes)
1611        if len(message) < n_bytes:
1612            raise PulsePalError(
1613                f"Synth Pal sent {len(message)} of the {n_bytes} byte(s) of its reply within "
1614                f"{self.port.timeout} s. {_common.NO_REPLY_HINT}"
1615            )
1616        self._reply_pending = None
1617        return message
1618
1619    def _read_ack(self, context):
1620        """Read a one-byte confirmation: 1 if the device executed the
1621        command, 0 if it rejected it."""
1622        try:
1623            reply = self._read_raw(1)[0]
1624        except PulsePalError as exc:
1625            raise PulsePalError(
1626                f"Synth Pal did not confirm {context}: no reply arrived within {self.port.timeout} s. "
1627                f"{_common.NO_REPLY_HINT}"
1628            ) from exc
1629        if reply != 1:
1630            raise _Rejected(
1631                f"Synth Pal rejected {context}. A value was out of range."
1632            )