Skip to content

Commit

Permalink
Rework & update docs (#74)
Browse files Browse the repository at this point in the history 
* Make device descriptions match state upstream
* Rework pwm_enable value descriptions; add curve control references
* Create a starting PROTOCOLS.MD document
* Add missing fan_min, fan_max and fan_target entries from kernel docs
* Document current and total Aquaero uptime
* Remove extra line break
* Note Aquaero temp offsets, Aquastream XT PWM functionality
* Prettify table in README
* Clean up README and add submitting changes section
* Explain usage and upstreaming differences
* Add naming convention, sensor flapping in README
* Add curve params and explanations
* Misc PROTOCOLS.MD changes before actual work
* Add descriptions to PROTOCOLS for nearly all devices
* Removed separate D5 Next readme
---------

Signed-off-by: Aleksa Savic <savicaleksa83@gmail.com>
  • Loading branch information
@aleksamagicka
aleksamagicka authored Jul 5, 2023
1 parent dda741d commit 083a6d9
Show file tree
Hide file tree
Showing 5 changed files with 647 additions and 156 deletions.
115 changes: 91 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,21 +90,22 @@ Fan 4 current: 22.00 mA

The following devices are supported by this driver, and from which kernel version (if applicable):

| Device | Supported since kernel | Functionality | Microcontroller |
| :------------: | :--------------------: | :----------------------------------------------------------: | :-------------: |
| D5 Next | 5.15 | Various sensors, direct fan PWM control (6.0+) | ? |
| Farbwerk 360 | 5.18 | Temperature sensors | MCF51JU128VHS |
| Farbwerk | 5.19 | Temperature sensors | ? |
| Octo | 5.19 | Temperature and fan sensors, direct fan PWM control | MCF51JU128VLH |
| Quadro | 6.0 | Temperature, flow and fan sensors, direct fan PWM control, flow sensor pulses | MCF51JU128VHS |
| High Flow Next | 6.1 | Various sensors | ? |
| Aquaero 5/6 | 6.3 (sensors), 6.4 (fan control), rest here | Temperature sensors, fan sensors, direct fan PWM control, DC/PWM mode setting, flow sensors | MCF51JM128EVLK |
| Leakshield | 6.5 (sensors), rest here | Various sensors and setting parameters for higher accuracy | ? |
| Aquastream XT | 6.4 (sensors), rest here | Temperature sensors, voltage sensors, pump and fan speed control | ATMEGA8-16MU |
| Aquastream Ultimate | 6.3 | Temperature sensors, pump and fan sensors, pressure and flow | ? |
| Poweradjust 3 | 6.3 | External temperature sensor | ? |

Microcontrollers are noted for general reference, as this driver only communicates through HID reports and does not interact with the device CPU & electronics directly.
| Device | Supported since kernel | Functionality | Microcontroller |
| :-----------------: | :-----------------------------------------: | :----------------------------------------------------------: | :-------------: |
| D5 Next | 5.15 | Various sensors, direct fan PWM control (6.0+) | ? |
| Farbwerk 360 | 5.18 | Temperature sensors | MCF51JU128VHS |
| Farbwerk | 5.19 | Temperature sensors | ? |
| Octo | 5.19 | Temperature and fan sensors, direct fan PWM control | MCF51JU128VLH |
| Quadro | 6.0 | Temperature, flow and fan sensors, direct fan PWM control, flow sensor pulses | MCF51JU128VHS |
| High Flow Next | 6.1 | Various sensors | ? |
| Aquaero 5/6 | 6.3 (sensors), 6.4 (fan control), rest here | Temperature sensors, fan sensors, direct fan PWM control, DC/PWM mode setting, flow sensors | MCF51JM128EVLK |
| Leakshield | 6.5 (sensors), rest here | Various sensors and setting parameters for higher accuracy | ? |
| Aquastream XT | 6.4 (sensors), rest here | Temperature sensors, voltage sensors, pump and fan speed control | ATMEGA8-16MU |
| Aquastream Ultimate | 6.3 | Temperature sensors, pump and fan sensors, pressure and flow | ? |
| Poweradjust 3 | 6.3 | External temperature sensor | ? |

Microcontrollers are noted for general reference, as this driver only communicates through HID reports and does not interact
with the device CPU & electronics directly.

Being a standard `hwmon` driver, it provides readings via `sysfs`, which are easily accessible through `lm-sensors` as usual.

Expand All @@ -113,18 +114,32 @@ Being a standard `hwmon` driver, it provides readings via `sysfs`, which are eas
Only notable parts are listed:

* _aquacomputer_d5next.c_ - the driver itself
* [Reverse engineering docs](re-docs) - WIP, documents explaining how the devices communicate to help understand what
the driver does

* [Reverse engineering docs](re-docs) - documents explaining how the devices communicate to help understand what the driver does
* [Kernel docs](docs) - driver documentation for the kernel

## Installation and usage
It may happen that at times, this repo will be ahead of the kernel in terms of bug fixes or features, as evidenced in the table
in the previous section. Upstreaming progress is tracked in [#81][#81] and the state of the driver in the kernel is tracked in the
[hwmon-state](https://github.com/aleksamagicka/aquacomputer_d5next-hwmon/tree/hwmon-state) branch.

[#81]: https://github.com/aleksamagicka/aquacomputer_d5next-hwmon/issues/81

## Compiling and installation

Ideally, you are on a recent kernel and your distro includes it. If that's the case, you should already have this driver
available! Refer to the table in the overview above to check.

If you're not, or your kernel does not have the driver support for your particular device, you can clone this repository
and compile the driver yourself.
If you're not, or your kernel does not have the driver support for your particular device, you can compile it yourself.

### Kernel 5.18 and later

The driver uses some features only available in kernel 5.18 and later. You can check your kernel version by running:

```commandline
uname -r
```

If you're on an older version, you'll have to do some additional steps, outlined in the next section. Whether any of
the supported or unsupported devices are currently plugged in do not have an effect on the outcome of compilation.

First, clone the repository by running:

Expand All @@ -138,12 +153,64 @@ Then, compile it and insert it into the running kernel, replacing the existing i
make dev
```

You can then try running `sensors` and your devices should be listed there. If the compilation fails, you probably have
an older, possibly LTS kernel that does not have the functionality that this driver uses. In that case, you can modify the driver, following what the compiler says, or upgrade to a newer kernel (see [#28][#28] for an example).
If all went well, you can skip ahead to see how to use it.

If you are sure that you're on a recent kernel and are still getting errors, please open an issue so we can track it down.

### Kernel 5.17 and earlier

These kernels do not have `hwmon_pwm_auto_channels_temp`, so compilation fails. In that case, you can modify
the driver, following what the compiler says, or upgrade to a newer kernel (see [#28][#28] for an example).
That functionality is not needed for basic usage. These kernels are old by now and no extra support will be
provided.

[#28]: https://github.com/aleksamagicka/aquacomputer_d5next-hwmon/issues/28

## Usage

If the driver is inserted, try running `sensors` and your devices should be listed there, if plugged in and supported.

Some devices have controllable fans, pumps or curves; to control them, you can access their sysfs entries under
`/sys/class/hwmon/hwmonX`, where `hwmonX` is the directory of the device that you wish to control. Every `hwmonX`
instance has a `name` entry, so you can be sure what its referring to. For explanation of entries, look up the
[kernel docs](https://github.com/aleksamagicka/aquacomputer_d5next-hwmon/blob/main/docs/aquacomputer_d5next.rst).

### lm-sensors device naming convention

The driver does not control the full name that lm-sensors generates. For example, if you have an Octo, lm-sensors
may name it `octo-hid-3-11`. Only the `octo` part comes from the driver as it detected the device as such. This may
present a problem for users who try to scrape the data from the output of `sensors`, which is a tedious way to go about
that. It's much easier (and more reliable) to read the data from hwmon directly. Related issues: [#40][#40], [#66][#66].

The numbers after the device name may depend on the order in which the driver (or the devices) are loaded by the kernel.
The driver can not control when it gets loaded, only that it's loaded after the HID subsystem.

[#40]: https://github.com/aleksamagicka/aquacomputer_d5next-hwmon/issues/40#issuecomment-1250233049
[#66]: https://github.com/aleksamagicka/aquacomputer_d5next-hwmon/issues/66

### Sensor flapping?

If a fan header is set to a certain speed, but is not physically connected, its values may flap from 0 to around 12V.
This happens because the device repeatedly tries to establish PWM signal and is not a bug in the driver. See [#7][#7]
for a case in point.

[#7]: https://github.com/aleksamagicka/aquacomputer_d5next-hwmon/issues/7

## Contributing

Contributions in form of reporting issues and sending bug fixes and new functionality are very welcome! Without contributors, this driver would never be as feature rich as it is today. Please use the issue tracker and PR functionality for any feedback and patches. Code contributions must follow the [Linux code style rules](https://www.kernel.org/doc/html/v4.10/process/coding-style.html).
Contributions in form of reporting issues, sending bug fixes and new functionality are very welcome! Without
contributors, this driver would never be as feature rich as it is today. Please use the issue tracker and PR
functionality for any feedback and patches. Code contributions must follow the
[Linux code style rules](https://www.kernel.org/doc/html/latest/process/coding-style.html).

### Submitting changes

Pull requests have CI workflows to check if the driver compiles and if the code is following the code style.
If you're sure that a checkpatch warning should not be fixed, please be prepared to elaborate. There's a quick
way to run checkpatch yourself, without bothering with the exact command:

```commandline
make checkpatch
```

All commits must be signed off.
127 changes: 64 additions & 63 deletions docs/aquacomputer_d5next.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,32 +25,34 @@ Description
This driver exposes hardware sensors of listed Aquacomputer devices, which
communicate through proprietary USB HID protocols.

The Aquaero devices expose eight temperature sensors and four PWM controllable fans,
along with their speed (in RPM), power, voltage and current. The PWM fans can be
controlled directly and can be configured as DC or PWM using pwm[1-4]_mode. Note
that Aquaero 5 can set PWM mode only for the fourth fan.
The Aquaero devices expose eight physical, eight virtual and four calculated
virtual temperature sensors, as well as two flow sensors. The fans expose their
speed (in RPM), power, voltage and current. The four fans can also be
controlled directly, as well as configured as DC or PWM using pwm[1-4]_mode.
Temperature offsets can also be controlled.

Additionally, Aquaero devices also expose twenty temperature sensors and twelve flow
sensors from devices connected via Aquabus. The assigned sensor number is
predetermined by the Aquabus address of the device.

For the D5 Next pump, available sensors are pump and fan speed, power, voltage
and current, as well as coolant temperature. Also available through debugfs are
the serial number, firmware version and power-on count. Attaching a fan to it is
optional and allows it to be controlled using temperature curves directly from the
pump. If it's not connected, the fan-related sensors will report zeroes.

The pump can be configured either through software or via its physical
interface. Configuring the pump and the other devices through this driver
is not implemented completely, as it seems to require sending it a complete
configuration. That includes addressable RGB LEDs, for which there is no standard
sysfs interface. Thus, that task is better suited for userspace tools.
and current, as well as coolant temperature and eight virtual temp sensors. Also
available through debugfs are the serial number, firmware version and power-on
count. Attaching a fan to it is optional and allows it to be controlled using
temperature curves directly from the pump. If it's not connected, the fan-related
sensors will report zeroes. The pump can be configured either through software or
via its physical interface.

The Octo exposes four physical and sixteen virtual temperature sensors, as well as
eight PWM controllable fans, along with their speed (in RPM), power, voltage and
current.

The Octo exposes four temperature sensors and eight PWM controllable fans, along
with their speed (in RPM), power, voltage and current.
The Quadro exposes four physical and sixteen virtual temperature sensors, a flow
sensor and four PWM controllable fans, along with their speed (in RPM), power,
voltage and current. Flow sensor pulses are also available.

The Quadro exposes four temperature sensors, a flow sensor and four PWM controllable fans,
along with their speed (in RPM), power, voltage and current.
The Farbwerk and Farbwerk 360 expose four temperature sensors. Additionally,
sixteen virtual temperature sensors of the Farbwerk 360 are exposed.

The High Flow Next exposes +5V voltages, water quality, conductivity and flow readings.
A temperature sensor can be connected to it, in which case it provides its reading
Expand All @@ -62,74 +64,73 @@ filled with coolant. Pump RPM and flow can be set to enhance on-device calculati

The Aquastream XT pump exposes temperature readings for the coolant, external sensor
and fan IC. It also exposes pump and fan speeds (in RPM), voltages, as well as pump
current.
current. Pump and fan speed can be controlled using PWM.

The Aquastream Ultimate pump exposes coolant temp and an external temp sensor, along
with speed, power, voltage and current of both the pump and optionally connected fan.
It also exposes pressure and flow speed readings.

The Poweradjust 3 controller exposes a single external temperature sensor.

The possible values for pwm_enable are:
for D5 Next, Quadro and Octo

= =================
0 no change
1 manual pwm mode
2 PID control mode
3 fan curve mode
= =================

additionally for Quadro and Octo
Configuring listed devices through this driver is not implemented completely, as
some features include addressable RGB LEDs, for which there is no standard sysfs interface.
Thus, some tasks are better suited for userspace tools.

= ===============
4 follow fan1 pwm
5 follow fan2 pwm
6 follow fan3 pwm
7 follow fan4 pwm
= ===============

additionally for Octo

== ===============
8 follow fan5 pwm
9 follow fan6 pwm
10 follow fan7 pwm
11 follow fan8 pwm
== ===============

The Farbwerk and Farbwerk 360 expose four temperature sensors. Depending on the device,
not all sysfs and debugfs entries will be available.
Depending on the device, not all sysfs and debugfs entries will be available.
Writing to virtual temperature sensors is not currently supported.

Usage notes
-----------

The devices communicate via HID reports. The driver is loaded automatically by
the kernel and supports hotswapping.

Configuring fan curves is available on the D5 Next, Quadro and Octo. Possible
pwm_enable values are:

====== ==========================================================
0 Set fan to 100%
1 Direct PWM mode (applies value in corresponding PWM entry)
2 PID control mode
3 Fan curve mode
[4-11] Follow fan[1-8], if available and device supports
====== ==========================================================

Sysfs entries
-------------

=========================== ==============================================================
temp[1-40]_input Physical/virtual temperature sensors (in millidegrees Celsius)
temp[1-4]_offset Temperature sensor correction offset (in millidegrees Celsius)
fan[1-20]_input Pump/fan speed (in RPM) / Flow speed (in dL/h)
fan5_pulses Quadro flow sensor pulses
power[1-8]_input Pump/fan power (in micro Watts)
in[0-7]_input Pump/fan voltage (in milli Volts)
curr[1-8]_input Pump/fan current (in milli Amperes)
pwm[1-8] Fan PWM (0 - 255)
pwm[1-8]_enable Fan control mode
pwm[1-8]_auto_channels_temp Fan control temperature sensors select
pwm[1-4]_mode Fan mode (DC or PWM)
=========================== ===============================================================
=============================== ====================================================================
temp[1-40]_input Physical/virtual temperature sensors (in millidegrees Celsius)
temp[1-4]_offset Temperature sensor correction offset (in millidegrees Celsius)
fan[1-20]_input Pump/fan speed (in RPM) / Flow speed (in dL/h)
fan[1-4]_min Minimal fan speed (in RPM)
fan[1-4]_max Maximal fan speed (in RPM)
fan1_target Target fan speed (in RPM)
fan5_pulses Quadro flow sensor pulses
power[1-8]_input Pump/fan power (in micro Watts)
in[0-7]_input Pump/fan voltage (in milli Volts)
curr[1-8]_input Pump/fan current (in milli Amperes)
pwm[1-8] Fan PWM (0 - 255)
pwm[1-8]_enable Fan control mode
pwm[1-8]_auto_channels_temp Fan control temperature sensors select
pwm[1-4]_mode Fan mode (DC or PWM)
temp[1-8]_auto_point[1-16]_temp Temperature value of point on curve for given fan
temp[1-8]_auto_point[1-16]_pwm PWM value of point on curve for given fan
curve[1-8]_power_min Minimum curve power (curve scales to this)
curve[1-8]_power_max Maximum curve power (curve scales to this)
curve[1-8]_power_fallback Fallback power (if sensor/data is unavailable)
curve[1-8]_start_boost Shortly run fan at 100% until firmware loads curve (0 - no, 1 - yes)
curve[1-8]_power_hold_min Hold minimum power (0 - no, 1 - yes)
=============================== ====================================================================

Debugfs entries
---------------

================ ==================================================
================ =========================================================
serial_number Serial number of the device
firmware_version Version of installed firmware
power_cycles Count of how many times the device was powered on
hw_version Hardware version/revision of device (Aquaero only)
================ ==================================================
current_uptime Current power on device uptime (in seconds, Aquaero only)
total_uptime Total device uptime (in seconds, Aquaero only)
================ =========================================================
Loading

0 comments on commit 083a6d9

Please sign in to comment.