joy4ge is a framework and a set of tools that allow you to control Google Earth Pro (on macOS) with any USB HID-compatible controller, joystick, gamepad, or custom device.

Originally developed for use with the internal 3DconnexionClient framework, it now also includes a lightweight tool HIDToKey, which translates raw HID input into keyboard events. This lets you control Google Earth even in the web browser version.

• Overview
• Installation & Building
• Usage with Google Earth Pro
• Live Key Mapping: HIDToKey
• Console Output
• Configuration File
• Development Notes
• Known Issues
• Changelog
• Authors
• License

joy4ge consists of:

• A framework that can be injected into Google Earth Pro using the 3DconnexionClient interface to emulate a 3D mouse,
• A fallback tool HIDToKey, which sends simulated keyboard events based on gamepad input for compatibility with Google Earth in the browser or when the framework injection fails.

It supports deadzone calibration, axis-to-key mapping, button translation (with modifiers), and multiple device types.

1. Open the Xcode project (3DconnexionClient.xcodeproj).

2. Build it (last verified with Xcode 16.2 / Google Earth 7.3.6).

3. The compiled framework will be placed in:

   ~/Library/Frameworks/3DconnexionClient.framework/
   

   or install to /Library/Frameworks/ if needed for system-wide access or you have Google Earth 7.3 and later.

A standalone tool located under /HIDToKey/:

cd HIDToKey/
./build.sh

This will compile the command-line tool. You can run it directly:

./HIDToKey

It will listen for input from connected USB HID devices and simulate keyboard input accordingly.

1. Ensure your custom version of 3DconnexionClient.framework is placed in:

   ~/Library/Frameworks/
   

   or, if needed:

   /Library/Frameworks/
   

With Version 7.3 and later it works only from /Library/Frameworks/, not ~/Library/Frameworks/ Tip: If you have a genuine 3Dconnexion device, you don’t need joy4ge.

Works out of the box with joy4ge (named 3DconnexionClient.framework after compiling).

Google Earth ships with a built-in 3DconnexionClient.framework inside the app bundle, which overrides the user-installed version. You must:

1. Open the Google Earth.app bundle:

   /Applications/Google Earth Pro.app/Contents/Frameworks/
   

2. Rename or remove 3DconnexionClient.framework inside that folder.

Version 7.3 and later did not have a built-in 3DconnexionClient.framework.

HIDToKey allows live mapping of controller buttons and analog axes to macOS keyboard events. This makes it possible to control Google Earth in Safari, Chrome, Firefox, or any other app using only standard keys (like arrow keys, page up/down, shift-modified inputs, etc.).

• Up to 16 buttons and 4 analog axes supported
• Per-button key and modifier assignment
• Per-axis calibration with deadzone and direction mapping
• Detects button edges (press/release), not just state
• Modifier-aware (Shift, Command, etc.)
• Diagonal movement and multi-key combos supported
• Plain C and Objective-C — no dependencies

⚠️ Dieses Tool ist in der aktuellen Version auf einfache HID-Gamepads ausgelegt:

• Es kann nur ein Gerät gleichzeitig handhaben.
  Wenn ein weiteres Gerät während der Laufzeit angeschlossen wird, ist das Verhalten undefiniert.

• Es werden nur HID-Geräte unterstützt, die alle relevanten Daten (Buttons, Achsen)
  in einem einzigen Report senden – typischerweise mit Report-ID 0x30.

• Split-Reports, wie sie z. B. von PS3-Controllern verwendet werden, werden aktuell nicht unterstützt.

• Die Konfiguration (Tasten & Achsen) erfolgt manuell über die Datei:
  ~/Library/Application Support/HIDToKey/config.json

Eine zukünftige Version könnte:

• mehrere Geräte gleichzeitig handhaben
• Reports automatisch dekodieren (per IOHIDElement)
• dynamisches Mapping über eine GUI ermöglichen

When the joy4ge framework is active (means you installed it correctly and then started Google Earth) and you have plugged in a USB HID device to your computer you should see in the Apple Console Log entries like this:

12.08.15 08:44:13,224 Google Earth[2885]: InstallConnexionHandlers()
12.08.15 08:44:13,225 Google Earth[2885]: RegisterConnexionClient(signature = 45727468, name = (null), mode = 0001, mask = 00003F00)
12.08.15 08:44:14,281 Google Earth[2885]: HID device plugged: PS3/PC Adaptor
12.08.15 08:44:14,282 Google Earth[2885]: Number of detected axis: 4
12.08.15 08:44:14,282 Google Earth[2885]: Number of detected buttons: 12

When you execute HIDToKey in a terminal, you'll see something like:

🎮 Starte HIDToKey (alle Buttons → Tastatur)
✅ Lausche auf Eingaben...
➡️ down
➡️ up
🇷2️⃣ down
🇷2️⃣ up
X ⇦ down
X ⇦ up

Useful for debugging mappings or identifying unknown buttons/axes.

For the original 3DconnexionClient.framework, a configuration file is created at:

~/Library/Application Support/3DconnexionClient/controller.config.plist

It includes for each controller it was connected to:

• Button and axis mappings
• Deadzone calibration
• Sensitivity scaling

The first generated configuration will be based on the developer's default controller. You can manually edit this file to match your device.

⚠️ Documentation on the structure of this config is still minimal. Check the source code for guidance.

• Goal was to support a wide range of HID devices (PS3-style, wheel pedals, flight sticks, etc.)
• Currently designed for macOS
• HIDToKey requires no system extensions or root privileges
• A future GUI for mapping and calibration is welcome — join the project!

On macOS 14.x (Sonoma), Google Earth Pro 7.3.6.x crashes at startup when a Bluetooth HID device (e.g. Gamepad Controller) is already connected before launching the application. This happens on Apple Silicon (Rosetta) installations. Crash does not occur when:

• a HID gamepad controller is connected via USB, or
• the Bluetooth HID controller is connected after GE has started.

⚠️ This is a bug in Google Earth Pro 7.3.6.x and happens completely without joy4ge installed! It is just listed here since you will very likely see it when using joy4ge with a Bluetooth HID controller.

1. Pair a Bluetooth HID controller
2. Launch Google Earth Pro.
3. App crashes within 1–2 seconds.

• macOS 14.7
• GE Pro 7.3.6.10201
• Apple M1 via Rosetta (64-bit Intel)

Google Earth seems to register for HID devices directly during initialization, possibly without checking if the HID stack is fully ready (especially for Bluetooth devices, which may initialize asynchronously). This might trigger a crash due to incomplete or invalid device state.

Turning off Bluetooth before launching Google Earth avoids the crash.

• Added: HIDToKey as browser-compatible fallback tool
• Updated: readme changed to readme.md
• Axis deadzone handling and shift modifiers fully working
• Project converted to GitHub with MIT License
• build.sh script added

• Compatible with Google Earth Pro 7.3.4.8248
• Added: Support for SetConnexionHandlers()
• Works only from /Library/Frameworks/, not ~/Library/Frameworks/

• Google Earth 7.3.3.7786 compatibility
• Framework must now be installed in /Library/Frameworks/
• Google Software Update interferes — workaround: block with Little Snitch

• Added: Example configuration
• Updated: Project for Xcode 7.3.1
• Updated: 3Dconnexion API v10-4-4 (r2541)
• Google Earth Pro 7.3.0.3832 support

• Updated: for XCode 6.2 and SDK 10.9
• Updated: 3DconnexionClient framework version updated from 1.7.1 to 10.2.2
• Added: readme

• Initial project started

• Waitsnake — original author of joy4ge and HIDToKey.m
• Keysworth (ChatGPT/OpenAI) — co-author and helper for HIDToKey.m

MIT License — see LICENSE file for full text.

Use at your own risk. The authors are not responsible for damage caused by this software.
Compatible with all USB HID devices on macOS that follow standard descriptors.