virtualUSB {Beta version} - Install and config guide on MacOS

1. About virtualUSB

virtualUSB allows users to develop, remote debugging, and test apps on Private and Local mobile devices hosted on Kobiton portal.

2. System Requirements 

2.1 Hardware/Software

  • Mac machine with M1 or Intel processor
  • macOS: Monterey 12 or the latest
  • Xcode version:  Xcode 13 or latest (if you want to test the new beta version of iOS). 
  • Android Studio:
    - For Intel processor Mac machines, we recommend Android Studio Bumblebee 2021.1.1 or the latest
    - For M1 processor Mac machines, we recommend the latest version of Android Studio Chipmunk 2021.2.1

2.2 Prerequisites

  • Preparing debug symbols for iOS devices:

    There is a limitation in downloading debug symbol files for Xcode via virtualUSB: it can be very slow and thus unreliable in a low bandwidth network. Users may need to manually prepare the debug symbols, which are matched with the device’s iOS version. Please contact our Support team to get the debug symbol for your device. After that, copy the debug symbol to your local Mac folder: /Users/<your_username>/Library/Developer/Xcode/iOS DeviceSupport/.

  • To use virtualUSB for Android devices:

3. Download and launch virtualUSB

3.1 Download virtualUSB

Download virtualUSB.dmg to your local location. The install package can be found here:

  • Package for M1 processor Mac machines: https://shorturl.ae/M221f

  • Package for Intel processor Mac machines: https://shorturl.ae/GEuUV

3.2 Configuration

Configure Gigafox API key (required)

For now, a Gigafox API key is required to be able to connect/disconnect to a device via virtualUSB. Please contact our Support team to get deviceConnect server & API key info.

Create a gigafox-device-auth.json file in /Users/{username}/Library/Application Support/virtualUSB (or update the existing file)

  • Edit the json file with the following format:

{
"<DeviceConnect Public IP/Domain>": "<Legacy Gigafox API key>",
"<DeviceConnect Public IP/Domain>": "<Legacy Gigafox API key>",
}

For example: 

{
"host1.kobiton.com": "9xxxxxf7-axx8-4xxa-9xx3-xxxxxxxxxx1a"
"host2.kobiton.com": "7xxxxx59-8xxa-axx4-3xx9-34xxxxxxxxxx"
}

Config API base URL (optional)

If you are not using the Kobiton cloud environment, you will need to update the API base URL to point to your environment.

Navigate to the folder ~/Library/Application Support/virtualUSB, open config.ini file and edit the Kobiton.ApiBaseUrl to the URL that you want to point the app to and restart.

By default, its value will be: Kobiton.ApiBaseUrl=https://api.kobiton.com

3.3 Launch virtualUSB

Navigate to path/to/virtualUSB.dmg folder.

Open virtualUSB.dmg file.

Copy or move the virtualUSB.app file to the Applications folder to make it easy to access. Then, go to the Applications folder, open virtualUSB.app.image-20220513-140626.png

NOTE: if you double-click to open the file, you may be prompted that the app cannot open and see this message:

image-20220516-040845.png

Click “Cancel” then try again by right-clicking on virtualUSB.dmg. Select “Open” in the menu, then click “Open” on the next dialog.

image-20220516-041111.png

image-20220516-041118.png

The first time you launch virtualUSB, it will need the user to enter the Mac admin account password to install the daemon. Enter the password and select OK to move forward.

Then, the application is launched and the Login to Kobiton form is displayed. Use your Kobiton credentials to log in.image-20220513-135958.png

4. Using virtualUSB

4.1 Connect to a device

Once logged in successfully, you will see the list of Private and Local devices assigned to you (from all teams). Choose the device you want to use by selecting the “Connect” button to launch that device:image-20220513-135506.png

Once the device is connected successfully:

  • You'll see the device status changed to “Retained” - a device is kept at “Retained” status for 24 hours unless you disconnect before then. 

  • The Retained devices will automatically be sorted to display at the top of the device list.

  • The “Connection status” column will display the value “Connected”. 

image-20220513-135317.png

4.2 Using devices while connected via virtualUSB

Checking connected devices

For Android devices: In Android Studio, navigate to Device Manager. Under Physical devices, the connected device should be listed there:

Screen_Shot_2022-03-22_at_14.07.03.png

For iOS devices: Connected device(s) should be available in MacFinder:image-20220512-114039.png

Connected device(s) should also be recognized in Xcode: Screen_Shot_2022-03-24_at_08.06.18.png

Screen_Shot_2022-03-24_at_08.06.43__1_.png

Launching a manual session

While connected via virtualUSB, if you want to observe what is happening on the device screen, you can go to the Portal and launch a manual session on that device. When your testing is complete, disconnect virtualUSB first, then end the manual session.

NOTE: The manual session must be kept running while you are working on virtualUSB, i.e. do not end the session before you disconnect virtualUSB.

Sessions might automatically end due to timeout cutoff. To prevent this, open the Manual Session Settings while in your manual session and uncheck the Quit session after staying idle for 10 minutes.

Screen_Shot_2022-05-20_at_12.18.09_AM.png

image-20220517-112853.png

Disconnecting a device

To disconnect a device, go to virtualUSB and select the Disconnect button under the Action column. A dialog will prompt you to confirm the action:image-20220513-135820.png

Save log

Selecting the Save log icon will prompt a dialog for you to select the time period to be included in the log file.image-20220512-022107.png

image-20220513-135849.png

5. Limitations

  • While connected to virtualUSB, a device cannot be launched with multiple manual sessions. Once launched, the manual session should be kept alive until the user disconnects virtualUSB. If the user exits a manual session while the device is still connected to virtualUSB, the device may be stuck at Utilizing status.

  • If the Admin user accidentally cancels a Retained device while it is connected to virtualUSB - other users will see the device with “Online” status but not be able to connect to it.

  • After clicking the “Connect” button, sometimes, you may see the Connection status change to “Offline” or “Error” before successfully “Connected”. We will address this behavior in an upcoming release.

  • On the login screen of virtualUSB, you will not be able to copy/paste into the Username & Password fields.

  • Currently virtualUSB is only offered to Private Devices on Latest Kobiton platform. 
Was this article helpful?
0 out of 0 found this helpful