DeviceAnywhere Enterprise iOS Device Onboarding Guide

DeviceAnywhere Enterprise
iOS Device Onboarding Guide
DeviceAnywhere Enterprise
iOS Device Onboarding Guide
DeviceAnywhere Enterprise 6.2.1
DeviceAnywhere Enterprise Automation 6.2.1
DeviceAnywhere Enterprise Monitoring 6.0
March 2014
Copyright Notice
Copyright © 1995-2014 Keynote Systems, Inc. All rights reserved
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT ANY
EXPRESS REPRESENTATIONS OF WARRANTIES. IN ADDITION, KEYNOTE DISCLAIMS ALL
IMPLIED REPRESENTATIONS AND WARRANTIES, INCLUDING ANY WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT OF
THIRD PARTY INTELLECTURAL PROPERTY RIGHTS.
All text and figures included in this publication are the exclusive property of Keynote and may not be
copied, reproduced, or used in any way without the express permission in writing of Keynote.
Information in this document is subject to change without notice and does not represent a commitment
on the part of Keynote. Keynote may have patents or pending patent applications covering subject matter
in this document. The furnishing of this document does not give you any license to these patents except
as expressly provided in any written license agreement from Keynote.
The trademarks or registered trademarks of Keynote Systems, Inc. in the United States and other
countries include Keynote®, DataPulse®, CustomerScope®, Keynote Customer Experience Rankings®,
Perspective®, Keynote Red Alert®, Keynote WebEffective®, The Internet Performance Authority®,
MyKeynote®, SIGOS®, SITE®, keynote® The Mobile & Internet Performance Authority™, Keynote
FlexUse®, Keynote DeviceAnywhere®, DeviceAnywhere®, Keynote DemoAnywhere®, Keynote
MonitorAnywhere®. All related trademarks, trade names, logos, characters, design and trade dress are
trademarks or registered trademarks of Keynote Systems, Inc. in the United States and other countries
and may not be used without written permission. All other trademarks are the property of their
respective owners.
Please forward any comments or suggestions regarding this document to Keynote Support.
Keynote Systems, Inc.
777 Mariners Island Blvd.
San Mateo, CA 94404
ii
Keynote Confidential
iOS Device Onboarding Guide
DeviceAnywhere Enterprise
Contents
About This Document ...................................................................................................... 5
Document Outline ........................................................................................................................................ 5
Typographical Conventions........................................................................................................................ 5
Contacting Support ...................................................................................................................................... 5
Additional Documentation ......................................................................................................................... 5
1
Prerequisites and Overview ................................................................................. 7
1.1
Hardware ........................................................................................................................................ 7
1.2
Software ........................................................................................................................................... 7
1.2.1
System Requirements for the Ensemble Server ........................................................... 8
1.2.2
System Requirements for Keynote DeviceAnywhere Studio .................................... 8
2
Before Installing the DeviceAnywhere Agent................................................... 9
3
DeviceAnywhere Agent Installation ................................................................ 14
4
Onboarding Your iOS Device ............................................................................ 21
4.1
Adding the iOS Device ................................................................................................................ 21
4.2
Running and Setting Up the DeviceAnywhere Agent ............................................................ 23
4.3
Onboarding (Attaching) the Device to the Server ................................................................... 24
Keynote Confidential
iii
iOS Device Onboarding Guide
DeviceAnywhere Enterprise
About This Document
This document describes how to connect software-integrated or hybrid iOS devices to the Ensemble
Server. Connecting a device to the Ensemble Server by plugging it in to a USB port or via Wi-Fi enables
you to control and interact with it in DeviceAnywhere Studio.
In this document, you will learn how to set up your iOS device for communication via USB cable or Wi-Fi.
In order to control device input and view output in DeviceAnywhere Studio, you must attach, or onboard
the device to your Ensemble Server. The onboarding process is run from DeviceAnywhere Studio.
Document Outline
Prerequisites provides information on hardware and software prerequisites for onboarding your iOS
device to the Ensemble Server.
Before Installing the DeviceAnywhere iPhone Agent contains information on software
installation/configuration requirements in order to install the DeviceAnywhere Agent on your iOS device.
DeviceAnywhere Agent Installation explains the procedure for installing the DeviceAnywhere Agent on
your iPhone.
Onboarding Your iPhone describes how to add a device from DeviceAnywhere Studio, configure the
device agent for a particular connection type, and finish up the onboarding process.
Typographical Conventions
The table below describes the typographical conventions used in DeviceAnywhere documentation.
Style
Element
Example
Blue
Links and email addresses
http://www.keynote.com
The Document Outline section describes the
structure of this manual.
Bold
User interface elements such as menu
items
Click My Devices in DeviceAnywhere Studio.
Monospace
Commands, code output, filenames,
directories
Right-click the project’s test cases
directory.
Monospace bold
User input
In a command window, type adb devices.
Italic
Document titles and emphasis
Refer to the DeviceAnywhere Enterprise Private
System Installation Guide for instructions on
setting up server infrastructure.
Contacting Support
If you have any comments or suggestions regarding this document, contact Keynote Support at
http://support.keynote.com or 1-888-KEY-SYST (539-7978).
Additional Documentation
You can find additional documentation at:
Keynote Confidential
5
DeviceAnywhere Enterprise
iOS Device Onboarding Guide

