Managing Your POS Devices: Introduction

Windows Embedded for Point of Service (WEPOS) allows you to manage your POS devices in various ways, including:

  • Adding and deleting POS devices from machines (non-Plug and Play devices only).
  • Listing POS devices and/or service objects for particular machines.
  • Configuring a WEPOS service object (SO) to run for a particular device port (non-Plug and Play devices only).
  • Setting a default device for a POS device class.
  • Preventing a service object from running for a device.
  • Assigning a logical name by which a POS application can access the service object for a device.

POS devices are managed via a WMI provider installed on the POS device host as part of the WEPOS installation. Instructions in this Guide assume that you have already installed WEPOS.

You can access this WMI provider through the WMI API or by using the command-line tool included in WEPOS, POSDM.EXE.

© 2005 Microsoft Corporation. All rights reserved.


Changing Windows Firewall Settings to Enable Remote Device Management

The default Windows Firewall settings require you to enable remote administration before you can use POS Device Manager to manage your POS devices. To enable this functionality, you can:

  • Use a netsh firewall command in the command line, or
  • Use a script to enable the Windows Firewall remote administration feature.


Using the Command Line to Enable Remote Management

The following command line enables remote management of devices:

netsh firewall set service RemoteAdmin

Note: After the first boot of the newly installed WEPOS, the Windows Firewall service is not running. To turn it on, you must either restart the operating system or start the Windows Firewall service. You can start the Windows Firewall service from the command line or from the Control Panel.

From the command line:

  • Type net start sharedaccess and then press Enter.

From the Control Panel:

  • Click Control Panel on the Start menu.
  • Click Administrative Tools, then Component Services, then Services, then Windows Firewall, and choose options in the dialog.


Using the WMI API to Manage Devices

The WMI provider serves a WMI namespace called /root/MicrosoftPointOfService. This namespace defines four classes:

  • ServiceObject
  • PosDevice
  • LogicalDevice
  • DeviceProperty

ServiceObject represents a POS for .NET service object from a management perspective. PosDevice represents the physical device serviced by the service object. LogicalDevice represents a logical name assigned to a PosDevice, providing third-party applications with the ability to access a service object without conflicting with other applications that may also be accessing the same service object. DeviceProperty instances are name/value pairs that can be associated with a PosDevice to store optional configuration data for service objects.


The ServiceObject Class

The ServiceObject Class represents the management view of a service object.

Properties

Type and Name | Access | Key | Description
string Name | Read | X | The name of the service object.
string Type | Read | X | The POS Device Class that is implemented by the service object.
string UposVersion | Read |  | The version of the UPOS standard the service object is implementing.
string Path | Read |  | Path of the service object’s assembly.
string Version | Read |  | The version number of the service object’s assembly.
uint32 Compatibility | Read |  | The major version of POS for .NET the service object is compatible with.
string Description | Read |  | A short description of the service object.
bool IsPlugNPlay | Read |  | If TRUE, the service object supports Plug and Play.
bool IsLegacy | Read |  | If TRUE, the device is using a legacy (OPOS) service object. If FALSE, the device is using a POS for.NET service object.

Methods

Type and Name | Description
void AddDevice(string Path) | Adds a non-Plug and Play device for this service object. Path is the hardware path of the non-Plug and Play device to add.
void DeleteDevice(string Path) | Deletes a non-Plug and Play device associated with this service object. Path is the hardware path of the non-Plug and Play device to delete.


The PosDevice Class

The PosDevice Class represents a single physical POS device. The class provides properties and methods that are needed to manage that physical device.

Properties

Type and Name | Access | Key | Description
string Type | Read | X | The POS device type or category. For example, Scanner, Printer, etc.
string SoName | Read | X | The name of the service object for this physical device.
string Path | Read | X | The hardware path of a Device. For Plug and Play devices, this path comes from the Plug and Play engine. For non-Plug and Play devices, it is provided via the AddDevice method of ServiceObject. For devices using legacy (OPOS) service objects, this may be blank.
string HardwareDescription | Read |  | The device description, of the logical device, returned from the registry and used by the Plug and Play engine. This may be blank for devices using legacy (OPOS) service objects.
bool IsPlugNPlay | Read |  | If TRUE, the device is a Plug and Play device.
bool IsLegacy | Read |  | If TRUE, the device is using a legacy (OPOS) service object. If FALSE, the device is using a POS for.NET service object.
bool Enabled | Read/Write |  | If TRUE, enable the device. If FALSE, disable the device.
bool Default | Read/Write |  | If TRUE, the device is the default in a POS Device category.

