ACCESS Developer Network | Using the Simulator | Simulator, Target, Configuration, Use, Option

The ACCESS Linux Platform Simulator is a hosted GTK application that simulates Access Linux Platform executing on arbitrary target hardware. It allows you to view the execution and behavior of applications running on the simulated target device, while giving you full control over the simulated target device's inputs—whether they be a touch screen, buttons, or accessory connections. Target control is provided through the use of the host computer's mouse, keyboard, monitor, and peripheral connections. The Simulator is ideal for testing and debugging your ACCESS Linux Platform applications.

Simulator Overview ^TOP^

The Simulator consists of two major parts: the user interface (also referred to as the "front end"), and the interface to the Simulator engine (the "back end"). Normally you would launch the whole using alp-sim. You have the option to launch the simulator engine alone with alp-simulator, but it is highly recommended to use alp-sim, which prepares the environment automatically.

The Simulator engine drives only the device's display and touchscreen; without the front end you won't see the device "skin" and you won't be able to click on simulated hard keys (but note that there are keyboard equivalents for most, if not all of these).

The Simulator front end is based upon xoo and Xephyr. xoo is a GTK2 based graphical wrapper around a "windowed" X server. It is intended for embedded developers who want to simulate a target device (with an accurate display size, working hardware buttons, etc.) on a desktop machine. xoo is free software, available under the GPL. For more on xoo, refer to http://projects.o-hand.com/xoo/.

The Simulator runs only on a Linux computer running a recent version of Ubuntu (e.g. 6.10 or 7.04).

Controlling the Simulator ^TOP^

The Simulator is a hosted GTK application, and as such, provides you with full control over the target. You can control target configuration, creating any number of configurations to be saved and later reloaded. Any configuration can be used to start up a simulation session. Sessions can be launched, rebooted, or halted. Actions that are specific to a target, such as pressing buttons or inserting accessories, can be performed by selecting them from a menu.

Simulated Target Device ^TOP^

The Simulator displays an image, or "skin," of the actual target device around a virtual touchscreen. Each skin can contain designated areas that can be used to simulate target device buttons. During a simulation session, you can run applications on the selected target configuration, interacting with the target either through the virtual touchscreen, device buttons, or keys, by using the host's mouse or keyboard.

User Interface ^TOP^

The Simulator's user interface consists a set of menus used to control the Simulator, a target "skin" (a bitmap of a real or imaginary device that simulates the body of the device, including hard keys), and an area that simulates the target device's display and touchscreen. The menus allow you to configure and control the Simulator, as well as simulate certain target actions (altering the battery level, for instance).

When you place your cursor over one of the buttons on the device (such as "HOME", or "5", or "volume up" [on the left side of the device image]) and click your mouse, the simulated device responds as if you had pressed the corresponding button on a real device. As well, to simulate touchscreen presses simply place your cursor on the desired spot on the touchscreen and click your mouse.

