Skip to content

v0.1.3 - Serial Communication Reliability & Documentation (2025-12-02)

What Changed?

This release improves serial communication reliability with better buffer management and response polling, while significantly expanding notebook-based documentation with complete workflow examples. The changes maintain full backward compatibility while providing a more robust foundation for device interaction.

What's New

Improved Serial Communication

What it does: Enhanced the PortDevice.receive_response() method with in_waiting polling to provide more reliable response detection. The device now clears the input buffer before sending commands to prevent stale data interference.

How to use it: No API changes required. The improvements are transparent to users and automatically provide better communication reliability.

Key improvements:

  • Input buffer is cleared before each command transmission
  • Response polling uses in_waiting for more responsive data detection
  • Data events are properly skipped when searching for command responses

Comprehensive Notebook Documentation

What it does: Added three complete notebook examples demonstrating real-world workflows using the library.

Available notebooks (located in notebooks/md/):

  • basic_readout.md - Complete data acquisition workflow
  • set_thresholds.md - Configuring detector thresholds
  • threshold_scan.md - Performing threshold scan analysis

These notebooks use Jupytext markdown format and are executable in Jupyter environments.

Installation

Quick Start

# Update to latest main
git pull origin main

# Install/update dependencies
uv sync

# Run tests to verify
pytest

What's Different from the Last Version?

✅ Added

  • Three comprehensive Jupyter notebook examples (basic_readout, set_thresholds, threshold_scan)
  • Jupytext configuration for markdown-based notebook development
  • ipykernel dependency for notebook support
  • Input buffer clearing before command transmission
  • Improved response polling with in_waiting detection
  • _get_device helper function in CLI for cleaner code organization

🔧 Changed

  • PortDevice.serial_device renamed to PortDevice.device for consistency
  • receive_response() refactored with in-waiting polling strategy
  • Response query logic improved to skip data events
  • CLI code reorganized for better maintainability
  • Updated .gitignore to exclude notebook build artifacts

🐛 Fixed

  • Fixed issue where stale data in serial buffer could interfere with command responses
  • Improved handling of data events during response parsing in query operations

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All public APIs remain unchanged
  • Internal refactoring (e.g., serial_device → device) only affects internal implementation
  • Serial communication improvements are transparent to users
  • Notebooks are optional and don't affect existing library usage

Tests Passed

  • ✅ Code builds without errors
  • ✅ Linting passes (ruff check)
  • ✅ Type checking passes (mypy)
  • ✅ Serial communication improvements validated through device integration

Release Details

  • Date: 2025-12-02
  • Version: v0.1.3
  • Files Changed: 14
  • Commits: 16 commits since v0.1.2
  • Lines Added: 1,202 | Lines Removed: 80

Next Steps

  • Expand test coverage for device communication improvements
  • Add more specialized notebook examples (calibration, analysis workflows)
  • Consider async support for parallel device operations
  • Explore additional export formats for collected data