About virtualUSB

virtualUSB allows users to develop, debug, and test apps on Private and Local mobile devices hosted on the Kobiton Portal.

virtualUSB is available as an option for the Enterprise plan. Please contact support@kobiton.com or your Account Executive if you are interested in adding this feature.

This is the guide to install and configure virtualUSB for macOS. See this guide for how to use virtualUSB.

Prerequisites

Hardware and software requirements

• End-user Mac machine with M1 or Intel processor
• macOS version: Monterey 12 or above
• Xcode version: Xcode 13 or above (version depends on the iOS of the devices you are testing)

NOTE: You cannot run virtualUSB from a Mac that has deviceConnect or Kobiton Desktop installed.

Android requirements

To connect to Android devices via virtualUSB, Android Debug Bridge (adb) from Android SDK Platform-Tools package must be installed.

If you don't already have adb on your workstation, you can download it from Android or install an IDE like Android Studio.

Follow the official Android developer guide to set up the required environment variables for adb.

On your Mac running MacOS Monterey with the default Zsh shell, add the following lines to the ~/.zshrc file (create the file if it doesn't exist) where path/to/Android/sdk is the location of SDK installation directory (the folder containing platform-tools):

export ANDROID_HOME=path/to/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools

Prepare debug symbols for iOS devices

Fetching debug symbol files for Xcode via virtualUSB can be slow and unreliable if your network has a low bandwidth. If this is your case, you'll need to manually prepare the debug symbols, which are specific to the device’s iOS version. If needed, contact our Support team and request the debug symbols for your devices. Then, copy the debug symbols to your local Mac folder:

/Users/<your username>/Library/Developer/Xcode/iOS DeviceSupport/

Clean up previous virtualUSB version before installing new version

If you have installed virtualUSB previously, we recommend uninstalling the old version before installing a new one.

See Uninstall virtualUSB

Download virtualUSB

In the Kobiton Portal, click the Download button on the left navigation bar, then select virtualUSB for Mac:

 

This will download a file named virtualUSB.dmg to the local machine.

Install and launch virtualUSB

NOTE: virtualUSB cannot coexist on a Mac that has deviceConnect or Kobiton Desktop. They must be on separate machines.

Open the downloaded virtualUSB.dmg file, drag and drop the virtualUSB icon to the Applications folder for easy access:

Go to the Applications folder in Finder, and open virtualUSB:

When prompted if you want to open an app downloaded from the internet, select Open:

If this is the first launch, provide the admin password or Touch ID (if enabled) to install the required daemon. Select Use Password... or scan fingerprint to allow it:

On the first time launching the app, put the check mark on I have read and agreed to the License terms and click Continue:

 

For Cloud customers who log into Kobiton Portal via portal.kobiton.com, sign in using your Kobiton Portal credentials without selecting the check box. You can login using your Kobiton account’s password or API Key:

Additional configurations for Kobiton Cloud customer-hosted environment

For virtualUSB v4.6 and above:

For Cloud customers who log into a custom domain such as portal.<company-name>.com, select the Login to your custom domain portal checkbox in the login screen, then input the values for the 2 additional fields as below, replacing <custom-domain> with the customer's domain name:

• API Base Url: https://api.<custom-domain>.com

• API GRPC Base Url: https://proxy-api-public-grpc-server.<custom-domain>.com

Then input the Username/Email and Password/API Key to log in.

Note: the values for API Base Url and API GRPC Base Url are remembered and prefilled the next time you open the app.

 

For older versions:

Cloud customers that host their own devices must update the configurations file to point virtualUSB to their customer-hosted environment.

Navigate to the folder ~/Library/"Application Support"/virtualUSB, open the config.ini file and take note of the following values:

• Kobiton.ApiBaseUrl: https://api.kobiton.com
• Kobiton.ApiGrpcBaseUrl: https://proxy-api-public-grpc-server.kobiton.com

If your organization use a custom domain, edit the following values by replacing <custom-domain> with the customer's domain name; otherwise keep the default value.

• Kobiton.ApiBaseUrl: https://api.<custom-domain>.com
• Kobiton.ApiGrpcBaseUrl: https://proxy-api-public-grpc-server.<custom-domain>.com

Save the changes (if any)and restart the virtualUSB app to apply the changes.

Additional configurations for Standalone environments

Using virtualUSB with Kobiton Standalone requires configurations on the following machines:

• Mac mini hosts: these are the Mac mini machines where deviceConnect is installed and that host the mobile devices
• End-user workstation: The users' Mac machine where virtualUSB is installed

No configuration is required on the Dell server that hosts the Kobiton Portal, referred to as on-premises server (OP server). However, it is important to note down the following information:

• whether the server uses HTTP or HTTPS protocol
• IP address or domain of the Dell server
• username and password to access the server's files

Configure Mac mini hosts for Kobiton Standalone

On every Mac mini host using Kobiton Standalone, perform the following:

Open /usr/local/deviceconnect/dc.ini and make sure these fields are listed:

GatewayPublicAddress=<Private IP|Outbound IP> 
ExternalAirstreamTlsPort=<10161|Outbound port>

Example:

GatewayPublicAddress=192.168.36.36
ExternalAirstreamTlsPort=10161

Run the following command in terminal to apply the changes:

sudo sv restart dc-services dc-webviewer dc-watchdog

Configure end-user workstation for Kobiton Standalone

HTTPS and self-signed SSL cert

This section is only applicable if the OP server is set up to use HTTPS and the SSL cert is a self-signed cert. Otherwise, skip to the next section.

These steps only need to be performed once on the first time installing virtualUSB.

• Download the self-sign certificate from the standalone server by using the below command (remember to turn on the VPN to the standalone server):
  

scp <server-username>@<server-ip>:/path/to/ssl.crt /path/to/local-dir

• • <server-username> is the username to access the server
  • <server-ip> is the IP address of the server
  • /path/to/ssl.crt is the location of the certificate file on the server, which is /ml/var/kobiton-op/config/ssl.crt by default
    
  • /path/to/local-dir is where to save the certificate file on the end-user workstation

• Enter the password used to access the standalone server. The ssl.crt file will be then downloaded
• Open the Keychain Access application
• Open Finder, go to /path/to/local-dir folder, and then drag and drop the ssl.crt file into the Keychain Access application
• Double-click on the newly added certificate file. In the dialog below, choose the Always Trust option from the dropdown list for the two fields:
  • Secure Sockets Layer (SSL)
  • X.509 Basic Policy
    

• Close the dialog and enter the admin password of the user workstation to save the changes

Custom URL configurations for Standalone

For virtualUSB v4.6 and above:

For Standalone customers, select the Login to your custom domain portal checkbox in the login screen, then input the values for 2 the additional fields as <http/https>://<Portal private domain or IP>:<REST API port>, where:

• <http/https>: if the OP server uses HTTPS, then use https. Else, use http.
• <Portal private domain or IP>: If the OP server has a private domain then use its private domain. Otherwise, use the OP server’s IP address.
• <REST API port>:
  • For API Base Url, check if there is the field rest_api_ingress_advertised_port in the file config/app.yaml in the OP server. If yes, use its value for the <REST API port>; else, use “3000”.
  • For API GRPC Base Url, check if there is the field grpc_ingress_gateway_public_advertised_port in the file config/app.yaml in the OP server. If yes, use its value for the <REST API port>; else, use “3001”.

Below is an example:

• API Base Url: http://129.168.36.24:3000
• API GRPC Base Url: http://129.168.36.24:3001

Then input the Username/Email and Password/API key to log in.

Note: the values for API Base Url and API GRPC Base Url are remembered and prefilled the next time you open the app.

For older versions:

Navigate to the folder ~/Library/Application Support/virtualUSB on the end-user workstation. Open the config.ini file and edit the value of the following parameters:

Kobiton.ApiBaseUrl=<http/https>://<OP server private domain or IP>:<REST API port>
Kobiton.ApiGrpcBaseUrl=<http/https>://<OP server private domain or IP>:<REST API port> 

• <http/https>: if the OP server uses HTTPS, then use https. Else, use http.
• <OP server private domain or IP>: If the OP server has a private domain then use its private domain. Otherwise, use the OP server’s IP address.
• <REST API port>:
  • For Kobiton.ApiBaseUrl, check if there is the field rest_api_ingress_advertised_port in the file config/app.yaml in the OP server. If yes, use its value for the <REST API port>; else, use “3000”.
  • For Kobiton.ApiGrpcBaseUrl, check if there is the field grpc_ingress_gateway_public_advertised_port in the file config/app.yaml in the OP server. If yes, use its value for the <REST API port>; else, use “3001”.

Below is an example:

Kobiton.ApiBaseUrl=https://192.168.36.24:3000
Kobiton.ApiGrpcBaseUrl=https://192.168.36.24:3001

Once done, save the config.ini file and you can launch the virtualUSB application.

4. Uninstall virtualUSB

Go to the Applications folder in Finder and drag the virtualUSB to the trash.

Run the following command to clean up:

sudo dcb uninstall && sudo rm -rf /usr/local/var/dcb /usr/local/bin/dcb ~/.dcbridgerc ~/Library/Application\ Support/virtualUSB

5. Limitations

• virtualUSB does not work on machines with deviceConnect or Kobiton Desktop software already installed.