Page tree
Skip to end of metadata
Go to start of metadata

Last updated: Dec 17, 2018 12:48

Prerequisites

Before installing and using the DevTunnel feature on your development station, verify the following system requirements:

  • DevTunnel Installation package requires Administration privilege on the development station.
  • Java JDK of version 1.7 or later is installed on the development station.
  • For Windows workstation - .NET Framework v4.6 or later.

    Note: If .NET framework not pre-installed, it will be installed as part of DevTunnel installation package.


  • Networking configuration:
    • Local network employs a transparent proxy to connect to the Perfecto Lab - verify all CQ Lab sites included in the white-list of the proxy.
    • Local network employs a explicit proxy with credential authentication proxy to connect to the Perfecto Lab - follow the procedure in the Proxy Configuration page.
    • Local network employs web inspection - verify all CQ Lab sites included in the white-list of the proxy.

Installation Package

Perfecto provides an installation package that installs the different software elements onto your computer. These elements allow you to:

  • Establish a secure connection between your development computer and the Perfecto Lab Handset Server.
  • Make the Android debugging tools identify the Perfecto device as connected to the development station.

Download the Installer Package

  • Open a Perfecto Lab device either within the IDE (Eclipse or Android Studio) plugin or in a Perfecto Interactive interface window.

  • Go to the Perfecto widgets, and click the DevTunnel widget (blue box in following pictures).


  • A popup notification is displayed that includes a download link for the DevTunnel Installer package (see blue box in following picture). Click the link and follow the dialogue boxes to save the file on your local development station. Click the Cancel Session button.


  • The download tool will identify the target development station's operating system (Windows or Mac) and download the proper installation package.

  • Alternatively, download the correct installer package from the Perfecto Lab More menu (upper right corner). Select the Download DevTunnel option.

  • You can also directly download the installation package from Perfecto Lab:

    • For installation on Windows based development stations download the https://[your Lab]/nexperience/devtunnel/PerfectoInstaller.exe file.
    • For installation on MacOS based development stations download the https://[your Lab]/nexperience/devtunnel/PerfectoInstaller.pkg file.

Install on Development Station

Important: Add PerfectoInstaller.exe to the anti-virus exception list on your workstation if you use any of the following anti-virus software tools:

  • Avira
  • Baid
  • Endgame
  • Invincea
  • Qihoo-360

The virus-detection of these tools may falsely identify a virus associated with the installer package.

Windows station

Activate the installation package and, if prompted, confirm the permission to install the software.

  • Agree to the Perfecto License. This provides the terms of using this software.
  • Select a folder where the Perfecto software will be installed on the development computer. By default the software is installed at C:\Program Files(x86)\perfecto but you can change this location by clicking the Browse button.
  • Click Install to begin the installation.
  • The installation process displays a progress bar. 
  • Click on Close on the Perfecto Installer Completed window to complete the entire installation.

Mac development station

Activate the installation package.

  • In the Install Perfecto DevTunnel Welcome window. click Continue.
  • Read the license agreement, and click Continue. Agree to the Perfecto License.
  • Click Continue in the Destination Select window to install the software packages on the computer's default installation device (Macintosh Hard Drive).
  • Click Install on the Installation Type window to install the software at the default file locations. Do not change the installation location.
  • System may ask you to confirm the installation, by supplying your login password.
  • The installation process displays a progress bar.
  • As part of the installation process, several packages are installed - (see below)
  • Just prior to completing the installation, you may be prompted to restart some applications:

  • Select to either Restart the apps (click Restart Apps) at this point, or later (click Skip). For more information see below.
  • Click Close in the Summary window to complete the entire installation.

Mac Restart Applications

As part of the DevTunnel installation, Perfecto supplies a Relay service that affects how different applications identify the devices connected to the Mac workstation. This affects any applications, for example Xcode, that may need to access a connected device.

During the installation process, DevTunnel checks whether any of the affected applications are active, and requests that they be restarted before using them with the connected devices.

Things to know about Restart Applications:

  • If you intend to use your IDE or Safari Web Inspector with a device connected through DevTunnel, you should elect to restart the apps.
    • In any case, the application must be restarted before using a DevTunnel connected device.
  • If you do not intend on using any of the listed applications with DevTunnel devices, you can Skip the automatic restart.
  • If you are installing DevTunnel from a Safari session, and you elect to restart Safari, as a result of the prompt, your Perfecto Lab session will be closed and you will need to reconnect and reopen the device.
    • When connecting to DevTunnel, you do not need to reinstall the service.
  • The list of applications to restart may include applications that are running background services.

Installed Packages

The following is the list of Third-party packages that are installed as part of the DevTunnel installation:

Mac

  1. STunnel (www.stunnel.org) – To establish a secure tunnel from a local port to a remote DevTunnel server on port 443.
    Location: /usr/local/etc/stunnel
  2. Perfecto Binaries:
    1. PerfectoDevTunnel.jar – Client that starts up when a session is started. Responsible for DevTunnel initialization.
    2. DevTunnelHelper.app – macOS application used to bridge between browser and PerfectoDevTunnel.jar.
    3. PerfectoADBHelper.jar – Detects client ADB version for compatibility improvements.
    4. Perfecto_iOS – Used to initiate iOS DevTunnel sessions.
    5. Perfecto_Android.sh – Used to initiate Android DevTunnel session.
    6. DevTunnelRelay.jar - DevTunnel service that directs traffic to proper connected device.

Windows

  1. STunnel (www.stunnel.org) – To establish a secure tunnel from a local port to a remote DevTunnel server on port 443.
    Location: DevTunnel installation folder (Default: C:\Program files (x86)\DevTunnel\stunnel)
  2. Plink (www.chiark.greenend.org.uk/~sgtatham/putty) – To establish a secure channel over the STunnel layer.
    Location: C:\Program Files (x86)\DevTunnel (default)
  3. Subinacl (https://www.microsoft.com/en-us/download/details.aspx?id=23510)- Microsoft binary used by the installer to lower the DevTunnel windows service permissions.
  4. Perfecto Binaries:
    1. DevTunnel Windows Service - .NET binary – DevTunnel client that starts up when a session is started. Responsible for DevTunnel initialization.
    2. DevTunnelHelper - .NET binary used to bridge between browser and DevTunnel Windows Service.
    3. External Dlls:
      1. INIFileParser.dll (https://github.com/rickyah/ini-parser) - Used to parse STunnel INI file
      2. Renci.SshNet.dll (http://sshnet.codeplex.com/) - Used for the connectivity test

Uninstalling DevTunnel

Mac

Use the supplied uninstall.sh shell script in sudo mode to uninstall the DevTunnel service. The shell script is installed (by default) in the /usr/local/etc/stunnel folder.

Using uninstall shell script
sudo /usr/local/etc/stunnel/uninstall.sh

Windows


Use the Uninstall DevTunnel application - in the Start Menu under Perfecto - to uninstall the DevTunnel service:

After activating you will be prompted to allow the uninstall:

Click OK - progress bar is displayed - when completed, click Close.

Known Limitations

See here for the current list of limitations