With the exponential growth of Windows Embedded Compact 7 kernel images unfortunately also the build time grows exponentially. I have always used VMWare Workstation to keep my Windows CE build environments separate (as side-by-side installations are not supported). Unfortunately, with WEC7 it felt like being back in Windows CE 3.0 days... In those days it was not the size of the kernel causing clean sysgen's to take over 40 minutes to build but it was slow hardware. I've always been able to keep build times below 25 minutes using VMWare and fast hardware, but with WEC7 this proved impossible. On my Core I5 2.6 Ghz with 16 MB DDR3 memory and a 7200 rpm SATA3 disk a WEC7 build inside a VM running Win7 took over 50 minutes!

To speed up the builds I have now invested in a separate laptop, configured specifically to build WEC7 kernels. It's an ASUS N55SF with an Intel® Core™ i7 2670QM/2630QM Processor, 6M cache, 4 cores/8 threads, 3.1 GHz and 8 GB DDR3 memory.

As you may know, processor speed is only one part of the equation with the other big factor being disk speed. I therefore invested in one of the fastest SSD's available at the moment: the OCZ Vertex 4: SATA 3, 6 GB/s, 2.5" SSD with a max of 120k IOPS and 550 MB/s read and 475 MB/s write speed. I chose the 512 GB version as it is the fastest and with the huge kernels and installation size of WEC7 you simply need the space.

Even with this hardware running a VMWare Win7 image a build still took 25 minutes; quite an improvement from the >50 minute builds on my Core I5 with 7200 rpm SATA 3 disk but still too long. I then decided to ditch VMWare and try a native install with the OS on the SSD, together with VS2K5 and WEC7 Platform Builder.

After speeding up the build system using the method described in this blog post, my builds are now 9 minutes for a reasonably feature rich WEC7 kernel (and <5 minutes for small headless kernels). Finally we're back in the 21st century again! It sure took some time and money to speed up WEC7 builds but if you are building a lot of kernels the investment will pay itself off after a couple of weeks!

Here's the full specification (of all components relating to build speed):

• Intel® Core™ i7-2670QM Processor (6M Cache, up to 3.10 GHz)

Room for improvement here if you go for a desktop system.

• DDR3 1333 MHz SDRAM

Room for improvement here if you go for a desktop system.

• 512 GB OCZ Vertex 4: SATA 3, 6 GB/s, 2.5" SSD

The Patriot Wildfire is the fastest according to passmark.com but the OCZ Vetex 4 is unbeatable in price/performance.

• OS: Windows 7 64 bit

Unfortunately side-by-side installation of Windows CE 6.0 and WEC7 is not supported, but I'd love to see how fast a CE 6.0 kernel will build on this machine... Under a minute?

Conclusion:

When building kernels with WEC7 it's worth to fork out some cash to speed up the builds if you are building lots of kernels (or if you just don't want to drink so much coffee on a day ;)

PS: All build times are Debug OS Designs, with shell and built with blddemo clean -q

We've just released a major upgrade to the Topaz BSP. The main feature we added in this release is support for a boot splash screen. Due to the changes in memory layout you will need to install the new Topaz Flasher and this new Topaz Flasher can not be used with Topaz releases older than r676.

Here's the changelist:

CE 6.0 R3 Release 676

• Changed version number and product name of Topaz SDK
• Updated FlexCAN driver source
• Now turning backlight off after 10 minutes (instead of 1 minute)
• Fixed serial debug redirection in bootloader (now works)
• Added boot splash screen support from NAND and SD
• Added registry setting so NETUI times out quicker on headless configurations

Get Topaz Release r676 now!

Note that the latest release can always be found at this link: http://guruce.com/topaz/release/latest

We've just release a new version of the Topaz Binary BSP, Image Binaries and SDK containing some bug fixes and improvements to the BSP.

Get Topaz Release r589 now!

Note that the latest release can always be found at this link: http://guruce.com/topaz/release/latest

Recently I had to add Bluetooth support to a custom board running Windows Embedded Compact 7. The Bluetooth module was CSR compatible connected to UART2. To enable the driver for this module you'll have to add the following registry settings to platform.reg:

You'll have to adjust the baudrate and COM port to match your configuration. The Bluetooth universal loader (SYSGEN_BTH) first looks for PnP devices (like USB/SDIO) and if it can't find any of those it will look for devices listed in the above Bluetooth\Transports\BuiltIn key in the order they are listed.

When I first added support for Bluetooth I just clicked all of the available items in the catalog:

• Bluetooth Profile Management APIs (SYSGEN_BTH_BTHUTIL)
• Bluetooth Stack with Universal Loadable Driver (SYSGEN_BTH)
• Bluetooth HID - Keyboard (SYSGEN_BTH_HID_KEYBOARD)
• Bluetooth HID - Mouse (SYSGEN_BTH_HID_MOUSE)
• Bluetooth HS/HF and Audio Gateway Service (SYSGEN_BTH_AG)
• Bluetooth PAN (SYSGEN_BTH_PAN)
• Bluetooth Settings UI (SYSGEN_BTH_SETTINGS)

After rebuilding the OS Design the universal loader just did not want to load the driver I specified under the Bluetooth\Transports\BuiltIn key. Without (premium shared) source code of the universal loader it was very difficult to find out what was going wrong. All I could go on was the debug messages outputted by the Bluetooth Module, which I enabled by adding this key to the device's registry (in OSDesign.reg):

Unfortunately the debug messages did not give any clue as to why it did not want to load the driver I specified. In the end I decided to just select the Universal Loadable Driver (SYSGEN_BTH) in the catalog and deselect everything else, just to get rid of all other unrelated Bluetooth messages. To my surprise all of a sudden the driver did load!

I copied the reginit.ini from the release folder to a temporary folder, selected all Bluetooth components again and rebuilt the kernel. I then compared the reginit.ini of the kernel with only the universal loader component selected with the reginit of the kernel with all Bluetooth components selected. That way I discovered the culprit component was the Bluetooth Profile Management APIs (SYSGEN_BTH_BTHUTIL) component.

This component adds the following registry settings:

This disables the radio by default, hence the driver did not load.

So, when you want to enable Bluetooth at boot and you include the Bluetooth Profile Management APIs component, you'll have to override these registry values either inside platform.reg or OSDesign.reg:

When I tried WEDU (the Windows Embedded Developer Update) I was never able to get past the pages where you have to register. After some back and forth with Microsoft it seems you HAVE to select "Yes, I agree" to the question "Do you agree that a Windows Embedded representative may contact you using the phone number or email address provided by you to supply further Windows Embedded Information", even though the options are "Please select from the Following Options", "Yes, I agree" and "No, I do not agree":

See also this forum post.

Initially I selected "No, I do not agree" because I do not want any unsolicited calls from Microsoft or one of my competitors ;). When you select that option WEDU does not throw any warning message, nothing in red, it just simply loops back to the registration page until you select "Yes, I agree".

I think this can be classified as a bug...

So, if you also encounter the WEDU endless registration loop problem; select "Yes, I agree" and say "No, I do not agree" out loud when you select it. That'll do it! :P

UPDATE: If that did not do the trick, you may set the following registry value on your development PC to bypass WEDU registration alltogether:

Many thanks to Michael Koster for that tip!

In the previous 2 articles (this and this one) I showed you how to create .NET C# based client applications consuming a webservice running on a Windows Embedded Compact device. In this blog post I will show you how to do the same, but then with a client application running on Windows Phone 7.5!

Convert RPC/encoded to RPC/literal

When you try to use the existing wsdl file in a silverlight solution for WP7 you won't be able to use the operations as described. It seems that the silverlight version doesn't support RPC/encoded soap and ignores those operations. It does support RPC/Literal soap style so we need to change the style from RPC/encoded to RPC/literal. This is actually really easy: Open the wsdl file and modify the input and output operations from

<soap:body use="encoded" ..../>

to

<soap:body use="literal" ..../>.

In XMLSpy:

You can see that the HelloWorld_Binding, the middle part, has changed. The input and output body styles have been modified from encoded to literal. That's basically all you need to change. This change in the wsdl file requires us to modify and rebuild the server and client code. Let's start with the server side.

Rebuild HelloWorldWebService solution

Open the existing "HelloWorldWebService.sln" solution we created in the previous blog post.

1. Right-click the wsdl file and choose “compile”.
2. Now recompile our (regenerated) header file: Right-click on the HelloWsdl.h file and choose "compile". This will re-generate a bunch of files as well.
3. Finally; build the solution...

Oops! Unresolved externals... The reason for these is that we changed the message style and therefore we need to construct (or actually gSOAP needs to construct) the soap message slightly different.

In the HelloWorldWebservice solution open HelloWsdlMethods.cpp and modify the content to match the following:

I commented the original code and added new code to emphasize the code differences.

Windows Phone 7.5 (Mango) Client application

Now lets create a Windows Phone 7.5 client application. Make sure you have the Windows Phone SDK 7.1 installed. You need this to build applications for WP7/7.5.

Open Visual Studio 2010 Express for Windows Phone and create a new application (File | New Project). In the C# section "Silverlight for Windows Phone" choose "Windows Phone Application":

Choose TestWebServiceWP7 as the solution name and leave the other options as is. Select "OK" to create the solution.
I'll leave the sample as simple as possible just to illustrate how to consume a webservice running on a Windows Embedded Compact device. Drag 2 buttons on the content panel. Name the first button "Test" and the other "UploadImage". Something like:

Double-click the test button so we can enter the code behind. First thing we need to do is add our (Web)Service reference. In the solution explorer right click on the "Service Reference" and choose "Add Service Reference". Select HelloWsdl, created in the beginning of this article. You should be seeing something like:

As you can see I named the service "HelloWsdlService". Click "OK" to add the web service to our solution. Add the following code to complete the Test button implementation:

As you can see I create the service class and the event handler which handles the HelloWorldOperation asynchroneously in the constructor. The button test code (Test_Click) calls HelloWorldOperation. Deploy your solution to either the WP7 emulator or to your Windows Phone device. Run the webservice code on the Topaz (as describer in the other articles) and run the application on the WP7 emulator or device.

To illustrate the complete solution check out this video showing me uploading and running the Windows Phone 7 application and the webservice on the Topaz. It is a recording of my desktop (I am using Cerdisp and Cerhost as an RDP solution to show the desktop of the Windows Embedded Compact device):

[video:www.youtube.com/watch?v=vhPtS-SmkB4 width:640 height:385 ratio:16/9]

If you have any questions please leave a comment below!

[UPDATE: This issue has been resolved through the "Offline Layout" feature]

Microsoft changed the update mechanisms in the new version of Windows CE; Windows Embedded Compact 7. The update mechanism definitely needed an update, but in my humble opinion Microsoft made it worse instead of better...

We now have WEDU, the Windows Embedded Developer Update, a great idea if it would work. WEDU simply does not work inside a VMWare virtual machine and even if it works it always downloads the updates without a possibility to install from previously downloaded update packages.

That doesn't really matter if you have only 1 installation to keep updated, but what if you have multiple? Downloading gigabytes of data multiple times might not be time consuming or costing a lot of money in places where internet is fast and uncapped, but here in NZ internet is slow, expensive and capped so I really only want to download once and install often (see also this and this post).