Methods

Type and Name | Description
void AddName(string Name) | Adds a logical name for the device. Name is the name of the logical device to add. The name must be unique within a device class (type). Logical names are represented by the LogicalDevice class.
void DeleteName(string Name) | Deletes the logical name from the device. Name is the name of the logical device to delete. Logical names are represented by the LogicalDevice class.
void AddProperty(string Name, string Value) | Adds a property (a name/value pair) to this device. Name is the name of the property. Value is the value of the property. Device properties are represented by the Property class.
void DeleteProperty(string Name) | Deletes a property from this device. Name is the name of the property to be deleted. Device properties are represented by the Property class.


The LogicalDevice Class

The LogicalDevice class represents a logical device associated with a PosDevice. It provides a naming mechanism so that applications can be developed independently and refer to the same device without conflict.

Properties

Type and Name | Access | Key | Description
string Type | Read | X | The POS device category that the logical device belongs to.
string SoName | Read | X | The name of the service object.
string Path | Read | X | The path of the physical device.
string Name | Read | X | The name for the logical device.


The DeviceProperty Class

The DeviceProperty class represents a name/value pair of a configuration property for a physical device. There may be multiple DeviceProperties associated with a PosDevice.

Properties

Type and Name | Access | Key | Description
string Type | Read | X | The POS device category.
string SoName | Read | X | The name of the service object.
string Path | Read | X | The path of the physical device.
string Name | Read | X | The name of this property.
string Value | Read |  | The data of this property.


Using VBScript

The following VBScript code illustrates how to enumerate the PosDevice class instances, add a device, and add a name to that device.

'Get a handle to the POS namespace service into 'objServices'
Set objLocator = CreateObject("WbemScripting.SWbemLocator")
Set objServices = objLocator.ConnectServer(, "/root/MicrosoftPointOfService")

'List the POS devices
EnumeratePosDevice

'Add a name: MSRSim for Msr Simulator by retrieving the SO and invoking AddDevice() then AddName()
WScript.Echo "Add Device on COM1 and add name 'MSRSim' for MsrSimulator ..."
Set objSO = objServices.Get("ServiceObject.Type='Msr',Name='Msr Simulator'")
objSO.AddDevice "COM1"
Set objDevice = objServices.Get("PosDevice.SoName='Msr Simulator',Type='Msr',Path='COM1'")
objDevice.AddName "MSRSim"
Set objDevice = GetDevice("Msr", "MSRSim")
WScript.Echo "Added 'MSRSim' to: " & objDevice.Type & vbTab & objDevice.SoName & vbTab & objDevice.Path

'Enumerate the sClass by name
Sub EnumeratePosDevice( )
  sClass = "PosDevice"
  WScript.Echo "Enumerating " & sClass & "..." & vbCrLf
  Set collection = objServices.ExecQuery("SELECT * From " & sClass)
  For Each obj In collection
   Enabled = "DISABLED"
   if obj.Enabled = true Then
      Enabled = "ENABLED"
   end If
    WScript.Echo obj.Type & Space(15-len(obj.type)) & obj.SoName & Space(25-len(obj.SoName)) & Enabled & vbTab & obj.Path
  Next
  WScript.Echo vbCrLf
End Sub

'Return a PosDevice matching DeviceType and Name
Function GetDevice( DeviceType, Name )
  Set Logical = GetLogicalDevice( DeviceType, Name )
  objectPath = "PosDevice.SoName='" & Logical.SoName & "',Type='" & DeviceType & "',Path='" & Logical.Path & "'"
  Set GetDevice = objServices.Get(objectPath)
End Function

'Return a LogicalDevice matching DeviceType and Name
Function GetLogicalDevice( DeviceType, Name )
  Query = "SELECT * From LogicalDevice WHERE Type = '" & DeviceType & "' AND Name='" & Name & "'"
  Set collection = objServices.ExecQuery( Query )
  For Each obj In collection
    Set GetLogicalDevice = obj
    exit For
  Next
End Function

The following output results from running the VBScript shown above:

Enumerating PosDevice...

