fixing problems

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,54 @@
+---
+name: Bug Report
+about: Report a bug or issue with python-emc2305
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+A clear and concise description of the bug.
+
+## Hardware Setup
+- **EMC2305 Variant**: (e.g., EMC2305-1-APTR, EMC2305-2, etc.)
+- **I2C Address**: (e.g., 0x4D)
+- **Platform**: (e.g., Raspberry Pi 4, Banana Pi M5, x86 Linux)
+- **OS**: (e.g., Raspberry Pi OS Bookworm, Ubuntu 22.04)
+- **Fan Type**: (e.g., Noctua NF-A4x10 PWM, Generic 4-wire fan)
+
+## Software Environment
+- **Python Version**: (e.g., 3.11.2)
+- **python-emc2305 Version**: (e.g., 0.1.0)
+- **Installation Method**: (pip, source, other)
+
+## Steps to Reproduce
+Minimal code example to reproduce the issue:
+
+```python
+from emc2305 import FanController
+
+# Your code here
+```
+
+## Expected Behavior
+What you expected to happen.
+
+## Actual Behavior
+What actually happened.
+
+## Error Messages/Logs
+```
+Paste error messages, tracebacks, or logs here
+```
+
+## I2C Communication Traces (if applicable)
+```bash
+# Output of i2cdetect
+$ i2cdetect -y 0
+
+# Register reads/writes that failed
+$ i2cget -y 0 0x4d 0x30 b
+```
+
+## Additional Context
+Any other relevant information, hardware modifications, or observations.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,33 @@
+---
+name: Feature Request
+about: Suggest a new feature for python-emc2305
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+A clear and concise description of the feature you'd like to see.
+
+## Use Case
+Describe the problem or use case this feature would solve.
+
+**Example scenario:**
+"As a developer building a fan control system, I need..."
+
+## Proposed Solution
+How do you envision this feature working?
+
+```python
+# Example API usage
+controller.your_proposed_feature(...)
+```
+
+## Alternatives Considered
+What alternatives have you considered? Why would this approach be better?
+
+## Hardware Requirements
+Does this feature require specific EMC2305 capabilities or hardware support?
+
+## Additional Context
+Any other information, links to datasheets, or examples from other libraries.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,21 @@
+---
+name: Question
+about: Ask a question about python-emc2305
+title: '[QUESTION] '
+labels: question
+assignees: ''
+---
+
+## Question
+Your question here.
+
+## Context
+What are you trying to accomplish?
+
+## What I've Tried
+What have you already tried or researched?
+
+## Hardware/Setup (if relevant)
+- Platform:
+- EMC2305 variant:
+- Configuration:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,68 @@
+## Description
+Brief description of what this PR does.
+
+Fixes #(issue number)
+
+## Type of Change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code refactoring
+- [ ] Performance improvement
+- [ ] Test addition/modification
+
+## Hardware Tested
+- [ ] Tested with actual EMC2305 hardware
+- [ ] Hardware variant: (e.g., EMC2305-1-APTR)
+- [ ] Platform: (e.g., Raspberry Pi 4)
+- [ ] I2C address: (e.g., 0x4D)
+- [ ] Fan type: (e.g., Noctua NF-A4x10 PWM)
+
+OR
+
+- [ ] No hardware testing required (docs/tests only)
+- [ ] Hardware testing coordinated with maintainers
+
+## Changes Made
+- Change 1
+- Change 2
+- Change 3
+
+## Testing Performed
+
+### Unit Tests
+```bash
+# Test results
+pytest tests/test_driver_unit.py -v
+```
+
+### Hardware Tests (if applicable)
+```bash
+# Commands run
+i2cdetect -y 0
+python3 examples/python/test_fan_control.py
+```
+
+**Test Results:**
+- [ ] All unit tests pass
+- [ ] Hardware tests pass (if applicable)
+- [ ] No regressions observed
+
+## Checklist
+- [ ] Code follows project style guidelines (PEP 8, Black, isort)
+- [ ] Type hints added for all new functions
+- [ ] Google-style docstrings added
+- [ ] Unit tests added and passing
+- [ ] Hardware tested (or coordinated with maintainers)
+- [ ] Documentation updated (README, docstrings, etc.)
+- [ ] CHANGELOG.md updated
+- [ ] No breaking changes (or documented in CHANGELOG)
+- [ ] All CI checks passing
+- [ ] Commit messages follow conventional commits format
+
+## Additional Notes
+Any additional information that reviewers should know.
+
+## Screenshots/Oscilloscope Traces (if applicable)
+If relevant, include oscilloscope traces of PWM signals, screenshots of monitoring tools, etc.

.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev,config]"
+
+    - name: Lint with ruff
+      run: |
+        ruff check emc2305/
+
+    - name: Check formatting with black
+      run: |
+        black --diff emc2305/ tests/ || true
+        black --check emc2305/ tests/
+
+    - name: Check import sorting with isort
+      run: |
+        isort --check-only emc2305/ tests/
+
+    - name: Type check with mypy
+      run: |
+        mypy emc2305/ --no-error-summary || true
+
+    - name: Run unit tests
+      run: |
+        pytest tests/test_driver_unit.py -v --cov=emc2305 --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+        token: ${{ secrets.CODECOV_TOKEN }}
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package with twine
+      run: twine check dist/*
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-packages
+        path: dist/

.gitignore

@@ -54,6 +54,11 @@ htmlcov/
 # Configuration
 *.toml
 !config/*.toml
+!pyproject.toml
 
 # Deployment
 *.tar.gz
+
+# Debug sessions - hardware-specific debugging documentation
+debug-sessions/*/
+!debug-sessions/README.md

.readthedocs.yml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - config
+        - dev
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+formats:
+  - pdf
+  - epub

CHANGELOG.md

@@ -8,12 +8,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- Initial project structure
-- Basic driver architecture
-- I2C communication layer with cross-process locking
-- Configuration management system
+- Nothing yet
 
-## [0.1.0] - TBD
+## [0.1.0] - 2025-11-24
 
 ### Added
-- First release
+- Initial release of python-emc2305 driver library
+- Complete EMC2305 5-channel PWM fan controller support
+- Dual control modes: PWM (direct duty cycle) and FSC (closed-loop RPM)
+- Per-fan PWM frequency configuration
+- RPM monitoring via tachometer
+- Comprehensive fault detection (stall, spin failure, drive failure)
+- SMBus Alert (ALERT#) hardware interrupt support
+- Software configuration lock with race-condition safety
+- Watchdog timer support
+- Thread-safe operations with atomic register access
+- Cross-process I2C bus locking using filelock
+- YAML/TOML configuration file support
+- Hardware capability auto-detection
+- Full type hints (PEP 561) throughout codebase
+- Comprehensive input validation (I2C addresses, registers, RPM bounds)
+- Mock I2C bus implementation for hardware-independent testing
+- 34 comprehensive unit tests with pytest
+- Google-style docstrings for all public APIs
+- Hardware-validated on EMC2305-1-APTR chip
+- Example scripts for all major use cases
+- Development documentation and hardware integration guides
+
+### Fixed
+- GLBL_EN bit now automatically enabled in driver initialization (critical for PWM output)
+- UPDATE_TIME correctly set to 200ms (500ms breaks PWM control)
+- Drive fail band register addresses corrected (datasheet errors)
+- Minimum drive percentage unrestricted (0-100% range)
+- PWM register readback quantization documented (25% reads as ~30%, physical output correct)
+
+### Changed
+- Configuration system uses sensible defaults with auto-creation
+- PWM output configured as open-drain for better signal integrity
+- PWM polarity set to normal (LOW=run) by default
+
+### Documentation
+- Complete README with quickstart and examples
+- Hardware setup guide with I2C address configuration
+- API documentation for all public classes and methods
+- Production readiness status report
+- Register readback behavior analysis
+- Known limitations and platform requirements
+- PyPI publishing guide
+
+### Infrastructure
+- Modern pyproject.toml configuration
+- Backwards-compatible setup.py
+- GitHub Actions CI/CD workflow
+- Issue and pull request templates
+- Contributing guidelines
+- MIT License
+
+[Unreleased]: https://github.com/moffa90/python-emc2305/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/moffa90/python-emc2305/releases/tag/v0.1.0