Buccaneer Fan Controller

This project provides a command-line application written in Rust for controlling Corsair Hydro Platinum and Commander Pro fan controllers. It implements a PID (Proportional-Integral-Derivative) controller to automatically regulate fan speeds based on a chosen target temperature, aiming to maintain optimal thermal performance for your system.

Features

• PID-based Temperature Regulation: Dynamically adjusts fan duty cycles to maintain a user-defined target temperature.
• Corsair Device Support: Compatible with Corsair Hydro Platinum AIO coolers and Commander Pro fan controllers.
• Real-time Monitoring (TUI): Displays live temperature graphs, fan speeds, and device status through a text-based user interface (TUI).
• Configurable Parameters: Allows setting target temperature and control loop delta (tick rate) via command-line arguments.
• Mock Device Mode: Includes mock implementations for development and testing without physical hardware.

Supported Devices

• Corsair Hydro Platinum series AIO Coolers
• Corsair Commander Pro fan controllers

How It Works

The application uses a PID (Proportional-Integral-Derivative) control loop to manage the cooling performance.

1. Temperature Sensing: It periodically reads temperature data from the connected Corsair devices.
2. Error Calculation: The difference between the current temperature and the desired target temperature is calculated.
3. Fan Duty Adjustment: The PID controller uses this error, its rate of change (derivative), and the accumulated error (integral) to determine the appropriate fan duty cycle. Fans are typically run at a base speed (e.g., 20%) and adjusted up to 100% based on the controller's output.
4. Feedback Loop: The new fan duty cycle is applied to the cooling devices, and the process repeats, continuously seeking to minimize the temperature error.

Usage

Prerequisites

• Rust toolchain (stable or nightly)
• hidapi library (ensure necessary system dependencies for hidapi are installed, e.g., libudev-dev on Debian/Ubuntu, hidapi or hidapi-libusb on other systems).

Building and Running

1. Clone the repository:

   git clone https://github.com/karinushka/buccaneer.git
   cd buccaneer

2. Build the application:

   cargo build --release

3. (optional) Adjust permissions of your /dev/hidraw* devices:

   chgrp usb /dev/hidraw*
   chmod 664 /dev/hidraw*

4. Run the application: If you do not have permissions to /dev/hidraw* device files, you may need elevated privileges (e.g., sudo on Linux) to access HID devices.

   # Run with default settings (target temp 42°C, delta 5 seconds)
   cargo run --release
   
   # Set a custom target temperature (e.g., 38°C)
   cargo run --release -- -t 38
   
   # Set a custom delta (e.g., update every 10 seconds)
   cargo run --release -- -d 10
   
   # Run in mock device mode (for testing without hardware)
   cargo run --release -- -m

Command-line Arguments

• -t, --target <TEMPERATURE>: Sets the target temperature in Celsius (0-100). Default: 42.
• -d, --delta <SECONDS>: Sets the delta between operational ticks in seconds (0-100). This is how often the controller updates. Default: 5.
• -m, --mock: Runs the application in mock device mode, simulating cooling devices for testing purposes.

TUI Controls

• q: Quit the application.
• Tab: Cycle focus between multiple Regulator instances (switches focus between Commander Pro and HydroPlatinum devices).
• j: Decrease the target temperature for the focused regulator.
• k: Increase the target temperature for the focused regulator.

Code Structure

• src/main.rs: The main application entry point. It parses command-line arguments, initializes devices (or mock devices), sets up the PID controllers, and manages the TUI.
• src/cooler.rs: Defines the core traits (Cooler and Sensor) for abstracting cooling device interactions. It also contains the open_device function for discovering HID devices and a MockCooler for testing.
• src/hydro_platinum.rs: Implements the Cooler and Sensor traits for Corsair Hydro Platinum devices, handling their specific communication protocols and commands. It also includes a MockHydroDevice.
• src/commander_pro.rs: Implements the Cooler and Sensor traits for Corsair Commander Pro devices, managing their unique commands and responses. It includes a MockCommanderDevice for testing.

Dependencies

This project relies on the following Rust crates:

• hidapi: For interacting with HID (Human Interface Device) USB devices.
• clap: A powerful command-line argument parser.
• ratatui: A library for building text-based user interfaces (TUIs).
• log: A logging facade.
• env_logger: An opinionated log implementation.

License

This project is licensed under the MIT license - see the LICENSE.txt file for details.

Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.