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.

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!

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 of 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:

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)

Yes, it's official: I've posted too many answers to the newsgroups in the past 9 years.

They blacklisted me! No, just kidding (I hope). I'm not sure what is going on, but the reason for me being really quiet on the newsgroups is because my posts seem to be blocked by the NNTP server...

If I try to post using any newsreader (I use Thunderbird but also tried Agent) my posts get sent correctly but never appear on the server. If I try to post using the web front-end on microsoft.com, my posts do show up on the web front-end but again never make it to the NNTP server (so they are not being propagated to my (and your) newsreader and also don't appear in Google's Group archive/DejaNews). I've even tried the shadowing news server of my ISP provider. My posts do show up on the news server of my provider, but again don't make it to the news.microsoft.com server.

For example these posts are on the web, but not on the NNTP server:
how to use .CAB file provided by driver vendor
USB unmount in CE 6.0
QFE updates
Strange PM timeouts behaviour

And since nobody is responding to my posts I can only conclude nobody is actually using the web front-end on microsoft.com, well, except for this user (because he responded to my post, yeah!):
Parallel port interrupt

So it all points to me being blacklisted... Maybe there's a spam rule: "if [user's post count] > 10000; "it must be a spambot; block it!"

Microsoft is looking into it, so hopefully I'm back soon...

If you have seen the same behavior or may know what's going on, please leave a comment or send me an email (through the contact form on this site)

UPDATE: It indeed seems to be a spam filter thing. I tried changing my email address but that didn't seem to help. Then I tried changing my "Display Name" as well and now I can post again. If you find yourself unable to post; change both your email address (you don't want to use your real email address on NG's anyway because of email-harvester-bots) and your display name and you should be good to go again!

Today all of a sudden Platform Builder 5.0 didn't want to load my workspace anymore. Just before I updated the machine using Windows Update so I figured it must have had something to do with that. Platform Builder would start loading the workspace, show "Refreshing the Catalog" in the status bar, then show "Getting variables that correspond with catalog items" and then it would just sit there consuming 50% CPU and not responding to anything else. Luckily I'm using VMWare for all my CE development work so it was easy to revert back to an earlier snapshot before I updated XP. Unfortunately, this didn't solve the problem! I continued my search and after some frustrating hours I found the cause:

A bit earlier in the day I added a whole lot of header files (121 to be precise) to one of my subprojects sources file (using the FILE_VIEW_INCLUDES_FOLDER macro), and this proved to be the problem. After I reverted the sources file back to its previous revision in SVN the project loaded again.

Another one of those Platform Builder 5.0 mysteries solved...

If sysgen_capture doesn't work for some reason you can always manually clone the component you want to modify. By following the instructions on the blog post "Cloning Public Code: An Example" you should be able to get this working, but to help you a bit more here are some step by step instructions for manually cloning public code.

In this blogpost we'll be cloning TELNETD because for some reason sysgen_capture doesn't work for this component. TELNETD is located under the WINCE project tree "servers". I know the exact name of the WINCEPROJ by opening up the makefile in \PUBLIC\SERVERS\CESYSGEN and searching for WINCEPROJ. The correct sysgen_capture command for TELNETD would be:

sysgen_capture -p servers telnetd

