puda-drivers 0.0.4__tar.gz → 0.0.6__tar.gz

{puda_drivers-0.0.4 → puda_drivers-0.0.6}/.gitignore

@@ -129,3 +129,7 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# Log files
+logs/
+*.log

{puda_drivers-0.0.4 → puda_drivers-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.4
+Version: 0.0.6
 Summary: Hardware drivers for the PUDA platform.
 Project-URL: Homepage, https://github.com/zhao-bears/puda-drivers
 Project-URL: Issues, https://github.com/zhao-bears/puda-drivers/issues
@@ -27,6 +27,7 @@ Hardware drivers for the PUDA (Physical Unified Device Architecture) platform. T
 - **Gantry Control**: Control G-code compatible motion systems (e.g., QuBot)
 - **Liquid Handling**: Interface with Sartorius rLINE® pipettes and dispensers
 - **Serial Communication**: Robust serial port management with automatic reconnection
+- **Logging**: Configurable logging with optional file output to logs folder
 - **Cross-platform**: Works on Linux, macOS, and Windows
 
 ## Installation
@@ -47,6 +48,37 @@ pip install -e .
 
 ## Quick Start
 
+### Logging Configuration
+
+Configure logging for your application with optional file output:
+
+```python
+import logging
+from puda_drivers.core.logging import setup_logging
+
+# Configure logging with file output enabled
+setup_logging(
+    enable_file_logging=True,
+    log_level=logging.DEBUG,
+    logs_folder="logs", # Optional: default to logs
+    log_file_name="my_experiment"  # Optional: custom log file name
+)
+
+# Or disable file logging (console only)
+setup_logging(
+    enable_file_logging=False,
+    log_level=logging.INFO
+)
+```
+
+**Logging Options:**
+- `enable_file_logging`: If `True`, logs are written to files in the `logs/` folder. If `False`, logs only go to console (default: `False`)
+- `log_level`: Logging level constant (e.g., `logging.DEBUG`, `logging.INFO`, `logging.WARNING`, `logging.ERROR`, `logging.CRITICAL`) (default: `logging.DEBUG`)
+- `logs_folder`: Name of the folder to store log files (default: `"logs"`)
+- `log_file_name`: Custom name for the log file. If `None` or empty, uses timestamp-based name (e.g., `log_20250101_120000.log`). If provided without `.log` extension, it will be added automatically.
+
+When file logging is enabled, logs are saved to timestamped files (unless a custom name is provided) in the `logs/` folder. The logs folder is created automatically if it doesn't exist.
+
 ### Gantry Control (GCode)
 
 ```python
@@ -56,13 +88,19 @@ from puda_drivers.move import GCodeController
 gantry = GCodeController(port_name="/dev/ttyACM0", feed=3000)
 gantry.connect()
 
+# Configure axis limits for safety (recommended)
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+gantry.set_axis_limits("Z", -100, 0)
+gantry.set_axis_limits("A", -180, 180)
+
 # Home the gantry
 gantry.home()
 
-# Move to absolute position
+# Move to absolute position (validated against limits)
 gantry.move_absolute(x=50.0, y=-100.0, z=-10.0)
 
-# Move relative to current position
+# Move relative to current position (validated after conversion to absolute)
 gantry.move_relative(x=20.0, y=-10.0)
 
 # Query current position
@@ -73,6 +111,8 @@ print(f"Current position: {position}")
 gantry.disconnect()
 ```
 
+**Axis Limits and Validation**: The `move_absolute()` and `move_relative()` methods automatically validate that target positions are within configured axis limits. If a position is outside the limits, a `ValueError` is raised before any movement is executed. Use `set_axis_limits()` to configure limits for each axis.
+
 ### Liquid Handling (Sartorius)
 
 ```python
@@ -134,6 +174,7 @@ pipette.disconnect()
   - Supports X, Y, Z, and A axes
   - Configurable feed rates
   - Position synchronization and homing
+  - Automatic axis limit validation for safe operation
 
 ### Liquid Handling
 
@@ -142,6 +183,61 @@ pipette.disconnect()
   - Tip attachment and ejection
   - Configurable speeds and volumes
 
+## Error Handling
+
+### Axis Limit Validation
+
+Both `move_absolute()` and `move_relative()` validate positions against configured axis limits before executing any movement. If a position is outside the limits, a `ValueError` is raised:
+
+```python
+from puda_drivers.move import GCodeController
+
+gantry = GCodeController(port_name="/dev/ttyACM0")
+gantry.connect()
+
+# Set axis limits
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+
+try:
+    # This will raise ValueError: Value 250 outside axis limits [0, 200]
+    gantry.move_absolute(x=250.0, y=-50.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+
+# Relative moves are also validated after conversion to absolute positions
+try:
+    # If current X is 150, moving 100 more would exceed the limit
+    gantry.move_relative(x=100.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+```
+
+Validation errors are automatically logged at the ERROR level before the exception is raised.
+
+### Logging Best Practices
+
+For production applications, configure logging at the start of your script:
+
+```python
+import logging
+from puda_drivers.core.logging import setup_logging
+from puda_drivers.move import GCodeController
+
+# Configure logging first, before initializing devices
+setup_logging(
+    enable_file_logging=True,
+    log_level=logging.INFO,
+    log_file_name="gantry_operation"
+)
+
+# Now all device operations will be logged
+gantry = GCodeController(port_name="/dev/ttyACM0")
+# ... rest of your code
+```
+
+This ensures all device communication, movements, and errors are captured in log files for debugging and audit purposes.
+
 ## Finding Serial Ports
 
 To discover available serial ports on your system:

{puda_drivers-0.0.4 → puda_drivers-0.0.6}/README.md

@@ -7,6 +7,7 @@ Hardware drivers for the PUDA (Physical Unified Device Architecture) platform. T
 - **Gantry Control**: Control G-code compatible motion systems (e.g., QuBot)
 - **Liquid Handling**: Interface with Sartorius rLINE® pipettes and dispensers
 - **Serial Communication**: Robust serial port management with automatic reconnection
+- **Logging**: Configurable logging with optional file output to logs folder
 - **Cross-platform**: Works on Linux, macOS, and Windows
 
 ## Installation
@@ -27,6 +28,37 @@ pip install -e .
 
 ## Quick Start
 
+### Logging Configuration
+
+Configure logging for your application with optional file output:
+
+```python
+import logging
+from puda_drivers.core.logging import setup_logging
+
+# Configure logging with file output enabled
+setup_logging(
+    enable_file_logging=True,
+    log_level=logging.DEBUG,
+    logs_folder="logs", # Optional: default to logs
+    log_file_name="my_experiment"  # Optional: custom log file name
+)
+
+# Or disable file logging (console only)
+setup_logging(
+    enable_file_logging=False,
+    log_level=logging.INFO
+)
+```
+
+**Logging Options:**
+- `enable_file_logging`: If `True`, logs are written to files in the `logs/` folder. If `False`, logs only go to console (default: `False`)
+- `log_level`: Logging level constant (e.g., `logging.DEBUG`, `logging.INFO`, `logging.WARNING`, `logging.ERROR`, `logging.CRITICAL`) (default: `logging.DEBUG`)
+- `logs_folder`: Name of the folder to store log files (default: `"logs"`)
+- `log_file_name`: Custom name for the log file. If `None` or empty, uses timestamp-based name (e.g., `log_20250101_120000.log`). If provided without `.log` extension, it will be added automatically.
+
+When file logging is enabled, logs are saved to timestamped files (unless a custom name is provided) in the `logs/` folder. The logs folder is created automatically if it doesn't exist.
+
 ### Gantry Control (GCode)
 
 ```python
@@ -36,13 +68,19 @@ from puda_drivers.move import GCodeController
 gantry = GCodeController(port_name="/dev/ttyACM0", feed=3000)
 gantry.connect()
 
+# Configure axis limits for safety (recommended)
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+gantry.set_axis_limits("Z", -100, 0)
+gantry.set_axis_limits("A", -180, 180)
+
 # Home the gantry
 gantry.home()
 
-# Move to absolute position
+# Move to absolute position (validated against limits)
 gantry.move_absolute(x=50.0, y=-100.0, z=-10.0)
 
-# Move relative to current position
+# Move relative to current position (validated after conversion to absolute)
 gantry.move_relative(x=20.0, y=-10.0)
 
 # Query current position
@@ -53,6 +91,8 @@ print(f"Current position: {position}")
 gantry.disconnect()
 ```
 
+**Axis Limits and Validation**: The `move_absolute()` and `move_relative()` methods automatically validate that target positions are within configured axis limits. If a position is outside the limits, a `ValueError` is raised before any movement is executed. Use `set_axis_limits()` to configure limits for each axis.
+
 ### Liquid Handling (Sartorius)
 
 ```python
@@ -114,6 +154,7 @@ pipette.disconnect()
   - Supports X, Y, Z, and A axes
   - Configurable feed rates
   - Position synchronization and homing
+  - Automatic axis limit validation for safe operation
 
 ### Liquid Handling
 
@@ -122,6 +163,61 @@ pipette.disconnect()
   - Tip attachment and ejection
   - Configurable speeds and volumes
 
+## Error Handling
+
+### Axis Limit Validation
+
+Both `move_absolute()` and `move_relative()` validate positions against configured axis limits before executing any movement. If a position is outside the limits, a `ValueError` is raised:
+
+```python
+from puda_drivers.move import GCodeController
+
+gantry = GCodeController(port_name="/dev/ttyACM0")
+gantry.connect()
+
+# Set axis limits
+gantry.set_axis_limits("X", 0, 200)
+gantry.set_axis_limits("Y", -200, 0)
+
+try:
+    # This will raise ValueError: Value 250 outside axis limits [0, 200]
+    gantry.move_absolute(x=250.0, y=-50.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+
+# Relative moves are also validated after conversion to absolute positions
+try:
+    # If current X is 150, moving 100 more would exceed the limit
+    gantry.move_relative(x=100.0)
+except ValueError as e:
+    print(f"Move rejected: {e}")
+```
+
+Validation errors are automatically logged at the ERROR level before the exception is raised.
+
+### Logging Best Practices
+
+For production applications, configure logging at the start of your script:
+
+```python
+import logging
+from puda_drivers.core.logging import setup_logging
+from puda_drivers.move import GCodeController
+
+# Configure logging first, before initializing devices
+setup_logging(
+    enable_file_logging=True,
+    log_level=logging.INFO,
+    log_file_name="gantry_operation"
+)
+
+# Now all device operations will be logged
+gantry = GCodeController(port_name="/dev/ttyACM0")
+# ... rest of your code
+```
+
+This ensures all device communication, movements, and errors are captured in log files for debugging and audit purposes.
+
 ## Finding Serial Ports
 
 To discover available serial ports on your system:

{puda_drivers-0.0.4 → puda_drivers-0.0.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "puda-drivers"
-version = "0.0.4"
+version = "0.0.6"
 description = "Hardware drivers for the PUDA platform."
 readme = "README.md"
 authors = [

puda_drivers-0.0.6/src/puda_drivers/core/__init__.py

@@ -0,0 +1,4 @@
+from .serialcontroller import SerialController, list_serial_ports
+from .logging import setup_logging
+
+__all__ = ["SerialController", "list_serial_ports", "setup_logging"]

puda_drivers-0.0.6/src/puda_drivers/core/logging.py

@@ -0,0 +1,73 @@
+"""
+Logging configuration utility.
+
+This module provides a function to configure logging with optional file output
+to a logs folder.
+"""
+
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+def setup_logging(
+    enable_file_logging: bool = False,
+    log_level: int = logging.DEBUG,
+    logs_folder: str = "logs",
+    log_file_name: Optional[str] = None,
+) -> None:
+    """
+    Configure logging with optional file output to a logs folder.
+
+    Args:
+        enable_file_logging: If True, logs will be written to files in the logs folder.
+                           If False, logs will only be output to console.
+        log_level: Logging level constant from logging module (e.g., logging.DEBUG,
+                   logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL).
+                   Defaults to logging.DEBUG.
+        logs_folder: Name of the folder to store log files (default: "logs")
+        log_file_name: Custom name for the log file. If None or empty string, uses
+                      timestamp-based name. If provided without .log extension, it will
+                      be added automatically.
+    """
+    # Create logs folder if file logging is enabled
+    if enable_file_logging:
+        log_dir = Path(logs_folder)
+        log_dir.mkdir(exist_ok=True)
+        
+        # Create a log file with custom name or timestamp
+        if log_file_name and log_file_name.strip():  # None or empty/whitespace strings use timestamp
+            # Ensure .log extension if not present
+            if not log_file_name.endswith(".log"):
+                log_file_name = f"{log_file_name}.log"
+            log_file = log_dir / log_file_name
+        else:
+            # Default: timestamp-based name
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            log_file = log_dir / f"log_{timestamp}.log"
+        
+        # Configure logging with both console and file handlers
+        logging.basicConfig(
+            level=log_level,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            handlers=[
+                logging.StreamHandler(),  # Console output
+                logging.FileHandler(log_file, mode="w"),  # File output
+            ],
+        )
+        
+        # Log that file logging is enabled
+        logger = logging.getLogger(__name__)
+        logger.info("File logging enabled. Log file: %s", log_file)
+    else:
+        # Configure logging with only console handler
+        logging.basicConfig(
+            level=log_level,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            handlers=[logging.StreamHandler()],  # Console output only
+        )
+        
+        # Log that file logging is disabled
+        logger = logging.getLogger(__name__)
+        logger.info("File logging disabled. Logs will only be output to console.")

{puda_drivers-0.0.4 → puda_drivers-0.0.6}/src/puda_drivers/core/serialcontroller.py

@@ -2,12 +2,12 @@
 Generic Serial Controller for communicating with devices over serial ports.
 """
 
-import serial
 import time
-import serial.tools.list_ports
 import logging
 from typing import Optional, List, Tuple
 from abc import ABC
+import serial
+import serial.tools.list_ports
 
 logger = logging.getLogger(__name__)
 
@@ -45,7 +45,7 @@ def list_serial_ports(filter_desc: Optional[str] = None) -> List[Tuple[str, str,
 
 class SerialController(ABC):
     DEFAULT_BAUDRATE = 9600
-    DEFAULT_TIMEOUT = 20  # seconds
+    DEFAULT_TIMEOUT = 30  # seconds
     POLL_INTERVAL = 0.1  # seconds
 
     def __init__(self, port_name, baudrate=DEFAULT_BAUDRATE, timeout=DEFAULT_TIMEOUT):
@@ -127,8 +127,8 @@ class SerialController(ABC):
         try:
             self._serial.reset_input_buffer()  # clear input buffer
             self._serial.reset_output_buffer()  # clear output buffer
-            self._serial.write(bytes(command, "utf-8"))
             self._serial.flush()
+            self._serial.write(bytes(command, "utf-8"))
 
         except serial.SerialTimeoutException as e:
             # Log the timeout error and return None as requested (no re-raise)
@@ -159,9 +159,13 @@ class SerialController(ABC):
                 # Read all available bytes
                 response += self._serial.read(self._serial.in_waiting)
 
-                # Check for expected response markers for early return
+                # Check for expected response markers for early return for qubot
                 if b"ok" in response or b"err" in response:
                     break
+                
+                # Check for expected response markers for early return for sartorius
+                if b"\xba\r" in response:
+                    break
             else:
                 time.sleep(0.1)
 
@@ -175,10 +179,12 @@ class SerialController(ABC):
         # Decode once and check the decoded string
         decoded_response = response.decode("utf-8", errors="ignore").strip()
         
-        if "ok" in decoded_response.lower():
+        if "ok" in decoded_response.lower(): # for qubot
             self._logger.debug("<- Received response: %r", decoded_response)
-        elif "err" in decoded_response.lower():
+        elif "err" in decoded_response.lower(): # for qubot
             self._logger.error("<- Received error: %r", decoded_response)
+        elif "º" in decoded_response: # for sartorius
+            self._logger.debug("<- Received response: %r", decoded_response)
         else:
             self._logger.warning(
                 "<- Received unexpected response (no 'ok' or 'err'): %r", decoded_response