Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Using the command prompt to control the BlackBerry Smartphone Simulator

The BlackBerry Smartphone Simulator contains a controller tool, named fledgecontroller.exe. This controller tool is a command prompt tool that is you can use to programmatically control the BlackBerry Smartphone Simulator in test scripts. When events occur inside the BlackBerry Smartphone Simulator, the controller tool generates messages. The controller tool is designed to enable you to test events that normally would only be perceived visually or audibly.

The controller tool provides commands that can instruct the BlackBerry Smartphone Simulator to simulate application commands, device commands, or external event commands. Application commands are commands for manipulating the simulated device on the BlackBerry Smartphone Simulator, such as a command to close the BlackBerry Smartphone Simulator, or to load a particular .cod file. Device commands control the simulated device and its immediate environment, such as whether it is open or closed, or device movement between GPS locations. External events are events that are generated externally from the

Use test scripts

You can produce automated tests by including the BlackBerry Smartphone Simulator controller tool within batch files. The BlackBerry Smartphone Simulator controller tool issues commands to the BlackBerry Smartphone Simulator. The controller tool is designed to enable you to test events that normally would only be perceived visually or audibly. When the BlackBerry Smartphone Simulator receives events or carries out commands, the controller tool presents messages on standard output. You do not require tools that automate GUI tests.

For example, you can use test scripts to test your application on several models of the BlackBerry device simultaneously.

The BlackBerry Smartphone Simulator controller tool accepts commands from either standard input or from a text file. You must connect the controller tool to a simulator session. You can create a .bat file that contains both the instructions for starting the simulator and the controller tool commands, or you can divide them into separate files. You must issue one controller tool command per line.

The BlackBerry Smartphone Simulator controller tool commands are like function calls. Optional parameters are at the end of the command and can be omitted if the default parameter is acceptable for your needs. Case is not important. White space around the parentheses is not important.

When you disconnect the controller tool from the BlackBerry Smartphone Simulator, the simulator still reflects the events that happened. For example, if you set the battery level to a new value, the simulator continues to reflect that value until the level is set again or the simulator is started again.

Start the BlackBerry Smartphone Simulator controller tool

At the command prompt, type fledgecontroller /session=<nnnn > with any additional parameters.

Example: Starting the controller tool with the /execute parameter

The BlackBerry Smartphone Simulator controller tool issues the BatteryLevel(5) command to the BlackBerry Smartphone Simulator for the BlackBerry 7290 smartphone and exits.

fledgecontroller /session=7290 /execute=BatteryLevel(5)

Syntax for the BlackBerry Smartphone Simulator controller tool

The BlackBerry Smartphone Simulator controller tool reads from standard input and writes to standard output. The controller tool has the following syntax:
fledgecontroller /session=<model_name> [/execute=<command>] [/timeout=<time_in_seconds>] [/get-sessions]

Parameter

Description

/session=<model_name>

This parameter specifies the session of the BlackBerry Smartphone Simulator to attach to. This parameter is required.

/execute=<command>

This parameter specifies which BlackBerry Smartphone Simulator command to be run. After running the command, the BlackBerry Smartphone Simulator controller tool closes.

/timeout=<time_in_seconds>

This parameter specifies how long, in seconds, the controller tool should run before closing.

/get-sessions

This parameter lists the names of any BlackBerry Smartphone Simulator sessions that are running. When this parameter is specified, even if other parameters are specified, the BlackBerry Smartphone Simulator controller tool closes after listing the names of existing sessions.

Send commands to the BlackBerry Smartphone Simulator

The BlackBerry Smartphone Simulator UI reflects the commands you type.
  1. At the command prompt, navigate to either the installation folder for the simulator or the bin folder of your BlackBerry Java Development Environment installation files.
  2. If necessary, start the BlackBerry Smartphone Simulator.
  3. Using the controller tool, named fledgecontroller.exe, connect the BlackBerry Smartphone Simulator controller tool to a running BlackBerry Smartphone Simulator.
  4. Type a BlackBerry Smartphone Simulator controller tool command.