If you have access to the Mobile & Embedded Communications Extranet (ECE) you can download most updates in img format, but unfortunately not all updates include all files needed and thus they are still web installers.

Luckily there are ways to reconstruct web installers so that you only have to download once and install (offline) often.

As an example we'll take the Windows Embedded Compact 7 Monthly Update July 2011:

1. Download WindowsEmbeddedCompact7.exe
2. Delete all subfolders under C:\Documents and Settings\All Users\Application Data\PkgCache
3. Run the update
4. When asked for a location for the files, click the box "Allow downloading for all files" and the click button "Download"
   NB: Everything from the OS, CTK and PB locations (see tree structure below) can be copied directly from the original WEC7 DVDs or you can point the installer to the DVD
5. Once the download is finished you'll find the downloaded files in a GUID named subfolder of the PkgCache folder (full path above)
6. Copy the downloaded files to a subfolder named "1" in the folder you placed WindowsEmbeddedCompact7.exe
7. Continue the installation (NOTE: Do NOT exit the installation at any time before you have copied the files from the PkgCache folder! When you exit the update application ALL downloaded files will be deleted!)
8. Repeat the steps above and increase the number of the subfolder you copy the files in for every component downloaded
9. Once all components are downloaded and copied, exit the update application before it starts installing
10. Restart the update application
11. It will ask again for the missing files. Take note of the path it is showing in the box, for instance: [.]\OS\Common\Common.msi (for Architecture Common files)
12. Rename the subfolder to match the expected location. So if you copied the common architecture update files into subfolder "4" you recreate the expected location (".\OS\Common") and move the files there
13. Do this for all components and press OK
14. The installer should then find the files and check if they are correct
15. If all the files are in their correct places the installer does not show a download dialog anymore but instead will directly show a "Begin Install" window
16. You can now run the installer for multiple (offline) installations

For reference, this is the entire directory tree required for offline installation of the July 2011 WEC7 update:

(***) This folder and all subfolders are copied from original WEC7 DVDs. You can also just point the installer to the DVD when asked for these files.

By popular demand here's a simple example how to upload a file using a gSOAP webservice. This is a follow up post; for this example you first need to read and implement the code from the first post in this series.

With the base code of the first post it is now very simple to extend that solution's functionality because we've already completed the most difficult part; setting up your solution.

In this follow up blog post I will create a method that allows you to upload a file to the Topaz target:

int UploadResource(String resourceName, byte[] resource, uint resourceId, uint &statusCode);

First we need to modify the existing wsdl file (our webservice design). I won't list the entire wsdl file here because it's getting a bit long. Instead I have downloaded a tool that allows me to graphically design my wsdl file; Altova XML spy. Altova XML spy is not a free tool but it is very nice to work with it. There may be some free tools that offer the same functionality as well (let me know if you find one). I opened the wsdl file we created in the previous blog post in this series and opened it in XML spy for modification. After modification it looks like this:

Note the port type "UploadResource" I added (left block under HelloWorld_PortType). I added the input parameters resourceName (String), resourceId (unsinged integer) and a byte buffer for the actual data (base64Binary). I also added an output parameter statusCode. In the code I am not doing anything with it, but I just put it there to illustrate an output parameter. To complete the wsdl design we need to add the encodingStyle and namespace fields for the binding (the middle part of the picture). Just copy'n'paste it from the HelloWorldOperation. For complete reference I've attached the wsdl file to this blog post. It's a good example how to construct your webservice interface. It also shows a wsdl file can get complicated very quickly so a design tool like the one I used is recommended.

Open the existing "HelloWorldWebService" solution we created in the previous blog post. You're now just a few simple steps away from finishing the server side code:

1). Right click the wsdl file and choose “Compile”. Now our header (HelloWsdl.h2). Right click on the HelloWsdl.h file and choose "compile". Again this will re-generate a bunch of files as well.

If you would now build your solution you will end up with some unresolved externals; our newly created method. You can find the declaration of this new method in the generated soapStub.h file:

Open HelloWsdlMethods.cpp and add the following method implementation:

Don't let the xsd__base64Binary type scare you. It's just a class with some members including:
__ptr: A character pointer to the memory buffer (char* buf) containing the contents of the file.
_size: Contains the number of bytes in the buffer above.

4). Build your solution and run the server code on your Topaz!

The C# Managed Client

In the previous blog post in this series we've created a Testclient application written in C# to test our webservice. Open the "TestWebServiceClient" solution. Add an OpenFileDialog control and a button control to the Form. Call the button something like UploadFile:

Double click on the newly added button which will create the button click event code behind. Now implement the event handler with the following content:

Of course this is just a sample and you should take of security and parameter checking. In this sample I have left this stuff out just to keep it as simple as possible.

When you run the HelloWorldWebservice on the target device and run the C# Client sample on your pc, a file open dialog will appear when you click on the "Upload File" button. Select a file (I just selected desktop.ini) and it will upload the contents of that file to the webservice on the target.

If you implemented everything correctly you should be seeing the following output on the target:

That's it!

To recap: To modify or extend your webservice, create/modify the wsdl. Compile the wsdl file, compile the header file. Implement the native webservice. When that's done, modify your client by refreshing the imported wsdl file and you can call your new webservice.

Happy 2012 to all our readers!

Since we included our iMX FlexCAN driver in the iMX25 Topaz image binaries we have received a couple of requests for sample code, so here it is:

The code above is using our standard FlexCAN driver functionality and uses our (free downloadable) debug message templates for debug logging. Our High Performance FlexCAN driver supports complex ID filtering setups and a high speed (virtually unlimited) receive FIFO, among many more features.

