quarchpy 2.1.11.dev4__py3-none-any.whl → 2.2.17.dev1__py3-none-any.whl

quarchpy/device/quarchQPS.py

@@ -1,379 +1,856 @@
+from __future__ import annotations
+import logging
+logger = logging.getLogger(__name__)
+import time
+from io import StringIO
+from typing_extensions import Optional, Union, List, Any, Literal
+import enum
+
+# Third-party imports
+try:
+    import pandas as pd
+except ImportError:
+    pd = None  # type: ignore
+
+# Local application imports
 from quarchpy.device import quarchDevice
-from quarchpy.qps import toQpsTimeStamp
-import os, time, datetime, sys, logging
+from quarchpy.user_interface.user_interface import requestDialog
 
-if sys.version_info[0] < 3:
-    from StringIO import StringIO
-else:
-    from io import StringIO
+def qpsNowStr() -> str:
+    """
+    Gets the current time as milliseconds since the Unix epoch.
 
-current_milli_time = lambda: int (round (time.time() * 1000))
-current_second_time = lambda: int (round (time.time()))
+    Returns:
+        str: The current time as a string representing milliseconds
+             since the epoch.
+    """
+    return str(current_milli_time())
 
-# Using standard Unix time,  milliseconds since the epoch (midnight 1 January 1970 UTC)
-# Should avoid issues with time zones and summer time correction but the local and host
-# clocks should still be synchronised
-def qpsNowStr():
-    return current_milli_time()                          # datetime supports microseconds
 
+# --- Main Classes ---
 
 class quarchQPS(quarchDevice):
-    def __init__(self, quarchDevice):
+    """
+    Represents a Quarch Power Supply (QPS) device, extending quarchDevice.
 
-        self.quarchDevice = quarchDevice
-        self.ConType = quarchDevice.ConType
-        self.ConString = quarchDevice.ConString
+    Handles interaction specific to QPS modules, including stream management.
+    """
+
+    def __init__(self, quarchDevice: quarchDevice):
+        """
+        Initializes the quarchQPS wrapper using an existing quarchDevice object.
 
+        Args:
+            quarchDevice (quarchDevice): An initialized instance of
+                the base quarchDevice class containing connection details.
+
+        Raises:
+            AttributeError: If the provided quarchDevice is not a valid QPS connection.
+        """
+        super().__init__(quarchDevice.ConString, ConType=quarchDevice.ConType)
+        self.quarchDevice = quarchDevice
         self.connectionObj = quarchDevice.connectionObj
-        self.IP_address = quarchDevice.connectionObj.qps.host
-        self.port_number = quarchDevice.connectionObj.qps.port
 
-    def startStream(self, directory, unserInput=True):
+        if not hasattr(self.connectionObj, 'qps'):
+            raise AttributeError("The provided quarchDevice is not a valid QPS connection.")
+        self.IP_address = self.connectionObj.qps.host
+        self.port_number = self.connectionObj.qps.port
+
+    # --- Public API Methods ---
+
+    def start_stream(self, directory: str, user_input: bool = True, stream_duration: str = "") -> 'quarchStream':
+        """
+        Initializes and starts a Quarch data stream.
+
+        This method creates a quarchStream object, which handles the setup
+        and management of the data stream for the QPS application.
+
+        Args:
+            directory (str): The target directory where stream data will be saved.
+            user_input (bool, optional): Controls user interaction on failure.
+                If True (default), prompts the user. If False, raises an
+                Exception on failure.
+            stream_duration (str, optional): Defines the requested duration for the
+                stream. An empty string (default) signifies an indefinite stream.
+
+        Returns:
+            quarchStream: An instance of the quarchStream class representing and
+            managing the active stream.
         """
-        directory - str - desired stream dir
-        unserInput=True - if a failure occurs userInput=True allows user to rectify problem with user input. set to False if user interaction is not available (automating).
+        return quarchStream(self, directory, user_input, stream_duration)
+
+    def startStream(self, directory: str, unserInput: bool = True, streamDuration: str = "") -> 'quarchStream':
         """
-        time.sleep(1) #TODO remove this sleep once script->QPS timeing issue resolved. This works fine in the meantime
-        return quarchStream(self.quarchDevice, directory, unserInput)
+        DEPRECATED: Use start_stream instead.
 
+        Args:
+            directory (str): The target directory where stream data will be saved.
+            unserInput (bool, optional): Controls user interaction on failure.
+            streamDuration (str, optional): Defines the requested duration.
 
+        Returns:
+            quarchStream: An instance of the quarchStream class.
+        """
+        return self.start_stream(directory, unserInput, streamDuration)
 
-    
 
 class quarchStream:
-    def __init__(self, quarchQPS, directory, unserInput=True):
+    """
+    Manages an active data stream from a Quarch QPS device.
+
+    Instantiation automatically attempts to start the stream. Provides methods to
+    control and monitor the stream.
+    """
+
+    def __init__(self, quarchQPS: quarchQPS, directory: str, unserInput: bool = True, streamDuration: str = ""):
+        """
+        Initializes and attempts to start a data stream from the connected device.
+
+        Args:
+            quarchQPS (quarchQPS): The quarchQPS object to stream from.
+            directory (str): The target directory for the stream data.
+            unserInput (bool, optional): Controls user interaction if the initial
+                stream start command fails. Defaults to True.
+            streamDuration (str, optional): Requested stream duration. Defaults to "".
+
+        Raises:
+            Exception: If starting the stream fails and `unserInput` is False.
+        """
         self.connectionObj = quarchQPS.connectionObj
-        self.IP_address = quarchQPS.connectionObj.qps.host
-        self.port_number = quarchQPS.connectionObj.qps.port
+        self.IP_address = quarchQPS.IP_address
+        self.port_number = quarchQPS.port_number
         self.ConString = quarchQPS.ConString
         self.ConType = quarchQPS.ConType
-        time.sleep(1)
-        response = self.startQPSStream(directory)
-        if not "fail:" in response.lower():
-            return
-        else:
+
+        response = self.startQPSStream(directory, streamDuration)
+        if "fail:" in response.lower():
             if unserInput is False:
                 raise Exception(response)
             else:
-                self.failCheck(response)
+                self.failCheck(response, streamDuration)
+
+    # --- Public API Methods ---
+
+    def start_qps_stream(self, new_directory: str, stream_duration: str = "") -> str:
+        """
+        Sends the command to start the QPS stream.
+
+        Args:
+            new_directory (str): The path for the stream data.
+            stream_duration (str, optional): The duration for the stream. Defaults to "".
 
-    def startQPSStream(self, newDirectory):
-        '''STARTS the stream '''
-        response = self.connectionObj.qps.sendCmdVerbose("$start stream \"" + str(newDirectory)+"\"")
+        Returns:
+            str: The response from the QPS system.
+        """
+        command = f'$start stream "{new_directory}" {stream_duration}'.strip()
+        response = self.connectionObj.qps.sendCmdVerbose(command)
+        if "Error" in response:
+            logger.debug("Initial start stream command failed with 'Error', retrying once.")
+            response = self.connectionObj.qps.sendCmdVerbose(command)
         return response
 
-    def failCheck(self, response):
-        ''' handles failed starting of stream that requires input from user to fix.'''
+    def startQPSStream(self, newDirectory: str, streamDuration: str = "") -> str:
+        """
+        DEPRECATED: Use start_qps_stream instead.
+
+        Args:
+            newDirectory (str): The path to the directory where the stream data should be saved.
+            streamDuration (str, optional): The duration for which the stream should run.
+
+        Returns:
+            str: The response message from the QPS system.
+        """
+        return self.start_qps_stream(newDirectory, streamDuration)
+
+    def fail_check(self, response: str, stream_duration: str) -> str:
+        """
+        Handles recoverable failures during stream startup.
+
+        Currently handles "Directory already exists" by prompting for a new name.
+
+        Args:
+            response (str): The failure response message from the server.
+            stream_duration (str): The stream duration, for retrying.
+
+        Returns:
+            str: The successful response after a retry.
+
+        Raises:
+            Exception: If the failure is not a known, handled type.
+        """
         while "fail:" in response.lower():
             if "Fail: Directory already exists" in response:
-                print (response)
-                print("Please enter a new file name:")
-                if sys.version_info.major==3:
-                    newDir = input()
-                else:
-                    newDir = raw_input()
-                response = self.startQPSStream( newDir)
-            else:  #  If its a failure we don't know how to handle.
-                raise Exception(response)
+                new_dir = requestDialog(message=f"{response}\nPlease enter a new file name:")
+                response = self.start_qps_stream(new_dir, stream_duration)
+            else:
+                raise Exception(f"Unhandled QPS stream start failure: {response}")
         return response
 
-    def get_stats(self, format="df"):
+    def failCheck(self, response: str, streamDuration: str) -> str:
+        """
+        DEPRECATED: Use fail_check instead.
+
+        Args:
+            response (str): The response message from a stream start attempt.
+            streamDuration (str): The duration for the stream, needed for retry attempts.
+
+        Returns:
+            str: The successful response message after a retry.
+
+        Raises:
+            Exception: If the response contains an unhandled failure.
+        """
+        return self.fail_check(response, streamDuration)
+
+    def get_stats(self, format: str = "df") -> Union[pd.DataFrame, List[List[str]], None]:
         """
-                      Returns the QPS annotation statistics grid information as a pandas dataframe object
+        Retrieves statistics from the QPS device.
+
+        Args:
+            format (str, optional): The desired output format ("df" for pandas
+                DataFrame, "list" for list of lists). Defaults to "df".
+
+        Returns:
+            Union[pd.DataFrame, List[List[str]], None]: Statistics data in the
+            specified format, or None if pandas is required but not found.
 
-                                  Returns
-                                  -------
-                                  df = : dataframe
-                                      The response text from QPS. If successful "ok. Saving stats to : file_name" otherwise returns the exception thrown
+        Raises:
+            Exception: If the QPS command fails.
         """
         command_response = self.connectionObj.qps.sendCmdVerbose("$get stats", timeout=60).strip()
         if command_response.startswith("Fail"):
             raise Exception(command_response)
 
         if format == "df":
-            try:
-                import warnings
-                warnings.simplefilter(action='ignore', category=FutureWarning)
-                import pandas as pd
-                pd.set_option('display.max_columns', None)
-                pd.set_option('display.width', 1024)
-            except Exception as e:
-                logging.error(e)
-                logging.warning("pandas not imported correctly. Continuing")
-                pass
+            if pd is None:
+                logger.error("Pandas is not installed, cannot return DataFrame.")
+                return None
+
             test_data = StringIO(command_response)
-            retVal = pd.read_csv(test_data, sep=",", header=[0, 1], error_bad_lines=False)
-        elif format == "list":
-            retVal = []
-            for line in command_response.replace("\r\n","\n").split("\n"):
-                row = []
-                for element in line.split(","):
-                    row.append(element)
-                retVal.append(row)
 
-        return retVal
+            df = pd.read_csv(test_data, sep=",", header=[0, 1], on_bad_lines="skip")
 
+            return df
 
-    def stats_to_CSV(self, file_name=""):
-        """
-        Saves the statistics grid to a csv file
+        elif format == "list":
+            ret_val = []
+            for line in command_response.replace("\r\n", "\n").split("\n"):
+                row = [element for element in line.split(",")]
+                ret_val.append(row)
+            return ret_val
 
-                    Parameters
-                    ----------
-                    file-name= : str, optional
-                        The absolute path of the file you would like to save the csv to. If left empty then a filename will be give.
-                        Default location is the path of the executable.
-                    Returns
-                    -------
-                    command_response : str or None
+        return None
 
-                        The response text from QPS. If successful "ok. Saving stats to : file_name" otherwise returns the exception thrown
+    def stats_to_csv(self, file_name: str = "", poll_till_complete: bool = False,
+                     check_interval: float = 0.5, timeout: int = 60) -> str:
         """
-        command_response = self.connectionObj.qps.sendCmdVerbose("$stats to csv \""+file_name+"\"", timeout=60)
+        Commands the QPS device to save its current statistics to a CSV file.
+
+        Args:
+            file_name (str, optional): Absolute path for the CSV file on the QPS
+                device's filesystem. Defaults to "".
+            poll_till_complete (bool, optional): If True, waits for the export
+                to finish. Defaults to False.
+            check_interval (float, optional): Seconds between status checks when
+                polling. Defaults to 0.5.
+            timeout (int, optional): Max seconds to wait for polling to complete.
+                Defaults to 60.
+
+        Returns:
+            str: The initial response from the QPS device.
+
+        Raises:
+            Exception: If the initial QPS command fails.
+            TimeoutError: If polling is enabled and times out.
+        """
+        cmd = f'$stats to csv "{file_name}"'
+        command_response = self.connectionObj.qps.sendCmdVerbose(cmd, timeout=60)
+
         if command_response.startswith("Fail"):
             raise Exception(command_response)
+
+        if poll_till_complete:
+            start_time = time.monotonic()
+            while check_export_status(self.get_stats_export_status()):
+                if (time.monotonic() - start_time) > timeout:
+                    raise TimeoutError(f"QPS CSV Export of stats timed out after {timeout} seconds")
+                time.sleep(check_interval)
+
         return command_response
 
-    def get_custom_stats_range(self, start_time, end_time):
-        """
-                      Returns the QPS statistics information over a specific time ignoring any set annotations.
-
-                                Parameters
-                                ----------
-                                start_time = : str
-                                    The time in seconds you would like the stats to start this can be in integer or string format.
-                                    or using the following format to specify daysDhours:minutes:seconds.milliseconds
-                                    xxxDxx:xx:xx.xxxx
-                                end_time = : str
-                                    The time in seconds you would like the stats to stop this can be in integer or string format
-                                    or using the following format to specify daysDhours:minutes:seconds.milliseconds
-                                    xxxDxx:xx:xx.xxxx
-                                Returns
-                                -------
-                                df = : dataframe
-                                    The response text from QPS. If successful "ok. Saving stats to : file_name" otherwise returns the exception thrown
+    def stats_to_CSV(self, file_name: str = "", poll_till_complete: bool = False,
+                     check_interval: float = 0.5, timeout: int = 60) -> str:
         """
-        try:
-            import warnings
-            warnings.simplefilter(action='ignore', category=FutureWarning)
-            import pandas as pd
-            pd.set_option('max_columns', None)
-            pd.set_option('display.width', 1024)
-        except:
-            logging.warning("pandas not imported correctly")
-            pass
-        command_response = self.connectionObj.qps.sendCmdVerbose("$get custom stats range " + str(start_time)+ " " + str(end_time), timeout=60)
+        DEPRECATED: Use stats_to_csv instead.
+
+        Args:
+            file_name (str, optional): The absolute path for the CSV file. Defaults to "".
+            poll_till_complete (bool, optional): If True, polls until the export is
+                finished. Defaults to False.
+            check_interval (float, optional): Time in seconds between status checks
+                when polling. Defaults to 0.5.
+            timeout (int, optional): Max time in seconds to wait for polling. Defaults to 60.
+
+        Returns:
+            str: The initial response message from the QPS device.
+        """
+        return self.stats_to_csv(file_name, poll_till_complete, check_interval, timeout)
+
+    def get_custom_stats_range(self, start_time: Union[int, str], end_time: Union[int, str]) -> Optional[pd.DataFrame]:
+        """
+        Retrieves statistics from the QPS device for a specified time range.
+
+        Args:
+            start_time (Union[int, str]): The start time for stats calculation.
+            end_time (Union[int, str]): The end time for stats calculation.
+
+        Returns:
+            Optional[pd.DataFrame]: A DataFrame containing the stats.
+
+        Raises:
+            ImportError: If the pandas library is not installed.
+            Exception: If the QPS command fails or data parsing fails.
+        """
+        if pd is None:
+            logger.warning("pandas not imported correctly. Required for get_custom_stats_range.")
+            raise ImportError("pandas library is required for get_custom_stats_range")
+
+        command_response = self.connectionObj.qps.sendCmdVerbose(
+            f"$get custom stats range {start_time} {end_time}", timeout=60)
+
         if command_response.startswith("Fail"):
             raise Exception(command_response)
+
         test_data = StringIO(command_response)
         try:
-            df = pd.read_csv(test_data, sep=",", header=[0,1])
+            df = pd.read_csv(test_data, sep=",", header=[0, 1], on_bad_lines="skip")
         except Exception as e:
-            logging.error("Unable to create pandas data frame from command response :" + str(command_response))
+            logger.error(f"Unable to create pandas data frame from command response: {command_response}")
             raise e
         return df
 
