Background

Our LANforge InterOp solution is used to support real client testing for access points. InterOp combines the benefits of testing with real clients with customizable testing and reporting.

We have support for various kinds of real clients:

-      Android clients.
-      iOS clients.
-      Windows Machines.
-      Linux Machines.
-      MacOS Machines.

Network Topology:

Hands-Free Device Control:

In order to provide a hands-free solution for iOS testing, LANforge controls each device via a Bluetooth connection. USB Bluetooth adapters plugged into the LANforge act as Bluetooth keyboard devices. An adapter connects with the iOS device and then sends it keystroke packets. These keystrokes are interpreted by the device as actions, and it's possible to perform system functions, navigate the UI, send text, etc.

Supported Devices:

The LANforge InterOp iOS platform supports the following devices:

(iOS 17/18)

• iPhone SE (2nd Gen)
• iPhone SE (3rd Gen)
• iPhone 11 (Base, Pro, Pro Max)
• iPhone 12 (Base, Pro, Pro Max, Mini)
• iPhone 13 (Base, Pro, Pro Max, Mini)
• iPhone 14 (Base, Pro, Pro Max, Plus)
• iPhone 15 (Base, Pro, Pro Max, Plus)
• iPhone 16 (Base, Pro, Pro Max, Plus)
  
  

(iPadOS 18)

• iPad (7th/8th/9th/10th generation + A16)
• iPad Pro 11-inch (1st/2nd/3rd/4th generation + M4)
• iPad Pro 12.9-inch (3rd/4th/5th/6th generation)
• iPad Pro 13-inch (M4)
• iPad mini (5th/6th generation + A17 Pro)
• iPad Air (3th/4th/5th generation + M2/M3)

Before getting started:

The LANforge Manager this device will be clustered with must be in clustering mode. That includes configuring the realm, mode, and resource number of the manager, as well as having the right licenses. Please verify you have the correct licenses and follow this cookbook to set your manager up.

Hardware Requirements:

• a supported iOS Device (see above).

• a USB cable for connecting the device to a LANforge unit (USB-A to Lightning/USB-C).
  using a USB 2.0 cable is preferred in order to prevent bluetooth interference.

• a USB Bluetooth 5.0 adapter (Edimax BT-8500 and TP-Link UB500 are known to work).

• a LANforge system with at least two free USB ports.

• a Mac Mini for ios configuration and screen mirroring purposes (optional).

LANforge Machine Installs/Config

1. Open a terminal on your LANforge machine (and mac mini if in use) and run:
   sudo ./lf_kinstall --do_ios_tools
   Then restart LANforge so that it notices the new IOS binaries:
   sudo /home/lanforge/serverctl.bash restart

iOS Device Initial Setup

2. For a new iOS device, ensure that the initial Apple setup is complete and that the device is logged into an Apple account. Ensure also that the lock screen passcode is disabled. This can be disabled in Settings->Face ID & Passcode.

3. Download LANforge InterOp (beta) onto the device by opening the Testflight Invite Link in the device's browser. You can access this link by re-opening this cookbook on your device (search the web for this cookbook via 'Candela iOS setup' or similar).
   If this method is not working, you may require an invite to be sent to you. In this case, please contact Candela support.

4. Download TestFlight, Open TestFlight, and install the LANforge InterOp App. It's recommended that most users disable Automatic Updates. But users who frequently update their testbed with new LANforge beta builds should leave it enabled. This way, iOS devices with an internet connection will automatically stay updated with the latest InterOp App releases.

5. Open the LANforge App and accept TestFlight prompts.

6. Open the Settings App on the device.

   1. Disable All Keyboard Settings shown

   

   2. Set Display Auto-Lock to Never

   

Connecting the iOS Device to LANforge

Note: If using a Mac Mini, both the Mac and the iPhone must be signed into the same Apple ID.

7. Connect the device via its USB port (Lightning or USB-C) to one of the USB-A slots on the LANforge. (as per the testbed topology)

8. On the device screen, when prompted about trusting the computer, select 'Trust'.

9. Open the LANforge GUI window. The Interop tab should appear now. Click on the tab to see your device detected as an InterOp device.

Connecting Bluetooth USB Adapter

