# Development

This guide is for contributors. End-user installation and troubleshooting are in [README.md](README.md).

## Prerequisites

- Rust stable toolchain.
- Omarchy Quattro for QML/plugin validation.
- A supported Logitech HID++ mouse is required for hardware write verification.

## Project layout

| Path                            | Purpose                                                     |
| ------------------------------- | ----------------------------------------------------------- |
| `src/main.rs`                   | Native HID++ controller.                                    |
| `bin/logitech-g-daemon`         | x86_64 Linux executable shipped with the plugin.            |
| `Service.qml`                   | Starts the controller and applies its JSON status.          |
| `Model.js`                      | Converts controller JSON into QML state.                    |
| `manifest.json`                 | Marketplace and plugin metadata; canonical release version. |
| `.github/workflows/release.yml` | Creates GitHub version tags and releases.                   |

## Native controller

The controller communicates directly with `/dev/hidraw` using HID++ 2.0. It dynamically resolves feature indices after connection and waits up to five seconds for a receiver to become ready.

Build and update the executable shipped in the plugin:

```bash
cargo fmt
cargo build --locked --release
install -Dm755 target/release/logitech-g-daemon bin/logitech-g-daemon
```

The bundled executable targets x86_64 GNU/Linux. Build it on the target architecture when supporting another platform.

### CLI contract

```bash
./bin/logitech-g-daemon --once
./bin/logitech-g-daemon --set-dpi 1600
./bin/logitech-g-daemon --set-rate 4000
./bin/logitech-g-daemon --set-actuation 4 --left
./bin/logitech-g-daemon --set-rt 2 --left
./bin/logitech-g-daemon --set-haptics 5 --left
```

Each invocation prints one JSON status object. It also atomically publishes the latest status as a mode-`0600` regular file under `${XDG_RUNTIME_DIR}/omarchy-logitech-g-mouse/`; the UI consumes the bounded stdout contract rather than that file.

### HID++ features

| Capability           | Preferred feature | Compatible feature |
| -------------------- | ----------------- | ------------------ |
| Device name          | `0x0005`          | —                  |
| Battery status       | `0x1004`          | `0x1000`           |
| DPI                   | `0x2202`          | `0x2201`           |
| HITS analog switches | `0x1B0C`          | —                  |
| Onboard profiles     | `0x8100`          | —                  |
| Report rate           | `0x8061`          | `0x8060`           |

Feature indices are always resolved from the connected device. The compatible HID++ features cover devices such as the G304/G305 LIGHTSPEED receiver, while newer extended features remain preferred when both are available.

## Local development

After QML or bundled-binary changes, copy the plugin and restart the shell:

```bash
omarchy plugin validate .
cp -a . ~/.config/omarchy/plugins/tantuyu.logitech-g-mouse/
omarchy restart shell
```

Verify the native controller before testing the QML surface:

```bash
cargo build --locked --release
./bin/logitech-g-daemon --once
```

Use a no-op write matching the current DPI to exercise a hardware write without changing the configured value:

```bash
./bin/logitech-g-daemon --set-dpi 1200
```

## Releases

`manifest.json` is the canonical plugin version. On a push to `main`, `.github/workflows/release.yml` builds the controller from the locked source at the triggering full commit SHA, creates a GitHub Release and `v<version>` tag when that semantic version does not already have a tag, and attaches the CI-built binary, its SHA-256 checksum, and provenance JSON.

To release:

1. Update `manifest.json` to the new semantic version.
2. Build and update `bin/logitech-g-daemon` if the native controller changed.
3. Run the verification commands above.
4. Commit and push to `main`.

Existing release tags are never overwritten.