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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puda-drivers
-Version: 0.0.5
+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
@@ -183,6 +215,29 @@ except ValueError as 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.5 → 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
@@ -163,6 +195,29 @@ except ValueError as 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.5 → puda_drivers-0.0.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "puda-drivers"
-version = "0.0.5"
+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.5 → puda_drivers-0.0.6}/src/puda_drivers/core/serialcontroller.py

@@ -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

{puda_drivers-0.0.5 → puda_drivers-0.0.6}/tests/pipette.py

@@ -1,22 +1,25 @@
 import logging
 from puda_drivers.transfer.liquid.sartorius import SartoriusController
+from puda_drivers.core.logging import setup_logging
 
 # Optional: finding ports
 # import serial.tools.list_ports
 # for port, desc, hwid in serial.tools.list_ports.comports():
 #     print(f"{port}: {desc} [{hwid}]")
 
-# 1. Configure the root logger
-# All loggers in imported modules (SerialController, GCodeController) will inherit this setup.
-logging.basicConfig(
-    # Use logging.DEBUG to see all (DEBUG, INFO, WARNING, ERROR, CRITICAL) logs
-    level=logging.DEBUG,
-    # Recommended format: includes time, logger name, level, and message
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+# --- LOGGING CONFIGURATION ---
+# Set ENABLE_FILE_LOGGING to True to save logs to logs/ folder, False to only output to console
+ENABLE_FILE_LOGGING = True  # Change to False to disable file logging
+
+# Configure logging
+# All loggers in imported modules (SerialController, SartoriusController) will inherit this setup.
+setup_logging(
+    enable_file_logging=ENABLE_FILE_LOGGING,
+    log_level=logging.DEBUG,  # Use logging.DEBUG to see all (DEBUG, INFO, WARNING, ERROR, CRITICAL) logs
 )
 
-# 2. OPTIONAL: If you only want GCodeController's logs at specific level, you can specifically set it here
-# logging.getLogger('drivers.gcodecontroller').setLevel(logging.INFO)
+# OPTIONAL: If you only want specific loggers at specific level, you can specifically set it here
+# logging.getLogger('puda_drivers.transfer.liquid.sartorius').setLevel(logging.INFO)
 
 
 # --- CONFIGURATION ---
@@ -42,19 +45,19 @@ def test_pipette_operations():
         # Always start with initializing
         pipette.initialize()
 
-        pipette.get_inward_speed()
+        # pipette.get_inward_speed()
         # print("\n set inward speed to 3")
         # pipette.set_inward_speed(3)
 
         # 3. Eject Tip (if any)
-        # print("\n[STEP 3] Ejecting Tip (if any)...")
-        # pipette.eject_tip(return_position=30)
-        # print(f"\n[STEP 3] Aspirate {TRANSFER_VOLUME} uL...")
-        # pipette.aspirate(amount=TRANSFER_VOLUME)
+        print("\n[STEP 3] Ejecting Tip (if any)...")
+        pipette.eject_tip(return_position=30)
+        print(f"\n[STEP 3] Aspirate {TRANSFER_VOLUME} uL...")
+        pipette.aspirate(amount=TRANSFER_VOLUME)
 
         # 4. Dispense
-        # print(f"\n[STEP 4] Dispensing {TRANSFER_VOLUME} uL...")
-        # pipette.dispense(amount=TRANSFER_VOLUME)
+        print(f"\n[STEP 4] Dispensing {TRANSFER_VOLUME} uL...")
+        pipette.dispense(amount=TRANSFER_VOLUME)
 
         # # 5. Eject Tip
         # print("\n[STEP 5] Ejecting Tip...")

{puda_drivers-0.0.5 → puda_drivers-0.0.6}/tests/qubot.py

@@ -1,21 +1,20 @@
 import logging
 from puda_drivers.move import GCodeController
+from puda_drivers.core.logging import setup_logging
 
 # Optinal: finding ports
-import serial.tools.list_ports
-for port, desc, hwid in serial.tools.list_ports.comports():
-    print(f"{port}: {desc} [{hwid}]")
+# import serial.tools.list_ports
+# for port, desc, hwid in serial.tools.list_ports.comports():
+#     print(f"{port}: {desc} [{hwid}]")
 
-# 1. Configure the root logger
+# --- LOGGING CONFIGURATION ---
 # All loggers in imported modules (SerialController, GCodeController) will inherit this setup.
-logging.basicConfig(
-    # Use logging.DEBUG to see all (DEBUG, INFO, WARNING, ERROR, CRITICAL) logs
-    level=logging.WARNING,
-    # Recommended format: includes time, logger name, level, and message
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+setup_logging(
+    enable_file_logging=True,
+    log_level=logging.DEBUG,  # Use logging.DEBUG to see all (DEBUG, INFO, WARNING, ERROR, CRITICAL) logs
 )
 
-# 2. OPTIONAL: If you only want GCodeController's logs at specific level, you can specifically set it here
+# OPTIONAL: If you only want GCodeController's logs at specific level, you can specifically set it here
 # logging.getLogger('puda_drivers.gcodecontroller').setLevel(logging.INFO)
 
 PORT_NAME = "/dev/ttyACM0"
@@ -54,7 +53,7 @@ def main():
         # qubot.feed = 5000
 
         # Relative moves are converted to absolute internally, but works the same
-        # for anything in the Z-axis, will have to be moved individually, else error will be raised
+        # for anything in the -axis, will have to be moved individually, else error will be raised
         print("\n")
         qubot.move_absolute(x=00.0, y=-50.0, a=-100.0)
         

{puda_drivers-0.0.5 → puda_drivers-0.0.6}/tests/together.py

@@ -2,11 +2,12 @@ import logging
 import serial
 from puda_drivers.move import GCodeController
 from puda_drivers.transfer.liquid.sartorius import SartoriusController
+from puda_drivers.core.logging import setup_logging
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,  # Use INFO level for cleaner output during automation
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+# --- LOGGING CONFIGURATION ---
+setup_logging(
+    enable_file_logging=False,
+    log_level=logging.INFO,  # Use INFO level for cleaner output during automation
 )
 
 # Qubot Configuration
@@ -65,6 +66,7 @@ try:
     print("Connecting to pipette")
     # SartoriusController connects automatically in __init__, no need to call connect()
     pipette = SartoriusController(port_name=SARTORIUS_PORT)
+    # always start with initializing
     pipette.initialize()
 except Exception as e:
     print(f"FATAL ERROR: Could not initialize/connect Sartorius: {e}")
@@ -90,10 +92,6 @@ def run_automation():
         # 4. Protocol Step 2: Aspirate Liquid
         print(f"\nProtocol Step 2: Aspirating {TRANSFER_VOLUME} uL")
 
-        # Move to safe Z-height before moving across the deck
-        pos = qubot.move_absolute(z=SAFE_Z_POS)
-        print(f"  Position after safe Z move: {pos}")
-
         # Move to the source well (ASPIRATE_POS)
         pos = qubot.move_absolute(
             x=ASPIRATE_POS["X"], y=ASPIRATE_POS["Y"], z=ASPIRATE_POS["Z"], feed=3000
@@ -129,10 +127,6 @@ def run_automation():
         # 6. Protocol Step 4: Finalization
         print("\nProtocol Step 4: Finalizing")
 
-        # Move back to safe Z-height
-        pos = qubot.move_absolute(z=SAFE_Z_POS)
-        print(f"  Position after safe Z move: {pos}")
-
         # Simulate moving to a trash bin and ejecting the tip
         pos = qubot.move_absolute(x=10.0, y=-10.0)
         print(f"  Position at trash bin: {pos}")

{puda_drivers-0.0.5 → puda_drivers-0.0.6}/uv.lock

@@ -9,7 +9,7 @@ resolution-markers = [
 
 [[package]]
 name = "puda-drivers"
-version = "0.0.5"
+version = "0.0.6"
 source = { editable = "." }
 dependencies = [
     { name = "pyserial" },

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

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