Using the Windows CE 5.0 DeviceEmulator BSP

The Major Steps
•	PB Developer
o	Install bits
o	Configure & build your OS Design
o	Configure an SDK
o	Configure your Device Emulation device settings
o	Build the SDK
•	App Developer
o	Install the SDK
o	Configure your Device in VS 2005
o	Create a Smart Device Project
o	Deploy the Smart Device Project

PB DEVELOPER

PB DEVELOPER: Install bits

1.	Ensure you have ARMV4I support installed with PB 5.0
2.	Install the DeviceEmulatorBSP.msi onto a PC which has PB 5.0 installed. 

PB DEVELOPER: Configure & build your OS Design

3.	Open PB. You should now see the “Microsoft Device Emulator: ARMV4I” BSP in the catalog view, underneath the “BSPs” folder.

4.	Launch the New Platform Wizard and be sure to select the Microsoft Device Emulator BSP. 

5.	When configuring your OS Design, you should consider the following notes:
a.	For our internal testing, we started with the following:
i.	Selected an Enterprise Web Pad as the initial design template 
ii.	Modified LAN support by removing “Wireless” and anchoring “Wired”:
1.	OS Design View: Your Design Template Name->Communication Services and Networking->Networking – Local Area Network (LAN)
iii.	Added NE2000-Compatible PCMCIA card catalog item
1.	Catalog View: Device Drivers->Networking->Local Area Networking (LAN) devices->NE2000-compatible (PCMCIA card)
b.	For supporting the managed app development experience in VS 2005, SYSGEN_WCELOAD is required 
i.	Catalog View: Core OS->Windows CE Devices->Applications – End User->CAB File Installer/Uninstaller
c.	Adding ActiveSync is optional (SYSGEN_AS_BASE)
d.	To support emulated flash memory, add the following catalog items:
i.	SmartMedia NAND flash driver (SMFlash)
1.	Catalog View: BSP->Microsoft Device Emulator->Storage Drivers->MSFlash Drivers->SmartMedia NAND Flash Driver (SMFLASH)
ii.	Partition Driver 
1.	Catalog View: Core OS->Windows CE Devices->File Systems and Data Store-> Storage Manager->Partition Driver
iii.	FAT File System
1.	Catalog View: Core OS->Windows CE Devices->File Systems and Data Store->Storage Manager->FAT File System

6.	Build your image: Build OS->Sysgen

PB DEVELOPER: Configure an SDK

7.	Platform->SDK->New SDK. Step through the Wizard.

8.	Platform->SDK->Configure SDK. Verify all your settings.

PB DEVELOPER: Configure your Device Emulation device settings

9.	Open a Build Window: Build OS->Open Release Directory

10.	 Make a backup of the following file: %_projectroot%\..\..\ExportSdk.sdkcfg

