ALIEN TECHNOLOGY
.NET API
DEVELOPER'S GUIDE
April 2009
All Full
Featured
Readers
Legal Notices
Copyright © 2008 Alien Technology Corporation. All rights reserved.
Alien Technology Corporation has intellectual property rights relating to technology
embodied in the products described in this document, including without limitation certain
patents or patent pending applications in the U.S. or other countries.
This document and the products to which it pertains are distributed under licenses
restricting their use, copying, distribution and decompilation. No part of this product
documentation may be reproduced in any form or by any means without the prior written
consent of Alien Technology Corporation and its licensors, if any. Third party software is
copyrighted and licensed from Licensors. Alien, Alien Technology, the Alien logo,
Nanoblock, Fluidic Self Assembly, FSA, Gen2Ready, Squiggle, RFID Gateway,
Nanoscanner and other graphics, logos, and service names used in this document are
trademarks of Alien Technology Corporation in the U.S. and other countries. All other
trademarks are the property of their respective owners. U.S. Government approval
required when exporting the product described in this documentation.
Federal Acquisitions: Commercial Software -- Government Users Subject to Standard
License Terms and Conditions. U.S. Government: If this Software is being acquired by or
on behalf of the U.S. Government or by a U.S. Government prime contractor or
subcontractor (at any tier), then the Government's rights in the Software and
accompanying documentation shall be only as set forth in this license; this is in
accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense
(DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).
DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED
CONDITIONS, REPRESENTATIONS AND WARANTEES, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NON-INFRINGMENT ARE HEREBY DISCLAIMED, EXCEPT TO THE EXTENT THAT
SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
i
TABLE OF CONTENTS
Alien Technology
.NET Developer’s Guide (v.2.3)
All Full Featured Readers
Table of Contents
CHAPTER 1 INTRODUCTION ..................................................................................................................... 1
Audience .................................................................................................................................................... 1
Overview .................................................................................................................................................... 1
Installation ................................................................................................................................................. 4
CHAPTER 2 SUPPORTING DATA TYPES ................................................................................................. 5
Introduction ................................................................................................................................................ 5
The ReaderInfo Class................................................................................................................................ 6
The TagInfo Class ..................................................................................................................................... 7
The NotifyInfo Class .................................................................................................................................. 8
The AlienIOInfo Class................................................................................................................................ 9
The UpgradeInfo Class............................................................................................................................ 10
CHAPTER 3 THE CLSREADERMONITOR CLASS .................................................................................. 11
Introduction .............................................................................................................................................. 11
Serial Discovery and Monitoring .............................................................................................................. 13
Network Discovery and Monitoring .......................................................................................................... 15
CHAPTER 4 THE CLSREADER CLASS ................................................................................................... 17
Introduction .............................................................................................................................................. 17
Instancing a Reader from the clsReaderMonitor Discovery Class .......................................................... 17
Instancing a Reader Directly On a Serial Connection ............................................................................. 17
Instancing a Reader Directly on the Network .......................................................................................... 18
Opening and Closing Connection to a Reader ........................................................................................ 18
Communication with a Reader ................................................................................................................ 20
CHAPTER 5 TAG WORKS ........................................................................................................................ 22
Introduction .............................................................................................................................................. 22
Reading Tags .......................................................................................................................................... 22
Programming Tags .................................................................................................................................. 24
CHAPTER 6 ALIEN NOTIFICATIONS AND STREAMING ....................................................................... 28
Introduction .............................................................................................................................................. 28
Retrieve Notifications Synchronously ...................................................................................................... 29
Asynchronous Notifications ..................................................................................................................... 29
CHAPTER 7 READER FIRMWARE UPGRADE........................................................................................ 33
CHAPTER 8 ALIEN INTELLIGENT TAG RADAR
................................................................................. 34
.NET DEVELOPER’S GUIDE
DOC. CONTROL # 8101948-000 REV. H
1
TABLE OF CONTENTS
Table of Figures
Figure 1: Alien RFID Library class diagram ................................................................................................................. 3
Figure 2: Alien RFID Library enumerations ................................................................................................................. 5
Figure 3: ReaderInfo class ............................................................................................................................................ 6
Figure 4: Class TagInfo ................................................................................................................................................ 7
Figure 5: Class NotifyInfo ............................................................................................................................................ 8
Figure 6: Class AlienIOInfo ......................................................................................................................................... 9
Figure 7: Class UpgradeInfo ....................................................................................................................................... 10
Figure 8: Example of Subscribing to clsReaderMonitor events in C# ........................................................................ 11
Figure 9: Example implementation of the clsReaderMonitor.ReaderAdded event .................................................... 12
Figure 10: Updating ListBox lbReaders with received data ....................................................................................... 12
Figure 11: Manually checking presence of Alien readers on Com ports .................................................................... 13
Figure 12: Getting current reader list on Com ports ................................................................................................... 14
Figure 13: Clearing the current list of serial-connected readers, GUI, and the collection variable ............................ 14
Figure 14: Example application # 5 in actions............................................................................................................ 15
Figure 15: Monitoring Alien Readers both on network and serial connecitons ........................................................... 16
Figure 16: Creating an instance of the reader from the Reader Monitoring ............................................................... 17
Figure 17: Initializing reader for serial communication ............................................................................................. 17
Figure 18: Initializing reader for network communication ......................................................................................... 18
Figure 19: Opening connection to the reader .............................................................................................................. 18
Figure 20: Logging to the network ............................................................................................................................. 19
Figure 21: Comand/Response communication of Alien reader with a mobile device. ................................................ 20
Figure 22: Synchronous and asynchronous reader responses ..................................................................................... 21
Figure 23: Obtaining reader internal Tag list .............................................................................................................. 22
Figure 24: Tag list returned in Text format (default) .................................................................................................. 22
Figure 25: Tag list returned in XML format ............................................................................................................... 23
Figure 26: Parsing obtained Tag list ........................................................................................................................... 23
Figure 27: Ex6 – Tag List running.............................................................................................................................. 24
Figure 28: Example11 - Programming Tags running ................................................................................................. 26
Figure 29: Members of the CAlienServer class .......................................................................................................... 28
Figure 30: Notifications Example Application ........................................................................................................... 30
Figure 31: Ex9 – Data Streaming on Network sample application ............................................................................. 31
Figure 32: Mobile device receives data from reader and transfers them to a desktop application ............................. 32
Figure 33: Firmware Upgrading with the Ex10 sample application ........................................................................... 33
Figure 34: Demonstrating Alien Intelligent Tag Radar
features. ............................................................................. 34
iii
.NET DEVELOPER’S GUIDE
DOC. CONTROL # 8101948-000 REV. H
CHAPTER 1
INTRODUCTION
CHAPTER 1
Introduction
The .NET Developers’ Guide provides basic instructions for programmatically
controlling Alien RFID readers using Microsoft .NET Framework v.2.0. Alien
provides a number of assemblies (for both full and Compact Framework) as class
libraries, custom user controls and sample applications that are included
withinnnn Alien Developer's Kit.
Audience
For the purposes of this book, we assume the readers of this document:
• Have minimal previous knowledge of radio-frequency identification
technology,
• Are familiar with the Alien Reader ASCII Protocol (see Reader Interface
Guide, Doc# 8101938-000),
• Are experienced in .NET software development.
Overview
The Alien RFID Reader can be programmatically controlled using a number of
systems and languages. This document focuses on controlling the reader using
the Alien .NET API supplied with the developers’ kit. Terms Alien .NET Library
(Library) and Alien .NET API have been used in this document interchangeable.
Class library for full .NET Framework is called AlienRFID2.dll and for the
Compact Framework – AlienMobileAPI.dll.
NOTE: Not all features of the full library are supported by the mobile API
(e.g.: Firmware upgrade is not supported by mobile build.)
Alien Technology provides a number of example applications with their source
code developed in .NET environment (C# and VB.NET) as Alien .NET SDK
demonstrating how to use features of Alien readers and software. There is also
the Visual Basic 6
another set of sample applications developed with
environment
the
AlienRFID2.dll described by the AlienRFID2.tlb type-library.
for demonstrating how
interface of
to use
the COM
The class library contained within Alien .NET API provides type structures and
classes that constitute discrete functional groups for controlling various aspects
of the reader:
The class clsReader is the main class for interaction with an Alien reader. It
reflects the Alien Reader ASCII Interface described in the Reader Interface
Guide, doc #: 8101938-000 and has additional features related to a separate
reader device.
.NET DEVELOPER’S GUIDE
DOC. CONTROL # 8101948-000 REV. H
1
INTRODUCTION
CHAPTER 1
Library provides Discovery and Monitoring features – Classes for discovering the
location of readers connected via serial ports or networks as well as for
monitoring tags’ status read by a reader.
Library includes Storage Types – Data types for handling data about readers and
RFID tags. The Alien RFID classes clsReaderMonitor and clsReader use these
types to pass information to functions and user applications about the state of
readers connected to the system.
Though, the Alien .NET API had been started as a functional mirror to the
AlienRFIDLibrary.dll ActiveX component that had been used by developers with
Visual Basic 6 (VB6) since 2003, it has overgrew it with time. The .NET Library
doesn’t use MSComm control that was so popular for VB6 developers but
unfortunately has some limitations and license restrictions for redistribution.
Instead, the native .NET classes have been used as well as low level Win32 API
calls.
The following diagram demonstrates high-level structure of the Alien .NET API:
2
.NET DEVELOPER’S GUIDE
DOC. CONTROL # 8101948-000 REV.H
CHAPTER 1
INTRODUCTION
Figure 1: Alien RFID Library class diagram
.NET DEVELOPER’S GUIDE
DOC. CONTROL # 8101948-000 REV. H
3
INTRODUCTION
CHAPTER 1
Installation
To use the Alien RFID library from within .NET Development Environment the
corresponding assembly must be installed locally to the working directory of your
client application or into the Global Assembly Cache (GAC.)
A reference to installed Library must be added to the project.
For your convenience, you may want to add the nsAlienRFID2 (nsAlienRFIDcf for
mobile build) namespace to the section “using” in C# or section “Imports” in
Visual Basic.NET (VB.NET.)
Sample applications of the Alien .NET SDK with their source code have to be
copied and used locally. All sample applications included in the package use
local copies of the Library.
In order to see micro-help for Alien Library members in the Visual Studio .NET
provided with the Microsoft IntelliSence feature a corresponding *.xml file must
be placed in the same directory as the Library.
The Alien .NET API Documentation.chm file provides the MSDN-style help for all
classes, methods, properties, and types of the Library. It can be open from any
location disregarding the Library or SDKs source code.
There are also setup package and merge module included for redistribution
Library to COM users. Those provide installation to the Windows directory and
registration in Windows Registry. Please see the “Visual Basic Developers
Guide” for detailed information on using Library as a COM component.
4
.NET DEVELOPER’S GUIDE
DOC. CONTROL # 8101948-000 REV.H