Export (0) Print
Expand All

Configuring Object Routing

By default, users open applications on Microsoft Surface by tapping the application icon image in the Launcher menu. You can also set up object routing so that users can find and open applications by using tagged objects.

For example, a user walks up to Surface in a resort hotel lobby and places their tagged phone on the screen. On the screen, the following menu appears next to the phone.

An object routing menu next to a tagged object.

How Object Routing Works

The vision system in devices made for Microsoft Surface reads the value of the tag on the loyalty card and checks if the tag is registered with Surface Shell. Then, Surface Shell displays a menu of applications that are associated with the tagged object. A user can tap and start any of the named applications in the object routing menu.

If the user taps one of the application icons, the Launcher menu will scroll to, and activate, the selected application. When the application starts, the object's menu disappears and the object begins to interact with the newly opened application. Because the application will interact with the object, the object routing menu is not displayed. To activate a different application associated with the object, the user must exit the current application, using the access points, and replace the object on the surface for the object routing menu to appear.

Users can put tagged objects that are configured for object routing on the screen at any time, whether in the Attract application, in Launcher, or in any Surface application that is not associated with the object. If a user puts the object on Launcher, the object's menu displays but the user can still scroll Launcher and start any application from it. The object routing menu is unavailable only when the foreground application is interacting with the object, or when the device made for Surface is out-of-order or during transitions, such as when Surface Shell loads Launcher.

noteNote
Multiple users can put multiple tagged objects that are configured for object routing on the screen at the same time. Each tagged object displays the appropriate object routing menu.

Surface must be configured to recognize tagged objects for object routing. If users place a tagged object on an application that is not associated with the object, the object routing menu displays and the object does not interact with the foreground application.

Tags and Objects Used for Object Routing

Typically, if a Surface application can use tags and object routing, the appropriate objects are provided by the application vendor. However, you may need to replace objects or tags and the following sections explain how tags and objects work with Surface Shell. You can use this information to help you troubleshoot issues that may occur with your Surface applications that use object routing.

Tags

Surface supports 8-bit (1 byte) tags, providing 256 unique tag values. The following illustration shows four tags that store 8 bits of data (1 byte) on each tag:

Example tags

If several applications on a particular device made for Surface were created by different developers, you must also consider tag value collision or conflict. For tips about how to distinguish between errors in an application's object routing and errors from duplicate tag values, see Troubleshooting Object Routing.

Objects

Any portable object to which you can affix a tag can be used with Surface applications that are designed to use tags and tagged objects. Some examples include game pieces, such as chess pieces, beverage glasses, or loyalty cards, as mentioned earlier. As with tags, objects must also be registered with Surface Shell. Objects can be various shapes and sizes, and tags can be applied in varying positions on these objects. In order for Surface Shell to display the object routing menu in the right way (for example, so the object does not cover the object routing menu), Surface Shell needs to know how large the tagged object is and where the tag is affixed to it.

The following illustration shows the parts of a tag on a tagged object (loyalty card):

Tagged object with physical attributes labeled
  1. The offset of the bounding box center from the tag center, in the X-direction. (PhysicalCenterOffsetFromTagX) The bounding box is the size of the rectangle around the tagged object that Surface uses to determine the size of the object routing menu.

  2. The offset of the bounding box center from the tag center, in the Y-direction. (PhysicalCenterOffsetFromTagY)

  3. The center point of the bounding box.

  4. The center point of the tag.

  5. The offset of the bounding box orientation from the tag orientation, degrees. (OrientationOffsetFromTag)

Surface Shell gets information about the position of tags and the size of tagged objects from the ApplicationName.ObjectSets.xml file where the following attributes are specified:

 

Attribute Description Unit

BoundingBoxWidth

The width of the bounding box, which is the size of the rectangle around an object that Surface Shell uses to determine the size of the object routing menu.

inches

BoundingBoxHeight

The height of the bounding box. For more information, see the description of BoundingBoxWidth in the previous row of this table.

inches

PhysicalCenterOffsetFromTagX

The offset of the bounding box center from the tag center, in the X-direction.

inches

PhysicalCenterOffsetFromTagY

The offset of the bounding box center from the tag center, in the Y-direction.

inches

OrientationOffsetFromTag

The offset of the bounding box orientation from the tag orientation, clockwise.

degrees

Text

The text to appear under the object.

not applicable

The following code example shows a typical ApplicationName.ObjectSets.xml file, which can be found in the %ProgramData%\Microsoft\Surface\v2.0\ObjectSets directory:


<?xml version="1.0" encoding="utf-8"?>
<ss:ObjectDescriptions
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ss="http://schemas.microsoft.com/Surface/2010/ObjectDescription">
    <Object ID="CreditCard">
      <Layout
        BoundingBoxWidth="3"
        BoundingBoxHeight="2"
        Text="Contoso Express" />
      <ObjectTagSet>
        <Schema>
          <Single Value="0x0" />
        </Schema>
        <Series>
          <Single Value="0x0" />
        </Series>
        <ExtendedValue>
          <Single Value="0x0" />
        </ExtendedValue>
        <Value>
          <Range Min="0xc1" Max="0xc3" />
        </Value>
      </ObjectTagSet>
    </Object>
</ss:ObjectDescriptions>

noteNote
Verify that your tag value is specified in your application's registration XML file.

If your application has an installer, the installer should automatically create and add the correct information into the XML configuration files to enable object routing.

Object Routing Configuration

ImportantImportant
Typically, the application developers and object vendors should provide installers that install the application, create the correct entries in the XML configuration files, and create and set the correct registry entries. If so, you just need to install the application and test it by using the appropriate tagged object. The following configuration details are provided to assist you in troubleshooting your object routing application installations.