If you develop drivers for Windows CE or Embedded Compact you know it is a major PITA to have to reload the entire kernel every time you change something in the driver code. You need to do this even in a debug kernel because the driver binaries are in use (and thus you can't re-compile & link) when the driver is loaded.

To workaround this I created a tool that allows you to unload or (re)load a driver at runtime. The way I use it is as follows:

1. I build a small debug kernel including the driver under development
2. I add the driver dll to the list of modules that will be loaded from the Release Directory (in VS2K5 with PB go to menu "Target"->"Release Directory Modules..." and add the driver)
3. I add my tool (see below) as a subproject to the OS Design

Now when I download the kernel the driver will load (if the correct Drivers\BuiltIn registry values are there of course). I can set breakpoints in and step through my driver code, etc. Now when I find a bug I just press F5 to continue execution, open a "Target Control" window (menu Target->Target Control) and use my tool to unload the driver, then fix the bug, recompile & link and then (re)load the driver without the need for rebuilding or even reloading the kernel:

reloaddrv [-u] drv1: [[-u] drv2: {etc}]

In Target Control you use the 's' command to start an executable: s reloaddrv -u drv1:

The drv1: is the name of your driver (a 3 letter prefix followed by an index and a colon). Make sure to specify the -u (unload) parameter before the driver name!

To just reload the driver (so a quick unload followed immediately by a load; great for debugging initialization and clean-up) you use the tool as follows: s reloaddrv drv1:

If the driver was not loaded when you executed the above command the tool will try to find the BuiltIn registry key for the driver and load it from there.

You can specify multiple drivers on the commandline as well (-u always applies to the driver directly following it): s reloaddrv -u drv1: -u drv2: drv3: -u drv4: drv5: drv6:

I'm sure this tool is useful to a lot of you developing drivers for Windows CE/Embedded Compact, so here it is:

And for your convenience here's the tool 7-zipped up as an OS Design subproject: reloaddrv.7z

In this blog post I will show you how you can customize all Windows CE dialogs without the need to change ANY file in the PUBLIC tree. As you no doubt know changing any code in the Windows CE PUBLIC (& PRIVATE) tree is a bad idea. It is a bad idea because it is very hard to maintain, your changes may be overwritten at any time by a Windows CE Update and worst of all your changes affect ALL OS Designs (not just the OS Design you need the changes for). Besides that you often need to do a "Build & Sysgen" to get your changes into your kernel image and we all know you should NEVER EVER do a "Build & Sysgen".

However, MSDN is still full of articles with instructions telling you to change code in the PUBLIC tree. An example of this is the "Customizing a UI Component" article in MSDN. It talks about modifying files in %_WINCEROOT%\Public\Common\Oak\Drivers and changing \WINCE600\PUBLIC\CEBASE\OAK\MISC\Winceos.bat... Bad, bad, bad!

Time for an update on this article:

Customizing a UI Component

To suit the requirements of your target device, Windows CE allows you to customize and replace certain user interface (UI) components. Windows CE provides these UI components in the form of libraries that you can either use as supplied or replace with your own custom UI components. The following table shows these UI components.

For detailed instructions on how to clone Calibrui please see Cloning CalibrUi in Windows CE 6.0. This article deals with STARTUI and OOMUI

To customize a UI component, we first need to clone the component into our OS Design and change it so that the build system uses our cloned binaries when linking GWES. We'll take STARTUI as an example for this exercise:

1. Copy \WINCE600\PUBLIC\COMMON\OAK\DRIVERS\STARTUI to \WINCE600\OSDesigns\YourOSDesign\YourOSDesign\STARTUI
2. Open the 'sources.' file in \WINCE600\OSDesigns\YourOSDesign\YourOSDesign\STARTUI and add the following to the top of the file (right under the !endif):
_OEMINCPATH=$(_WINCEROOT)\public\common\ddk\inc;$(_WINCEROOT)\public\common\oak\inc;$(_WINCEROOT)\public\common\sdk\inc;
__PROJROOT=$(_PROJECTROOT)
_COMMONPUBROOT=$(_WINCEROOT)\public\common

WINCEOEM=1
PBP_PRESYSGEN=1

3. Append '_clone' to the TARGETNAME:

TARGETNAME=startui_clone

4. Add RELEASETYPE and TARGET_PDB_NAME under TARGETTYPE=LIBRARY:
RELEASETYPE=OAK
TARGET_PDB_NAME=$(_RELEASELIBDIR)\$(TARGETNAME).pdb
5. Remove the INCLUDES. In this case nothing is included from ..\..\inc but if it would be we would have to include the correct absolute path to the required include files.
6. Remove any #xref lines (not used anymore since CE 2.12)

The final sources file should look something like this:

_OEMINCPATH=$(_WINCEROOT)\public\common\ddk\inc;$(_WINCEROOT)\public\common\oak\inc;$(_WINCEROOT)\public\common\sdk\inc;
__PROJROOT=$(_PROJECTROOT)
_COMMONPUBROOT=$(_WINCEROOT)\public\common

WINCEOEM=1
PBP_PRESYSGEN=1

TARGETNAME=startui_clone
TARGETTYPE=LIBRARY
RELEASETYPE=OAK
TARGET_PDB_NAME=$(_RELEASELIBDIR)\$(TARGETNAME).pdb

MODULES=gwes
CDEFINES= $(CDEFINES) -D__USERDECL_H__ -D__PRIVDECL_H__ -DGWE

!IFDEF MEM_ACCOUNT
CDEFINES=$(CDEFINES) -DMEM_ACCOUNT=1
!ENDIF

WINCETARGETFILES= \
  $(_COMMONOAKROOT)\lib\$(_CPUINDPATH)\$(TARGETNAME).res \
 
SOURCES=startui.cpp                

7. Now add this project to your OS Design's subprojects

by right clicking the "SubProjects" node in the Solution Explorer and choosing "Add existing subproject...". Then browse to the STARTUI folder in your OS Design folder and be sure to select "Sources/Dirs Files (sources;dirs)" in the "Files of type" drop down list to be able to select the STARTUI sources. file.

This action creates several files and adds several lines to our sources file that we do not need...

8. From the Solution Explorer select all the files in the "Parameter Files" node (ProjSysgen.bat, STARTUI.bib, .dat, .db & .reg) of the STARTUI subproject, right click and "Remove and delete" them.
9. If you want you can add "startui.rc" and "windowsce.bmp" to the "Resource Files" node in the subproject (but it is not necessary for building).
10. Now we need to tell Platform Builder that this component needs to built before we sysgen the common tree so GWES can link our binaries instead of the default ones. We do this by editing the STARTUI.pbpxml file. Make sure the STARTUI.pbpxml file is as follows:
    
    <?xml version="1.0"?>
    <PBProject DisplayName="STARTUI (clone)" SysgenDeptree="common" SysgenModule="gwe2" xmlns="urn:PBProject-schema" />

    I added "(clone)" to the display name just to make clear this is a cloned component; it is not necessary for building. SysgenDeptree tells Platfom Builder this needs to be built before sysgenning the common dependency tree and SysgenModule specifies the module this component needs to be linked with.

11. Since we named our project STARTUI_clone we need to rename the startui.rc file to startui_clone.rc (in preparation for the step below).
12. The final step involves building the resources for all possible locales. The script used was taken from the Calibrui clone operation described in Cloning CalibrUi in Windows CE 6.0. The only thing added is setting the INCLUDE environment variable so that windows.h can be found by the resource compiler (startui_clone.rc needs windows.h). Copy the following into the prelink.bat file:
    
    @echo off
    @REM This is called before build to create all the RES files needed for all locales
    @REM WARNING: Do not change the names of any files because SYSGENMAKE.EXE assumes their location for cloning
    (IF NOT EXIST obj mkdir obj || goto EXIT_ERROR
    (IF NOT EXIST obj\%_TGTCPU% mkdir obj\%_TGTCPU%) || goto EXIT_ERROR
    (IF NOT EXIST obj\%_TGTCPU%\%WINCEDEBUG% mkdir obj\%_TGTCPU%\%WINCEDEBUG%) || goto EXIT_ERROR

    dir /AD /B %_PUBLICROOT%\COMMON\OAK\LIB\%_TGTCPU%\%WINCEDEBUG% > obj\%_TGTCPU%\%WINCEDEBUG%\clone_locales.txt

    set INCLUDE=%_WINCEROOT%\public\common\sdk\inc;
    set _PRELINK_LOCALE=%LOCALE%
    for /f %%L in (obj\%_TGTCPU%\%WINCEDEBUG%\clone_locales.txt) do call :COMPILE_RC %%L
    set LOCALE=%_PRELINK_LOCALE%
    goto :END_CLONING

    :COMPILE_RC
    (set LOCALE=%1 && nmake startui_clone.res) || goto EXIT_ERROR
    (IF NOT EXIST obj\%_TGTCPU%\%WINCEDEBUG%\%1 mkdir obj\%_TGTCPU%\%WINCEDEBUG%\%1) || goto EXIT_ERROR
    move /Y startui_clone.res obj\%_TGTCPU%\%WINCEDEBUG%\%1\startui_clone.res || goto EXIT_ERROR
    goto EOF

    :EXIT_ERROR
    exit /b -1

    :END_CLONING
    @REM Place any additional steps after END_CLONING but before EOF
    :EOF

That's it! You can now modify the STARTUI sources and build (sysgen) your OS Design to see your changes included in GWES, all without modifying one single file in the PUBLIC tree. The same instructions can be used to clone and modify OOMUI (the "out of memory" dialogs).

Good luck!

Windows CE supports a hardware watchdog implementation. The watchdog's properties can be set through two exported kernel variables; dwOEMWatchDogPeriod (to set the period in ms between feeding the dog) and dwNKWatchDogThreadPriority (to set the priority of the watchdog thread).

Unfortunately, dwNKWatchDogThreadPriority is not defined... Looks like somebody at Microsoft made a typo; the name of the exported variable is dwdwNKWatchDogThreadPriority (note the double 'dw').

Here's some example code to setup the watchdog:

Of course WatchdogInit and WatchdogFeed are functions implemented to initialize and feed your hardware watchdog.

Since the change to Silverlight/Bing on Microsoft downloads, the download search has become completely useless (for fun, try searching for "CE 6.0", then try "CE") [Update: MS seems to have fixed the search phrase problems, so "CE" and "CE 6.0" now return the correct results. Nevertheless; the remainder of this blog post is still valid]. Therefore the links in this post do not work anymore and an update is needed.

All Windows Embedded Compact 7 / Windows Embedded CE 6.0 / Windows Embedded CE 5.0 / Windows CE.NET 4.2 / Windows CE 3.0 (you can leave it to MS marketing to make product naming as confusing as possible...) updates can be found at these links:

Windows Embedded Compact 7
Windows Embedded CE 6.0
Windows Embedded CE 5.0
Windows CE .NET 4.2
Windows CE 3.0

You can still download the QFEInstaller so you don't have to click the QFE installation wizard a million times, but nowadays the msi installers support silent installation through commandline options as well. The QFEInstaller is still handy because it makes sure the QFE's are installed in the right order.

Today GuruCE released the first version of the Topaz iMX25 Windows Embedded Compact 7 BSP and image binaries and a new release of the CE 6.0 R3 BSP and image binaries.

Release notes and the latest revision can be downloaded here.

We've also released a new version of the Topaz Flasher.

When you modify something small in your BSP's code and parameter files (like platform.reg) and want to build it, the right way is to right click your BSP and select "Build and Sysgen" (note that this is NOT the demonic Build and Sysgen variant; this merely results in a cebuild -qbsp).

(for a more in depth discussion of what to build when click here)

The downside of this is that if you happened to have just changed your build configuration from RELEASE to DEBUG (or vice-versa), the build system will rebuild all of the SOC folders in the platform common folder.

The default installation of Windows Embedded Compact 7 comes with 7 SOC folders and rebuilding all of these is completely useless and a waste of time (since your BSP only uses 1 SOC folder, if any at all!).

Luckily, we can let the build system know we only want to build the SOC folders we really need by utilizing "OPTIONAL_DIRS".

Here's how:

1. Change "DIRS=*" in \WINCE700\PLATFORM\common\src\SOC\dirs. to "OPTIONAL_DIRS=*"
2. Add "set BUILD_OPTIONS=socdir1 socdir2" to your BSP batch file in \WINCE700\PLATFORM\YourBSP\YourBSP.bat (and set the socdir's to the correct foldernames you want to build separated by a space if you want to build more than 1, eg. "set BUILD_OPTIONS=x86_ms_v1")

That's it! A very quick and easy way to speed up your targeted builds.

PS. This also works for CE 6.0 and WEC2013!

By now, all of you reading this blog should know that you should NEVER EVER DO A BUILD AND SYSGEN (a "blddemo" without "-q") on your build tree.

The reason for this is that this command will try to rebuild the entire tree which (besides taking forever!) will overwrite binaries that may have been updated through QFE's and will result in errors because Microsoft does not supply all of the source code required to rebuild everything. Executing this command will lead to a corrupted build tree for which the only resolution is to do a complete re-install of Windows Embedded Compact 7. The "(Re)Build and sysgen" commands are only useful for people who have full source code: The Microsoft Windows Embedded Compact Development Team (even with premium shared source you don't get a full 100% of source code!).

This has always been an issue, ever since the invention of Windows CE (now known as Windows Embedded Compact).

Despite years and years of lobbying by many MVPs (including myself) with Microsoft they simply refuse to remove these demonic commands from the build menu. In previous versions of Windows CE it was very simple to remove these commands from the build menu (to prevent accidental clicking of these commands). Unfortunately, things have become worse in Platform Builder for Windows Embedded Compact 7. As in the previous version of Windows CE (6.0 R3) the "(Re)Build and Sysgen" commands are in the "Advanced Build" menu. In the previous version of CE you would simply "Customize" the toolbar and remove the "Build and Sysgen" commands from the "Advanced Build" menu. Not anymore... For some strange reason the "Advanced Build Commands" submenu now shows "(Advanced command placeholder)" when in "Customize-mode" and deleting individual commands is no longer possible:

So, what to do? Deleting the whole "Advanced Build Commands" menu seems a bit rigorous, especially since it does contain some very useful commands (like "Clean sysgen" and "Build Current BSP and Subprojects" etc.). All of these commands are also available by right clicking the correct nodes in the Solution Explorer, but still, it's nice to have them handy in the "Advanced Build Commands" menu as well.

Luckily, Platform Builder for Windows Embedded Compact 7 introduces a new feature; Custom Build Commands.

Using Custom Build Commands we can re-create the non-demonic commands from the "Advance Build Commands" menu and omit the demonic commands. That way we can safely delete the entire "Advanced Build Commands" menu, so let's start with that:

1. Click "Customize..." in the "Tools" menu
2. Click the "Build" menu
3. Right click the "Advanced Build Commands" submenu
4. Choose "Delete" from the context menu
5. and finally close the "Customize" dialog

We can now add the useful commands back as custom build commands:

1. Click "Options..." from the "Tools" menu
2. Open the node "Platform Builder -> OS Design and Build -> Build Commands"
3. Click on the "Add" button in the "Custom build commands" section
4. Add the following commands:
• Sysgen (blddemo -q)    blddemo -q
• Clean Sysgen (blddemo clean -q)    blddemo clean -q
• Build Current BSP and Subprojects (blddemo -qbsp)    blddemo -qbsp
• Rebuild Current BSP and Subprojects (blddemo -c -qbsp)    blddemo -c -qbsp

Now click OK and see the magic in your "Build" menu:

In this blog post I'd like to discuss how to host webservices on a Windows Embedded Compact device. You can certainly consume webservices on a smart device using managed code, but hosting a webservice on the device is unfortunately not possible using managed code. So it's back to good old native code again!

I will use gSOAP, a third party framework, that will do most of the nitty gritty work for us. Sounds easy right? Let's get started!

The most important part is the WSDL (Web Services Description Language) file. The WSDL file is an XML document that describes the interface and thus which methods we want to expose and host on our device. I won't spend much time explaining the WSDL syntax as there are lots of online WSDL tutorials available that explain the syntax much better than I ever could.

For now I just created a very simple WSDL file that describes one very simple webservice method: string HelloWorld(string name)

The wsdl:

As you can see there are 6 main tags in the WSDL within the mandatory <definition></definition> tags:

types

Provides data type(s) used for the method parameters and return values.

message

Represents an abstract definition of the data being transmitted. A message consists of logical parts, each of which is associated with a definition within some type system.

portType

A set of abstract operations. Each operation refers to an input message and output messages.

binding

Specifies concrete protocol and data format specifications for the operations and messages defined by a particular portType.

port

Specifies an address for a binding, thus defining a single communication endpoint.

service

Used to aggregate a set of related ports and to set the network location of the actual service.

Basically Type, Message and portType describe the webservice methods used and binding, port and service describe how to transfer the data over the socket.

The location contains the IP address or hostname of the target that runs the server hosting the webservice. In this example I use a Topaz device (you would normally set this to the IP address or hostname assigned to your device).

After this very brief WSDL description let's set up our Visual Studio 2008 project. This will be the biggest task.

Before we can create the actual VS2008 project we need to perform a couple of steps (described in more detail below):

1. Import the WSDL in an emtpy project
2. Let gSOAP generate a header file via wsdl2header.exe
3. Let gSOAP generate the corresponding implementation *.cpp file
4. Implement our methods

Because gSOAP generates a lot files I prefer to separate the generated files from the actual implementation files so that you only have to focus on your implementation and not what is being generated by gSOAP. So let’s begin and create an empty project in Visual Studio 2008 and add the WSDL file.

Step 1: Import the WSDL in an empty project

Open Visual Studio and create a new C++ smart device project (File menu | New | Project) and enter HelloWorldWebService as the name of the solution.

Select Ok, and click next on the "Welcome to the Win32 Smart Device Project Wizard" dialog. In the "platforms" dialog select the SDK for your target device. As you can see I chose the Topaz device (http://guruce.com/topaz). Select next:

In the "project setttings" dialog select "console application" and "empty project" and click finish.

When the solution is created, go to the solution explorer (normally this would be visible by default but if not: go to View | Solution Explorer) and add a new filter "gsoap" in the "header" section (right click "Header Files", choose Add->New Filter) and do the same in the "source" section. We'll get gSOAP to generate its files there. Now create a new file with extension .wsdl in your solution's folder. Copy the contents of the sample WSDL above and add the WSDL file to your solution (right click on the solution and select “add existing item”). I've named the file HelloWsdl.wsdl. It should look something like this:

Step 2: Let gSOAP generate the header file from our wsdl.

First download gSOAP in order to get the tools needed. You can download gSOAP from this location:
http://sourceforge.net/projects/gsoap2/files/
Make sure you save the extracted files in an appropriate folder for you to remember because we need references to this folder within our visual studio project later on.

Now go back to your solution and right click on the wsdl file and select properties. In the “Custom build step“ add the following command (note that I’ve put the gSOAP tools in the $(SolutionDir); make sure you get the path right and that the solution directory doesn't contain any spaces) in the “Command Line” section:
$(SolutionDir)\gsoap-2.8\gsoap\bin\win32\wsdl2h.exe -s $(InputPath) -o $(ProjectDir)$(InputName).h
This will run the wsdl2h.exe to generate our header file. The parameters specify the input and output file. In the “Outputs” field on the property page enter:
$(InputName).h

.

You need to specify something in the “outputs” field in order to make the wsld ‘compilable’. Note that the path here contains a version number (gsoap-2.8). This can change of course so keep that in mind. Also notice that I did this "setting" for "All Configurations" and not just for the current one.

Click “Apply” and “Ok”, and then right click the wsdl file again and choose “Compile”.
Now our header (HelloWsdl.h) file is generated in the project directory and we need to add this file to the project. In the solution explorer right click on the “gsoap” folder in the header section and choose “add existing item”. Navigate to HelloWsdl.h and add it.

Let’s do the same for generating the cpp file:

Step 2: Let gSOAP generate the cpp source file.

In the solution explorer right click on the HelloWsdl.h, which we just added in the previous step, and select “properties”. In the “Custom build step“ add the following command:
$(SolutionDir)\gsoap-2.8\gsoap\bin\win32\soapcpp2.exe -S $(InputPath)

In the “Outputs” field enter the following:
$(InputName).cpp

.

Right click on the HelloWsdl.h file and choose "compile". This will generate a bunch of files as well, but we are not yet ready to build our solution... If you would try to build the solution at this time, like I did when I first started with gSOAP, you will run into a lot of compile errors so bear with me for a few more steps.

Right click the gSOAP folder in the header section in your solution and add these header files:
- soapH.h
- soapStub.h

Right click the gSOAP folder in the source section in your solution and add these cpp files:
- soapC.cpp
- soapServer.cpp

The next step is to add stdsoap2.h and stdsoap2.cpp to your solution. You can find these 2 files in “gsoap-2.8\gsoap”. Add them together by right clicking the project in the solution explorer and select “Add existing item”. They will automatically appear under the correct “header” and “source” sections.

We’ve added the stdsoap2.h to our solution but we also need to add the directory where stdsoap2.h resides to the project's "include directory list". Add “$(SolutionDir)\gsoap-2.8\gsoap” to the include directorie list by right clicking the project in the solution explorer and click "Properties". In the “Configuration Properties" | C/C++ | General” section you will find “Additional Include Directories”.

Now that we’re done generating files we can actually start to code!

Step 4: Implement our methods

First we need to create the cpp source code containing the main definition and our methods. I will use 2 separate files for this. The first file will contain the server code and will listen to incoming requests/messages. The second file will actually implement our webservice's methods.

Right click on the “Source Files” in the Solution Explorer and select “New Item”. Choose C/C++ file and name the file HelloWsdl.cpp. Do exactly the same for a file called HelloWsdlMethods.cpp.

Your complete solution should now look like this:

.

Let’s start with an easy one; open the HelloWsdlMethods.cpp and copy and paste the following code snippet into that file:

Now if you have built the project prior to adding this piece of incredible intelligent code, you would have seen an unresolved external in the error list: this method. The above function is generated (or better; declared) by gSOAP and the code snippet above is the implementation. You can find the declaration of this method in the generated soapStub.h file:

This is where you will find your method's declarations when you have added your own in the WSDL.

We’re almost there! The last thing we need to do is add our server code. Code that will wait for a request from any client. Below is the code needed. It may look complicated at first but don’t let it scare you. This code is taken from the gSOAP website (section 7.2.3 How to Create a Stand-Alone Server in the documentation section: link listed below) with some minor changes that I will describe below:

Copy and paste the code above into HelloWsld.cpp.

I've listed my changes with some comments (/** */). What is added is that we include a namespaces struct to explicitly set the correct namespaces. gSOAP (soapcpp2.exe) will not only generate code files but also a *.nsmap file which generates a static struct containing the correct namespace to use. The soap_set_namespaces() method will set this struct to use it. That’s it!

All of this may seem like a lot of work but when you are finished setting up the project every change you make in your interface (wsdl) will automatically drill down into your implementation. After setting up the project you most likely will only need to work on the wsdl file and HelloWsdlMethods.cpp to add your own methods.

Now that we've created the server on Windows CE it is time to create a client that will consume our service:

The C# Managed Client

Create a C# .NET (desktop) application with just one Form (I'm not going through each single step of how to create a C# .NET application as this is outside of the scope of this article and assumed known). Add just one button to the form and give it a name. After that we need add our webservice reference to the solution (our wsdl file). In the solution explorer right click on "References" and select "Add Service Reference". In the address field enter the path and the name of the wsdl file on your local machine. In my case this is: C:\Data\Development\HelloWorldWebService\HelloWorldWebService\HelloWsdl.wsdl. I named the reference HelloWsdlMethods and this name will appear in the solution explorer. Click "Go":

.

On the main form Double click on the button and paste the following code into the button handler:

The code behind the button will access our server and call the webservices method. As you can see the naming is probably not the best but for this example it will do.
Run the server program (HelloWorldWebService.exe) on the target and run the client on the desktop. If you've done everything correct you should see the following after pressing the "Test" button:
The C# Client running on the desktop:

Application console on the Windows Embedded Compact device:

Things to lookout for

As you have seen there is a bit of work involved to get gSOAP to integrate nicely with Visual Studio 2008. The process is error prone and gSOAP's logging doesn't help much in most cases. In my experience there are basically three areas where things are most likely to go wrong:

• Location

This tag in the wsdl file specifies the network address on which the webservices are running. Make sure it is set right.

• Namespaces

Make sure that the namespaces used in the wsdl file match the ones in the source code (use the nsmap file) and don't forget to call soap_set_namespaces().

• Hostname

Make sure that you leave the hostname empty: soap_bind(&soap, "", 8080, 100). Specifying the hostname does not work on CE. Also the tools wsdl2h.exe and soapcpp2.exe have a lot of options that I did not discuss in this article. However, getting to know the different gSOAP options is definitely worth the time. The gSOAP website contains a wealth of information and the documentation is comprehensive.

Of course this article only shows a very simple example of how to use Webservices on Windows CE with gSOAP but it should be enough to get you going on much more complex webservices hosted on smart devices.

Please let us know if you'd like to see a more complex example (for instance transferring a file through webservices).

Good luck!

If you have a need to clone the calibration application in Windows CE 6.0 you'll run into several problems when following the instructions in MSDN. The instructions on that page seem to be working fine for Windows CE 5.0 but are causing major headaches on Windows CE 6.0...

Time for an update on the documentation to match the correct procedure for Windows CE 6.0:

Cloning the CalibrUi Module

To clone the CalibrUi module

1. Select the Catalog Items View tab in the workspace window.
2. Expand the [OS Design Name]\Core OS node, and navigate to CEBASE\Shell and User Interface\Graphics, Windowing and Events.
3. Right-click Minimal GDI Configuration. In the pop-up menu that appears, select Clone Catalog Item.
4. The Clone Catalog Item - gwe2 window appears, with a list of component libraries that can be cloned. If the Calibrui module is not already selected, select it and choose OK. In the Cloning Complete window, choose OK.
5. To make sure that the CalibrUi module has been cloned, select the Solution Explorer tab in the workspace. Expand the Subprojects node. If the cloning operation was successful, you will see CalibrUi (gwe2 clone) in the list of subprojects.
   

   Note: You must never change the project name CalibrUi (gwe2 clone). Making changes to the project name will affect the build system and cause your run-time image to be built incorrectly or to fail.

6. Expand the CalibrUi (gwe2 clone) node. All of the source files that relate to the Calibrui module are now available for editing. Any changes to the source files will take effect in any run-time image or executable that you create from this point forward.

You can now try to build the CalibrUi subproject by right clicking it and choosing "Build" from the context menu. If you have sysgenned your OS Design before it should build without any problems.

The problems start when you now (re)sysgen your entire OS Design (needed to include the cloned CalibrUi into your kernel).

When the build system executes sysgen -p dcom preproc a build tool called "SysgenMake.exe" will throw an unhandled exception:

Unhandled Exception: System.ArgumentException: Illegal characters in path.
at System.IO.Path.CheckInvalidPathChars(String path)
at System.IO.Path.GetFileName(String path)
at System.IO.Path.GetFileNameWithoutExtension(String path)
at Microsoft.PlatformBuilder.MainClass.ComputeClonedLibs(String targetLibs, StringDictionary& moduleVars, StringDictionary& environmentVariables, Boolean res2res)
at Microsoft.PlatformBuilder.MainClass.Main(String[] args)
NMAKE : fatal error U1077: 'SysgenMake' : return code '0xe0434f4d'
Stop.


This error is caused by TAB characters in the makefile in \WINCE600\PUBLIC\DCOM\CESYSGEN. Remember that you should NEVER EVER change anything in the PUBLIC or PRIVATE folders? Well, this is an exception. There's simply no way around this bug without changing the TAB characters to spaces, so:

1. Open \WINCE600\PUBLIC\DCOM\CESYSGEN\makefile. in Visual Studio 2008
2. Press CTRL-R, CTRL-W (this will turn on "View White Space")
3. Replace all TAB characters in the file (recognizable by the right arrow character) with spaces
4. Save the file

If you would now sysgen your OS Design again you will see that it successfully executes the sysgen -p dcom preproc command but unfortunately it will fail a bit later in the build process with the following error:

Copying gwestubs.*
Building combined gwes res file for 0419
SysgenMake -RES2RES %GWES_RESOURCES% -fo C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\Wince600\MyBSP_ARMV4I\cesysgen\oak\target\ARMV4I\retail\0419\gwes.res
Res2Res for Windows CE (Release) (Built on Jun 30 2006 16:52:50)
Copyright (C) Microsoft Corp. 1991-2004. All rights reserved.
Res2Res: Ignoring "dummy"
Res2Res: Using C:\WINCE600\public\common\oak\Bin\i386\R2RDUMMY.DLL for temp exe
Res2Res: Using resources from C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res.
Res2Res: Adding resources from C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res to C:\DOCUME~1\Michel\LOCALS~1\Temp\R2R1A00.tmp.
ERROR: Res2Res: Could not open C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res.
Res2Res: Error adding resources (-1) 
 
NMAKE : fatal error U1077: 'SysgenMake' : return code '0x2'
Stop.

It is complaining it can't find the file C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\calibrui\obj\ARMV4I\retail\0419\calibrui_clone.res. Let's check if that file exists or not...

This is the tree of the CalibrUi subproject after building it:

+---obj
    +---ARMV4I
        +---retail
            +---0404
            +---0407
            +---0409
            +---040C
            +---0410
            +---0411
            +---0412
            +---0413
            +---0416
            +---041D
            +---0804
            +---0C0A


As you can see all locale subfolders are created *except* 0419 (Russian)... Even though you may not even need Russian this is still causing a problem!

Inside the obj dir of CalibrUi a file named clone_locales.txt is generated. It looks like this file may have something to do with our problem... But who/where/when is this file created?

The magic is in prelink.bat (thank you for the tip MVP Pavel Belevsky!):

As you can see in the above batch file the folder list in clone_locales.txt is created by the line:

The folder %_PROJECTOAKROOT%\files\INTLTRNS (in our case C:\WINCE600\OSDesigns\MyOSDesign\MyOSDesign\Wince600\MyBSP_ARMV4I\OAK\files\INTLTRNS) apparently does not contain the full list of locales we need for a successful sysgen of the OS Design. We already saw that our %_FLATRELEASEDIR% does seem to contain more locale IDs but at the time of a clean sysgen those folders do not exist in the %_FLATRELEASEDIR% yet, so we need to get them from another location. A bit of searching leads us to \WINCE600\PUBLIC\COMMON\OAK\LIB so lets change the line creating clone_locales.txt to take that location as a source:

Now if you build the CalibrUi subproject you will end up with this tree:


+---obj
    +---ARMV4I
        +---retail
            +---0404
            +---0407
            +---0409
            +---040C
            +---0410
            +---0411
            +---0412
            +---0413
            +---0416
            +---0419
            +---041D
            +---0804
            +---0C0A


With all the above changes implemented you can finally successfully sysgen your platform with your cloned and modified CalibrUi component!

We have just released a new version of the BSP (r366).

Here are the fixes/additions in this release:

• Improved LCD autodetection routines
• Added support for LCD autodetection in 24LC32+ EEPROMs
• Added support for backlight configuration in LCD structures
• Added support for LCD enable configuration in LCD structures
• LCD autodetection is now an optional component
• Fixed PWM2 and PWM4 pad settings
• Added SDK headers and library for PWM
• Added automatic prescaler selection for PWM
• Fixed UART4 pad settings
• Added UART5 DMA support
• Fixed I2C pad and ALT settings
• Fixed I2C and USB OTG duplicated pin use
• Changed driver selection to match DevKit EXP headers
• Fixed flash in IE

We have just released a new version of the BSP (r298) and a new version of the Topaz Flasher.

The r298 Topaz BSP now includes a fully configurable GPIO driver and SDK libraries / headers (amongst other improvements/fixes) and the Topaz Flasher can now also be used to flash a custom flat binary file of any size to any location in flash (so you can now use the Topaz Flasher to flash Linux for instance!).

If you are a device manufacturer or are in any other way involved in building Windows CE 6.0 kernels, you undoubtedly also have to generate an SDK for your device so that application developers can create applications targeting your device.

Platform Builder for Windows CE 6.0 plugs into Visual Studio 2005, but the latest and greatest version of Visual Studio that supports "smart device" development is Visual Studio 2008 (unfortunately not Visual Studio 2010, yet?!). Most application developers will use Visual Studio 2008 for smart device development, so that's what your SDK should support in most cases.

You may have noticed that some of your customers are complaining that the SDK installation aborts and rolls back completely. This only happens on systems that do not have Visual Studio 2005 installed:

The reason for these "ToolsMsmCA(Error): IHxFilters filter registration failure" and "ToolsMsmCA(Error): IHxRegisterSession transaction failure" errors is that the documentation of the SDK is trying to merge with the Visual Studio namespace "VS.VSIPCC.v80", which is the Visual Studio 2005 namespace. Visual Studio 2008 uses the namespace "VS.VSIPCC.v90", and the namespace "VS.VSIPCC.v80" is not available on systems with only Visual Studio 2008 installed.

The solution is simple:

Open your SDK.sdkcfg file and look for the lines:

If you want the SDK to install into Visual Studio 2005 then leave these lines as it is, but if you want the SDK to install into Visual Studio 2008 then change the "v80" into "v90":

and regenerate the SDK.

But what if you have an SDK from a 3rd party and you can't regenerate the SDK? Well, to this problem there are two solutions:

1. Do a custom installation of the SDK and de-select the documentation
2. Use Orca (or any other msi editor) to change the namespace

Of course "solution" number 1 is not a real solution. What if you really need the documentation of this SDK?

Solution number 2 is of course much better. Orca is in the Microsoft Windows SDK which should be on your machine if you've installed Visual Studio. Take a look in your "Program Files" folder and see if there's a folder "Microsoft SDKs". If there is, you'll find "Orca.msi" in the "bin" folder (if not, install Visual Studio or download the Microsoft Windows SDK here.

Once you've installed Orca you can right click the msi and choose "Edit with Orca". When Orca opens you'll have to select the "Property" table on the left and scroll to the property "VS_NAMESPACE" on the right. Now double click on the value of that property and change "MS.VSIPCC.v80" into "MS.VSIPCC.v90" if you want the documentation to install correctly into Visual Studio 2008.

Of course it would be nice to be able to build one SDK that will install without any problems in any version of Visual Studio that supports smart device development. Without an update to the SDK roller by Microsoft or some more hacking and editing of the MSI using Orca this isn't possible at the moment, but the above solutions will at least give you a way to target either VS2005 or VS2008 with your SDK.

GuruCE is the official supplier and support center for Windows CE/Windows Embedded Compact on Device Solution's Topaz i.MX25 CPU Module and the Topaz i.MX25 Development Kit.

For more information and downloads, see the Topaz page.

Martin Welford of Device Solutions, the board manufacturer, made a cool video about what the Topaz is and can do:

Microsoft has decided to retire the newsgroups and move community support to webforums, so it's goodbye:

news://microsoft.public.windowsce.platbuilder
news://microsoft.public.windowsce.embedded.vc
news://microsoft.public.windowsce.embedded
news://microsoft.public.windowsce.app.development

and hello:

Windows Embedded Compact Platform Development
Windows Embedded Compact Native Application Development
Windows Embedded Compact Managed Application Development

You can find them all here.

Remember that when asking questions in the new forums, this still applies!

This post is a bit off-topic for this blog, but since source control and bugtracking are important for Windows CE development as well I thought I'd post about my experiences for (my own) future reference (but I'm sure this will help others as well).

The current setup

At GuruCE we use Subversion (aka SVN) for source control and Mantis (a free popular web-based bugtracking system) for tracking bugs & features.

Subversion runs on a Windows Server through VisualSVN Server (VisualSVN Server makes the Subversion server easy and convenient to install and administer on Windows).

Mantis is running on a Linux server on the other side of the world.

The goal

The goal is to automatically update the status and notes of an issue when committing changes to the SVN server through the TortoiseSVN client.

I want to be able to write comments like:

Worked on issue #64. Robot now enters low power mode when in surveillance mode.
Fixed bug #65. No more unintentional kills. Hopefully...
Implemented feature #66. Robot is now self-aware.
Implementing feature #67 failed. Robot does not allow implementation of self-destruct command.

Ok, I apologize. That was really geeky... ;)

The solution

A lot of information can be found on the net about integrating Subversion and Mantis when they both run on the same Linux server. Our situation is a bit different, being that Subversion runs on a Windows server and Mantis runs on a Linux server on the other side of the world.

Step 1: Configuring Mantis

Using MantisBT version 1.2.0
The first step is to configure Mantis to filter comments so it can determine which issue to update and what to set the state of the issue to. To do that, open config_inc.php in your Mantis installation folder on your server and add the following items:

• $g_source_control_regexp = '/\b(?:feature|bug|issue)\s*[#]{0,1}(\d+)\b/i';

This regular expression filters out the feature, issue or bug number (however you'd like to call it) so it can add a note to the feature/bug/issue.

• $g_source_control_fixed_regexp = '/\b(?:implement(?:ed|s)|fix(?:ed|es))\s+(?:feature|bug|issue)?\s*[#]{0,1}(\d+)\b/i';

This regular expression filters out the feature/bug/issue number if you prepend the word "fixed", "fixes", "implemented" or "implements". When this regular expression evaluates to a number Mantis will use the settings below to set the state of the issue.

• $g_source_control_set_status_to = RESOLVED;

If you fix a bug or implement a feature Mantis will set the issue to status "Resolved".

• $g_source_control_set_resolution_to = FIXED;

If you fix a bug or implement a feature Mantis will set the resolution to "Fixed".

• $g_source_control_notes_view_status = VS_PUBLIC;

Any note added to the issue will be "Public" by default. If you omit this statement all notes will be "Private".

Mantis v1.2.0 comes with a script that you can call from your source control application when committing (or checking in) files. The script can be found in the "scripts" subfolder in your Mantis installation and is called checkin.php.

This script originally uses g_source_control_account to specify the name of the user updating the issue. I didn't want to always specify the same user, but instead specify the name of the user actually committing the files. Therefore I changed line 31 so it reads:

Now the script accepts a username as the first parameter to the script. For this to work you need to make sure that the usernames you have configured in VisualSVN (subversion) are the same as the ones you configure in Mantis.

To see if Mantis is configured correctly you can test the script. First create a new test issue in Mantis and note the issue number. Now login to your server (through ssh) and run the script as follows (if your host doesn't have a simple way to log in using ssh read on to see how to use PuTTY for this):

path-to/php-cli path-to/checkin.php "username" <<< "This will be added as a note to issue #nn"

In our case, the server that runs Mantis is hosted by hostmonster, so for me the actual command to run is:

/ramdisk/bin/php5-cli ~/public_html/mantis/scripts/checkin.php "Michel" <<< "This will be added as a note to issue #46"

The above should add a note to your newly created issue (remember to change #46 with the issue number you created!).

If you want to test setting the issue to "Resolved" with resolution "Fixed", run the following command:

path-to/php-cli path-to/checkin.php "username" <<< "This fixes bug #nn"

Again, in my case:

/ramdisk/bin/php5-cli ~/public_html/mantis/scripts/checkin.php "Michel" <<< "This fixes bug #46"

Once you've verified the checkin script is working properly, you have to configure the machine running the VisualSVN Server so it can remote login on the server running Mantis over ssh. I've used PuTTY/Plink for that purpose:

Step 2: Configuring PuTTY/Plink

1. Download the PuTTY suite
2. Generate a public/private key pair using PuTTYgen

DO NOT enter a passphrase for this private key. We want to use Plink from a script so we can not enter a passphrase!

3. Import the public key into your server running Mantis and authenticate the key (if your Mantis server is hosted by Hostmonster you can simply use the "SSH/Shell Access" icon on the HM control panel to "Manage SSH Keys" and import & authenticate the public key that way, otherwise read this)
4. Now start PuTTY, fill in the hostname and the ssh port of your server running Mantis and point to the private key in Connection->SSH->Auth->Private key file for authentication

Test the session by clicking "Open". If this is the first time you access this server using PuTTY it will display a warning:



Click yes to store the server's fingerprint in the registry (so you don't have to do this the next time).

Now enter the username you use for ssh access to your Mantis server (in the case of hostmonster this is your account name). If you imported and authenticated the public key you created in (2) correctly on your server you should NOT have to enter a password. The server should have authenticated you using the key you pointed to in (4).

You should now be able to run the checkin script through PuTTY using the same commands as above.

The next step is to use Plink, a commandline version of PuTTY that can be used to run commands on a remote server using ssh without dialogs or user input:

5. "path-to\plink.exe" -ssh -i "path-to-private-key" -batch sshusername@server.com path-to/php-cli path-to/checkin.php username <<< \"This will be added as a note to issue #nn\""

If you've filled in the correct values for the placeholders above plink should return without outputting any warning or error, and a note should be added to the specified issue in Mantis.

If not, specify -v on the plink commandline to get verbose output.

We're almost done! What we have accomplished so far is that we are able to update Mantis remotely, from the machine running the VisualSVN (or subversion) server. Now all we have to do is write a proper "hook" script that gets called right after we commit some files.

Step 3: Configuring the VisualSVN post-commit hook script

In VisualSVN (or subversion), create a "Test" repository that you'll be using to test the post-commit hook script.

VisualSVN offers a handy IDE to edit hook scripts. Go to the VisualSVN administration console, right click on the repository you want to install the hook into ("Test"), click "Properties" and select the "Hooks" tab. Here you will find templates for the various scripts SVN supports. We want to use the post-commit script, so select that script and press the "Edit" button.

Paste the following batch script into the VisualSVN edit window (or if you're not using VisualSVN just create post-commit.cmd) and update the PLINK, PLINK_CMDLINE, PHP, CHECKIN and SVNLOOK environment variables to the correct values on your system:

Step 4: Testing it all (and some bugfixing)

Now locally check out the repository "Test" and add a text file to it. Commit the changes with a comment "worked on issue #nn", of course replacing nn with the number of the Mantis test issue you created above, and the script should be automatically called.

After committing, go to Mantis and see if your note has been added.

No? Hmmm.... Strange...

Check the "hooks" subfolder in repository "Test" and open the plinkbat.cmd file:

"C:\Program Files (x86)\PuTTY\plink.exe" -ssh -i "path-to-private-key" -batch sshusername@server.com "/server_path_to/php5-cli /server_path_to_mantis/scripts/checkin.php \"Michel\" <<< \"Worked some more on issue #50 --- Checked into repository C:\Repositories\Test (Revision 23) by Michel\""

Well, that's strange. That command looks all good. (Of course your command has the right values filled in for "path-to-private-key" etc!)

Let's try to manually call the post-commit.cmd file and see if it works then...

Open a dos prompt command window (in Windows 7 shift-rightclick the folder in Explorer and choose "Open command window here") to your repository's hook subfolder (in my case "C:\Repositories\Test\hooks") and run the following command:

post-commit.cmd C:\Repositories\Test 23 (of course replacing '23' with your revision number!)

Now check the issue again in Mantis. Has it been updated? What the... Now it works!?

If you would take a look in plinkbat.cmd you'd see it is exactly the same as before (in fact, running plinkbat.cmd from the command line results in the note being added to Mantis as well of course!), so what is going on?

Well, that question has kept me busy for some time... Remember we started PuTTY once to store the server key in the registry? Well, it so happens that VisualSVN runs as a service, and as such executes the hook scripts under a different user name than yours (because you may not be logged in at all). Second, PuTTY stores the ssh host keys under HKEY_CURRENT_USER in the registry, and what's even worse DOES NOT return 1 when it fails to connect to the server due to the server's host key not being cached in the registry. I think that's a bug in plink. Plink should return 1 in that instance (if it would we would be able to see the error in TortoiseSVN).

So, what's the solution? The solution is to simply copy the stored ssh host key to all users in the system:

1. Start regedit.exe
2. Browse to "HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\SshHostKeys" and export that key
3. Browse to HKEY_USERS and expand the key
4. You should now see a list of users on your system similar to this:
   • .DEFAULT
   • S-1-5-18
   • S-1-5-19
   • ...etc...
5. Open the exported key from (2) in notepad and duplicate the key for the list of users above

Like this:

[HKEY_USERS\.DEFAULT\Software\SimonTatham\PuTTY\SshHostKeys]
   hostkeyvalue_here

[HKEY_USERS\S-1-5-18\Software\SimonTatham\PuTTY\SshHostKeys]
   hostkeyvalue_here

[HKEY_USERS\S-1-5-19\Software\SimonTatham\PuTTY\SshHostKeys]
   hostkeyvalue_here

...etc...

Do not duplicate the key for user keys that have more numbers behind S-1-5-XX, since that is the current user.

6. Now save and close the registry file
7. And finally double click it to add the hostkey registry information to the registry

If you now change a file in your Test repository again, commit it and add a comment containing "issue #nn", Mantis should update correctly now with a note added to the issue, like this:

You could go on and write a more elaborate batch script, but we all know that batch files are not the most user friendly way of writing scripts. Nothing stops us from writing a simple C# application that gathers all information and updates Mantis for us though!

I've attached a simple C# application that updates Mantis using a nicely formatted note, like these ones (I committed 2 files at the same time with the comments "worked on issue #50 (file1.txt)" and "implemented feature #46 (file2.txt)":

As you can see my C# program supports updating multiple issues at the same commit, it gathers all information and formats it nicely.

Call the attached C# program, UpdateMantis.exe, like this from your post-commit.cmd:

But, before you do you'll of course have to install UpdateMantis (a setup package is included in the attachment) and configure the UpdateMantis.exe.config file (note that in Windows 7 you'll have to configure security for the .config file so normal users can modify the file):

Note that you can use environment variables in the xml values. My config file looks something like this:

Note that the attached VS2008 C# project includes source and IS NOT OF PRODUCTION QUALITY. There is no error handling whatsoever, so if you want to use this program in a production environment you should add some code and make it more robust.

I hope this blog post will help some of you out there struggling to get Mantis integrated with SVN. Good luck!

Last but not least, I'd like to thank the writer of this blog post and all people that commented on that blog post. It has been my single source of information while trying to find a solution to my specific problem. Thanks!

I already provided a way to "download once install often" for the Windows CE 6.0 R2 update, and now I've modified the sources to do the same for the R3 update (1.19 GB). Full source and executable attached!

Enjoy!

PS. If you have any trouble installing the Windows CE 6.0 R3 Update please let Brian Rogers know by providing feedback on this blogpost. Feedback will make the process better next time round!

Update: Microsoft has made a download available of the Windows CE R3 update in ISO form! Of course you can still use my tool if you want. Sometimes I just wish Microsoft would announce these kind of things...

The fixes to CE 6.0 R2 VoIP will be included in the July 2009 QFE package which should be released this week.

These QFE's are a direct result from the support incident we opened with Microsoft regarding this issue. The support incident was of course completely free because this was a bug, so, whenever you find a bug that needs fixing: Please open a support incident with Microsoft and help make Windows CE better!

At this moment the whole Windows CE support procedure you have to go through is frustrating to say the least, but Microsoft is updating its support procedures for Windows CE so it will be streamlined in the near future. For now, just keep your cool on the phone and follow the instructions as per the leaflet inside the Windows CE 6.0 box. Do not pay or give them your credit card number if you still have a free support call left (you get 2 free support calls when you buy Platform Builder for Windows CE 6.0).

I'll keep you updated when I hear something back from Microsoft regarding the support procedures.

The war is settled! After years of not knowing, the definitive answer is finally clear:

The internet thinks this about Windows CE and this about Linux.

;)

Version 3.0 of the MicroFramework SDK (finally!) supports configuring USB for other functions than just debug. This means you can now use USB as a communications medium for your applications. Microsoft ships a sample that shows one of those possibilities: Transforming your device into a mouse. In this blog post I'll show a more useful solution: How to setup a MicroFramework device so you can send and receive data over USB to and from the device.

Independent hardware vendors (IHVs) who manufacture USB devices must typically provide a way for applications to access the device’s features. Historically, this has meant using the Windows® Driver Model (WDM) to implement a function driver for the device and installing the driver in the device stack. However, drivers require a significant development effort, and some devices are simple enough that they do not require the full support of a custom function driver.
The USB functionality we'll be developing will be simple, so writing a full function driver will be overkill. Luckily Microsoft introduced the user-mode driver framework (UMDF) and part of this framework is WinUSB. WinUSB was developed concurrently with the Windows Driver Foundation (WDF) and is available for Windows XP and later versions of Windows. It includes a kernel-mode driver, WinUsb.sys, which is an integral part of the WDF-UMDF support for USB drivers. For USB devices that are accessed by only a single application, you can often install WinUsb.sys as the device’s function driver instead of implementing a custom driver. The application can then configure the device and access its endpoints by using the WinUSB API, and that's exactly what I'll do in this example!

WinUSB consists of two primary components:

• WinUsb.sys is a kernel-mode driver that can be installed as either a filter or function driver, above the protocol drivers in a USB device’s kernel-mode device stack.
• WinUsb.dll is a user-mode DLL that exposes the WinUSB API. Applications can use this API to communicate with WinUsb.sys when it is installed as a device’s function driver.

For devices that do not require a custom function driver, WinUsb.sys can be installed in the device’s kernel-mode stack as the function driver. User-mode processes can then communicate with WinUsb.sys through a set of device I/O control requests. The WinUSB API, exposed by WinUSB.dll, simplifies this communication process. Instead of constructing device I/O control requests to perform standard USB operations such as configuring the device, sending control requests, and transferring data to or from the device, applications call equivalent WinUSB API functions. Internally, WinUsb.dll uses the data that the application passes to the WinUSB function to construct the appropriate device I/O control request and sends the request to WinUsb.sys for processing. When the request is complete, the WinUSB function passes any information returned by WinUsb.sys such as data from a read request—back to the calling process.

Using the WinUSB API to communicate with a device is much simpler than implementing a driver, but has some corresponding limitations:

• The WinUSB API allows only one application at a time to communicate with the device. If more than one application must be able to communicate concurrently with a device, you must implement a function driver.
• The WinUSB API does not support streaming data to or from isochronous endpoints. Isochronous transfers require a kernel-mode function driver.
• The WinUSB API does not support devices that already have kernel-mode support. Examples of such devices include modems and network adaptors, which are supported by the telephony API (TAPI) and NDIS, respectively.
• For multifunction devices, you can use the device’s INF to specify either an in-box kernel-mode driver or WinUsb.sys for each USB function separately. However, you can specify only one of these options for a particular function, not both.

WinUSB is natively supported on all Windows Vista SKU's and is supported on all SKU's of the 32 bit versions of Windows XP SP2 and later service packs. WinUSB is not native to Windows XP; it must be installed with the WinUSB co-installer.

The WinUSB co-installer package can be found in the Windows Driver Kit under the WinDDK\BuildNumber\Redist\Winusb folder. The DLLs are signed and can be redistributed by IHVs. So if you want to develop an application that talks to your MicroFramework device over USB under XP, you'll have to install the WinDDK. After you've completed your development and are ready to ship your device your customers of course don't have to install the WinDDK to use your application because you'll ship your device with an installer that includes the redistributable co-installer package.

Read "How to Get the WDK and the WLK" to obtain the latest WDK version.

Before your application can use the WinUSB API to communicate with your device, you must install WinUsb.sys as the device’s function driver. To do so, you have to create a package that includes:

• The WinUSB co installer, which installs WinUSB on the target system, if necessary. The WDK includes two versions of the co-installer, one for x86 systems and one for x64 systems. They are both named WinUSBCoInstaller.dll and are located in the WinDDK\BuildNumber\redist\winusb folder.
• The Kernel Mode Driver Framework (KMDF) co installer, which installs the correct version of KMDF on the target system, if necessary. This co-installer is required because WinUsb.sys depends on KMDF. The x86 and x64 versions of WdfCoInstaller01005.dll are included with the WDK under the WinDDK\BuildNumber\redist\wdf folder (but you need WDK version 6001.18002 or higher).
• An INF that installs WinUsb.sys as the device’s function driver.
• A signed catalog file for the package. This file is required to install WinUSB on x64 versions of Windows Vista. For more information on how to create and test signed catalog files, see "Kernel-Mode Code Signing Walkthrough". Note that this document states that Inf2Cat is not currently part of the WDK tools, but in fact it is (you can find it in \WinDDK\BuildNumber\bin\SelfSign).

Before we can create the INF, let's define what we want our MicroFramework device to do, and develop the device side code!

In this example we want to keep it as simple as possible; all we want is two-way communication with our device. The best option for this is to create 2 bulk endpoints; one for reading and one for writing data. I'll be using the DeviceSolutions TahoeII board to develop the application on.

[Note: Download all code below]

Let's start coding!

1. Start Visual Studio 2008
   I'm assuming you have Visual Studio 2008 with SP1, the .NET MicroFramework SDK v3.0 and the TahoeII SDK v3.0 installed.
2. Create a new MicroFramework Console Application
3. First let's add the needed references. Right click on your project in the solution explorer and select "Add reference...". Now add the following references:
   • Microsoft.SPOT.Hardware.Usb
4. Open program.cs and add the following to the top of the file:
   
   using Microsoft.SPOT.Hardware.UsbClient;
5. Add the following constants to class Program:
   
   private const int WRITE_EP = 1;
   private const int READ_EP = 2;

   We use these constants so we can easily change the used endpoints if needed.

6. Delete the standard Debug.Print line from the function Main()
7. Now we add code to function Main() to detect the number of USB Controllers supported by the hardware:
   
   // See if the hardware supports USB
   UsbController[] controllers = UsbController.GetControllers();

   // Bail out if USB is not supported on this hardware!
   if (0 == controllers.Length)
   {
       Debug.Print("USB is not supported on this hardware!");
       return;
   }

8. At this moment the .NET MicroFramework 3.0 does not support changing the USB configuration on the fly so using USB for application communication and Visual Studio Debugging is not possible when configuring USB from C# code running on the device. If you update the device's USB descriptors through XML using MFDeploy it is possible to debug and communicate at the same time (over multiple USB interfaces descriptors that is! More about that in a follow up post about CDC).
   
   // Find a free USB controller
   UsbController usbController = null;
   foreach (UsbController controller in controllers)
   {
       if (UsbController.PortState.Stopped == controller.Status)
       {
           usbController = controller;
           break;
       }
   }

   // If no free USB controller
   if (null == usbController)
   {
       Debug.Print("All available USB controllers already in use. Set the device to use Ethernet or Serial debugging.");
       return;
   }

   Setting the TahoeII to use Ethernet or serial debugging is easy; just hold SW4 while resetting the device for debugging over Ethernet, or hold SW2 for debugging over serial. If you set it to debug over Ethernet then don't forget to configure the TahoeII's Ethernet settings using MFDeploy (see "Configuring Ethernet on the Tahoe-II" in the TahoeII SDK documentation -> press F1 in Visual Studio)

9. If we found a free USB controller we can now start to configure that controller. We'll put the configuration code in a separate function to keep it all together. Add the following function to the Program class:
   
   1. private static bool ConfigureUSBController(UsbController usbController)
   2. {
   3.     bool bRet = false;
   4.  
   5.     // Create the device descriptor
   6.     Configuration.DeviceDescriptor device = new Configuration.DeviceDescriptor(0xDEAD, 0x0001, 0x0100);
   7.     device.bcdUSB           = 0x110;
   8.     device.bDeviceClass     = 0xFF;     // Vendor defined class
   9.     device.bDeviceSubClass  = 0xFF;     // Vendor defined subclass
   10.     device.bDeviceProtocol  = 0;
   11.     device.bMaxPacketSize0  = 8;        // Maximum packet size of EP0
   12.     device.iManufacturer    = 1;        // String #1 is manufacturer name (see string descriptors below)
   13.     device.iProduct         = 2;        // String #2 is product name
   14.     device.iSerialNumber    = 3;        // String #3 is the serial number
   15.  
   16.     // Create the endpoints
   17.     Configuration.Endpoint writeEP = new Configuration.Endpoint(WRITE_EP, Configuration.Endpoint.ATTRIB_Bulk | Configuration.Endpoint.ATTRIB_Write);
   18.     writeEP.wMaxPacketSize  = 64;
   19.     writeEP.bInterval       = 0;
   20.  
   21.     Configuration.Endpoint readEP = new Configuration.Endpoint(READ_EP, Configuration.Endpoint.ATTRIB_Bulk | Configuration.Endpoint.ATTRIB_Read);
   22.     readEP.wMaxPacketSize   = 64;
   23.     readEP.bInterval        = 0;
   24.  
   25.     Configuration.Endpoint[] usbEndpoints = new Configuration.Endpoint[] { writeEP, readEP };
   26.  
   27.     // Set up the USB interface
   28.     Configuration.UsbInterface usbInterface = new Configuration.UsbInterface(0, usbEndpoints);
   29.     usbInterface.bInterfaceClass    = 0xFF; // Vendor defined class
   30.     usbInterface.bInterfaceSubClass = 0xFF; // Vendor defined subclass
   31.     usbInterface.bInterfaceProtocol = 0;
   32.  
   33.     // Create array of USB interfaces
   34.     Configuration.UsbInterface[] usbInterfaces = new Configuration.UsbInterface[] { usbInterface };
   35.    
   36.     // Create configuration descriptor
   37.     Configuration.ConfigurationDescriptor config = new Configuration.ConfigurationDescriptor(180, usbInterfaces);
   38.  
   39.     // Create the string descriptors
   40.     Configuration.StringDescriptor manufacturerName = new Configuration.StringDescriptor(1, "GuruCE");
   41.     Configuration.StringDescriptor productName      = new Configuration.StringDescriptor(2, "MicroFramework WinUSB");
   42.     Configuration.StringDescriptor serialNumber     = new Configuration.StringDescriptor(3, "0000-0000-0000-0001");
   43.     Configuration.StringDescriptor displayName      = new Configuration.StringDescriptor(4, "MicroFramework WinUSB");
   44.     Configuration.StringDescriptor friendlyName     = new Configuration.StringDescriptor(5, "NetMF_WinUSB");
   45.  
   46.     // Create the final configuration
   47.     Configuration configuration = new Configuration();
   48.     configuration.descriptors = new Configuration.Descriptor[]
   49.     {
   50.         device,
   51.         config,
   52.         manufacturerName,
   53.         productName,
   54.         serialNumber,
   55.         displayName,
   56.         friendlyName
   57.     };
   58.  
   59.     try
   60.     {
   61.         // Set the configuration
   62.         usbController.Configuration = configuration;
   63.         if (UsbController.ConfigError.ConfigOK != usbController.ConfigurationError)
   64.             throw new ArgumentException();
   65.         // If all ok, start the USB controller.
   66.         bRet = usbController.Start();
   67.     }
   68.     catch (ArgumentException)
   69.     {
   70.         Debug.Print("Can't configure USB controller, error " + usbController.ConfigurationError.ToString());
   71.     }
   72.     return bRet;
   73. }

   The MicroFramework SDK v3.0 shipped without documentation on the new USB classes, but an extra download updating the documentation fixes that.

   Let's step through the code:

   • Line 6-14: We start by creating the device descriptor. The constructor of the Configuration.DeviceDescriptor Class has the following signature:
     
     public DeviceDescriptor(ushort Vendor, ushort Product, ushort DeviceVersion)

     Using parameter "Vendor" we supply the VID of the device. In this example I'm using a non-existing VID (0xDEAD), but in your final commercial device you'd have to use your own registered VID (check out http://usb.org for information on how to acquire a VID/PID). Note that in most countries using someone else's VID is considered theft and thus a criminal offense, not just a civil one. The parameter "Product" is used to supply the PID. In this case we'll just use a PID of 0x0001. The "DeviceVersion" parameter can be used to indicate device version and you are free to set this to anything you like (I set it to "1.0").
     The next 4 lines set the USB version in bcdUSB (USB 1.1), the device class, subclass & protocol. We set these to indicate our device is a custom vendor defined class; it doesn't fit in one of the predefined USB classes. The MicroFramework firmware already sets up control endpoint 0 for us so all we have to do is supply the maximum packet size of EP0. Even though the maximum packet size for EP0 is 32 bytes (see the iMXS datasheet; the processor the Meridian module on the TahoeII board is using) the TahoeII firmware sets it up as 8 bytes, so we have to set this field to 8. The iManufacturer, iProduct and iSerialNumber fields are indexes pointing to strings (that are defined in lines 40 - 44).

   • Line 17-25: Here we create our two endpoints: EP1 BULK IN (which means data flows from device to host, so we'll call this WRITE) and EP2 BULK OUT (which means data flows from host to device so we'll call this READ). The class constructor:
     
     public Endpoint(byte EndpointAddress, byte Attributes)

     . The EndpointAddress indicates the physical endpoint number. The attributes indicate the type of transfer, the type of synchronization and the usage type for the endpoint.
     After creating the two endpoints we store them in an array of endpoints so we can include them in the UsbInterface:

   • Line 28-34: The UsbInterface class constructor has the following signature:
     
     public UsbInterface(byte InterfaceNumber, Microsoft.SPOT.Hardware.UsbClient.Configuration.Endpoint[] Endpoints)

     The parameter InterfaceNumber allows us to define multiple interfaces with a different set of endpoints. In this case I define only 1 interface with 2 endpoints in the array. We set the InterfaceClass and InterfaceSubClass again to "vendor defined" and we put our interface in an array so we can include them in the configuration descriptor:

   • Line 37: The ConfigurationDescriptor class constructor has the following signature:
     
     public ConfigurationDescriptor(ushort MaxPower_mA, Microsoft.SPOT.Hardware.UsbClient.Configuration.UsbInterface[] Interfaces)

     The parameter MaxPower_mA is used to set the maximum power in mA. The TahoeII draws an absolute maximum of 180 mA, so that's what we set. The 2nd parameter holds our interfaces.

   • Line 40-44: Here we create our string descriptors that we point at in line 12 - 14.
   • Line 46-57: After creating the various descriptors we can now put them all together in the Configuration class.
   • Line 59-71: And finally we apply the configuration and start the USB controller.
10. Now that we've finished that function, we can continue adding code to the end of the Main() function:
    
    UsbStream usbStream = null;
    try
    {   // Configure the USB controller
        if (ConfigureUSBController(usbController))
            usbStream = usbController.CreateUsbStream(WRITE_EP, READ_EP);
        else
            throw new Exception();
    }
    catch (Exception)
    {
        Debug.Print("USB stream could not be created, error " + usbController.ConfigurationError.ToString());
        return;
    }

    The code above calls the ConfigureUSBController function we created before and creates the USB stream.

11. All we want our program to do is echo back whatever our application running on the PC sends to it. Add the following function to the Program class:
    
    static void USBLoop(UsbStream usbStream)
    {
        byte[] readData = new byte[100];
        for (; ; )
        {
            int bytesRead = usbStream.Read(readData, 0, readData.Length);
            if (bytesRead > 0)
            {   // echo back!
                usbStream.Write(readData, 0, bytesRead);
            }
        }
    }
12. And finally we'll call this never ending loop by adding the following code to the end of the Main() function:
    
    // Start our communication loop
    USBLoop(usbStream);
    usbStream.Close();

    Of course the usbStream.Close() function will never be reached in our case, but we could add code to return from the loop if "Quit" is received for instance...

13. Now that our program is finished we have to set up the correct debug transport to the TahoeII. Before switching the TahoeII to Ethernet you'll have to configure the Ethernet settings using MFDeploy:
    • Make sure the TahoeII is using USB as a debug transport by holding SW3 while resetting the TahoeII
    • Now start MFDeploy and select "USB" from the Device dropdown. The TahoeII should immediately pop up (as "Meridian_XXXXXXXX"). Ping the device to make sure you can reach it.
    • From the Target menu, click "Configuration" and select "Network".
    • Configure the TahoeII to match your network (set a static IP and subnetmask within range of your PC's IP or enable DHCP if you have a DHCP server on your network)
    • Now set the TahoeII to use TCP/IP as debug transport by holding SW4 while resetting the device.

    If the TahoeII is setup for TCP/IP we have to setup Visual Studio 2008 to use TCP/IP as well: Right click on your project in the solution explorer, choose "Properties" and click on the ".NET Micro Framework" tab. Select "All Configurations" from the "Configuration" dropdown list, set "Transport" to "TCP/IP" and you should see the device's IP and MAC address appearing in the "Device" dropdown list. Select the correct one (if you have more than one TahoeII connected) and close this window.

If all is well you can now press F5 to build and deploy the program. If you keep a close eye on your taskbar notification area you'll see the following notifications pop up:

And after that XP will ask you for the driver:

Since we'll be using WinUSB as the driver, all we need to do now is create the .inf file for our device. The document "How to Use WinUSB to Communicate with a USB Device" explains in detail how to do exactly that. If we modify the sample from that document according to the instructions we'll end up with an inf that looks like this:

If you don't use one of the System-Supplied Device Setup Classes you'll have to add a ClassInstall32 section to the inf that adds the class name to the registry. Even though our device would seem to fit the USB class we can't use that class because it's only meant for USB Host controllers and hubs (not for USB peripherals).

Note that if you want to ship a device using the above inf you'll have to change the following:

• Class: Change to something meaningful for your device
• ClassGuid: Generate a new GUID for the class
• CatalogFile: Change to something meaningful for your device
• DriverVer: Change to something meaningful for your device
• Manufacturer/Models sections: Change to something meaningful for your device and make sure the VID/PID matches your device.
• [Dev_AddReg]: Generate a new GUID for the device
• [Strings]: Change to something meaningful for your device

With this inf file we can now create our driver package. The drivers and tools required are all in the Windows Driver Kit, so you'll need to install that first.

After you have installed the WDK create a new folder, let's say C:\MFWinUSBDriver, and create the inf file in that folder. Now open a build environment matching your operating system by clicking the appropriate shortcut in the "Windows Driver Kits" start menu group. Now "cd" (change directory) to C:\MFWinUSBDriver.

The next step is to create a catalog file out of our inf. The process of creating a catalog file (and signing) is described in "Kernel-Mode Code Signing Walkthrough" and the tool to use is Inf2Cat. If you are planning on shipping your driver to your customers you should properly sign your catalog. For the sake of simplicity this blogpost will not discuss official signing (but will focus on getting the driver to load asap!).

As you can see, the inf file lists a couple of dll's. These dll's are part of the WDF redistributables that can be found in the WDK at this location: C:\WinDDK\6001.18002\redist

Copy the amd64, ia64 and x86 folders from C:\WinDDK\6001.18002\redist\wdf to C:\MFWinUSBDriver so that you now have the following 3 folders (with the corresponding driver files in those folders):

Now copy the amd64, ia64 and x86 folders from C:\WinDDK\6001.18002\redist\winusb to C:\MFWinUSBDriver and click "Yes to All" in the "Confirm Folder Replace" dialog.

You should now have the following files in those 3 folders listed above:

The _chk files are for checked (debug) builds of the operating system and since we won't be using those you can delete all the _chk files from the 3 folders listed above.
You can also remove the WUDFUpdate*.dll files because we are going to be talking to the WinUSB driver directly from our application. If you want to write a UMDF driver instead you'll need to add the UMDF coinstaller and have all of the appropriate entries in the inf (like UmdfServiceOrder). The ZIP file contains an example inf file for UMDF as well.

Now that everything is in place we can finally call Inf2Cat:

If all went well the inf2cat output should show:

If you still have the "Found New Hardware Wizard" open you can now point the wizard to C:\MFWinUSBDriver and have it install the driver. If you don't have the wizard open anymore; go to the Device Manager, delete the unknown USB device from the "Other devices" node and re-attach (or reset) the TahoeII.

Now everything is ready and we can start the development of the PC application. Fortunately Jan Axelson already developed an application in C# that can talk to devices utilizing WinUSB. She provides full source code and it's a real good starting point for your own applications. Download the latest version from her WinUSB page.

Download and extract winusb_cs_xxx.zip to a folder of your choice and load the solution in Visual Studio 2008. Now open the frmMain.cs code and change the WINUSB_DEMO_GUID_STRING to match our inf file: "{77C99034-2428-424a-8130-DC481841429B}".

Now press F5 to run the solution. Enter some text in the "Bulk Transfers" textbox and click on the "Send" button:

Eureka! The TahoeII is echoing back whatever we send to it. You can download the MicroFramework code and the MFWinUSB Driver here.

I'll try to follow up this article with an article showing how to setup the TahoeII as a USB Communication Device Class (CDC) so that you can communicate with your device without using WinUSB (and without having to sign your "driver").


Good luck in creating your next USB connected device running the MicroFramework!

Some portions of the text in this article were taken (and modified/updated/added to where necessary) from "How to Use WinUSB to Communicate with a USB Device".

If you try to sysgen a Windows CE R2 OS Design that contains the VoIP components you'll encounter an "error in sysgen phase" when sysgenning FP_VOIP. Build.log will show the error occurred when trying to link phsettings.exe:

phsettings.exe : fatal error LNK1120: 4 unresolved externals

The reason for this is an error in the "sources." file of \WINCE600\PUBLIC\FP_VOIP\OAK\PHONE\COMMON\UTILS:

No files after SecurityUtils.cpp will be built because of the extra return (actually a couple of funny characters messing up the build parser). The shipped libraries were built using this faulty "sources." file, hence the unresolved external symbols when phsettings links to voip_common.lib.

What I'm going to tell you now is against all my beliefs: To (quickly) fix this, you'll have to modify some files in the PUBLIC tree (did I really say that?!)... Well, at least until Microsoft releases the QFE (I've opened a support incident with Microsoft and they are working on fixing this bug at this very moment).

First copy \WINCE600\PUBLIC\FP_VOIP to \WINCE600\ORG_PUBLIC_FP_VOIP (so that you can restore the original FP_VOIP folder when Microsoft releases the QFE).

Now change the "sources." file in \WINCE600\PUBLIC\FP_VOIP\OAK\PHONE\COMMON\UTILS to match this:

Once you've done this, browse to PUBLIC\FP_VOIP in the Solution Explorer (in Visual Studio 2005 with your OS Design open), right click on FP_VOIP and choose "Rebuild" from the context menu. After the rebuild has completed you can sysgen your OS Design successfully.

Unfortunately when you run your kernel you will encounter some more bugs in FP_VOIP... When you add the portrait resources the settings application (phsettings.exe) won't start because it can't find the correct menu structure (breaks at networkdnssettings.cpp line 330 (function NetworkDNSSettingsDialog_t::CreateSpinnerDisplayItem) and when you add the landscape resources the settings application will run correctly, but the homescreen application won't show any text on the buttons (and the buttons don't work).

So, the out-of-the-box applications don't work as expected, but again, Microsoft will release a QFE fixing these issues soon. In the meantime you can play around with it (just make sure you select the landscape resources) by manually starting phsettings.exe so you can setup VoIP. You can even make a phone call (wow! ;), but you'll have to manually start the correct applications.

Seems like this R2 VOIP stuff was never really tested...

This is going to be awesome, can't wait!

User Interface Technologies for Windows Embedded CE

(From Mike Hall's blog)