Example

The following set of commands is entered at the command prompt in the folder that contains the BlackBerry JDE. The commands start the BlackBerry Smartphone Simulator, start the BlackBerry Smartphone Simulator controller tool, set the battery level to one-half, and stop the controller tool.

$ cd \Program Files\Research In Motion\BlackBerry JDE 4.2.0\bin
fledge /handheld=9800
fledgecontroller /session=9800
BatteryLevel(50)
quit

Test BlackBerry Smartphone Simulator events by using a script

  1. If necessary, create a command file and save it in the folder that contains your BlackBerry Smartphone Simulator or the bin folder of your BlackBerry Java Development Environment.
  2. Create a .bat file with commands to start the BlackBerry Smartphone Simulator and create a session.
  3. In the .bat file, write commands for connecting the BlackBerry Smartphone Simulator controller to the session, with a command that inputs data from the command file and directs output to a text file.
  4. Save the .bat file in the same folder that contains your command file.
  5. At a command prompt, navigate to the same folder that contains your command file.
  6. Start the .bat file.

Example

The BlackBerry Smartphone Simulator controller starts and issues the test commands in PhoneTest.txt to the BlackBerry Smartphone Simulator. After all the commands in the test command file are issued, the BlackBerry Smartphone Simulator closes and messages are written to a text file named out.txt. Both the test command file and the .bat file are in the same folder as the BlackBerry Smartphone Simulator.

The test command file, PhoneTest.txt, contains the following commands:

Pause(45)
RemoteCallCreation("519-555-0100")
Pause(2)
ThumbwheelPress
ThumbwheelRelease
Pause(10)
KeyPress(ESCAPE)
Pause(2)
KeyRelease(ESCAPE)
Exit

The .bat file contains the following commands:

fledge /handheld=9800
FledgeController.exe /session=9800 < PhoneTest.txt > out.txt

After running the .bat file, the out.txt file contains the following messages:

Audio: alert stopped
Connecting to Fledge session "test"... connected.
Buzzer: alert started
Buzzer: alert stopped
Audio: alert started
Disconnected

Close the BlackBerry Smartphone Simulator controller tool session

Perform one of the following tasks:

Task

Steps

Close the session connection.

Perform one of the following actions:

  • At the command prompt, type quit.
  • Press CTRL+Z.

Close the session connection and close the BlackBerry Smartphone Simulator.

  1. At the command prompt, type exit.

See a list of BlackBerry Smartphone Simulator commands

To view a list of commands for controlling the BlackBerry Smartphone Simulator, perform one of the following actions:

Action

Description

View a list of commands from the BlackBerry Smartphone Simulator.

  1. On the Help menu, click Controller Command Help.

View a list of BlackBerry Smartphone Simulator commands from a command prompt.

  1. At the command prompt, type fledge help.

For more information on running the BlackBerry Smartphone Simulator controller, type FledgeController /help.

Accessory commands

Device accessory or peripheral commands generate events on the BlackBerry Smartphone Simulator that involve BlackBerry device accessories or peripheral events.

Command

Description

Parameter

BatteryLevel (int level)

Specifies the charge level of the battery

level : Specifies the charge level of the battery as a percentage, where 100 represents a full charge, 0 represents empty

ExternalPower (bool charging)

Specifies whether battery charging is on or off

charging : If true, the battery charging is on; if false, the battery charging is off

HeadsetConnection (bool connected)

Specifies whether the external headset is connected

connected : If true, the external headset is connected; if false, the external headset is disconnected

RemoteCallDisconnection (string number)

Specifies that the remote phone should hang up

number : Specifies the phone number to disconnect from

HeadsetClick (bool pressed)

Specifies the state of the button on the external headset

pressed : If true, the button appears pressed; if false, the button does not appear pressed

Holster (bool holstered)

