Skip to content

INSTALL-linux.md

Latest commit

 

History

History
185 lines (142 loc) · 5.61 KB

INSTALL-linux.md

File metadata and controls

185 lines (142 loc) · 5.61 KB
Raw

Installing OpenLogi on Linux

Note

Linux support is in active development. HID++ device enumeration supports Logi Bolt (USB PID 0xC548) and Logi Unifying (PID 0xC52B and others) receivers, as well as Bluetooth-direct devices.

Prerequisites

  • Quit Solaar (or any other Logitech manager) before starting OpenLogi — the two applications fight over HID++ access.
  • A kernel with hidraw and uinput module support (standard on all major distros).
  • systemd + udev (standard on Ubuntu, Fedora, Arch, Debian, openSUSE, …).
  • GLIBC 2.35 or newer for the pre-built packages (Ubuntu 22.04 baseline).

NixOS

The repository Flake provides a package and a NixOS module for x86_64 and aarch64 Linux. Importing the module is preferred over adding the package to environment.systemPackages by itself: the module also registers the udev rules required for device access and manages the agent's user service.

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  inputs.openlogi = {
    url = "github:AprilNEA/OpenLogi";
    inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, openlogi, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux"; # or aarch64-linux
      modules = [
        openlogi.nixosModules.default
        {
          programs.openlogi = {
            enable = true;
            # Starts openlogi-agent with graphical-session.target by default.
            launchAtLogin = true;
          };
        }
      ];
    };
  };
}

Set programs.openlogi.launchAtLogin = false to install the package and udev rules without automatically starting the agent. It remains available as systemctl --user start openlogi-agent.service.

For a build without installing the module:

nix build github:AprilNEA/OpenLogi#openlogi

Build from source

Pre-built .deb and .rpm packages are available on the releases page — see the main README for the package-based install. To build from source instead, use the stable Rust toolchain:

git clone https://github.com/AprilNEA/OpenLogi
cd OpenLogi
cargo build --release -p openlogi -p openlogi-desktop -p openlogi-agent

Four production executables land in target/release/:

Binary Role
openlogi CLI — inventory, diagnostics, asset sync
openlogi-desktop Desktop GUI
openlogi-overlay Actions Ring overlay helper
openlogi-agent Background agent — HID++ loop, input hook

Device access: udev rules

OpenLogi needs:

  • Write access to /dev/uinput — to create the virtual input device for button remapping.
  • Read/write access to /dev/hidraw* — to send HID++ commands to the Bolt receiver, or to the device itself when it is paired over Bluetooth.
  • Read access to the mouse's /dev/input/event* node — the hook grabs the pointer there to capture button presses. Bluetooth mice need the bundled rule for this: their event node hangs off /devices/virtual/misc/uhid, which has no seat, so logind never grants the ACL on its own.

Install the bundled udev rules to grant access to the active-seat user without requiring sudo or group membership (requires systemd-logind):

sudo cp packaging/linux/udev/70-openlogi.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

Verify access (should open without error):

# Check uinput
openlogi-agent --check-uinput 2>/dev/null || \
    test -w /dev/uinput && echo "uinput OK"

# Check a hidraw node
ls -la /dev/hidraw*

# Check the mouse's event node — look for a "+" (ACL) in the mode, or your
# user in the ACL itself. Without it the agent logs
# "could not install OS mouse hook".
getfacl /dev/input/event*

The GUI Settings → Permissions page shows a live Granted / Not granted indicator; check it after installing the rules (no restart needed).

Device already connected? udevadm trigger re-evaluates rules but does not re-grant uaccess ACLs on nodes that were already open when the rules were installed. If access is still denied, unplug and replug your receiver or mouse (or power-cycle for wireless devices) to let udev apply the new rules on reconnect.

Non-systemd systems (SysV init, OpenRC)

Replace TAG+="uaccess" in the rules file with MODE="0660", GROUP="input", then add your user to the input group:

sudo usermod -aG input "$USER"
# Re-login for the group change to take effect.

Install with the script

The packaging/linux/install.sh script copies the binaries, udev rules, systemd unit, desktop entry, and icon to system paths, then reloads udevadm.

# From the repo root, after building:
sudo packaging/linux/install.sh
# Or to a custom prefix (e.g. /usr):
packaging/linux/install.sh --prefix=/usr

To remove:

packaging/linux/uninstall.sh

Autostart (launch at login)

The background agent (openlogi-agent) must be running for the GUI and CLI to show connected devices. Enable it for your user session:

systemctl --user enable --now openlogi-agent.service

Alternatively, toggle Settings → General → Launch at login in the GUI — it writes the unit to ~/.config/systemd/user/openlogi-agent.service automatically.

Verify the installation

# List connected Logitech devices:
openlogi list

# Launch the GUI:
openlogi-desktop

Known limitations

Limitation Status
Wayland: per-application profile switching Requires XWayland (WM_CLASS lookup uses X11)
Button capture: middle / mode-shift / thumbwheel Side buttons only today