Tempi/README.md

# Tempi
Control your Raspberry Pi's temperature with a fan.

## Description
This program control a GPIO pin depending on the temperature of your CPU. It is thought of as a way to regulate the CPU's temperature by connecting a fan to the GPIO and letting the program check the temperature at a regular interval in the background.

## Installation
### From Crates.io
```sh
cargo install tempi
```

### From source
First you need to [install Rust]. Then you can do the Rust's standard installation procedure:
```sh
git clone https://zykino.net/gitea/zykino/Tempi.git
cd Tempi
cargo build --release
```

If you prefer to cross-compile from a non raspberry computer I followed the manual instructions at <https://mudge.name/2019/01/02/cross-compiling-rust-for-a-raspberry-pi-on-travis-ci/>. Once build, transfert the binary to your target and test it.
```sh
scp target/arm-unknown-linux-gnueabihf/release/tempi pi@<YOUR_PI_IP>:<PATH_TO_WHERE_YOU_WANT_YOUR_BINARY>
```

## Usage
To use the application you just have to start the `tempi` executable. If you want to use it on a daily basis, it is recommanded to start the application at logon or startup.

## Configuration
The only way to configure `tempi` is with a configuration file. The configuration file is written in yaml, you can copy one of the examples below and twist the values as you like.  
On Linux the configuration file is `~/.config/tempi/tempi.yml`.

By default `tempi` will control the pin 18 (physical 12) in an `Hysteresis` mode. The configuration file corresponding is the following:
```yaml
---
check_interval:
  secs: 10
  nanos: 0
mode:
  Hysteresis:               # Either Hysteresis or Pwm ith th appropriate parameters
    max_temperature: 70.0
    hysteresis: 10.0
    bcm_pin: 18
verbosity_mode: Human       # One of Human, Machine or Quiet
```

If you prefer using the `PWM` mode you first need to follow this instructions to [enable PWM on your Raspberry Pi]. It is also recommended to let [the members of the gpio group configure PWM] without being root. Then you can use and adapt the following configuration file:
```yaml
---
check_interval:
  secs: 10
  nanos: 0
mode:
  Pwm:
    max_temperature: 70.0
    min_temperature: 60.0
    frequency: 1          # You should tweak this value depending on your fan and expected percentage of normal usage.
    channel: Pwm0
verbosity_mode: Human
```

## State of the project
I feel that this project is fully featured for what it is right now: a raspberry pi temperature controler.  
If someone would create a circuit using a 5V PIN and a GPIO as switch, I would love to elaborate and test new cooling strategies.

It is also still possible to support more boards and have a better output for logging/plotting on an other application.

Code wise it is one of my first Rust projets so any hint on how to upgrade my code and the ergonomics of `tempi` is welcome. Including adding tests, better usage of error, understanding if I should use `embedded-hal`, ...  
I also need to document the code and maybe expose an interface to use it as a library.

[install Rust]: https://www.rust-lang.org/tools/install
[enable PWM on your Raspberry Pi]: https://docs.golemparts.com/rppal/0.11.2/rppal/pwm/#pwm-channels
[the members of the gpio group configure PWM]: https://docs.golemparts.com/rppal/0.11.2/rppal/pwm/#using-pwm-without-superuser-privileges-sudo