Specifies whether the BlackBerry device is holstered

holstered : If true, the BlackBerry device is in the holster; if false, the BlackBerry device is not in the holster

SimInsertion (bool inserted)

Specifies whether the SIM card is inserted

inserted : If true, the SIM card is inserted; if false, the SIM card is not inserted

Application commands

Application commands can control the behavior and appearance of the BlackBerry Smartphone Simulator.

Command

Description

Parameter

AllowFocusChange

Specifies that another application can obtain the foreground window focus

CarCradleAccessory (uint state)

Specifies whether the car cradle accessory is connected

state : If true, specifies that the car cradle is connected

Default value is false

Exit (bool save-flash)

Specifies that the BlackBerry Smartphone Simulator close

save-flash : If true, saves your changes to simulated application storage before closing

Default value is true

GetPid

Specifies that the controller tool return the ID of the BlackBerry Smartphone Simulator process

Help

Specifies that the controller tool generate help on controller tool commands

Kill

Specifies that the BlackBerry Smartphone Simulator process ends without saving simulated application storage, but the BlackBerry Smartphone Simulator ends immediately if the clean-up process fails

LoadCod (Path path)

Specifies a Java application in .cod format to load

path : The full path to the .cod file of the application

Pause (int time)

Specifies a period of inactivity for the BlackBerry Smartphone Simulator

time : The number of seconds to pause the BlackBerry Smartphone Simulator

Reset

Specifies that the BlackBerry Smartphone Simulator resets

SaveLcdSnapshot (Path filename)

Specifies that the current LCD image be saved as a snapshot in either .jpg format or .png format

filename : The path and file name of the saved image, where the format is determined by the extension of the file name

WindowLower

Specifies that the main BlackBerry Smartphone Simulator window move behind all other windows

WindowRaise

Specifies that the main BlackBerry Smartphone Simulator window move to the foreground

The Windows operating system blocks this command unless the application with focus calls the AllowSetForegroundWindow API.

WindowShow (bool show)

Specifies that the Windows operating system show or hide the main BlackBerry Smartphone Simulator window

show : If true, the BlackBerry Smartphone Simulator displays the main window

Default value is true

Network and phone commands

Network commands generate data and phone events.

Command

Description

Parameter

NetworkCoverage (int RSSI, WAF-types WAF)

Specifies the wireless coverage level

  • RSSI : Specifies the dB level, with -40 being strong and -256 being outside the wireless coverage area
  • WAF : Specifies the wireless access family, which is one of:
    • WAF_3GPP
    • WAF_CDMA
    • WAF_DUMMY
    • WAF_IDEN
    • WAF_NONE
    • WAF_USB
    • WAF_VPN
    • WAF_WLAN

    Default value is WAF_NONE

RemoteCallAnswer

Specifies that a remote phone answers a call placed from the BlackBerry device

RemoteCallCreation (string number, presentation-indicator-types presentation-indicator, alternate-line-type alternate-line)

Specifies a call from a remote phone to the BlackBerry device

  • number : Specifies the phone number that you call

  • presentation-indicator : Specifies the display of the caller ID, which is one of:
    • PI_ALLOWED
    • PI_PRIVATE
    • PI_UNKNOWN

    Default value is PI_ALLOWED

  • alternate-line : Specifies the line on the device that receives the call, which is one of:
    • VOICE_LINE_1
    • VOICE_LINE_2

    Default value is VOICE_LINE_1

RemoteCallDisconnection (string number)

Specifies that the remote phone hangs up

number : Specifies the phone number to disconnect from

RemoteCallFailure (string number, reason-types reason)

Specifies that the call fails

  • number : Specifies the phone number to use for the remote call

  • reason : Specifies the reason for the remote call failure, which is one of the reason documented on the online help

SupplementaryServiceProvisioning (service-types service, bool provisioned)

Specifies the addition or removal of a supplementary phone service

  • service : Specifies the supplementary service type to simulate, which is one of the supplementary services documented on the online help
  • provisioned : Specifies the service is provisioned, if true

