Logitech G710+ without "Gaming Software"

TL;DR

Run this command line tool on macOS to use the G1-6 keys of the Logitech G710+ gaming keyboard without installing proprietary Software by Logitech.

✅ Tested on macOS Sequoia 15.6 - Fully compatible with modern macOS security requirements.

Introduction

So you just bought this gaming keyboard and realize "oh no, the G-keys don't work without the Logitech spyware drivers :("

"No problem", you say, "I'll install https://github.com/tekezo/Karabiner/ and remap them manually" - only to find out that the G-keys simply mirror the numeric 1-6 keys, which makes them indistinguishable.

Digging in deeper, you might find out that someone reverse engineered the USB communication of the keyboard. It turns out that you can instruct the keyboard to stop mirroring the number keys.

How it works

This is a simple command line application written in Swift that communicates directly via USB with your keyboard and does the following:

• Disables G-key mirroring (G-keys normally mirror number keys 1-6)
• Maps G-keys to customizable shortcuts via JSON configuration (default mappings):
  • G1 → Control+Command+Shift+L
  • G2 → Control+Command+Shift+K
  • G3 → Control+Command+Shift+J
  • G4 → F6 tap → F18 hold (key sequence with holding behavior)
  • G5 → F17, G6 → F18
• Supports advanced features: key sequences, key holding, and post-release actions
• Controls M-mode indicator lights on the keyboard (M1 light illuminates by default)
• M1 key works, M2/M3 keys currently don't do anything

In effect, this allows you to use the keyboard in games without any Logitech driver.

Installation

Option 1: macOS App Bundle (Recommended)

Build and install as a proper macOS app that runs silently in the background:

1. Clone this repository:

git clone https://github.com/Rendann/g710plus.git
cd g710plus

2. Build the app bundle:

./build-app.sh

3. Install to Applications folder:

cp -r g710plus/g710plus/G710Plus.app /Applications/

Advantages:

• Runs silently without terminal windows
• Proper macOS app bundle with code signing
• Integrates cleanly with Login Items
• Unified logging via Console.app

Option 2: Command-Line Executable (Alternative)

1. Clone this repository:

git clone https://github.com/Rendann/g710plus.git
cd g710plus/g710plus/g710plus

2. Build the executable:

swiftc -o g710plus Classes/*.swift -framework IOKit -framework CoreGraphics -framework Foundation

3. Install to a permanent location (e.g., /usr/local/bin/):

sudo cp g710plus /usr/local/bin/g710plus

Note: Command-line version shows terminal window when used as login item.

First Run and Permissions

Testing the App Bundle

Open the app to test functionality:

open /Applications/G710Plus.app

Testing the Command-Line Version

/usr/local/bin/g710plus --verbose

Required Permissions (TCC)

On first run, macOS will prompt for security permissions:

1. Input Monitoring Permission: Required to detect G-key presses

   • Location: System Settings > Privacy & Security > Input Monitoring
   • Enable: G710Plus (for app bundle) or g710plus (for command-line)

2. Accessibility Permission: May be prompted if needed for key injection

   • Location: System Settings > Privacy & Security > Accessibility
   • Enable: G710Plus when prompted

Important: Restart the app after granting permissions for them to take effect.

Configuration

G-key shortcuts are fully customizable via JSON configuration files using the new array-based format that supports both single keys and multi-key sequences.

Configuration File Priority (checked in order):

1. Custom path: --config /path/to/config.json command line argument
2. App bundle: G710Plus.app/Contents/Resources/g710plus-config.json
3. Home directory: ~/.g710plus-config.json
4. Built-in defaults: Hardcoded fallback configuration

Basic Configuration Format

Create ~/.g710plus-config.json to override defaults:

{
  "g1": {
    "keys": [
      {"key": "k", "modifiers": []}
    ]
  },
  "g2": {
    "keys": [
      {"key": "k", "modifiers": ["shift"]}
    ]
  },
  "g3": {
    "keys": [
      {"key": "Space", "modifiers": ["command"]}
    ]
  },
  "g4": {
    "keys": [
      {"key": "F13", "modifiers": []}
    ]
  },
  "g5": {
    "keys": [
      {"key": "Enter", "modifiers": []}
    ]
  },
  "g6": {
    "keys": [
      {"key": "Escape", "modifiers": []}
    ]
  }
}

Key Sequences (Multi-Key Macros)

Execute multiple keystrokes in sequence with proper timing:

{
  "g2": {
    "keys": [
      {"key": "h", "modifiers": ["command"]},
      {"key": "i", "modifiers": ["shift"]}
    ]
  },
  "g3": {
    "keys": [
      {"key": "Escape", "modifiers": []},
      {"key": "Tab", "modifiers": []},
      {"key": "Enter", "modifiers": []}
    ]
  }
}

Sequence Behavior:

• Intermediate keys: Tap briefly (10ms press + release) with 50ms delay between steps
• Final key: Holds down until G-key is released (enables modifier keys, etc.)
• Timing: Non-blocking async execution prevents UI freezing

Post-Release Sequences (onRelease)

Execute additional keystrokes after the G-key is released:

{
  "g4": {
    "keys": [
      {"key": "F6", "modifiers": []},
      {"key": "F18", "modifiers": []}
    ],
    "onRelease": [
      {"key": "F6", "modifiers": []}
    ]
  },
  "g6": {
    "keys": [
      {"key": "Space", "modifiers": ["command"]}
    ],
    "onRelease": [
      {"key": "Escape", "modifiers": []},
      {"key": "Tab", "modifiers": []}
    ]
  }
}

onRelease Behavior:

• Executes after held key from main sequence is released
• All onRelease keys are tapped (no holding since G-key is already released)
• Perfect for complex macros requiring different press/release actions

Supported Keys and Modifiers

Key Examples:

• Letters: "k" (lowercase only - use ["shift"] modifier for uppercase)
• Special: "Space", "Enter", "Tab", "Escape", "Backspace"
• Function: "F1" through "F18"
• Arrows: "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"
• Punctuation: ";" (use ["shift"] for ":"), ",", ".", "1" (use ["shift"] for "!"), etc.

Supported Modifiers:

• "control" or "ctrl" - Control key
• "command" or "cmd" - Command key (⌘)
• "shift" - Shift key
• "option" or "alt" - Option/Alt key

Examples:

• {"key": "k", "modifiers": []} → k
• {"key": "k", "modifiers": ["shift"]} → K
• {"key": "k", "modifiers": ["command"]} → ⌘K
• {"key": "k", "modifiers": ["control", "shift"]} → ⌃⇧K

Real-World Configuration Examples

Gaming Setup:

{
  "g1": {
    "keys": [{"key": "1", "modifiers": []}]
  },
  "g2": {
    "keys": [{"key": "2", "modifiers": []}]
  },
  "g3": {
    "keys": [
      {"key": "Tab", "modifiers": []},
      {"key": "Space", "modifiers": []}
    ]
  }
}

Development Workflow:

{
  "g1": {
    "keys": [{"key": "s", "modifiers": ["command"]}]
  },
  "g2": {
    "keys": [
      {"key": "k", "modifiers": ["command"]},
      {"key": "u", "modifiers": ["command"]}
    ]
  },
  "g3": {
    "keys": [{"key": "`", "modifiers": ["command"]}],
    "onRelease": [
      {"key": "c", "modifiers": ["command"]},
      {"key": "Enter", "modifiers": []}
    ]
  }
}

Media Control:

{
  "g4": {
    "keys": [
      {"key": "Space", "modifiers": []}
    ]
  },
  "g5": {
    "keys": [
      {"key": "ArrowLeft", "modifiers": []}
    ]
  },
  "g6": {
    "keys": [
      {"key": "ArrowRight", "modifiers": []}
    ]
  }
}

Modifier-Aware G-Key Mappings

G-keys can perform different actions based on which modifier keys (Alt, Shift, etc.) are held when pressed. Use the withModifiers field to define alternate behaviors:

{
  "g3": {
    "keys": [{"key": "F17", "modifiers": []}],
    "withModifiers": {
      "option": {
        "keys": [{"key": "F19", "modifiers": []}]
      },
      "option+shift": {
        "keys": [{"key": "F21", "modifiers": []}],
        "onRelease": [{"key": "F22", "modifiers": []}]
      }
    }
  }
}

Behavior:

• G3 alone → sends F17
• Alt+G3 → sends F19 (Alt is stripped from output)
• Alt+Shift+G3 → sends F21, then F22 on release

Key Features:

• Modifier stripping: Triggering modifiers are NOT passed through to output. Alt+G3 sends just the configured keys, not Alt+<configured-keys>. If you want Alt in the output, add it explicitly to the variant's modifiers.
• Exact matching: Holding option+shift requires an exact "option+shift" variant; there's no fallback to partial matches like just "option".
• State captured at press: The variant is determined when the G-key is pressed and stored, so release works correctly even if you release the modifier keys before releasing the G-key.
• Normalized modifier names: "alt" = "option", "cmd" = "command", "ctrl" = "control". Multi-modifier combos are sorted alphabetically (e.g., "shift+alt" becomes "option+shift").

Important Notes:

• Uppercase letters (A-Z) are not allowed in key names. Use lowercase letters with explicit "shift" modifier instead.
• Configuration changes require app restart to take effect.
• Use --config /path/to/config.json argument for custom configuration file locations.
• Example configurations are available in the repository: example-sequence-config.json

Automatic Startup

Option 1: App Bundle (Recommended)

Add G710Plus.app to Login Items for clean startup without terminal windows:

1. Open System Settings (or System Preferences on older macOS)
2. Go to General > Login Items (or Users & Groups > Login Items)
3. Click the + button to add a new login item
4. Navigate to and select: /Applications/G710Plus.app
5. Make sure it's enabled (checkbox checked)

The app will start automatically and run silently in the background.

Option 2: Command-Line Version

For the command-line executable:

1. Follow the same steps as above but select: /usr/local/bin/g710plus
2. Note: This will show a terminal window on login

Alternative command-line method:

osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/G710Plus.app", hidden:false}'

Why Login Items? Modern macOS security restricts Launch Agents from accessing HID devices during boot. Login Items run with full user privileges and work reliably.

Troubleshooting

G-keys Output Numbers Instead of Function Keys

• Check if utility is running: Look for G710Plus in Activity Monitor
• Verify TCC permissions: Input Monitoring must be enabled in System Settings
• Restart after permission grant: Quit and relaunch the app
• Test manually: open /Applications/G710Plus.app (for app bundle) or /usr/local/bin/g710plus --verbose (for command-line)

No G-key Response At All

• Check Login Items: Ensure G710Plus.app is in Login Items and enabled
• Verify TCC permissions: Both Input Monitoring and Accessibility (if prompted) must be granted
• Rebuild and re-authorize: Code signing issues may require TCC re-authorization

Viewing Diagnostic Logs

Console.app Method:

1. Open Console.app (Applications > Utilities)
2. Filter by process: "G710Plus" or "g710plus"
3. Use predicate: subsystem == "com.halo.g710plus"

Command Line Method:

log stream --predicate 'subsystem == "com.halo.g710plus"' --info --debug

Note: Debug logs may show "Control transfer failed: -536850432" during startup. This is expected and does not affect functionality.

When Working Properly

• M1 light should be illuminated on the keyboard
• G-keys trigger configured shortcuts (default: G1-G3→Control+Command+Shift+L/K/J, G4→F6 tap+F18 hold, G5→F17, G6→F18)
• Keys send configured outputs instead of numbers 1-6
• No terminal windows visible (for app bundle)
• Logs show "G710+ keyboard connected" in Console.app

Limitations

• There is no key-repeat. You press a G key once and it triggers once.

Credits

• K900 libusb python script
• Eric Betts' KuandoSwift

License

Copyright (c) 2016 halo, MIT License

See each respective file or LICENSE.md for more details.