sertools 0.1.0__tar.gz

sertools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Doar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sertools-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: sertools
+Version: 0.1.0
+Summary: Interface for serial devices using pyserial.
+Author-email: Jason Doar <jbdoar@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jbdoar/sertools
+Project-URL: Issues, https://github.com/jbdoar/sertools/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial
+Requires-Dist: readchar
+Dynamic: license-file
+
+# sertools
+
+Interface for serial devices using pyserial.
+
+## Installation
+
+```bash
+pip install sertools
+```
+
+## Features
+- Query method with flexible configuration parameters for various response formats.
+- Lightweight serial port terminal emulator.
+
+## Usage
+The SerialDevice instance may be called with a command string to send to the serial port and optional readback/terminator parameters.
+
+```python
+from sertools import SerialDevice
+ser = SerialDevice()
+ser('HELP')
+```
+
+## Development
+```bash
+git clone https://github.com/jbdoar/sertools
+cd sertools
+pip install -e .
+```

sertools-0.1.0/README.md

@@ -0,0 +1,29 @@
+# sertools
+
+Interface for serial devices using pyserial.
+
+## Installation
+
+```bash
+pip install sertools
+```
+
+## Features
+- Query method with flexible configuration parameters for various response formats.
+- Lightweight serial port terminal emulator.
+
+## Usage
+The SerialDevice instance may be called with a command string to send to the serial port and optional readback/terminator parameters.
+
+```python
+from sertools import SerialDevice
+ser = SerialDevice()
+ser('HELP')
+```
+
+## Development
+```bash
+git clone https://github.com/jbdoar/sertools
+cd sertools
+pip install -e .
+```

sertools-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+# pyproject.toml
+
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sertools"
+version = "0.1.0"
+description = "Interface for serial devices using pyserial."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{name = "Jason Doar", email = "jbdoar@gmail.com"}]
+dependencies = ["pyserial", "readchar"]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.urls]
+Homepage = "https://github.com/jbdoar/sertools"
+Issues = "https://github.com/jbdoar/sertools/issues"
+
+[project.scripts]
+# serial terminal emulator
+sterm = "sertools.scripts.sterm:main"
+
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

sertools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sertools-0.1.0/src/sertools/__init__.py

@@ -0,0 +1,3 @@
+from .serial_device import SerialDevice
+
+__all__ = ["SerialDevice"]

sertools-0.1.0/src/sertools/scripts/sterm.py

