# Installing Dials

Dials puts your lights, mouse speed and fan speed in one window, with setups that switch by themselves when a game
starts.

**Works on:** Linux, with Python 3.10 or newer. Windows is planned and not available yet.

## What it controls today

| Device | What | Status |
|---|---|---|
| Motherboards, graphics cards, RAM and mice that OpenRGB supports | Colour | Works through OpenRGB |
| Razer Basilisk V3 | Mouse speed | Tested on a real mouse |
| Keychron V1 (QMK/VIA) | Keyboard colour | Tested on a real keyboard |
| Boards with an ITE IT8689E fan chip (for example Gigabyte B760M DS3H AX) | Fan modes | Tested on a real PC; needs a one-time setup |

Other mice, keyboards and fan chips don't work yet. They show up as missing, not broken.

## Install (one line)
Open a terminal and paste:
```
curl -fsSL https://dials-5ng.pages.dev/install.sh | sh
```
It downloads Dials, checks the file's SHA-256, and installs Dials for you only, with no password. If Python's window
toolkit (Tkinter) is missing, it shows the command for your distro and asks before running it; that is the only step
that uses `sudo`. To read the installer first: `curl -fsSL https://dials-5ng.pages.dev/install.sh | less`. Run the same
line again to update. Your setups are kept.

For motherboard, graphics card and mouse lights, also install **OpenRGB** (https://openrgb.org). Dials starts it in the
background by itself.

## Install by hand
1. Install Tkinter: `sudo dnf install python3-tkinter` (Fedora/Nobara), `sudo apt install python3-tk`
   (Ubuntu/Debian/Mint) or `sudo pacman -S tk` (Arch).
2. Download `dials-<version>-linux.tar.gz` and its `.sha256` from the download page, then check and unpack it:
   `sha256sum -c dials-<version>-linux.tar.gz.sha256 && tar -xzf dials-<version>-linux.tar.gz`
3. Run `sh dials-<version>-linux/install.sh`.

## First run
Open **Dials** from the app menu.
- **Your setups**: save the current colours and mouse speed under a name, and optionally a game that switches to it.
- **Lights**: click a colour to change it.
- **Match colours**: if white looks different on each device, match them by eye once. Dials corrects every colour from
  then on.
- **Mouse speed**: drag the slider.
- **Fans**: Automatic leaves the motherboard in charge. The other modes need the one-time setup below.

Only one Dials window runs at a time. Opening it again brings the existing window to the front.

## Optional: fan modes
> **Your responsibility.** Too little cooling can overheat and damage your PC. Dials keeps fans at 30% or more and gives
> them back to the motherboard when it closes. If Dials is killed, the PC crashes, or you log out while a mode is on,
> the fans stay where they were until you reopen Dials.

Fan modes work only on boards with the ITE IT8689E chip. They need its out-of-tree driver
(https://github.com/frankcrawford/it87) and a one-time permission step. The Fans card in Dials shows the exact command
and has a Copy button. It looks like:
```
sudo sh ~/.local/share/dials/app/dials/data/install-fans.sh
```
Read the script first: it is short and says what it changes. Add `--remove` to undo it.

## If the mouse or keyboard isn't found
Most distros already let you talk to your own mouse and keyboard. If yours doesn't, run once:
```
sudo sh ~/.local/share/dials/app/dials/data/setup-devices.sh
```
then unplug and replug the device. Add `--remove` to undo it.

## Uninstall
```
sh ~/.local/share/dials/uninstall.sh            # keeps your setups in ~/.config/dials
sh ~/.local/share/dials/uninstall.sh --purge    # removes them too
```
If you set up fan or device permissions, run the matching `--remove` command above **before** uninstalling.

## Troubleshooting
Not sure what's wrong? Run **`dials doctor`** in a terminal. It checks OpenRGB, your keyboard, mouse, fans and CPU
sensor without changing anything, and gives a fix for each problem. Paste its output into a bug report.

| You see | Do this |
|---|---|
| "Colour needs OpenRGB running" | Install OpenRGB. If it's installed, close Dials and open it again. |
| My graphics card isn't listed | OpenRGB supports most retail cards (ASUS, MSI, Gigabyte, EVGA, Zotac...). Cards made for Dell, HP or Lenovo PCs usually have no lighting software can control. |
| A light shows "No lights to colour" | OpenRGB found the device but it has no LEDs Dials can set. |
| Mouse speed is missing | Only the Razer Basilisk V3 is supported so far. Otherwise, see If the mouse or keyboard isn't found. |
| Fans offer only Automatic | Run the fan setup under Optional: fan modes, then reopen Dials. |
| Fans stay loud after closing | Reopen Dials and choose Automatic, or restart the PC. |
| Nothing opens from the menu | Run `dials-app` in a terminal to see the error. |
