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:

Supported Devices and iOS Versions:

The LANforge InterOp iOS platform supports the following devices and iOS Versions:

(iOS 17/18)

• iPhone SE (2nd generation and later)
• 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)

(iOS 26)

• iPhone SE (2nd generation and later)
• 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)
• iPhone 17 (Base, Pro, Pro Max)
• iPhone Air

(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)

(iPadOS 26)

• iPad (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 (M4/M5)
• 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).

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

Optional Hardware:

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

• a USB Bluetooth Device (The TP-Link UB500 is known to work well.)

LANforge Machine Installs/Config

1. Fetch the latest version of lf_kinstall. Open a terminal on your LANforge machine and run:
   wget https://www.candelatech.com/lf_kinstall.pl
   Allow for the newly downloaded script to execute:
   chmod +x lf_kinstall.pl
2. Open a terminal on your LANforge machine (and mac mini if in use) and run:
   sudo ./lf_kinstall.pl --do_ios_tools
   Then restart LANforge so that it notices the new IOS binaries:
   sudo /home/lanforge/serverctl.bash restart

iOS Device Initial Setup

This section describes the setup needed to control an iOS device using command line tools. This is the preferred method of controlling iOS devices as of LANforge 5.5.3. If your testbed is using LANforge 5.5.3, the device can be optionally configured to use an emulated Bluetooth keyboard to control the device. The Bluetooth keyboard control is the only method of controlling iOS devices using LANforge versions 5.5.2 and below. The setup for the Bluetooth keyboard is described in the "Configuring the Bluetooth Keyboard" section of this cookbook.

3. Proceed through initial iOS device setup until the device is activated.

4. Connect the iOS device to the LANforge unit with the USB cable. When prompted to trust the computer on the iOS device, select 'Trust'.

5. The first time an iOS device is introduced to the testbed, a certificate file will need to be created. For any subsequent iOS devices, the resulting certificate file can be reused. If multiple devices are being configured, skip steps 6 and 7 after the first device is setup. If you have many iOS devices connected to multiple LANforge machines, you can either copy the certificate file to each LANforge machine or follow the steps to create a certificate on each LANforge unit.

6. Create encryption keys for device supervision:
   ios prepare create-cert

7. Create the supervision certificate:
   openssl pkcs12 -export -inkey supervision-private-key.pem -in supervision-cert.pem -out certificate.p12 -password pass:lanforge -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1
   Do not delete or rename the certificate.p12 file. It will be needed for Wi-Fi automation features to function.

8. Record the UDID of the device being setup:
   ios list --details

9. Setup device supervision using the device UDID and certificate from above:
   ios prepare --udid=<DEVICE_UDID> --certfile=supervision-cert.pem --orgname=LANforge

10. Once the device is setup for supervision, complete the remaining new device setup by logging into an Apple account. If the supervision process was successful, the text "this iPhone is supervised and managed by LANforge" will appear above the Apple ID in the settings app. Ensure also that the lock screen passcode is disabled. This can be disabled in Settings->Face ID & Passcode.

11. Enable developer mode on the device using the UDID obtained in step 8:
    ios devmode enable --udid=<DEVICE_UDID> --enable-post-restart
    The device will restart to enable developer mode. You should see a notification that developer mode was enabled upon the device rebooting.

12. 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.

13. 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.

14. Open the LANforge App and accept TestFlight prompts.

15. Open the Settings App on the device.

    1. Set Display Auto-Lock to Never

    

    2. Set AirDrop receiving to Receiving Off

    

    3. Enable Location Services

    

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.

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

Starting the LANforge App

17. 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.

18. 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.

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

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

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

Configuring the Bluetooth Keyboard

1. Plug your USB Bluetooth dongle into an available USB port on a LANforge machine. If you have a testbed consisting of multiple LANforge machines, the USB Bluetooth dongle can be inserted into any one of them.

2. Open a terminal on the LANforge machine that now holds the USB Bluetooth dongle and run:
   bluetoothctl

3. The terminal window should show show an entry with an accompanying MAC address.
   

4. The string in the format 'XX:XX:XX:XX:XX:XX' is the Bluetooth dongle's MAC address. Write this down.

• Note: You may use the USB path of the Bluetooth Controller instead of the MAC address if desired. Prior to LANforge 5.5.2, you must use a USB path. To do so, open a terminal on the LANforge machine, run dmesg -w, and insert the Bluetooth dongle into a USB port on the LANforge. The terminal window should show dmesg output containing a string in the form 'usb 1-2.1.4', indicating in this case that '2-1-4' is the USB path of the adapter.

5. In the LANforge GUI, select the iOS device in the Interop tab and click the button labeled Modify.

• Note: In LANforge versions prior to 5.5.2, these options are accessed through the Batch-Modify button.

6. In the Modify window (or Batch-Modify if 5.5.1 or older) enter the Bluetooth Controller’s MAC address (found from bluetoothctl earlier) and click Set MAC to start the Bluetooth control process.

Connecting via Secondary LANforge Resource

- If connecting the iOS device and the USB Bluetooth dongle to different LANforge machines, we need to specify which resource machine contains the USB Bluetooth dongle:

• Prior to LANforge version 5.5.2, the secondary resource must be specified like so:
  In general: Resource-{SHELF}.{RESOURCE}:{USB-PATH}
  Example: Resource-1.1:2-1-4

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

8. 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.

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

10. On the device, disable all keyboard settings shown

11. 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.

12. 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

13. In the LANforge Modify window, open the Advanced Settings tab and click the Build Apple 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.

14. 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.

Using BT Scratchpad

Keystrokes can be sent directly to an interop device using the BT Keystroke Scratchpad.

1. Select the target device from the interop tab of the LANforge GUI.

2. Navigate to the BT Keystroke Scratchpad menu.

3. From this menu, keystrokes can be sent to the connected interop device.

3a. To use the scratchpad, type your desired keystrokes into the BT Keystroke Scratchpad text box. You will see the converted forms of those strokes appear in the Converted Keystrokes text box. Once you are ready to send those keystrokes to the connected device, hit Send Keystrokes. Alternatively, select the auto-send checkbox to automatically send new keystrokes to the device as you type them.

3b. In the lower half of the panel, under Common iOS Navigation Commands, there are a set of common keystrokes that you can automatically send to the device simply by clicking. This method is useful for keystrokes that are not present on traditional keyboards like Home Screen.

4. Once a keystroke has been sent, it will appear in the Sent Keystroke Sequences dialogue box.

5. The state of the Bluetooth connection can also be controlled from this menu with the BT Pause, BT Resume, and BT Reconnect buttons.

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.