The -p parameter indicates the WINCEPROJ, so in this case it's of course not "common", but "servers". Unfortunately for some reason this command doesn't output a sources.telnetd file (in fact it doesn't output any file!). No stress, let's just clone manually:

1. Copy the TELNETD folder to your OS Design (\WINCE500\PBWorkspaces\<MyOSDesign>\TELNETD or \WINCE600\OSDesigns\<MyOSDesign>\<MyOSDesign>\TELNETD)
2. Open the sources. file in the folder you just copied
3. Set TARGETTYPE to DYNLINK
4. Set RELEASETYPE to LOCAL
5. Delete WINCETARGETFILE0=$(_RELEASELIBDIR)\$(TARGETDEFNAME).def
6. Open the makefile. in <WINCEROOT>\PUBLIC\SERVERS\CESYSGEN and search for telnetd
7. Copy the line @set TARGETLIBS... and @set DLLENTRY...
8. Paste into your sources. file
9. Change @set TARGETLIBS... in your sources. file to:
   
   TARGETLIBS=$(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\ws2.lib \
              $(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\coredll.lib \
              $(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\ceosutil.lib  \
              $(_PROJECTROOT)\cesysgen\sdk\lib\$(_CPUINDPATH)\authhlp.lib
10. Change @set DLLENTRY... in your sources. file to:
    
    DLLENTRY=DllEntry
11. Add the include paths:
    
    _OEMINCPATH=$(_WINCEROOT)\public\common\oak\inc; $(_WINCEROOT)\public\common\sdk\inc; $(_WINCEROOT)\public\common\ddk\inc

    NOTE: DO NOT PUT SPACES BETWEEN THE PATHS! I know it is confusing because I do it above, but I have to to support line breaking (otherwise this page will look ugly...).

12. And build...

Easy as that! Now that you have the TELNETD component successfully cloned you can continue following the instructions from step 7 in the blog post "Cloning Public Code: An Example" (of course replacing "netui" with "telnetd" in the text).

Here's the complete sources. file for reference (don't forget to delete the spaces in the _ISVINCPATH, _OEMINCPATH and INCLUDES macros! I need those spaces here to format the HTML nicely, but you will get compiler error "/I" requires an argument if you leave those spaces):

For some strange reason, people are still changing public code and doing build and sysgen's on their Windows CE tree (read this to learn why this is a bad thing). Changing code in the PUBLIC and PRIVATE trees might seem like a shortcut but actually it is everything but a shortcut. When you clone the code before changing it in place you will save yourself hours and hours of build time. A targeted build of a cloned driver takes seconds, a clean build and sysgen takes hours.

Cloning is not difficult at all, so there is really no reason to change PUBLIC or PRIVATE code. To prove that it is not difficult (once you know what you are doing) I will show you how to clone PUBLIC code in this blog post. Note that there is an article by Steve Maillet and Mike Hall in MSDN about cloning public code too. They split the clone into a "LIB" part and a "DLL" part. I don't really like that method; I just merge the sources file into one that creates the DLL in one go. Have a look at the "split" method here.

I chose to clone NETUI, since this component is responsible for a lot of dialog boxes that you may want to change to match your systems specifications.

I am cloning NETUI on a Windows CE 6.0 tree, but it works exactly the same on a Windows CE 5.0 tree (apart from the OSDesign folder which is called PBWorkspaces in CE 5.0).

Prerequisites: A sysgenned OSDesign with the "Network UI" component included.

Let's start!

1. Copy the entire \WINCE600\PUBLIC\COMMON\OAK\DRIVERS\NETUI folder to your OSDesign, for instance \WINCE600\OSDesigns\MyOS\MyOS
2. Open a build window (in Platform Builder / VS2005 click "Open Release Directory in Build Window" from the menu "Build"
3. In the build window, type:
   
   cd..
   cd..
   cd netui
4. Now type:
   
   sysgen_capture -p common netui

   This command will output a set of files in the current directory.

5. Since we only want to build netui, you can delete:
   
   sources.btdrt
   sources.ceddk
   sources.iphlpapi
   sources.k.iphlpapi
   sources.ws2
   sources.ws2k
6. Now intelligently merge sources. with sources.netui (we make the changes in the sources. file):
• Make a backup of the sources. file (copy to sources.org) so you can always go back if needed
• We are trying to build a DLL, so change TARGETTYPE=LIBRARY to TARGETTYPE=DYNLINK
• We are building NETUI as a project in our workspace, so set the RELEASETYPE to LOCAL (RELEASETYPE=LOCAL)
• We are not building a LIB anymore, so there's no need to preprocess the def file. Remove the following lines:
  
  WINCETARGETFILE0=$(_RELEASELIBDIR)\$(TARGETDEFNAME).def
  PREPROCESSDEFFILE=1

And add this line to tell the build system to use the local def file for the exports:

DEFFILE=$(TARGETDEFNAME).def
• We don't need the resource file later (because we are not creating a lib that has to be transformed into a dll later), so remove the COPYRES=1 line and the WINCETARGETFILES line pointing to the res.
• OSDesign SubProjects get build last, so we don't need to copy SYNCHRONIZE_DRAIN=1 from sources.netui to our sources. file
• Since we are now building a DLL, copy the DLLENTRY line from sources.netui to sources.
• Now move the entire SOURCELIBS and TARGETLIBS from sources.netui to sources.
• and delete any references to netui (netui.lib/netui.res) itself (because we are building that now)
• Change the paths to the target libraries from using the PUBLIC sysgened libraries to the libraries sysgened to your workspace, so change $(_SYSGENSDKROOT)\ to $(_PROJECTROOT)\cesysgen\sdk\ and $(_SYSGENOAKROOT)\ to $(_PROJECTROOT)\cesysgen\oak\
• You can also delete the #xref lines, they are remains of older days (CE 2.11 era).
• Now try to build (by typing "build" in the build window you still have open)
• oops! Doesn't build. It can't find the standard include files... Add the following to the top of the sources file:
  
  _ISVINCPATH=$(_WINCEROOT)\public\common\sdk\inc;
  _OEMINCPATH=$(_WINCEROOT)\public\common\ddk\inc; $(_WINCEROOT)\public\common\oak\inc; $(_WINCEROOT)\public\common\sdk\inc;

  NOTE: DO NOT PUT SPACES BETWEEN THE PATHS! I know it is confusing because I do it above, but I have to to support line breaking (otherwise this page will look ugly...).

• And since this project is building OEM code (a kernel component) set WINCEOEM=1 to indicate we want to use the _OEMINCPATH (so if you really want to you can delete the _ISVINCPATH since we don't use that one).
• Try to build again:
  
  BUILD: [01:0000000048:ERRORE] \WINCE600\OSDesigns\MyOS\MyOS\NETUI\.\btmgmtui.cpp(39) : fatal error C1083: Cannot open include file: '../bluetooth/sample/btenum/btenum.hxx': No such file or directory

  So, one of the sources files is trying to include a header on a relative path. Since NETUI came from \WINCE600\PUBLIC\COMMON\OAK\DRIVERS\NETUI this path must be \WINCE600\PUBLIC\COMMON\OAK\DRIVERS\BLUETOOTH

  Now there are 3 ways to solving this: Either add the \WINCE600\PUBLIC\COMMON\OAK\DRIVERS\NETUI folder to the include path (add INCLUDES=$(INCLUDES);\WINCE600\PUBLIC\COMMON\OAK\DRIVERS\NETUI) so that the header file can be found off the relative path, or change the source file including the header to use a full path to the header file, or copy the btenum.hxx file into the NETUI folder and change the source file including the header to use the local header file. I think the last option is the cleanest, so let's copy \WINCE600\PUBLIC\COMMON\OAK\DRIVERS\BLUETOOTH\SAMPLE\BTENUM\btenum.hxx to \WINCE600\OSDesigns\MyOS\MyOS\NETUI\btenum.hxx and change btmgmtui.cpp to #include "btenum.hxx"

• Build again: 0 Warnings,  0 Errors. Whuuhooo!
• Now there is one final thing we have to add to the NETUI sources. file. We have to tell the build system we want to copy the final binary to the _FLATRELEASEDIR so our netui.dll will overwrite the default one from the PUBLIC\COMMON folder. Add WINCEREL=1 to the top of the sources. file.
7. Now add the NETUI project to your workspace. In the Platform Builder VS IDE click "Add Existing Subproject..." from the "Project" menu. Browse to the \WINCE600\OSDesigns\MyOS\MyOS\NETUI folder, select "Sources/Dirs Files" from the "Files of type" dropdown list, select the sources. file, and click "Open"
8. In the Solution Explorer window you can now find your NETUI component under the "SubProjects" node. Right click NETUI and click "Rebuild" to see if you can build the project from the IDE. It should all build fine.
9. If all builds fine, you can delete the sources.netui and the sources.org files since you no longer need them now.
10. The "Insert existing project" action created a couple of files for you. One of those files is a bib file. BIB files are used to indicate which files need to be included in the image. Since we cloned NETUI, but did not remove it from the OSDesign features, we now have 2 references to NETUI in the combined BIB files (one is in COMMON.BIB and the other in our newly generated NETUI.BIB). We don't need an extra reference in the BIB files, all we want is overwrite the default NETUI.DLL in the _FLATRELEASEDIR, so you can remove this reference from the newly generated NETUI.bib.

Now you can change whatever you need to change in NETUI without worrying about messing up the PUBLIC portion of the WINCE tree or having to do a "Clean Build and Sysgen".

If you have followed all the steps above your final NETUI sources. file should look like this (except the spaces in the _ISVINCPATH, _OEMINCPATH and INCLUDES macros!):

If you read this blog or the CE newsgroups you should by now know you should never change any files in the PUBLIC or PRIVATE folders of your WINCE installation tree. So what if you want to change a setting in common.reg (which is located in the PUBLIC folder)? Well, add the same entry to your platform.reg (in your PLATFORM\BSP folder) and set it to whatever you like. So, what if you want to delete a setting from common.reg? Again, add the same entry to your platform.reg but precede the key name with a "-". This works because platform.reg is merged into reginit.ini after common.reg, so any duplicate entries or deletion commands (the "-") will override the settings in common.reg.

So, what about dat files? Unfortunately, deleting dat entries with the "-" tag is not supported. Dat files are responsible for the initial copy of files and creation of folders during boot. For instance, dat files are used to copy shortcuts from the \Windows folder to the desktop of your CE device. Now what if you don't want to have icons on your desktop? The only way that seems possible is to actually change the public dat files in place, but you know you should never change any files in the PUBLIC tree! We just have to come up with a different solution...

The solution in this case is to filter the dat files and remove any unwanted lines before creating the final image but after the sysgen phase and without touching the original files in PUBLIC. Windows CE calls out to a number of batch files during the makeimg process to let you write your own scripts to affect the image at different points during the image building process. One of those batch files is "PostFmergeObj.bat" which, as the name suggests, is called just after fmerge merged the "Obj" files (which are in fact "Dat" files... confused already? ;o) into your FLATRELEASEDIR.

By using a bit of scripting magic we can use this batch file to filter out unwanted lines from the final merged InitObj.dat file:

The core of the script is from line 15 onwards. In line 15 we delete any previous initobj.org file this batch file may have left behind. Then, in line 16, we rename initobj.tmp (all dat files are merged into this file by fmerge) to initobj.org and in line 17 we call the dos utility Findstr:

By calling findstr with options /I and /V we effectively filter out the lines we specify in PostFmergeObj.txt and we pipe the output of findstr into InitObj.tmp. After this batch file returns the build system will call the "Text to Unicode" tool (Txt2ucde.exe) that converts any ASCII text strings in Initobj.tmp to Unicode text strings and creates the file Initobj.dat which then contains the Unicode conversion of InitObj.tmp (see http://msdn.microsoft.com/en-us/library/ms930234.aspx).

Note that you can also use regular expressions to find strings with findstr. Using this you have a very powerful tool to filter whatever file you want filtered and of course this trick doesn't only work on dat files, it works on any ascii text file (like bib, reg, etc).

All you have to do for all this to start working in your build is create PostFmergeObj.bat in your PLATFORM\BSP\FILES folder and copy'n'paste the above script. The Windows CE build system will automatically search for this batch file and if it finds it execute it just after it has merged the various configuration files. Don't forget to create a "PostFmergeObj.txt" file with the lines you want to delete from the final InitObj.dat file in the same folder as the batch file, like this:

When you now perform a "make image" this batch file should automatically execute and its output (the "echo" commands in the batch file) should appear in the build output window.

The first public beta of version 3.0 of the .NET Micro Framework SDK just got released through the Microsoft Connect website, check out the new features!

In all the drivers and applications I develop, I always take the time to add plenty of logging because I know good logging will save me loads of time debugging my code (as if I ever have to "debug" my perfect code, ha! ;o).

Windows CE has a really great mechanism for debug logging called Debug Zones. This mechanism allows you to divide your debug messages into 16 zones and each of these zones can be turned on or off at run-time. This allows you to control the verbosity of your debug output and helps prevent cluttering of messages. Read this excellent blog post by Travis first before reading on: http://blogs.msdn.com/ce_base/archive/2006/12/18/debug-messages-and-debu...

To add debug logging using Debug Zones to your application or driver do the following:

1. Define your zones using the DEBUGZONE macro
1. Define a DBGPARAM structure and fill it
2. Call either DEBUGREGISTER or RETAILREGISTERZONES from your DllMain (driver) or WinMain (application)
3. Log messages using either DEBUGMSG or RETAILMSG

Sounds easy (and actually it is) but to make it more easy (and because I found myself doing the same thing over and over) I created a template I now use in all my driver and application code, even on projects targeted for Desktop Windows. Even though "Big" Windows doesn't have a "Debug Zone" mechanism you can still use the template. The big benefit of course being your code is completely portable between desktop PC's and CE devices (and also MBS/UNICODE)! The only thing you can't do is switch debug zones at run-time, but you can still select which zones should be on or off at compile-time.

Let me explain the template by walking through it; I'll start with DebugZones.cpp (the line numbers reflect the actual line numbers in the template files):

The first and most important thing to note is that you should not change anything in this file. You configure the template all through the header file, which I will be discussing later.

In this first part of DebugZones.cpp I simply define a global variable dpCurSettings of type DBGPARAM and fill the structure with defines from DebugZones.h. The __TMODULE__ corresponds to the "lpszName" member, the ZONEx_TEXT defines fill the "rglpszZones" array and finally RETAILZONES or DEBUGZONES (depending on whether you build a "debug" or "release" version of the code) corresponds to the "ulZoneMask" member of the DBGPARAM structure. The CE debug system uses this structure to get Debug Zone information from the module and to set or clear debug zones during execution of the module. When you use the template for code targeted at Desktop Windows this structure will only be used by the DEBUGMSG/RETAILMSG macros (they use the ulZoneMask member as a display condition).

This code is only used when you target Desktop Windows. Only Windows CE defines NKDbgPrintf so for Desktop Windows I had to create my own implementation of this function to make the Debug Zones system portable. This function simply takes a format string followed by a variable number of parameters and transforms that into a formatted string and outputs it to the debug output window of Visual Studio. Note that the maximum length of the formatted string is BUFFER_SIZE characters.

This next bit of code is a helper function that solves a problem when you want your code to be portable between MBS and UNICODE. MBS is multi-byte string, also called ANSI string, and UNICODE is, well, UNICODE strings. Let's say you are compiling for UNICODE but want to display a multi-byte string using a function that uses a format string. The way to do that is to use %S instead of %s in the format string. When you use %s in code compiled for UNICODE the variable indicated by %s should be in UNICODE. When you compile for MBS the variable indicated by %s should be MBS. In other words, %s indicates the "native" string format. If you want to display a multi-byte string in code compiled for UNICODE you'd use %S, and if you want to display a UNICODE string in code compiled for MBS you'd use %S as well. In other words, %S indicates the "opposite" string format. And here lies the problem: What if you want to display a multi-byte string regardless of whether the code is compiled for MBS or UNICODE?

Take a look at the following code:

Note that the _T macro is defined as L in UNICODE (making the following string a UNICODE string) and as nothing in MBS (leaving the following string a multi-byte string).

When compiled for UNICODE the above code works perfectly:

But now see what happens when you compile the above code for MBS:

You only get the output of the first line! So what just happened? Well, the _vstprintf_s function in NKDbgPrintf expected the first argument to be of the opposite string format. Since you compiled for MBS this means it expects a UNICODE string. The _vstprintf_s function detects it is not and bails out, setting szBuffer to an empty string.

The to_T function solves this problem:

When compiled for MBS the output is:

I can here you say: So why don't you just use _T() in that 2nd call to NkDbgPrintf? And yes, you are right, in the above code that would work, but what if it's a variable pointing to a multi-byte string? You can't use _T() around a variable:

Line 64 defines the maximum number of times you can call this function before it will start overwriting its internal buffers. Increase this value if you want to use more than 4 parameters that need to be converted in one call. To understand this, see the following code and its output:

Output:

Let's move on to the real core of the template; DebugZones.h:

This is the part of the template you should change to match your driver or application. First, in line 30, change the __MODULE__ define to the name of your driver or application. If you are creating a flash driver you'd set this to "FLASH" for instance.
Next, in lines 33 to 48, you define the friendly names of the debug zones you want. These names will show up when you use the Debug Zones dialog or the "zo" command from Platform Builder. The predefined ones are always useful:

• Init

Use this zone to display debug messages during the initialization phase of your driver. I use this zone in the Init function of drivers.

• Function

This zone is used to display function entry and exit. Used by the FUNC_ENTRY and FUNC_EXIT macros (I'll discuss those later)

• Memory

This zone is used to display memory allocation and de-allocation. Having a separate zone for memory really helps in identifying memory leaks or memory related problems in your driver or application (besides CeDebugX)

• Info

This zone is used to display general information. I use this zone a lot through-out my code and enabling this zone usually means I get heaps of debug messages, but also heaps of information about the flow of my code

• Warning

Use this zone for non-fatal errors (also known as warnings ;o)

• Error

Use this zone for fatal errors; situations where you had to abort a certain operation

Another zone I use often is "IOCTL". If my driver handles custom IOCTLs I use that zone to display information when those IOCTLs are handled. If you want to add the IOCTL zone you'd change line 36 to:

Lines 51 to 66 define the actual zone IDs. You use these defines as the first parameter of LOG_MSG (that I'll discuss later) to indicate the zone this message belongs to. After you added the IOCTL zone to the friendly names list, you'd change line 54 to:

Lines 69 to 84 define the zone masks. You use these defines to indicate which zones should be enabled by default. After you added the IOCTL zone to the zone ID list, you'd change line 72 to:

Line 86 and 87 define the default zones to use in a release build and a debug build. I enable zones INIT, WARNING and ERROR in a release build and add FUNCTION, MEMORY and INFO to debug builds. Note that in a "ship" build (on Windows CE, WINCESHIP=1) debug/retail messages are defined as "nothing" (so all the logging code is effectively removed from the final binary).

If you define FULL_CONTEXT (line 91) the LOGMSG macro will output the full path to the source code filename in front of the message, instead of just the module name. I don't enable this by default because it makes the debug output cluttered and less readable (but it can be very handy in some cases).

This concludes the part of DebugZones.h that you should change. The remainder of the code mostly deals with the differences between Desktop Windows and Windows CE:

The interesting part is from line 165 to 173 where I define three macros that allow you to log messages in a good format (in my humble opinion):

• FUNC_ENTRY

Usage:

FUNC_ENTRY(format_string [, arg1, arg2, ...]);

Examples:

FUNC_ENTRY(_T("void"));
FUNC_ENTRY(_T("lpParameter = 0x%08X"), lpParameter);

Output:
(Note the '+' characters that indicate function entry)

ModuleName: +FunctionName(void)+
ModuleName: +FunctionName(lpParameter = 0xA5A5A5A5)+
• FUNC_EXIT

Usage:

FUNC_EXIT(format_string [, arg1, arg2, ...]);

Examples:

FUNC_EXIT(_T(""));
FUNC_EXIT(_T("return %s"), bRet ? _T("true") : _T("false"));

Output:
(Note the '-' characters that indicate function exit)

ModuleName: -FunctionName()-
ModuleName: -FunctionName(return false)-
• LOGMSG

Usage:

LOGMSG(ZONE_ID, format_string [, arg1, arg2, ...]);

Examples:

LOGMSG(ZONE_INIT, _T("Started successfully!\r\n"));
LOGMSG(ZONE_ERROR, _T("ERROR: Invalid parameter (dwParam = %d)\r\n"), dwParam);
LOGMSG(ZONE_WARNING, _T("WARNING: Could not reach IP %s\r\n"), to_T(inet_ntoa(IPAddress)));

Output:

ModuleName:  FunctionName> Started successfully!
ModuleName:  FunctionName> ERROR: Invalid parameter (dwParam = 1234)
ModuleName:  FunctionName> WARNING: Could not reach IP 192.168.1.1

To use the Debug Zones template in your projects you simply add DebugZones.cpp and DebugZones.h to your solution and call RETAILREGISTERZONES(hMod) from your entry point function:

or in case of an application:

Note that the parameter to RETAIL/DEBUGREGISTERZONES MUST be NULL if you want to register debug zones from an application!

If you are using precompiled headers you have to set DebugZones.cpp to "Not Using Precompiled Headers" (in VS2008 right click DebugZones.cpp in your solution, click "Properties", then select "Precompiled Headers" under "Configuration Properties -> C/C++" and change the "Create/Use Precompiled Header" value). Now include "DebugZones.h" in any file you want to use debug zone logging.

The attached ZIP file contains the complete template.

I hope this template will prove as useful to you as it is to me!

This page is also available in Italian. Want to translate into your language? Let me know!

There are certain rules when you use a community driven newsgroup to get answers to your questions. The Microsoft newsgroups that deal with Platform Builder and Windows CE development (like microsoft.public.windowsce.platbuilder, microsoft.public.windowsce.embedded & microsoft.public.windowsce.embedded.vc) are not actively monitored by Microsoft. The people answering your questions are your peers; volunteers who spend their time researching your problem because they find it interesting and want to learn more.

The people that post most answers are in many cases MVPs, Most Valuable Professionals, a status awarded by Microsoft to people who help out the community by running user groups, answering questions in public newsgroups, etc.

It is important to note that nobody is being paid to answer questions. They're all volunteers.

Now that you know this, you also know that there is no guarantee to get an answer. The most common reasons for not getting an answer are:

• Your question has been answered on the newsgroup in the past

Search before you ask!

• You didn't supply enough information

"I call this function and it doesn't work, please help" is useless.

• You keep on posting the same question over and over

If nobody answered your question after a couple of days it is because you didn't read this blog post on how to ask questions or simply because nobody knows an answer. If you want to "reactivate" your question, post a reply to your own question with something like "Anybody? Please?" and supply any other relevant information you may have gathered over the past few days. Do not start another thread for the same question. It is annoying and will result in people ignoring you.

• You demand a quick answer

Demanding things from people you do not pay any money is generally counterproductive.

• You post the same question separately to different newsgroups

If you think your question is relevant to multiple newsgroups post one question to multiple newsgroups. Please do not post the same question separately to different newsgroups. If you want to crosspost that's fine; just create one message with all the newsgroups you want to post to listed in the To: field (just as you would sent one email to multiple email addresses using the To, CC, or BCC fields). Replies to your question will then appear in all newsgroups you posted to. If you post the same question separately to multiple newsgroups the reply will only appear in the newsgroup that was replied to, leaving the question in the other newsgroups unanswered.

Note that the above says nothing about "stupid" questions. That is because stupid questions do not exist! Everybody on the newsgroups started with Windows CE at some point, and everybody struggled with the (sometimes) steep learning curve in the beginning. We know where you are coming from so don't be shy and ask, but before you do, take note of the following "rules" that will increase your chances in getting a useful answer:

• Read MSDN Library

This sounds logical, but you'd be surprised how many questions are asked that can be easily found in MSDN. Click here for the Windows CE documentation and use the search box in the top right hand corner to search. When you use search, make sure you check if the description you see is for "desktop" Windows, or for Windows Embedded. As you know, Windows CE uses a subset of the big Win32 API and some API parameters have different meaning in CE, so be careful there! That said, sometimes the big Win32 API description lists more information that also applies to and is still useful for CE. First thing to do when you encounter a problem with an API is to open the description of that API in MSDN, check all the parameters and read the remarks section. The remarks section has useful information about error conditions and special requisites that may be needed for the API. If you encounter a problem in the documentation, or missing information or something else wrong with the documentation: Use the "Click to Rate and Give Feedback" link in the top right corner. The people at Microsoft responsible for the documentation really read this feedback and will update the documentation where necessary. Help make the documentation better!

• Before asking a question, search the newsgroups for an answer

Use Google Group Search to search the newsgroups. Type some keywords in the "with all of the words" box, then in the "Return only messages from the group at this location" box type *windowsce* to search all newsgroups related to Windows CE. I also usually set the form to "Return 100 messages" and "Sort by Date" so I get the latest answers on the top of the list.

• Subscribe to blogs

Most MVPs and some people within the Microsoft Product Team have blogs. Blog posts usually deal with a FAQoaN (a Frequently Asked Question on a Newsgroup ;o), like the "What to build when" post on this blog. Some of the blogs that I subscribe to are the Windows CE Base Team Blog, Mike Hall's Windows Embedded Blog, the Windows Mobile Team Blog and of course the GuruCE Blog.

If your search did not return a useful answer you can post a question to the newsgroup, but before you do: try a debug build, get KITL going and analyse the debug messages. If you can't build a debug kernel or get KITL going it will be difficult to get to the root of the problem, but not always. If you can't get KITL or a debug build going list that in your question!

Information that should be in your question:

• OS version / hardware / board / kernel / QFE's

List the OS version, what hardware, what processor, what board, what BSP, debug or retail kernel, KITL yes/no, and what QFEs you installed

• Specific Component

If you have problems with an existing driver or a specific component; tell us! Saying "I've got a problem with the touch driver" is useless, because there is no such thing as the touch driver. If you made the driver; tell us. If you cloned a driver, tell us which driver you cloned (including the original path you cloned from). If you are having problems with a standard driver, tell us exactly which one including the complete path. Example: "I've got problems with the MainstoneIII touch driver located in C:\WINCE600\PLATFORM\MAINSTONEIII\SRC\DRIVERS\TOUCH"

• Big picture

Explain what you want to accomplish, not how you want to accomplish it. There may be better ways to get where you want. Describe the bigger picture.

• What did you try

List the things you tried, the tests you performed and why it didn't work. If people ask you to perform another test: do it! Don't expect an answer if you are unwilling to follow advice that may lead to the solution of your problem. Also, if your search found a solution to your problem but somehow it didn't work, list that too.

• Detailed error messages

If you got an error, list it. If an API returns an error, get the error number by calling GetLastError() and list it.

• Detailed debug messages

Post the debug message lines that you think are relevant to the problem. Do not post 6000 lines of debug log because nobody will want to read through all of that.

• Be polite

Don't demand an answer. Remember nobody is being paid to answer your questions. If you want paid support, buy support from Microsoft or one of the Embedded Partners, like GuruCE. Same goes for people answering questions; be polite, remember your own struggles when you started with CE.

• Proof read / Spell check

We understand English is not the language the entire world speaks fluently; it's not my native language either. Spelling mistakes are common and not a problem at all, but before you post; at least read back what you wrote and make sure it is understandable. Don't just check for funny sentences and spelling mistakes, make sure there is enough information in the message for other people to understand your problem. The quality of the answer can only be as good as the quality of the question!

• MSN/SMS/Text Generation

Remember you are not paying per-byte on the newsgroups so please refrain from trying to shorten your messages. Do not use "ur" instead of "you're" or "2" instead of "to". It makes the message unreadable/annoying. R3m3mb3r typing l1k3 th1s do3s n0t m@k3 u 3733T, 1t 1ly m@k3$ u l00k st00p1d!

If you follow these rules (that are valid for any community driven forum) then there are no stupid questions and you will most certainly get an answer from one of the many volunteers answering questions in the newsgroups.

Here's a template you can use to ask questions in the CE newsgroups:

One final request: Return the favor!

Once you find a solution to your problem, either by yourself or because of a tip from somebody on the newsgroup, please spend 5 minutes to write it down and post it as a reply to your original question. Your solution may save somebody a lot of time and frustration in the future.

Why not become part of the community? Don't be afraid to answer questions if you think you know the answer!