microchip-emc2305

Python Driver for Microchip EMC2305 5-Channel PWM Fan Controller

A hardware-agnostic, production-ready Python driver for the Microchip EMC2305 fan controller with comprehensive feature support and robust I2C communication.

Features

Hardware Support

Chip: Microchip EMC2305-1, EMC2305-2, EMC2305-3, EMC2305-4 (5-channel variants)
Interface: I2C/SMBus with cross-process locking
Platform: Any Linux system with I2C support (Raspberry Pi, Banana Pi, x86, etc.)

Fan Control

✅ 5 independent PWM channels - Control up to 5 fans simultaneously
✅ Dual control modes:
- PWM Mode: Direct duty cycle control (0-100%)
- FSC Mode: Closed-loop RPM control with PID (500-32,000 RPM)
✅ Per-fan PWM frequency - Individual frequency control per channel
✅ Configurable spin-up - Aggressive start for high-inertia fans
✅ RPM monitoring - Real-time tachometer reading

Advanced Features

✅ Fault detection: Stall, spin failure, aging fan detection
✅ SMBus Alert (ALERT#): Hardware interrupt support
✅ Software configuration lock - Protect settings in production (race-condition safe)
✅ Watchdog timer - Automatic failsafe
✅ Hardware capability detection - Auto-detect chip features
✅ Thread-safe operation - Concurrent access protection with atomic operations
✅ Comprehensive validation - I2C addresses (0x00-0x7F), registers (0x00-0xFF), SMBus block limits (32 bytes), and RPM bounds checking

Code Quality

✅ Full type hints (PEP 561)
✅ Comprehensive documentation
✅ Hardware-validated
✅ MIT licensed

Installation

From PyPI (Recommended)

pip install microchip-emc2305

From Source

git clone https://github.com/moffa90/python-emc2305.git
cd emc2305-python
pip install -e .

Optional Dependencies

# For YAML configuration file support
pip install microchip-emc2305[config]

# For development
pip install microchip-emc2305[dev]

Quick Start

Basic PWM Control

from emc2305.driver.i2c import I2CBus
from emc2305.driver.emc2305 import EMC2305, FanConfig

# Initialize I2C bus (with cross-process locking)
i2c_bus = I2CBus(bus_number=0)

# Initialize EMC2305 at default address 0x4D
fan_controller = EMC2305(i2c_bus, device_address=0x4D)

# Configure tachometer for your fan type (IMPORTANT for accurate RPM!)
# edges=3 for 1-pulse/rev, edges=5 for 2-pulse/rev (default), edges=9 for 4-pulse/rev
config = FanConfig(edges=3)  # Adjust based on your fan's tachometer
fan_controller.configure_fan(channel=1, config=config)

# Set fan 1 to 75% duty cycle
fan_controller.set_pwm_duty_cycle(channel=1, percent=75.0)

# Read current RPM
rpm = fan_controller.get_current_rpm(channel=1)
print(f"Fan 1 speed: {rpm} RPM")

Closed-Loop RPM Control (FSC Mode)

from emc2305.driver.emc2305 import EMC2305, ControlMode, FanConfig

# Configure for FSC mode
config = FanConfig(
    control_mode=ControlMode.FSC,
    min_rpm=1000,
    max_rpm=4000,
    pid_gain_p=4,  # Proportional gain
    pid_gain_i=2,  # Integral gain
    pid_gain_d=1,  # Derivative gain
)

fan_controller.configure_fan(channel=1, config=config)
fan_controller.set_target_rpm(channel=1, rpm=3000)

# Hardware PID will maintain 3000 RPM automatically

Fault Detection

from emc2305.driver.emc2305 import FanStatus

# Check fan status
status = fan_controller.get_fan_status(channel=1)

if status == FanStatus.STALLED:
    print("Fan 1 is stalled!")
elif status == FanStatus.DRIVE_FAILURE:
    print("Fan 1 is aging (drive failure)")
elif status == FanStatus.OK:
    print("Fan 1 is operating normally")

Alert/Interrupt Handling

# Enable alerts for fan 1
fan_controller.configure_fan_alerts(channel=1, enabled=True)

# Check if any alerts are active
if fan_controller.is_alert_active():
    # Get which fans have alerts
    alerts = fan_controller.get_alert_status()
    for channel, has_alert in alerts.items():
        if has_alert:
            print(f"Fan {channel} has an alert condition")

    # Clear alert status
    fan_controller.clear_alert_status()

Tachometer Configuration

Understanding the `edges` Parameter

The edges parameter is critical for accurate RPM readings. It must match your fan's tachometer signal:

Fan Type	Pulses/Revolution	`edges` Setting
1-pole	1	`edges=3`
2-pole	2	`edges=5` (default)
3-pole	3	`edges=7`
4-pole	4	`edges=9`

How to determine your fan's pulse count:

Check the fan datasheet for "FG Signal" or "Tachometer" specification
Or use trial and error: the correct setting gives RPM readings that scale linearly with PWM

Example: Configuring for Different Fan Types

from emc2305.driver.emc2305 import EMC2305, FanConfig
from emc2305.driver.i2c import I2CBus

bus = I2CBus(bus_number=0)
controller = EMC2305(i2c_bus=bus, device_address=0x4D)

# For a 1-pulse-per-revolution fan (common in high-speed fans)
config_1pole = FanConfig(edges=3)
controller.configure_fan(1, config_1pole)

# For a standard 2-pulse-per-revolution fan
config_2pole = FanConfig(edges=5)
controller.configure_fan(2, config_2pole)

# For a 4-pulse-per-revolution fan (some server fans)
config_4pole = FanConfig(edges=9)
controller.configure_fan(3, config_4pole)

Diagnosing Incorrect RPM Readings

If your RPM readings seem wrong (too high, too low, or not scaling with PWM):

# Test different edges configurations
import time

controller.set_pwm_duty_cycle(1, 100)  # Set to full speed
time.sleep(2)  # Wait for fan to stabilize

for edges in [3, 5, 7, 9]:
    config = FanConfig(edges=edges)
    controller.configure_fan(1, config)
    time.sleep(0.5)
    rpm = controller.get_current_rpm(1)
    print(f"edges={edges}: {rpm} RPM")

# The correct setting will show a reasonable RPM that matches
# your fan's rated speed at 100% PWM

Hardware Requirements for Tachometer

Pull-up resistor: EMC2305 TACH pins are open-drain and require a 10kΩ pull-up to 3.3V
Signal voltage: TACH signal should swing from 0V to VDD (typically 3.3V)
Wiring: Connect fan's TACH wire to EMC2305's TACHx pin for the corresponding channel

Hardware Setup

I2C Address Configuration

The EMC2305 I2C address is configurable via the ADDR_SEL pin:

ADDR_SEL	Address
GND	0x4C
VDD	0x4D
SDA	0x5C
SCL	0x5D
Float	0x5E/0x5F

Default in this driver: 0x61 (adjust for your hardware)

I2C Bus Permissions

Ensure your user has I2C access:

# Add user to i2c group
sudo usermod -aG i2c $USER

# Or set permissions
sudo chmod 666 /dev/i2c-*

Verify Hardware

# Install i2c-tools
sudo apt-get install i2c-tools

# Scan I2C bus 0
i2cdetect -y 0

# You should see your EMC2305 at its configured address

Configuration File

Optional YAML configuration support:

# ~/.config/emc2305/emc2305.yaml

i2c:
  bus: 0
  lock_enabled: true

emc2305:
  address: 0x61
  pwm_frequency_hz: 26000

  fans:
    1:
      name: "CPU Fan"
      control_mode: "fsc"
      min_rpm: 1000
      max_rpm: 4500
      default_target_rpm: 3000
      pid_gain_p: 4
      pid_gain_i: 2
      pid_gain_d: 1

    2:
      name: "Case Fan"
      control_mode: "pwm"
      default_duty_percent: 50

Load configuration:

from emc2305.settings import ConfigManager

config_mgr = ConfigManager()
config = config_mgr.load()

# Use loaded configuration
fan_controller = EMC2305(
    i2c_bus,
    device_address=config.emc2305.address,
    pwm_frequency=config.emc2305.pwm_frequency_hz
)

Architecture

┌─────────────────────────────────────┐
│   Application Code                  │
├─────────────────────────────────────┤
│   EMC2305 Driver (emc2305.py)       │  ← High-level API
│   - Fan control                     │
│   - RPM monitoring                  │
│   - Fault detection                 │
├─────────────────────────────────────┤
│   I2C Communication (i2c.py)        │  ← Low-level I/O
│   - SMBus operations                │
│   - Cross-process locking           │
├─────────────────────────────────────┤
│   Hardware (EMC2305 chip)           │
└─────────────────────────────────────┘

API Documentation

Main Classes

`EMC2305`

Main driver class for fan control.

Methods:

set_pwm_duty_cycle(channel, percent) - Set PWM duty cycle
set_target_rpm(channel, rpm) - Set target RPM (FSC mode)
get_current_rpm(channel) - Read current RPM
get_fan_status(channel) - Get fault status
configure_fan(channel, config) - Apply full configuration
lock_configuration() - Lock settings (irreversible until reset)
get_product_features() - Read hardware capabilities

`FanConfig`

Configuration dataclass for fan channels.

Fields:

control_mode: PWM or FSC
min_rpm, max_rpm: RPM limits
min_drive_percent: Minimum PWM percentage
pid_gain_p/i/d: PID tuning parameters
spin_up_level_percent, spin_up_time_ms: Spin-up configuration
pwm_divide: Per-fan PWM frequency divider

`I2CBus`

Low-level I2C communication with locking.

Methods:

read_byte(address, register)
write_byte(address, register, value)
read_block(address, register, length)
write_block(address, register, data)

Examples

See examples/python/ directory:

test_fan_control.py - Basic PWM control
test_rpm_monitor.py - RPM monitoring
test_fsc_mode.py - Closed-loop control
test_fault_detection.py - Fault handling

Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=emc2305 --cov-report=html

# Run specific test
pytest tests/test_emc2305_init.py -v

Note: Most tests require actual EMC2305 hardware.

Compatibility

Supported Python Versions

Python 3.9+
Python 3.10+
Python 3.11+
Python 3.12+

Supported Platforms

Linux (any distribution with I2C support)
Raspberry Pi OS
Banana Pi
Generic embedded Linux

Hardware Requirements

I2C bus interface
Microchip EMC2305 (any variant: EMC2305-1/2/3/4)
Appropriate fan connectors and power supply

Contributing

Contributions are welcome! This project aims to provide a comprehensive, hardware-agnostic driver for the EMC2305.

Development Setup

git clone https://github.com/moffa90/python-emc2305.git
cd emc2305-python
pip install -e ".[dev]"

Code Style

Follow PEP 8
Use type hints (PEP 484)
Document all public APIs
Run tests before submitting

License

MIT License - see LICENSE file for details.

References

Support

Issues: GitHub Issues
Documentation: GitHub Wiki
Discussions: GitHub Discussions

Donate

If you find this project useful, consider supporting its development:

Acknowledgments

This driver implements the complete EMC2305 register map and feature set as documented in the Microchip datasheet. Special thanks to the community contributors who helped validate and improve this driver.

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github		.github
config		config
debug-sessions		debug-sessions
docs		docs
emc2305		emc2305
examples/python		examples/python
scripts		scripts
tests		tests
.gitignore		.gitignore
.readthedocs.yml		.readthedocs.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
PRODUCTION_READINESS.md		PRODUCTION_READINESS.md
PYPI_PUBLISHING.md		PYPI_PUBLISHING.md
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

License

moffa90/python-emc2305

Folders and files

Latest commit

History

Repository files navigation

microchip-emc2305

Features

Hardware Support

Fan Control

Advanced Features

Code Quality

Installation

From PyPI (Recommended)

From Source

Optional Dependencies

Quick Start

Basic PWM Control

Closed-Loop RPM Control (FSC Mode)

Fault Detection

Alert/Interrupt Handling

Tachometer Configuration

Understanding the edges Parameter

Example: Configuring for Different Fan Types

Diagnosing Incorrect RPM Readings

Hardware Requirements for Tachometer

Hardware Setup

I2C Address Configuration

I2C Bus Permissions

Verify Hardware

Configuration File

Architecture

API Documentation

Main Classes

EMC2305

FanConfig

I2CBus

Examples

Testing

Compatibility

Supported Python Versions

Supported Platforms

Hardware Requirements

Contributing

Development Setup

Code Style

License

References

Support

Donate

Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 2

Uh oh!

Languages

Understanding the `edges` Parameter

`EMC2305`

`FanConfig`

`I2CBus`

Packages