Microsoft Surface Applications - Deployment and Object Routing

Continued from: Microsoft Surface Tagged Objects and Tag Visualizations

When users interact with a Microsoft Surface unit, they launch the applications from Launcher.  Launcher is the menu that displays the applications that are available to users in a horizontal interactive strip.


 As part of deploying the Surface application, we must register it with Surface so that it is available in the Launcher. This is done by copying the application’s xml file to the Surface’s program data folder (%PROGRAMDATA%\Microsoft\Surface\Programs).

This application xml file is created by default when the Visual Studio project template is used. Otherwise, we can create a normal xml file with the file name equivalent as the project (executable) name and with the following tags.

<?xml version="1.0" encoding="utf-8" ?>
<ss:ApplicationInfo
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:ss="http://schemas.microsoft.com/Surface/2007/ApplicationMetadata">
  <Application>
    <Title>My Surface App</Title>
    <Description>This is a sample Surface application.</Description>
    <ExecutableFile>%ProgramFiles%\MyCompany\MyApp\MyApp.exe</ExecutableFile>
    <Arguments></Arguments>
    <IconImageFile>%ProgramFiles%\MyCompany\MyApp\Resources\icon.png</IconImageFile>
    <Preview>
      <PreviewImageFile>%ProgramFiles%\MyCompany\MyApp\Resources\iconPreview.png</PreviewImageFile>
    </Preview>
    <Tags>
      <ByteTag Value="C0">
        <Actions>
          <Launch />
        </Actions>
      </ByteTag>
    </Tags>
  </Application>
</ss:ApplicationInfo>

The <Application> tag specifies that this is a normal Surface application. Other options are <AttractApplication> for attract mode (similar to screen saver) applications and <ServiceApplication> for apps that run in the background and does not have a UI.

The <Title> is displayed on the Launcher all the time, and <Description> is displayed when the application is selected from the Launcher. <ExecutableFile> specifies the path to the actual application exe. If the application is accepting any command line arguments it can be supplied through <Arguments> tag. <IconImageFile> specifies the png image to be displayed in the Launcher as application icon and <Preview> specifies the image to be displayed when the application is selected in the Launcher. This can be a bigger static image(<PreviewImageFile>) or a slideshow of images(<SlideshowImageFile>) or a movie (<MovieFile>).

The <Tags> specify the tags used by the application and <Launch> is used to specify that the particular tag value is used for object routing (which is discussed later).

To summarize the deployment steps again:

• Build your Surface application in Release mode.
• Copy all the files from the build folder to any location in the Surface computer (typically %ProgramFiles%\CompanyName\ApplicationName\).
• Make sure that this path is specified in the Application’s xml file.
• Copy the Application’s xml file to (%PROGRAMDATA%\Microsoft\Surface\Programs folder.

That’s all to it and the application will now be available in the Launcher for the user to see and launch.

Tagged Object Routing
On 2009-May-10, Microsoft released its first Service Pack (SP1) to Surface 1.0 with lots of new features and improvements. Read about them at official Surface blog.

Object Routing is one of the new SP1 features that enable the developer to configure tagged objects which can open applications without using Launcher. The tagged object can be placed anywhere on the Surface interface (attract applications, other non-registered applications or the Launcher) to bring up the list of applications that are registered with that tag. The applications will appear as tiny bubbly icons that smoothly pops up from the object and can be launched by touching them.

 
To enable the object routing for an applications:

• Specify the required type of tag (Byte/Identity) within the <Tags> section of the application’s xml file and specify its value and have the <Actions> as <Launch>.

<ByteTag Value="C0">
  <Actions>
    <Launch />
  </Actions>
</ByteTag>

or

<IdentityTag Series="4245A8E4901C2C0B">
  <Actions>
    <Launch /> 
  </Actions>
</IdentityTag>

I have used an example value of C0 for Byte tag and 4245A8E4901C2C0B for Identity tag.

• Create a new registry key using this tag value under TagInfo section as below:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Surface\TagInfo\v1.0\ByteTags\C0
or

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Surface\TagInfo\v1.0\IdentityTags\4245A8E4901C2C0B

• Add the following String Value items on this key
• Text : ‘object routing card title’.
• BoundingBoxWidth : ‘3.25’.
• BoundingBoxHeight : ‘2.125’.
• PhysicalCenterOffsetFromTagX : ‘0’.
• PhysicalCenterOffsetFromTagY : ‘0’.
• OrientationOffsetFromTag : ‘0’.

This specifies the size of tagged object (business card size is 3.25 x 2.125 inches) and the location of the tag within this object (Zero means there is no offset from the center of the object; the tag is exactly on the center of this business card sized object)

Note that the other registry settings (enabled by default) to enable Object Routing (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Surface\v1.0\Shell\EnableObjectRouting ) must be set as well.

That’s all the settings we need to do to get object routing work. Now if you place a tag with the specified value, all the applications that have this tag value in their xml file registered will popup from this object.

If you have done everything right, and still its not working as expected, refer the event log (run the command eventvwr) and navigate to Applications and Services Logs/Microsoft/Surface/Shell/Operational for any possible warnings or errors. Chances are that there is some error in the application's xml file or the registry settings. A sample warning (when the required registry entry is not present) looks like below:

The application info file C:\ProgramData\Microsoft\Surface\Programs\Macroni.xml refers to tag 29EB049F73061803, however, some configuration information for 29EB049F73061803 is missing from the registry. The default value '2.125' will be used for the missing setting.
Path to the tag's missing configuration setting in the registry:
HKEY_LOCAL_MACHINE\Software\Microsoft\Surface\TagInfo\v1.0\IdentityTags\29EB049F73061803\BoundingBoxHeight

Happy coding!