@@ -0,0 +1,125 @@
+import argparse
+import logging
+import sys
+import threading
+
+import readchar
+
+import sertools
+
+
+log = logging.getLogger('sertools')
+
+
+def configure_logging(logfile=None):
+    """
+    """
+    log.setLevel(logging.INFO)
+    log.handlers.clear()
+    log.propagate = False
+
+    if logfile:
+        file_handler = logging.FileHandler(logfile, encoding='utf-8')
+        file_handler.setLevel(logging.INFO)
+        file_handler.setFormatter(logging.Formatter('%(asctime)s %(message)s', datefmt='%Y-%m-%d %H:%M%S'))
+        log.addHandler(file_handler)
+
+
+def reader(ser, stop_event):
+    """
+    """
+    buf = bytearray()
+
+    while not stop_event.is_set():
+        try:
+            n = ser.ser.in_waiting
+            data = ser.ser.read(n or 1)
+        except Exception:
+            break
+
+        if not data:
+            continue
+
+        text = data.decode(ser.encoding, errors='replace')
+        sys.stdout.write(text)
+        sys.stdout.flush()
+
+        buf.extend(data)
+
+        while True:
+            i_crlf = buf.find(b'\r\n')
+            i_cr = buf.find(b'\r')
+            i_lf = buf.find(b'\n')
+
+            matches = [(i, 2) for i in [i_crlf] if i != -1]
+            matches += [(i, 1) for i in [i_cr, i_lf] if i != -1]
+
+            if not matches:
+                break
+
+            i, nl_len = min(matches, key=lambda x: x[0])
+            line = bytes(buf[:i]).decode(ser.encoding, errors='replace')
+            del buf[:i + nl_len]
+
+            if line:
+                log.info('RX: %r', line)
+
+
+def send_raw(ser, s):
+    """
+    """
+    sys.stdout.write(s)
+    sys.stdout.flush()
+    ser.write(s, append_newline=False)
+    log.info('TX: %r', s)
+
+
+
+def terminal(ser):
+    stop_event = threading.Event()
+    threading.Thread(target=reader, args=(ser, stop_event), daemon=True).start()
+
+    try:
+        while True:
+            try:
+                key = readchar.readkey()
+            except KeyboardInterrupt:
+                break
+
+            if key == readchar.key.ESC:
+                send_raw(ser, '\x1b')
+            elif key == readchar.key.BACKSPACE:
+                send_raw(ser, '\x08')
+            elif key in (readchar.key.ENTER, readchar.key.CR, readchar.key.LF):
+                send_raw(ser, ser.newline_tx or '\r')
+            else:
+                send_raw(ser, key)
+    finally:
+        stop_event.set()
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('port')
+    parser.add_argument('baudrate', type=int)
+    parser.add_argument('--log', help='path to log file')
+    args = parser.parse_args()
+
+    configure_logging(args.log)
+
+    ser = sertools.SerialDevice(
+        port=args.port,
+        baudrate=args.baudrate,
+        newline_rx='\r',
+        terminator=None,
+        terminator_cmd=None,
+    )
+
+    try:
+        terminal(ser)
+    finally:
+        ser.close()
+
+
+if __name__ == "__main__":
+    main()

sertools-0.1.0/src/sertools/serial_device.py