-    def takeSnapshot(self):
+    def take_snapshot(self) -> str:
         """
-                      Triggers QPS take snapshot function and saves it in the streams directory.
+        Triggers the QPS device to capture an immediate snapshot.
+
+        Returns:
+            str: The response from the QPS device.
+
+        Raises:
+            Exception: If the command fails.
         """
         command_response = self.connectionObj.qps.sendCmdVerbose("$take snapshot")
         if command_response.startswith("Fail"):
             raise Exception(command_response)
-        return(command_response)
+        return command_response
 
-    def getStreamState(self):
+    def takeSnapshot(self) -> str:
         """
-                      Askes QPS for the stream status.
-                      QPS stream state != Module stream state.
-                      This is different from "rec stream?" cmd to the module as it will return "streaming" when the module is nolonger streaming but QPS is still receiveing stream data from the module.
-                      ei the module has stopped streaming but is emptying the stream buffer.
+        DEPRECATED: Use take_snapshot instead.
+
+        Returns:
+            str: The response message from the QPS device.
+        """
+        return self.take_snapshot()
+
+    def get_stream_state(self) -> str:
+        """
+        Queries the QPS application for its current stream processing state.
+
+        Returns:
+            str: The stream state as reported by the QPS application.
+
+        Raises:
+            Exception: If the command fails.
         """
         command_response = self.connectionObj.qps.sendCmdVerbose("$stream state")
         if command_response.startswith("Fail"):
             raise Exception(command_response)
-        return(command_response)
-
-    def addAnnotation(self, title, annotationTime = 0, extraText="", yPos="", titleColor ="", annotationColor = "", annotationType = "", annotationGroup =""):
-        """
-                    Adds a custom annotation to stream with given parameters.
-
-                    Parameters
-                    ----------
-                    title= : str
-                        The title appears next to the annotation in the stream
-                    extraText= : str, optional
-                        The additional text that can be viewed when selecting the annotation
-                    yPos : str, optional
-                        The percetange of how high up the screen the annotation should appear 0 is the bottom and 100 the top
-                    titleColor : str, optional
-                        The color of the text next to the annotation in hex format 000000 to FFFFFF
-                    annotationColor : str, optional
-                        The color of the annotation marker in hex format 000000 to FFFFFF
-                    annotationGroup : str, optional
-                        The group the annotation belongs to
-                    annotationTime : int, optional
-                        The time in milliseconds after the start of the stream at which the annotation should be placed. 0 will plot the annotation live at the most recent sample
-
-                    Returns
-                    -------
-                    command_response : str or None
-
-                        The response text from QPS. "ok" if annotation successfully added
-            """
-        annotationTime = str(annotationTime)
-        annotationType = annotationType.lower()
-        if annotationType == "" or annotationType == "annotation":
-            annotationType = "annotate"
-        elif annotationType == "comment":
-            pass # already in the correct format for command
-        else:
-            retString = "Fail annotationType must be 'annotation' or 'comment'"
-            logging.warning(retString)
-            return retString
+        return command_response
 
