PulsePal

   1"""
   2Python interface for the [Pulse Pal](https://sites.google.com/site/pulsepalwiki/)
   3open source pulse train generator.
   4
   5Pulse Pal delivers precisely timed voltage pulse trains on four analog
   6output channels, and can be triggered by TTL logic on two trigger
   7channels or in software. This module configures and triggers the device
   8over its USB serial port.
   9
  10Everything is accessed through `PulsePalDevice`. Import it, connect to
  11the device's serial port, program parameters, and trigger, e.g.
  12
  13```python
  14from PulsePal import PulsePalDevice
  15
  16with PulsePalDevice("COM3") as P:
  17    P.set_output_param("phase1_voltage", 1, 5)
  18    P.set_output_param("phase1_duration", 1, 0.001)
  19    P.set_output_param("pulse_train_duration", 1, 2)
  20    P.trigger(1)
  21```
  22
  23## Parameter arrays
  24
  25Output parameters are exposed as plain Python lists on the device
  26object, one list per parameter. Each list has five elements so that the
  27list index matches the Pulse Pal channel number: index 0 is unused and
  28holds `nan`, and indices 1 to 4 hold the values for output channels
  291-4. `PulsePalDevice.trigger_mode` follows the same convention with
  30three elements, for trigger channels 1 and 2.
  31
  32```python
  33P.phase1_voltage[2] = 7                  # channel 2 only
  34P.inter_pulse_interval[1:5] = [0.2] * 4  # all four channels
  35P.sync_to_device()             # push the edits to the device
  36```
  37
  38Editing these lists changes only the local copy. Call
  39`PulsePalDevice.sync_to_device` to program the device, or use
  40`PulsePalDevice.set_output_param` and
  41`PulsePalDevice.set_trigger_param`, which program a single parameter
  42immediately and keep the local copy in step.
  43
  44## Units
  45
  46Voltages are in volts in the range [-10, 10]. Times are in seconds, and
  47are rounded to the nearest cycle of the device's hardware timer (see
  48`DeviceInfo.cycle_frequency`). Enumerated parameters are integers, and
  49their meanings are given with each attribute below.
  50
  51## Further reading
  52
  53- Parameter guide:
  54  https://sites.google.com/site/pulsepalwiki/parameter-guide
  55- Serial interface and general documentation:
  56  https://sites.google.com/site/pulsepalwiki/
  57
  58## License
  59
  60This file is part of the Sanworks PulsePal repository.
  61Copyright (C) Sanworks LLC, Rochester, New York, USA
  62
  63This program is free software: you can redistribute it and/or modify
  64it under the terms of the GNU General Public License as published by
  65the Free Software Foundation, version 3.
  66
  67This program is distributed WITHOUT ANY WARRANTY and without even the
  68implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  69See the GNU General Public License for more details.
  70
  71You should have received a copy of the GNU General Public License
  72along with this program. If not, see <http://www.gnu.org/licenses/>.
  73"""
  74
  75from decimal import Decimal
  76from dataclasses import dataclass
  77import numbers
  78import struct
  79import time
  80
  81import numpy as np
  82import serial
  83import serial.tools.list_ports
  84
  85__all__ = ["PulsePalDevice", "DeviceInfo", "PulsePalError"]
  86__docformat__ = "google"
  87
  88
  89class PulsePalError(Exception):
  90    """Raised when Pulse Pal communication or configuration fails.
  91
  92    This covers serial reads that time out, short serial writes, missing
  93    acknowledgement bytes, unknown parameter names, values that do not
  94    fit the datatype expected by the device, and operations that the
  95    connected firmware or hardware revision does not support.
  96    """
  97
  98
  99@dataclass
 100class DeviceInfo:
 101    """Properties of the connected Pulse Pal device.
 102
 103    An instance is created for each connection and populated during the
 104    handshake in `PulsePalDevice.__init__`. It is available as
 105    `PulsePalDevice.info`. Devices running firmware v21 report only a
 106    firmware version, so the remaining fields are filled in with the
 107    known values for Pulse Pal hardware v2.
 108
 109    ```python
 110    print(P.info.firmware_version)
 111    ```
 112    """
 113
 114    output_parameter_names: list = None
 115    """Output parameter names, ordered by parameter code.
 116
 117    The position of a name in this list, plus 1, is the parameter code
 118    the device expects. Any name here is valid as the `param_name`
 119    argument of `PulsePalDevice.set_output_param`, and is also the name
 120    of the matching parameter array attribute on `PulsePalDevice`.
 121    """
 122
 123    trigger_parameter_names: list = None
 124    """Trigger parameter names, accepted by
 125    `PulsePalDevice.set_trigger_param`."""
 126
 127    firmware_version: int = None
 128    """Firmware version running on the connected device."""
 129
 130    hardware_version: int = None
 131    """Hardware revision of the connected device, e.g. `2` or `3`.
 132
 133    Reported by the device on firmware v22 and newer; assumed to be `2`
 134    on older firmware.
 135    """
 136
 137    max_custom_pulses: int = None
 138    """Maximum number of pulses in a single custom pulse train."""
 139
 140    n_custom_pulse_trains: int = None
 141    """Number of custom pulse trains the device can store."""
 142
 143    cycle_frequency: float = None
 144    """Update frequency of the device's hardware timer, in Hz.
 145
 146    All time parameters are rounded to a whole number of these cycles,
 147    so this sets the timing resolution of the device.
 148    """
 149
 150    cycle_period_us: float = None
 151    """Update period of the device's hardware timer, in microseconds."""
 152
 153
 154class PulsePalDevice:
 155    """A class to control a Pulse Pal device on a USB serial port.
 156
 157    Creating an instance opens the serial port, exchanges a handshake
 158    with the device, verifies that its firmware is supported, reads the
 159    device properties into `PulsePalDevice.info`, and programs the
 160    device with the default parameters.
 161
 162    ```python
 163    from PulsePal import PulsePalDevice
 164
 165    P = PulsePalDevice("COM3")
 166    P.set_output_param("phase1_voltage", 1, 5)
 167    P.trigger(1)
 168    P.close()
 169    ```
 170
 171    Here, replace "COM3" with Pulse Pal's USB serial port name.
 172    To view a list of available ports, use
 173    PulsePalDevice.serialportlist()
 174    Pulse Pal's port may not be visible if it is connected to another
 175    instance of PulsePalDevice or an external application. Use
 176    PulsePalDevice.serialportlist('all') to view all ports.
 177    If you see multiple available ports, disconnect Pulse Pal's USB plug
 178    and re-run serialportlist(). Notice which port disappears from the list.
 179
 180    PulsePalDevice is also a context manager, which closes the connection on
 181    exit even if an error is raised:
 182
 183    ```python
 184    with PulsePalDevice("COM3") as P:
 185        P.trigger(1)
 186    ```
 187
 188    The attributes below named after Pulse Pal parameters are the local
 189    copy of the device's program. Each is a five element list indexed by
 190    channel number, with index 0 unused. This way channels are addressed
 191    by the index on the device, e.g. trigger channels 1-2 and output
 192    channels 1-4. Assigning parameters does not update the device until
 193    `PulsePalDevice.sync_to_device` is called;
 194    `PulsePalDevice.set_output_param` programs one parameter right away.
 195    """
 196
 197    port: "serial.Serial"
 198    """The open `serial.Serial` port connected to the device."""
 199
 200    info: DeviceInfo
 201    """Properties of the connected device. See `DeviceInfo`."""
 202
 203    is_biphasic: list
 204    """Pulse shape per channel: `0` for monophasic, `1` for biphasic.
 205
 206    Monophasic pulses use only the phase 1 parameters. Biphasic pulses
 207    follow phase 1 with `PulsePalDevice.inter_phase_interval` and then
 208    phase 2.
 209    """
 210
 211    phase1_voltage: list
 212    """Voltage of the first phase of each pulse, in volts [-10, 10]."""
 213
 214    phase2_voltage: list
 215    """Voltage of the second phase of each pulse, in volts [-10, 10].
 216
 217    Used only when `PulsePalDevice.is_biphasic` is `1` for the channel.
 218    """
 219
 220    resting_voltage: list
 221    """Voltage held between pulses, in volts [-10, 10]."""
 222
 223    phase1_duration: list
 224    """Duration of the first phase of each pulse, in seconds."""
 225
 226    inter_phase_interval: list
 227    """Interval between the two phases of a biphasic pulse, in seconds.
 228
 229    The channel rests at `PulsePalDevice.resting_voltage` during the
 230    interval. Used only when `PulsePalDevice.is_biphasic` is `1`.
 231    """
 232
 233    phase2_duration: list
 234    """Duration of the second phase of each pulse, in seconds.
 235
 236    Used only when `PulsePalDevice.is_biphasic` is `1` for the channel.
 237    """
 238
 239    inter_pulse_interval: list
 240    """Interval from the end of one pulse to the onset of the next, in
 241    seconds."""
 242
 243    burst_duration: list
 244    """Duration of each burst of pulses, in seconds.
 245
 246    Set to `0` to disable bursts, so that pulses continue for the whole
 247    pulse train.
 248    """
 249
 250    inter_burst_interval: list
 251    """Interval between bursts of pulses, in seconds.
 252
 253    The channel rests at `PulsePalDevice.resting_voltage` between
 254    bursts. Ignored when `PulsePalDevice.burst_duration` is `0`.
 255    """
 256
 257    pulse_train_duration: list
 258    """Total duration of the pulse train, in seconds."""
 259
 260    pulse_train_delay: list
 261    """Delay from the trigger to the onset of the pulse train, in
 262    seconds."""
 263
 264    link_trigger_channel1: list
 265    """Whether each output channel is linked to trigger channel 1.
 266
 267    `1` links the output channel to trigger channel 1, `0` unlinks it.
 268    """
 269
 270    link_trigger_channel2: list
 271    """Whether each output channel is linked to trigger channel 2.
 272
 273    `1` links the output channel to trigger channel 2, `0` unlinks it.
 274    """
 275
 276    custom_train_id: list
 277    """Custom pulse train played by each output channel.
 278
 279    `0` plays the parametrically defined train. `1` or higher plays the
 280    matching custom train, previously loaded with
 281    `PulsePalDevice.send_custom_pulse_train` or
 282    `PulsePalDevice.send_custom_waveform`.
 283    """
 284
 285    custom_train_target: list
 286    """What the timestamps of a custom train mark.
 287
 288    `0` if each timestamp is the onset of a pulse, `1` if each timestamp
 289    is the onset of a burst of pulses.
 290    """
 291
 292    custom_train_loop: list
 293    """Whether a custom train repeats.
 294
 295    `1` loops the custom train until
 296    `PulsePalDevice.pulse_train_duration` has elapsed, `0` plays it
 297    once.
 298    """
 299
 300    playback_mode: list
 301    """Continuous playback mode of parametric pulse trains after being triggered
 302
 303    - `0` plays the pulse train once until pulse_train_duration seconds
 304    - `1` plays the pulse train indefinitely, ignoring pulse_train_duration
 305    
 306    """
 307
 308    trigger_mode: list
 309    """Response of each trigger channel to an incoming TTL pulse.
 310
 311    Three element list indexed by trigger channel, with index 0 unused.
 312    Elements 1 and 2 control the respective channels on the device.
 313    Their values can be:
 314
 315    - `0` (normal): a TTL rising edge starts the pulse train, and edges
 316      during the train are ignored.
 317    - `1` (toggle): same as 0 but a TTL rising edge during the train stops it.
 318    - `2` (pulse gated): the train runs only while the trigger TTL is high.
 319    """
 320
 321    _CURRENT_FIRMWARE_VERSION = 22
 322
 323    _OP_MENU_BYTE = 213
 324    _HANDSHAKE_OPCODE = 72
 325    _HANDSHAKE_RESPONSE = 75
 326    _DAC_BITMAX = 65535
 327    _OLDEST_FIRMWARE_SUPPORTED = 21
 328
 329    _OUTPUT_PARAMETER_NAMES = (
 330        "is_biphasic",
 331        "phase1_voltage",
 332        "phase2_voltage",
 333        "phase1_duration",
 334        "inter_phase_interval",
 335        "phase2_duration",
 336        "inter_pulse_interval",
 337        "burst_duration",
 338        "inter_burst_interval",
 339        "pulse_train_duration",
 340        "pulse_train_delay",
 341        "link_trigger_channel1",
 342        "link_trigger_channel2",
 343        "custom_train_id",
 344        "custom_train_target",
 345        "custom_train_loop",
 346        "playback_mode",
 347        "resting_voltage",
 348    )
 349    _TRIGGER_PARAMETER_NAMES = ("trigger_mode",)
 350
 351    _OUTPUT_PARAMETER_ATTRS = {
 352        1: "is_biphasic",
 353        2: "phase1_voltage",
 354        3: "phase2_voltage",
 355        4: "phase1_duration",
 356        5: "inter_phase_interval",
 357        6: "phase2_duration",
 358        7: "inter_pulse_interval",
 359        8: "burst_duration",
 360        9: "inter_burst_interval",
 361        10: "pulse_train_duration",
 362        11: "pulse_train_delay",
 363        12: "link_trigger_channel1",
 364        13: "link_trigger_channel2",
 365        14: "custom_train_id",
 366        15: "custom_train_target",
 367        16: "custom_train_loop",
 368        17: "resting_voltage",
 369        18: "playback_mode",
 370    }
 371    _ENDIANNESS = "<"
 372    _STRUCT_FORMATS = {
 373        "uint8": "B",
 374        "int8": "b",
 375        "char": "c",
 376        "uint16": "H",
 377        "int16": "h",
 378        "uint32": "I",
 379        "int32": "i",
 380        "single": "f",
 381        "double": "d",
 382    }
 383    _TYPE_RANGES = {
 384        "uint8": (0, 2**8 - 1),
 385        "int8": (-(2**7), 2**7 - 1),
 386        "uint16": (0, 2**16 - 1),
 387        "int16": (-(2**15), 2**15 - 1),
 388        "uint32": (0, 2**32 - 1),
 389        "int32": (-(2**31), 2**31 - 1),
 390    }
 391
 392    def __init__(self, port_name, baud_rate=12000000, timeout=10):
 393        """Open a connection to a Pulse Pal device.
 394
 395        Opens the serial port, exchanges the handshake, verifies the
 396        firmware version, reads the device properties into
 397        `PulsePalDevice.info`, and programs the device with the default
 398        parameters.
 399
 400        Args:
 401            port_name: USB serial port for the Pulse Pal device, such as
 402                `COM3` on Windows or `/dev/ttyACM0` on Linux.
 403            baud_rate: Serial baud rate.
 404            timeout: Serial read timeout, in seconds.
 405
 406        Raises:
 407            PulsePalError: If the device does not return the expected
 408                handshake, or its firmware is older than v21, or its
 409                firmware is newer than this module supports.
 410            serial.SerialException: If the serial port cannot be opened.
 411        """
 412        self.info = DeviceInfo()
 413        self._gui = None
 414        self.port = serial.Serial(
 415            port_name,
 416            baud_rate,
 417            timeout=timeout,
 418            rtscts=True,
 419        )
 420        self._closed = False
 421        self._dac_bit_max = self._to_decimal(0)
 422        self.info.firmware_version = None
 423        self.info.hardware_version = None
 424        self.info.output_parameter_names = list(self._OUTPUT_PARAMETER_NAMES)
 425        self.info.trigger_parameter_names = list(self._TRIGGER_PARAMETER_NAMES)
 426
 427        self._write_serial(
 428            (self._OP_MENU_BYTE, self._HANDSHAKE_OPCODE),
 429            "uint8",
 430        )
 431        handshake = self._read_serial(1, "uint8")
 432        if handshake != self._HANDSHAKE_RESPONSE:
 433            self.close(send_disconnect=False)
 434            raise PulsePalError(
 435                "Error: incorrect handshake returned. Expected "
 436                f"{self._HANDSHAKE_RESPONSE}, received {handshake}."
 437            )
 438
 439        firmware_version = self._read_serial(1, "uint32")
 440        if firmware_version < self._OLDEST_FIRMWARE_SUPPORTED:
 441            raise PulsePalError(
 442                "Error: Old firmware detected, v"
 443                f"{firmware_version}. v{self._OLDEST_FIRMWARE_SUPPORTED} or "
 444                "newer is required."
 445            )
 446        if firmware_version > self._CURRENT_FIRMWARE_VERSION:
 447            raise PulsePalError(
 448                "Error: Future firmware detected, v"
 449                f"{firmware_version}. Please update PulsePal.py or downgrade "
 450                f"firmware to v{self._CURRENT_FIRMWARE_VERSION}."
 451            )
 452        if firmware_version < self._CURRENT_FIRMWARE_VERSION:
 453            print(
 454                "Old firmware detected, v"
 455                f"{firmware_version}. This firmware is supported. Update to v"
 456                f"{self._CURRENT_FIRMWARE_VERSION} is available."
 457            )
 458        self._dac_bit_max = self._to_decimal(self._DAC_BITMAX)
 459        self.info.firmware_version = firmware_version
 460
 461        if self.info.firmware_version > 21:
 462            self._write_serial((self._OP_MENU_BYTE, 94), "uint8")
 463            self.info.hardware_version = self._read_serial(1, "uint8")
 464            self.info.cycle_period_us = self._read_serial(1, "uint32")
 465            self.info.cycle_frequency = 1 / (
 466                self.info.cycle_period_us / 1000000
 467            )
 468            self.info.n_custom_pulse_trains = self._read_serial(1, "uint8")
 469            self.info.max_custom_pulses = self._read_serial(1, "uint32")
 470        else:
 471            self.info.hardware_version = 2
 472            self.info.cycle_period_us = 50
 473            self.info.cycle_frequency = 20000
 474            self.info.n_custom_pulse_trains = 2
 475            self.info.max_custom_pulses = 5000
 476
 477        # Client name op + "PYTHON" in ASCII.
 478        self._write_serial(
 479            (self._OP_MENU_BYTE, 89, 80, 89, 84, 72, 79, 78),
 480            "uint8",
 481        )
 482
 483        self.set_default_params()
 484        self.sync_to_device()
 485
 486    @staticmethod
 487    def serialportlist(ports_to_list="available"):
 488        """Return the names of the USB serial ports on this computer.
 489
 490        Called on the class, without connecting to a device, to find the
 491        port name to pass to `PulsePalDevice`:
 492
 493        ```python
 494        from PulsePal import PulsePalDevice
 495
 496        ports = PulsePalDevice.serialportlist()
 497        P = PulsePalDevice(ports[0])
 498        ```
 499
 500        Args:
 501            ports_to_list: `available` to list only the ports that are
 502                not already in use, or `all` to list every USB serial
 503                port. Not case sensitive.
 504
 505        Returns:
 506            Sorted list of port names, such as `["COM3", "COM7"]` on
 507            Windows or `["/dev/ttyACM0"]` on Linux.
 508
 509        Raises:
 510            PulsePalError: If `ports_to_list` is not `available` or
 511                `all`.
 512        """
 513        if not isinstance(ports_to_list, str):
 514            raise PulsePalError(
 515                "serialportlist() takes 'available' or 'all'."
 516            )
 517        mode = ports_to_list.lower()
 518        if mode not in ("available", "all"):
 519            raise PulsePalError(
 520                f"Unknown port list type: {ports_to_list}. "
 521                "Use 'available' or 'all'."
 522            )
 523
 524        port_names = []
 525        for port_info in serial.tools.list_ports.comports():
 526            is_usb = port_info.vid is not None or "USB" in (
 527                port_info.hwid or ""
 528            ).upper()
 529            if not is_usb:
 530                continue
 531            if mode == "available" and not PulsePalDevice._port_is_free(
 532                port_info.device
 533            ):
 534                continue
 535            port_names.append(port_info.device)
 536        return sorted(port_names)
 537
 538    @staticmethod
 539    def _port_is_free(port_name):
 540        """Return True if the port is not already open in another program."""
 541        port = serial.Serial()
 542        port.port = port_name
 543        # Leaving the control lines low avoids resetting boards that
 544        # reset on DTR while the port is probed.
 545        port.dtr = False
 546        port.rts = False
 547        try:
 548            port.open()
 549        except (serial.SerialException, OSError):
 550            return False
 551        port.close()
 552        return True
 553
 554    def set_default_params(self):
 555        """Reset the local copy of all parameters to their defaults.
 556
 557        The defaults are a 1 ms, +5 V monophasic pulse every 10 ms for
 558        1 second, on all four output channels, linked to trigger channel
 559        1 in normal trigger mode.
 560
 561        This updates only the local copy. Call
 562        `PulsePalDevice.sync_to_device` to program the device with them.
 563        """
 564        nan = float("nan")
 565        self.is_biphasic = [nan, 0, 0, 0, 0]
 566        self.phase1_voltage = [nan, 5, 5, 5, 5]
 567        self.phase2_voltage = [nan, -5, -5, -5, -5]
 568        self.resting_voltage = [nan, 0, 0, 0, 0]
 569        self.phase1_duration = [nan, 0.001, 0.001, 0.001, 0.001]
 570        self.inter_phase_interval = [nan, 0.001, 0.001, 0.001, 0.001]
 571        self.phase2_duration = [nan, 0.001, 0.001, 0.001, 0.001]
 572        self.inter_pulse_interval = [nan, 0.01, 0.01, 0.01, 0.01]
 573        self.burst_duration = [nan, 0, 0, 0, 0]
 574        self.inter_burst_interval = [nan, 0, 0, 0, 0]
 575        self.pulse_train_duration = [nan, 1, 1, 1, 1]
 576        self.pulse_train_delay = [nan, 0, 0, 0, 0]
 577        self.link_trigger_channel1 = [nan, 1, 1, 1, 1]
 578        self.link_trigger_channel2 = [nan, 0, 0, 0, 0]
 579        self.custom_train_id = [nan, 0, 0, 0, 0]
 580        self.custom_train_target = [nan, 0, 0, 0, 0]
 581        self.custom_train_loop = [nan, 0, 0, 0, 0]
 582        self.playback_mode = [nan, 0, 0, 0, 0]
 583        self.trigger_mode = [nan, 0, 0]
 584
 585    def set_voltage(self, channel, voltage):
 586        """Set an output channel to a fixed voltage.
 587
 588        The channel holds the voltage until it is set again or until a
 589        pulse train is triggered on it.
 590
 591        Args:
 592            channel: Output channel number, 1-4.
 593            voltage: Voltage to set, in volts [-10, 10].
 594
 595        Raises:
 596            PulsePalError: If the device does not acknowledge the
 597                command.
 598        """
 599        voltage_bits = self._volts_to_bits(voltage)
 600        self._write_serial(
 601            (self._OP_MENU_BYTE, 79, channel),
 602            "uint8",
 603            voltage_bits,
 604            "uint16",
 605        )
 606        self._read_ack("set_fixed_voltage()")
 607
 608    def set_calibration(self, channel, voltage_offset):
 609        """Calibrate the zero code of an output channel.
 610
 611        The offset is added to every voltage the channel produces, to
 612        correct for DAC offset error. It is stored in the device's
 613        EEPROM and reloaded on boot, so it only needs to be set once.
 614
 615        Requires Pulse Pal hardware v3 or newer.
 616
 617        Args:
 618            channel: Output channel number, 1-4.
 619            voltage_offset: Offset to apply, in volts [-0.1, 0.1].
 620
 621        Raises:
 622            PulsePalError: If the connected hardware is older than v3,
 623                or the device does not acknowledge the command.
 624            ValueError: If `channel` is not 1-4, or `voltage_offset` is
 625                outside [-0.1, 0.1].
 626        """
 627        if self.info.hardware_version < 3:
 628            raise PulsePalError(
 629                "set_calibration() requires hardware v3 or newer."
 630            )
 631        if channel not in (1, 2, 3, 4):
 632            raise ValueError("channel must be 1, 2, 3 or 4")
 633        if voltage_offset < -0.1 or voltage_offset > 0.1:
 634            raise ValueError(
 635                "voltage_offset for zero code calibration must be in range "
 636                "[-0.1, 0.1]"
 637            )
 638        voltage_bits = voltage_offset * (1 / (20 / 65536))
 639        self._write_serial(
 640            (self._OP_MENU_BYTE, 96, channel - 1),
 641            "uint8",
 642            voltage_bits,
 643            "int16",
 644        )
 645        self._read_ack("set_calibration()")
 646
 647    def set_output_param(self, param_name, channel, value):
 648        """Program a single output channel parameter on the device.
 649
 650        The local copy of the parameter is updated to match, so a later
 651        `PulsePalDevice.sync_to_device` will not undo the change.
 652
 653        ```python
 654        P.set_output_param("is_biphasic", 1, 1)
 655        P.set_output_param("phase1_voltage", 1, 10)
 656        P.set_output_param(3, 1, -10)   # same, by param code
 657        ```
 658
 659        Args:
 660            param_name: Parameter name, as listed in
 661                `DeviceInfo.output_parameter_names`, or its integer
 662                parameter code.
 663            channel: Output channel number, 1-4.
 664            value: Value to set. Units are volts for voltage parameters,
 665                seconds for time parameters, and integers for enumerated
 666                parameters. See the attributes of `PulsePalDevice` for
 667                the meaning of each parameter.
 668
 669        Raises:
 670            PulsePalError: If the parameter name is not recognized, the
 671                value does not fit the datatype the device expects, or
 672                the device does not acknowledge the command.
 673        """
 674        original_value = value
 675        param_code = self._get_output_param_code(param_name)
 676
 677        if param_code in (2, 3, 17):
 678            value = self._volts_to_bits(value)
 679            self._write_serial(
 680                (self._OP_MENU_BYTE, 74, param_code, channel),
 681                "uint8",
 682                value,
 683                "uint16",
 684            )
 685        elif 4 <= param_code <= 11:
 686            self._write_serial(
 687                (self._OP_MENU_BYTE, 74, param_code, channel),
 688                "uint8",
 689                self._seconds_to_cycles(value),
 690                "uint32",
 691            )
 692        else:
 693            self._write_serial(
 694                (self._OP_MENU_BYTE, 74, param_code, channel, value),
 695                "uint8",
 696            )
 697
 698        self._read_ack("program_output_channel_param()")
 699        self._set_output_param_value(param_code, channel, original_value)
 700
 701    def set_trigger_param(self, param_name, channel, value):
 702        """Program a single trigger channel parameter on the device.
 703
 704        The local copy of the parameter is updated to match, so a later
 705        `PulsePalDevice.sync_to_device` will not undo the change.
 706
 707        ```python
 708        P.set_trigger_param("trigger_mode", 1, 2)  # pulse gated
 709        ```
 710
 711        Args:
 712            param_name: Parameter name, as listed in
 713                `DeviceInfo.trigger_parameter_names`, or its integer
 714                parameter code.
 715            channel: Trigger channel number, 1-2.
 716            value: Value to set. See `PulsePalDevice.trigger_mode` for
 717                the trigger modes.
 718
 719        Raises:
 720            PulsePalError: If the parameter name is not recognized, the
 721                value does not fit the datatype the device expects, or
 722                the device does not acknowledge the command.
 723        """
 724        original_value = value
 725        param_code = self._get_trigger_param_code(param_name)
 726
 727        self._write_serial(
 728            (self._OP_MENU_BYTE, 74, param_code, channel, value),
 729            "uint8",
 730        )
 731        self._read_ack("program_trigger_channel_param()")
 732
 733        if param_code in (1, 128):
 734            self.trigger_mode[channel] = original_value
 735
 736    def sync_to_device(self):
 737        """Program the device with the local copy of all parameters.
 738
 739        Call this after assigning to the parameter array attributes, to
 740        send every output and trigger parameter to the device in a
 741        single transaction.
 742
 743        ```python
 744        P.phase1_voltage[1:5] = [5] * 4
 745        P.sync_to_device()
 746        ```
 747
 748        Raises:
 749            PulsePalError: If the device does not acknowledge the
 750                command.
 751        """
 752        # _sync_all_params() for firmware v22+ uses the newer packed sync
 753        # opcode (92). _sync_all_params_legacy() uses the less efficient
 754        # legacy packed sync opcode (73).
 755        if self.info.firmware_version > 21:
 756            self._sync_all_params()
 757        else:
 758            self._sync_all_params_legacy()
 759        self._read_ack("sync_to_device()")
 760
 761    def sync_from_device(self):
 762        """Read all parameters from the device into the local copy.
 763
 764        Overwrites every parameter array attribute with the program
 765        currently stored on the device. Useful after the device has been
 766        reprogrammed from its thumb joystick.
 767
 768        Requires firmware v22 or newer.
 769
 770        Raises:
 771            PulsePalError: If the connected firmware is older than v22,
 772                or the device does not return the full parameter set.
 773        """
 774        self._require_firmware(22, "sync_from_device()")
 775        self._write_serial((self._OP_MENU_BYTE, 93), "uint8")
 776        for attr_name in (
 777                "phase1_duration",
 778                "inter_phase_interval",
 779                "phase2_duration",
 780                "inter_pulse_interval",
 781                "burst_duration",
 782                "inter_burst_interval",
 783                "pulse_train_duration",
 784                "pulse_train_delay",
 785        ):
 786            setattr(
 787                self,
 788                attr_name,
 789                [float("nan")]
 790                + [
 791                    self._cycles_to_seconds(x)
 792                    for x in self._read_serial(4, "uint32")
 793                ],
 794            )
 795
 796        for attr_name in (
 797                "phase1_voltage",
 798                "phase2_voltage",
 799                "resting_voltage",
 800        ):
 801            setattr(
 802                self,
 803                attr_name,
 804                [float("nan")]
 805                + [
 806                    self._bits_to_volts(x)
 807                    for x in self._read_serial(4, "uint16")
 808                ],
 809            )
 810
 811        for attr_name in (
 812                "is_biphasic",
 813                "custom_train_id",
 814                "custom_train_target",
 815                "custom_train_loop",
 816                "link_trigger_channel1",
 817                "link_trigger_channel2",
 818        ):
 819            setattr(
 820                self,
 821                attr_name,
 822                [float("nan")] + self._read_serial(4, "uint8"),
 823            )
 824        self.trigger_mode = [float("nan")] + self._read_serial(2, "uint8")
 825
 826    def send_custom_pulse_train(
 827        self,
 828        custom_train_id,
 829        pulse_times,
 830        pulse_voltages,
 831    ):
 832        """Load a custom pulse train onto the device.
 833
 834        A custom pulse train is an arbitrary list of pulse onset times
 835        and voltages, replacing the parametric pulse voltage and onset timing.
 836        Set `PulsePalDevice.custom_train_id` on an output channel to play
 837        the train there.
 838
 839        ```python
 840        P.send_custom_pulse_train(
 841            2, [0, 0.2, 0.5, 1], [8, 4, -3.5, -10]
 842        )
 843        P.set_output_param("custom_train_id", 1, 2)
 844        ```
 845
 846        Args:
 847            custom_train_id: Custom train to load, 1-2. See
 848                `DeviceInfo.n_custom_pulse_trains`.
 849            pulse_times: Pulse onset times, in seconds, relative to the
 850                start of the train. Accepts a list, tuple or NumPy
 851                array.
 852            pulse_voltages: Voltage of each pulse, in volts [-10, 10].
 853                Must be the same length as `pulse_times`.
 854
 855        Raises:
 856            PulsePalError: If `pulse_times` and `pulse_voltages` differ
 857                in length, or the device does not acknowledge the
 858                command.
 859        """
 860        pulse_times = self._as_list(pulse_times)
 861        pulse_voltages = self._as_list(pulse_voltages)
 862        n_pulses = len(pulse_times)
 863        if n_pulses != len(pulse_voltages):
 864            raise PulsePalError(
 865                "pulse_times and pulse_voltages must be the same length."
 866            )
 867
 868        pulse_times_cycles = [
 869            self._seconds_to_cycles(pulse_time)
 870            for pulse_time in pulse_times
 871        ]
 872        pulse_voltage_bits = [
 873            self._volts_to_bits(voltage)
 874            for voltage in pulse_voltages
 875        ]
 876
 877        op_code = int(custom_train_id) + 74
 878        self._write_serial(
 879            (self._OP_MENU_BYTE, op_code),
 880            "uint8",
 881            n_pulses,
 882            "uint32",
 883            pulse_times_cycles,
 884            "uint32",
 885            pulse_voltage_bits,
 886            "uint16",
 887        )
 888        self._read_ack("send_custom_pulse_train()")
 889
 890    def send_custom_waveform(
 891        self,
 892        custom_train_id,
 893        pulse_width,
 894        pulse_voltages,
 895    ):
 896        """Load an arbitrary waveform onto the device.
 897
 898        A convenience shorthand for
 899        `PulsePalDevice.send_custom_pulse_train` with evenly spaced,
 900        confluent pulses, so that `pulse_voltages` is played as a
 901        waveform sampled every `pulse_width` seconds.
 902
 903        Set the channel's `PulsePalDevice.phase1_duration` to
 904        `pulse_width` as well, so that each sample is held for the
 905        sampling period.
 906
 907        ```python
 908        import math
 909
 910        samples = [math.sin(i / 10.0) * 10 for i in range(1000)]
 911        P.send_custom_waveform(1, 0.001, samples)   # 1 kHz
 912        P.set_output_param("custom_train_id", 2, 1)
 913        P.set_output_param("phase1_duration", 2, 0.001)
 914        ```
 915
 916        Args:
 917            custom_train_id: Custom train to load, 1-2. See
 918                `DeviceInfo.n_custom_pulse_trains`.
 919            pulse_width: Sampling period, in seconds. Each voltage is
 920                held for this long.
 921            pulse_voltages: Waveform samples, in volts [-10, 10].
 922                Accepts a list, tuple or NumPy array.
 923
 924        Raises:
 925            PulsePalError: If the device does not acknowledge the
 926                command.
 927        """
 928        pulse_voltages = self._as_list(pulse_voltages)
 929        n_pulses = len(pulse_voltages)
 930        pulse_width_cycles = self._seconds_to_cycles(pulse_width)
 931        pulse_times = [pulse_width_cycles * i for i in range(n_pulses)]
 932        pulse_voltage_bits = [
 933            self._volts_to_bits(voltage)
 934            for voltage in pulse_voltages
 935        ]
 936
 937        op_code = int(custom_train_id) + 74
 938        self._write_serial(
 939            (self._OP_MENU_BYTE, op_code),
 940            "uint8",
 941            n_pulses,
 942            "uint32",
 943            pulse_times,
 944            "uint32",
 945            pulse_voltage_bits,
 946            "uint16",
 947        )
 948        self._read_ack("send_custom_waveform()")
 949
 950    def trigger(
 951        self,
 952        channel1=None,
 953        channel2=None,
 954        channel3=None,
 955        channel4=None,
 956    ):
 957        """Trigger output channels in software.
 958
 959        Triggered channels start their pulse trains together. Three
 960        calling conventions are accepted:
 961
 962        ```python
 963        P.trigger(1, 0, 1, 0)   # one flag per channel
 964        P.trigger(3)            # a single channel number
 965        P.trigger([1, 4])       # several channel numbers
 966        ```
 967
 968        Channel numbers outside 1-4 are ignored.
 969
 970        Args:
 971            channel1: `1` to trigger channel 1, otherwise `0`; or, when
 972                it is the only argument given, a single channel number
 973                or a list of channel numbers to trigger.
 974            channel2: `1` to trigger channel 2, otherwise `0`.
 975            channel3: `1` to trigger channel 3, otherwise `0`.
 976            channel4: `1` to trigger channel 4, otherwise `0`.
 977        """
 978        trigger_byte = 0
 979
 980        # Options 2 & 3: Only one argument was provided
 981        if channel2 is None and channel3 is None and channel4 is None:
 982            # Option 2: Single integer
 983            if isinstance(channel1, int):
 984                channels_to_trigger = [channel1]
 985            # Option 3: List/Tuple of integers
 986            elif isinstance(channel1, (list, tuple, set)):
 987                channels_to_trigger = channel1
 988            else:
 989                channels_to_trigger = []
 990
 991            # Use bitwise shifts to calculate the trigger byte
 992            # (ch1=bit0, ch2=bit1, etc.)
 993            for ch in channels_to_trigger:
 994                if 1 <= ch <= 4:
 995                    trigger_byte |= (1 << (ch - 1))
 996
 997        # Option 1: Original input scheme (logicals for each channel)
 998        else:
 999            # Fallback to 0 if an argument was omitted via kwargs