Application environment and GPS commands

Application environment commands can control the environment of the simulated BlackBerry device, including the GPS information.

Command

Description

Parameter

BodyChanged(string state)

If the BlackBerry device is a flip phone or a slider phone, specifies whether the BlackBerry device is open or shut

state : Specifies the possible states for the device are open and shut

Default value is open

OrientationChanged (string orientation)

Specifies the new orientation of the BlackBerry device

orientation : Specifies the possible orientation of the device are top, left, right, bottom, front, and back

Default value is top

RenderingAccelerationChanged (int renderingAcceleration)

Specifies the graphics rendering acceleration for the BlackBerry Smartphone Simulator

renderingAcceleration : Specifies the speed of the graphics rending as one of off, low, medium, high, and max

GpsAddLocation (string Name, double Latitude, double Longitude, short Altitude, int Satellites)

Specifies the new GPS location of the BlackBerry device

  • Name : Specifies a name of the location, chosen by the BlackBerry device user
  • Latitude : Specifies the latitude value, between 89.99 and -90.00 degrees
  • Longitude : Specifies the longitude value, between 179.99 and -180.00 degrees
  • Altitude : Specifies the altitude in meters above or below the WGS 84 ellipsoid; default value is 0
  • Satellites : Specifies the number of visible satellites; default value is 4

GpsDeleteLocation(string Name)

Specifies the GPS location that the BlackBerry device should delete

Name : Specifies the name of the location

GpsAddRoute(string Name)

Specifies the addition of a new empty route

Name : Specifies the name of the route

GpsDeleteRoute(string Name)

Specifies the removal of the named route

Name : Specifies the name of the route

GpsAddLocationToRoute(string route, string location, double speed )

Specifies a location to be added to the named route

  • route : Specifies the name of the route
  • location : Specifies the name of the GPS location to add
  • speed : Specifies the speed of travel, in meters per second

GpsAddCoordsToRoute (string route, double speed, double latitude, double longitude, short altitude, int num-sats)

Specifies coordinates that are added to the named route

  • route : Specifies the name of the route
  • speed : Specifies the speed of travel, in meters per second
  • latitude : Specifies the latitude value, between 89.99 and -90.00 degrees
  • longitude : Specifies the longitude value, between 179.99 and -180.00 degrees
  • altitude : Specifies the altitude in meters above or below the WGS 84 ellipsoid; default value is 0
  • num-sats : Specifies the number of visible satellites; default value is 4

GpsGenerateRandomRoute (string name, string start, string finish, double legs, double time)

Specifies that the BlackBerry Smartphone Simulator create a new route

  • name : Specifies the name of the new route
  • start : Specifies the starting location of the route, which must be an existing named location or the word Random
  • finish : Specifies the ending location of the route, which must be an existing named location or the word Random
  • legs : Specifies the number of sections in the route
  • time : Specifies the time, in seconds, to complete the route

GpsLoadRouteFromFile (Path file, string name)

Specifies the name of a file that contains the route, one route to a file

  • file : Specifies the path to the file
  • name : Specifies the name that the route is given

GpsSetCoords (double latitude, double longitude, short altitude, int num-sats)

Specifies by coordinates the current GPS location for the BlackBerry device

  • latitude : Specifies the latitude value, between 89.99 and -90.00 degrees
  • longitude : Specifies the longitude value, between 179.99 and -180.00 degrees
  • altitude : Specifies the altitude in meters above or below the WGS 84 ellipsoid; default value is 0
  • num-sats : Specifies the number of visible satellites; default value is 4

GpsSetLocation (string location)

Specifies by name the current GPS location for the BlackBerry device

location : Specifies the name of the location

GpsStartRoutePlayback (string name)

Specifies that the BlackBerry device start playing the named route

name : Specifies the name of the route

GpsStopRoutePlayback (string name)