The menus with which you configure and control the Simulator are displayed at the top of the image (Configuration, Session, Actions, Help). ACCESS Linux Platform devices have their own menus, accessed either by clicking the MENU button on the device's keypad, or by tapping the application's name in the title bar (on the touchscreen; in the above image the application's name is "Applications").

The Simulator also maps keys on your host computer keyboard to device actions. See "Operating the Simulator" for the specific keyboard mappings.

Menus ^TOP^

The Simulator's menu contain the items listed in . The Configuration menu allows you to manipulate target configurations. The Session menu consists of (re)booting, running, and terminating the target. The Actions menu consist of those things that can be done to the target, such as connecting a external battery charger or informing the target of the current battery level.

Simulator menu itemsÂ

Menu	Item	Selection	Description
Configuration
	Edit		Edit the current configuration
	Open		Open an existing configuration file
	Save		Save the current configuration to the current file
	Save As...		Save the current configuration to a new file
	Close		Close the current configuration file and halt the session
	Quit		Halt and exit the Simulator
Session
	Reboot		Reboot the target
	Launch		Launch the target
	Halt		Halt the current session
	Factory Reset		Reboot the target with a factory reset
Actions
	Telnet to Target		Create a telnet session in a console window, connected to the simulated target
	Charger Connected		Simulate connection or disconnection of an external power supply
	Battery Level...
		Full	Set battery level to full
		Low	Set battery level to low
		Empty	Set battery level to empty
Help
	About		Display general information, including version and copyrights

Target Configuration ^TOP^

A simulator session is an instance of a target's execution. Each target configuration specifies the attributes of the target device for a Simulator session. A configuration consists of a description of the platform image, the engine to use when simulating the target, the amount of RAM assigned to the device, the skin, and host TCP/IP settings.

The selected platform image can either be a Scratchbox target or a ROM image file (ROM image files can be any localized image, and can either be release or debug images). The selection of a simulation engine allows you to choose the type of platform virtualization.

The Simulator uses the notion of a "current configuration" which is stored using the GConf configuration system so that when you launch the Simulator the last specified configuration is recalled and used. You can specify or change this "current configuration" at any time by selecting New from the Simulator's Configuration menu.

The Target Configuration dialog, which is displayed when you create a new session, is shown in Figure 1.1.

Figure 1.1 Target configuration dialog

The contents of this dialog are as follows:

Scratchbox Target: The name of the Scratchbox target. This defaults to the currently selected target in Scratchbox, but you can use the pull-down list to select a different target if you like.
ROM Image: If, instead of a Scratchbox target, you want to run the Simulator based upon a ROM image, you would select the radio button next to the ROM Image label and then browse to the file containing the ROM image (an ext2 format file) by clicking the button to the right. Normally you use a Scratchbox target when simulating ACCESS Linux Platform targets, and would not use this option.
Simulation Engine: Allows you to select between the supported Simulation engines.
RAM Amount: Use this to alter the amount of RAM in the simulated target device. While ACCESS Linux Platform is designed to work comfortably in 64Mb of RAM, if the device you are simulating has more, you'll want to alter this setting. As well, you may find that additional RAM improves performance.
Skin: Specifies the skin to be used for this target configuration. Skins are typically found in /opt/alp-dev/share/xoo/.
Create host network bridge: Enables access to your local network or the Internet from inside the Simulator through the Connection Manager (or applications that use it). Selecting this option allows device applications such as the web browser to work using your host computer's network connection. See the discussion of the --net option under "Command-Line Options for Starting the Simulator Engine" for more specifics.
Enable NAT: This option, which is only relevant if Create host network bridge is enabled, enables or disables Network Address Translation (NAT).
Keep host network bridge: If selected, causes the host network bridge to persist between simulation sessions.
Factory Reset: Performs a factory reset the next time the target is rebooted.

Using the Simulator ^TOP^

A simulation session can be launched as follows:

Launch the Simulator; the configuration is set from the configuration that was defined before the Simulator was last terminated.
Open a configuration file; the configuration is set from the contents of the file.
Edit the configuration; the configuration is set from the values in the Target Configuration dialog once it is closed by accepting the values.
Launch the target with the Session > Launch menu item, although note that this can only be done once a session has been halted.

In each of these cases the specified platform image is launched in the specified simulation engine with the specified RAM quantity and networking values passes to the engine. If the skin is different in the new configuration, it is changed before the target is launched. If the session is being launched from a new configuration, it can be specified to do a factory reset first.

Once a session is running, it can be halted as follows:

Simply close the Simulator, either by selecting the Configuration > Quit menu item or by clicking the "Close Window" icon (the red X icon in the upper right corner of the Simulator window).
Use the Session > Halt menu item. This simply halts the session; any currently opened configuration file is neither changed nor closed, and the Simulator is not exited.

There is only one way to reboot the session: use the Session > Reboot menu item.

Launching ^TOP^

The Simulator is launched from a Terminal window with:

alp-sim

It can be launched with various command-line options:

--factory-default | -f: force target configuration, seeded with factory defaults before launch
--help | -h: show help

Change or specify the current configuration at any time by using the Configuration > Edit menu item. Note that when you edit and accept the configuration, the Simulator session will be restarted! Any configuration can be saved in an XML "target configuration" file, through the use of the Save and Save As menu items in the Configuration menu. To restore a saved target configuration, use Configuration > Open and specify the desired configuration file.

When you launch the Simulator for the very first time, or when you launch it using the factory default option, the Target Configuration dialog will appear before the session is started. Make any desired changes to the configuration, after which the session will be started.

Rebooting a Target ^TOP^

To reboot a running session, use Session > Reboot.

Operating the Simulator ^TOP^

Table 1.1 identifies how some of your computer's keyboard keys are mapped to special functions in the Simulator.

Table 1.1 Simulator feature to keyboard mappingÂ

Simulated Feature	Keyboard Key
Home screen	The "home" key
HotSync	F12
Generic app launch keys	F4-F7
On-hook	Escape
Off-hook	F1
Menu	F10
Jump list	F8
JV-Lite (Java) Left soft key	F1
JV-Lite (Java) Right soft key	F2

Entering Unicode Characters

To enter a Unicode character, hold down the Control and Shift keys while entering the Unicode code point. For example:

While holding Ctrl+Shift, press 2, 0, A, C to enter the Euro character.
While holding Ctrl+Shift, press 6, 7, 0, 8 to enter the Chinese moon/month character.

Restricting the Cursor to the Simulator Window

The Control and Shift keys, when held while entering hexadecimal values, allow you to "type" Unicode characters. If you press the Control and Shift keys and then release them without entering a hexadecimal value, however, the cursor will be "locked" to the Simulator window; you will be unable to move it beyond the bounds of the window.

Press the Control and Shift keys and then release them to "unlock" the cursor, allowing it once again to escape the bounds of the Simulator window.

Exiting an Application

Return to the home screen by pressing the Home key on your computer's keyboard.

Connecting to the Simulator ^TOP^

To connect to the Simulator from a separate host shell prompt, enable network connectivity (see "Networking") and type:

telnet 192.168.3.101

Command-Line Options for Starting the Simulator Engine ^TOP^

There are a number of command-line options that can be used when launching the Simulator engine, alp-simulator. Use the --help option to display a complete list of options. Note that not all options are available when using alp-sim directly, as recommended.

alp-simulator --help

Other options are:

--factory-reset: Boot in "factory reset" mode, deleting all data.
--rescue-mode: Boot in minimal "rescue mode", for fixing system problems.
--nat: Configure iptables for NAT forwarding to UML and copy DNS info (the host's resolv.conf) into the rootfs.; See "Networking" for more information on this option.
--net: Create host network bridge (br0) and connect to eth1 in UML. Like --nat, this option also configures iptables for NAT forwarding to UML and copies DNS info (the host's resolv.conf) into the rootfs.; The UML_NET_IFACE environment variable overrides the host physical connection default (eth0 in most cases). The UML_NET_IP environment variable assigns a static IP to br0 instead of using DHCP.; See "Networking" for more information on this option.
--net-nonat: Same as --net but without the effects of --nat.
--keep: Leave the host network bridge up after UML exits. This option is for use with the --net or --net-nonat options.
--noninteractive: Boot UML with no sudo commands or prompts. This option is intended primarily for Eclipse or automation.
--serial: Configure serial ports ttyS0 and ttyS1 for UML. If a USB serial device is connected as /dev/ttyUSB0, it replaces the ttyS0 serial port in UML.; The UML_TTYS0_SPEED environment variable overrides the default port ttyS0 speed of 115200. The UML_TTYS1_SPEED environment variable overrides the port ttyS1 default speed of 19200.
--skin [name]: Enable a Simulator device skin. Use the default skin unless name is specified or the UML_DEVICE_SKIN variable is set (in which case it is not necessary to use the --skin option).
--no-skin: Disable any Simulator device skin that may have been specified using the UML_DEVICE_SKIN environment variable.
--list-skins: Display the list of available device skins.
--ROM-image file: Boot using the specified ROM image file (ext2 on /dev/ubda).
--var-image file: Mount the specified read/write /var image file (ext2 on /dev/ubdc).

NOTE: file must be a complete path; relative paths are not allowed. You can use "`pwd`/file.ext2".

--var: Automatically create and use the default read/write /var image. The UML_VAR_SIZE environment variable overrides the default size (in MB) of 64. A target-specific var image will be created and used. Use "--var" or "--var-image file" but not both. To reset (clear) the var image, use
"--factory-reset".; The --var option is enabled by default; to disable it, use --novar.
--novar: Do not create and use a default target-specific /var image. Instead, use /var from the root filesystem.
--append-cmdline str: Append the specified string to the UML kernel command line. For example, str could be "ubdd=/path/to/image.ext2".
--kernel-config: Displays the configuration file from which the UML kernel was built.
--kernel-version: Displays the UML Linux kernel version information.
-v | --version: Display version information (using "alp-versions").

Environment Variables ^TOP^

There are a couple of environment variables that can be set to alter the default behavior of the ACCESS Linux Platform Simulator:

UML_TARGET, UML_ROOT: By default the Simulator boots the Scratchbox target named "alp-simulator" unless the UML_TARGET or UML_ROOT variables are defined. Use UML_TARGET to specify the Scratchbox target to boot. Use UML_ROOT to specify a path to the UML root filesystem. For example:; export UML_TARGET=my-simulator; or; export UML_ROOT=/path/to/uml/rootfs
UML_DIR: This variable allows you to specify an alternate path to the UML binary. By default, the command alp-sim runs /opt/alp-dev/lib/alp-simulator.
UML_MEM: Specifies the amount of physical memory the Simulator is launched with. By default, it is launched with 64 MB of physical memory. To change it, for instance to 256 MB:; export UML_MEM=256M
UML_NET_IP: When the --net option is used the bridge is configured using DHCP unless the environment variable UML_NET_IP is set, in which case the bridge is statically configured using the value of UML_NET_IP.
UML_NET_IFACE: When the --net option is used, during configuration of the bridge if the environment variable UML_NET_IFACE is set its value is taken as the bridge endpoint on a LAN (i.e., if you have several Ethernet cards).
DISPLAY: The DISPLAY variable specifies the X display server. For example:; DISPLAY=192.168.108.123:0.0 alp-simulator
UML_XSCREEN: The screen number to be used by the UML internal Xephyr is :0. An alternate may be provided by defining UML_XSCREEN, like this:; UML_XSCREEN=:1 alp-simulator
PALMSOURCE_COMPORT_VP: By default, the UML environment expects to contact the Virtual Phone program at 192.168.3.100. An alternate address can be provided by defining PALMSOURCE_COMPORT_VP:; PALMSOURCE_COMPORT_VP=192.168.108.123
PALMTRACE_TARGET: If the trace facility is configured to output to "tcp:", with no host specified, the trace facility looks to the PALMTRACE_TARGET variable for the host and optional port number of the trace target (Palm OS Reporter).

Networking ^TOP^

The first time you run the Simulator engine with the --nat option, it is configured so that subsequent runs of the Simulator should support networking without you having to again specify the --nat option.

Use the --nat option for:

Virtual Phone (running on a different machine)
Palm Reporter
Cygwin/X
gaining access to your local network or the Internet from inside UML without using the Connection Manager (or applications that use it).

The --nat option turns your Ubuntu computer into a gateway for your UML. DNS servers are copied inside the UML rootfs.

Use the --net option for:

gaining access to your local network or the Internet from inside UML through the Connection Manager (or applications that use it).

The --net (as opposed to --nat) option enables an Ethernet connection with the Connection Manager (or applications that use it). This option has the following effects:

Sets your Ethernet connection down on your Ubuntu computer.
Creates a bridge between your Ethernet card and a virtual interface.
Configures the bridge. This is done using DHCP unless the environment variable UML_NET_IP is set, in which case the bridge is statically configured using the value of UML_NET_IP. If the environment variable UML_NET_IFACE is set, its value is taken as the bridge endpoint on a LAN (i.e. if you have several Ethernet cards).
Launches a virtual switch (which is connected to the virtual connection) in a new xterm. The window appears when you start the Simulator.
Starts UML with an additional Ethernet interface (eth1) which is connected to the virtual switch. The --net-keep option skips this step but performs the others, allowing for faster starts the next time you start the Simulator with either --net or --net-keep.

When you halt UML, the virtual switch is killed, the bridge is destroyed, and your Ethernet is restored.

The --net option automatically includes --nat. To get the --net option without the effects of --nat, use the --net-nonat option instead.

NOTE: Don't worry about the huge size of the traces of the virtual switch inside the xterm: this is a side effect of the bridge configuration. After several hours, the virtual switch can slow down the performances of your Ubuntu computer. In this case, halt your UML and restart it.

Debugging Drawing ^TOP^

From the Xephyr ReadMe file:

Send a SIGUSR1 to the server (e.g. "kill -USR1 `pidof Xephyr`" from a target shell) to toggle the debugging mode. In this mode red rectangles are painted to screen areas getting painted before painting the actual content. The delay between this can be altered by setting a XEPHYR_PAUSE environment variable to a value in microseconds.