DeviceAnywhere Enterprise shared system with private devices:
http://www.keynotedeviceanywhere.com/dae-pvt-devices-documentation.html

DAE Automation: http://www.keynotedeviceanywhere.com/testing-automation-documentation.html

DAE Monitoring: http://www.keynotedeviceanywhere.com/monitoring-documentation.html
In addition, you can access documentation from the Help menu in DeviceAnywhere Studio.
6
Keynote Confidential
iOS Device Onboarding Guide
1
DeviceAnywhere Enterprise
Prerequisites and Overview
This section lists the hardware and software prerequisites for connecting software-integrated or hybrid
iPhone devices to the Ensemble Server. This document assumes that you are familiar with interacting
with mobile devices in DeviceAnywhere Studio.
1.1
Hardware
Hardware requirements include:

One USB port per iOS device on the Ensemble Server machine, if connecting to the device via USB
cable

iPhone mobile device(s) (iOS versions 3 to 6.1.3 are supported)
NOTE Upgrading the OS can invalidate settings required for the device to operate in a
DeviceAnywhere Enterprise environment. If you wish to upgrade your OS, please contact
http://support.keynote.com.

Wi-Fi gear (router, access points, etc.) and setup if connecting the device via Wi-Fi (See Before
Installing the DeviceAnywhere iOS Agent for pointers on Wi-Fi configuration.)
1.2
Software
Software requirements are:

A DeviceAnywhere Studio account with the System Admin role, enabling you to access the Device
Manager view
If you require an account, please contact your system administrator.

Ensemble Server pointing to a fully operational DeviceAnywhere Enterprise environment (including
Access Server, SQL Server, and other components)—this can be the DeviceAnywhere Enterprise
cloud service or a dedicated system hosted by us or behind your firewall.
Refer to System Requirements for the Ensemble Server below for minimum installation requirements.
For detailed installation instructions, refer to the DeviceAnywhere Enterprise Private System Installation
Guide.

DeviceAnywhere Studio client software, pointing to a fully operational DeviceAnywhere Enterprise
environment
Refer to System Requirements for DeviceAnywhere Studio below for minimum installation
requirements.

iTunes 10.3 is required to connect to the device—contact Keynote Support for a location from where
you can download this.

Cydia, which enables your iPhone device to browse and download applications

Device profile XML files, provided by Keynote, for the devices you wish to test
Keynote Confidential
7
DeviceAnywhere Enterprise
iOS Device Onboarding Guide

DeviceAnywhere Agent for iPhone, DA Agent, available at http://download.keynote.com/da/iphone.
Please contact Keynote Support before you update device firmware as this might impact the
availability of the Agent for your device.

Appropriate licensing for the DeviceAnywhere Enterprise product modules you wish to use
NOTE Components of a DeviceAnywhere Enterprise environment require a network connection to
communicate with each other.
1.2.1 System Requirements for the Ensemble Server
Minimum system requirements are as follows:

Core i3 processor

3 or 4 GB RAM

At least 10 GB available hard disk space

One USB port per device connected to the Ensemble Server via USB cable

Supported operating systems: Windows XP, Windows 7, Windows Server 2008
NOTES While Ensemble Server is available for Windows 2003, onboarding of software-integrated
devices is not supported.
Ensemble Server is compatible with Windows 7 x64. Only x86 supported on other Windows systems.
You cannot avail of more than 4 GB RAM on x86 machines.
1.2.2 System Requirements for Keynote DeviceAnywhere Studio
Minimum system requirements are as follows:

2 GHz dual‐core processor (Pentium 4 or higher)

2 GB RAM

At least 10 GB available hard disk space

Monitor with at least 1600 x 900 screen resolution

Optional: Audio card for sound input/output

Supported operating systems: Windows XP, Windows Server 2003, Windows 7, Mac OS 10.2 or
higher
NOTES DeviceAnywhere Studio can be installed on Windows machines with 32-bit operating
systems and 64-bit operating systems running in 32-bit compatibility mode.
JDK v1.5+ must be installed for Mac OS.
In order to begin testing on your iPhone, you must:
1
Perform some preliminary software installation and configuration steps.
2
Install the DeviceAnywhere Agent on your iPhone.
3
Onboard the device to the Ensemble Server.
8
Keynote Confidential
iOS Device Onboarding Guide
2
DeviceAnywhere Enterprise
Before Installing the DeviceAnywhere Agent
This chapter explains the software installation/configuration steps that you must perform before
installing the DeviceAnywhere Agent on your iOS device.
As part of your DeviceAnywhere Enterprise environment setup, you must:

Copy the device profile XML file(s) and install iTunes 10.3 and Apple Mobile Device Support 3.2.0.47
(all provided by Keynote).

For iPhone 4S, iPad2 or later devices, add the hardware ID to the .inf file.

In addition, you must prepare for connectivity by USB cable or Wi-Fi.
Perform these steps as described below:
1
Copy the device profile XML file (e.g., iPhone_4.xml) to the smartphoneXMLs directory of your
DeviceAnywhere Studio installation. The default location is:

Windows XP: C:\Documents and Settings\<Windows_user>\Local Settings\
Application Data\DeviceAnywhere\smartphoneXMLs

Windows Vista and later: C:\Users\<Windows_user>\AppData\Local\
DeviceAnywhere\smartphoneXMLs
If you do not have a device profile XML file, please contact your system administrator or Keynote
Support (http://support.keynote.com).
2
Install iTunes 10.3 on the Ensemble Server machine, unchecking the option for automatic updates.
Contact Keynote Support for the correct executable for your 32-bit or 64-bit machine. iTunes is
required for connecting to your iOS device via USB cable.
3
Uninstall Apple Mobile Device Support from your Ensemble Server machine; reinstall Apple Mobile
Device Support version 3.2.0.47.
Keynote Confidential
9
DeviceAnywhere Enterprise
4
a
From your Control Panel, select Add or Remove Programs.
b
Select Apple Mobile Device Support and click Remove.
c
Install Apple Mobile Device Support 3.2.0.47 for your 32-bit or 64-bit machine—contact Keynote
Support for the correct executable.
If you are connecting an iPhone 4S, iPad 2, or newer device, you must add the device hardware ID to
the .inf file, which provides information on installing device drivers.
a
Connect your device by USB cable to the Ensemble Server machine.
b
Locate your Apple device in the Windows Device Manager:

10
iOS Device Onboarding Guide
Windows XP: Start > right-click My Computer > Manage > Device Manager. Select your
device (e.g., Apple iPhone from Imaging devices).
Keynote Confidential
iOS Device Onboarding Guide

DeviceAnywhere Enterprise
Windows 7: Start > Devices and Printers. Select your device (e.g., Apple iPhone from
Unspecified).
c
Double-click to open device properties.
d
View the hardware ID.

Windows XP: Select the Details tab > select Hardware Ids from the drop-down list.

Windows 7: Hardware tab > Properties > Details tab > select Hardware Ids from the dropdown list.
Keynote Confidential
11
DeviceAnywhere Enterprise
iOS Device Onboarding Guide
e
Select any of the strings displayed and press Ctrl+C to copy it. (You will need to enter a portion of
the string in the .inf file.
f
Navigate to C:\Program Files\Common Files\Apple\Mobile Device Support\
Drivers.
g
Open the .inf file in a text editor—usbaapl64.inf on 64-bit and usbaapl.inf on 32-bit
systems.
h
Insert a line of the following format in the iphone section.

32-bit systems:
%iPhone.DeviceDesc%=USBAAPL.Dev, <Hardware_ID>

64-bit systems:
%iPhone.DeviceDesc%=USBAAPL64.Dev, <Hardware_ID>
where <Hardware_ID> includes only characters before the second ampersand (&) in the string
copied from device properties. For example, if you copied the string
USB\VID_05AC&PID_12A0&MI_00, you must paste USB\VID_05AC&PID_12A0.
i
12
Save and close the .inf file.
Keynote Confidential
iOS Device Onboarding Guide
5
DeviceAnywhere Enterprise
Prepare for connectivity by USB cable or Wi-Fi:

If connecting by USB cable, connect your iPhone by USB cable to the Ensemble Server.

If connecting by Wi-Fi:
i
Ensure that the Ensemble Server has a fixed IP address on the internal network.
ii
Ensure that the Ensemble Server does not sit behind the Wi-Fi router.
iii Ensure that Wi-Fi is enabled on your device (Settings > Wi-Fi > On), and connect to an
available wireless network.
Next, proceed with installing the iOS Agent on your device.
Keynote Confidential
13
DeviceAnywhere Enterprise
3
iOS Device Onboarding Guide
DeviceAnywhere Agent Installation
The DeviceAnywhere Agent enables you to access and control your iOS device remotely. This section
describes the simple procedures for installing or upgrading the iOS Agent on an iOS device.
To install the iOS Agent on your device:
1
Open Cydia and ensure that the BTstack package is installed:
a
In Cydia, choose Manage > Packages.
b
Packages are listed alphabetically. Check for the BTstack package.
c
If BTstack is not installed, install it from BigBoss:
i
14
Navigate to Manage > Sources > BigBoss.
Keynote Confidential
iOS Device Onboarding Guide
ii
d
DeviceAnywhere Enterprise
Select and install BTstack.
If BTstack is not available, you must delete and reinstall BigBoss, and then install BTstack:
i
Navigate to Sources > Edit.
ii
Click the red icon
next to BigBoss.
iii Click Delete.
iv Select Cydia and scroll to find and select More Package Sources.
Keynote Confidential
15
DeviceAnywhere Enterprise
v
iOS Device Onboarding Guide
Select BigBoss and install it.
vi Navigate to Manage > Sources > BigBoss.
vii Select and install BTstack.
2
16
Add Keynote as an application source and download the DeviceAnywhere Agent:
a
In Cydia, choose Manage > Sources > Edit > Add.
b
Enter http://download.keynote.com/da/iphone in the field provided and click Add Source.
c
Wait for the sources to be updated and then click Return to Cydia.
d
This returns you to the list of sources. Click Done.
Keynote Confidential
iOS Device Onboarding Guide
e
DeviceAnywhere Enterprise
From the list of sources, select the Keynote source you just added.
Available iOS DeviceAnywhere Agents are displayed.
f
Select the most recent DA Agent version, DA Agent 3.6 and click Install.
Keynote Confidential
17
DeviceAnywhere Enterprise
3
g
Click Confirm.
h
You will see errors in red indicating that BTstack could not be overwritten. This behavior is expected.
Click Restart SpringBoard to restart your device.
i
When you have restarted the device, navigate to the home page with the Cydia app. You will
notice that two packages are installed. A third package, DA Agent, is not installed.
To complete the installation, delete BigBoss, delete BTstack, and install the missing DA Agent
package:
a
18
iOS Device Onboarding Guide
Delete BigBoss:
i
In Cydia, navigate to Manage > Sources > Edit.
ii
Click the red icon next to BigBoss.
Keynote Confidential
iOS Device Onboarding Guide
DeviceAnywhere Enterprise
iii Click Delete.
b
c
Delete the BTstack package:
i
Navigate to Manage > Packages.
ii
Select the BTstack package and click Remove.
Add the Keynote source required to download the missing DA Agent package:
i
Navigate to Manage > Sources > Edit > Add.
ii
Enter http://download.keynote.com/da/others in the field provided and click Add Source.
iii Wait for the sources to be updated and then click Return to Cydia.
iv This returns you to the list of sources. Click Done.
v
From the list of sources, select the Keynote source you just added.
Keynote Confidential
19
DeviceAnywhere Enterprise
iOS Device Onboarding Guide
vi Select DA Agent 3.6 and install it.
vii Click Restart SpringBoard once installation is complete.
viii Navigate to the home page with the Cydia app. You should see three packages installed as
part of the DeviceAnywhere Agent.
ix Place the DA Agent app and the two other components into a folder so that automated
scripts have no chance of accidentally deleting it.
You can now onboard the device to the Ensemble Server.
20
Keynote Confidential
iOS Device Onboarding Guide
4
DeviceAnywhere Enterprise
Onboarding Your iOS Device
Once you have met all prerequisites you can onboard your device to the Ensemble Server. To onboard the
device, you must:
1
Add your device from DeviceAnywhere Studio.
2
Set up the iOS Agent to connect via USB cable or Wi-Fi.
3
Attach your device to the Ensemble Server to complete the onboarding process.
It is best to complete the onboarding process one device at a time to facilitate any troubleshooting steps.
4.1 Adding the iOS Device
1
Select the Device Manager view in the left sidebar of DeviceAnywhere Studio and click Add device.
The Add device window lists all device profile XML files that can be found in your DeviceAnywhere
Studio installation. If you do not see your XML file in this list, check to make sure that you have
copied it to the smartphoneXMLs directory:
2

Windows XP: C:\Documents and Settings\<Windows_user>\Local Settings\
Application Data\DeviceAnywhere\smartphoneXMLs

Windows Vista and later: C:\Users\<Windows_user>\AppData\Local\
DeviceAnywhere\smartphoneXMLs
From the left pane, select the device you wish to add and click Next.
Keynote Confidential
21
DeviceAnywhere Enterprise
iOS Device Onboarding Guide
3
Enter a name of your choice for the device, e.g., iPhone 4, and click Next.
4
DeviceAnywhere Studio confirms that the device has been added. Click Finish. Your device is now
listed as offline in the Device Manager view.
NOTE If you uncheck Onboard device now, you can resume the onboarding process later by rightclicking your device in the Device Manager view and selecting Onboard Device.
To continue with the onboarding process, you must run and set up the DeviceAnywhere Agent on your
device.
22
Keynote Confidential
iOS Device Onboarding Guide
DeviceAnywhere Enterprise
4.2 Running and Setting Up the DeviceAnywhere Agent
On your iOS device, you must start up the DeviceAnywhere Agent and set it up for connecting to the
Ensemble Server using USB cable or Wi-Fi.
NOTES If your device is already onboard and you want to change connection type, skip to step 2 below.
Even if your iOS devices are communicating with the Ensemble Server over Wi-Fi or Bluetooth, you
might want to leave them connected by USB cable in order to charge their batteries. iPad devices that are
powered on maintain their power but do not charge over USB; you must connect them to a power outlet
in order to charge their batteries.
1
Open the DA Agent app. You will see the Setup screen.
2
Choose a connection type and connection parameters.
To connect via USB cable:
a
Select USB Cable from the Setup screen.
To connect via Wi-Fi:
a
Select Wi-Fi from the Setup screen and click the arrow next to it.
Keynote Confidential
23
DeviceAnywhere Enterprise
3
iOS Device Onboarding Guide
b
In the Ensemble Hostname/IP field, enter the hostname or IP address of the Ensemble Server you
wish to onboard the device to.
c
Leave the default Port (7890) for connecting to the Ensemble Server as is. This should match the
default port on the Ensemble Server.
Click Setup > Reboot to restart the device.
4.3 Onboarding (Attaching) the Device to the Server
Continue to the onboarding procedure in DeviceAnywhere Studio:
1
If you need to, initiate the onboarding wizard by right-clicking your device in the Device Manager
view and selecting Onboard Device.
2
Select the IP address or hostname of the Ensemble Server you are onboarding the device to.
24
Keynote Confidential
iOS Device Onboarding Guide
3
DeviceAnywhere Enterprise
Select a connection method. This must match the connection method selected in the iOS Agent.
NOTE Connecting to the Ensemble Server via USB Cable or Wi-Fi should satisfy most testing needs.
4
Ensure that your device is ready to connect to the server and click Next.
Keynote Confidential
25
DeviceAnywhere Enterprise
5
iOS Device Onboarding Guide
Select the UDID number for your device and click Next. (The list only displays iOS devices that have
not been onboarded yet.)
If there are several UDID numbers in the list and you are unsure of which one to pick, disconnect all
other iOS devices from the Ensemble Server. Your device serial number should now be the only one
listed.
If you are unable to unplug other devices, locate the device’s UDID number in iTunes to identify it:
26
a
Select your device in iTunes. The serial number is displayed.
b
Click the serial number. The device UDID is displayed.
Keynote Confidential
iOS Device Onboarding Guide
6
DeviceAnywhere Enterprise
Click Finish to complete the onboarding procedure.
Your device appears in the Device Manager view of DeviceAnywhere Studio with green device control
status icons.
The device is also listed in the On Board Devices package in the Test Center view.
Keynote Confidential
27