-        # If the function has already been passed the XML string to give to QPS
-        if ("<<" in title.replace(" ", "")):
-            annotationString = str(title)
-        else:
-            annotationString = "<"
+    def getStreamState(self) -> str:
+        """
+        DEPRECATED: Use get_stream_state instead.
 
-            if annotationTime == "0":
-                # Use current time
-                annotationTime = qpsNowStr()
-            elif(annotationTime.startswith("e")):
-                pass
-            else:
-                # Convert timestamp to QPS format
-                annotationTime = toQpsTimeStamp(annotationTime)
-
-            if title != "":
-                annotationString += "<text>" + str(title) + "</text>"
-            if extraText != "":
-                annotationString += "<extraText>" + str(extraText) + "</extraText>"
-            if yPos != "":
-                annotationString += "<yPos>" + str(yPos) + "</yPos>"
-            if titleColor != "":
-                annotationString += "<textColor>" + str(titleColor) + "</textColor>"
-            if annotationColor != "":
-                annotationString += "<color>" + str(annotationColor) + "</color>"
-            if annotationGroup != "":
-                annotationString += "<userType>" + str(annotationGroup) + "</userType>"
-            annotationString += ">"
-
-        # command is sent on newline so \n needs to be chnaged to \\n which is changed back just before printing in qps.
-        annotationString = annotationString.replace("\n", "\\n")
-        logging.debug("Time sending to QPS:" + str(annotationTime))
-        return self.connectionObj.qps.sendCmdVerbose("$" +annotationType+" "+str(annotationTime)+" "+annotationString)
-
-    def addComment(self, title, commentTime = 0, extraText="", yPos="", titleColor ="", commentColor = "", annotationType = "", annotationGroup =""):
-        #Comments are just annotations that do not affect the statistics grid.
-        #This function was kept to be backwards compatible and is a simple pass through to add annotation.
-        if annotationType == "":
-            annotationType = "comment"
-        return self.addAnnotation(title = title, annotationTime=commentTime, extraText=extraText, yPos=yPos, titleColor=titleColor, annotationColor=commentColor, annotationType=annotationType, annotationGroup=annotationGroup)
-
-    def saveCSV(self,filePath, linesPerFile=None, cr=None, delimiter=None, timeout=60):
-        """
-            Saves the stream to csv file at specified location
-
-            Parameters
-            ----------
-            filePath= : str
-                The file path that ou would like the CSV file saved to.
-            linesPerFile= : str, optional
-                    The number of lines per CSV file. Can be any int number or "all"
-            cr : bool, optional
-                Whether the end of line terminator should include a carriage return.
-            delimiter : str, optional
-                The delimiter to be used by the csv file.
-            timeout : str, otptional
-                The timeout to wait for a response from QPS
-
-            Returns
-            -------
-            command_response : str or None
-                The response text from QPS. "ok" if command is successful or the stack trace if exception thrown
+        Returns:
+            str: The stream state reported by the QPS application.
+        """
+        return self.get_stream_state()
+
+    def add_annotation(self, title: str, annotation_time: Union[int, str] = 0, extra_text: str = "",
+                       y_pos: Union[int, str] = "",
+                       title_color: str = "", annotation_color: str = "", annotation_type: str = "annotate",
+                       time_format: str = "unix") -> str:
+        """
+        Adds a custom annotation marker to the active QPS stream.
+
+        Args:
+            title (str): The primary text label for the annotation.
+            annotation_time (Union[int, str], optional): When the annotation appears. Defaults to 0 ("now").
+            extra_text (str, optional): Additional text for the annotation. Defaults to "".
+            y_pos (Union[int, str], optional): Vertical position (0-100). Defaults to "".
+            title_color (str, optional): Hex color for the title. Defaults to "".
+            annotation_color (str, optional): Hex color for the marker. Defaults to "".
+            annotation_type (str, optional): "annotate" or "comment". Defaults to "annotate".
+            time_format (str, optional): "unix" or "elapsed". Defaults to "unix".
+
+        Returns:
+            str: The response message from the QPS device.
+        """
+        time_val = str(annotation_time)
+        if any(c.isalpha() for c in time_val):
+            time_format = "elapsed"
+            if time_val.startswith("e"):
+                time_val = time_val[1:] + "s"
+        elif time_val == "0":
+            time_val = qpsNowStr()
+            time_format = "unix"
+
+        title = title.replace("\n", "\\n")
+        extra_text = extra_text.replace("\n", "\\n")
+
+        cmd = f'$stream annotation add time={time_val} text="{title}"'
+        if extra_text:
+            cmd += f' extraText="{extra_text}"'
+        if y_pos != "":
+            cmd += f' yPos={y_pos}'
+        if annotation_type:
+            cmd += f' type={annotation_type}'
+        if annotation_color:
+            cmd += f' colour={annotation_color}'
+        if title_color:
+            cmd += f' textColour={title_color}'
+        if time_format:
+            cmd += f' timeFormat={time_format}'
+
+        return self.connectionObj.qps.sendCmdVerbose(cmd)
+
+    def addAnnotation(self, title: str, annotationTime: Union[int, str] = 0, extraText: str = "",
+                      yPos: Union[int, str] = "",
+                      titleColor: str = "", annotationColor: str = "", annotationType: str = "",
+                      annotationGroup: str = "", timeFormat: str = "unix") -> str:
+        """
+        DEPRECATED: Use add_annotation instead.
+
+        Args:
+            title (str): The primary text label for the annotation.
+            annotationTime (Union[int, str], optional): Timestamp. Defaults to 0 ("now").
+            extraText (str, optional): Additional text. Defaults to "".
+            yPos (Union[int, str], optional): Vertical position (0-100). Defaults to "".
+            titleColor (str, optional): Hex color for the title. Defaults to "".
+            annotationColor (str, optional): Hex color for the marker. Defaults to "".
+            annotationType (str, optional): "annotate" or "comment". Defaults to "".
+            annotationGroup (str, optional): Not used. Defaults to "".
+            timeFormat (str, optional): "unix" or "elapsed". Defaults to "unix".
+
+        Returns:
+            str: The response message from the QPS device.
+        """
+        current_type = annotationType.lower()
+        if current_type == "" or current_type == "annotation":
+            current_type = "annotate"
+
+        return self.add_annotation(title, annotation_time=annotationTime, extra_text=extraText, y_pos=yPos,
+                                   title_color=titleColor, annotation_color=annotationColor,
+                                   annotation_type=current_type, time_format=timeFormat)
+
+    def add_comment(self, title: str, comment_time: Union[int, str] = 0, **kwargs: Any) -> str:
+        """
+        Adds a 'comment' type annotation to the QPS stream.
+
+        This is a convenience wrapper for `add_annotation` that sets the type to 'comment'.
+
+        Args:
+            title (str): The text label for the comment.
+            comment_time (Union[int, str], optional): The timestamp. Defaults to 0.
+            **kwargs: Other arguments accepted by `add_annotation`.
+
+        Returns:
+            str: The response message from the QPS device.
+        """
+        kwargs['annotation_type'] = 'comment'
+        return self.add_annotation(title, annotation_time=comment_time, **kwargs)
+
+    def addComment(self, title: str, commentTime: Union[int, str] = 0, extraText: str = "", yPos: Union[int, str] = "",
+                   titleColor: str = "", commentColor: str = "", annotationType: str = "",
+                   annotationGroup: str = "", timeFormat: str = "unix") -> str:
+        """
+        DEPRECATED: Use add_comment instead.
+
+        Args:
+            title (str): The text label for the comment.
+            commentTime (Union[int, str], optional): The timestamp. Defaults to 0.
+            extraText (str, optional): Additional text. Defaults to "".
+            yPos (Union[int, str], optional): Vertical position (0-100). Defaults to "".
+            titleColor (str, optional): Hex color for the title. Defaults to "".
+            commentColor (str, optional): Hex color for the comment marker. Defaults to "".
+            annotationType (str, optional): Overridden to 'comment'. Defaults to "".
+            annotationGroup (str, optional): Not used. Defaults to "".
+            timeFormat (str, optional): "unix" or "elapsed". Defaults to "unix".
+
+        Returns:
+            str: The response message from the QPS device.
+        """
+        return self.add_comment(title, comment_time=commentTime, extraText=extraText, yPos=yPos,
+                                titleColor=titleColor, commentColor=commentColor,
+                                timeFormat=timeFormat)
+
+    def save_csv(self, file_path: str, lines_per_file: Optional[Union[int, str]] = None, use_cr: Optional[bool] = None,
+                 delimiter: Optional[str] = None, timeout: int = 180, poll_till_complete: bool = False,
+                 check_interval: float = 0.5) -> str:
+        """
+        Commands the QPS device to save the stream data to a CSV file.
+
+        Args:
+            file_path (str): Target file path on the QPS device's filesystem.
+            lines_per_file (Optional[Union[int, str]], optional): Max lines per file. Defaults to None.
+            use_cr (Optional[bool], optional): True for CRLF, False for LF. Defaults to None.
+            delimiter (Optional[str], optional): Field delimiter for the CSV. Defaults to None.
+            timeout (int, optional): Timeout in seconds. Defaults to 180.
+            poll_till_complete (bool, optional): If True, waits for export to finish. Defaults to False.
+            check_interval (float, optional): Seconds between status checks when polling. Defaults to 0.5.
+
+        Returns:
+            str: The initial response from the QPS device.
+
+        Raises:
+            TimeoutError: If polling is enabled and the export does not complete in time.
         """
         args = ""
+        if lines_per_file is not None:
+            args += f" -l{lines_per_file}"
+        if use_cr is not None:
+            args += " -cyes" if use_cr else " -cno"
+        if delimiter is not None:
+            args += f" -s{delimiter}"
+
+        command = f'$save csv "{file_path}" {args}'.strip()
+        command_response = self.connectionObj.qps.sendCmdVerbose(command, timeout=timeout)
+
+        if poll_till_complete:
+            start_time = time.monotonic()
+            while check_export_status(self.get_stream_export_status()):
+                if (time.monotonic() - start_time) > timeout:
+                    raise TimeoutError(f"Stream export to CSV timed out after {timeout} seconds")
+                logger.debug("Waiting for stream export to complete...")
+                time.sleep(check_interval)
 
-        if linesPerFile != None:
-            args +=" -l" + str(linesPerFile)
-        if cr !=None:
-            if cr is True:
-                args+= " -cyes"
-            elif cr is False:
-                args += " -cno"
-        if delimiter !=None:
-            args += " -s"+delimiter
+        return command_response
+
+    def saveCSV(self, filePath: str, linesPerFile: Optional[Union[int, str]] = None, cr: Optional[bool] = None,
+                delimiter: Optional[str] = None, timeout: int = 180, pollTillComplete: bool = False,
+                checkInterval: float = 0.5) -> str:
+        """
+        DEPRECATED: Use save_csv instead.
+
+        Args:
+            filePath (str): The target file path on the QPS device's filesystem.
+            linesPerFile (Optional[Union[int, str]], optional): Max lines per file. Defaults to None.
+            cr (Optional[bool], optional): True for CRLF, False for LF line endings. Defaults to None.
+            delimiter (Optional[str], optional): Field delimiter for the CSV. Defaults to None.
+            timeout (int, optional): Timeout in seconds. Defaults to 180.
+            pollTillComplete (bool, optional): If True, waits for export to finish. Defaults to False.
+            checkInterval (float, optional): Seconds between status checks when polling. Defaults to 0.5.
+
+        Returns:
+            str: The initial response from the QPS device.
+        """
+        return self.save_csv(filePath, linesPerFile, cr, delimiter, timeout, pollTillComplete, checkInterval)
 
-        #, filePath, linesPerFile, cr, delimiter
-        return self.connectionObj.qps.sendCmdVerbose("$save csv \"" + filePath + "\" " + args, timeout=timeout)
+    def create_channel(self, channel_name: str, channel_group: str, base_units: str, use_prefix: bool) -> str:
+        """
+        Creates a new custom data channel on the QPS device.
 
-    def createChannel(self, channelName, channelGroup, baseUnits, usePrefix):
-        #Conditions to convert false / true inputs to specification input
-        if usePrefix == False: 
-            usePrefix = "no"
-        if usePrefix == True:
-            usePrefix = "yes"
+        Args:
+            channel_name (str): The name for the new channel.
+            channel_group (str): The group to associate the channel with (e.g., "Voltage").
+            base_units (str): The fundamental unit for the channel (e.g., "V", "A").
+            use_prefix (bool): If True, allows channel prefixes (e.g., 'm' for milli).
 
-        return self.connectionObj.qps.sendCmdVerbose("$create channel " + channelName + " " + channelGroup  + " " + baseUnits + " " + usePrefix)
+        Returns:
+            str: The response from the QPS device.
+        """
+        prefix_str = "yes" if use_prefix else "no"
+        command = f"$create channel {channel_name} {channel_group} {base_units} {prefix_str}"
+        return self.connectionObj.qps.sendCmdVerbose(command)
 
-    def hideChannel(self, channelSpecifier):
-        return self.connectionObj.qps.sendCmdVerbose("$hide channel " + channelSpecifier)
+    def createChannel(self, channelName: str, channelGroup: str, baseUnits: str, usePrefix: bool) -> str:
+        """
+        DEPRECATED: Use create_channel instead.
 
-    def showChannel(self, channelSpecifier):
-        return self.connectionObj.qps.sendCmdVerbose("$show channel " + channelSpecifier)
+        Args:
+            channelName (str): The name for the new channel.
+            channelGroup (str): The group to associate the channel with.
+            baseUnits (str): The fundamental unit for the channel.
+            usePrefix (bool): If True, allows channel prefixes.
 
-    def myChannels(self):
-        return self.connectionObj.qps.sendCmdVerbose("$channels")
+        Returns:
+            str: The response message from the QPS device.
+        """
+        return self.create_channel(channelName, channelGroup, baseUnits, usePrefix)
+
+    def hide_channel(self, channel_specifier: str) -> str:
+        """
+        Hides a specified channel from the QPS stream view.
+
+        Args:
+            channel_specifier (str): The identifier of the channel to hide (e.g., "5v:voltage").
+
+        Returns:
+            str: The response from the QPS device.
+        """
+        return self.connectionObj.qps.sendCmdVerbose(f"$hide channel {channel_specifier}")
+
+    def hideChannel(self, channelSpecifier: str) -> str:
+        """
+        DEPRECATED: Use hide_channel instead.
+
+        Args:
+            channelSpecifier (str): The identifier of the channel to hide.
+
+        Returns:
+            str: The response message from the QPS device.
+        """
+        return self.hide_channel(channelSpecifier)
+
+    def show_channel(self, channel_specifier: str) -> str:
+        """
+        Shows (un-hides) a specified channel in the QPS stream view.
 
-    def channels(self):
+        Args:
+            channel_specifier (str): The identifier of the channel to show.
+
+        Returns:
+            str: The response from the QPS device.
+        """
+        return self.connectionObj.qps.sendCmdVerbose(f"$show channel {channel_specifier}")
+
+    def showChannel(self, channelSpecifier: str) -> str:
+        """
+        DEPRECATED: Use show_channel instead.
+
+        Args:
+            channelSpecifier (str): The identifier of the channel to show.
+
+        Returns:
+            str: The response message from the QPS device.
+        """
+        return self.show_channel(channelSpecifier)
+
+    def channels(self) -> List[str]:
+        """
+        Retrieves the list of available channels from QPS, split into a list of strings.
+
+        Returns:
+            list[str]: A list where each element is a channel identifier string.
+        """
         return self.connectionObj.qps.sendCmdVerbose("$channels").splitlines()
-             
-    def stopStream(self):
-        return self.connectionObj.qps.sendCmdVerbose("$stop stream")
-
-    def stopStreamAndAllowBufferToEmpty(self, checkInterval=0.5):
-        self.stopStream()
-        streamState = self.getStreamState().lower()
-        while "running" in streamState:
-            logging.debug("Stream buffer still emptying: "+ streamState)
-            time.sleep(checkInterval)
-            streamState = self.getStreamState().lower()
-        logging.debug("QPS no longer Streaming: " + streamState)
-
-    def hideAllDefaultChannels(self):
-    	
-    	#TODO query QPS / Device for all channel names and hide all of them
-    	#All Default Channels
-        self.hideChannel ("3.3v:voltage")
-        self.hideChannel ("3v3:voltage")
-        self.hideChannel ("5v:voltage")
-        self.hideChannel ("12v:voltage")
-        self.hideChannel ("3v3:current")
-        self.hideChannel ("3.3v:current")
-        self.hideChannel ("5v:current")
-        self.hideChannel ("12v:current")
-        self.hideChannel ("3v3:power")
-        self.hideChannel ("3.3v:power")
-        self.hideChannel ("5v:power")
-        self.hideChannel ("12v:power")
-        self.hideChannel ("tot:power")
-        #Default PAM channels
-        self.hideChannel ("perst#:digital")
-        self.hideChannel ("wake#:digital")
-        self.hideChannel ("lkreq#:digital")
-        self.hideChannel ("smclk:digital")
-        self.hideChannel ("smdat:digital")
-    
-    #function to add a data point the the stream
-    #time value will default to current time if none passed
-    def addDataPoint(self, channelName, groupName, dataValue, dataPointTime = 0):
-        if dataPointTime == 0:
-            dataPointTime = qpsNowStr()
+
+    def myChannels(self) -> str:
+        """
+        DEPRECATED: Use channels instead.
+
+        Retrieves the list of available channels from QPS as a single raw string.
+
+        Returns:
+            str: The raw response string from the QPS '$channels' command.
+        """
+        return self.connectionObj.qps.sendCmdVerbose("$channels")
+
+    def hide_all_default_channels(self) -> None:
+        """
+        Hides a predefined list of common default QPS/PAM channels.
+
+        Note:
+            This list is hardcoded and might not be exhaustive for all hardware.
+        """
+        default_channels = [
+            "3.3v:voltage", "3v3:voltage", "5v:voltage", "12v:voltage",
+            "3.3v:current", "3v3:current", "5v:current", "12v:current",
+            "3.3v:power", "3v3:power", "5v:power", "12v:power", "tot:power",
+            "perst#:digital", "wake#:digital", "clkreq#:digital",
+            "smclk:digital", "smdat:digital"
+        ]
+        for channel in default_channels:
+            try:
+                self.hide_channel(channel)
+            except Exception as e:
+                logger.warning(f"Failed to hide default channel '{channel}': {e}")
+
+    def hideAllDefaultChannels(self) -> None:
+        """
+        DEPRECATED: Use hide_all_default_channels instead.
+
+        Hides a predefined list of common default QPS/PAM channels.
+        """
+        self.hide_all_default_channels()
+
+    def add_data_point(self, channel_name: str, group_name: str, data_value: Union[int, float],
+                       data_point_time: Union[int, str] = 0, time_format: str = "unix") -> None:
+        """
+        Adds a single data point to a specified custom channel.
+
+        Args:
+            channel_name (str): The name of the custom channel.
+            group_name (str): The group associated with the channel.
+            data_value (Union[int, float]): The numeric value of the data point.
+            data_point_time (Union[int, str], optional): Timestamp for the data point.
+                Defaults to 0 (current time).
+            time_format (str, optional): "unix" or "elapsed". Defaults to "unix".
+        """
+        if data_point_time == 0:
+            timestamp = qpsNowStr()
+            time_format = "unix"
         else:
-            dataPointTime = toQpsTimeStamp (dataPointTime)
+            timestamp = str(data_point_time)
+
+        command = (f"$stream data add {channel_name} {group_name} "
+                   f"{timestamp} {data_value} {time_format}")
+
+        self.connectionObj.qps.sendCmdVerbose(command)
+
+    def addDataPoint(self, channelName: str, groupName: str, dataValue: Union[int, float],
+                     dataPointTime: Union[int, str] = 0, timeFormat: str = "unix") -> None:
+        """
+        DEPRECATED: Use add_data_point instead.
+
+        Adds a single data point to a specified custom channel in the QPS stream.
+
+        Args:
+            channelName (str): The name of the custom channel to add data to.
+            groupName (str): The group associated with the channel (must match creation).
+            dataValue (int or float): The numeric value of the data point.
+            dataPointTime (int or str, optional): The timestamp for the data point.
+            timeFormat (str, optional): The format of the given time ["elapsed"|"unix"].
+        """
+        self.add_data_point(channelName, groupName, dataValue, dataPointTime, timeFormat)
+
+    def get_stream_export_status(self) -> str:
+        """
+        Queries the QPS device for the status of the main stream data export process.
+
+        Returns:
+            str: The response string from QPS indicating the stream export status
+        """
+        return self.connectionObj.qps.sendCmdVerbose("$stream export status")
+
+    def get_stats_export_status(self) -> str:
+        """
+        Queries the QPS device for the status of the statistics data export process.
+
+        Returns:
+            str: The response string from QPS indicating the stats export status
+        """
+        return self.connectionObj.qps.sendCmdVerbose("$stream stats export status")
+
+    def stop_stream(self, poll_till_complete: bool = False, check_interval: float = 0.1, timeout: int = 60) -> Literal[Status.OVERRUN, Status.STOPPED] | Any:
+        """
+        Sends the command to stop the QPS data stream.
 
