Virtual Keyboard · Four connection modes
Virtual Keyboard offers three modes that use eTouch on the Mac — Bluetooth, LAN and USB — plus a lab-only Universal Bluetooth mode that needs no Mac app. Switch at any time from Connection Management on the phone home screen.
Which one to choose
- Bluetooth: best on the go, no Wi-Fi needed, with middle-of-the-road bandwidth and latency. The first connection needs a 6-digit code.
- LAN: use it when the phone and Mac share a Wi-Fi network. Bonjour finds the Mac automatically and latency is lower than Bluetooth. The first connection needs a 6-digit code.
- USB cable: the lowest latency and the most stable option, unaffected by Wi-Fi or Bluetooth. Plugging in switches to USB automatically; no pairing code.
- Universal Bluetooth: the phone acts as a standard Bluetooth HID device for macOS, Windows, Linux and iPad without a companion app. Features are limited, and it is off by default.
Latency from low to high: USB, LAN, Bluetooth.
Bluetooth
Bluetooth uses a custom BLE GATT service. The phone is the peripheral and the Mac connects to it.
- Make sure eTouch is running.
- Choose Bluetooth on the phone.
- Read the 6-digit code from the Mac menu bar, eTouch popover or main window.
- Enter the code on the phone.
Both sides store a token after pairing and reconnect automatically on launch. A wrong code shows how many attempts remain; an expired code can be refreshed with Get a new code, without restarting.
The connection interval is controlled by the Mac; the phone can only request low latency. Input usually lands within tens of milliseconds, with slight variation when many Bluetooth devices are nearby.
LAN
LAN uses TCP port 45120 with Bonjour discovery. The phone is the client.
- Put the phone and Mac on the same Wi-Fi or wired LAN.
- Choose LAN on the phone.
- Pick the Mac under Available Devices. The last Mac used reconnects automatically.
- Enter the 6-digit code shown on the Mac on first use.
If Bonjour discovery fails, check Local Network permission, that Wi-Fi is on, whether a VPN or proxy blocks mDNS, and whether the router uses client isolation. A USB cable is a reliable alternative that does not depend on the network.
USB cable
USB uses a local tunnel through usbmuxd and then the same protocol as LAN. It needs no Wi-Fi, Bluetooth or pairing code.
- Connect the phone and Mac with a data-capable cable. Charge-only cables do not work.
- Unlock the phone and choose Trust if the system asks whether to trust the computer.
- The phone detects USB and switches to it automatically.
If you plug in during a wireless session, the app switches from Bluetooth or LAN to USB immediately and reuses the established connection. If the cable is removed and no connection returns within four seconds, it falls back to the previous wireless mode and reconnects. After you choose a transport manually, the app will not auto-switch to USB again until it restarts; the plug-in-first behavior returns on the next launch.
Universal Bluetooth (lab)
Universal Bluetooth uses the standard Bluetooth HID service. The target sees the phone as keyboard, mouse, media and gamepad HID devices. It does not use the app's private frame protocol or eTouch.
- Turn on Universal Bluetooth under Settings → Lab Features.
- Return to Connection Management and choose Universal Bluetooth.
- On the Mac, Windows, Linux or iPad, connect to the device named like
VK-<phone name>in Bluetooth settings. On a Mac the first connection is manual; after that it reconnects automatically. - Connected hosts can be selected as the input target. With several hosts, input goes to the Default Host.
Limitations of Universal Bluetooth:
- Clipboard, dictation, non-ASCII text keys and some unmapped media keys are unavailable.
- Horizontal scrolling is not declared by default, so some hosts cannot scroll sideways. Turn on Horizontal Scrolling in Connection Management; the mouse HID service is rebuilt and the host must reconnect.
- Hosts may cache the old HID descriptor. If the phone says connected but the host receives nothing after reinstalling or restarting the app, press Re-broadcast first; if that fails, turn Bluetooth off and on again on the host.
- The connection page has a Compatible with Android (no encryption) switch. Turning encryption off weakens security; use it only when a host cannot connect otherwise.
Pairing, reconnecting and multiple devices
- Pairing: Bluetooth and LAN need a 6-digit code on first use and then store a token for automatic reconnection. USB is trusted as soon as the link is established and needs no code.
- Automatic reconnect: wireless links back off at 1, 2, 4 seconds and up to about 64 seconds. LAN reconnects only to the last Mac used; other Macs must be selected manually. Bluetooth and USB connections are initiated by the Mac.
- One phone, several Macs: the phone remembers multiple paired Macs and switches the input target from the target row or Connection Management. Before switching, it releases keys held on the old Mac.
- One Mac, several phones: all three app transports can accept multiple phones at once, and input is merged on the Mac. Keys and mouse buttons are reference-counted; continuous gestures belong to the phone that started them.
- Device role: Settings can limit the phone to Keyboard Only or Trackpad Only. The default, Automatic, follows the current page.
Encryption and privacy
- Bluetooth / LAN: after pairing, the two sides derive frame encryption from the token; input does not travel in plaintext over the network.
- USB: plaintext by design, but bound to the phone's loopback address and carried through the usbmuxd tunnel, so other devices on the Wi-Fi cannot connect to it.
- Universal Bluetooth: uses system Bluetooth pairing and HID, not the app's frame encryption. Pairing encryption is required by default and can be disabled on the connection page for older hosts.
- Every connection is direct between the phone and your Mac. Nothing goes through Flavor servers, and the Mac app does not upload input.
Known limits
- The macOS login window and FileVault unlock screen are not supported; the protocol link only becomes available after the user session starts.
- Switching the phone to the background, locking it or suspending the app disconnects input.
- Universal Bluetooth requires the foreground with the screen on. The app removes the HID peripheral when it goes to the background.
- Bluetooth and LAN need eTouch running; Universal Bluetooth does not, but has fewer features.
Next: Keyboard, layouts and remotes · Connections and troubleshooting