Skip to content

Commit 13905a9

Browse files
moffa90moffa90
authored
Merge pull request #1 from moffa90/fix/emc2305-critical-configuration
fixing problems
2 parents 9a380c5 + 34f4aac commit 13905a9

52 files changed

Lines changed: 7659 additions & 765 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug or issue with python-emc2305
4+
title: '[BUG] '
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Bug Description
10+
A clear and concise description of the bug.
11+
12+
## Hardware Setup
13+
- **EMC2305 Variant**: (e.g., EMC2305-1-APTR, EMC2305-2, etc.)
14+
- **I2C Address**: (e.g., 0x4D)
15+
- **Platform**: (e.g., Raspberry Pi 4, Banana Pi M5, x86 Linux)
16+
- **OS**: (e.g., Raspberry Pi OS Bookworm, Ubuntu 22.04)
17+
- **Fan Type**: (e.g., Noctua NF-A4x10 PWM, Generic 4-wire fan)
18+
19+
## Software Environment
20+
- **Python Version**: (e.g., 3.11.2)
21+
- **python-emc2305 Version**: (e.g., 0.1.0)
22+
- **Installation Method**: (pip, source, other)
23+
24+
## Steps to Reproduce
25+
Minimal code example to reproduce the issue:
26+
27+
```python
28+
from emc2305 import FanController
29+
30+
# Your code here
31+
```
32+
33+
## Expected Behavior
34+
What you expected to happen.
35+
36+
## Actual Behavior
37+
What actually happened.
38+
39+
## Error Messages/Logs
40+
```
41+
Paste error messages, tracebacks, or logs here
42+
```
43+
44+
## I2C Communication Traces (if applicable)
45+
```bash
46+
# Output of i2cdetect
47+
$ i2cdetect -y 0
48+
49+
# Register reads/writes that failed
50+
$ i2cget -y 0 0x4d 0x30 b
51+
```
52+
53+
## Additional Context
54+
Any other relevant information, hardware modifications, or observations.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: Feature Request
3+
about: Suggest a new feature for python-emc2305
4+
title: '[FEATURE] '
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Feature Description
10+
A clear and concise description of the feature you'd like to see.
11+
12+
## Use Case
13+
Describe the problem or use case this feature would solve.
14+
15+
**Example scenario:**
16+
"As a developer building a fan control system, I need..."
17+
18+
## Proposed Solution
19+
How do you envision this feature working?
20+
21+
```python
22+
# Example API usage
23+
controller.your_proposed_feature(...)
24+
```
25+
26+
## Alternatives Considered
27+
What alternatives have you considered? Why would this approach be better?
28+
29+
## Hardware Requirements
30+
Does this feature require specific EMC2305 capabilities or hardware support?
31+
32+
## Additional Context
33+
Any other information, links to datasheets, or examples from other libraries.