CashDrawer   CashDrawer Simulator   ENABLED
CheckScanner  CheckScanner Simulator  ENABLED
LineDisplay  LineDisplay Simulator  ENABLED
Msr      Msr Simulator      ENABLED
PinPad     PinPad Simulator     ENABLED
PosKeyboard  PosKeyboard Simulator  ENABLED
PosPrinter   PosPrinter Simulator   ENABLED
Scanner    Scanner Simulator    ENABLED
Msr      ExampleMsr        ENABLED
Scanner    Example Scanner     ENABLED

Add Device on COM1 and add name 'MSRSim' for MsrSimulator ...
Added 'MSRSim' to: Msr Msr Simulator  COM1


Using Visual Studio .NET Management Extensions and the WEPOS WMI Management Classes

A Visual Studio extension called Management (WMI) Extensions for Visual Studio .NET 2003 Server Explorer adds management services to the Server Explorer in Visual Studio .NET. Using this extension, you can navigate the root\MicrosoftPointOfService namespace and drag and drop the instances of the classes into your project’s class designer.

To download this extension, go to:

http://www.microsoft.com/downloads/details.aspx?FamilyID=62d91a63-1253-4ea6-8599-68fb3ef77de1&DisplayLang=en This feature requires Microsoft Visual Studio .NET 2003 and the Microsoft WEPOS runtimes to be installed on the local development machine.

To use the extension:

  1. Launch Visual Studio .NET 2003 and open the Server Explorer window.
  2. Expand the Servers node, and then expand the Machine node.
  3. Right-click the Management Classes node, and then choose Add Classes from the popup menu.
  4. In the Add Classes dialog, expand the root\MicrosoftPointOfService node in the Available Classes tree view.
  5. Select the DeviceProperty class, and then click the Add button to add the class to the Server Explorer. Repeat this step for the LogicalDevice, PosDevice, and ServiceObject classes.

To use the management classes:

  1. Create a .NET project.
  2. Open the Server Explorer.
  3. Right-click on the DeviceProperty node, and then choose Generate Managed Class from the popup menu to add the generated class to the project. Repeat this step for the LogicalDevice, PosDevice, and ServiceObject classes to generate managed classes.

To use an instance of a management class:

  1. In the Server Explorer, expand the desired class to list the available class objects.
  2. Drag and drop the instances onto the projects class designer.

Generating Early-Bound Classes for the WEPOS WMI Management Classes

An alternative to using the GUI to create your wrapper is to use the command-line tool called mgmtClassGen.exe. This tool will generate a .NET class wrapper for classes in a WMI namespace. This feature requires Microsoft Visual Studio .NET 2003 and the Microsoft WEPOS runtimes to be installed on the local development machine. The tool is found in the \Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin folder.

Using this tool, you can create a .NET class for the WMI root/microsoftpointofservice/PosDevice class as follows:

mgmtClassGen.exe /n root/microsoftpointofservice /l cs PosDevice

This command creates the C# class in a file called PosDevice.cs in the current directory. Create a C# command-line project and add the PosDevice.cs file to the project. Compile the following C# code against it. This code simply enumerates the PosDevices on the local machine.

Note: Before you run this sample on Windows XP Professional or Windows Embedded for Point of Service, you must install the .NET Framework v1.1 SP1.

using System;
using System.Management;
using ROOT.MICROSOFTPOINTOFSERVICE;

namespace Management
{
   public class Test
   {
      public Test()
      {
         ManagementScope scope = new ManagementScope("root\\microsoftpointofservice");
         scope.Connect();
         PosDevice.PosDeviceCollection devices = PosDevice.GetInstances(scope, "");
         string format = "{0,10}\t{1,25}\t{2}\t{3,50}";
         if( devices.Count > 0 )
            Console.WriteLine(format, "Type", "Name", "Enabled", "Path");
         foreach( PosDevice d in devices )
         {
            Console.WriteLine(format, d.Type, d.SoName, d.Enabled ? 'Y' : 'N', d.Path);
         }
      }

      static int Main()
      {
         Test t = new Test();
         return 0;
      }
   }
}


Using the POS Device Manager Command-Line Tool (POSDM.EXE)

To use the POS Device Manager Command Line Tool after Windows Embedded for Point of Service has been installed on your computer, and after the Windows Firewall settings have been changed as described in Changing Windows Firewall Settings to Enable Remote Device Management:

  • On the command line, type posdm followed by a space and then any of the commands and switches listed below.

The general syntax is:

posdm [general switches] command [command arguments]

For more information and examples of usage, see:

Command-Line Help for POSDM

General POSDM Switches

POSDM Commands

POSDM Command Arguments


Command-Line Help for POSDM

You can display information about the general usage and syntax for POSDM.EXE by typing the following on the command line:

posdm /?

To get more information about any POSDM command, type the following on the command line:

posdm help command

Example:

posdm help listdevices


General POSDM Switches

The following general switches may be used between posdm and a command on the command line:

Switch | Description
/? | Displays posdm help information.
/output:file | Prints all output to file instead of to the console.
/machine:host | Uses host as the remote machine. Default is the local machine.
/user:username | Uses username as the user account. Prefix with domain separated by a backslash if the user domain is not the current one.
/password:password | Uses password with the specified username account.


POSDM Commands

POSDM has the following commands.

Command Description Syntax and Examples
adddevice Adds a physical non-Plug and Play device. posdm [general switches] adddevice path filter [/info]

where path is a hardware path of the physical device,

filter is one or more of the following:

/type:devicetype

/soname:soname

and

/info is an optional switch that displays all device properties

Example:

posdm adddevice COM3 /soname:MsrSimulator

This adds a device with the hardware path COM3 to the MsrSimulator service object.
addname Adds a logical name to a device. This allows multiple applications to reference a device without interfering with each other. posdm [general switches] addname devicename filter

where devicename is the logical name to give to the device, and filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

Example:

posdm addname MainMSR /type:MSR /path:COM3

This adds the logical name MainMSR for the MSR device on the COM3 hardware path.

posdm addname BackupMSR /name:MainMSR

This adds the logical name BackupMSR for the device named MainMSR.
addproperty Adds a configuration property to a device. posdm [general switches] addproperty propertyname value filter [/info]

where propertyname is the name of the property and value is the initial value for that property, and filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

/info is an optional switch that displays all device properties

Example:

posdm addproperty PrintSpecialGreeting "Happy New Year!" /name:MainMSR

This adds the PrintSpecialGreeting property with the value of "Happy New Year!" to the device named MainMSR.
deletedevice Deletes a physical non-Plug and Play device. posdm [general switches] deletedevice [path] filter

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

Example:

posdm deletedevice COM3 /type:Msr

This deletes the MSR device on COM3.

Only devices previously added by the adddevice command can be deleted.
deletename Deletes a logical name from a device's list of names. posdm [general switches] deletename devicename filter [/info]

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

and

/info is an optional switch that displays all device properties

Example:

posdm deletename "Main Scanner" /type:Scanner /path:COM3

This deletes the logical name Main Scanner for the scanner device on the COM3 path.

Only logical names previously added by the addname command can be deleted.
deleteproperty Deletes a configuration property from a device. posdm [general switches] deleteproperty propertyname filter [/info]

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

and

/info is an optional switch that displays all device properties

posdm deleteproperty PrintSpecialGreeting /name:MainMSR

This deletes the PrintSpecialGreeting property from the device named MainMSR.

Only configuration properties previously added by the addproperty command can be deleted.
disable Prevents a service object from running for a physical POS device. posdm [general switches] disable filter

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

Example:

posdm disable /name:ReceiptPrn

This prevents a service object from running for a device named ReceiptPrn. As a result, applications will not see the device in the list of available POS devices.
enable Permits a service object to run for a physical POS device. posdm [general switches] enable filter

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

Example:

posdm enable /type:MSR

This permits a service object to run for all MSR devices.
info Displays information about the device, including its configuration properties. posdm [general switches] info filter

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

Example:

posdm info /name:MSR1

This command displays information about a device with the logical name “MSR1.”
listdevices Lists the physical POS devices. posdm [general switches] listdevices [/type: devicetype]

where the optional /type: devicetype switch narrows the list to a particular type of device.

Examples:

posdm listdevices

This displays a list of all physical POS devices installed on the local machine.

posdm listdevices /type:MSR

This displays a list of all MSR devices installed on the local machine.

posdm /machine:Center10 /username:JohnDoe3 /password:B$tg59ce listdevices

This lists all physical POS devices installed on the machine named Center10, after logging in with username and password credentials.
listnames Lists the logical names associated with POS devices. posdm [general switches] listnames filter

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

Example:

posdm listnames /type:MSR /path:COM3

This displays a list of names associated with the MSR device on COM3.
listprops Lists the configuration properties associated with a POS device and their values. posdm [general switches] listprops filter

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

