Simulator for Windows SideShow

The Microsoft Windows Software Development Kit includes the Device Simulator 3.0 for Windows SideShow. This simulator is a program that simulates a Windows SideShow–compatible device built on the Microsoft .NET Micro Framework firmware solution, so that developers of gadgets for SideShow can test their gadgets without physical hardware.

Note

  • The simulator is supported only on Windows Vista or later versions of Windows.

  • The simulator requires Administrator privileges to run.

This topic contains information on the following:

  • Installing the simulator

  • Running the simulator in different modes for touch-enabled and button-driven devices.

  • Configuring the screen resolution

  • Simulator command-line arguments

  • Troubleshooting the simulator

  • Changing the default language of the simulator

  • Files you can use to run the simulator

Installing the Simulator

  1. Open an elevated command prompt. (To do this: Click Start, point to All Programs, point to Accessories, right-click Command Prompt, and then select Run as administrator.)

  2. Go to the following location: Windows SDK Installation Folder\Bin

    If your Windows SDK installation does not contain the simulator setup file, DeviceSimulatorForWindowsSideShow.msi, download the file from the Microsoft Web Site.

  3. Run the command: DeviceSimulatorForWindowsSideShow.msi

  4. Install the simulator by using the wizard that appears.

Running the simulator in touch, landscape and portrait modes

You can run the simulator in three different modes: touch, landscape, and portrait. The touch mode emulates touch-enabled hardware and does not provide directional pad (D-pad) buttons. The screen resolution in touch mode is configurable to up to 640 x 480. Landscape mode runs the simulator with D-pad buttons enabled, in landscape orientation with a screen resolution of 320 x 240. Portrait mode also runs the simulator with D-pad buttons, but in portrait orientation with a screen resolution of 240 x 320.

The following Start menu options are available to launch the simulator in these modes.

  • Start > Programs > Windows SideShow > Device Simulator 3.0 > Simulator (Touch mode)

  • Start > Programs > Windows SideShow > Device Simulator 3.0 > Simulator (Landscape mode)

  • Start > Programs > Windows SideShow > Device Simulator 3.0 > Simulator (Portrait mode)

Configuring the Screen Resolution

You can use the following Start menu option to open the configuration file for the touch-mode simulator (TouchSimulator.emulatorconfig):

Start > Programs > Windows SideShow > Device Simulator 3.0 > Simulator (Config)

To adjust the screen size of the touch-mode simulator, edit the height and width in the following <LcdDisplay> section of the configuration file.

<LcdDisplay id="LcdDisplay">
  <Width>320</Width>
  <Height>240</Height>
  <BitsPerPixel>16</BitsPerPixel>
</LcdDisplay>

The maximum screen resolution is 640 x 480 for touch mode.

To adjust the screen resolution of the landscape or portrait simulator, edit ButtonSimulator.emulatorconfig. The landscape and portrait simulators are designed for resolutions of 320 x 240 and 240 x 320, respectively.

Simulator Command-Line Options

The simulator recognizes the following combinations of command-line arguments.

Command Line Description

VirtualSideShow.exe

Loads the default touch-enabled firmware in landscape mode.

VirtualSideShow.exe /portrait

Loads the touch-enabled firmware in portrait mode.

VirtualSideShow.exe /button

Loads the landscape firmware that is not touch-enabled, with the D-pad buttons enabled.

VirtualSideShow.exe /button /portrait

Loads the portrait firmware that is not touch-enabled, with the D-pad buttons enabled.

Command-Line Arguments

