Image

The event handler components of BizTalk RFID provide a method for capturing the stream of information from RFID devices. The ability to execute synchronous commands completes the device interaction story, allowing tags to be commissioned, device properties to be changed on the fly, and lights to be turned on and off via I/O ports. The term commissioning in an RFID context refers to the act of preparing an RFID tag (and accompanying label, etc.) for use. This typically involves programming the ID (for UHF tags), writing any user memory, and printing a physical label. The primary goals of this chapter are the following:

  • Establishing synchronous connections to a BizTalk RFID server
  • Managing devices from .NET applications
  • Performing common RFID-related tasks such as tag printing from .NET applications

All of the examples in this chapter will use the following baseline configuration of simulated readers (as shown in Figure 6-1). Exercise 6-1 introduces the setup of this configuration.

  • Two RFID readers (Dock Door Portal and Conveyer A)
  • One RFID printer (Warehouse A)
Image

Figure 6-1. Baseline configuration for exercises in Chapter 6

Exercise 6-1. Setting Up the Baseline Configuration

This exercise will demonstrate how to set up the baseline configuration of two simulated RFID readers and a simulated RFID printer using RFID Manager.

  1. Set up the Contoso simulator for two devices, as per Exercise 3-2.
  2. Start RFID Manager. Right-click the Devices tab and click New Device.
  3. From the Add Device wizard, select Add Single Device and click Next.
  4. From the list of available providers, select Simulator and click Next.
  5. Select the TCP connection type, with an IP address of 127.0.0.1 and a port of 8001.
  6. From the Add Device to a Group page, click Next to accept the default device group.
  7. From the Authentication page, click Next to accept the default credentials (no username, no password).
  8. When complete, the RFID Manager Devices view should be similar to the one shown in Figure 6-2.
    Image

    Figure 6-2. RFID Manager with baseline reader configuration

  9. From RFID Manager, right-click Processes and click New Process.
  10. In the New Process window, type in a process name of Chapter 6 Test, and click OK.
  11. From the “Welcome to the Bind wizard” screen that appears, click Next.
  12. From the Bind Process to Logical Devices screen, click New.
  13. From the Logical Device Name dialog, type in the name Sample Device, and click OK.
  14. In the list of logical devices in the Bind Process to Logical Devices dialog, click the check box next to Sample Device, and then click Next.
  15. In the “Configure logical device – Sample Device” dialog, click Dock Door Portal and Warehouse A in the “Devices and groups” box (shown in Figure 6-3). Then click Next.
    Image

    Figure 6-3. The Bind wizard with baseline configuration

  16. From the Configure Components dialog, click New Component.
  17. In the Add Component dialog, click the SqlServerSink component in the list of available components, and then click Add.
  18. From the Add Component Instance dialog that appears, type in an instance name of SqlSink, and then click OK. The Bind wizard should now look like Figure 6-4.
    Image

    Figure 6-4. The Bind wizard with baseline configuration for the SqlSink component

  19. Click Close to return to the Configure Components dialog, and then click Next.
  20. Click “Start the process when I click Finish,” and then click Finish to finalize the process configuration and start the process. When complete, the Processes view from RFID Manager should resemble Figure 6-5.
    Image

    Figure 6-5. RFID Manager with the Chapter 6 test project configured

Connecting BizTalk RFID to Your Application

The first step in connecting your application to BizTalk RFID is adding the necessary proxy references and using statements. The ManagementWebServiceProxies assembly exposes all of the synchronous management features provided by BizTalk RFID through a series of proxy objects (shown in Table 6-1).

  1. From Visual Studio, create your base project (typically either a Windows Forms or console application).
  2. Add the following assembly references to your project (these are typically found in C:Program FilesMicrosoft BizTalk RFIDin):
    • Microsoft.Rfid.ManagementWebServiceProxies.dll
    • Microsoft.Rfid.Design
    • Microsoft.Rfid.SpiSdk

Image

Processes

RFID processes may also be manipulated through the use of synchronous commands (via the ProcessManagerProxy class). These commands allow processes to be registered, started, and stopped. One of the common tasks in external applications relating to RFID processes is retrieving the list of active processes for use in tag simulation. The only “direct” way to push simulated events into a running process is to use the AddEventToProcessPipeline command, which requires a process and a logical device name. The code in Exercise 6-2 uses the ProcessManagerProxy class to obtain the list of processes from the BizTalk RFID server and dump the list of logical devices and event handlers assigned to each.

ImageNote This exercise requires that the baseline configuration (from Exercise 6-1) is set up and running on the target BizTalk RFID server.

Exercise 6-2. Obtaining a List of Registered Processes