Specifies that the BlackBerry device stop playing the named route

name : Specifies the name of the route

Keyboard and event commands

The input commands generate keyboard events and BlackBerry smartphone input events.

Command

Description

Parameters

KeyPress (key-types key)

Specifies the key-press signal to send

key : Specifies the key to use for a key-press event

KeyRelease (key-types key)

Specifies the key-release signal to send

key : Specifies the key to use for a key-release event

KeyCodePress (int key, int depth)

Specifies the press and release of the key with the given key code

  • key : Specifies the key code of the key to press, which defaults to 0
  • depth : Specifies the level of clicks for the key event, which defaults to -1

StringInjection (string key)

Specifies the character string to be inserted into the application

string : Specifies an ASCII character string to enter into the application, even if the characters in the string cannot be created using the keyboard of the BlackBerry smartphone

PreTranslatedKeyPress (char key)

Specifies the pre-translated key that is pressed

key : Specifies the key that you want to use for a press pre-translated key event

PreTranslatedKeyRelease (char key)

Specifies the pre-translated key that is released

key : Specifies the key that you want to use for a release pre-translated key event

SimulateSwipe( int direction )

Specifies a swipe event on a touchscreen

direction: Specifies the direction of the simulated swipe, which is one of the following:
  • 0 represents an upward swipe
  • 1 represents a swipe to the right
  • 2 represents a downward swipe
  • 3 represents a swipe to the left

ThumbwheelPress

Specifies a press of the trackwheel

ThumbwheelRelease

Specifies a release of the trackwheel

ThumbwheelRoll (int movement)

Specifies that the trackwheel is moved a number of clicks

movement : Specifies the number of clicks to roll the trackwheel, where a positive value indicates a downward roll and a negative value indicates an upward roll

TrackballPress

Specifies a press of the trackball

TrackballRelease

Specifies a release of the trackball

TrackballRoll (int x-delta, int y-delta)

Specifies that the trackball is rolled a number of clicks.

  • x-delta : Specifies the number of clicks to roll the trackball in the left or right direction, where a positive value indicates a right roll and a negative value indicates a left roll
  • y-delta : Specifies the number of clicks to roll the trackball in the up or down direction, where a positive value indicates an upward roll and a negative value indicates a downward roll

TouchScreenClick

Specifies a click on the touch screen

TouchScreenUnclick

Specifies the end of a click on the touch screen

TouchScreenPress( int x, int y, int finger)

Specifies a press on the touch screen

  • x : The x coordinate to press on, where the coordinate is displayed in the lower corner of the BlackBerry Smartphone Simulator
  • y : The y coordinate to press on, where the coordinate is displayed in the lower corner of the BlackBerry Smartphone Simulator
  • finger : Specifies the finger to press with, used when performing multitouch events, which defaults to 0

TouchScreenUnpress( int finger)

Specifies the end of a press on the touch screen

finger : Specifies the finger to release, which defaults to 0

IT policy commands

The IT policy commands generate and accept IT policy events. To use these events, you must be set up your BlackBerry Smartphone Simulator to test BlackBerry Enterprise Server IT policies.

Command

Description

Parameters

ITPolicyQueue(unsigned long Tag, unsigned long SubTag, string Value)

Specifies which IT policy to put into the queue

  • Tag : Specifies the IT policy category
  • SubTag : Specifies the name of the IT policy
  • Value : Specifies the value or content of the IT policy

ITPolicySend

Specifies that the controller should send all IT policies in the queue to the BlackBerry smartphone

ITPolicyACQueue(ITP_AC_ID ID, ITP_AC_VALUE Value)

Specifies that the BlackBerry Smartphone Simulator controller should queue up an application control permission

  • ID : Specifies the application control ID
  • Value : Specifies the permission given to the application control ID, which is currently ITP_AC_DENY

ITPolicyACSend

Specifies that the controller should send all application control permissions that are in the queue to the BlackBerry smartphone