Example:

posdm listprops /type:MSR /path:COM3

This displays a list of property names and values associated with the MSR device on COM3.
listsos Lists the POS service objects on the target machine. posdm [general switches] listsos [/type: devicetype]

where the optional /type: devicetype switch narrows the list to a particular type of device.

Examples:

posdm /output:a:\solist.txt listsos

This writes a list of all service objects installed on the local machine to a file named solist.txt on the A drive.

posdm listsos /type:MSR

This displays a list of all service objects associated with MSR devices on the local machine.

posdm /machine:Center10 /username:JohnDoe3 /password:B$tg59ce listsos

This lists all service objects on the machine named Center10, after logging in with username and password credentials.
setdefault Sets one device as the default of its type.

The default flag directs the PosExplorer.GetDevice(type) method to return this device even if there is more than one device of the type available.

 posdm [general switches] setdefault ON|OFF filter [/info]

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

The optional /info switch causes all device properties to be displayed.

Example:

posdm setdefault ON /name:FirstScanner

This example designates FirstScanner as the one the CCL device enumeration will find.
setpath Sets the POS device path for non-Plug and Play devices. posdm [general switches] setpath hardware_path filter

where filter is one or more of the following needed to uniquely identify a device:

/type:devicetype

/soname:soname

/path:hardware_path

/name:devicename

Example:

posdm setpath COM2 /type:MSR

This sets the hardware path for MSR devices to COM2.

The setpath command works only for non-Plug and Play devices previously added with the adddevice command.


POSDM Command Arguments

The following switches can be used as arguments for POSDM commands.

Command Switch | Description
/type:devicetype | The device type as determined by the service object supplier. Example: /type:msr specifies a magnetic strip reader.
/soname:soname | The service object name from the service object supplier. Names containing spaces must be enclosed in double quotation marks ("). Example: /soname:"Super MSR" specifies a service object named Super MSR
/path:hardware_path | The hardware path for the device. Example: /path:COM2 specifies a location of COM2.
/name:devicename | The logical name for the device. This is useful when there are multiple instances of the service object, and also provides a way for an application to refer to an service object without hardcoding. This name must be unique within devicetype. If a name contains a space, it must be contained within double quotation marks ("). Examples: /name:msr4 refers to a device with the logical name msr4, /name:"Main MSR" refers to a device with the logical name of Main MSR.


Legal Notice

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2005 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, Windows Server, Active Directory, ActiveSync, ActiveX, Direct3D, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, FrontPage, HighMAT, JScript, Microsoft Press, MSN, Outlook, PowerPoint, Visual Basic, Visual C++, Visual InterDev, Visual J++, Visual Studio, WebTV, Windows Media, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

This product contains graphics filter software; this software is based in part on the work of the Independent JPEG Group.

All other trademarks are property of their respective owners.

The links in this area will let you leave Microsoft's site. The linked sites are not under the control of Microsoft and Microsoft is not responsible for the contents of any linked site or any link contained in a linked site, or any changes or updates to such sites. Microsoft is not responsible for webcasting or any other form of transmission received from any linked site. Microsoft is providing these links to you only as a convenience, and the inclusion of any link does not imply endorsement by Microsoft of the site.


Using Group Policy Editor (GPEDIT.MSC) to Enable Remote Management

To use the Group Policy Editor (GPEDIT.MSC) to enable remote management of POS devices:

  1. Under the Local Computer Policy heading, open the Computer Configuration folder.
  2. Open the Administrative Templates folder.
  3. Open the Network folder.
  4. Open the Network Connections folder.
  5. Open the Windows Firewall folder.
  6. If the computer is in the domain, then open the Domain Profile folder; otherwise, open the Standard Profile folder.
  7. Click the Windows Firewall: Allow remote administration exception item.
  8. Click the Action menu and select Properties.
  9. Click Enable, and then click the OK button.

Note: If the user is not an administrator but has Remote Enable permission on the local computer, then the user also must be given DCOM Remote Launch privilege on The local computer by running Dcomcnfg.exe at the command line. The 0x80070005 error occurs when this privilege is not set. For more information, see Administrator and Non-Administrator Access to WMI.

The connection from the local computer is required only when the client script or application makes an asynchronous call to the remote computer. Whenever possible, semi-synchronous calls should be made instead. Performance of semi-synchronous calls is nearly as good as asynchronous, and the call is more secure.