11.	 Using your favorite editor, open this file (it's simply XML text)

12.	 Decide whether or not your SDK will support custom skins, then copy the appropriate XML snippet below:

a.	Custom Skin: 
If you plan on having the device emulator reference a custom skin, copy the following XML snippet  [Note: Highlighted lines are lines you will be editing shortly]

<PropertyBag NAME="DeviceEmulation">
  <Property NAME="Default Image">1</Property>
  <PropertyBag NAME="1">
    <Property NAME="ImageName"></Property>
    <Property NAME="VMID"></Property>
    <Property NAME="Default Skin">DE 1</Property>
    <Property NAME="Height">480</Property>
    <Property NAME="Width">640</Property>
    <Property NAME="BitDepth">16</Property>
    <Property NAME="Memory">128</Property>
       <Property NAME="Bin Dest">Emulation\nk.bin</Property>
    <Property NAME="Fixed Screen">1</Property>
    <Property NAME="CpuName">ARMV4I</Property>
    <Property NAME="DPIX">96</Property>
    <Property NAME="DPIY">96</Property>
    <Property NAME="SupportRotation">0</Property>
    <Property NAME="Enabled">1</Property>
    <Property NAME="Bin Path" />
    <Property NAME="Ethernet">1</Property>
    <Property NAME="Ports">1</Property>
    <Property NAME="AdditionalParameters"> </Property>
    <PropertyBag NAME="Skins">
      <PropertyBag NAME="DE 1">
        <Property NAME="Display_Name">Device Emulator</Property>
        <Property NAME="Path" />
        <Property NAME="Destination">MySkin\MySkin.xml</Property>
        <Property NAME="DisplayHeight">480</Property>
        <Property NAME="DisplayWidth">640</Property>
      </PropertyBag>
    </PropertyBag>
  </PropertyBag>
</PropertyBag>

b.	No Custom Skin
If you plan on not having the device emulator reference any custom skin, copy the following XML snippet instead:

[Note: Highlighted lines are lines you will be editing shortly]

    <PropertyBag NAME="DeviceEmulation">
        <Property NAME="Default Image">1</Property>
        <PropertyBag NAME="1">
            <Property NAME="ImageName"></Property>
            <Property NAME="VMID"></Property>
            <Property NAME="Default Skin"/>
            <Property NAME="Height">480</Property>
            <Property NAME="Width">640</Property>
            <Property NAME="BitDepth">16</Property>
            <Property NAME="Memory">128</Property>
            <Property NAME="Bin Dest">Emulation\nk.bin</Property>
            <Property NAME="Fixed Screen">1</Property>
            <Property NAME="CpuName">ARMV4I</Property>
            <Property NAME="DPIX">96</Property>
            <Property NAME="DPIY">96</Property>
            <Property NAME="SupportRotation">0</Property>
            <Property NAME="Enabled">1</Property>
            <Property NAME="Bin Path"></Property>
            <Property NAME="Ethernet">1</Property>
            <Property NAME="Ports">1</Property>
         <Property NAME="AdditionalParameters"> </Property>
            <PropertyBag NAME="Skins"/>
        </PropertyBag>
    </PropertyBag>

As you can see, the primary differences between the two snippets are the "Default Skin" property and the "Skins" property bag.

13.	 Paste either snippet into the ExportSdk.sdkcfg file such that the "DeviceEmulation" property bag is a child of the <root> node, i.e. it resides at the same level as the "Emulation" property bag.

14.	 Modify the following individual properties within the "DeviceEmulation" property bag:

a.	ImageName: The display name the app developer will see in the VS IDE
b.	VMID: Uniquely identifies the image via a GUID. Create your own GUID using guidgen.exe or a website such as http://www.guidgen.com/Index.aspx
c.	Height/Width: Form factor size (applicable for images not referencing a skin)
d.	BitDepth: Color-depth
e.	Memory: The RAM size to allocate for the device
f.	DPIX/DPIY: Screen resolution

For those referencing a custom skin, update the following properties under "DeviceEmulation/1/Skins/DE 1" property bags well:

g.	Display_Name: Form factor display name
h.	Destination: A path relative to the SDK install root where the skin's installed XML data file will live
i.	DisplayHeight/DisplayWidth: Form factor dimensions

15.	 Based on whether or not you're supporting custom skins, copy the appropriate XML snippet below:

[Note: Highlighted lines are lines you will be editing shortly]

a.	Custom Skin
If you plan on referencing Skins, then Copy and Paste the following snippet into ExportSdk.sdkcfg such that "Added Files" resides at the same level as the "DeviceEmulation" property bag:

    <PropertyBag NAME="Added Files">
        <PropertyBag NAME="{3B388597-0924-4102-ADFA-2519D2C3E11B}">
            <Property NAME="Source">C:\WINCE500\MyDeviceEmulation\ \ReleaseImage</Property>
            <Property NAME="Destination">Emulation</Property>
            <Property NAME="Subfolders">0</Property>
        </PropertyBag>
        <PropertyBag NAME="{4C76DDF6-B89A-4f63-8FC7-3EE50FC7BF80}">
            <Property NAME="Source">C:\WINCE500\MyDeviceEmulation\ \MyCustomSkin</Property>
            <Property NAME="Destination">MySkin</Property>
            <Property NAME="Subfolders">1</Property>
        </PropertyBag>
    </PropertyBag>

b.	No Custom Skin
If you do not plan on referencing Skins, then Copy and Paste the following snippet into ExportSdk.sdkcfg instead such that "Added Files" resides at the same level as the "DeviceEmulation" property bag:

    <PropertyBag NAME="Added Files">
        <PropertyBag NAME="{3B388597-0924-4102-ADFA-2519D2C3E11B}">
            <Property NAME="Source">C:\WINCE500\MyDeviceEmulation\ \ReleaseImage</Property>
            <Property NAME="Destination">Emulation</Property>
            <Property NAME="Subfolders">0</Property>
        </PropertyBag>
    </PropertyBag>

NOTE: If you've already configured your SDK to add additional files, then your ExportSdk.sdkcfg file should already have this "Added Files" property bag. If so, then merely copy the child property bag(s) above ("{3B388597-0924-4102-ADFA-2519D2C3E11B}" and/or "{4C76DDF6-B89A-4f63-8FC7-3EE50FC7BF80}") and paste within the existing "Added Files" property bag.

16.	 Update properties above:

a.	From the "3B388597-0924-4102-ADFA-2519D2C3E11B" property bag:
i.	Source: The local folder containing your Device Emulation nk.bin file. We recommend this local folder contains nothing other than the final nk.bin, as the SDK Roller will pull in everything that lives in this local folder at build-time.

b.	For those supporting custom skins:
From the "4C76DDF6-B89A-4f63-8FC7-3EE50FC7BF80" property bag:
i.	Source: The local folder containing your skin files and subfolders, including the XML data file describing the skin. 
ii.	Destination: A path relative to the SDK install root where the skin files and subfolders will get installed. Should correspond to the value of the Destination property in the "DeviceEmulation/1/Skins/DE 1" property bag

17.	 Save the ExportSdk.sdkcfg file.

PB DEVELOPER: Build the SDK

18.	 To build the SDK, either:
a.	Invoke from PB: Platform->SDK->Build SDK  
b.	Invoke from the command-line: <PBInstallFolder>\cepb\bin\buildsdk.exe %path_to_workspace_pbxml_file%

App developer

App-developer: Install the SDK

19.	 Install the SDK onto a machine w/ VS 2005.

App-developer: Configure your Device in VS 2005

20.	 Launch VS 2005. 

21.	 Goto Tools->Options. Expand the “Device Tools” node on left and select “Devices”:

22.	 Select your platform and then the device matching the name you had configured and hit Properties.

23.	 You’ll now see Emulator Properties dialog. Verify that the "Transport" field is set to DMA Transport. 

24.	 Click on "Emulator Options" button.

25.	In the popup, select the Display tab:

a.	If you had chosen to include a custom skin:
i.	Verify that you see the Skin radio button selected and the path to the skin file is correct.
 
b.	If you had NOT chosen to include a custom skin:
i.	Select the Video setting and review your video settings. 

NOTE: This latter case is a workaround to a bug in Visual Studio 2005 in which SDKs that do not provide skins are broken.

26.	Click OK to dismiss the Emulator Options dialog

27.	 Click OK to dismiss the Emulator Properties dialog. 

28.	 Click OK to dismiss the Tools->Options dialog.

App-developer: Create a Smart Device Project

29.	 Create a new Smart Device app. If you’re creating a native app, be sure to select the target SDK in the New VC++ Smart Device Project Wizard. 

30.	 Once project is loaded, verify the target device drop down box contains your target DeviceEmulator:

App-developer: Deploy the Smart Device Project

31.	 Verify you’ve selected your Device Emulator in the Target Device drop down. Click the “Connect to Device” button next to this Target Device drop down box. 

32.	 The Device Emulator will launch. It may take 1-2 minutes for the device’s desktop to load.

33.	 You may also hit F5. This will actually download your app, launch your app, and connect the app debugger.

For additional information on debugging on the Device Emulator, refer to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnppcgen/html/Device_Debug_VS2005.asp