@@ -0,0 +1,303 @@
+"""sertools.py module, a thin pyserial wrapper"""
+
+import logging
+import time
+
+import serial
+
+
+log = logging.getLogger(__name__)
+
+
+class SerialDevice:
+    """Thin wrapper for pyserial.Serial class.
+    Provides a flexible query method for sending commands and receiving responses.
+    Responses are always either a str (single line) or list of str (multiline).
+    
+    Parameters
+    ----------
+    port : str
+    baudrate : int
+    timeout : float
+    encoding : str
+    newline_tx : str
+    newline_rx : str
+    terminator : str
+    terminator_cmd : str
+
+    Examples
+    --------
+    >>> dut = SerialDevice(port='COM42',
+                           baudrate=460800,
+                           timeout=None,
+                           newline_tx='\r',
+                           newline_rx='\r\n',
+                           terminator='Ok',
+                           terminator_cmd='\r')
+    """
+    def __init__(self, *,
+                 port: str | None = None,
+                 baudrate: int = 9600,
+                 timeout: float | None = None,
+                 encoding: str = 'ascii',
+                 newline_tx: str = '\r',
+                 newline_rx: str = '\r',
+                 terminator: str | None = None,
+                 terminator_cmd: str | None = None):
+
+        self.port = port
+        self.baudrate = baudrate
+        self.timeout = timeout
+        self.encoding = encoding
+        self.newline_tx = newline_tx
+        self.newline_rx = newline_rx
+        self.terminator = terminator
+        self.terminator_cmd = terminator_cmd
+        self._rx_buffer = bytearray()
+
+        self.ser = serial.Serial(port=port,
+                                 baudrate=baudrate,
+                                 timeout=timeout)
+
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(port={self.port!r}, baudrate={self.baudrate})"
+
+
+    def __str__(self):
+        return f"{self.port} @ {self.baudrate}"
+
+
+    def __call__(self, command: str, **kwargs) -> str | list[str]:
+        """Passes `command` and other params along to `self.query`."""
+
+        response = self.query(command, **kwargs)
+        return response
+
+
+    def open(self) -> None:
+        """Open port."""
+        self.ser.open()
+
+
+    def close(self) -> None:
+        """Close port."""
+        self.ser.close()
+
+
+    def flush(self) -> None:
+        """Reset input and output buffers."""
+        self.ser.reset_input_buffer()
+        self.ser.reset_output_buffer()
+
+
+    def write(self, command: str,
+              newline_tx: str | None = None,
+              append_newline: bool = True) -> int:
+        """Write command to port.
+
+        Parameters
+        ----------
+        command : str
+            Command sent to device.
+        newline_tx : str, optional
+            Newline character denoting end of line sent.
+            Defaults to `self.newline_tx'
+        append_newline : bool, optional
+            Optionally append newline_tx to command if not already present.
+            Defaults to True.
+
+        Returns
+        -------
+        int
+            Number of bytes sent to port.
+
+        Examples
+        --------
+        >>> TBD
+        """
+        newline_tx = self.newline_tx if newline_tx is None else newline_tx
+
+        if append_newline and not command.endswith(newline_tx):
+            command += newline_tx
+
+        log.info("TX: %r", command)
+        tx = command.encode(self.encoding)
+        return self.ser.write(tx)
+
+
+    def readline(self, newline_rx: str | None = None,
+                 timeout: float | None = None) -> str:
+        """Read a line from device.
+
+        Parameters
+        ----------
+        newline_rx : str, optional
+            Newline character denoting end of line read.
+            Defaults to self.newline_rx.
+        timeout : float, optional
+            Timeout.
+            Defaults to self.timeout.
+
+        Returns
+        -------
+        line : str
+
+        Examples
+        --------
+        >>> TBD
+        """
+        newline_rx = self.newline_rx if newline_rx is None else newline_rx
+        timeout = self.timeout if timeout is None else timeout
+
+        nl = newline_rx.encode(self.encoding)
+        t0 = time.monotonic()
+        line_bytes = None
+
+        while True:
+            i = self._rx_buffer.find(nl)
+            if i != -1:
+                line_bytes = self._rx_buffer[:i]
+                del self._rx_buffer[:i + len(nl)]
+                break
+
+            if timeout is not None and time.monotonic() - t0 >= timeout:
+                if self._rx_buffer:
+                    line_bytes = bytes(self._rx_buffer)
+                    self._rx_buffer.clear()
+                else:
+                    line_bytes = b''
+                break
+
+            n = self.ser.in_waiting
+            if n:
+                self._rx_buffer.extend(self.ser.read(n))
+            else:
+                time.sleep(0.005)
+
+        line = line_bytes.decode(self.encoding, errors='replace').strip()
+        if line:
+            log.info("RX: %r", line)
+        return line
+    
+
+    def query(self, command: str, **kwargs) -> str | list[str]:
+        """Primary method for sending command and receiving response.
+
+        Parameters
+        ----------
+        command : str
+            Command sent to device.
+
+        **kwargs
+            Additional read options.
+            May override instance defaults such as `newline_tx`, `newline_rx`, etc.
+
+        newline_tx : str, optional
+            Newline character for `self.write`.
+            Defaults to `self.newline_tx`.
+        newline_rx : str, optional
+            Newline character for `self.readline`.
+            Defaults to `self.newline_rx`.
+        timeout : float, optional
+            Read timeout for whole query, separate from `self.ser.timeout`.
+            Defaults to `self.timeout`.
+        terminator : str, optional
+            Ends readline loop when `terminator` in `line`.
+            Defaults to `self.terminator`.
+        terminator_cmd : str, optional
+            Command string sent to port that triggers device to emit `terminator`.
+            Defaults to `self.terminator_cmd`.
+        strip_terminator : bool, optional
+            Remove `terminator` line from end of `response`.
+            Defaults to `True`.
+        terminator_delay : float, optional
+            Wait `terminator_delay` seconds before sending `terminator_cmd`.
+            Defaults to 0.
+        num_lines : int, optional
+            Stops read when `len(response) == num_lines`.
+            Defaults to None.
+
+        Returns
+        -------
+        response : str or list[str]
+
+        Examples
+        --------
+        >>> TBD
+        """
+
+        newline_tx = kwargs.get('newline_tx', self.newline_tx)
+        newline_rx = kwargs.get('newline_rx', self.newline_rx)
+        timeout = kwargs.get('timeout', self.timeout)
+        terminator = kwargs.get('terminator', self.terminator)
+        terminator_cmd = kwargs.get('terminator_cmd', self.terminator_cmd)
+        strip_terminator = kwargs.get('strip_terminator', True)
+        terminator_delay = kwargs.get('terminator_delay', 0)
+        num_lines = kwargs.get('num_lines', None)
+
+        # do we want to check if stuff is getting received?
+
+        self.flush()
+
+        self.write(command, newline_tx=newline_tx, append_newline=True)
+
+        response = []
+        t0 = time.monotonic()
+        sent_terminator = False
+        saw_terminator = False
+
+        while True:
+            # End read if timeout
+            if timeout is None:
+                remaining = None
+            else:
+                remaining = timeout - (time.monotonic() - t0)
+                if remaining <= 0:
+                    break
+
+            # Send terminator_cmd after terminator_delay.
+            # Toggle sent_terminator to True so it only sends it once.
+            if (terminator_cmd is not None
+                and terminator_delay >= 0
+                and not sent_terminator
+                and time.monotonic() - t0 >= terminator_delay
+                ):
+                self.write(terminator_cmd, newline_tx=newline_tx, append_newline=False)
+                sent_terminator = True
+
+            # Read line and append to response if it's not empty
+            line = self.readline(newline_rx=newline_rx, timeout=remaining)
+
+            if line:
+                response.append(line)
+
+            # Optionally end read at num_lines
+            if num_lines is not None and len(response) >= num_lines:
+                break
+
+            # Optionally end read at terminator
+            if (terminator is not None
+                and line
+                and terminator in line
+                and sent_terminator):
+                saw_terminator = True
+                break
+
+        # Optionally remove terminator from response.
+        if strip_terminator and response and terminator and saw_terminator and terminator in response[-1]:
+            response = response[:-1]
+
+        # If response is single line, return as str
+        if len(response) == 1:
+            response = response[0]
+
+        # clear 'self._rx_buffer'
+        self._rx_buffer = bytearray()
+
+        # flush
+        if self.ser.in_waiting != 0:
+            self.flush()
+
+        return response
+