This exercise will demonstrate how to obtain a detailed list of the registered processes on a BizTalk RFID server from a .NET application. It will demonstrate how to retrieve the logical devices and event handlers registered to each process. This application is set to run from the same machine as the BizTalk RFID server, but can run on another machine by changing the hostname in the ProcessManagerProxy constructor.

  1. Begin by creating a C# console application in Visual Studio .NET. Name the project SyncSample2.
  2. Add the following assemblies as project references:
    Microsoft.RFID.Design
    Microsoft.Rfid.ManagementWebServiceProxies
  3. Add the using references as shown in Listing 6-1 to the top of the Program.cs file.

    Listing 6-1. Importing the Required Namespaces

    using Microsoft.SensorServices.Rfid.Management;
    using Microsoft.SensorServices.Rfid.Design;
  4. In the Program.cs file, create a new method called DumpProcessList, as shown in Listing 6-2.

    Listing 6-2. Using the ProcessManagerProxy to Obtain a List of Registered RFID Processes

    static public void DumpProcessList()
    {
     // Create a process manager proxy
     ProcessManagerProxy pmp = new ProcessManagerProxy();

     // Obtain the list of process names
     string[] processNames = pmp.GetAllProcesses();

     foreach (string procName in processNames)
     {
      Console.WriteLine("Process {0}: --------------------------");

      DumpLogicalDevices(pmp, procName);
      DumpEventHandlers(pmp, procName);
     }
    }
  5. In the Program.cs file, create a new method called DumpLogicalDevices, as shown in Listing 6-3.

    Listing 6-3. Using the ProcessManagerProxy to Obtain a List of Logical Devices Assigned to a Process

    static public void DumpLogicalDevices(ProcessManagerProxy pmp,
        string procName)
    {
     // Get detailed information on this process
     RfidProcess process = pmp.GetProcess(procName);

     // Obtain the list of logical devices
     ICollection<LogicalDevice> logicalDevices =
    process.GetAllLogicalDevices();

     Console.Write("Logical devices: ");

     foreach (LogicalDevice d in logicalDevices)
      Console.Write(" {0},", d.Name);

     Console.WriteLine("");
    }
  6. In the Program.cs file, create a new method called DumpEventHandlers, as shown in Listing 6-4.

    Listing 6-4. Using the ProcessManagerProxy to Obtain a List of Event Handler Components Assigned to a Process

    static public void DumpEventHandlers(ProcessManagerProxy pmp,
        string procName)
    {
     // Get detailed information on this process
     RfidProcess process = pmp.GetProcess(procName);

     // Obtain the list of event handlers
     ICollection<EventHandlerDefinition> eventHandlers =
      process.GetAllEventHandlers();
     Console.Write("Event Handlers: ");

     foreach (EventHandlerDefinition eh in eventHandlers)
      Console.Write(" {0}, ", eh.ComponentName);

     Console.WriteLine("");
    }
  7. In the Program.cs file, modify the main method as shown in Listing 6-5.

    Listing 6-5. Calling the Method to Dump the Process List

    static void Main(string[] args)
    {
     DumpProcessList();
    }
  8. From Visual Studio.NET 2008, click Project, then Debug, and then Start Without Debugging. The application will execute and print the following to a command window:
    Process Testproc:
    --------------------------
    Logical devices:  Test,
    Event Handlers:  sink,

ImageNote You use the Start Without Debugging command to run the application, as it will leave the command window open until a key is pressed.

Devices

The management proxies provide full access to the list of devices configured on a BizTalk RFID server. This allows external applications to inspect the list of provisioned devices, configure devices with specific properties, and add new devices (though this would more commonly be done through RFID Manager, or automated through a PowerShell script or rfidclientconsole.exe command-line tool). One of the common tasks when implementing synchronous commands against BizTalk RFID is obtaining a list of device names (as the BizTalk RFID device name is required to open a connection before issuing commands to RFID devices).

Exercise 6-3 demonstrates how to use the synchronous API to obtain a list of all registered devices.

Exercise 6-3. Obtaining a List of Registered Devices

This exercise will demonstrate how to obtain a list of the names of registered devices on a BizTalk RFID server from a .NET application. Note that this could also be accomplished by using the rfidclientconsole.exe getalldevicestatus command (actually, both the console application and this example are using the same objects in the ManagementWebProxy library to accomplish the same task).

  1. Begin by creating a C# console application in Visual Studio .NET. Name the project SyncSample2.
  2. Add the following assemblies as project references:
    Microsoft.RFID.Design
    Microsoft.Rfid.ManagementWebServiceProxies
  3. Add the using references as shown in Listing 6-6 to the top of the Program.cs file.

    Listing 6-6. Using the ProcessManagerProxy to Obtain a List of Registered RFID Processes

    using Microsoft.SensorServices.Rfid.Management;
    using Microsoft.SensorServices.Rfid.Design;
  4. In the Program.cs file, create a new method called DumpDeviceList, as shown in Listing 6-7.

    Listing 6-7. Using the DeviceManagerProxy to Obtain a List of Devices

    public void ListDevices()
    {
     DeviceManagerProxy dmp = new DeviceManagerProxy();
     DeviceDefinition[] devices = dmp.GetAllDevices();

     foreach (DeviceDefinition device in devices)
     {
      Console.WriteLine("Device {0}: {1}",
      device.Name, device.DeviceInformation);
     }
    }
  5. In the Program.cs file, modify the main method as shown in Listing 6-8.

    Listing 6-8. Using the ProcessManagerProxy to Obtain a List of Event Handler Components Assigned to a Process

    static void Main(string[] args)
    {
        DumpDeviceList();
    }
  6. From Visual Studio.NET 2008, click Project, then Debug, and then Start Without Debugging. The application will execute, and print the following to a command window:
    Device Advanced Reader:
    <logicalDeviceInformation>
        <deviceInformationBase>
            <connectionInformation>
                <provider>Symbol</provider>
                <transportSettings>
                    <tcpTransportSettings>
                         <host>192.168.0.132</host><port>80</port>
                    </tcpTransportSettings>
                </transportSettings>
            </connectionInformation>
        </deviceInformationBase>
    </logicalDeviceInformation>

The rest of the examples in this chapter will assume that a list of physical and logical device names have been obtained from a BizTalk RFID server.

Device Management

The most commonly used synchronous commands relate to controlling and configuring RFID devices as well as printing RFID tags. The two key scenarios are callbacks from an asynchronous command handler and device control from an external application.

