iKontroller for Mac

Setup Guide

1. Download iKontroller from the Mac App Store
2. Launch the app and enter your username
3. Grant Accessibility permission when prompted
4. Grant Local Network permission when prompted
5. The Mac app will start advertising itself and browse for iOS devices

Granting Accessibility Permissions

iKontroller requires Accessibility permissions to simulate keyboard and mouse input from your iPhone and iPad.

How to Grant Permission:

1. Open System Settings (or System Preferences on older macOS)
2. Navigate to Privacy & Security
3. Click on Accessibility
4. Click the + button (you may need to unlock with your password)
5. Find and select iKontroller
6. Ensure the checkbox next to iKontroller is enabled
7. Restart iKontroller if it was already running

Device Pairing

Pairing a New iPhone or iPad

1. Ensure the iPhone/iPad and Mac are on the same network or connected via USB-C/Lightning cable
2. On your Mac, go to the Device Pairing tab
3. On iOS, select your Mac from the discovered devices
4. A 6-digit code will appear on your Mac
5. Enter this code on your iOS device
6. The devices are now paired!

Managing Paired Devices

• Forget: Remove a device as paired and delete all its mappings and data
• Block: Remove a device as paired, delete all its mappings and data and prevent the device from pairing again. A blocked device cannot send you any data
• Unblock: Settings → Blocked Devices → Unblock

Settings & Customization

Adjusting Sensitivity

Go to Settings → General:

• Relative Sensitivity: Controls in-game camera movement speed
• Scroll Sensitivity: Controls scroll wheel speed

Changing Username

1. Go to Settings → General
2. Click the pencil icon next to your username
3. Enter new username
4. Click Save (the app will validate the name)

Active Keys Visualization

iKontroller shows floating visual feedback of active keys on your Mac screen. This helps with:

• Verifying key presses during gaming
• Streaming or recording gameplay
• Debugging custom mappings

Keys appear as they're pressed and fade out when released.

Troubleshooting Mac Issues

Keys Not Working/Stuck Keys

• Verify Accessibility permissions are granted
• Disconnect and reconnect your iPhone/iPad
• iKontroller has automatic stuck key detection and correction; Press or use the button/joystick that caused the stuck key(s) again and it should get released
• Press the stuck key on your physical keyboard to release it

Mouse Cursor Behavior Issues

• Adjust Relative Sensitivity in Settings
• Switch between Relative and Absolute modes on iOS

Connection Drops After Network Change

• iKontroller automatically detects network changes
• Both apps will attempt to reconnect
• If reconnection fails, manually disconnect and reconnect on iOS

Firewall Blocking Connections

If using a firewall:

1. Open System Settings → Network → Firewall
2. Click Options
3. Ensure iKontroller is allowed to receive incoming connections
4. Add ports 8888, 8889, 8896, 8897, 8898, 8899 if using custom firewall rules

Technical Details

Network Ports Used

• TCP 8888: Main connection for pairing and mappings
• UDP 8889: Main connection for pairing and mappings (ultra high-frequency)
• TCP 8898: Dedicated to binary controls data (buttons and joysticks input)
• TCP 8899: Dedicated to binary touchpad data (touchpad and mouse input)
• UDP 8896: Dedicated to binary controls data (ultra high-frequency buttons and joysticks input)
• UDP 8897: Dedicated to binary touchpad data (ultra high-frequency touchpad and mouse input)

Supported Features

• Apple Silicon (M1/M2/M3/M4) and Intel Macs
• Multiple external displays
• Full-screen/minimized/windowed apps and games
• Modifier keys (Shift, Command, Option, Control)
• Reference-counted key presses (prevents stuck keys)
• Sub-20ms input latency on local networks