First Connection

This guide walks you through connecting your iPhone to Specchio for the first time.

Table of Contents

1. Launch Specchio
2. Initial Setup Wizard
3. USB Connection
4. WiFi Connection
5. First Launch Process
6. What to Expect

---

Launch Specchio

If Building from Source

cd /path/to/Specchio
xcodebuild build -project Specchio.xcodeproj -scheme Specchio
open /path/to/Specchio.app

If Using a Pre-built Release

1. Download the latest .dmg or .zip from the Releases page
2. Open the downloaded file
3. Drag Specchio to Applications
4. Open Specchio from Applications

First Launch

When you launch Specchio for the first time, you may see:

• A macOS security prompt (click Open)
• A setup wizard if any prerequisites are missing

---

Initial Setup Wizard

Specchio automatically checks for required components. The setup wizard will guide you through any missing items.

What the Wizard Checks

The wizard verifies:

1. ✅ Xcode is installed
2. ✅ Xcode license is accepted
3. ✅ iOS Platform SDK is installed
4. ✅ Apple Development certificate exists

If Everything is Ready

You'll see a "All set!" message. Click Continue to proceed.

If Something is Missing

The wizard will show you what's missing with a Fix button. Click it to open instructions or automatically fix the issue.

---

USB Connection (Recommended)

USB connection provides the lowest latency and most reliable experience.

Step 1: Connect Your iPhone

1. Use a Lightning or USB-C cable
2. Connect your iPhone to your Mac
3. Ensure your iPhone is unlocked
4. Tap Trust if prompted on your iPhone
5. Enter your passcode if prompted

Step 2: Select Your Device in Specchio

1. In Specchio, click the Connect button or open the device picker
2. Your iPhone should appear in the list
3. Click on your iPhone to select it
4. Click Connect via USB

Step 3: Wait for WebDriverAgent Installation

The first connection takes about 60 seconds while Specchio:

• Builds WebDriverAgent for your specific device
• Installs it on your iPhone
• Starts the WDA server

You'll see progress indicators:

• "Building WebDriverAgent..."
• "Installing on device..."
• "Starting server..."

Step 4: Connection Established

Once connected:

• Your iPhone screen appears in the Specchio window
• You can now control your iPhone with your mouse and keyboard
• Subsequent connections take only ~5 seconds

---

WiFi Connection

WiFi connection allows wireless freedom but requires additional setup.

Prerequisites

• Both Mac and iPhone on the same WiFi network
• WiFi debugging enabled on your iPhone (see Device Setup)
• Specchio Premium license (WiFi connection is a premium feature)

Step 1: Enable WiFi Debugging

If you haven't already:

1. Open Xcode on your Mac
2. Go to Window → Devices and Simulators
3. Select your iPhone
4. Check Connect via network
5. Unplug your iPhone — it should remain visible in Xcode

Step 2: Connect via WiFi in Specchio

1. Make sure your iPhone is on the same WiFi network as your Mac
2. In Specchio, open the device picker
3. Your iPhone should appear with a WiFi icon
4. Click Connect via WiFi

Step 3: First WiFi Connection

The first WiFi connection also takes ~60 seconds for WebDriverAgent setup.

---

First Launch Process

What happens behind the scenes during your first connection:

1. Device Detection (2 seconds)

Specchio uses libimobiledevice to detect connected iOS devices.

2. USB Tunnel Setup (3 seconds)

Specchio launches iproxy to tunnel port 8100 from your iPhone to localhost on your Mac.

3. WebDriverAgent Build (45-60 seconds, first time only)

Specchio compiles WebDriverAgent specifically for your device:

• Uses Xcode's command-line tools
• Signs the app with your Apple Development certificate
• Installs via XCUITest framework

4. WDA Server Start (5 seconds)

The WebDriverAgent app launches on your iPhone and starts its HTTP server on port 8100.

5. Handshake (2 seconds)

Specchio connects to the WDA server and performs:

• Version compatibility check
• Screen capability detection
• Input capability verification

6. Streaming Begins

Your iPhone screen starts streaming to your Mac!

---

What to Expect

First Connection Performance

Step	Duration	Notes
USB detection	~2 seconds	Fast, happens every time
iproxy tunnel	~3 seconds	Fast, happens every time
WDA build	~45-60 seconds	Only on first connection!
WDA install	~5 seconds	Only on first connection
Subsequent connections	~5-10 seconds	WDA is cached on device

Screen Quality

• USB Video Mode: Pixel-perfect, 30-60 FPS (best quality)
• WiFi Screenshot Mode: Pixel-perfect, 5-15 FPS
• Lite Mode: Synthetic UI, 2-5 FPS (lowest bandwidth)

Input Latency

• USB: Nearly instantaneous (imperceptible delay)
• WiFi: Slight delay (10-50ms depending on network)

---

Verifying Your Connection

Check Device is Connected

In Terminal, run:

# Check if iproxy is running (should show process)
ps aux | grep iproxy

# Check if port 8100 is listening
lsof -i :8100

# Test WDA connection
curl http://localhost:8100/status

Expected output for the last command:

{
  "value": {
    "state": "success",
    "os": {
      "name": "iOS",
      "version": "17.0"
    },
    "ios": {
      "ip": "169.254.22.19"
    },
    "time": "2024-04-16T12:34:56Z"
  },
  "sessionId": "..."
}

Check Screen Streaming

If screen is black or not updating:

# Check WDA screenshot endpoint
curl http://localhost:8100/screenshot --output test.png
open test.png

This should save a PNG of your iPhone screen. If it works, WDA is functioning correctly.

---

Next Steps

Now that you're connected:

1. Explore Connection Modes to learn about USB vs WiFi
2. Try different Display Modes for your needs
3. Learn about Keyboard & Mouse Controls
4. If something isn't working, check Troubleshooting

---

Troubleshooting First Connection

"Device Not Found"

Problem: Your iPhone doesn't appear in the device list.

Solutions:

• Make sure your iPhone is unlocked
• Try a different USB cable
• Try a different USB port
• Restart your iPhone and Mac
• Re-enable "Trust This Computer" on your iPhone

"WebDriverAgent Build Failed"

Problem: WDA build fails with an error.

Solutions:

• Verify Xcode is properly installed: xcodebuild -version
• Verify iOS SDK is installed: xcodebuild -showsdks
• Verify you have an Apple Development certificate
• Check that your device is in Developer Mode
• Try deleting ~/Library/Developer/Xcode/DerivedData/Specchio-* and retry

"Connected but Screen is Black"

Problem: Connection succeeds but no screen appears.

Solutions:

• Try a different display mode (use the mode switcher)
• Check that your iPhone is not locked
• Run the diagnostic command: curl http://localhost:8100/screenshot --output test.png
• Check the logs in Specchio (View → Show Log)

"Very Slow/Laggy Connection"

Problem: Screen updates are slow or input is delayed.

Solutions:

• For best performance, use USB connection
• Try "Lite" display mode for lower bandwidth
• Close other apps using your network
• Check your WiFi signal strength if using WiFi

For more help, see the full Troubleshooting section.