Test Center Enterprise ios Device Onboarding Guide
Copyright Copyright 2012 Keynote DeviceAnywhere. All Rights Reserved. March 2012. Notice 2012 Keynote DeviceAnywhere. All rights reserved. THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED AS IS WITHOUT ANY EXPRESS REPRESENTATIONS OF WARRANTIES. IN ADDITION, KEYNOTE DEVICEANYWHERE, 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. Test Center Enterprise Automation 5.2 Test Center Enterprise Monitoring 5.2 All text and figures included in this publication are the exclusive property of Keynote DeviceAnywhere, and may not be copied, reproduced, or used in any way without the express permission in writing of Keynote DeviceAnywhere. Information in this document is subject to change without notice and does not represent a commitment on the part of Keynote DeviceAnywhere. Keynote DeviceAnywhere 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 DeviceAnywhere. Mobile Complete, the Keynote DeviceAnywhere logo, DeviceAnywhere, Direct-to-Device, DeviceAnywhere Studio, Test Center Developer, Test Center Enterprise, Test Center Enterprise Interactive, Test Center Enterprise Automation, Test Center Enterprise Monitoring, DemoAnywhere, and DeviceAnywhere Portal are trademarks of Keynote DeviceAnywhere in the United States and/or other countries. This document also contains registered trademarks, and trademarks and service marks that are owned by their respective owners. Keynote DeviceAnywhere disclaims any responsibility for specifying marks that are owned by their respective companies or organizations. If you have any comments or suggestions regarding this document, please send them by e-mail to kda-esupport@keynote.com. Keynote DeviceAnywhere 777 Mariners Island Blvd. San Mateo, CA 94404 ii Copyright 2012 Keynote DeviceAnywhere. All Rights Reserved. Keynote DeviceAnywhere Confidential
Contents About This Document... 5 Document Outline... 5 Typographical Conventions... 5 Contacting Support... 6 Additional Documentation... 6 1 Prerequisites... 7 1.1 Hardware... 7 1.2 Software... 7 1.2.1 System Requirements for the Keynote DeviceAnywhere Ensemble Server... 8 1.2.2 System Requirements for Keynote DeviceAnywhere Studio... 8 2 Before Installing the ios Agent... 10 3 Keynote DeviceAnywhere ios Agent Installation... 15 4 Onboarding Your ios Device... 21 4.1 Adding Your ios Device... 21 4.2 Running and Setting Up the ios Agent... 23 4.3 Onboarding (Attaching) the Device to the Server... 26 Appendix: Preparing for Bluetooth Connectivity... 30 Copyright 2012 Keynote DeviceAnywhere. All Rights Reserved. Keynote DeviceAnywhere Confidential iii
About This Document This document describes how to connect software-integrated or hybrid ios devices to the Keynote DeviceAnywhere Ensemble Server. These devices use Keynote DeviceAnywhere s Direct to Device Software and Software Plus device interaction technologies respectively, enabling you to control and interact with mobile devices by simply plugging them into the USB port of your Ensemble Server. You can also communicate with mobile devices wirelessly using Wi-Fi. 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 device output in the Keynote DeviceAnywhere Studio client application, you must attach, or onboard, the device to your Ensemble Server. The onboarding process is run from Studio. IMPORTANT The Keynote DeviceAnywhere Agent (application) for ios includes the capability for connecting your device to the Ensemble server using Bluetooth, and this document covers instructions for Bluetooth connectivity. However, this functionality is best applied to specific use cases contact your Keynote DeviceAnywhere Technical Account Manager (TAM) at kda-esupport@keynote.com for information. If your testing does not require Bluetooth connectivity, we recommend you use USB cable or Wi-Fi instead. Document Outline In this document: 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 Keynote DeviceAnywhere Agent on your ios device. DeviceAnywhere iphone Agent Installation explains the simple procedure for installing/upgrading the Keynote DeviceAnywhere Agent on your iphone. Onboarding Your iphone describes how to add a device from Studio, configure the Agent on the device for a particular connection type, and finish up the onboarding process in Studio. The appendix Preparing for Bluetooth Connectivity contains information on setting up Bluetooth connectivity between your iphone and the Ensemble Server. Read this chapter if connecting to the device via Bluetooth. Typographical Conventions The table below describes the typographical conventions used in Keynote DeviceAnywhere documentation. Style Element Examples Blue Links and email addresses http://www.keynotedeviceanywhere.com The Document Outline section describes the structure of this manual. Keynote DeviceAnywhere Confidential 5
Style Element Examples Bold User interface elements such as menu items Click My Devices in the Test Center view of DeviceAnywhere Studio. Monospace Commands, code output, filenames, directories Right-click the project s step groups directory. Monospace bold User input In a command window, type adb killserver. Italic Document titles and emphasis Refer to the Keynote DeviceAnywhere Private System Installation Guide for instructions on setting up server infrastructure. Contacting Support If you have any comments or suggestions regarding this document, contact the Keynote DeviceAnywhere support organization for enterprise customers at kda-esupport@keynote.com. You may also send your inquiries about Keynote DeviceAnywhere product demonstrations and professional services to this address. Customers can find additional support information at http://www.keynotedeviceanywhere.com/enterprise-support.html. Additional Documentation Test Center Enterprise Automation users can find additional information in the following documents (available at http://www.keynotedeviceanywhere.com/enterprise-documentation.html. TCE Interactive User Guide TCE Automation User Guide TCE Private System Installation Guide Tips for Interacting with Devices in Keynote DeviceAnywhere TCE Automation Release Notes Test Center Enterprise Monitoring users can find additional documentation at http://www.keynotedeviceanywhere.com/monitoringdocumentation.html. In addition, you can access documentation from the Help menu in the Studio. 6 Keynote DeviceAnywhere Confidential
1 Prerequisites This section lists the hardware and software prerequisites for connecting software-integrated or hybrid iphone devices (devices that use Keynote DeviceAnywhere s Direct-to-Device Software and Software Plus technologies). This document assumes that you are familiar with interacting with mobile devices in the Keynote DeviceAnywhere Studio client application. 1.1 Hardware Hardware requirements include: One USB port per mobile device on the computer hosting the Keynote DeviceAnywhere Ensemble Server, if connecting to the device via USB cable iphone mobile device(s) (ios versions 3 to 5.0 are supported) NOTE Upgrading the OS can invalidate settings required for the device to operate in a Keynote DeviceAnywhere test environment. If you wish to upgrade your OS, please submit a ticket at kdaesupport@keynote.com to have it performed by Keynote DeviceAnywhere. 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.) Bluetooth dongle(s), if connecting to the device via Bluetooth One USB port per Bluetooth dongle if connecting to devices via Bluetooth (see also System Requirements for the DeviceAnywhere Ensemble Server below) 1.2 Software Software requirements are: A Keynote DeviceAnywhere account with the System Admin role, enabling you to access the Device Manager view in Studio If you require an account, please contact your system administrator. Keynote DeviceAnywhere Ensemble Server (Team or Individual), pointing to a fully operational Keynote DeviceAnywhere test environment (including Access Server, SQL Server, and other components) this can be the Keynote DeviceAnywhere cloud service or a dedicated system hosted by us or behind your firewall. Contact your Keynote DeviceAnywhere TAM at kda-esupport@keynote.com for information on connecting to the cloud-based service. Refer to System Requirements for the Keynote DeviceAnywhere Ensemble Server below for minimum installation requirements. For detailed installation instructions, refer to the Test Center Enterprise Private System Installation Guide. NOTES The Individual Ensemble Server license supports only one server, one client, and two concurrently attached devices. Both server and client are installed on the same machine. Remote access to devices requires Team Ensemble Server. Keynote DeviceAnywhere Confidential 7
Keynote DeviceAnywhere Studio client software, pointing to a fully operational Keynote DeviceAnywhere test environment Refer to System Requirements for Keynote DeviceAnywhere Studio below for minimum installation requirements. NOTE Individual Ensemble Server and Studio software may be installed on the same machine. itunes 10.3 is required to connect to the device your Keynote DeviceAnywhere TAM will provide a location from where you can download this. Cydia, which enables your iphone device to browse and download applications Device profile XML files, procured from Keynote DeviceAnywhere, for the mobile devices you wish to test Keynote DeviceAnywhere Agent for iphone, DA Agent, available at http://agents.deviceanywhere.com/iphone/. Your Keynote DeviceAnywhere TAM will provide the exact version of the Agent you must download. Please contact your TAM before you update device firmware as this might impact the availability of the Agent for your device. Appropriate licensing for the Keynote DeviceAnywhere product modules you wish to use NOTE Components of a Keynote DeviceAnywhere test environment require a network connection to communicate with each other. 1.2.1 System Requirements for the Keynote DeviceAnywhere Ensemble Server Minimum system requirements are as follows: 2 GHz dual core processor (Pentium 4) 2 GB RAM At least 10 GB available hard disk space One USB port per device connected to the Ensemble Server via USB cable One USB port per Bluetooth dongle if connecting to devices via Bluetooth Supported operating systems (32 bit): Windows XP SP2, Windows Vista, Windows 7, Windows Server 2008 NOTES While Ensemble Server is available for Windows 2003, onboarding software-integrated devices is not supported. The Ensemble Server is compatible with the 64 bit version of Windows 7. 1.2.2 System Requirements for Keynote DeviceAnywhere Studio Minimum system requirements are as follows: 2 GHz dual core processor (Pentium 4) 2 GB RAM At least 10 GB available hard disk space Monitor with at least 1024x768 screen resolution 8 Keynote DeviceAnywhere Confidential
Optional: Audio card for sound input/output Supported operating systems (32 and 64 bit): Windows XP SP2, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008, Mac OS NOTES You must install JDK v1.5 or later for Mac. Both 32- and 64-bit processing is supported on Windows. 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 DeviceAnywhere Ensemble Server. Keynote DeviceAnywhere Confidential 9
2 Before Installing the ios Agent This chapter explains the software installation/configuration steps that you must perform before installing the Keynote DeviceAnywhere Agent on your ios device. As part of your Keynote DeviceAnywhere test 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 DeviceAnywhere). 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, Wi-Fi, or Bluetooth. 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\<user>\Local Settings\ Application Data\DeviceAnywhere\smartphoneXMLs Windows Vista and later: C:\Users\<user>\AppData\Local\DeviceAnywhere\ smartphonexmls NOTE Users with older installations of DeviceAnywhere Studio might see this folder located at C:\Program Files\DeviceAnywhere\DeviceAnywhereStudio\smartphoneXMLs. If you do not have a device profile XML file, please contact your system administrator or Keynote DeviceAnywhere TAM (kda-esupport@keynote.com). 2 Install itunes 10.3 on the Keynote DeviceAnywhere Ensemble Server machine, unchecking the option for automatically updates. Contact your Keynote DeviceAnywhere TAM for the correct executable for your 32-bit or 64-bit machine. itunes is required for connecting to your iphone via USB cable. 10 Keynote DeviceAnywhere Confidential
3 Uninstall Apple Mobile Device Support from your Windows Ensemble Server machine; reinstall Apple Mobile Device Support version 3.2.0.47. a b From your Control Panel, select Add or Remove Programs. 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 your Keynote DeviceAnywhere TAM for the correct executable. 4 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 b Connect your device by USB cable to the Ensemble Server machine. Locate your Apple device in the Windows Device Manager: Windows XP: Start > right-click My Computer > Manage > Device Manager. Select your device (e.g., Apple iphone from Imaging devices). Keynote DeviceAnywhere Confidential 11
Windows 7: Start > Devices and Printers. Select your device (e.g., Apple iphone from Unspecified). c d Double-click, or right-click > Properties to open device properties. 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. 12 Keynote DeviceAnywhere Confidential
e f g h 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. Navigate to C:\Program Files\Common Files\Apple\Mobile Device Support\ Drivers. Open the.inf file in a text editor usbaapl64.inf on 64-bit and usbaapl.inf on 32-bit systems. 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 Save and close the.inf file. Keynote DeviceAnywhere Confidential 13
5 Prepare for connectivity by USB cable, Wi-Fi, or Bluetooth: If connecting by USB cable, connect your iphone by USB cable to the Ensemble Server. If connecting by Wi-Fi: i ii Ensure that the Ensemble Server has a fixed IP address on the internal network. 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. If connecting by Bluetooth, see the appendix Preparing for Bluetooth Connectivity. Next, proceed with installing the ios Agent on your device. 14 Keynote DeviceAnywhere Confidential
3 Keynote DeviceAnywhere ios Agent Installation The Keynote DeviceAnywhere ios Agent enables you to access and control the 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 add Keynote DeviceAnywhere as an application source: a b In Cydia, choose Manage > Sources > Edit > Add. Enter http://agents.deviceanywhere.com/iphone/ in the field provided. c Choose the Keynote DeviceAnywhere source you just created in Cydia and click Done. Keynote DeviceAnywhere Confidential 15
2 Select the Keynote DeviceAnywhere source. Available ios Agents are displayed. 3 Select the DA Agent application your DeviceAnywhere TAM will tell you the exact version of the agent you must download. 4 Click Install (top right) to install the ios Agent on your device. NOTE If you experience issues with installing the ios Agent, add http://agents.deviceanywhere.com/others as a source in Cydia. 5 Click Restart SpringBoard to restart your device. 16 Keynote DeviceAnywhere Confidential
6 When the installation is complete, the ios Agent (DA Agent) is listed on your ios device home screen. You can now onboard the device to the Ensemble Server. To upgrade the ios Agent: 1 Open Cydia. 2 Navigate to Manage > Sources and select the Keynote DeviceAnywhere source (http://agents.deviceanywhere.com/iphone). A green check mark indicates that an earlier version of the ios Agent has been installed on your device. Keynote DeviceAnywhere Confidential 17
Alternatively, navigate to Packages. Even if you have an earlier version of the ios Agent, the screen displays the latest available version number. A green check mark indicates that an earlier version has already been installed on your device. 3 Select the ios Agent (DA Agent) your DeviceAnywhere TAM will tell you which version you must upgrade to. 4 Select Modify. 18 Keynote DeviceAnywhere Confidential
5 Select Upgrade. 6 Confirm your selection. Keynote DeviceAnywhere Confidential 19
7 When the installation is complete, click Restart SpringBoard to restart your device. 20 Keynote DeviceAnywhere Confidential
4 Onboarding Your ios Device Once you have met all prerequisites (including preparing for Bluetooth connectivity, if necessary), you can onboard your device to the Keynote DeviceAnywhere Ensemble Server. To onboard the device, you must: 1 Add your device from Keynote DeviceAnywhere Studio. 2 Set up the ios Agent to connect via USB cable, Wi-Fi, or Bluetooth. 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 Your ios Device 1 From Studio, navigate to the Device Manager view in the left sidebar and click Add device. The Add device window lists all device profile XML files that can be found in your Studio installation. If you do not see your device XML file in this list, check to make sure that you have copied it to the smartphonexmls directory of your Studio installation: Windows XP: C:\Documents and Settings\<user>\Local Settings\ Application Data\DeviceAnywhere\smartphoneXMLs Windows Vista and later: C:\Users\<user>\AppData\Local\DeviceAnywhere\ smartphonexmls NOTE Users with older installations of Studio might see this folder located at C:\Program Files\DeviceAnywhere\DeviceAnywhereStudio\smartphoneXMLs. 2 From the left pane, select the device you wish to add and click Next. Keynote DeviceAnywhere Confidential 21
3 Enter a name of your choice for the device, e.g., iphone 4, and click Next. 4 Studio confirms that the device has been successfully added. Click Finish. Your device is now listed as offline in the Device Manager view of Studio. 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 ios Agent on your device. 22 Keynote DeviceAnywhere Confidential
4.2 Running and Setting Up the ios Agent On your ios device, you must start up the Keynote DeviceAnywhere ios Agent and set it up for connecting to the Ensemble Server using USB cable, Wi-Fi, or Bluetooth. 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 Select DA Agent to start the ios Agent on your device. The ios Agent displays the Setup screen. 2 Choose a connection type and specify any 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 DeviceAnywhere Confidential 23
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. To connect via Bluetooth: NOTE Although Bluetooth connectivity to the Ensemble Server is supported, this functionality is best applied to specific use cases contact your Keynote DeviceAnywhere TAM for information. If your testing does not require Bluetooth connectivity, we recommend you use USB cable or Wi-Fi instead. a Select Bluetooth from the Setup screen and click the arrow next to it. 24 Keynote DeviceAnywhere Confidential
b In the Bluetooth MAC Address field, enter the MAC address of the Bluetooth adapter on the Ensemble Server (see Preparing for Bluetooth Connectivity). (The Bluetooth pairing code is set to 0000 by default.) 2 Click Setup > Reboot to restart the device. 3 If connecting by Bluetooth, you must pair the device with the Ensemble Server. You must be able to view and access the Ensemble Server to perform this step. a You will see a notification near the Windows Taskbar on your Ensemble Server that a Bluetooth device is attempting to connect. Click to enable the connection. NOTE The Bluetooth notification only appears for a short period of time after your ios device has been reset. If you miss this prompt, power cycle your device to view the prompt again. b Enter 0000 in the dialog box that appears. This is the default pairing code configured in the ios Agent (see above). Click Next. Keynote DeviceAnywhere Confidential 25
You will see a message that the device has been successfully paired to the Ensemble Server. 4.3 Onboarding (Attaching) the Device to the Server Continue to the onboarding procedure in 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. 26 Keynote DeviceAnywhere Confidential
3 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 DeviceAnywhere Confidential 27
5 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: a b Select your device in itunes. The serial number is displayed. Click the serial number. The device UDID is displayed. 28 Keynote DeviceAnywhere Confidential
6 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 DeviceAnywhere Confidential 29
Appendix: Preparing for Bluetooth Connectivity You can connect ios devices to the Keynote DeviceAnywhere Ensemble Server via Bluetooth. You must prepare for Bluetooth connectivity by inserting a Bluetooth dongle into a USB port on the Ensemble Server, procuring the MAC address of the Bluetooth adapter, and disabling Bluetooth on the device (it will automatically be enabled by the ios Agent). NOTE Keynote DeviceAnywhere supports a maximum two devices connected per dongle. To set up Bluetooth connectivity: 1 Insert a Bluetooth dongle into a USB port on the Ensemble Server. Windows should automatically install a device driver; alternatively, use the software that came with the dongle to install a driver. 2 Make a note of the MAC address of the Bluetooth adapter you will require this when configuring the ios Agent to connect to the Ensemble Server: a Right-click the Bluetooth icon in the notification area of the Windows Taskbar to open up a context menu. Select Open Settings > Hardware > Generic Bluetooth Radio > Properties. You can also access this menu from the Windows Device Manager: Right-click My Computer > Manage > Device Manager > Bluetooth Radios > Generic Bluetooth Radio > Properties. b From the Advanced tab, note the MAC address of the Bluetooth adapter (highlighted in the image below). 3 Ensure that Bluetooth is disabled on your ios device it will automatically be enabled by the ios Agent. 30 Keynote DeviceAnywhere Confidential