Comm

pychilaslasers.comm

Serial communication interface for Chilas laser systems.

Provides low-level serial communication with laser drivers, including command/response handling, connection management, and port discovery.

Classes:

• Communication –

  Main serial communication handler.

Functions:

• list_comports –

  Discover available COM ports.

Authors: RLK, AVR, SDU

pychilaslasers.comm.Communication(com_port: str)

Communication class for handling communication with the laser driver over serial.

This class provides methods for sending commands to the laser, receiving responses, and managing the serial connection. It also handles the prefix mode for the laser driver.

This method sets up the serial connection to the laser driver and initializes the communication parameters. It also registers cleanup functions to ensure the serial connection is properly closed on exit or signal termination. And sets the initial baudrate to the default value. When a connection fails, it will attempt to reconnect using the next supported baudrate until a connection is established as this is one of the most common issues when connecting to the laser driver.

Parameters:

• com_port (str) –

  The serial port to connect to the laser driver. this can be found by using the pychilaslasers.comm.list_comports() function.

Returned by:

• Package Reference Laser  Laser Attributes  comm

Source code in src/pychilaslasers/comm.py

def __init__(self, com_port: str) -> None:
    """Initialize the Communication class with the specified serial port.

    This method sets up the serial connection to the laser driver and initializes
    the communication parameters. It also registers cleanup functions to ensure
    the serial connection is properly closed on exit or signal termination. And
    sets the initial baudrate to the default value. When a connection fails, it will
    attempt to reconnect using the next supported baudrate until a connection is
    established as this is one of the most common issues when connecting to the
    laser driver.

    Args:
        com_port: The serial port to connect to the laser driver.
            this can be found by using the `pychilaslasers.comm.list_comports()`
            function.

    """
    # Validate the com_port input
    if not isinstance(com_port, str):
        raise ValueError(
            "The com_port must be a string representing the serial port."
        )

    # Initialize serial connection to the laser
    self._serial: serial.Serial = serial.Serial(
        port=com_port,
        baudrate=Constants.TLM_INITIAL_BAUDRATE,  # Use the first supported baudrate
        bytesize=serial.EIGHTBITS,
        parity=serial.PARITY_NONE,
        stopbits=serial.STOPBITS_ONE,
        timeout=1.0,
    )
    self._previous_command: str = "None"

    self._prefix_mode: bool = True
    # Attempt to open the serial connection by trying different baudrates
    baudrates: set[int] = set(
        Constants.SUPPORTED_BAUDRATES
    )  # Copy to avoid modifying the original set
    rate = Constants.TLM_INITIAL_BAUDRATE
    while True:
        try:
            self.prefix_mode = True
            break
        except Exception:
            try:
                logger.error(
                    f"Serial connection failed at {rate} baud.Attempting new "
                    f"connection with baudrate {(rate := baudrates.pop())}."
                )
                self.baudrate = rate  # Try next baudrate if the current one fails
            except KeyError:
                logger.critical(
                    "No more supported baudrates available. Cannot establish serial"
                    " connection."
                )
                raise RuntimeError(
                    "Failed to establish serial connection with the laser driver. "
                    + "Please check the connection and supported baudrates."
                ) from None
    self.baudrate = Constants.DEFAULT_BAUDRATE

    # Ensure proper closing of the serial connection on exit or signal
    try:
        atexit.register(self.close_connection)
        signal.signal(signal.SIGINT, self.close_connection)
        signal.signal(signal.SIGTERM, self.close_connection)
    except Exception:
        # This may fail in threaded environments
        pass

Attributes

prefix_mode: bool property writable

Gets prefix mode for the laser driver.

The laser can be operated in two different communication modes:

1. Prefix mode on
2. Prefix mode off

When prefix mode is on, every message over the serial connection will be replied to by the driver with a response, and every response will be prefixed with a return code (rc), either 0 or 1 for an OK or ERROR respectively.

With prefix mode is off, responses from the laser driver are not prefixed with a return code. This means that in the case for a serial write command without an expected return value, the driver will not send back a reply.

Returns:

• bool –

  whether prefix mode is enabled (True) or disabled (False)

baudrate: int property writable

Gets the baudrate of the serial connection to the driver.

The baudrate can be changed, but does require a serial reconnect

Currently supported baudrates are:

• 9600
• 14400
• 19200
• 28800
• 38400
• 57600 default
• 115200
• 230400
• 460800
• 912600

Returns:

• int –

  baudrate currently in use

port: str property

Get the serial port currently used for communication.

Returns:

• str ( str ) –

  The name of the serial port in use.

Functions

__del__() -> None

Destructor that ensures the serial connection is closed after deletion.

This method is called when the object is garbage collected, providing an additional safety mechanism to ensure the serial connection is properly closed even if the user forgets to call close explicitly or if the program terminates unexpectedly.

Source code in src/pychilaslasers/comm.py

