Deploy to a BlackBerry tablet simulator

Before you distribute your application to users, you can test it by using the BlackBerry Tablet Simulator. The BlackBerry Tablet Simulator enables you to run and view your applications exactly as you would on a real BlackBerry PlayBook. The BlackBerry Tablet Simulator operates using VMware software.


Tablet Simulator

Installing the simulator for Windows

Pre-requisites:

Download and install the VMware Player from www.vmware.com/download/player. Verify that you have 8 GB of available hard disk space or more, and at least 2 GB of RAM.

Do not choose the Create a New Virtual Machine option to complete this task.

  1. On the VMware Player Home screen, click Open a Virtual Machine.
  2. On the Open a Virtual Machine screen, navigate to the folder where you installed the BlackBerry WebWorks SDK.
  3. In the bbwp/blackberry-tablet-sdk/BlackBerryPlayBookSimulator-<version> subfolder, click the BlackBerryPlayBookSimulator.vmx file.
  4. Click Open.
  5. Click Play virtual machine.
  6. After the simulator starts, in the Password field, type playbook.
  7. Click OK.

Installing the simulator for Mac OS

Pre-requisites:

Download and install VMware Fusion from www.vmware.com/products/fusion. You should install VMware Fusion as the root user, or it will not be able to access the simulator files. If you have already installed VMware Fusion as a non-root user, you can still use it without reinstalling by making a copy of the simulator folder as a non-root user. The default location for the simulator files is /Developer/SDKs/Research In Motion/BlackBerry WebWorks SDK for TabletOS <version>/bbwp/blackberry-tablet-sdk/BlackBerryPlayBookSimulator-<version>.

  1. In VMware Fusion, click File > Open.
  2. On the Open screen, navigate to the location where you installed the BlackBerry WebWorks SDK.
  3. In the bbwp/blackberry-tablet-sdk/BlackBerryPlayBookSimulator-<version> subfolder, select the BlackBerryPlayBookSimulator.vmx file.
  4. Click Open.
  5. Click Play virtual machine.
  6. After the simulator starts, in the Password field, type playbook.
  7. Click OK.

Running your application in the simulator

To run your application on the BlackBerry Tablet Simulator you need to:
  1. Set up the BlackBerry Tablet Simulator: turn on Development Mode and retrieve the IP address.
  2. Deploy your application to the BlackBerry Tablet Simulator by using the Ripple emulator or the BlackBerry WebWorks SDK.

Set up the BlackBerry Tablet Simulator

  1. Start the BlackBerry Tablet Simulator.
  2. In the BlackBerry Tablet Simulator, turn on the Development Mode. When the BlackBerry Tablet Simulator is in Development Mode, you can load and run your application on the simulator, as well as view the IP address of the BlackBerry Tablet Simulator.
    1. In the virtual machine for the BlackBerry Tablet Simulator, in the upper-right corner of the simulator screen, click the Image of Settings icon icon to access the settings.
    2. From the left panel, select Security.
    3. On the Security screen, click Development mode.
    4. Set Use Development Mode to ON.


      Enable Development Mode

    5. Close the Settings wndow by clicking the up arrow that's displayed at the bottom of the BlackBerry Tablet Simulator screen.

      The Development Mode icon Image of Development Mode icon displays on the main screen indicating that the Development Mode is enabled.

  3. Record the IP address of the BlackBerry Tablet Simulator. You can view the tablet's IP address by tapping the Image of Development Mode icon icon.

Deploying your application by using the Ripple emulator

  1. Complete the Launch settings in the Ripple emulator (you'll need to complete the Build section too, if you don't already have it filled in). After you have saved the settings, the Ripple emulator retains the settings for the next time you launch your application.
    1. In the Ripple emulator, select the Build panel.
    2. Select Settings.
    3. In the PlayBook IP field, type the IP address of your BlackBerry Tablet Simulator.
    4. In the PlayBook Password field, type the password for your BlackBerry Tablet Simulator (the default password is "playbook").
      Launch settings in the Ripple emulator

    5. Click the X to close the window and save your settings.
  2. If the build and deploy services are not currently running, click Start Services.
  3. Click Package & Launch.

The Ripple emulator builds and packages your application. If the build and package completes successfully, the message "Build succeeded!" displays. The .bar file is created in the output folder you specified in the settings. In the BlackBerry Tablet Simulator, your application launches.