The following are arguments that can be specified in one of the previously described recognized combinations of arguments, or in addition to one of the recognized combinations.

  • /load: filename
    Specifies a firmware .dat file or assembly file to load. A single .dat file or multiple assembly files can be loaded. If no /load option is specified, a .dat file is automatically loaded. The file that is loaded is determined by whether the /button and /portrait arguments are specified, as follows.

    Are /button and /portrait specified? .dat file loaded

    neither

    tinyclr_microsoft.dat

    /portrait

    tinyclr_microsoft.dat

    /button

    tinyclr_microsoft_landscape.dat

    /button /portrait

    tinyclr_microsoft_portrait.dat

  • /onclose:[disconnect | uninstall]
    Specifies what to do with the virtual SideShow–compatible device when the simulator exits. The default behavior is to disconnect from the device. Specifying uninstall causes the simulator to uninstall the virtual device on the existing device.
  • /pid:number
    Specifies an instance number to use for this simulator process. The instance number is appended to the application name and to the named pipe that is created to connect to the SideShow driver. To run multiple simulators at the same time, each one must be assigned a different PID. The default PID is 0.

    Note that when the simulators are launched from the Start menu, the touch-mode simulator is launched with a PID of 1, the landscape simulator is launched with PID 2, and the portrait simulator is launched with PID 3. This enables the three simulator modes to be run simultaneously.

  • /button
    Specifies that the simulator should run in D-pad mode. Directional pad buttons will appear in the simulator. This is required to use the button-driven user interface (UI), and will not work properly with touch-driven UI.
  • /portrait
    Specifies that the simulator should run in portrait mode.
  • /config: file_name
    Optional. Specifies the name of an emulator configuration file that has the .emulatorconfig extension. If no /config argument is specified, the simulator uses the ButtonSimulator.emulatorconfig file if the /button argument is specified, and the TouchSimulator.emulatorconfig file if /button is not specified.

Troubleshooting the Simulator

The following are known issues with the simulator.

  • The simulator may not run well on laptops. The simulator run speed is based on the run speed of the CPU, which may vary widely on a laptop that is cycling its CPU based on power settings. Timers are also based on the run speed of the CPU and will not advance evenly when running the simulator.

  • The simulator will fail if it is disabled in Device Manager and then closed. If this occurs, the simulator must be restarted with a different PID.

  • If the simulator is shut down improperly, an error may appear the next time it is run. To fix this problem, run the simulator again.

  • If the Windows SideShow Device SDK for .NET Micro Framework 3.0 is also installed, and the simulator version is incompatible with the version of the Windows SideShow Device SDK, the simulator may display an error or stall on the startup screen. This may occur if an older version of the simulator was installed after you installed the Windows SideShow Device SDK. The following steps fix the problem:

    1. If you have an older version installed, while the older simulator is running, open Device Manager and uninstall the Windows SideShow Simulator driver.

    2. Attempt to run the simulator installed with the Windows SideShow Device SDK 3.0. If an error appears, follow the instructions given.

    3. If errors continue to appear, you may have to reinstall the Windows SideShow Device SDK.

    4. If no error immediately appears but the simulator stalls on the startup screen, open Device Manager and scan for updates to download for the simulator driver.

Changing the Default Language of the Simulator

You can change the language of the simulator by using Control Panel, and following these steps:

  1. Start the simulator.

  2. While the simulator is running, open Windows SideShow in Control Panel, and click the Window SideShow Device Simulator icon or name to change device settings.

  3. In the Change Device Settings dialog box, choose your language from the drop-down list.

  4. Click OK

    The simulator will show the words "Please wait..." or its equivalent in the current UI language.

  5. After the Change Device Settings dialog box is dismissed, and the Windows SideShow Control Panel appears again, but while the Simulator still shows "Please wait...", close the simulator manually.

    The next time you start the simulator, the new language setting takes effect.

Simulator Files

The following are files included with the simulator.

  • Virtualsideshow.exe
    This is the simulator application. When it runs, it displays a window that contains a simulated Windows SideShow–compatible device. It also creates a virtual device that communicates with the SideShow Universal driver over a named pipe. If it is not already installed, the SideShow Universal driver is automatically downloaded from Windows Update the first time the simulator is run.
  • TouchSimulator.emulatorconfig
    This is the configuration file for running the simulator in touch mode. It is an XML file that defines and configures the emulated hardware components that the simulator creates. The file specifies the RAM size, the LCD screen dimensions, and the GPIO pins associated with the SideShow button set. You can edit this file to change LCD screen dimensions.

    The maximum supported resolution for running the simulator in touch mode is 640 x 480.

  • ButtonSimulator.emulatorconfig
    This is the configuration file for running the simulator with D-pad buttons enabled. It is an XML file that defines and configures the emulated hardware components that the simulator creates. The file specifies the RAM size, LCD screen dimensions, and the GPIO pins associated with the SideShow button set. You can edit this file to change LCD screen dimensions. However, the landscape and portrait simulators are intended to be used at 320 x 240 and 240 x 320, respectively.