#3 merge root README.md into doc

mstrthealias · Mar 3, 2020 · 9169de2 · 9169de2
1 parent 3e6cea3
commit 9169de2
Show file tree

Hide file tree

Showing 10 changed files with 182 additions and 163 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,14 @@
 # Teensy Fan Controller
 
-*Work in progress... An initial release is not yet available. However, you're welcome to build and flash using Arduino Studio (with Teensyduino add-on).*
+*Work in progress... An initial release is not yet available.*
 
 A PC fan controller with temperature sensor input, for **Teensy 3.x** USB Development Board(s).
 
 Supports up to 6 fans (4pin/PWM), and up to 5 temperature sensors (thermistors). Each fan may individually operate in PID, temperature-percent table, or fixed-percent control modes.
 
 Designed to control radiator fans on a PC water cooling loop (to maintain supply water temperature), but may be configured for other purposes (for example, see [Hardware/Router cooling demo][2]).
 
+
 ## Hardware
 
 Hardware is described in the [Hardware][5] folder:
@@ -16,39 +17,6 @@ Hardware is described in the [Hardware][5] folder:
 * [Prototype - Simple PCB][4]: requires PCB fabrication (gerber files provided) and through-hole soldering
 * [Router Cooling Demo][2]: breadboard based experiment using a single fan/single sensor to cool a router to a specific temperature
 
-## Interface
-
-The Teensy Micro USB port is used to configure and monitor the fan controller.
-
-Note: it is possible to connect the Micro USB port to an internal motherboard USB 1.1/2.0 header, by making a custom cable, or purchasing a *Micro USB 5pin Male to 1x 5Pin Female 0.1" USB Header PCB Motherboard Cable*.
-
-
-## Control Modes
-
-### PID Control Mode
-
-The PID controllers satisfy a temperature setpoint, by changing fan PWM duty cycle(s).  By default, all fans operate in PID mode for supply water temperature control.
-
-The fan controller may operate up to 4 PID controllers, one per the following temperature sensors: supply water temp, case temp, aux1 temp, and aux2 temp.
-
-
-#### Supply Water Temperature Control / Setpoint Adjustment
-
-TODO
-
-A supply water temperature setpoint reset schedule is enabled by default, to adjust for room and/or case temperature changes. By default, the setpoint adjusts between 28°C and 31.5°C, at 0.25°C increments. If a case temperature sensor is connected, the reset schedule is limited by a difference between supply water and case temperature (allowing fan spin-up when case temperature does not change).
-
-### Percent-Table Mode
-
-Each fan may be individually configured to operate using its own *temperature to fan %-table*.  This is like BIOS custom fan configurations.
-
-Any one of the five temperature sensors, or DeltaT (return temp - supply temp), may be used as a temperature source.
-
-
-### Fixed Mode
-
-Each fan may be individually configured to operate using a fixed speed (percent).
-
 
 ## Software
 