Deploying your application by using the BlackBerry WebWorks SDK

You can use the command-line BlackBerry WebWorks SDK to deploy your application to the BlackBerry Tablet Simulator.

Before you start:
  • Successfully package your application with the BlackBerry WebWorks SDK. For more information, see Package from the command line.
  • Make sure that your BlackBerry Tablet Simulator is running and that the Development Mode is enabled
  • Make sure you know the IP address of the BlackBerry Tablet Simulator
  1. Open up a command prompt, and navigate to the bbwp\blackberry-tablet-sdk\bin folder, which is under the BlackBerry WebWorks SDK installation folder.
  2. Type the following command to load and run your application in the simulator:

    For Windows: 

    blackberry-deploy -installApp -password <simulator password> 
    -device <simulator IP address> -package <BAR file path>

    For Mac OS: 

    ./blackberry-deploy -installApp -password <simulator password> 
    -device <simulator IP address> -package <BAR file path>

    Note: You can omit -password <simulator password> if you haven't set a password on your BlackBerry Tablet Simulator.

Removing your application from the simulator

  1. Open up a command prompt, and navigate to the bbwp\blackberry-tablet-sdk\bin folder, which is under the BlackBerry WebWorks SDK installation folder.
  2. Type the following command to remove your application from the simulator:

For Windows: 

blackberry-deploy -uninstallApp -device <IP_address> 
    -package <bar file name> -password <device password>

For Mac OS: 

./blackberry-deploy -uninstallApp -device <IP_address> 
    -package <bar file name> -password <device password>

Troubleshooting

To deploy your application to the BlackBerry Tablet Simulator you must perform the following actions:

  • Enable development mode on the target BlackBerry Tablet Simulator
  • Use the blackberry-deploy utility service from the command line prompt to deploy your application file to the simulator.

A result:success message appears if your application is deployed successfully. An error message appears if there is a problem with the deployment.

Error message

Description

Possible solutions

500 development apps pool exhausted

This message appears if you have more than ten applications installed on the simulator while in development mode.

Remove any unused applications from the simulator before you deploy your new application to the simulator.

500 navigator interlock failed

This message appears when a version of the application is already running on the simulator.

  • Wait for the simulator to release the application lock. If it fails to release the application lock then restart the simulator.
  • Use the blackberry-deploy -uninstallApp utility from the command line prompt to remove the application from the simulator.

Black screen at startup

When you start the simulator, it might launch a black screen on startup or it might freeze at the "BlackBerry PlayBook" splash screen.

  • Shut down the simulator. Ensure the 3D accelerator checkbox is checked on the VMware Player properties screen.
  • Reset the simulator from the VMware Player player menu. Click Virtual Machine, >Power, >Reset.

Cannot connect: Connection to https://<IP address> refused. You may have to reboot the target.

This message appears when the simulator is not responding.

  • Restart the simulator.
  • If the password is no longer accepted by the blackberry-deploy utility service, clear the password and set it again.

Connection to <IP address> Refused

This message appears when a VPN connection is blocking deployment.

  1. Test the IP address by typing a ping ip_address at the command prompt, using the IP address of your simulator.
  2. If testing the IP address with the ping command is unsuccessful, then the VPN connection is interfering with the connection to the simulator. Disable the VPN connection before you deploy your application.

Device is not in the development mode. Switch to Development from Security settings on the device.

This message appears when you do not have development mode enabled on your simulator.

  1. On the simulator, click the System icon on the taskbar.
  2. Select the Security tab.
  3. Switch the development mode option to On.
Invalid Auth Credentials

This message appears after you upgrade your simulator and you are running an older version of the BlackBerry Tablet OS SDK.

Upgrade the BlackBerry Tablet OS SDK to the same version of the simulator that you are using.

Username or password is invalid or not specified or time on the device is out of sync

This message appears in the following cases:

  • If the VMware Player was suspended, rather than the BlackBerry Tablet OS being shut down, the timestamp may be out of sync with that of the host machine.
  • The simulator password that was used during development is incorrect or expired.
  • Update the simulator system time to match that of your development machine.
  • Verify that the password is correct and not expired.
  • Verify that the version of the BlackBerry Tablet OS SDK is the same as the version of the BlackBerry Tablet OS.