About virtualUSB

NOTE: virtualUSB is currently in beta. We welcome your feedback at support@kobiton.com

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 your Account Executive if you are interested in adding this feature.

This is the guide to install and configure virtualUSB on Windows machine. See this guide for how to use virtualUSB.

Prerequisites

Hardware requirements

The user's Windows workstation must be on Windows 10 or above.

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 PC, open the terminal and enter the following commands, where C:\path\to\Android\Sdk is the location of SDK installation directory (the folder containing platform-tools):

set ANDROID_HOME=C:\path\to\Android\Sdk
set PATH=%PATH%;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-tools

iOS requirements

To connect iOS devices via virtualUSB, iTunes is required. iTunes must be installed from Apple, not from the Microsoft Store.

Additionally, some users may need additional tooling for their test needs to communicate with iOS devices. One example of an additional tool is libimobiledevice.

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 Windows:

This will download a virtualUSB.msi file to the local machine.

Install and launch virtualUSB

Open the downloaded virtualUSB.msi file. When the virtualUSB Setup Wizard starts, select Next:

Select a location to install virtualUSB. By default, it is C:\Program Files\virtualUSB\. Select Next to continue:

Select Install to begin the installation:

Give the installer permission to make changes to your computer by choosing Yes:

When the installation finishes, select Finish:

Note: these steps below are required only if you intend to use iOS devices with virtualUSB.
Open a terminal with administrator privilege and enter the following commands:

cd C:\Program Files\virtualUSB
vusb setup-ios

If there is an Ok response from the commands above, virtualUSB is ready to connect to iOS devices.

Important notice: starting from Kobiton release 4.6.2, iOS devices support for virtualUSB in Windows is no longer available.

Launch virtualUSB app from the Windows Start menu:

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 their user workstation configurations file to point virtualUSB to their customer-hosted environment.

Navigate to the folder %APPDATA% and open the folder virtualUSB:

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

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 admins to update 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' Windows 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.1.100
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 Esername/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 %APPDATA% and open the virtualUSB folder on the 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.1.101:3000
Kobiton.ApiGrpcBaseUrl=https://192.168.1.101:3001

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

Uninstall virtualUSB

Go to the virtualUSB installation folder, which is C:\Program Files\virtualUSB\ by default. In this folder, open the Uninstall virtualUSB shortcut to uninstall the application.