def __del__(self) -> None:
    """Destructor that ensures the serial connection is closed after deletion.

    This method is called when the object is garbage collected, providing an
    additional safety mechanism to ensure the serial connection is properly closed
    even if the user forgets to call close explicitly or if the program terminates
    unexpectedly.
    """
    self.close_connection()

query(data: str) -> str

Send a command to the laser and return its response.

This method sends a command to the laser over the serial connection and returns the response. It also handles the logging of the command and response. The response code of the reply is checked and an error is raised if the response code is not 0. Commands that are sent multiple times may be replaced with a semicolon to speed up communication.

Parameters:

• data (str) –

  The serial command to be sent to the laser.

Returns:

• str ( str ) –
• str –

  The response from the laser. The response is stripped of any leading or trailing whitespace as well as the return code. Response may be empty if the command does not return a value.

Raises:

• SerialException –

  If there is an error in the serial communication, such as a decoding error or an empty reply.

• LaserError –

  If the response code from the laser is not 0, indicating an error.

Source code in src/pychilaslasers/comm.py

def query(self, data: str) -> str:
    """Send a command to the laser and return its response.

    This method sends a command to the laser over the serial connection and returns
    the response. It also handles the logging of the command and response. The
    response code of the reply is checked and an error is raised if the response
    code is not 0. Commands that are sent multiple times may be replaced with a
    semicolon to speed up communication.

    Args:
        data: The serial command to be sent to the laser.

    Returns:
        str:
        The response from the laser. The response is stripped of any leading
            or trailing whitespace as well as the return code. Response may be
            empty if the command does not return a value.

    Raises:
        serial.SerialException: If there is an error in the serial communication,
            such as a decoding error or an empty reply.
        LaserError: If the response code from the laser is not 0,
            indicating an error.

    """
    # Write the command to the serial port
    logger.debug(msg=f"W {data}")  # Logs the command being sent
    self._serial.write(f"{self._semicolon_replace(data)}\r\n".encode("ascii"))
    self._serial.flush()

    if not self.prefix_mode:
        return ""  # If prefix mode is off, return empty string immediately

    # Read the response from the laser
    try:
        reply: str = self._serial.readline().decode("ascii").rstrip()
    except UnicodeDecodeError as e:
        logger.error(f"Failed to decode reply from device: {e}")
        raise serial.SerialException(
            f"Failed to decode reply from device: {e}. "
            + "Please check the connection and baudrate settings."
        ) from e

    # Error handling
    if not reply or reply == "":
        logger.error("Empty reply from device")
        raise serial.SerialException(
            "Empty reply from device. Please check the connection and prefix mode."
        )

    if reply[0] != "0":
        logger.error(f"Nonzero return code: {reply[2:]}")
        raise LaserError(
            code=reply[2:6], message=reply[8:]
        )  # Raise a custom error with the reply message
    else:
        logger.debug(f"R {reply}")

    return reply[2:]

close_connection(signum=None, fname=None) -> None

Close the serial connection to the laser driver safely.

Attempts to reset the prefix mode and baudrate to the initial value before closing the connection.

This method is registered to be called on exit or when a signal is received.

Source code in src/pychilaslasers/comm.py

def close_connection(self, signum=None, fname=None) -> None:
    """Close the serial connection to the laser driver safely.

    Attempts to reset the prefix mode and baudrate to the initial value before
    closing the connection.

    This method is registered to be called on exit or when a signal is received.
    """
    if self._serial and self._serial.is_open:
        if signum is not None:
            logger.error(
                f"Received signal {signal.Signals(signum).name} ({signum}):"
                "closing connection"
            )
        else:
            logger.debug("Closing connection")
        self.prefix_mode = True
        self.query("DRV:CYC:ABRT")  # Aborts cycler
        self.query("SYST:STAT 0")  # Turns off system
        self._serial.write(
            f"SYST:SER:BAUD {Constants.TLM_INITIAL_BAUDRATE}\r\n".encode("ascii")
        )  # Resets baud rate to initial value
        logger.debug("Resetting serial baudrate to initial value")
        self._serial.close()

pychilaslasers.comm.list_comports() -> list[str]

List all available COM ports on the system.

serial.tools.list_ports.comports is used to list all available ports. In that regard this method is but a wrapper for it.

Returns:

• list[str] –

  List of available COM ports as strings sorted

• list[str] –

  alphabetically in ascending order.

Referenced by:

• PyChilasLasers Quickstart Guide Initialization

Source code in src/pychilaslasers/comm.py

def list_comports() -> list[str]:
    """List all available COM ports on the system.

    `serial.tools.list_ports.comports` is used to list all available
    ports. In that regard this method is but a wrapper for it.

    Returns:
        List of available COM ports as strings sorted
        alphabetically in ascending order.
    """
    return sorted([port.device for port in serial.tools.list_ports.comports()])