Synchronous callbacks are commonly used to implement business logic such as turning on lights or buzzers through I/O ports. From an event handler component, a synchronous call-back is made to an RFID device (commonly the device that raised the event, but not always) to perform an I/O change or property update.

Device control from an external application is typically used to implement scenarios such as tag printing, commissioning, or automated configuration. From a .NET application, synchronous commands are issued to an RFID device.

We’ll cover how to set up the synchronous command proxies for both .NET applications and event handler components, and manage device connections. Then we’ll walk through each of the four core synchronous command types (RFID, configuration, printing, and vendor-specific). For each of these examples, the proxy class used will be the DeviceManagerProxy; however, the same framework code will work for any of the other proxy classes.

Implementing Synchronous Calls from .NET Applications

The most common use of the synchronous commands described in this chapter is creating a stand-alone .NET application (console, GUI, etc.) that can interact with RFID devices. This provides for such functionality as synchronous tag reads, printing tags, and configuring devices.

Implementing Device Callbacks

An alternate scenario for using these commands is when performing a synchronous callback within an event handler. Take the scenario wherein the overall RFID solution must flash a light when an invalid tag read is received (e.g., a tag read indicating a type of product that doesn’t belong on the conveyer belt that the RFID reader is monitoring).

In this situation, one of the event handlers would open a connection to the reader from which the event was received and execute a synchronous command to manipulate one of the digital output ports.

Managing Device Connections

