Skip to content

migration-guide.md

Latest commit

 

History

History
378 lines (286 loc) · 7.2 KB

migration-guide.md

File metadata and controls

378 lines (286 loc) · 7.2 KB
Raw

Migration Guide

This guide helps users transition from the original C++ logiops to logiops-rs.

Overview

logiops-rs is a Rust rewrite that aims for full feature parity with the original logiops. Key differences:

Aspect Original logiops logiops-rs
Language C++ Rust
Config format libconfig++ (.cfg) TOML
Service name logid logiops
Config path /etc/logid.cfg /etc/logiops/config.toml
Dependencies libevdev, libconfig++, libudev Pure Rust (minimal)

Configuration Migration

Automatic Migration Tool

# Convert existing config
logiops-migrate /etc/logid.cfg > /etc/logiops/config.toml

# Preview without writing
logiops-migrate --dry-run /etc/logid.cfg

Manual Conversion

Original libconfig++ Format

// /etc/logid.cfg
devices: ({
    name: "MX Master 3S";
    dpi: 1600;
    smartshift: {
        on: true;
        threshold: 30;
        torque: 50;
    };
    hiresscroll: {
        hires: true;
        invert: false;
        target: false;
    };
    buttons: ({
        cid: 0xc3;
        action: {
            type: "Gestures";
            gestures: ({
                direction: "Up";
                action: { type: "Keypress"; keys: ["KEY_VOLUMEUP"]; };
            }, {
                direction: "Down";
                action: { type: "Keypress"; keys: ["KEY_VOLUMEDOWN"]; };
            });
        };
    }, {
        cid: 0xc4;
        action: {
            type: "Keypress";
            keys: ["KEY_LEFTMETA"];
        };
    });
});

Equivalent TOML Format

# /etc/logiops/config.toml

[[devices]]
name = "MX Master 3S"
dpi = 1600

[devices.smartshift]
on = true
threshold = 30
torque = 50

[devices.hiresscroll]
hires = true
invert = false
target = false

[[devices.buttons]]
cid = 0x00c3
action = { type = "gestures", up = "KEY_VOLUMEUP", down = "KEY_VOLUMEDOWN" }

[[devices.buttons]]
cid = 0x00c4
action = { type = "keypress", keys = ["KEY_LEFTMETA"] }

Key Conversion Rules

libconfig++ TOML Notes
devices: ({ ... }) [[devices]] Array of tables
name: "..."; name = "..." String assignment
dpi: 1600; dpi = 1600 Integer, no semicolon
on: true; on = true Boolean
cid: 0xc3; cid = 0x00c3 Hex notation preserved
keys: ["KEY_A"]; keys = ["KEY_A"] Array syntax same
Nested objects Inline tables or sections See examples below

Action Type Mapping

Keypress

// Original
action: {
    type: "Keypress";
    keys: ["KEY_LEFTCTRL", "KEY_C"];
};
# TOML
action = { type = "keypress", keys = ["KEY_LEFTCTRL", "KEY_C"] }

Gestures

// Original
action: {
    type: "Gestures";
    gestures: ({
        direction: "Up";
        action: { type: "Keypress"; keys: ["KEY_VOLUMEUP"]; };
    }, {
        direction: "Down";
        action: { type: "Keypress"; keys: ["KEY_VOLUMEDOWN"]; };
    });
};
# TOML (simplified)
action = { type = "gestures", up = "KEY_VOLUMEUP", down = "KEY_VOLUMEDOWN" }

# Or with complex actions
[devices.buttons]
cid = 0x00c3

[devices.buttons.action]
type = "gestures"
up = ["KEY_LEFTCTRL", "KEY_PAGEUP"]
down = ["KEY_LEFTCTRL", "KEY_PAGEDOWN"]
left = "KEY_BACK"
right = "KEY_FORWARD"

CycleDPI

// Original
action: {
    type: "CycleDPI";
    dpis: [400, 800, 1600, 3200];
};
# TOML
action = { type = "cycledpi", dpis = [400, 800, 1600, 3200] }

ToggleSmartShift

// Original
action: { type: "ToggleSmartshift"; };
# TOML
action = { type = "togglesmartshift" }

None (Disable Button)

// Original
action: { type: "None"; };
# TOML
action = { type = "none" }

Service Migration

Step 1: Stop Original Service

sudo systemctl stop logid
sudo systemctl disable logid

Step 2: Install logiops-rs

# Debian/Ubuntu
sudo dpkg -i logiops_0.1.0_amd64.deb

# Fedora
sudo dnf install logiops-0.1.0-1.x86_64.rpm

# Arch Linux
yay -S logiops-rs

Step 3: Migrate Configuration

# Backup original
sudo cp /etc/logid.cfg /etc/logid.cfg.bak

# Convert (automatic)
sudo logiops-migrate /etc/logid.cfg | sudo tee /etc/logiops/config.toml

# Or convert manually (see above)

Step 4: Start New Service

sudo systemctl enable logiops
sudo systemctl start logiops

Step 5: Verify

# Check service status
sudo systemctl status logiops

# Check device detection
busctl call org.logiops /org/logiops/Manager org.logiops.Manager1 ListDevices

# View logs
journalctl -u logiops -f

Rollback Procedure

If something doesn't work:

# Stop new daemon
sudo systemctl stop logiops
sudo systemctl disable logiops

# Re-enable original
sudo systemctl enable logid
sudo systemctl start logid

Feature Compatibility

Fully Supported

  • DPI adjustment
  • SmartShift configuration
  • Hi-res scrolling
  • Button remapping (Keypress)
  • Gesture actions
  • CycleDPI
  • ToggleSmartShift
  • Thumb wheel configuration
  • Device hotplug

New Features in logiops-rs

  • D-Bus interface for external control
  • Environment variable configuration
  • Per-user config overrides
  • JSON log output option
  • Systemd watchdog support

Not Yet Implemented

Check the project issues for status on:

  • On-board memory profiles
  • Per-application profiles
  • Some device-specific quirks

Troubleshooting

Device Not Detected

# Check udev rules
ls -la /lib/udev/rules.d/99-logiops.rules

# Reload rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# Check permissions
ls -la /dev/hidraw*
# Should show group "plugdev"

# Add user to plugdev group
sudo usermod -aG plugdev $USER
# Log out and back in

Service Fails to Start

# Check logs
journalctl -u logiops -e

# Common issues:
# - Config syntax error: validate with `logiops --check-config`
# - Permission denied: check udev rules and user groups
# - Device in use: stop original logid service

Button Remapping Not Working

# Check if uinput is available
ls -la /dev/uinput
# Should show group "input"

# Add user/service to input group
sudo usermod -aG input $USER

# Verify virtual device created
ls /dev/input/by-id/ | grep logiops

Config Not Applied

# Validate config
logiops --check-config /etc/logiops/config.toml

# Reload config without restart
sudo systemctl reload logiops

# Or restart
sudo systemctl restart logiops

D-Bus Interface

logiops-rs exposes a D-Bus interface for runtime control:

# List devices
busctl call org.logiops /org/logiops/Manager org.logiops.Manager1 ListDevices

# Get device info
busctl call org.logiops /org/logiops/Manager org.logiops.Manager1 GetDeviceInfo s "device-id"

# Set DPI
busctl call org.logiops /org/logiops/Manager org.logiops.Manager1 SetDPI sq "device-id" 1600

# Get version
busctl get-property org.logiops /org/logiops/Manager org.logiops.Manager1 Version

Getting Help