-        #print ("printing command:  $log " + channelName + " " + groupName + " " + str(dataPointTime) + " " + str(dataValue))
-        self.connectionObj.qps.sendCmdVerbose("$log " + channelName + " " + groupName + " " + str(dataPointTime) + " " + str(dataValue))
+        Args:
+            poll_till_complete (bool, optional): If True, waits for the stream to fully stop. Defaults to False.
+            check_interval (float, optional): Seconds between status checks when polling. Defaults to 0.1.
+            timeout (int, optional): Max seconds to wait for polling to complete. Defaults to 60.
+
+        Returns:
+            str: The final stream status if polling, otherwise the initial command response.
+
+        Raises:
+            Exception: If the stop command itself fails.
+            TimeoutError: If polling is enabled and times out.
+        """
+        response = self.connectionObj.qps.sendCmdVerbose("$stop stream")
+        if response.startswith("Fail"):
+            raise Exception(response)
+
+        if poll_till_complete:
+            start_time = time.monotonic()
+            while True:
+                stream_state = self.get_stream_state().lower()
+                is_stopped = check_stream_stopped_status(stream_state)
+                if is_stopped:
+                    return is_stopped
+
+                if (time.monotonic() - start_time) > timeout:
+                    raise TimeoutError(f"Timeout ({timeout}s) waiting for stream to stop. Last state: {stream_state}")
+
+                logger.debug(f"Stream buffer still emptying: {stream_state}")
+                time.sleep(check_interval)
+
+        return response
+
+    def stopStream(self, pollTillComplete: bool = False, checkInterval: float = 0.1, timeout: int = 60) -> str:
+        """
+        DEPRECATED: Use stop_stream instead.
+
+        Args:
+            pollTillComplete (bool, optional): If True, waits until the QPS stream
+                                               state is no longer "running". Defaults to False.
+            checkInterval (float, optional): Time in seconds between status checks
+                                             when polling. Defaults to 0.1.
+            timeout (int, optional): Maximum time in seconds to wait. Defaults to 60.
+
+        Returns:
+            str: The final checked stream status string ("STOPPED", "OVERRUN") if polling,
+                 otherwise the initial response from the '$stop stream' command.
+        """
+        return self.stop_stream(pollTillComplete, checkInterval, timeout)
+
+
+# -------------------------------------
+#  Constants/Enums
+# -------------------------------------
+class Status(enum.Enum):
+    IN_PROGRESS = "IN PROGRESS"
+    COMPLETE = "COMPLETE"
+    STOPPED = "STOPPED"
+    OVERRUN = "OVERRUN"
+    OK = "OK"
+
+
+# -------------------------------------
+#  API Utility Functions
+# -------------------------------------
+def current_milli_time():
+    return int(round(time.time() * 1000))
+
+
+def current_second_time():
+    return int(round(time.time()))
+
+
+# -------------------------------------
+#  Stream API Utility Functions
+# -------------------------------------
+def check_stream_status(stream_status):
+    # Check the stream status, so we know if anything went wrong during the capture period
+    if "stopped" in stream_status:
+        if "overrun" in stream_status:
+            return '\tStream interrupted due to internal device buffer has filled up'
+        elif "user" in stream_status:
+            return '\tStream interrupted due to max file size has being exceeded'
+        else:
+            return "\tStopped for unknown reason"
+    return "\t Stream running"
+
+
+def check_stream_stopped_status(stream_status):
+    # Check the stream status, so we know if anything went wrong during the capture period
+    if "stopped" in stream_status:
+        if "overrun" in stream_status:
+            logger.warning('Stream interrupted due to internal device buffer has filled up')
+            return Status.OVERRUN
+        else:
+            return Status.STOPPED
+    return Status.IN_PROGRESS
+
+
+# -------------------------------------
+#  QPS API Utility Functions
+# -------------------------------------
+def check_export_status(export_status):
+    if export_status == Status.COMPLETE:
+        return True
+    elif export_status == Status.IN_PROGRESS:
+        return False
+    return False