Skip to content

feat(hid): map Windows Alt to iPad Globe - #5

Open
s-qin wants to merge 1 commit into
Divisionless:mainfrom
s-qin:feat/ipad-alt-globe
Open

feat(hid): map Windows Alt to iPad Globe#5
s-qin wants to merge 1 commit into
Divisionless:mainfrom
s-qin:feat/ipad-alt-globe

Conversation

@s-qin

@s-qin s-qin commented Sep 9, 2026

Copy link
Copy Markdown

Motivation

OpenSpan currently ships with Windows Alt mapped to iPad Command. Windows
Win/GUI already maps to the HID GUI modifier, which iPadOS treats as Command,
so the default layout gives two physical modifiers the same role.

The natural Command entry remains the Windows key. Ideally a PC Fn key could
provide iPad Globe, but many laptop Fn keys are handled below Windows in
firmware / the embedded controller and never reach WH_KEYBOARD_LL. On the
Lenovo Y9000P used for the real-hardware test, pressing Fn alone produced no
VK/scancode event in a keyboard-event tester, so a generic Fn -> Globe mapping
is not available to OpenSpan.

This feature intentionally uses a cross-platform UX mapping instead:

  • Win -> Command (unchanged)
  • Alt -> Globe

It preserves every Command shortcut while exposing the iPadOS Globe system
shortcut layer on ordinary Windows keyboards without relying on vendor-specific
Fn firmware behavior.

Technical basis

Globe is not a ninth bit in the normal HID keyboard modifier byte. The feature
adds a separate HID Consumer Control input report:

  • Usage Page: Consumer (0x0C)
  • Usage: AC Next Keyboard Layout Select (0x029D)
  • Report ID: 3
  • Report Reference: 03 01 (ID 3, Input)
  • Press payload: 9D 02
  • Release payload: 00 00

This is standards-based Globe system-shortcut support. It does not claim
to emulate the complete Apple vendor Top Case Fn usage (0x00FF:0x0003) or
its Fn+Backspace / Fn+Arrow semantics.

Implementation

  • Change the shipped keymap default from alt: cmd to alt: globe; Win/GUI
    remains the existing Command modifier path.
  • Add Consumer Report ID 3 and its HOGP Report characteristic.
  • Preserve Consumer/keyboard report ordering so held Alt can chord with normal
    keys.
  • Release Globe on Alt-up, Portal exit, exact overrides, synthetic clipboard
    chords, owner TCP disconnect, and BLE disconnect.
  • Token-guard ownership so an old socket cannot clear a newer connection's
    held Globe state.
  • Report consumer_subscribed separately without changing existing keyboard
    readiness behavior.

Validation

Automated:

  • Host Globe tests: 8/8 PASS
  • Debian guest Globe tests: 9/9 PASS
  • JSON validation: PASS
  • Python py_compile: PASS
  • git diff --check: PASS
  • The repository's script-style win/test_pair_flow.py has the same eight
    existing UI expectation failures on untouched upstream/main; this feature
    does not modify that flow.

Real hardware (iPadOS over BLE HOGP):

  • Win+Tab remains Command+Tab
  • Alt no longer behaves as Command
  • Alt+Up triggers Globe+Up / iPadOS App Switcher
  • A second Globe system shortcut works
  • Alt release leaves no stuck Globe state
  • Repeated Alt/Globe use is stable
  • Ctrl/Shift/ordinary keys remain normal
  • Keyboard, mouse, native pointer and same-radio A2DP coexistence remain active

Protocol references

  • USB HID Usage Tables 1.6: Consumer 0x029D, AC Next Keyboard Layout Select
  • Bluetooth HOGP: Report Map / Report characteristic / Report Reference model
  • Flipper Zero's inspectable USB/BLE HID Globe implementation and iPad user
    validation
  • ZMK's GLOBE / C_AC_NEXT_KEYBOARD_LAYOUT_SELECT definition
  • Linux hid-apple and Apple IOHID sources for the separate vendor Fn usage

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant