iSimulate Documentation

1. Introduction

iSimulate was designed to solve the issue of not being able to use multi-touch and the accelerometer in the iPhone Simulator. With iSimulate, you can record high-quality videos of your multi-touch or accelerometer-based applications, by screen capturing the iPhone Simulator which now receives all the touch and accelerometer events. And starting with the 1.5 update, you can also use the Compass in the iPhone Simulator.

Furthermore, you can save precious time spent in repeatedly installing applications to development devices by testing all your applications in the iPhone Simulator; with full multi-touch and accelerometer support. Besides saving considerable time, iSimulate allows you to send to the iPhone Simulator the true Device ID and true Location of your device, or, you can configure it so it sends various Fake Device IDs and various Fake Locations to the iPhone Simulator.

iSimulate consists of two parts, the iSimulate client and the iSimulate SDK library. The iSimulate client is an iPhone / iPod Touch application available on the App Store. The iSimulate SDK is a library that you need to add to your Xcode project.

To start using iSimulate, run the iSimulate client on your device and run your project in the iPhone Simulator. Any touches, all the accelerometer events, compass events, the Device ID and the Location information will be streamed to the iPhone Simulator.

2. Requirements

iSimulate Client

  • The iSimulate client runs all iterations of the iPhone and iPod Touch, up till the iPhone 3GS and the third generation iPod Touch. It is available on the App Store.

iSimulate SDK

  • The iSimulate SDK library works with applications built for the iPhone OS 3.0 and higher. As of iSimulate 1.5, the SDK for iPhone OS 2.x will no longer be maintained, but the latest version is kept available.

3. Installation

Below are the steps on how to start using iSimulate. You can instead watch this crazy cool "Using iSimulate" video below which details how to add the iSimulate SDK to your iPhone Xcode projects.

Download and Install

  1. Install the iSimulate client application for iPhone/iPod devices from the App Store.
  2. Download the iSimulate SDK library and extract it. If your application uses OpenGL, download the OpenGL SDK.
iSimulate Usage Steps

Add to Your Xcode Project

  1. Add the iSimulate library file named "libisimulate.a" to your Xcode project.
    • Open your project in Xcode and from the Project menu select "Add to Project..."
    • Browse to where you extracted the SDK, choose "libisimulate.a", and then in the next screen click "Add."
  2. Add the CoreLocation framework to your project if it is not already included.
    • iSimulate requires this framework to compile. It is a dynamic library, so it won't increase the size of your app.
    • To add the framework, in the "Groups & Files" panel, and under "Targets," right click on your project's target and select "Get Info." Then, in the "General" tab, click the "+" button below the "Linked Libraries" list and select the CoreLocation framework.
  3. Add to "Other Linker Flags" the value "-ObjC".
    • From the "Project" menu select "Edit Project Settings."
    • At the top of the "Build" tab select "All Configurations" in "Configurations" dropdown list, type "Other Linker Flags" in search box and set the value of the "Other Link Flags" to -ObjC.
    • Note: If iSimulate on your client is not seeing your Mac, it is likely the library wasn't linked to the application in the iPhone Simulator. Try adding the -ObjC flag in the Target as well as in Project Settings.
  4. Now build the project with the Simulator as the Active SDK.

Or, just watch this cool video:

4. Using iSimulate

iSimulate can be used in Capture Mode or Viewing Mode. In Capture Mode, all touch events, accelerometer events, compass events, Device ID and Location are sent in real-time to the iPhone Simulator. In Viewing Mode, you can see the data on-screen without connecting to the Simulator.

iSimulate Screenshot 1   iSimulate Screenshot 1   iSimulate Screenshot 1

Capture Mode

  1. Run your application on the iPhone Simulator, and run the iSimulate client on your iPhone or iPod Touch. Make sure that both your computer and the device are on the same wireless network.
  2. As soon as your application starts in the iPhone Simulator, the name of your computer would appear in the iSimulate client. Select your computer from the list.
  3. iSimulate will start the capture mode. Any touches, all the accelerometer events, compass events, the Device ID and the Location information will be streamed to the iPhone Simulator.

Viewing Mode

  1. To start the Viewing Mode, click on the Binoculars at the bottom left of the main iSimulate screen.
  2. In the Viewing Mode, all data is displayed on-screen and none is streamed back to the iPhone Simulator.

5. Options

Fake Device IDs

  1. Click on the Options button (the "i" at the top right corner) and select a Fake Device ID.
  2. Once the iSimulate client connects to the iPhone Simulator, it will be sending the Device ID as the selected one. For example, choosing "x1E" will send "id1cgfa75da26094e3b54e5c298d91a8ba114f3E" as the Device ID.

Fake Location Services

  1. Click on the Options button (the "i" at the top right corner) and select a Fake Location.
  2. Once the iSimulate client connects to the iPhone Simulator, it will be sending the location as the selected one.

Video Streaming

  • Click on the Options button (the "i" at the top right corner) and enable Video Streaming by selecting a frame rate to be used to stream the view of the iPhone Simulator to your device.

Disabling Touch Indicators

  • By default, iSimulate displays circles on the iPhone Simulator at the positions of the touch events. If you want to disable these touches, add the following code to applicationDidFinishLaunching method in your AppDelegate class:
  • if (NSClassFromString(@"iSimulate"))
    	[NSClassFromString(@"iSimulate") disableTouchesOverlay];
    

Customizing the Touch Indicators

    By default, iSimulate displays circular touch indicators in the position of touch occurrence on the iPhone Simulator. You can disable the display of these touches, as desribed above, and you might also change the look of the touch image.

  • isimulate-touch.png: Just add an image file named isimulate-touch.png to your project, and iSimulate will automatically use this image instead of the default indicator image for all touch events.
  • Or, region-based touches: You may also programmatically define regions on the screen and associate with each region a separate touch image. You can define as many regions as you want. To define a region:
  • if (NSClassFromString(@"iSimulate")) {
    	[NSClassFromString(@"iSimulate")
    		setImage:[
    			[NSBundle mainBundle]
    			pathForResource:@"imageName" ofType:@"png"
    		]
    		forRegion:CGRectMake(0, 0, 100, 100)
    		inOrientation:UIInterfaceOrientationLandscapeLeft
    		withAlpha:255
    	];
    }
    

SDK Updates

  • The iSimulate SDK can check for updates of the SDK on each time the application launches, and show an alert if one was found. Although no information of any kind is sent, this feature is disabled by default as of SDK version 1.0-20090807. To enable it, add the following code to the applicationDidFinishLaunching method in your AppDelegate class:
  • if (NSClassFromString(@"iSimulate"))
    	[NSClassFromString(@"iSimulate") enableUpdatesNotification];
    

6. OpenGL and UIKit Support

As of iSimulate 1.5, there are no limitations on the use of UIKit. All touches are transferred to all types of UIKit objects, so you can use iSimulate to develop virtually any OpenGL or UIKit application.