The following settings are required to successfully deploy object routing on Surface:

  1. Install at least one application that is configured to use object routing.The application should also provide tag visualization (through the TagVisualizer or TagVisualization classes from the Microsoft Surface SDK or through another programmatic means.)

  2. Include the Launch element in the application's XML registration file (ApplicationName.xml) to properly register the application with Surface Shell. For more information, see Mapping Object Routing Tags to a Surface Application and Registering Applications.

  3. In the registry, enable object routing by setting HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Surface\v2.0\Global\Shell\EnableObjectRouting entry value to 1. (By default, object routing is enabled on Surface.) For more information, see Surface Registry Keys.

  4. Define the shape data that is associated with tags by specifying values for a set of attributes in the ApplicationName.ObjectSets.xml file that is placed in the %ProgramData%\Microsoft\Surface\v2.0\ObjectSets folder. This shape data tells Surface Shell how large an object is to which the tag is affixed. It also tells Surface Shell where the tag is located on the object so Surface Shell knows where to position the object routing menu when an object is placed on the screen. For more information about the attributes that are used to specify tag location on objects, see the Objects section of this topic.

Tagged Object Scenarios for Microsoft Surface

There are several factors that affect the behavior of a tagged object. The following table describes several scenarios for tagged objects and how the Surface user experience changes.

 

Tagged object configuration Response to the tagged object on the Surface screen

An application is programmed to react to a tag.

The associated ApplicationName.xml file does not contain a <Tags> entry.

In the …\Global\Shell registry subkey on the device made for Surface, EnableObjectRouting is set to 0 (disabled).

If the application is not currently active, nothing happens. The Surface software ignores the tag values and handles the object as a blob (just like a hand).

If the application is active, the Surface software recognizes the tag, and the application reacts to the tagged object in whatever manner it was programmed to react.

An application is programmed to react to a tag.

The application's ApplicationName.xml file includes the <Tags>, <Actions>, and <Launch> entries.

The ApplicationName.ObjectSets.xml file contains the bounding box and offset information for this tagged object.

In the …\Global\Shell subkey, EnableObjectRouting is set to 1 (enabled).

If Surface Shell (or any application other than the application that is programmed to react to the tag) are active, the Surface software displays the object routing menu. A user can tap the icon to open the application.

If the application that is programmed to react to this tag is active, the Surface software does not show the object routing menu, and the application reacts to the tag like it is programmed to.

Three applications are programmed to react to a tag.

The ApplicationName.xml files for the first and second applications include the <Tags>, <Actions>, and <Launch> entries.

The ApplicationName.xml file for the third application includes the <Tags> and <Actions> entries, but it does not include the <Launch> entry. (This application is registered with Surface Shell but it is not registered with object routing.)

The ApplicationName.ObjectSets.xml file contains the bounding box and offset information for this tagged object.

In the …\Global\Shell subkey, EnableObjectRouting is set to 1 (enabled).

If Surface Shell (or any application other than the applications that are programmed to react to the tag) are active, the Surface software displays the object routing menu with the first and second applications' icons in it. Users can tap these two icons to open the first and second applications. An icon for the third application does not appear.

If any of the three applications that are programmed to react to this tag are active, the Surface software does not show the object routing menu, and the applications react to the tag like they are programmed to.

Two applications are programmed to react to the same tag value but use objects of different dimensions.

The ApplicationName.xml files for the first and second applications include the <Tags>, <Actions>, and <Launch> entries.

The ApplicationName.ObjectSets.xml file for each application contains the bounding box and offset information for the respective tagged objects.

In the …\Global\Shell subkey, EnableObjectRouting is set to 1 (enabled).

If Surface Shell (or any application other than the applications that are programmed to react to the tag) are active, the Surface software displays the object routing menu with the first and second applications' icons in it. Users can tap these two icons to open the first and second applications. In this case, Surface Shell will use the largest object dimensions to determine where to place the object routing menu UI. This may cause the object routing menu to appear slightly askew from the smaller object.

If any of the three applications that are programmed to react to this tag are active, the Surface software does not show the object routing menu, and the applications react to the tag like they are programmed to.

Developer and Administrator Responsibilities

To set up and configure object routing on a device made for Surface in a venue, both developers and administrators have specific responsibilities.

If you are the application project manager or coordinator:

  • Produce the tagged object and make sure that the appropriate tags are printed on the object or positioned on the object according to the developer's placement instructions.

If you are the developer:

  • Add the object's shape, tag orientation, and placement information in the ApplicationName.ObjectSets.xml file. (We recommend that you create an application installer that creates this XML file and sets the appropriate bounding box and offset information for the tagged object, creates the %ProgramData%\Microsoft\Surface\v2.0\ObjectSets folder, and places the ApplicationName.ObjectSets.xml there.)

  • Provide the appropriate tag visualizations so the application reacts to tag values.

  • Add the appropriate XML elements to the application's XML registration file to register for object routing.

If you are an administrator:

  • If the developer did not create an installer, or if you want to add a previously created application to the object routing menu, add the object's shape, tag orientation, and placement information in the ApplicationName.ObjectSets.xml file and add the appropriate XML elements to the application's XML registration file.

  • Turn the object routing functionality on or off on each device made for Surface.

  • Understand the deployment environment so that you can choose correctly if an application installer asks for permission to overwrite XML registration files.

Did you find this information useful? Please send us your suggestions and comments.

© 2011 Microsoft Corporation. All rights reserved.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft