# openrazer

The Razer peripherals' kernel driver and the account's daemon that drives it, on the workstations, as
a module (novox/hq ADR 0208: one module per piece of software). The tray that shows the devices is
the `polychromatic` module's. This module needs no display: the daemon speaks to the driver and to its
clients on the session bus.

## Owns

| what | where |
|---|---|
| the kernel driver's source, built by DKMS for each installed kernel (`razerkbd`, `razermouse`, `razerkraken`, `razeraccessory`) | package `openrazer-driver-dkms` |
| the daemon (`org.razer` on the session bus) and its user unit | package `openrazer-daemon` |
| the client library every front end speaks to the daemon through | package `python-openrazer` |
| the operator's account in the group `openrazer` | a `user` resource naming the account and that group, nothing else of it |

All three from the official repositories (`extra`). On both workstations they are installed today as
dependencies of the AUR tray, and become the mesh's here.

**Why two modules and not one `razer`:** the driver and the daemon are one project, in the official
repositories, and any front end uses them. The tray is another project, outside the official
repositories. That is the line between `bluetooth` and `blueman` too. A machine can hold the stack
without the tray, for a front end of the operator's own or for the daemon's persistence of the
devices' lighting and DPI.

Not this module's:

- **The kernel headers DKMS builds against** (`linux-headers`). They are the kernel's, and every DKMS
  driver on a machine needs them (the laptop also builds `nvidia`, the desktop `vboxhost` and `xone`).
  No module declares them yet. `openrazer_check` says when the driver is not built for the running
  kernel.
- **`dkms` itself**, which the driver package depends on.
- **The account's shell, home and other groups**: the login shell's module's, and the operator's.

## The group: declared here, and a new login once

The driver's udev rules give each device's files to the group `openrazer`, which the driver package
creates (sysusers). The daemon refuses to start for an account outside that group: *User is not a
member of the openrazer group*.

**The module puts the operator's account in `openrazer`** (novox/hq ADR 0252, issue 247). It declares
the account as a `user` resource with that one group and nothing else of it. The `zsh` module declares
the same account to set its shell; the controller lets several modules add groups to one account, and
refuses only two that set its shell or home. The resource is written after the three packages, and the
controller keeps it there, so the group exists when the account is put in it.

- **The account's other groups are never touched.** The node-engine appends (`usermod --append`).
- **A new login is needed.** The account's running service manager, and the daemon it starts, keep the
  groups they started with. The node-engine says so in the apply's outcome, and on every look until the
  running manager has the group: the module's resource `openrazer.account`, of kind `account`, is
  unhealthy with *relogin needed*, and the controller raises it as openrazer's condition on that machine.
  It clears on the first look after a new login.
- **Unassigned, the account leaves `openrazer`**, but only if the mesh put it there and no other module
  still asks for it. An account that was in the group before is left in it.

**On both workstations the account is not in it today, so the daemon has failed at every start**
since openrazer moved from `plugdev` to its own group. The tray runs, and shows no devices. The account
is still in `plugdev`, which openrazer no longer uses. Another device's rules may (the laptop has a
Logitech receiver rule that does), so it stays.

## How it starts: D-Bus activation, and nothing else

The package installs `org.razer` as a D-Bus service whose `SystemdService` is the user unit
`openrazer-daemon.service`. The first client that asks for `org.razer` starts the daemon through that
unit: at login, the tray's helper (`polychromatic-helper --autostart`). **That activation is the
daemon's one start.** One unit, so it is never two daemons.

- The unit is **not enabled** on either workstation, and the module does not enable it. Enabling it
  would start the same unit at login a moment earlier, with nothing gained.
- Asked by a tool, the bus is always called with `--auto-start=no`, so asking never starts it.

## Tools

They are served by the node's runtime as the operator account (ADR 0175).

| tool | does |
|---|---|
| `openrazer_status` (r) | <ul><li>the three packages' versions</li><li>the driver: the running kernel, DKMS's state for it, the modules loaded, the devices bound (USB id, driver, interfaces)</li><li>the group: whether the account is in it, and whether the account's running service manager has it</li><li>the daemon: its unit's active and enabled states, its process, its version, and, when its unit failed, the reason it gave</li><li>each device the daemon sees: name, type, firmware, battery and charging where the device has them. Never its serial</li></ul> |
| `openrazer_restart` (a) | restarts `openrazer-daemon.service` in the account's service manager and answers the devices it then sees. When it fails, the answer carries the daemon's own reason |
| `openrazer_check` (r) | <ul><li>the packages are installed</li><li>the driver is built for the running kernel, and loaded</li><li>a device is bound</li><li>the account is in `openrazer`, and its service manager has the group (a group added after login needs a new login)</li><li>one start: the activation file is present, no window-manager exec</li><li>one daemon runs, from its unit, and answers</li><li>it sees every device the driver holds</li></ul>Each finding says what to do |

Every command has a timeout and capped output. Everything runs through an injected runner and a fake
root in the tests.

## What changes when it is assigned

| | laptop | desktop |
|---|---|---|
| packages | none: the three are installed, 3.12.4, as dependencies of the tray | the same |
| driver | none: built for the running kernel, `razermouse` loaded, a Basilisk V3 Pro bound | the same, a Basilisk V2 bound |
| the account | put in `openrazer`; its other groups as they are | the same |
| daemon | none: the unit stays disabled; it failed at login (not in the group) | the same |

## Migration (ADR 0182)

On each workstation, once, after the push that sends this module's account resource:

1. The apply puts the account in `openrazer`, and openrazer's health says *relogin needed*.
2. Log out of every session, or reboot. The account's service manager takes its groups when it
   starts, and the daemon runs under it.
3. The condition clears, `openrazer_check` answers `ok`, and the tray shows the devices.

`plugdev` stays. Nothing else is required, and nothing is done with `sudo` by hand.

## Leaves as found

- The daemon's settings and persistence under `~/.config/openrazer/`, and its log under
  `~/.local/share/openrazer/`.
- `plugdev` and every other group of the account.
- The kernel headers and DKMS.

## Relies on

- **A node-engine that gives back what it put the account in, and says a new login is needed** (ADR
  0252). An older one puts the account in the group just the same, says nothing of the login, and
  never takes the group back.
- **A client to start the daemon.** At login that is the `polychromatic` module's tray helper.
  Without a client nothing asks, and nothing needs it to run.
- **The kernel headers of every installed kernel**, for DKMS.