sertools-0.1.0/src/sertools.egg-info/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: sertools
+Version: 0.1.0
+Summary: Interface for serial devices using pyserial.
+Author-email: Jason Doar <jbdoar@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jbdoar/sertools
+Project-URL: Issues, https://github.com/jbdoar/sertools/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial
+Requires-Dist: readchar
+Dynamic: license-file
+
+# sertools
+
+Interface for serial devices using pyserial.
+
+## Installation
+
+```bash
+pip install sertools
+```
+
+## Features
+- Query method with flexible configuration parameters for various response formats.
+- Lightweight serial port terminal emulator.
+
+## Usage
+The SerialDevice instance may be called with a command string to send to the serial port and optional readback/terminator parameters.
+
+```python
+from sertools import SerialDevice
+ser = SerialDevice()
+ser('HELP')
+```
+
+## Development
+```bash
+git clone https://github.com/jbdoar/sertools
+cd sertools
+pip install -e .
+```

sertools-0.1.0/src/sertools.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/sertools/__init__.py
+src/sertools/serial_device.py
+src/sertools.egg-info/PKG-INFO
+src/sertools.egg-info/SOURCES.txt
+src/sertools.egg-info/dependency_links.txt
+src/sertools.egg-info/entry_points.txt
+src/sertools.egg-info/requires.txt
+src/sertools.egg-info/top_level.txt
+src/sertools/scripts/__init__.py
+src/sertools/scripts/sterm.py

sertools-0.1.0/src/sertools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sertools-0.1.0/src/sertools.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sterm = sertools.scripts.sterm:main

sertools-0.1.0/src/sertools.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pyserial
+readchar

sertools-0.1.0/src/sertools.egg-info/top_level.txt

@@ -0,0 +1 @@
+sertools