1000            c1 = channel1 if channel1 is not None else 0
1001            c2 = channel2 if channel2 is not None else 0
1002            c3 = channel3 if channel3 is not None else 0
1003            c4 = channel4 if channel4 is not None else 0
1004
1005            trigger_byte = (
1006                (1 * c1)
1007                + (2 * c2)
1008                + (4 * c3)
1009                + (8 * c4)
1010            )
1011
1012        self._write_serial((self._OP_MENU_BYTE, 77, trigger_byte), "uint8")
1013
1014    def sd_settings(self, settings_file_name, op):
1015        """Save, load, or delete a settings file on the microSD card.
1016
1017        A settings file holds a complete Pulse Pal program, so that it
1018        can be recalled later from software or from the device's front
1019        panel. Loading a file also refreshes the local copy of the
1020        parameters, via `PulsePalDevice.sync_from_device`.
1021
1022        ```python
1023        P.sd_settings("MyProtocol.pps", "save")
1024        ```
1025
1026        Args:
1027            settings_file_name: Settings file name, at most 15 ASCII
1028                characters including the required `.pps` extension.
1029            op: `"save"`, `"load"`, or `"delete"`.
1030
1031        Raises:
1032            PulsePalError: If the file name has no `.pps` extension or
1033                is too long, `op` is not one of the three operations, or
1034                the device does not acknowledge the command.
1035        """
1036        if ".pps" not in settings_file_name:
1037            raise PulsePalError(
1038                "Error: The file name must have a valid .pps extension."
1039            )
1040        op_byte_by_name = {"save": 1, "load": 2, "delete": 3}
1041        try:
1042            op_byte = op_byte_by_name[str(op).lower()]
1043        except KeyError as exc:
1044            raise PulsePalError(
1045                "File op must be: 'save', 'load' or 'delete'."
1046            ) from exc
1047
1048        filename_bytes = settings_file_name.encode("ascii")
1049        if len(filename_bytes) > 15:
1050            raise PulsePalError("settings_file_name is too long.")
1051        self._write_serial(
1052            (self._OP_MENU_BYTE, 90, op_byte, len(filename_bytes)),
1053            "uint8",
1054            list(filename_bytes),
1055            "uint8",
1056        )
1057        if self.info.firmware_version > 21:
1058            self._read_ack("sd_settings()")
1059        if op_byte == 2:
1060            time.sleep(0.1)
1061            self.sync_from_device()
1062
1063    def stop(self, channels=None):
1064        """Stop pulse trains currently playing on the device.
1065
1066        Every output channel returns to its
1067        `PulsePalDevice.resting_voltage`.
1068
1069        Args:
1070            channels (list or tuple, optional): A list of channels to stop, e.g.,
1071                [1, 3, 4] to stop playback on Ch1, Ch3, and Ch4. Default is None,
1072                which stops all channels. (Requires firmware v22+)
1073        """
1074        bit_code = 15  # Default: 15 (binary 1111) stops all channels
1075
1076        if channels is not None:
1077            if self.info.firmware_version < 22:
1078                raise ValueError("stop() cannot address individual channels prior to firmware v22")
1079
1080            # If a single integer is provided, wrap it in a list
1081            if isinstance(channels, int):
1082                channels = [channels]
1083
1084            bit_code = 0
1085            for ch in channels:
1086                if ch not in (1, 2, 3, 4):
1087                    raise ValueError("All channels must be valid Pulse Pal output channel indexes: 1, 2, 3 or 4")
1088
1089                # Bitwise OR (|=) handles the summation, safely ignoring duplicate channel entries
1090                bit_code |= 1 << (ch - 1)
1091
1092        # Send
1093        if self.info.firmware_version < 22:
1094            self._write_serial((self._OP_MENU_BYTE, 80), "uint8")
1095        else:
1096            self._write_serial((self._OP_MENU_BYTE, 98, bit_code), "uint8")
1097
1098    def format_microsd(self, timeout=30):
1099        """Format the device's microSD card.
1100
1101        Erases every settings file stored on the device and resets its
1102        parameters to the defaults. The user is prompted at the console
1103        to confirm before anything is erased.
1104
1105        Requires Pulse Pal hardware v3 or newer.
1106
1107        Args:
1108            timeout: Seconds to wait for the device to report that
1109                formatting has finished.
1110
1111        Returns:
1112            `None` once the card has been formatted, or an empty string
1113            if the user declines the confirmation prompt.
1114
1115        Raises:
1116            PulsePalError: If the connected hardware is older than v3.
1117        """
1118        if self.info.hardware_version < 3:
1119            raise PulsePalError(
1120                "format_microsd() requires hardware v3 or newer."
1121            )
1122
1123        print("*** Pulse Pal microSD Formatter ***")
1124        print("This will format Pulse Pal's microSD card,")
1125        print("erase all settings files on the device")
1126        print("and reset all parameters to defaults.")
1127
1128        reply = input("Do you want to continue (y/n)")
1129
1130        if reply.strip().lower() != "y":
1131            print("Choice confirmed - microSD Card NOT formatted.")
1132            return ""
1133
1134        self._write_serial((self._OP_MENU_BYTE, 97), "uint8")
1135
1136        start = time.time()
1137        message = bytearray()
1138
1139        while time.time() - start < timeout:
1140            n_waiting = self.bytes_available()
1141            if n_waiting:
1142                message.extend(self.port.read(n_waiting))
1143                if ord("!") in message:
1144                    break
1145            time.sleep(0.01)
1146        raw_message = bytes(message)
1147        flag_index = raw_message.find(b"!")
1148        if flag_index >= 0:
1149            displayed_message = raw_message[:flag_index]
1150        else:
1151            displayed_message = raw_message
1152
1153        text = displayed_message.decode("ascii", errors="replace").rstrip()
1154        if text:
1155            print(text)
1156
1157        self.set_default_params()
1158        return None
1159
1160    def gui(self, block=None, theme=None):
1161        """Open the Pulse Pal parameter GUI, or focus an open one.
1162
1163        The GUI edits its own copy of the parameters, and loads them to
1164        the device when its 'Load to Device' button is clicked. The
1165        window closes automatically when the device is closed or
1166        deleted.
1167
1168        Calling this while the GUI is already open focuses the existing
1169        window rather than opening a second one.
1170
1171        Args:
1172            block: If `True`, the call returns when the GUI is closed. If
1173                `False`, the call returns immediately, and the host
1174                application must run the Tk event loop. If `None`, the
1175                GUI blocks only when the host does not already provide a
1176                Tk event loop, e.g. when launched from a script.
1177            theme: `"light"` or `"dark"` to select the color theme, or
1178                `None` to match the desktop theme. Passing a theme to an
1179                already-open GUI recolors it in place.
1180
1181        Returns:
1182            The `PulsePalGUI.PulsePalGUI` instance driving the window.
1183
1184        Raises:
1185            ValueError: If the theme name is not recognized.
1186        """
1187        gui = getattr(self, "_gui", None)
1188        if gui is not None and not gui.is_closed:
1189            if theme is not None:
1190                gui.set_theme(theme)
1191            gui.focus()
1192            return gui
1193
1194        try:
1195            from .PulsePalGUI import PulsePalGUI
1196        except ImportError:
1197            from PulsePalGUI import PulsePalGUI
1198
1199        gui = PulsePalGUI(self, theme=theme)
1200        self._gui = gui
1201        gui.start(block=block)
1202        return gui
1203
1204    def close(self, send_disconnect=True):
1205        """Close the connection to the device, and the GUI if open.
1206
1207        Safe to call more than once; later calls do nothing. Called
1208        automatically when leaving a `with` block and when the object is
1209        garbage collected.
1210
1211        Args:
1212            send_disconnect: If `True`, tell the device that the client
1213                is disconnecting before closing the port. Set to `False`
1214                when the device is in an unknown state, such as after a
1215                failed handshake.
1216        """
1217        gui = getattr(self, "_gui", None)
1218        self._gui = None
1219        if gui is not None:
1220            try:
1221                gui.close()
1222            except Exception:
1223                # Cleanup must not raise; Tk may already be torn down
1224                pass
1225
1226        if getattr(self, "_closed", True):
1227            return
1228
1229        try:
1230            if send_disconnect and self.port and self.port.is_open:
1231                self._write_serial((self._OP_MENU_BYTE, 81), "uint8")
1232        finally:
1233            if self.port and self.port.is_open:
1234                self.port.close()
1235            self._closed = True
1236
1237    def bytes_available(self):
1238        """Return the number of bytes waiting in the serial read buffer.
1239
1240        Returns:
1241            Count of bytes that can be read without blocking.
1242        """
1243        return self.port.in_waiting
1244
1245    def _get_output_param_code(self, param_name):
1246        """Resolve an output parameter name or code to its code."""
1247        if isinstance(param_name, str):
1248            try:
1249                return self.info.output_parameter_names.index(param_name) + 1
1250            except ValueError as exc:
1251                raise PulsePalError(
1252                    f"Unknown output parameter: {param_name}."
1253                ) from exc
1254        return int(param_name)
1255
1256    def _get_trigger_param_code(self, param_name):
1257        """Resolve a trigger parameter name or code to its code."""
1258        if isinstance(param_name, str):
1259            try:
1260                index = self.info.trigger_parameter_names.index(param_name)
1261                return index + 128
1262            except ValueError as exc:
1263                raise PulsePalError(
1264                    f"Unknown trigger parameter: {param_name}."
1265                ) from exc
1266        return int(param_name)
1267
1268    def _write_serial(self, *args):
1269        """Write one or more data/type pairs to the serial port."""
1270        if len(args) % 2 != 0:
1271            raise PulsePalError(
1272                "Serial writes require data/type argument pairs."
1273            )
1274
1275        payload = bytearray()
1276        for i in range(0, len(args), 2):
1277            payload.extend(self._pack_values(args[i], args[i + 1]))
1278
1279        bytes_written = self.port.write(bytes(payload))
1280        if bytes_written != len(payload):
1281            raise PulsePalError(
1282                f"Error: wrote {bytes_written} byte(s), expected to write "
1283                f"{len(payload)} byte(s)."
1284            )
1285
1286    def _read_serial(self, n_values, datatype):
1287        """Read values from the serial port and unpack them with struct."""
1288        datatype = self._normalize_datatype(datatype)
1289        fmt = self._STRUCT_FORMATS[datatype]
1290        n_values = int(n_values)
1291        n_bytes = n_values * struct.calcsize(fmt)
1292        message_bytes = self.port.read(n_bytes)
1293        if len(message_bytes) < n_bytes:
1294            raise PulsePalError(
1295                f"Error: serial port timed out. "
1296                f"{len(message_bytes)} byte(s) read. "
1297                f"Expected {n_bytes} byte(s)."
1298            )
1299
1300        values = struct.unpack(
1301            f"{self._ENDIANNESS}{n_values}{fmt}",
1302            message_bytes,
1303        )
1304        if n_values == 1:
1305            return values[0]
1306        return list(values)
1307
1308    def _read_ack(self, context):
1309        """Read a one-byte acknowledgement from the device."""
1310        try:
1311            self._read_serial(1, "uint8")
1312        except PulsePalError as exc:
1313            raise PulsePalError(
1314                "Error: Pulse Pal did not return an acknowledgement byte "
1315                f"after a call to {context}."
1316            ) from exc
1317
1318    def _pack_values(self, values, datatype):
1319        """Pack scalar, list/tuple, or NumPy array values into bytes."""
1320        datatype = self._normalize_datatype(datatype)
1321        fmt = self._STRUCT_FORMATS[datatype]
1322        values_list = self._as_list(values)
1323
1324        if datatype == "char":
1325            values_list = self._normalize_char_values(values_list)
1326        elif datatype in self._TYPE_RANGES:
1327            values_list = self._normalize_int_values(values_list, datatype)
1328        else:
1329            values_list = [float(value) for value in values_list]
1330
1331        return struct.pack(
1332            f"{self._ENDIANNESS}{len(values_list)}{fmt}",
1333            *values_list,
1334        )
1335
1336    def _normalize_datatype(self, datatype):
1337        """Return the datatype name, rejecting unsupported types."""
1338        datatype = str(datatype)
1339        if datatype not in self._STRUCT_FORMATS:
1340            raise PulsePalError(
1341                f"Error: {datatype} is not a data type supported by "
1342                "PulsePalObject."
1343            )
1344        return datatype
1345
1346    def _normalize_char_values(self, values):
1347        """Coerce str, int and bytes values to single ASCII bytes."""
1348        normalized = []
1349        for value in values:
1350            if isinstance(value, str):
1351                value = value.encode("ascii")
1352            if isinstance(value, int):
1353                value = bytes((value,))
1354            if not isinstance(value, (bytes, bytearray)) or len(value) != 1:
1355                raise PulsePalError(
1356                    "char values must be one-byte bytes, chars, or "
1357                    "integers."
1358                )
1359            normalized.append(bytes(value))
1360        return normalized
1361
1362    def _normalize_int_values(self, values, datatype):
1363        """Coerce values to ints, rejecting any out of range."""
1364        min_value, max_value = self._TYPE_RANGES[datatype]
1365        normalized = []
1366        for value in values:
1367            value = int(value)
1368            if not min_value <= value <= max_value:
1369                raise PulsePalError(
1370                    f"Value {value} is out of range for {datatype} "
1371                    f"({min_value} to {max_value})."
1372                )
1373            normalized.append(value)
1374        return normalized
1375
1376    def _as_list(self, values):
1377        """Return values as a flat list, wrapping scalars in one."""
1378        if isinstance(values, np.ndarray):
1379            return values.ravel().tolist()
1380        if isinstance(values, (bytes, bytearray, str)):
1381            return [values]
1382        if isinstance(values, numbers.Number) or isinstance(values, Decimal):
1383            return [values]
1384        try:
1385            return list(values)
1386        except TypeError:
1387            return [values]
1388
1389    def _set_output_param_value(self, param_code, channel, original_value):
1390        """Store a programmed value in its local parameter array."""
1391        attr_name = self._OUTPUT_PARAMETER_ATTRS.get(param_code)
1392        if attr_name is None:
1393            return
1394        values = getattr(self, attr_name)
1395        values[channel] = original_value
1396
1397    def _to_decimal(self, value):
1398        """Convert a value to a Decimal with PulsePal precision."""
1399        return Decimal(value).quantize(Decimal("1.0000"))
1400
1401    def _volts_to_bits(self, value):
1402        """Convert -10 V to +10 V to the corresponding DAC bit value."""
1403        normalized = (float(value) + 10) / 20
1404        bit_max = int(self._dac_bit_max)
1405        return int(min(max(round(normalized * bit_max), 0), bit_max))
1406
1407    def _bits_to_volts(self, value):
1408        """Convert a DAC code to volts, snapping clean values within 1 LSB."""
1409        bit_max = int(self._dac_bit_max)
1410        raw_volts = (float(value) / bit_max * 20) - 10
1411
1412        # Calculate the voltage of 1 bit
1413        lsb_volts = 20.0 / bit_max
1414
1415        # Find the nearest clean 3-decimal number (e.g. 5.000, 4.255)
1416        clean_volts = round(raw_volts, 3)
1417
1418        # If the raw voltage is within 1 bit of the clean voltage, snap to it
1419        if abs(raw_volts - clean_volts) <= lsb_volts:
1420            return clean_volts
1421
1422        # Otherwise, return the standard 4-decimal reading
1423        return round(raw_volts, 4)
1424
1425    def _seconds_to_cycles(self, value):
1426        """Convert seconds to the corresponding refresh-cycle count."""
1427        return int(round(float(value) * float(self.info.cycle_frequency)))
1428
1429    def _cycles_to_seconds(self, value):
1430        """Convert hardware timer cycle counts to seconds."""
1431        return float(value) / float(self.info.cycle_frequency)
1432
1433    def _require_firmware(self, minimum_version, context):
1434        """Raise unless the device firmware is new enough for an op."""
1435        if (
1436            self.info.firmware_version is None
1437            or self.info.firmware_version < minimum_version
1438        ):
1439            raise PulsePalError(
1440                f"{context} requires firmware v{minimum_version} or newer. "
1441                f"Detected firmware is v{self.info.firmware_version}."
1442            )
1443
1444    def _sync_all_params(self):
1445        """Send all parameters using the packed sync op (firmware v22+).
1446
1447        Values are grouped by width so that the whole program travels as
1448        one uint32 block, one uint16 block and one uint8 block.
1449        """
1450        time_values = []
1451        for attr_name in (
1452            "phase1_duration",
1453            "inter_phase_interval",
1454            "phase2_duration",
1455            "inter_pulse_interval",
1456            "burst_duration",
1457            "inter_burst_interval",
1458            "pulse_train_duration",
1459            "pulse_train_delay",
1460        ):
1461            time_values.extend(
1462                self._seconds_to_cycles(getattr(self, attr_name)[channel])
1463                for channel in range(1, 5)
1464            )
1465
1466        voltage_values = []
1467        for attr_name in (
1468            "phase1_voltage",
1469            "phase2_voltage",
1470            "resting_voltage",
1471        ):
1472            voltage_values.extend(
1473                self._volts_to_bits(getattr(self, attr_name)[channel])
1474                for channel in range(1, 5)
1475            )
1476
1477        single_byte_values = []
1478        for attr_name in (
1479            "is_biphasic",
1480            "custom_train_id",
1481            "custom_train_target",
1482            "custom_train_loop",
1483            "playback_mode",
1484        ):
1485            single_byte_values.extend(
1486                int(getattr(self, attr_name)[channel])
1487                for channel in range(1, 5)
1488            )
1489        single_byte_values.extend(
1490            int(self.link_trigger_channel1[channel])
1491            for channel in range(1, 5)
1492        )
1493        single_byte_values.extend(
1494            int(self.link_trigger_channel2[channel])
1495            for channel in range(1, 5)
1496        )
1497        single_byte_values.extend(
1498            int(value) for value in self.trigger_mode[1:3]
1499        )
1500
1501        self._write_serial(
1502            (self._OP_MENU_BYTE, 92),
1503            "uint8",
1504            time_values,
1505            "uint32",
1506            voltage_values,
1507            "uint16",
1508            single_byte_values,
1509            "uint8",
1510        )
1511
1512    def _sync_all_params_legacy(self):
1513        """Send all parameters using the legacy sync op (firmware v21).
1514
1515        Equivalent to `_sync_all_params`, but lays the program out
1516        channel by channel as the older firmware expects.
1517        """
1518        program_values_16 = []
1519        program_values_32 = []
1520        program_values_8 = [0] * 16
1521
1522        for channel in range(1, 5):
1523            program_values_32.extend(
1524                [
1525                    self._seconds_to_cycles(
1526                        self.phase1_duration[channel]),
1527                    self._seconds_to_cycles(
1528                        self.inter_phase_interval[channel]),
1529                    self._seconds_to_cycles(
1530                        self.phase2_duration[channel]),
1531                    self._seconds_to_cycles(
1532                        self.inter_pulse_interval[channel]),
1533                    self._seconds_to_cycles(
1534                        self.burst_duration[channel]),
1535                    self._seconds_to_cycles(
1536                        self.inter_burst_interval[channel]),
1537                    self._seconds_to_cycles(
1538                        self.pulse_train_duration[channel]),
1539                    self._seconds_to_cycles(
1540                        self.pulse_train_delay[channel]),
1541                ]
1542            )
1543
1544        for channel in range(1, 5):
1545            program_values_16.extend(
1546                [
1547                    self._volts_to_bits(self.phase1_voltage[channel]),
1548                    self._volts_to_bits(self.phase2_voltage[channel]),
1549                    self._volts_to_bits(self.resting_voltage[channel]),
1550                ]
1551            )
1552
1553        position = 0
1554        for channel in range(1, 5):
1555            program_values_8[position] = self.is_biphasic[channel]
1556            position += 1
1557            program_values_8[position] = self.custom_train_id[channel]
1558            position += 1
1559            program_values_8[position] = self.custom_train_target[channel]
1560            position += 1
1561            program_values_8[position] = self.custom_train_loop[channel]
1562            position += 1
1563
1564        program_values_tl = [0] * 8
1565        position = 0
1566        for channel in range(1, 5):
1567            program_values_tl[position] = self.link_trigger_channel1[channel]
1568            position += 1
1569        for channel in range(1, 5):
1570            program_values_tl[position] = self.link_trigger_channel2[channel]
1571            position += 1
1572
1573        self._write_serial(
1574            (self._OP_MENU_BYTE, 73),
1575            "uint8",
1576            program_values_32,
1577            "uint32",
1578            program_values_16,
1579            "uint16",
1580            program_values_8,
1581            "uint8",
1582            program_values_tl,
1583            "uint8",
1584            self.trigger_mode[1:3],
1585            "uint8",
1586        )
1587
1588    def __enter__(self):
1589        """Enter a `with` block, returning the connected device."""
1590        return self
1591
1592    def __exit__(self, exc_type, exc_value, traceback):
1593        """Disconnect and close the port when leaving a `with` block.
1594
1595        Returns:
1596            `False`, so any exception raised in the block propagates.
1597        """
1598        try:
1599            self._write_serial((self._OP_MENU_BYTE, 81), "uint8")
1600        except Exception:
1601            pass
1602        self.close()
1603        return False
1604
1605    def __del__(self):
1606        """Disconnect and close the port when the object is collected."""
1607        try:
1608            self._write_serial((self._OP_MENU_BYTE, 81), "uint8")
1609        except Exception:
1610            pass
1611
1612        try:
1613            self.close()
1614        except Exception:
1615            # Destructors should not raise; the serial object may already be
1616            # gone during interpreter shutdown.
1617            pass