Codex Micro Scroll

Proportional macOS scrolling for the planar joystick on the Work Louder Creator Micro 2 / Codex Micro.

The bridge reads normalized joystick angle and distance from the device's vendor HID channel and emits native pixel-based scroll events. It works over USB and Bluetooth.

Important

This is an unofficial community project, not Work Louder software. The vendor HID protocol is undocumented and may change in future firmware. Configuration writes are backed up and verified, but you use them at your own risk.

What it changes

The configurator changes only the joystick mapping on the currently active profile and layer. It replaces the radial menu with two KC_NONE sectors so the firmware continues emitting its analog kb.radial angle and distance notifications without triggering shortcuts. All other keys, macros, profiles, lighting, and smart actions remain untouched.

Install on a new Mac

Requirements:

• macOS 13 or newer
• Node.js 18 or newer
• Apple Command Line Tools (xcode-select --install)

git clone https://github.com/AnshSancheti/codex-micro-scroll.git
cd codex-micro-scroll
npm ci
swift build -c release

Connect the Micro in wired USB mode, select the profile and layer where you want analog scrolling, quit Work Louder Input, and inspect the proposed change:

npm run configure -- --dry-run

Apply and verify it:

npm run configure

The original keymap.json is saved under the ignored backups/ directory. After configuration succeeds, reconnect over Bluetooth if desired.

Run

./run.sh --max-speed 1400 --dead-zone 0.20 --curve 1.7

The first launch may require allowing Terminal under System Settings → Privacy & Security → Accessibility.

Options:

• --max-speed: full-deflection speed in pixels per second.
• --dead-zone: ignored center region from 0 to 0.9.
• --curve: response curve; larger values give more low-speed control.
• --horizontal: enable horizontal scrolling from the X axis.
• --invert-vertical: reverse vertical direction.
• --debug: print sampled live joystick values.

Press Control-C to stop. Keep Work Louder Input closed while the bridge is in use; Input can restore its own radial mappings.

If the device disconnects or radial updates stop unexpectedly, the bridge immediately returns the scroll axes to neutral and exits on a transport error.

Back up or restore your own device configuration

Configuration exports are personal and intentionally ignored by Git. Export the currently connected device to private-config/:

npm run export-config

Restore that directory later over wired USB:

npm run import-config -- --yes

Use --to <directory> when exporting or --from <directory> when importing a different location. Import overwrites the complete device configuration, so it requires --yes and creates timestamped local backups first.

How it works

1. The Node bridge opens the Creator Micro 2 vendor HID interface through node-hid.
2. Firmware notifications named kb.radial provide continuous joystick angle and distance.
3. The bridge converts polar input into normalized X/Y axes.
4. A small native Swift process applies the dead zone and response curve and posts pixel-based Core Graphics scroll events at 120 Hz.

The bridge prefers USB when both USB and Bluetooth interfaces are visible. Configuration writes require USB. A 350 ms watchdog prevents stale input from continuing to scroll if notifications stop.

Development

npm ci
npm test
swift build -c release

The pure joystick conversion, watchdog behavior, and transport selection have unit coverage. Hardware behavior still requires a Creator Micro 2.

Compatibility

• macOS 13 or newer
• Work Louder Creator Micro 2 using USB or Bluetooth for scrolling
• Wired USB for configuration writes

This project matches USB VID/PID 303A:8298. Other Work Louder devices are not selected. If a firmware update changes the vendor protocol, open an issue with the device model, firmware version, connection type, and debug output.

License

MIT