10. Open a terminal on the LANforge machine and run:
    dmesg -w

11. Plug your USB Bluetooth dongle into one of the USB ports on the LANforge.

12. The terminal window should show dmesg output acknowledging the new USB device.
    

13. The string 'usb 1-2.1.4' indicates that '2-1-4' is the USB-path of the adapter. Write this down.

Setting up iOS Device Keyboard Control

14. On your LANforge machine, select the iOS device in the Interop tab and click the button labeled Batch-Modify.

• Note: In LANforge version 5.5.2 and above, this configuration has been moved to the button labeled Modify.

15. In the Batch-Modify window (or Modify if 5.5.2) enter the Bluetooth Controller’s USB path (found from dmesg earlier). And click Apply to start the Bluetooth control process.

Connecting via Mac Mini

• If configuring on a Mac Mini, we need to configure path with format:
  Resource-{SHELF}.{RESOURCE}:{USB-PATH}

16. On the device, open the Bluetooth settings page and enable Bluetooth.

17. Keep watch on the device's Bluetooth settings page and a connection prompt should appear. Select ‘Pair’ to pair the device with your Bluetooth adapter.

18. On the device, open the Keyboard Accessibility settings and enable 'Full Keyboard Access'.

19. The device MUST be in the 'Full Keyboard Access' screen before running this step, see above. Back in the LANForge Batch-Modify window, tap the Set BT Keybinds button. Allow 5-10 minutes for this command to run and do not interfere with the process by touching the screen or power-cycling the device. Once this command is finished, the device will return to the home screen and appear idle again.

20. To ensure that the keyboard shortcut setup process was successful, re-open the Full Keyboard Access settings page and check for any differences against these expected values below.

iPhone Keyboard Shortcuts

iPad Keyboard Shortcuts

Additional Configuration if running iOS 26 or above:

Building LANforge Shortcut and Setting Keybind

1. In the LANforge Modify window, open the iOS Settings tab and tap the BUILD_SHORTCUT button. Allow 5-10 minutes for this command to run and do not interfere with the process by touching the screen or power cycling the device. Once this command is finished, the device will return to the home screen and appear idle again.

2. The device MUST be in the 'Full Keyboard Access' screen before running this step, see above. Now, tap the SET_SHORTCUT_KEYBIND button. As before, do not interfere with the device while it sets this keybind. Once complete, the device will again return to the home screen.

Follow these steps if the shortcut creation fails. We can build the shortcut manually.

1. On the device, open the Shortcuts app.
2. Navigate to the Library tab on the bottom of the screen and select the + icon in the upper right corner of the screen.

3. In the search bar type "Open App" and select this option.

4. Select the highlighted App field and search for LANforge InterOp. After selecting this, the phone will return to the previous screen.

5. At the top of the screen, select the down-arrow next to Open App and tap Rename. Change the name to Lanforge.

6. You may now return to the home screen.

Starting the LANforge App

21. Set the values needed to connect the device to LANforge: LANforge Manager IP and Resource ID (must be a Resource ID that's not in use). And if you wish to automatically connect the device to a WiFi network, then enter the SSID and password. Click Apply when done populating fields. The app will restart and attempt to connect using the configured values.

22. Wait for roughly a minute. And if this is your first time connecting the device to LANforge, you will need to manually accept some authorization prompts. If you do not see these prompts appear, ensure that your configuration values are correct and that the device is connected to the correct network. After this, use the batch-modify window to Stop (wait for it to complete) and then Start the app again.

23. Open the Resource Mgr tab and the iOS device should appear under the requested resource ID.

24. Back in the Port Mgr tab, we can see the iOS device's ports, IP address, and MAC address.

25. Your iOS device is now ready for use with LANforge testing.

Known Limitations:

1. A LANforge CT521B system supports management of up to four iOS devices connected via USB, where each is paired with its own USB bluetooth dongle that is also connected to the system. (4 devices + 4 dongles)

2. Screen Mirroring iOS devices on Fedora-based LANforge systems is not yet supported. But screen mirroring on MacOS machines is supported.

3. Automated installation and removal of the iOS InterOp app through the Interop tab's Batch-Modify window is not yet supported.