‎.github/ISSUE_TEMPLATE/question.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
name: Question
3+
about: Ask a question about python-emc2305
4+
title: '[QUESTION] '
5+
labels: question
6+
assignees: ''
7+
---
8+
9+
## Question
10+
Your question here.
11+
12+
## Context
13+
What are you trying to accomplish?
14+
15+
## What I've Tried
16+
What have you already tried or researched?
17+
18+
## Hardware/Setup (if relevant)
19+
- Platform:
20+
- EMC2305 variant:
21+
- Configuration:

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
## Description
2+
Brief description of what this PR does.
3+
4+
Fixes #(issue number)
5+
6+
## Type of Change
7+
- [ ] Bug fix (non-breaking change which fixes an issue)
8+
- [ ] New feature (non-breaking change which adds functionality)
9+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
10+
- [ ] Documentation update
11+
- [ ] Code refactoring
12+
- [ ] Performance improvement
13+
- [ ] Test addition/modification
14+
15+
## Hardware Tested
16+
- [ ] Tested with actual EMC2305 hardware
17+
- [ ] Hardware variant: (e.g., EMC2305-1-APTR)
18+
- [ ] Platform: (e.g., Raspberry Pi 4)
19+
- [ ] I2C address: (e.g., 0x4D)
20+
- [ ] Fan type: (e.g., Noctua NF-A4x10 PWM)
21+
22+
OR
23+
24+
- [ ] No hardware testing required (docs/tests only)
25+
- [ ] Hardware testing coordinated with maintainers
26+
27+
## Changes Made
28+
- Change 1
29+
- Change 2
30+
- Change 3
31+
32+
## Testing Performed
33+
34+
### Unit Tests
35+
```bash
36+
# Test results
37+
pytest tests/test_driver_unit.py -v
38+
```
39+
40+
### Hardware Tests (if applicable)
41+
```bash
42+
# Commands run
43+
i2cdetect -y 0
44+
python3 examples/python/test_fan_control.py
45+
```
46+
47+
**Test Results:**
48+
- [ ] All unit tests pass
49+
- [ ] Hardware tests pass (if applicable)
50+
- [ ] No regressions observed
51+
52+
## Checklist
53+
- [ ] Code follows project style guidelines (PEP 8, Black, isort)
54+
- [ ] Type hints added for all new functions
55+
- [ ] Google-style docstrings added
56+
- [ ] Unit tests added and passing
57+
- [ ] Hardware tested (or coordinated with maintainers)
58+
- [ ] Documentation updated (README, docstrings, etc.)
59+
- [ ] CHANGELOG.md updated
60+
- [ ] No breaking changes (or documented in CHANGELOG)
61+
- [ ] All CI checks passing
62+
- [ ] Commit messages follow conventional commits format
63+
64+
## Additional Notes
65+
Any additional information that reviewers should know.
66+
67+
## Screenshots/Oscilloscope Traces (if applicable)
68+
If relevant, include oscilloscope traces of PWM signals, screenshots of monitoring tools, etc.

‎.github/workflows/ci.yml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
jobs:
10+
test:
11+
name: Test Python ${{ matrix.python-version }}
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
python-version: ["3.9", "3.10", "3.11", "3.12"]
17+
18+
steps:
19+
- uses: actions/checkout@v4
20+
21+
- name: Set up Python ${{ matrix.python-version }}
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: ${{ matrix.python-version }}
25+
cache: 'pip'
26+
27+
- name: Install dependencies
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install -e ".[dev,config]"
31+
32+
- name: Lint with ruff
33+
run: |
34+
ruff check emc2305/
35+
36+
- name: Check formatting with black
37+
run: |
38+
black --diff emc2305/ tests/ || true
39+
black --check emc2305/ tests/
40+
41+
- name: Check import sorting with isort
42+
run: |
43+
isort --check-only emc2305/ tests/
44+
45+
- name: Type check with mypy
46+
run: |
47+
mypy emc2305/ --no-error-summary || true
48+
49+
- name: Run unit tests
50+
run: |
51+
pytest tests/test_driver_unit.py -v --cov=emc2305 --cov-report=xml --cov-report=term
52+
53+
- name: Upload coverage to Codecov
54+
uses: codecov/codecov-action@v4
55+
with:
56+
file: ./coverage.xml
57+
fail_ci_if_error: false
58+
token: ${{ secrets.CODECOV_TOKEN }}
59+
60+
build:
61+
name: Build package
62+
runs-on: ubuntu-latest
63+
64+
steps:
65+
- uses: actions/checkout@v4
66+
67+
- name: Set up Python
68+
uses: actions/setup-python@v5
69+
with:
70+
python-version: "3.11"
71+
72+
- name: Install build dependencies
73+
run: |
74+
python -m pip install --upgrade pip
75+
pip install build twine
76+
77+
- name: Build package
78+
run: python -m build
79+
80+
- name: Check package with twine
81+
run: twine check dist/*
82+
83+
- name: Upload artifacts
84+
uses: actions/upload-artifact@v4
85+
with:
86+
name: dist-packages
87+
path: dist/

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,11 @@ htmlcov/
5454
# Configuration
5555
*.toml
5656
!config/*.toml
57+
!pyproject.toml
5758

5859
# Deployment
5960
*.tar.gz
61+
62+
# Debug sessions - hardware-specific debugging documentation
63+
debug-sessions/*/
64+
!debug-sessions/README.md

‎.readthedocs.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Read the Docs configuration file
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
4+
version: 2
5+
6+
build:
7+
os: ubuntu-22.04
8+
tools:
9+
python: "3.11"
10+
11+
python:
12+
install:
13+
- method: pip
14+
path: .
15+
extra_requirements:
16+
- config
17+
- dev
18+
19+
sphinx:
20+
configuration: docs/conf.py
21+
fail_on_warning: false
22+
23+
formats:
24+
- pdf
25+
- epub

‎CHANGELOG.md‎

Lines changed: 55 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11-
- Initial project structure
12-
- Basic driver architecture
13-
- I2C communication layer with cross-process locking
14-
- Configuration management system
11+
- Nothing yet
1512

16-
## [0.1.0] - TBD
13+
## [0.1.0] - 2025-11-24
1714

1815
### Added
19-
- First release
16+
- Initial release of python-emc2305 driver library
17+
- Complete EMC2305 5-channel PWM fan controller support
18+
- Dual control modes: PWM (direct duty cycle) and FSC (closed-loop RPM)
19+
- Per-fan PWM frequency configuration
20+
- RPM monitoring via tachometer
21+
- Comprehensive fault detection (stall, spin failure, drive failure)
22+
- SMBus Alert (ALERT#) hardware interrupt support
23+
- Software configuration lock with race-condition safety
24+
- Watchdog timer support
25+
- Thread-safe operations with atomic register access
26+
- Cross-process I2C bus locking using filelock
27+
- YAML/TOML configuration file support
28+
- Hardware capability auto-detection
29+
- Full type hints (PEP 561) throughout codebase
30+
- Comprehensive input validation (I2C addresses, registers, RPM bounds)
31+
- Mock I2C bus implementation for hardware-independent testing
32+
- 34 comprehensive unit tests with pytest
33+
- Google-style docstrings for all public APIs
34+
- Hardware-validated on EMC2305-1-APTR chip
35+
- Example scripts for all major use cases
36+
- Development documentation and hardware integration guides
37+
38+
### Fixed
39+
- GLBL_EN bit now automatically enabled in driver initialization (critical for PWM output)
40+
- UPDATE_TIME correctly set to 200ms (500ms breaks PWM control)
41+
- Drive fail band register addresses corrected (datasheet errors)
42+
- Minimum drive percentage unrestricted (0-100% range)
43+
- PWM register readback quantization documented (25% reads as ~30%, physical output correct)
44+
45+
### Changed
46+
- Configuration system uses sensible defaults with auto-creation
47+
- PWM output configured as open-drain for better signal integrity
48+
- PWM polarity set to normal (LOW=run) by default
49+
50+
### Documentation
51+
- Complete README with quickstart and examples
52+
- Hardware setup guide with I2C address configuration
53+
- API documentation for all public classes and methods
54+
- Production readiness status report
55+
- Register readback behavior analysis
56+
- Known limitations and platform requirements
57+
- PyPI publishing guide
58+
59+
### Infrastructure
60+
- Modern pyproject.toml configuration
61+
- Backwards-compatible setup.py
62+
- GitHub Actions CI/CD workflow
63+
- Issue and pull request templates
64+
- Contributing guidelines
65+
- MIT License
66+
67+
[Unreleased]: https://github.com/moffa90/python-emc2305/compare/v0.1.0...HEAD
68+
[0.1.0]: https://github.com/moffa90/python-emc2305/releases/tag/v0.1.0

0 commit comments

Comments
 (0)