Every command issued to an RFID device requires an open device connection (either explicit or implicit). Managing these device connections is crucial to implementing a well-behaved and performant system. Many RFID devices only support a single “administrative” connection for issuing synchronous commands; as such, it is safer to treat RFID device connections like database connections—as a scarce resource. When issuing synchronous commands, follow these guidelines for establishing device connections:

  • Only hold the device connection open as long as you’re actively issuing commands. Especially in larger installations, keeping a connection open and idle may block another user (such as a system administrator) from connecting to the device.
  • If you are issuing a block of commands in close sequence, keep the connection open for the entire set. Rapidly opening and closing connections to issue a set of commands may reduce performance.
  • Wrap the DeviceConnection object in a using statement (when developing in C#) to ensure that the object is disposed of properly.
  • Use the Open method rather than OpenAdministrationConnection for normal task execution. The OpenAdministrationConnection method should be reserved for use by administrative interfaces as it can interfere with existing connections. Also, there’s no guarantee that the OpenAdministrationConnection method will be fully implemented by the device vendor, so mileage may vary.

ImageNote As a developer, you have the choice of either explicitly managing the connection (as per the preceding list) or requesting that BizTalk RFID automatically manage the connection to execute a single command. Think of this as similar to using ADO.NET TableAdapter objects vs. manually opening a DbConnection object. With the TableAdapter, the underlying ADO.NET opens a connection, executes a predetermined command, and closes the connection. BizTalk RFID device connections work the same way. If you want to execute a single command, the ExecuteDedicatedCommand method will handle the device connection. If you want to execute a sequence of commands, it is more efficient to manage the device connection manually.

The baseline code for establishing a device connection and issuing commands is shown in Listing 6-9.

Listing 6-9. Establishing a Connection to an RFID Device Through the DeviceConnection Class

using (DeviceConnection dc = new DeviceConnection(deviceName))
{
 try
 {
  dc.Open();
  // Do stuff here
  dc.Close();
 }
 catch (Exception ex0)
 {
  // Error handling and reporting
 }
}

The deviceName argument should be pulled from the list of registered devices.

Standard Commands

Standard commands are those “baked into” the Device Service Provider Interface (DSPI), and provide functionality that is common across a set of RFID devices. For example, the GetProperty command is implemented by all devices, but the PrintTag command would generally only be supported by RFID printers. The information about which devices support which standard (and extended commands) is available through the provider capability and metadata collections.

It is important to remember that not all device providers (or devices) are created equal. Different providers support different commands, and often implement them in different ways. In some situations, one provider will support multiple devices (such as devices based on the Intel R1000 chip), but not all of the devices will support the feature in question (such as I/O).

Always test your application with physical hardware to ensure that things work the way you expect. Tables 6-2 through 6-6 display the standard commands, along with a description of how they are commonly used.

Table 6-2 describes the general RFID commands, which are general purpose RFID commands that are not specific to a particular protocol or technology (such as HF or EPC Gen 2).

Image

Table 6-3 describes the UHF RFID commands. These are standard RFID commands that are more suited to UHF devices and tags.

Image

Table 6-4 describes the HF RFID commands. These are standard RFID commands that are more suited to HF devices and tags.

Image

Table 6-5 describes the commands that are used to configure and manage devices. All of the device management features provided by RFID Manager can be replicated through the use of the commands in this list. These functions are typically used when automating certain device management scenarios (such as automating the upload of new firmware to a set of devices managed by different BizTalk RFID servers).

Image

Table 6-6 describes the printing commands. There are a wide range of commands for commissioning and printing RFID tags. Most of these relate to the management of the print templates that are used to generate the physical printing, as well as the sequence of RFID data.

Image

Calling any of the standard commands follows the same general pattern:

  1. Establish a connection to the target RFID device.
  2. Create the appropriate command object (i.e., for a PrintTag command, create an instance of the PrintTagCommand class).
  3. For executing a series of commands in sequence (such as programming a set of device properties), open a connection with DeviceManagerProxy.OpenConnection and send commands with the DeviceManagerProxy.ExecuteCommandForConnection method.
  4. For executing a single command, use the DeviceManagerProxy. ExecuteDedicatedCommand method (this automatically opens and closes the required DeviceConnection).
  5. Parse the command object returned for a valid response object.

ImageNote Each of the command objects returns a specific response object. The response class types for each command are documented in the DSPI reference.

Calling several of the most commonly used standard commands is demonstrated in Exercises 6-4 through 6-7. As not every device supports all of the standard commands (e.g., it makes little sense for a reader to implement support for printing commands), some mechanism is required to determine which commands are supported by a particular device.

Each vendor is responsible for surfacing this information through the DeviceCapabilities list. This list can be accessed through the provider metadata, as shown in Exercise 6-4. To find out if a device supports a particular command, check the capabilities list. For example, if a particular device has the GetTags entry in the capabilities list, it will support the GetTags command.

Exercise 6-4. Obtaining a List of Tags Seen by the Reader (GetTagsCommand)

This exercise will demonstrate how to obtain a list of the tags currently in front of the sources (antennae) for the selected RFID reader.

  1. Open the SyncCommands project.
  2. Add the Microsoft.Rfid.Util.dll assembly.
  3. Add a using reference to the Microsoft.SensorServices.Rfid.Utilities namespace.
  4. Add the method as shown in Listing 6-10. This accepts a physical device name (see Exercise 6-3 for information on how to retrieve the list of registered device names) and executes a single GetTagsCommand method. The method then prints out the tag ID and source name to the console. Note that the tag ID is a binary array, so a helper method (from the Microsoft.Rfid.Util assembly) is used to convert it to a hex string.

    Listing 6-10. Executing the GetTags Command

    static public void ExecuteGetTags(string deviceName)
    {
     GetTagsCommand cmd = new GetTagsCommand(null);

     DeviceManagerProxy dmp = new DeviceManagerProxy();
     Command c = dmp.ExecuteDedicatedCommand(deviceName, cmd);

     cmd = c as GetTagsCommand;
     if (cmd != null && cmd.Response != null)
     {
      GetTagsResponse response = cmd.Response;
      ReadOnlyCollection<TagReadEvent> tags = response.Tags;

      Console.WriteLine("Tags Read: -----------------");
      foreach (TagReadEvent tre in tags)
      {
       Console.WriteLine("Tag {0} from source {1}",
       HexUtilities.HexEncode(tre.GetId()), tre.Source);
      }
     }
    }

    ImageNote This method does not implement error handling.

  5. Modify the main method in the Program.cs file to execute the ExecuteGetTags method, as shown in Listing 6-11.

    Listing 6-11. Calling DumpDeviceList

    static void Main(string[] args)
    {
        DumpDeviceList();
    }

Exercise 6-5. Reprogramming an EPC Tag with a New ID (WriteIdCommand)

This exercise demonstrates how to use the WriteId command to change the EPC number on a UHF tag.

  1. Open the SyncCommands project.
  2. Add the method as shown in Listing 6-12. This accepts a byte array (the new tag ID), but leaves the access and kill codes blank.

    Listing 6-12. Executing the GetTags Command

    public static void ExecuteWriteId(string readerName, byte[] id)
    {
     WriteIdCommand cmd = new WriteIdCommand(null, id, null, null);
     DeviceManagerProxy dmp = new DeviceManagerProxy();
     dmp.ExecuteDedicatedCommand(readerName, cmd);
    }
  3. Modify the main method in the Program.cs file to execute the ExecuteGetTags method, as shown in Listing 6-13.

    Listing 6-13. Calling the ExecuteWriteId Method

    static void Main(string[] args)
    {
        ExecuteWriteId("Sample Reader", new byte[] { 0x10, 0x20, 0x30, 0x40 } );
    }

Exercise 6-6. Changing the Digital Output Port Value

This exercise will demonstrate how to use the SetProperty method to manipulate the state of a digital output port on an RFID reader (that supports this feature). Most UHF readers support digital I/O, though the port and source names will differ between each specific model. The examples shown are for using any reader supporting LLRP with at least a digital output port.

  1. Open the SyncCommands project.
  2. Add the method as shown in Listing 6-14. This accepts a source name and byte value (the digital output port to change and the value to set). Note the use of the OpenConnection method to open a dedicated connection to the device. Since the SetProperty command can also apply to sources (as opposed to the device), ExecuteDedicatedCommand isn’t applicable.

    Listing 6-14. Executing the SetProperty Command

    static public void SetDigitalPort(string readerName,
        string source, byte[] val)
    {
        DeviceManagerProxy dmp = new DeviceManagerProxy();
        Guid connId = Guid.Empty;
        try
        {
            connId = dmp.OpenConnection(readerName);

            EntityProperty prop = new EntityProperty(
                new PropertyKey("Source", "Port Output Value"), val);
            Command mycmd = new SetPropertyCommand(prop);
            Command resp = dmp.ExecuteCommandForConnection(
                readerName, source, connId, mycmd);
        }
        finally
        {
            dmp.CloseConnection(readerName, connId);
        }
    }
  3. Modify the main method in the Program.cs file to execute the SetDigitalPort method, as shown in Listing 6-15. Note that the first digital output port is GPO_1 on LLRP readers, and that a digital LOW value is a byte array with a single byte value of 0.

    Listing 6-15. Calling the SetDigitalPort Method

    static void Main(string[] args)
    {
        byte[] off = new byte[] { 0 };
        SetDigitalPort("SampleReader", "GP0_1", off);
    }

Exercise 6-7. Reading the Current Timestamp (GetProperty/Time)

This exercise will demonstrate how to use the GetProperty command to read the timestamp from a device.

ImageNote The list of supported properties can be obtained from the DeviceCapability metadata, as shown later in Exercise 6-8.

  1. Open the SyncCommands project.
  2. Add the method as shown in Listing 6-16. This method uses the GetPropertyCommand method to return the timestamp from the reader, as stored in the General:Time property (Group:PropertyName is a common shorthand in BizTalk RFID).

    Listing 6-16. Executing the SetProperty Command

    private static void GetReaderTime(string readerName)
    {
        DeviceManagerProxy dmp = new DeviceManagerProxy();
        PropertyKey key = new PropertyKey("General", "Time");
        Command myCmd = new GetPropertyCommand(key);
        Command resp = dmp.ExecuteDedicatedCommand(readerName, myCmd);
        if (resp != null && resp is GetPropertyCommand)
        {
            GetPropertyResponse response =
                (resp as GetPropertyCommand).Response;
            object respValue = response.Property.PropertyValue;
            DateTime readerTime = (DateTime)respValue;
        }
    }
  3. Modify the main method in the Program.cs file to execute the GetReaderTime method, as shown in Listing 6-17.

    Listing 6-17. Calling the GetReaderTime Method

    static void Main(string[] args)
    {
        byte[] off = new byte[] { 0 };
        GetReaderTime("SampleReader");
    }

Vendor Commands

Vendor commands and properties are the extensibility points by which the unique capabilities of each hardware device are surfaced by individual vendors. Custom properties are employed to expose the full depth of the configuration experience for a specific device while maintaining a common interface. Custom commands are used to enable functionality that falls outside the standard command set, such as pulsing an I/O port. Understanding how to determine which vendor commands are available and how to invoke them is critical in taking full advantage of the unique capabilities of certain hardware devices.

Exercise 6-8 demonstrates how to retrieve the list of available vendor commands and examine the command metadata. Understanding the metadata is the key to being able to successfully invoke vendor commands, as demonstrated in Exercise 6-9.

Exercise 6-8. Retrieving the List of Vendor Commands (Provider Metadata)

This exercise demonstrates how to retrieve the metadata structure for a specific provider and dump the list of vendor commands supported by that device.

  1. This exercise will demonstrate how to obtain a list of the names of registered devices on a BizTalk RFID server from a .NET application. Begin by creating a C# console application in Visual Studio .NET. Name the project SyncSample2.
  2. Add the following assemblies as project references:
    Microsoft.RFID.Design
    Microsoft.Rfid.ManagementWebServiceProxies
  3. Add the using references as shown in Listing 6-18 to the top of the Program.cs file.

    Listing 6-18. using Statements for This Exercise

    using Microsoft.SensorServices.Rfid.Management;
    using Microsoft.SensorServices.Rfid.Design;
  4. In the Program.cs file, create a new method called DumpProviderCustomCommands, as shown in Listing 6-19.

    Listing 6-19. Obtaining the List of Vendor Metadata and Dumping the Capability List

    static public void DumpProviderCustomCommands(string provider)
    {
     ProviderManagerProxy pmp = new ProviderManagerProxy();
     ProviderMetadata meta = pmp.GetProviderMetadata(provider);
      // Dump the capability list
     Console.WriteLine("Capabilities for provider {0}", provider);
     foreach (ProviderCapability c in meta.ProviderCapabilities)
     {
      Console.WriteLine("Capability: {0}", c);
     }

     // Dump the vendor extensibility info
     DumpVendorInfo(meta.VendorExtensionsEntityMetadata);
    }
  5. In the Program.cs file, create a new method called DumpVendorInfo, as shown in Listing 6-20. This dumps out the standard command metadata components (name, description, etc.).

    Listing 6-20. Dumping the List of Vendor-Specific Commands

    private static void DumpVendorInfo(Dictionary<VendorEntityKey,
        VendorEntityMetadata> dictionary)
    {
     foreach (VendorEntityKey k in dictionary.Keys)
     {
      if (k.EntityType == EntityType.Command)
      {
       Console.WriteLine(" ----------------------");
       Console.WriteLine("Custom command: {0}", k.Name);
       VendorEntityMetadata meta = dictionary[k];
       Console.WriteLine("Description: {0}", meta.Description);

       // Some commands do not have parameters
       if (meta.SubEntities == null)
       {
        Console.WriteLine("-> No parameters");
        continue;
       }

       foreach (string parm in meta.SubEntities.Keys)
       {
        Console.WriteLine(" =======================");
        Console.WriteLine("Parameter {0}", parm);
        DumpParameterInfo(meta.SubEntities[parm]);
       }
      }
     }
    }
  6. In the Program.cs file, create a new method called DumpVendorInfo, as shown in Listing 6-21. This dumps out the standard command metadata components (name, description, etc.).

    Listing 6-21. Obtaining the List of Vendor Metadata and Dumping the Capability List

    public static void DumpParameterInfo(VendorEntityParameterMetadata meta)
    {
     // Dump the standard metadata items
     Console.WriteLine("Description: -------------");
     Console.WriteLine(meta.Description);
     Console.WriteLine(" Type:          {0}", meta.Type.Name);
     Console.WriteLine("Default:      {0}",
     meta.DefaultValue == null ? "None" : meta.DefaultValue.ToString());
     Console.WriteLine("              {0}, {1}, {2}, {3}",
     meta.IsMandatory ? "Mandatory" : "Optional",
     meta.IsPersistent ? "Persistent" : "Temporary",
     meta.IsWritable ? "Writable" : "Read-only",
     meta.RequiresRestart ? "Requires Restart" : "Immediate");

     // Dump the validation metadata (ranges, value sets, etc.)
     if (meta.Type == typeof(string))
     {
      // If the type has a valid set of values, print them
      if (meta.ValueSet != null && meta.ValueSet.Count > 0)
      {
       Console.Write("Valid values: ");
       foreach (object o in meta.ValueSet)
        Console.Write("{0}, ", o.ToString());
     }
     // If the type has a regex validation pattern, print it
     if (meta.ValueExpression != null)
      Console.WriteLine("Valid pat:  {0}", meta.ValueExpression.ToString());
     }

     if (meta.Type == typeof(int) || meta.Type == typeof(double))
     {
     if (meta.HigherRange != double.MaxValue)
      Console.WriteLine("Max value:  {0}", meta.HigherRange);
     if (meta.LowerRange != double.MinValue)
      Console.WriteLine("Min value:  {0}", meta.LowerRange);
    }
  7. In the Program.cs file, modify the main method to invoke the DumpProviderCustomCommands method as shown in Listing 6-22.

    Listing 6-22. Obtaining the List of Vendor Custom Commands

    static void Main(string[] args)
    {
     DumpProviderCustomCommands("Alien");
    }
  8. Execute the application by selecting Debug, and then Start Without Debugging, in Visual Studio. The sample output shown in Listing 6-23 is a section of the output produced when this application is run against the Alien provider. In Exercise 6-9, you will develop an application to invoke this vendor command.

    Listing 6-23. Sample Output from the Alien Provider

    Custom command: PulseOutputCommand
    Description: Sending an output impulse to the specified digital output
    port of the reader for specified time period.

    =======================
    Parameter Port
    Description:
    -------------
    String representing an Alien digital output port name (e.g.: o1, o3).
    Type:         String
    Default:      None
                  Mandatory, Persistent, Writable, Immediate
    Valid values: o0, o1, o2, o3, o4, o5, o6, o7,
    =======================
    Parameter TimeInterval
    Description:
    -------------
    Time interval in milliseconds.

    Type:         Int32
    Default:      None
                  Mandatory, Persistent, Writable, Immediate
    Max value:    30000
    Min value:    1

ImageNote This metadata shows the command PulseOutputCommand, which pulses one of the output lines on an Alien reader for a specified period of time (this command is commonly used to flash lights in a light stack). The command has two parameters. The first, TimeInterval, takes an integer value between 1 and 30000, and represents the length of time of the pulse. The second, Port, represents one of the eight output ports on the Alien device.

Exercise 6-9. Executing a Vendor-Specific Command

This exercise demonstrates how to execute a vendor-specific command. This exercise will build on the results of Exercise 6-8, using the Alien PulseOutputCommand as the reference command.

  1. Open the SyncSample2 project from the previous exercise.
  2. Add the ExecuteCustomCommand method as shown in Listing 6-24.

    Listing 6-24. Executing the Vendor Custom Command PulseOutputCommand

    public static void ExecuteCustomCommand(string readerName)
    {
     VendorSpecificInformation parms = new VendorSpecificInformation();
     parms.Add("Port", "o1");
     parms.Add("TimeInterval", 5000);

     VendorDefinedCommand cmd = new VendorDefinedCommand(
           null, "PulseOutputCommand", null, parms);

     DeviceManagerProxy dmp = new DeviceManagerProxy();
     Command resp = dmp.ExecuteDedicatedCommand(readerName, cmd);
    }

ImageNote The command and parameter names must match the metadata descriptions exactly. For example, attempting to execute the PulseOutput command rather than the PulseOutputCommand command will fail.

Common Tasks

This section covers two of the common “synchronous” tasks: printing tags (with visual labels) and simulating tag reads (for use in testing or validation).

Simulating Tag Reads

At one point or another, most developers will need to simulate a stream of RFID data in order to test or validate a particular scenario or business process. As alluded to earlier in this chapter, the AddEventToProcessPipeline command allows tag data to be pushed into a running process, providing an ideal entry point for simulated data. This section will demonstrate how to generate simulated single tag and tag list (multiple tags) events and inject them into a running process.

In order to inject simulated RFID data, the following pieces of information are required:

  • The event to simulate (such as a TagReadEvent or a TagListEvent). Generating these events is demonstrated next.
  • The name of the process into which to inject the event. This may be obtained from the ProcessManagerProxy class.
  • The logical reader source from which the event will appear to originate. This may also be obtained from the ProcessManagerProxy class.

Any object deriving from RfidEventBase may be simulated; however, the most useful types will tend to be TagReadEvent and TagListEvent objects. To generate a TagReadEvent, the tag ID (and sometimes tag data) fields are required. Creating the simulated tag data can be a little tricky (especially in scenarios with specific tag IDs or behavior), but the process of actually pushing the tags into a specific process is straightforward in its implementation.

The process of writing an application to simulate tag events is demonstrated in Exercise 6-10.

Exercise 6-10. Writing an Application to Simulate Tag Reads

This exercise demonstrates how to simulate different types of tag events using the AddEventToProcess pipeline command from a WinForms .NET application. It will tie together many of the techniques demonstrated in this chapter, including dynamic lookup of process and logical devices. The exercise will start with laying out the visual elements for the application, and then follow up with filling in the logic.

  1. From Visual Studio.NET 2008, create a new Windows Forms application called Exercise6_10, as shown in Figure 6-6.
    Image

    Figure 6-6. Creating the project

  2. Add the following assemblies as project references:
    Microsoft.Rfid.Design
    Microsoft.Rfid.SpiSdk
    Microsoft.Rfid.ManagementWebServices
  3. Open up the code-behind for Form1, and add the following using statements:
    using Microsoft.SensorServices.Rfid.Management;
    using System.IO.SensorServices.Rfid.Client;
    using Microsoft.SensorServices.Rfid;
  4. The next step is to add the necessary visuals and logic to allow dynamic selection of the process and logical device lists. Open the form designer for Form1, and do the following:
    • Add a GroupBox to the form, and call it Processes and Devices.
    • Within that GroupBox, add a label with a text value of Processes.
    • Next to the label, add a ComboBox item with a name of cbProcessList.
    • Add another label, with a text value of Logical Devices.
    • Next to the Logical Devices label, add a ComboBox item with a name of cbLogicalDevices.
    • Underneath the Logical Devices label, add a Button control with a name of btnRefresh and a text value of Refresh.
  5. In order to configure how the tag event data will be formatted (i.e., event type, number of tags, whether or not to generate user data, etc.), you’ll next add the graphical controls shown in Figure 6-7.
    Image

    Figure 6-7. The form after adding the processes and devices

  6. Add another GroupBox to the form, with a text value of Event Details.
  7. Within that GroupBox, add a radio button with a name of rbTagList and a value of “Send tags as TagListEvent.” Set the Checked property to True.
  8. Add another radio button with a name of rbTagRead and a value of “Send tags as TagReadEvent.”
  9. Add a NumericUpDown control to the Event Details group box with a name of numTagCount. Set its Maximum property to 1000 and its Value property to 1.
  10. Add a label next to the numTagCount control with a text value of Number of Tags. Your form should now look like Figure 6-8.
    Image

    Figure 6-8. Adding the event details

  11. Add a Button control beneath the Event Details group box with a name of btnSendTags and a value of Send Tags.
  12. Add a ContextMenuStrip to Form1 with a name of contextMenuStrip1. Add a single menu item with a name of miClear and a text value of Clear.
  13. Add a RichTextBox control to the side of the existing controls with a name of rtbStatus. Set its Context-MenuStrip property to contextMenuStrip1.
  14. Change the Text property of Form1 to Tag Read Simulator.
  15. Figure 6-9 shows the full tag read simulator.
    Image

    Figure 6-9. The full tag read simulator

  16. The visual components for your test application are in place. The remaining steps in the exercise deal with implementing the business logic to push simulated tag events to the selected BizTalk RFID process. Add the following variables to the class:
    private ProcessManagerProxy processProxy;
  17. Add methods to display status information in the rich text box, as shown in Listing 6-25. Since this example only uses synchronous calls, there is no need to wrap the access to the rtbStatus control in an Invoke pattern (using Control.Invoke to switch execution to the GUI thread).

    Listing 6-25. Displaying Status Information

    private void ShowMessage(string msg)
    {
     this.rtbStatus.AppendText(msg);
     this.rtbStatus.AppendText(" ");
    }

    private void ShowMessage(string fmt, params object[] vars)
    {
     ShowMessage(string.Format(fmt, vars));
    }
  18. In Form1, add an event handler for the Load event, as shown in Listing 6-26.

    Listing 6-26. Event Handler for the Load Event

    private void Form1_Load(object sender, EventArgs e)
    {
     // Initialize the proxy objects
     processProxy = new ProcessManagerProxy();

     // Load the initial process and logical device lists
     RefreshProcessLists();
    }
  19. Create an event handler for the Click event of the btnRefresh button, as shown in Listing 6-27.

    Listing 6-27. Event Handler for the Click Event

    private void btnRefresh_Click(object sender, EventArgs e)
    {
     // Refresh the process and logical device lists
     RefreshProcessLists();
    }
  20. Implement a function to retrieve the list of RFID processes and their related logical devices, as shown in Listing 6-28.

    Listing 6-28. Retrieving the List of RFID Processes

    /// <summary>
    /// Load a list of currently registered RFID processes along with the
    /// logical devices
    /// </summary>
    private void RefreshProcessLists()
    {
     ShowMessage("Retrieving process list..");
     processNames = processProxy.GetAllProcesses();
     if (processNames == null)
      processNames = new string[0];

     ShowMessage("Retrieving logical devices..");
     logicalDevices.Clear();
     foreach (string processName in processNames)
     {
      List<string> devices = new List<string>();
     RfidProcess processInfo = processProxy.GetProcess(processName);
      foreach (LogicalDevice d in processInfo.GetAllLogicalDevices())
      devices.Add(d.Name);

      logicalDevices.Add(processName, devices);
     }

     // Update the ComboBox control containing the process list
     cbProcessList.Items.Clear();
     cbProcessList.Items.AddRange(processNames);
     cbProcessList.SelectedIndex = -1;

     // Clear the logical device list (this is updated when the selected
     // index changes for the process list)
     cbLogicalDevices.Items.Clear();
    }
  21. Add a SelectedIndexChanged handler to the cbProcessList combo box, as shown in Listing 6-29. This will automatically update the list of available logical devices when the selected process changes.

    Listing 6-29. SelectedIndexChanged Event Handler

    private void cbProcessList_SelectedIndexChanged(object sender, EventArgs e)
    {
     if (cbProcessList.SelectedIndex > -1)
     {
      string procName = this.cbProcessList.SelectedItem.ToString();
     this.cbLogicalDevices.Items.Clear();
     this.cbLogicalDevices.Items.AddRange(
     this.logicalDevices[procName].ToArray<string>());

     if (cbLogicalDevices.Items.Count > 0)
      this.cbLogicalDevices.SelectedIndex = 0;
     }
    }
  22. All of the work thus far in this exercise has been to set the stage for this step—actually implementing the code to send simulated tag events into a selected process as if coming from a particular logical device. Implement an event handler for the Click event of the btnSendTags button, as shown in Listing 6-30. This will either send a tag list or send individual tag read events. The actual content of the tag events will be generated in the GenerateTagEvents method, which will be created in the next step.

    Listing 6-30. Event Handler for the Click Event

    private void btnSendTags_Click(object sender, EventArgs e)
    {
     // Must have a process selected
     if (this.cbProcessList.SelectedIndex == -1)
     {
      ShowMessage("Must select a process before sending tags");
      return;
     }
     string processName = this.cbProcessList.SelectedItem.ToString();

     // Must have a logical device selected
     if (this.cbLogicalDevices.SelectedIndex == -1)
     {
      ShowMessage("Must select a logical device before sending tags");
      return;
     }
     string logicalDevice = this.cbLogicalDevices.SelectedItem.ToString();

     // Generate a set of tag read events,
     List<TagReadEvent> tagEvents =
            GenerateTagEvents((int)this.numTagCount.Value);

     // If sending as a tag list, package them up and send to the server
     if (rbTagList.Checked)
     {
      ShowMessage("Sending {0} events to server as TagListEvent",
     this.numTagCount.Value);
     TagListEvent tle = new TagListEvent(tagEvents, "SIMULATED");
     processProxy.AddEventToProcessPipeline(processName, tle,
        logicalDevice);
     ShowMessage("Event delivered");
     }
     else
     {
      ShowMessage("Sending {0} events to server as TagListEvent",
       this.numTagCount.Value);
     int sent = 0;
     foreach (TagReadEvent tre in tagEvents)
     {
     processProxy.AddEventToProcessPipeline(processName, tre,
      logicalDevice);  
      ShowMessage("Sent event {0} of {1}", ++sent,
        this.numTagCount.Value);
      }
     }
    }
  23. Implement the GenerateTagList method, as shown in Listing 6-31. This method will generate fake EPC (96-bit ID) tag reads, all happening now with no user data.

    Listing 6-31. The GenerateTagList Method

    private List<TagReadEvent> GenerateTagEvents(int count)
    {
     // Generate a set of count TagReadEvent objects, each with a random
     // 96-bit tag ID, and a timestamp value of DateTime.Now.
     List<TagReadEvent> ret = new List<TagReadEvent>();
     System.Random rand = new Random();

     for (int i = 0; i < count; i++)
     {
      byte[] data = new byte[12]; // 96 bit / 8 bits / byte = 12 bytes
      rand.NextBytes(data);

      TagReadEvent tre = new TagReadEvent(data, TagType.EpcClass1Gen2,
       null, "SIMULATED", DateTime.Now, null, TagDataSelector.All);
      ret.Add(tre);
      }
      return ret;
    }
  24. From Visual Studio, click Debug, and then Start without Debugging. The Tag Read Simulator application will appear.
  25. In the Processes combo box, select the Test Process process.
  26. In the Logical Devices combo box, select the Dock Door Portal logical reader.
  27. In the Event Details section, select the “Send tags as TagListEvent” radio button.
  28. Select 10 for the number of tags.
  29. Click the Send Tags button (see Figure 6-10).
    Image

    Figure 6-10. Showing status in the tag read simulator

  30. In order to verify that the tags were received and processed by BizTalk RFID, open SQL Server Management Studio.
  31. From the connection screen, select the local database (localhost or .) and click Connect.
  32. Click the New Query button, and then select the rfidsink database from the drop-down list.
  33. Type in the following query, and then click Execute (or press the F5 key):
    SELECT * FROM TagEvents WHERE TagSource = 'SIMULATED'
  34. The results should resemble Figure 6-11, showing ten individual TagRead events (the SqlSink event handler component processes the TagList event into individual TagRead events before posting to the database).
    Image

    Figure 6-11. Results showing ten TagRead events

  35. Switch back to the Tag Read Simulator application.
  36. In the Event Details section, select the “Send tags as TagReadEvent” radio button.
  37. Select 5 for the number of tags.
  38. Click the Send Tags button (see Figure 6-12).
    Image

    Figure 6-12. Sent events

  39. Switch back to the SQL Server Management Studio application.
  40. Rerun the SELECT query. The results should now resemble Figure 6-13, showing five new TagRead events.
    Image

    Figure 6-13. The five new TagRead events

Conclusion

The synchronous command functionality in BizTalk RFID is the key method of creating custom applications for configuring devices, printing tags, and controlling I/O. By matching .NET applications with the interface provided by the ManagementWebProxy assembly, any of the functionality provided by RFID Manager or the rfidclientconsole.exe application can be included in your own applications.

CASE STUDY: PERSONALIZING ADVERTISING

Industry: Travel.

Overview: In many countries, organizations can display personal information about consumers as long as they are on company property. In a high-class travel agency of one European nation, customers are greeted at the door by a wall-sized display of personalized information and targeted advertising. The retrieval of this information is initiated by the read of an RFID tag embedded in the customer’s bank card (used in all transactions, including ATMs). Once the customer has been identified, the database retrieves the personalized information and calculates advertising that would appeal to this consumer based on previous transactions and travel.

Results: Customers are confronted with advertisements that appeal specifically to their needs. For instance, business travelers who frequent specific cities are shown discount fare options at hotels in areas where they have stayed in the past.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset