Embed Size (px)
Citation preview
TagCentric User’s Manual
Table of Contents1 What is TagCentric?.................................................................................................................................12 Running the TagCentric User Interface....................................................................................................2
2.1 Initial Execution of TagCentric........................................................................................................22.2 Mode of Operation for User Interface..............................................................................................22.3 Shutting Down the User Interface....................................................................................................3
3 TagCentric Administration (Admin Panel)..............................................................................................43.1 Starting and Stopping the Database Agent.......................................................................................43.2 Reader/Printer Agent Launchpad.....................................................................................................53.3 Managing Reader Information.........................................................................................................5
3.3.1 Adding a New Reader..................................................................................................................63.3.2 Modifying Reader Information.....................................................................................................63.3.3 Deleting Reader Information........................................................................................................7
3.4 Managing Printer Information..........................................................................................................73.4.1 Adding a New Printer...................................................................................................................73.4.2 Changing Printer Information.......................................................................................................83.4.3 Deleting Printer Information........................................................................................................8
3.5 Refreshing the Admin Panel.............................................................................................................84 TagCentric Testing (Test Panel)...............................................................................................................9
4.1 Real-Time Tag Reporting.................................................................................................................94.2 Running Tests...................................................................................................................................94.3 Managing the Company List..........................................................................................................104.4 Managing the Test Type List..........................................................................................................11
5 Database Panel........................................................................................................................................135.1 Launching the DBAgent.................................................................................................................145.2 Terminating the DBAgent..............................................................................................................145.3 Basic database operations...............................................................................................................15
5.3.1 Database initialize......................................................................................................................155.3.2 Database Update.........................................................................................................................16
5.4 The “Convert EPC Tags” checkbox...............................................................................................175.5 Information about the database......................................................................................................17
5.5.1 Schema Version..........................................................................................................................175.5.2 Connection Information..............................................................................................................185.5.3 Status..........................................................................................................................................19
5.5.3.1 OK status............................................................................................................................195.5.3.2 Version Mismatch: Old code detected...............................................................................195.5.3.3 Version Mismatch: UPDATE REQUIRED.......................................................................205.5.3.4 Uninitialized DB: Initialize to continue.............................................................................215.5.3.5 Initialize failed....................................................................................................................215.5.3.6 Update Failed......................................................................................................................22
5.6 Querying the Database...................................................................................................................235.6.1 Ad Hoc Queries..........................................................................................................................235.6.2 Stored Queries............................................................................................................................245.6.3 Pre-made Queries.......................................................................................................................245.6.4 Storing Queries...........................................................................................................................245.6.5 Parameterized Queries................................................................................................................24
5.6.5.1 Stored Query Formatting....................................................................................................245.6.5.2 Stored Query Parameter Creation.......................................................................................255.6.5.3 Stored Query Parameter Types...........................................................................................255.6.5.4 Stored Query Parameter Dependencies..............................................................................25
6 Reader Control (Reader Panel)...............................................................................................................266.1 Event Logging................................................................................................................................276.2 Tag Types.......................................................................................................................................276.3 Filtering Reads................................................................................................................................276.4 Poll Period......................................................................................................................................27
ii
6.5 Enabling/Disabling the Reader.......................................................................................................286.6 Terminating the Reader Agent.......................................................................................................28
7 Printer Control (Printer Panel)................................................................................................................297.1 Status Information..........................................................................................................................297.2 Starting Print Jobs...........................................................................................................................307.3 An Example....................................................................................................................................31
8 Caveats and Recommendations..............................................................................................................348.1 Basic Requirements for TagCentric Operation..............................................................................348.2 One GUI up at a time (recommended)...........................................................................................348.3 Use a Local Database.....................................................................................................................348.4 Database Operations: You Have The Power..................................................................................348.5 Beware of nebulous networking situations.....................................................................................348.6 Very High Tag-Read Rates Not Tested..........................................................................................358.7 EPCIS-Compatilbility.....................................................................................................................35
9 Notes on Specific Readers......................................................................................................................3610 A Step-by-Step Recipe for Getting Started............................................................................................37
10.1 Installing TagCentric......................................................................................................................3710.2 Running TagCentric.......................................................................................................................39
10.2.1 Initializing the database..........................................................................................................4010.2.2 Adding a Reader.....................................................................................................................4110.2.3 Reader Operations..................................................................................................................4510.2.4 Shutting Down the Dashboard................................................................................................47
11 Troubleshooting......................................................................................................................................4811.1 Admin Panel...................................................................................................................................4811.2 Reader Control................................................................................................................................4811.3 Database Panel................................................................................................................................4811.4 Printer Control................................................................................................................................4811.5 When All Else Fails........................................................................................................................48
12 Planned Enhancements...........................................................................................................................50
iii
1 What is TagCentric?TagCentric is software written for the purpose of controlling RFID devices and gathering RFID-related data in a facility. It allows the user to seamlessly interact with multiple brands of RFID readers, and to collect data into a user-specified database. TagCentric also allows the user to print and encode RFID tags, through the use of a Zebra printer. While TagCentric may not have all of the “bells and whistles” of some of the commercially available RFID middleware solutions, it’s cost (free!) and simplified user interface make it ideal for use by small businesses, RFID testing facilities and universities.
Throughout this document, we will refer to device controllers as “agents”. The TagCentric software allows the user to communicate with agents; the agents, in turn, communicate with their respective devices. Through TagCentric, a user will launch an agent (like a reader agent, or a printer agent, or a database agent) and the agent will establish communications with its target device.
Currently, TagCentric provides support for these types of readers: Alien, Symbol and ThingMagic. In addition, TagCentric provides a “Fake” reader, which can be instantiated and used for testing in the absence of actual readers.
TagCentric can connect to a number of different database types; currently, we support DB2, MySQL, Oracle, PostgreSQL, and the Java “DRB” embedded database. During the TagCentric installation process, the user can specify a connection to their database of choice either through ODBC or straight JDBC.
For tag printing, we offer limited support of the Zebra RFID printer. While we do not support all of the capabilities of the Zebra printer, we do allow users to print out textual information and an incrementing tag number on each label.
For a good description of the recommended modes of operation for TagCentric, see the “Caveats and Recommendations” appendix of this document.
iv
2 Running the TagCentric User InterfaceTo start the TagCentric user interface, run the “startup.bat” (for Windows) or “startup.sh” (for Unix/Linux) script in the “bin” directory of the TagCentric installation tree. From Unix/Linux, you may need to perform a “chmod +x startup.sh” to render the startup.sh script executable.
2.1 Initial Execution of TagCentricInitially, TagCentric has an empty database. During initial operation, the user needs to:(1) Start the database agent. This is done by pressing the “Start” button next to the “Database Agent:”
label in the Admin panel.(2) Initialize the database. This can either be done by pressing the “Initialize Database” button on the
Admin panel, or pressing the “Initialize” button in the Database panel. Initializing the database creates all of the tables and rows necessary for proper TagCentric operation.
After initializing the database, the user should then enter facility-specific information into the database describing the readers and printers available for use. This is done via the “Manage Reader Info” and “Manage Printer Info” buttons on the Admin panel; these are described in detail in the section entitled “TagCentric Administration”.
2.2 Mode of Operation for User InterfaceThe following screen shot shows the general look-and-feel of the user interface:
On the left, the currently active panels are arranged in a tree fashion (referred to as the “panel tree”). The leaf nodes all represent panels that correspond to active agents1. The panel displayed in the main viewing area corresponds to the current user selection from the panel tree. For example, by selecting “Fake-2” from the panel tree in the above example, a reader panel (corresponding to the reader named “Fake-2”) would be displayed on the right.
1 The “Local” panels are an exception to this policy. The Admin and Test panels do not correspond to any particular agent; they are more like applications.
v
Pressing the “Launch” button (in the Reader/Printer Agent Launchpad section) for an agent results in that agent being activated and a corresponding entry being created in the panel tree. Pressing the “Kill” button for an agent results in the agent being deactivated and its corresponding entry in the panel tree being removed.
2.3 Shutting Down the User InterfaceShutting down the TagCentric user interface application is as easy as pressing the “X” icon in the upper right-hand corner of the frame. However, keep in mind that agents are launched in such a way as to be persistent across the shutting down of the user interface. If you have active agents at the time that you shut down the user interface, those same agents will show up as active the next time that you launch the user interface. To shut down agents, you must explicitly kill them from the Admin panel.
vi
3 TagCentric Administration (Admin Panel)The Admin Panel is the primary user interface to the TagCentric application. It allows the user to manage reader and printer information as well as launch database, reader and printer agents.
(Editor’s Note: Just prior to release, we decided to remove the “Initialize Database” button from the Admin Panel. So, our Admin Panel screen shots are slightly inaccurate. Functionally, the Admin Panel still behaves as described in this document.)
3.1 Starting and Stopping the Database AgentBy pressing the “Start” button to the right of the “Database Agent:” label, the user can start the database agent2. Since all other operations on the panel rely on the existence of a database agent, no other operations are possible until the database agent is started. To stop an active database agent, press the “Stop” button to the right of the “Database Agent:” label. The “Start” button will only be enabled if no database agent is detected; the “Stop” button will only be enabled if a database agent is up and running. Before the database agent is started, the Admin panel looks like this:
2 A word of caution about launching database agents: The reference database for the TagCentric system will be the database specified during installation of the software that launched the database agent. In other words, suppose you install TagCentric instance A on host 1, specifying database X. Also suppose that you install TagCentric instance B on host 2, specifying database Y (different than X). If you launch the database agent via the TagCentric Dashboard running on host 1, then database X will be used by the entire TagCentric application. On the other hand, if you launch the database agent via the TagCentric Dashboard running on host 2, then database Y will be used by the entire TagCentric application. This is potentially a source of great confusion, as the databases could contain different readers, printers, company names, etc... It is advised that either you always launch the database agent from the same host, or that all TagCentric installations in your facility specify the exact same database.
vii
3.2 Reader/Printer Agent Launchpad
This section lists all known reader and printer agents, and provides a “Launch” button for each agent that is not currently active, and a “Kill” button for each agent that is currently active. Any agent that has been entered into the database shows up in this list. By pressing an agent’s “Launch” button, the agent becomes activated and shows up in the panel tree on the left of the window. By pressing an agent’s “Kill” button, the agent deactivates and is removed from the panel tree.
3.3 Managing Reader InformationIn order to make the system aware of the existence of RFID readers, information about the readers must be entered into the database. Pressing the “Manage Reader Info” button will allow you to manage the reader information in the database. Upon pressing this button, the following dialog appears:
viii
From here, the user can add new reader information, delete reader information, or modify existing reader information. When you are done managing reader information, press the “Exit” button.
3.3.1 Adding a New ReaderPressing the “Add New Reader” button in the “Manage Reader Information” dialog results in the following dialog box appearing:
The user needs to specify the following for each reader entered: ReaderName: A textual name for the reader, for easy
human identification of the reader. ReaderIPAddr: The IP address of the reader. ReaderClassID: The general class of the reader.
Choices include “No Class Specified”, “DOCK DOOR”, “CONVEYOR BELT”, “SALES FLOOR”, “POINT-OF-SALE”, and “CRUSHER”.
ReaderTypeID: The reader type. Supported values include “Fake”, “Symbol”, “Alien”, and “ThingMagic”.
Once the user is satisfied with the information entered, she can press the “Commit” button to enter the information into the database. The user can exit the
dialog any time (without committing to the database) by pressing the “Abort” button.
A note on “Fake” readers: You will need to provide an IP address for your “fake” readers, just like your “real” readers. However, the IP address associated with a fake reader will simply be a placeholder, and a way to distinguish one fake reader from another. Since there is no actual device associated with a fake reader, it’s IP address is never used for actual communications.
3.3.2 Modifying Reader InformationFrom the “Manage Reader Information” dialog, it is also possible to modify information about an already-existing reader. To do this, double-click one of the data rows displayed in the dialog; the following dialog will appear:
The “Modify Reader” dialog is very similar to the “Insert Reader” dialog. You can change any or all of the fields and press “Commit” to commit the changes to the database, or you can press the “Abort” button to abort the reader modification operation.
ix
3.3.3 Deleting Reader InformationFinally, it is possible to delete reader information from the “Manage Reader Information” dialog. Select one or more rows to delete and press the “Delete Selected Row(s)” button.
3.4 Managing Printer InformationThe user can manage printer information in the TagCentric database by pressing the “Manage Printer Info” button in the Admin panel. When this button is pressed, the following dialog appears:
The dialog lists information about all known printers. From here, the user can add information for a new printer, delete printer information, or modify information about an existing printer. When you are done modifying printer information, press the “Exit” button.
3.4.1 Adding a New PrinterBy pressing the “Add New Printer” button in the “Manage Printer Information” dialog, the following dialog pops up:
You must provide a name, an IP address, and a printer type for the newly added printer. Currently, the only available printer type is “Zebra”.
You cannot fill in the Printer ID field, as that value is determined by the TagCentric software.
x
When done, press the “Commit” button to commit the new printer information into the database. At any time, press the “Abort” button to abort the transaction.
3.4.2 Changing Printer InformationBy double-clicking a data row in the “Modify Printer Information” dialog, you can change the information contained in the given row. Such an action results in the following dialog being popped up:
From here, you may change information in any of the fields that describe this printer (except, of course, the Printer ID field).
When done, press the “Commit” button to commit the changes to the database. At any time, press the “Abort” button to abort the transaction.
3.4.3 Deleting Printer InformationYou may delete printer information from the database by selecting one or more rows to delete in the “Modify Printer Information” dialog, then pressing the “Delete Selected Row(s)” button.
3.5 Refreshing the Admin PanelOccasionally, the agents included in the “Reader/Printer Agent Launchpad” might get out of sync with respect to reality. Pressing the “Refresh” button will re-synchronize this list with the actual contents of the database.
xi
4 TagCentric Testing (Test Panel)The TagCentric Test Panel looks like this:
4.1 Real-Time Tag ReportingThe main area of the panel serves as a real-time view of the tag-read events that are occurring in the system. The contents of this area can be cleared by pressing the “Clear Table” button on the bottom of the panel.
4.2 Running TestsFirst, we should define here what we mean by a “test”. Our concept of RFID testing has been heavily influenced by the testing that occurs at the University of Arkansas RFID Center. Each of their tests involves one or two static readers. A pallet of boxes with attached RFID tags is transported through the read zone(s) of the reader(s) in question a number of times. Afterward, tag-read results are analyzed to determine the effectiveness of the readers in dealing with that particular pallet of goods.
To begin a test, press the “Start Test” button on the bottom of the Test Panel. The following dialog will appear:
xii
Before actually commencing the test, you are asked to provide the following information: Test Name . Assign a human-readable name to the specific test to be performed. Company . Which company’s product is being tested? To add companies to this list, use the “Manage
Companies” button on the Test Panel. Test Type . Is this an instance of a general test type? To add test types to this list, use the “Manage
Test Types” button on the Test Panel. Reader 1 . Choose a reader to associate with this test. Reader 2 . Choose a second reader to associate with this test.
At any point, the user can cancel the test by pressing the “Cancel” button.
When you are ready to commence the test, press the “Commence” button. The following dialog box will pop up:
When you are ready to run the pallet through the read zone, press the “Start Run” button. When the pallet is through the read zone, press the “Stop Run” button. Repeat this for as many trips through the read zone as desired. Each time that you stop a run, the “Run Number” value will be incremented. When you are
xiii
done with the final trip through the read zone (and have pressed “Stop Run”), then press the “End Test” button.
At the end of your test, your test description information is stored in the “TestData” table in the database. The start and stop times for each run are stored in the “RunData” table in the database. The tag-read information collected during the run is placed in the “TagData” table as usual. By running queries involving these three tables, the test results can be analyzed.
4.3 Managing the Company ListThe user can manage the list of companies available in the “Start Test” dialog by pressing the “Manage Company Info” button in the Test Panel. Upon pressing it, the following dialog is presented:
Pressing the “Add New Company” button will allow you to enter a new company name into the list. Double-clicking the row for an existing company will allow you to change the name of that company. Finally, you can delete companies from the list by selecting one or more rows and pressing the “Delete Selected Row(s)” button. When you are finished, hit the “Exit” button.
4.4 Managing the Test Type ListThe user can manage the list of companies available in the “Start Test” dialog by pressing the “Manage Company Info” button in the Test Panel. Upon pressing it, the “Manage Test Type Information” dialog seen below is presented to the user.
Pressing the “Add New Test Type” button will allow you to enter a new test type into the list. Double-clicking the row for an existing test type will allow you to change the name of that test type. Finally, you can delete test types from the list by selecting one or more rows and pressing the “Delete Selected Row(s)” button. When you are finished, hit the “Exit” button.
xiv
xv
5 Database PanelThe database agent, also known as the DBAgent, is an integral part of the TagCentric application. The application communicates with the database through the DBAgent. The graphic user interface that contains the controls for and the information about the database being used by the DBAgent is known as the database panel. It should be noted that at a given time, in a local area network, there can be only one DBAgent running. All the users in the LAN connect to that particular DBAgent. Hence, it is not possible for separate users to launch their own DBAgent. To illustrate this scenario, let us consider a user A connecting to a database DB. This scenario is portrayed below:
Database
User A
D DB
Figure 1: A single user connecting to the database
Now let us consider another two users B and C launching the application. These two users automatically connect to the DBAgent that was already launched by user A. The figure below illustrates this scenario:
User A
Database
User B
DB
User C DBAgent launched by A
Figure 2: Multiple users connecting to the database
xvi
Database panel DBAgent
Database panel DBAgent
Database panel
Database panel
5.1 Launching the DBAgentThe database agent can be launched by following the following steps:
1. Launch the TagCentric application.2. Click the Start button to the right of the “Database Agent:” label on the Admin Panel.
The DBAgent gets launched and connects to the configured database. The type of database (for instance Postresql or Oracle etc.) appears on the left-hand side as portrayed in the figure below.
The database panel can be accessed by selecting the database type (“Derby Embedded” in the screen shot below) from the panel tree on the left. The database panel in turn contains an Admin tab and a Query tab. While the query tab helps the user save, load and execute queries, the admin panel facilitates operations on the database (these operations are discussed later on) and provides information about the database and database agent. A typical screenshot of the database panel is provided below.
Figure 3: Admin Panel:
Click on the database type (“Derby Embedded”, here) to see Database Panel
5.2 Terminating the DBAgentThe DBAgent can be stopped in two different ways. The first method is stop the DBAgent from the Admin Panel by clicking the “Stop” button to the right of the “Database Agent:” label. Alternatively, one can stop the DBAgent by clicking the terminate button in the Database Administration Panel as illustrated below:
xvii
Figure 4: The Terminate button in database panel Admin tab
5.3 Basic database operationsThere are two operations supported by the Admin tab in the Database Panel: Initializing the database and updating the database.
5.3.1 Database initialize.The database initialize operation allows the user to ‘set up’ (or ‘clean up’) the entire database with the click of a button. All the tables (and the data within) are deleted and new tables created in their place. To initialize a database, click on the Initialize button in the admin tab of the database panel as shown:
xviii
It should be noted that initialization causes the entire data residing in the database to be deleted. Hence, this operation should be used judiciously by the user. To prevent unintentional initialization, a warning message pops up to confirm if the user wants to go ahead with the initialization. Click ‘OK’ on the pop up message only if you are sure want to continue the initialization procedure.
5.3.2 Database Update.There can occur circumstances in which a user connects to database that employs an old schema version (as compared to the one the user’s code expects). The update operation enables a user to bring the schema to the newer (the one which user’s code expects). The update operation, unlike the initialize, does not erase previous data residing in the database. To update a database, click the Update button in admin tab. The user can alternatively initialize the database as well. This would create the new set of tables in accordance with the latest schema version but would, however, erase the entire current contents of the database.
xix
Figure 5: Click on the Update button to upgrade schema
The update operation is mandatory under some circumstances and is not available to the user under some other circumstances. These circumstances are discussed in detail in the Information on database section of this document.
5.4 The “Convert EPC Tags” checkboxThis checkbox is experimental and relatively untested. If this box is checked, the database agent will extract EPC-related fields out of each tag reported, and store those values in a separate table. For now, check this box at your own risk.
5.5 Information about the databaseApart from providing the user with options to terminate, update and initialize the database, the admin tab in the database panel presents the user with information about the database to which the user is currently connected. The information displayed includes the schema version that is followed by the database, connection information and the status of the database.
5.5.1 Schema VersionThe schema version is displayed on the top of the Database Panel Admin tab. It is basically a number that indicates the schema that the current database is using. These version numbers are incremented every time an update is made to the schema.
Figure 6: Panel showing Schema Version 4
It should be noted that for databases that are yet to be initialized for the first time (i.e. when a user connects to fresh database without any tables), there exists no version for the database.
xx
Figure 7: Panel indicating that database is not yet initialized
5.5.2 Connection Information.The connection information basically displays the JDBC URL used to connect to the database. This information provides the user with the type of database being used, the database name and the machine and port number on which the database is currently running (file directory of the database in case of Derby). The following figure displays the information about a Derby database:
Figure 8: Panel showing connection information to “Derby” database
Care is taken to hide the username and password being used to connect to the database. However, in case of Oracle, some information pertaining to the same may be displayed in the admin tab.
xxi
5.5.3 StatusStatus displays to the user the condition of the database connection. There are six different status messages that may be encountered depending on the state of the database, which shall be explained in the ensuing subsections.
5.5.3.1 OK statusIf an OK status is displayed, the database connection and state can be interpreted to be all right and the user can proceed with using the connection.
Figure 9: Database Panel showing “OK” status
5.5.3.2 Version Mismatch: Old code detectedAn old code detected message indicates that the code being used by the user employs a schema version that is older than that present in the database. As shown in the following screen shot, some operations are disabled in such circumstances. The user can however, continue using the database. Hence, the TagCentric application is backward compatible as far as code using older schema is concerned. The only option available to the user to acquire code employing the latest schema is to download and install the latest version of the TagCentric application.
xxii
Database Panel showing Version Mismatch (old code)
5.5.3.3 Version Mismatch: UPDATE REQUIREDThe aforementioned status is displayed when a old schema version in the database (with respect to the code version) is detected. This would mean that queries and data dependent on the newer versions of schema will be unavailable to the user (due to their absence in the database). The only option available to the user under such a scenario is to update the database. The following screen shot illustrates such a scenario. As can be noticed, the query tab and the initialize button are disabled. Hence, the user has to either update the database to the newer schema (as recommended) or terminate and quit.
Database Panel showing Version Mismatch (old schema)
xxiii
5.5.3.4 Uninitialized DB: Initialize to continueThis scenario is encountered when a user connects to a totally fresh (i.e. lacking any TagCentric specific tables) database. This occurs typically when the database is being connected to for very first time. The user, under such circumstances should first initialize the tables to create all the tables expected by the application.
Database Panel showing Uninitialized Database
5.5.3.5 Initialize failedThis status is displayed whenever an initialization operation failed. The user should consult the logs (found under TagCentric_Home\logs) to ascertain the exact cause of the failure.
xxiv
Database Panel and op-up signifying Failed Initialization
5.5.3.6 Update FailedAt times, the update operation can fail due to a variety of reasons. Here again, the user should consult the logs to know the reason for the failure.
Database Panel showing Failed Update message and pop-up
xxv
5.6 Querying the Database
The “Query” sub-panel of the Database Panel allows the user to query the database and view the results of queries.
5.6.1 Ad Hoc Queries
The database query panel allows the user to run arbitrary SQL queries against the database. If the query returns results, the results will be populated in a table beneath the query text field.
Please note that there are no restrictions on what the user can do through the query panel. This includes inserting, updating, and deleting rows as well as modifying the schema or dropping tables.
xxvi
5.6.2 Stored Queries
The Tagcentric RFID Middleware application has a flexible stored query feature that allows users to store static queries as well as parse values into queries dynamically. After installation, the software has five pre-made queries that are useful for analyzing test runs.
5.6.3 Pre-made Queries
The pre-made queries are available from the database panel by selecting the load query button. A dialogue will ask you to select from the stored queries based on the description. Once a query is selected, the application will as for the test id you wish to analyze. If there are tests in the database, this will be a dropdown list of all tests. If no tests are in the database, you will be given a text field to enter the test id. However, if this is the case, none of the queries will return any values.
The following queries are available after installing the software:
All Test Reads—This query returns all the information from the TagData table for all reads during a test, ordered by run id.
Distinct Test Reads—Returns the raw RFID reads from a test, eliminating duplicates, ordered by run id.
Tag Read Counts For Test Per Run—Returns the number of times any tag was read during a particular run for a particular test.
Tag Read Counts For Test All Runs—Returns the number of times a particular tag was read during all the runs in a particular test without filtering the results
Number of Runs a Tag Appeared in During Test—Returns the number of times a particular tag was read for a particular test while filtering out multiple reads in a single run.
5.6.4 Storing QueriesTo store a query, enter the query you wish to store in the input field on the database query panel. Then click the ‘save query’ button. You will be prompted for a brief description of the query. This description will appear in the selection list when you click the ‘load query’ button, so be descriptive enough to recognize it later. Queries are limited to 1000 characters, descriptions are limited to 100 characters.
5.6.5 Parameterized QueriesThe stored query system supports user creation of parameterized queries using the same mechanism as the pre-made queries use to ask for a test id. However, currently there is not an automated tool to create these stored queries. Instead, the user must format the stored query correctly and then create a record in the StoredQueryParam table for each parameter. The following guide explains the details.
5.6.5.1 Stored Query FormattingThe format of the stored query is the same as a normal query, except that wherever you want a variable parsed in, indicate it with {} braces. For instance:
SELECT * FROM tagdata WHERE readerid={READER_ID} AND status={STATUS}
xxvii
Would require two parameters to be defined in the StoredQueryParam table. Please note that parameter names are case sensitive, and the {} are not part of the variable name.
5.6.5.2 Stored Query Parameter CreationEach record in the StoredQueryParameter must have the following fields defined:
query_id – Matches the stored query for which this is a parameterparam_name – Name of the variable, must match the pattern inside the {} of the stored query exactly. Case sensitive.param_type – One of three values: TextField, StaticList, or QueryListparam_order – The order the parameters are presented to the user for input. In many cases this does not matter, but if some parameters depend on others, this is crucial.Arguments – Specifies the values presented in StaticList and QueryList types. If the arguments are not set or result in an empty list, the input dialog will revert to TextField behavior.
5.6.5.3 Stored Query Parameter Types
There are three types of stored query parameters supported, but the dialog presented to the user will either be a text field or a dropdown list. If a parameter specifies a dropdown list but the arguments result in an empty list, the application reverts to a text field.
TextFieldThis parameter type requires no arguments, and places no restrictions on the input of the user. It simply replaces the pattern in the query with the input from the user.
StaticListThis parameter type requires a comma-delimited list in the arguments column. The dialog will present the elements from the list in a dropdown box, and the exact text of the selection will replace the pattern in the query.
QueryListThis parameter type requires a query in the arguments column. The results of the query are used to populate a list to present to the user. If the query returns a single column, the values of that column are both the names in the list and the values that get parsed into the query. If the query returns two columns per result, the rows of the result are treated as name/value pairs. If the query is ‘SELECT name, id FROM table’, the name will appear in the list, but the id will be parsed into the query.
5.6.5.4 Stored Query Parameter Dependencies
The stored query parameter system allows user input to modify the contents of later lists. For instance, a user might want to query values from a reader involved in a specific test. Rather than selecting from a list of all readers in the database, the user could first select the test of interest, and then select from a list of only the readers involved in that test.
The mechanism for this is the same as the mechanism for parsing values into queries. Before a QueryList arguments query is evaluated, the application attempts to replace any matches to previous patterns that may appear in the arguments query. So if the arguments query would look something like:
SELECT Reader1Id FROM TestData WHERE TestId={TEST_ID}
The previously selected test id would be parsed in before the query was run to populate the list.
xxviii
6 Reader Control (Reader Panel)The screen shot below shows the panel used for controlling readers. The general mode of operation for a reader is to:(1) Specify the manner in which you would like the reader to operate.(2) Enable the reader for operation. This allows the reader to report tag-read information to the database.
While a reader is enabled, you cannot change the manner in which it processes tag information. (3) When done, disable the reader. This causes the reader to cease reporting tag-read information to the
database.
ReaderPanel for Inactive Reader
Reader Panel for Active Reader
For each tag event reported, the reader agent emits the following information to the database:
xxix
Raw Tag ID (RFIDRaw field in TagData table). This is the Tag ID in hexadecimal format. Reader ID (ReaderID field in TagData table). This is the ID of the reader which detected the tag. Event Type (Status field in TagData table – “A” for “Arrival”, “D” for “Departure”) ReadPointList (RPL field in TagData table). This is a list of the antennas which actually “saw” the tag
on the reader. Currently, this is only a “list” for Symbol readers, and a single antenna ID for Alien and ThingMagic readers.
Read timestamp (ReadTime field in TagData table). This is the timestamp of the tag-read. Count (Count field in TagData table). The number of times that the tag was read during the polling
period. Currently, this field is only meaningful for ThingMagic readers; Alien and Symbol reader agents set this field to 1.
The subsections below will describe each section of the reader panel.
6.1 Event LoggingThe “Event Logging” section allows you to specify the types of events that you would like logged to the database for the reader, once it is enabled. You may choose one of: “Log Arrivals”: Report the arrival of each tag into the read zone. “Log Departures”: Report the departure of each tag from the read zone. It should be noted that this is
not an exact science; TagCentric logic will record a departure event some time after it ceases to read a tag.
“Log Arrivals and Departures”: Report both the arrival of each tag into the read zone, and it’s departure from the read zone.
Note: If the reader is enabled in “unfiltered” mode (i.e., the “Filter Reads” checkbox is not checked), then all reported events will be tagged as arrivals.
6.2 Tag TypesThe “Tag Types” section of the panel allows the user to specify a tag type filter for the reader. The three checkboxes can be checked in any combination desired by the user. In general, if you know that you will only be seeing a certain tag type, then you should filter on that tag type for better reader performance. For example, if you know that you are only dealing with Gen2 tags, then check only the “Class 1, Gen 2” box.
Note: The Symbol reader agent ignores tag type filtering information. However, the Alien and Thingmagic reader agents use it.
6.3 Filtering ReadsIf you check the “Filter Reads” box, then the TagCentric software will make an attempt to avoid reporting multiple reads for a tag while it is in the read zone. If you do not check this box, then the software will report every read for every tag.
When running the software in a production setting, it is advisable to filter the reads. One would only want to un-filter the reads in a test environment.
6.4 Poll PeriodThe Poll Period determines the frequency at which the reader agent will poll the reader for information. The lowest allowable value is 100 milliseconds. Generally, you would want to poll more often (i.e., smaller poll period) in situations where tags might move through the read zone relatively quickly, and poll less often (higher poll period) when tags move through the read zone relatively slowly.
6.5 Enabling/Disabling the ReaderThe reader will become enabled when you press the “Enable” button. At this point, the reader agent will start emitting information, the widgets on the panel will “gray out”, and the “Enable” button will turn into a “Disable” button. See the “Reader Panel for Active Reader” screen shot below.
xxx
When you want to stop the reader agent from reporting tag information, you press the “Disable” button. This will re-enable the widgets on the panel, stop the reader agent from transmitting tag-read information, and turn the “Disable” button into an “Enable” button.
6.6 Terminating the Reader AgentTo discontinue the reader agent, press the “Shut Down” button. You will get a dialog asking if you are sure that you want to shut down; press “OK” to complete the operation.
xxxi
7 Printer Control (Printer Panel)The Printer Panel is used to control an RFID tag printer. As of this writing, the only tag printer that we support is the Zebra tag printer. The Printer Panel looks like this:
Printer Panel
7.1 Status InformationThere are three items of printer status information provided on the Printer Panel: Connection, Busy, and Status.
The Connection value shows the status of the network connection to the printer. When the printer agent is first launched, the connection value will show up as “Testing…”, as the printer agent attempts to connect to the printer:
Printer Panel During Connection Testing
After the testing phase, the Connection value will either be “Connected” if the connection was established (see “Connected Printer” figure below), or “Not Connected” if the connection failed (see “Unconnected
xxxii
Printer” figure below). Possible reasons for connection failures are: The printer is not turned ON. The printer is not physically connected to the network. The agent was assigned the wrong IP address (i.e., it does not match the printer’s IP address). The network is down Printer Error (i.e., ribbon is not set properly or paper is not feed in properly).
The Busy value indicates whether or not the printer is currently busy with a print job.
The Status value gives some indication of the current status of the printer.
You will only be able to initiate a tag-printing job if the printer is connected and is not currently busy.
Panel showing good connection to printer
Panel showing failed connection to printer
7.2 Starting Print JobsTo start a print job, you need to provide three pieces of data: The beginning tag number, in hexadecimal, in the text box to the right of the “RFID tag code:” label.
If you are printing multiple tags, this number will be incremented by one for each tag printed. If the starting tag number that you provide is less than 24 hexadecimal nibbles (96 bits), then the printed value will be right-filled with zeroes.
xxxiii
The number of tags to be printed, in the text box to the right of the “Count:” label. Some free-format text (maybe a company name and address) in the text area beneath the “Enter the
Text to be printed on the tag” label.
Once you are satisfied with the data that you have provided, press the “Print” button to start your print job. If all goes as planned, the printer will start printing and the Printer Panel will indicate that the printer is busy. After the job completes, the Printer Panel will be available to start another print job.
If there is some sort of error in printing, you will be notified via the “Status” value in the Printer Panel.
Note: The Printer Panel is prone to indicating some sort of timeout in the Status after a successful print job. We will try to fix this.
7.3 An ExampleIn this subsection, we go through how to set up a sample print job, and give an example of what the resulting tags look like.
In this example we try to enter following fields likeRFID tag code to be : 123456789009876543211234And we would like to Print 3 tags so, we enter Count : 3And we enter some text in the text box : RFID CENTER
University of Arkansas Fayetteville AR-72701
Before starting the print job, our Printer Panel looks like this:
Printer Panel Before Initiating Print Job
After pressing the “Print” button to initiate the print job, the Printer Panel looks like this:
xxxiv
Printer Panel During Print Job
When the print job is done, the Printer Panel looks like this:
Printer Panel After Print Job
The tags printed are shown in the following figure:
xxxv
First 2 Labels from Example
xxxvi
8 Caveats and Recommendations
8.1 Basic Requirements for TagCentric OperationIn order to run the TagCentric software, the following must be true: The host machine must have an active network connection. The Java Runtime Environment (JRE), version 1.5, must be installed on the host, and the “java”
program must be reachable through the “PATH” environment variable. If a firewall exists on the host machine, it must be configured such that TagCentric agents are allowed
to open TCP connections to each other. While we have established no minimum processor speed for the successful execution of TagCentric,
suffice it to say that the performance of TagCentric will be better on a faster processor than on a slower processor.
8.2 One GUI up at a time (recommended)While the TagCentric application was designed for distributed, multi-user operation, that may not be a good idea with the current software. Many of the critical control messages are UDP unicast and multicast messages, and we have yet to implement any sort of reliability mechanism on top of UDP to ensure the delivery of these messages (this is coming!). If some of these critical messages are dropped, TagCentric may behave in an erratic or unpleasant fashion.
The safe thing to do is to run in single-user mode, where only one TagCentric GUI is up at a time, and to chose a single machine on which to run the software every time.
If you do attempt to operate with multiple simultaneous users/GUIs, though, there is a good chance (but not a guarantee) that TagCentric will operate in an acceptable fashion, especially on a “wired” network. Our experience has shown that multiple GUIs on an ethernet network works fairly well, while multiple GUIs on a wireless network results in significant packet loss.
8.3 Use a Local DatabaseWe recommend that you configure TagCentric (during installation) for use with a local database (i.e. same host or subnet as TagCentric), as opposed to a remote database. As of now, tag-read events are inserted into the database one at a time. These tag-read events can start backing up if there are a lot of them being generated and the database connection is a little slow (which is more likely to occur with remote databases).
8.4 Database Operations: You Have The PowerOur database interface will allow you to shoot yourself in the proverbial foot; it provides a great deal of power to the user. The user can drop tables, delete rows or columns, and change important table values through the Database Panel – in other words, the user can really mess things up.
It will be up to the user to be careful to be careful about what he/she does through the Database Panel query interface. If you stick to queries (i.e., SELECT statements) and avoid DROPS, UPDATES or table alterations, you should be fine.
8.5 Beware of nebulous networking situationsWe have seen some problems with TagCentric in both of the following scenarios: The host running the software has multiple network interfaces. For example, if the host has an ethernet
interface and a wireless interface, TagCentric may get confused about what it’s host IP address should be, and this can cause communications problems. This situation is exacerbated when one of the networks is intermittent, an example being a wireless network connection that keeps disconnecting and re-connecting.
xxxvii
The host is DHCP-enabled in “dynamic address” mode, and is re-connected during execution of the TagCentric software.
Both of these situations can cause an identity crisis for the TagCentric software, resulting in dropped messages and “frozen” behavior from the software and user interface.
8.6 Very High Tag-Read Rates Not TestedWe have tested TagCentric with maybe 4-5 readers being enabled at one time. We plan on testing on a larger scale at some point, but do not have the facilities to do so right now. So, if you try to run TagCentric with 10 or 20 readers, you are breaking new ground. We see no reason why it should not work, but we have not verified that it does.
Another “scaling” factor that we have not really tested is the processing of a massive number of tag-read events in a short amount of time, which can occur with even a small number of readers (especially if the readers are enabled in unfiltered mode).
To summarize, our testing (in terms of the rate of tag-read events) to this point has been relatively tame.
8.7 EPCIS-CompatilbilityDo we have an EPCIS interface? The answer, for now, is “no”. We do have plans to implement an Application Level Event (ALE) server at some point in the future.
xxxviii
9 Notes on Specific ReadersReader types will vary in the features that they support. The following table summarizes the differences between the readers as the TagCentric software supports them:
Alien Symbol ThingMagic FakeGenerates “count” information for each tag-read event
No; count field hard-coded to 1.
No; count field hard-coded to 1.
Yes Yes (Synthetic)
Generates valid read-point list (RPL) for each tag-read event
No Yes No Yes (Synthetic)
Capable of focusing on specified tag types
Yes No Yes N/A
A note on the Symbol readers: Symbol readers have a tendency to “fall asleep” (or disconnect) after a period of inactivity. Thus, if you keep a Symbol reader disabled for a certain amount of time (8 minutes?) and do not communicate with it, you might find that the agent’s connection to the reader has been dropped. For this reason, it is good to keep the Symbol readers enabled while they are powered on.
xxxix
10 A Step-by-Step Recipe for Getting StartedIn this section, we will go through a sample installation and execution of the TagCentric software. We will not go through all of the many ways that TagCentric could be configured and executed, but rather one way: TagCentric will be installed and executed on a Windows system, using the embedded Derby database, and using fake readers. Installing to Linux is very similar (except the directory-separator slashes are different). Installing with databases other than Derby is also fairly straightforward.
10.1 Installing TagCentric
We’ll assume that I have downloaded TagCentric-Install.jar to a directory called C:\work\scratch. To begin the installation, one would enter the following command at the DOS prompt:
C:\work\scratch>java –jar TagCentric-Install.jar
Upon entering this command, the installation dialog pops up:
Since I want to install TagCentric in C:\work\scratch\TagCentric_HOME, I substitute this directory for the default installation directory already in the text box, so that the text box now contains “C:\work\scratch\TagCentric_HOME”. To continue with the installation, press the “Setup Database >>” button. The dialog then changes to the following:
xl
I want to use the “Derby Embedded” database, but I want to install it into the C:\work\scratch\TagCentric_DB directory; accordingly, I change the text in the directory specification box to be “C:\work\scratch\TagCentric_DB” and press the “Install >>” button. The installation proceeds and I am presented with the following dialog:
xli
At this point, press the “Finish” button to end the installation.
10.2 Running TagCentricTo run the TagCentric graphical user interface, launch the “startup.bat” script from the “bin” directory of the installed TagCentric software. For our example, that means we would want to go to the C:\work\scratch\TagCentric_HOME\bin directory, and launch the “startup.bat” script. Once we do this, we are presented with the TagCentric “Dashboard” dialog3:
3 As noted in the Admin Panel section, the appearance of the Admin Panel was changed just before we released the software. It no longer contains the red “Initialize Database” button. This button can be found, however, in the Database Panel “Admin” page.
xlii
10.2.1 Initializing the databaseFrom here, press the “Start” button next to the “Database Agent:” label to launch the database agent. The Dashboard should now look like this:
Press the “Derby Embedded” entry from the panel tree on the left to show the interface to the database agent. The Dashboard should now look something like this:
xliii
Note the status of the database agent: the database is uninitialized. To remedy this, press the “Initialize” button on this panel. (You will need to say “OK” to the resulting dialog which warns you about initializing the database). After some processing time, the Dashboard should now look something like this:
Your schema version may be different, and your Connection may look slightly different, but the important thing is that the database is now properly initialized. We can now get on to running the application.
10.2.2 Adding a ReaderReturn to the main Admin panel by selecting the “Admin” element of the panel tree on the left of the Dashboard. It looks like this:
xliv
You will notice that there are no readers or printers to launch or kill in the “Reader/Printer Agent Launchpad” area. We would like to add a reader, so we press the “Manage Reader Info” button on this panel; the following dialog pops up:
To add a new reader, press the “Add New Reader” button. This pops up the following:
xlv
We will populate this dialog as follows with the values for our initial reader:
Pressing “Commit” causes this reader information to be inserted into our database. The “Modify Reader Information” dialog now looks like this:
xlvi
For the purposes of our small example, we’ll be satisfied with our one “fake” reader. Press the “Exit” button, and the Admin panel now looks like this:
We now have a fake reader in our database.
xlvii
10.2.3 Reader OperationsTo “Launch” a reader agent, press the “Launch” button corresponding to the agent to be launched. In our example, we will press the “Launch” button associated with the “Fake-1” reader. The Dashboard now looks like this:
Note that the “Launch” button is now a “Kill” button, and that an entry for “Fake-1” has been added to the panel tree on the left of the Dashboard. At this point, the “Fake-1” reader agent has been launched, but it is still in a “disabled” or “deactivated” state. We need to enable the reader through the Fake-1 interface panel. To see the interface panel for the “Fake-1” reader, press the “Fake-1” entry from the panel tree on the left. The Dashboard now looks like this:
xlviii
For the purposes of our example, we will stick with the default values of: Log tag arrival events only Only report Gen2 tags Filter the tag-read information to prevent a tag from being reported multiple times during the same trip
through the read zone Poll every 1000 ms (i.e., once per second)
By pressing the “Enable” button, the “Fake” reader starts generating synthetic tag-read events. (A “real” reader would start reporting any suitable tags that entered its read zone). After pressing “Enable”, the Dashboard looks like this:
Note that you are not allowed to change read characteristics while the reader is enabled. If, for example, you wanted to change the poll period from 1000 ms to 200 ms, you would need to disable the reader, make the change, and then re-enable the reader.
While readers are enabled, the “Test” panel shows a real-time view of the tag-read events as they are reported. Select the “Test” panel from the panel tree on the left of the dashboard, and you should see something that looks similar to the following:
xlix
To disable the reader (which causes the reader to cease reporting tag-read event information), go back to the “Fake-1” panel and press the “Disable” button.
Disabling the reader, though, does not deactivate the reader agent. To shut down the reader agent, go back to the “Admin” panel and press the “Kill” button associated with the “Fake-1” reader. Upon pressing that button, the “Fake-1” entry should be removed from the panel tree on the left of the Dashboard.
10.2.4 Shutting Down the Dashboard
Simply pressing the “X” widget in the top-right corner of the Dashboard will kill the application. However, any active agents (Database agent, reader agents, printer agents) will still be active even in the absence of the Dashboard. To truly shut everything down:1. Kill all reader and printer agents by pressing any “Kill” buttons in the “Reader/Printer Agent
Launchpad” area of the Admin panel.2. Kill the database agent by pressing the “Stop” button to the right of the “Database Agent:” label on the
Admin panel.3. Close the application by pressing the “X” icon in the upper-right corner of the application.
l
11 Troubleshooting
11.1 Admin PanelI cannot successfully launch an agent (printer/reader/database). Close the application and re-start it.
I am running 2 TagCentric Dashboard applications simultaneously, and the contents of the “Reader/Printer Agent Launchpad” lists, or their Panel Trees, do not match. Try pressing the “Refresh” button on both Admin panels. If this fails, close both Dashboard applications and restart them.
I am running multiple TagCentric Dashboard applications. I added a reader (or printer) through one Dashboard, but it did not show up in the other’s “Reader/Printer Agent Launchpad” list. Why? At the moment, we have no facility for communicating reader/printer additions amongst all active LaunchPads. The workaround is to press the “Refresh” button on the Admin panel of the “out-of-sync” Dashboard application.
I successfully ran a database schema update operation, and now none of my readers or printers shows up in the “Reader/Printer Agent Launchpad” list. They should still be in the database; try hitting the “Refresh” button.
11.2 Reader ControlWhen my reader panel first appears, it has the wrong reader type and the action button is labeled “??????????” instead of “Enable” or “Disable”. Sometimes, it takes reader agents a while to initialize properly and connect with their target devices. During this lag, the reader panel is waiting for status information from the reader agent, and may temporarily be a bit out of sync.
I am unable to enable/disable my reader agent through the reader panel. Try killing the agent and re-launching it. If that doesn’t work, try closing the GUI application and restarting it.
11.3 Database PanelMy queries result in a pop-up saying “Problem with reply”. There may be some problem with the TCP “back-door” connection between the GUI and the database agent. Try stopping and then re-starting the database agent.
11.4 Printer ControlThe Zebra printer prints blank tags or tags with only tag numbers on them, and/or too many tags are printed, and/or the initial user-specified tag number is printed over and over rather than incrementing with each tag. We developed our Zebra support software using a single Zebra printer. Our software does not work too well at times with Zebra printers with different firmware than our development printer, or Zebra printers whose configurations have been altered from their factory settings. We’re working on it.
11.5 When All Else FailsIf you ever think that TagCentric is behaving strangely and have no idea how to fix it, try the following in the order given:1) Try stopping all agents (reader/printer agents first, then the database agent) from the Admin panel, then
restarting them (database agent first, then desired reader/printer agents). If that doesn’t fix the problem, then
2) Try closing, then re-starting, the TagCentric Dashboard application. If that doesn’t fix the problem, then:
3) Try closing the TagCentric Dashboard application, and killing every TagCentric-related Java process on your system.
li
The last one may seem a bit harsh, and it may be hard to tell which Java processes on your system are TagCentric-related and which are not. But this step may be necessary to correct some odd behaviors.
lii
12 Planned EnhancementsWe plan on adding several enhancements to TagCentric in the near future. These enhancements include (but are not necessarily limited to) the following: Message Reliability Mechanisms. Add some reliability mechanisms on top of our UDP unicasts and
multicasts. By doing this, we could “green light” multi-GUI, multi-user operation. Support for Mobile Readers. Currently, the software assumes static readers. However, mobile readers
are an emerging technology that we would like to support as well. Support for “Smart” Tags, Readers. In addition to normal Gen2-type tags, there exist “smart” tags that
record things like temperature and shock information over time. We would like to be able to integrate support for these types of tags into TagCentric.
Security/Access Control Mechanisms. Support for Additional Printers. Give the user options to the Zebra printer. Block Inserts for Tag Data. Currently, tag-read events get inserted into the database one at a time,
which is inefficient and could impair the scalability of the software. We would like to enhance the database logic to insert the tag-data events in blocks.
Query Tool Enhancements. We would like to increase the power and usability of the analysis tools provided by TagCentric.
ALE Server. This would be a huge step toward EPCIS-compatibility.
liii