@@ -61,90 +29,15 @@ Each fan may be individually configured to operate using a fixed speed (percent)
 [Fork of liquidtux](https://github.com/mstrthealias/liquidtux): Linux kernel module for reading temperatures and fan RPMs using *lm-sensors* (or *psensor*, as used below).  Tested on Ubuntu 18.04.
 
 
-## PID Usage and Example
-
-The default configuration works well on a PC with a water-cooled CPU and an air-cooled GPU:
-
-- Uses a supply water temperature sensor and a case temperature sensor
-- Controls supply water temperature to 2-3°C above case temperature (initial setpoint is 28°C)
-- Fan output percent is generally between 45%-60%, unless CPU is loaded
-- If case temperature is within 2°C of supply water temperature, and fan output percent is greater than 60% for 20 seconds, the setpoint increases by 0.25°C
-
-
-For example, the fans are controlled to keep supply water temperature at setpoint:
-
-![Example 1.1](doc/images/ex1.1.jpg?raw=true 'Example 1.1')
-
-
-In the same dataset as *Example 1.1*, and only plotting fan RPMs and DeltaT (return temp - supply temp), observe the fan speeds trailing DeltaT (which represents CPU load in the following example):
-
-![Example 1.2](doc/images/ex1.2.jpg?raw=true 'Example 1.2')
-
-
-Next, an air-cooled GPU is used for about 30 minutes, showing *setpoint adjustment* keeping fan speeds within the configured range:
-
-![Example 2](doc/images/ex2.jpg?raw=true 'Example 2')
-
-
-The same behavior is observed, except caused by room temperature changes, in this example:
-
-![Example 3](doc/images/ex3.jpg?raw=true 'Example 3')
-
-
-When only the CPU is loaded, the setpoint temperature does not change, and the fans speed up as needed:
-
-![Example 4](doc/images/ex4.jpg?raw=true 'Example 4')
-
-
-### Considerations
-
-A case temperature sensor should be used if using *setpoint adjustment* with PID supply water temperature control:
-
-- When under load and without a case temperature sensor, the setpoint will increase to the maximum before allowing fan speedup
-- Without a case temperature sensor, *setpoint adjustment* may achieve the same result as using a supply water *temperature to fan %-table*
-
-
-## Configuration
-TODO
-
-
-### Fan(s)
-TODO
-
-#### Hardware Setup
-TODO
-- PWM Pin
-- RPM Pin
-
-### Sensor(s)
-TODO
-
-Note: sensors are labeled as supply water temp, return water temp, case temp, aux1 temp, and aux2 temp.
-
-#### Hardware Setup
-TODO
-- Pin
-- Thermistor Beta Coefficient
-- Thermistor Nominal Resistance (fe. 10k, 50k)
-- Thermistor Series Resistance (value of series resistor, fe. 10000 for 10k 1% resistor)
-
-### PID Setup
-TODO
-
+## Compatibility
 
+- Teensy 3.5
+- Teensy 3.2
 
 
 ## Notes
 
-Releases will be published for supported devices. For now, Teensy 3.x should be used (although prototype hardware is pin-compatible with Teensy LC, 3.x, and 4.0).
-
-If used on a Teensy LC, the config will not be savable on the device (and will always load compiled defaults on start).
-
-
-### Compatibility
-
-- Teensy 3.5
-- Teensy 3.2
+Releases will be published for supported devices. Teensy 3.x should be used for development.
 
 
 ### Code

diff --git a/doc/Examples/PC water cooling demo 1.md b/doc/Examples/PC water cooling demo 1.md
@@ -3,3 +3,40 @@
 TODO
 
 
+## PID Usage and Example
+
+TODO
+
+The default configuration works well on a PC with a water-cooled CPU and an air-cooled GPU:
+
+- Uses a supply water temperature sensor and a case temperature sensor
+- Controls supply water temperature to 2-3°C above case temperature (initial setpoint is 28°C)
+- Fan output percent is generally between 45%-60%, unless CPU is loaded
+- If case temperature is within 2°C of supply water temperature, and fan output percent is greater than 60% for 20 seconds, the setpoint increases by 0.25°C
+
+
+For example, the fans are controlled to keep supply water temperature at setpoint:
+
+![Example 1.1](../images/ex1.1.jpg?raw=true 'Example 1.1')
+
+
+In the same dataset as *Example 1.1*, and only plotting fan RPMs and DeltaT (return temp - supply temp), observe the fan speeds trailing DeltaT (which represents CPU load in the following example):
+
+![Example 1.2](../images/ex1.2.jpg?raw=true 'Example 1.2')
+
+
+Next, an air-cooled GPU is used for about 30 minutes, showing *setpoint adjustment* keeping fan speeds within the configured range:
+
+![Example 2](../images/ex2.jpg?raw=true 'Example 2')
+
+
+The same behavior is observed, except caused by room temperature changes, in this example:
+
+![Example 3](../images/ex3.jpg?raw=true 'Example 3')
+
+
+When only the CPU is loaded, the setpoint temperature does not change, and the fans speed up as needed:
+
+![Example 4](../images/ex4.jpg?raw=true 'Example 4')
+
+
diff --git a/doc/Examples/Router cooling demo.md b/doc/Examples/Router cooling demo.md
@@ -1,2 +1,27 @@
-# Prototype (based on Schmart Board)
+# Router Cooling Demo
 
+The controller is configured to cool a temperature sensor (placed between a desk router and switch) to a specific temperature.
+
+
+## Hardware Requirements
+
+1. A Teensy Fan Controller (fe. [Breadboard][1], [Schmart Board prototype][2], [Simple PCB][3])
+1. One Teensy 3.x with headers (previously *flashed with Teensy Fan Controller*)
+1. A Micro USB cable
+1. One 12v power supply (up to 15V should be OK)
+1. One PWM PC fan (80mm, 120mm, 140mm)
+1. Wires
+
+[1]: ../hardware/breadboard
+[2]: ../hardware/prototype
+[3]: ../hardware/simple-pcb
+
+
+## Sensor and fan placement
+
+- The temperature sensor is placed between the cases of a router stacked on top of a switch
+- The fan is pointed at the router/switch
+
+TODO 
+
+![Router cooling demo - sensor/fan setup](../images/rcd.setup.jpg)
diff --git a/doc/Hardware/Breadboard.md b/doc/Hardware/Breadboard.md
@@ -1,13 +1,11 @@
-# Teensy Fan Controller - Router Cooling Demo
-
-The controller is configured to cool a temperature sensor (placed between a desk router and switch) to a specific temperature.
+# Breadboard Prototype
 
 A single PWM fan and single sensor is connected to a Teensy 3.2 using a breadboard.
 
 
 ## Hardware Requirements
 
-1. One Breadboard, or a Teensy Fan Controller board (fe. Simple 001)
+1. One Breadboard
 1. One Teensy 3.x with headers (previously *flashed with Teensy Fan Controller*)
 1. A Micro USB cable
 1. One 10k thermistor (fe. [Adafruit 10K Precision Epoxy Thermistor - 3950 NTC][1])
@@ -22,11 +20,11 @@ A single PWM fan and single sensor is connected to a Teensy 3.2 using a breadboa
 
 ## Hardware Setup
 
-[![Breadboard wiring diagram](../../doc/images/rcd.thumb.breadboard.png)](../../doc/images/rcd.breadboard.png) [![Schematic](../../doc/images/rcd.thumb.schematic.png)](../../doc/images/rcd.schematic.png) [![Board example](../../doc/images/rcd.thumb.board.png)](../../doc/images/rcd.board.png)
+[![Breadboard wiring diagram](../../doc/images/rcd.thumb.breadboard.png)](../../doc/images/rcd.breadboard.png) [![Breadboard example](../../doc/images/rcd.thumb.photo.png)](../../doc/images/rcd.photo.png)
 
 Steps to set up a breadboard with a Teensy 3.2, a single fan, a single temperature sensor, and a 12v power supply:
 
-1. Place the **Teensy** into the top end of the breadboard (Teensy GND on breadboard row 1)
+1. Place the **Teensy** into the top end of the breadboard (**Teensy GND** on breadboard **row 1**)
 1. Place a **10k Ohm resistor** between **Teensy AREF** (breadboard **I4**) and **Teensy A5** (breadboard **I8**)
 1. Place a **diode** with anode at **Teensy D5** (breadboard **A6**) and cathode at breadboard **row 22** (use a wire if needed)
 1. Connect **Teensy GND** (breadboard **A1**) to the **GND bus** on the **left side** of the breadboard
@@ -43,30 +41,7 @@ Steps to set up a breadboard with a Teensy 3.2, a single fan, a single temperatu
    1. Connect **power supply GND** to the **GND bus** on the **left side** of the breadboard
    1. Connect **power supply +12V** to the **PWR bus** on the **left side** of the breadboard
 
-### Sensor and fan placement
-
-TODO 
-
-<div class="ctbl-wrapper">
-<table>
-<tbody>
-<tr>
-<td>
-
-* The temperature sensor is placed between the cases of a router stacked on top of a switch
-* The fan is pointed at the router/switch
-
-</td>
-<td align="right">
-
-![Router cooling demo - sensor/fan setup](../../doc/images/rcd.setup.jpg)
-
-</td>
-</tr>
-</tbody>
-</table>
-</div>
-
+[![Schematic](../../doc/images/rcd.thumb.schematic.png)](../../doc/images/rcd.schematic.png) [![Board example](../../doc/images/rcd.thumb.board.png)](../../doc/images/rcd.board.png)
 
 ## Software Setup
 
@@ -80,12 +55,6 @@ Thermistor pin 1 | A5 (pin 19)
 
 Configure the software using the information given above:
 
-<div class="ctbl-wrapper">
-<table>
-<tbody>
-<tr>
-<td>
-
 1. Connect the **Micro USB cable** to the **Teensy 3.x**
 1. Launch **Teensy Fan Controller UI**
 1. Select **Menu** > **Hardware Setup**
@@ -112,17 +81,9 @@ Configure the software using the information given above:
     Fan 6: RPM Pin | 0
 
 1. Click **Save**
-1. Click the **back arrow** on the top-left
-
-</td>
-<td align="right">
-
-![Router cooling demo - fan settings](../../doc/images/rcd.sw.fansettings.jpg)
-
-</td>
-</tr>
-</tbody>
-</table>
-</div>
 
 
+{% hint style="info" %}
+After making changes, the Hardware Setup screen should appear as:
+![Breadboard - fan settings](../../doc/images/rcd.sw.fansettings.jpg)
+{% endhint %}
diff --git a/doc/README.md b/doc/README.md
@@ -4,6 +4,45 @@ A PC fan controller with temperature sensor input, for **Teensy 3.x** USB Develo
 
 Supports up to 6 fans (4pin/PWM), and up to 5 temperature sensors (thermistors). Each fan may individually operate in PID, temperature-percent table, or fixed-percent control modes.
 
-Designed to control radiator fans on a PC water cooling loop (to maintain supply water temperature), but may be configured for other purposes (for example, see [Hardware/Router cooling demo][2]).
+Designed to control radiator fans on a PC water cooling loop (to maintain supply water temperature), but may be configured for other purposes (for example, see [Hardware/Router cooling demo][1]).
+
+[1]: demo/router-cooling-demo
+
+
+## Hardware
+
+The following hardware has been used with Teensy Fan Controller:
+
+- [Breadboard][3]: breadboard example with a single fan/single sensor
+- [Prototype - Hand-made (Schmart Board based)][4]: uses over-the-shelf components
+- [Prototype - Simple PCB][5]: requires PCB fabrication (gerber files provided) and through-hole soldering
+
+Related files are available in the [TeensyFanController/Hardware][2] folder.
+
+[2]: https://github.com/mstrthealias/TeensyFanController/tree/master/Hardware
+[3]: breadboard
+[4]: prototype
+[5]: simple-pcb
+
+### Hardware Interface
+
+The Teensy Micro USB port is used to configure and monitor the fan controller.
+
+{% hint style="info" %}
+It is possible to connect the Micro USB port to an internal motherboard USB 1.1/2.0 header, by making a custom cable, or purchasing a *Micro USB 5pin Male to 1x 5Pin Female 0.1" USB Header PCB Motherboard Cable*.
+{% endhint %}
+
+
+## Software
+
+### Qt UI
+
+[Teensy Fan Controller UI (Qt5)](https://github.com/mstrthealias/TFC-ui): provides a user interface to configure and monitor the fan controller.
+
+### Linux Kernel module (hwmon)
+
+[Fork of liquidtux](https://github.com/mstrthealias/liquidtux): Linux kernel module for reading temperatures and fan RPMs using *lm-sensors* (or *psensor*, as used below).  Tested on Ubuntu 18.04.
+
+
 
 
diff --git a/doc/TOC.md b/doc/TOC.md
@@ -3,6 +3,11 @@
 * [Teensy Fan Controller](README.md)
 
 
+## Usage
+
+* [Fan Control Modes](Usage/Fan Control Modes.md)
+
+
 ## Hardware
 
 * [Prototype](Hardware/Prototype.md)