ALIEN TECHNOLOGY

ON-READER
PROGRAMMING
OVERVIEW
Ruby API
for
Alien Custom
Application ARCATM Kit
May 2009

All Readers

Legal Notices
Copyright 2009 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.

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

TABLE OF CONTENTS

Alien Technology

Alien ARCATM OnOn-Reader Programming

Overview
All Alien RFID Readers
Table of Contents

INTRODUCTION.............................................................................................................................. 1
Purpose........................................................................................................................................ 1
Background.................................................................................................................................. 1
Quick Start ................................................................................................................................... 1
INSTALL RUBY & ALIEN RUBY API ON THE READER .............................................................. 2
The Ruby Interpreter.................................................................................................................... 2
Installing the Ruby Interpreter ............................................................................................. 2
The Alien Ruby RFID Library....................................................................................................... 2
Installing the Alien Ruby RFID Library ................................................................................ 2
LEARN TO USE RUBY AND THE ALIEN RUBY API .................................................................... 3
Familiarize Yourself with Ruby .................................................................................................... 3
alien-rfid-lib .................................................................................................................................. 3
Alien Reader Application Interface (RAI) for your PC ................................................................. 5
net-scp................................................................................................................................. 5
API Documentation...................................................................................................................... 6
LOOK AT API EXAMPLES, WRITE AN APPLICATION................................................................ 7
API Examples .............................................................................................................................. 7
config.dat............................................................................................................................. 7
ex_helloworld.rb .................................................................................................................. 7
ex_get_taglist.rb.................................................................................................................. 9
Running ex_get_taglist.rb........................................................................................... 12
Your Application ................................................................................................................ 12
USE RAI TO MANAGE APPS ON THE READER........................................................................ 13
Create and Run ioant on the PC ............................................................................................... 13
Install the ioant Application on the Reader ................................................................................ 15
Register the ioant Application and Run It .................................................................................. 17
Unregister the ioant Application................................................................................................. 18
Retrieve Application Files from the Reader ............................................................................... 19
Remove an Application from the Reader................................................................................... 19

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

ii

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Introduction
Purpose
This document describes how to write, load, and run applications on Alien
Technology RFID readers, using the Alien RFID Custom Application ARCA,
which features the Ruby programming language. Supported readers include:

ALR-9900

ALR-9650

ALR-9800

ALR-8800

Background
Alien readers communicate via the Alien Reader Protocol, a flexible interface
featuring AutoMode, notification, tag masking, tag and IO-streaming and other
powerful features. Coupled with the Alien Reader Protocol, ARCA provides a
feature-rich, highly adaptable platform for implementing RFID solutions. Now
users can easily implement custom extensions to the Alien Reader Protocol,
including RFID data pre-processing, application-specific triggering modes or
custom communication channels with server-side applications.
ARCA expands the utility of Alien readers in ways that only our inventive users
can predict. On-reader applications can eliminate the need for a centralized
reader management system so that readers can react to events autonomously.
Many remote and mobile applications will benefit from this capability. With ARCA
users can offload business logic to readers to distribute decision making and
enhance system reliability. On-reader applications enable a wide range of
custom filtering, pre-processing and data formatting options. The Alien RFID
Custom Application Kit enables users to discover more value, more quickly, for
applications like retail inventory management, industrial manufacturing and asset
tracking.
Why Ruby? Alien selected Ruby because it is a stable, flexible, object-oriented
programming language that allows users to rapidly develop cross-platform
applications. Ruby is relatively easy to master. It is suitable to the scale of
applications RFID users want to implement on our readers. Coupled with the
Alien Reader Protocol, Ruby provides an easy to use, feature-rich, highly
adaptable platform for implementing RFID solutions.

Quick Start

Install Ruby and the Alien Ruby API on the reader.

Learn to use Ruby and the Alien Ruby API.

Look at API Examples, write an Application

Use RAI to manage applications on the reader.

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Install Ruby & Alien Ruby API on the Reader

The Ruby Interpreter
Running Ruby applications on the reader requires the Ruby interpreter and
standard library files, the Alien Ruby RFID API, and your application source files.
Ruby source files are plain-text and interpreted by Ruby on-the-fly. No
compilation or processing of your source code is required.

Installing the Ruby Interpreter

First install the Ruby interpreter on your reader using the Alien firmware package
that has a filename similar to:
alien-ruby_1.8.72-1_arm.tar.aef
Use the reader's web interface to install the Ruby interpreter onto the reader,
as you might install a firmware upgrade. Go to your reader's IP address using a
web browser, click on Reader Management, log in, then point to the alienruby file and click on Upload. Installation should take about a minute.

The Alien Ruby RFID Library

In addition to the Ruby interpreter that you just installed, you need to also install
the Alien Ruby RFID libraries. Your application uses these library files to
communicate with the reader, implementing the full set of Alien Reader Protocol
commands as well as parsing tag data, listening on sockets, etc.

Installing the Alien Ruby RFID Library

Use the reader's web interface to install the Alien Ruby RFID libraries onto
the reader. The installer should have a filename similar to:
alien-ruby-api_0.8.3-1_arm.tar.aef

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Learn to Use Ruby and the Alien Ruby API

Familiarize Yourself with Ruby
While Ruby is very intuitive and flexible, some aspects of it are significantly
different from other programming languages. We recommend that those who are
new to Ruby spend some time at http://www.ruby-lang.org. This site offers an
interactive Ruby tutorial, documentation, forums, and tips on transitioning to
Ruby from other languages. Information about Ruby installers for other platforms
is also available at this web site.
The version of Ruby installed on readers is 1.8.7. In order to avoid compatibility
issues when developing Ruby applications for Alien readers on your PC make
sure
to
install
Ruby
version
1.8.6
or
1.8.7
on
your
PC.
The easiest option to install Ruby on Windows is to use the Ruby one-click
installer v 1.8.6 from http://www.ruby-lang.org/en/downloads/
There are several ways to install Ruby on Linux:

some Linux distributions already include Ruby.

you can also download the source code and compile by hand.

on some platforms, there are package management solutions that make

installing Ruby extremely easy. For example, you can use 'apt-get' on
Debian or Ubuntu: sudo apt-get install ruby irb rdoc

The distribution of Ruby that you installed on the reader includes standard Ruby
libraries. No additional extensions, known as Ruby "gems have been installed,
and there are no plans to support gems on the reader.
Before you start writing applications for your readers, use the website to become
proficient enough at Ruby to work through the tutorials, and even write your own
apps from scratch. Get comfortable running Ruby applications from your
system's command-line. If you used the "one-click-installer" to install Ruby on
your Windows system, it will associate the .rb extension with Ruby, and add the
Ruby executable to your command path.
Next, begin examining the lib directory inside the alien-rfid-lib folder and
study the class files Alien has put together to communicate with your RFID
reader.

alien-rfid-lib
The library files in the alien-rfid-lib/ folder are exactly the same as those
that you previously installed on the reader. In fact, when running your Ruby
application on the reader, the only difference in your code is the IP address used
to connect to the reader. When running your application on the reader, you
simply use 127.0.0.1 (localhost) for the reader's IP address.
We also
recommend that you connect on the CommandPortLocal (2300, by default). This
is new reader feature intended to support on-reader applications. It is an
independent command channel, just like the normal, port 23 command channel,

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

but it only accepts connections originating from within the reader itself. Using port
2300 leaves the standard port 23 available for external connections to the reader,
so reader can be controlled from both the on-reader application and the
command channel on port 23 at the same time. This could be desirable or not
depending on the logic of your application, so select whichever port works for
your use case.
You can put the alien-rfid-lib/ folder wherever you want on your PC's
hard drive. The only requirement is that you should stage your RFID
applications in your own folder inside alien-rfid-lib/, next to the lib/
folder, as shown below. The same folder structure is maintained on the reader to
assure that your application will find the required Alien libraries when running on
the reader.
alien-rfid-lib/
|-- lib/
|-- examples/
|-- yourApp1/
|

|-- yourApp1.rb

|-- other files1

|-- yourApp2/
|-- yourApp2.rb
|-- other files2
Inside the lib/ folder there is a set of Ruby classes written by Alien whose use
is demonstrated in the files inside the examples/ folder. You have full access
to the source code for these classes, and you may find that looking through them
improves your understanding or Ruby and how the classes work, but you should
refrain from modifying the library files directly.
Please forward bug reports and change requests for these libraries directly to
Alien for incorporation into future versions of the Alien Rubi API. The library files
residing on the reader are controlled by Alien, via the alien-ruby-api_x.y.z1_arm.tar.aef package installer.
The reader identifies your application by the same name as the directory that the
application resides in, so the main file for your application must have the
same name as the directory name. Thus, an application named "foobar" would
be located at alien-rfid-lib/foobar/foobar.rb.
All file and folder names should conform to Linux file naming standards. Also,
avoid using spaces and subdirectories. You can use multiple Ruby source code
files in your project but they all have to reside in the same folder in your
application folder. This is because the current version of RAI tool only supports
flat folder structure and does not support subfolders.
When your application needs to reference the Alien classes in the lib/ folder,
your use a relative reference, like "../lib/alienreader.rb". When your
application is finally installed and run on the reader, it is copied into a similar
directory alongside the same lib/ folder.

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Alien Reader Application Interface (RAI) for your PC

In addition to the alien-rfid-lib API and associated reader packages, you also
need to install the Alien Reader Application Interface (RAI) tool on your PC. This
utility facilitates loading and execution of user applications on the reader. The
RAI tool is a Ruby script called rai.rb, and is included in the SDK distribution.
You need to be able to invoke the RAI tool without too much fuss, and from any
arbitrary application directory, so we recommend that you place rai.rb in a
directory that is in the PATH on your PC, so that the system can find the utility
no matter what your current working directory is. If you do this, and your PC also
associates the .rb extension with the Ruby interpreter, then you can run the RAI
tool from the command prompt from any directory just by entering the command
"rai".
If the .rb extension is not associated with the Ruby interpreter, you will have to
type something less elegant, like "ruby <path_to_rai.rb>\rai.rb"
More information on the usage of RAI tool is provided in a later section, "Use RAI
to Manage Apps on the Reader".

net-scp
The RAI tool uses Secure Copy (SCP) to transfer files to your reader and issue
commands remotely, but the default Ruby installation generally doesn't include
the required SCP and SSH libraries. The easiest way to install them is to use
Ruby 'gem' distribution mechanism and install the net-scp Ruby "gem" with
"gem install net-scp" at the command prompt. Since 'net-scp'
depends on 'net-ssh' this will also install 'net-ssh' library.
Note: As mentioned above, Ruby gems are not supported on readers. For this
reason we do not generally recommend installing them and relying on their
functionality on your Ruby-RFID development PC. However, this gem is an
exception that simplifies the installation of 'net-ssh' and 'net-scp' libraries
used by the Alien RAI tool and we do find using gem mechanism useful in this
case.
Detailed information is available at:
http://net-ssh.rubyforge.org/scp/v1/api/index.html
http://net-ssh.rubyforge.org/ssh/v2/api/index.html
Alternatively, you can install libraries manually, without resorting to Ruby gems
by following these steps:

download 'net-scp-*' and 'net-ssh-2*' library packages from:

http://rubyforge.org/projects/net-ssh
(download '*.zip' archives for Windows or '*.tar.gz' archives for
Linux)

unzip '*.zip' archives on Windows or untar '*.tar.gz' archives on

Linux (tar xzf *.tgz)

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

cd net-ssh-2*
ruby setup.rb config
ruby setup.rb install (might need sudo/administrative privileges)

cd net-scp-*
ruby setup.rb config
ruby setup.rb install (might need sudo/administrative privileges)

The only requirement for NET::SSH2 you might be missing is the OpenSSL
bindings for Ruby. These are built by default on most platforms (the one-click
installer for Windows includes them) and to verify that they're installed on your
system just run the following on the command line:
ruby -ropenssl -e 'puts OpenSSL::OPENSSL_VERSION'
You should see something like "OpenSSL 0.9.8g 19 Oct 2007". If you get an
error, then you'll need to either rebuild Ruby with OpenSSL support, or, if your
platform supports it, install the OpenSSL bindings separately. For example, on
Debian
or
Ubuntu
you
can
use
'apt-get':
sudo apt-get install libopenssl-ruby

API Documentation
The Alien Rubi API documentation is created with a tool called rdoc, which works
similarly to JavaDoc, by scanning specially-formatted comments in the source
code and generating a suite of HTML files. You can view API and examples
documentation with your web browser at:
Documentation/alien-rfid-lib/index.html
Many examples of usage are available in the documentation, in addition to the
set of Ruby example files that Alien provides.
If you examine the documentation on the AlienReader class, you may be
surprised to see only a handful of methods defined to issue reader commands.
The bulk of the code that handles the Alien Reader Protocol (ARP) command set
is generated on-the-fly when the AlienReader class is created. It scans an
external readermethods.dat file which lists all of the reader commands and
their
get/set/do
usage.
From
each
command
description
in
readermethods.dat, the class builds accessor methods with the same names
as the command the ARP command name in lowercase letters. For instance, to
get the AntennaSequence, use the getter method:
AlienReader.antennasequence

To set the AntennaSequence, use the setter method:

AlienReader.antennasequence="0 1"

Some commands are "do" kinds of commands, such as the method:

AlienReader.automodereset

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Look at API Examples, Write an Application

API Examples
Inside the examples/ folder there are over a dozen sample Ruby applications,
each demonstrating different aspects of the API classes. For a quick overview of
the files and what they do, just view the documentation for the examples, at
Documentation/examples/index.html

config.dat
In addition to the sample .rb files, there is one other important file in the
examples directory, config.dat. We recommend that you create your own
config.dat (or copy this one) for use in your application. It resides in your
application directory. It is a preference file that contains IP addresses, ports,
username/password, and any other configuration information that your
application might need.
You don't have to use config.dat. You can handle your own application
preferences and settings in other ways, but this is how the examples work, so it's
worth becoming familiar with it. By storing common configuration information in
one file, it is easily accessible to all of your Ruby scripts by using the provided
AlienConfig class. You'll see how it is used in the examples to follow.
The first entry in config.dat is generally the IP address of the reader your
application needs to connect to. When you transfer your Ruby application to the
reader you just need to change the IP address to 127.0.0.1 (localhost) and your
app should work the same as when it was running remotely.

ex_helloworld.rb
Following tradition, we'll start by looking at a simple "Hello World" application.
This application will connect to a reader (with IP address specified in
config.dat) get its ReaderName, and print a "Hello world!" greeting from the
reader.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

=begin rdoc
=Alien Ruby RFID Library Examples
==ex_hello_world.rb
A "Hello World" application using the Alien RFID Library for Ruby.
Uses the AlienReader.open command with default values for port, username and password.
(Change the "reader_ip_address" parameter in your config.dat file to the one
appropriate for your reader.)
Copyright 2008, Alien Technology Corporation. All rights reserved.
=end
# Add the default relative library location to the search path
$:.unshift File.join(File.dirname(__FILE__),"..","lib")
require 'alienreader'
require 'alienconfig'

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

begin
# Grab various parameters out of a configuration file
config = AlienConfig.new("config.dat")
# Create the new reader
r = AlienReader.new
puts "----------------------------------"
# Open a connection to the reader and get the reader's name.
if r.open( config["reader_ip_address"]) # Uses default usr, pwd, port...
puts "Hello World! I am #{r.readername}."
end
puts "----------------------------------"
# Close the connection.
r.close
rescue
# Print out any errors
STDERR.puts $!
end

Lines 1-20

=begin=end is a multi-line commend. The contents are formatted so

that rdoc can use them.

Line 13

$: is the variable containing the library path. We are prepending

"../lib" to the path to make the Alien classes available. This is
more complicated than it probably needs to be.

Lines 15-16

These two lines link in the AlienReader and AlienConfig classes.

AlienConfig allows us to use the data in the config.dat file, and
AlienReader provides the class to communicate with the reader.

Lines 18,34,37

A begin-rescue-end block is the equivalent of try-catch block. The

code before "rescue" is evaluated until an exception is raised, then
the code under "rescue" is run.

Line 20

Creates a new AlienConfig object, which reads and parsed the contents
of config.dat. The resulting config variable is a hash, allowing us
to access any of the fields in config.dat by name.

Line 23

Creates a new AlienReader object.

Lines 25, 30

Puts prints text to the screen.

Line 27

Opens a connection to the reader, using the IP address given by the

config hash. This version of AlienReader.open() uses the default
username, password, and commandport values. If the connection is
made, open() returns true.

Line 28

Prints the "Hello World" string to the screen. Embedded in the string
is #{r.readername}, which is a method call, "readername" on the
AlienReader object, r. The surrounding #{} structure is a way of
embedding Ruby code directly in a string literal. We could have also
written:
puts "Hello World! I am " + r.readername + "."

Line 33

Closes the connection to the reader.

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

RUNNING EX_HELLOWORLD.RB
Make sure the config.dat file in the examples/ folder has the correct
connection information for your reader, then type "ruby ex_helloworld.rb"
at your PC's command-line. You should see:
$ cd /<pathToYourRubyAPI>/alien-rfid-lib/examples
$ ruby ex_hello_world.rb
---------------------------------Hello World! I am David's 9800.
---------------------------------$

(my reader's name is "David's 9800")

Let's look at a more complicated example.

ex_get_taglist.rb
This example connects to the reader, gets a taglist, and parses it into an array of
AlienTag objects. It then sorts them based on their EPC codes and prints the list.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

=begin rdoc
=Alien Ruby RFID Library Examples
==ex_get_taglist.rb
An example program to play with taglists.
* Connect to an Alien RFID reader. Login.
* Grab some tag data.
* Scan the data for interesting tags and display the results.
Copyright 2008, Alien Technology Corporation. All rights reserved.
=end
# Add the default relative library location to the search path
$:.unshift File.join(File.dirname(__FILE__),"..","lib")
require 'alienreader'
require 'alientag'
require 'alienconfig'

# A little regular expression scanner. Looks at a list of tags and returns a

# message containing those tag IDs that match a particular regular expression filter.
def filter_tags(tl, filter)
i=0
msg = ""
tl.each do |tag|
if tag.id =~ filter
msg << ( i.to_s + "\t" + tag.id + "\r\n")
end
i+=1
end
return msg
end

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

10

# Takes a string returned from a Taglist function call and builds an array of tags.
def build_tag_array(taglist_string)
tl = Array.new
# Grab the taglist from the reader, split it into individual line entries...
lines = taglist_string.split("\r\n")
#...and build an array of tag objects
lines.each do |line|
if line =="(No Tags)"
tl = []
else
tl.push(AlienTag.new(line))
end
end
return tl
end
begin
# Grab various parameters out of a configuration file
config = AlienConfig.new("config.dat")
# Change "reader_ip_address" in the config.dat file to the IP
# address of your reader.
ipaddress = config["reader_ip_address"]
# Create a reader
r = AlienReader.new
# Create a tag list
tl = Array.new
# Use your reader's IP address here.
if r.open(ipaddress)
puts "----------------------------------"
puts 'Connected to: ' + r.readername
# Construct a taglist from the reader's tag list string
# Note: if automode is running this will contain the latest tags.
# If not, the reader will read tags and then return the data.
tl = build_tag_array(r.taglist)
# How many tags did we find?
puts "Number of tags found: " + tl.length.to_s
p tl
# Sort your list to make reading easier. The comparison operator <=>,
# used by sort, is part of the Tag class in alientag.rb.
tl.sort!
# Did we find a particular tag? You can use a regular expression to check
# if elements in the list are tags that match what you are interested in.
puts 'Tag List Matches:'
puts "Tag #\tTag ID"

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

89
90
91
92
93
94
95
96
97
98
99

msg = filter_tags(tl, /.*/)

puts msg
puts "----------------------------------"
# Be nice. Close the connection.
r.close
end
rescue
puts $!
end

Lines 1-11

=begin=end is a multi-line commend. The contents are formatted so

that rdoc can use them.

Line 14

$: is the variable containing the library path. We are prepending

"../lib" to the path to make the Alien classes available. This is
more complicated than it probably needs to be.

Lines 16-18

These lines link in the AlienReader, AlienTag, and AlienConfig

classes.

Lines 23-34

These lines define a method/function called filter_tags. It takes an

array of AlienTags and a regular expression-style filter. Any tags
that match the filter have their EPC appended to the msg variable. An
index and the EPC are separated by a tab, and each line gets a \r\n
line ending. The function returns the generated list of filtered
tags.

Lines 37-53

This build_tag_array method/function is actually part of the

AlienTaglist class, but it nicely shows how to create a new array,
split a string on a delimeter into an array of strings, iterate over
that array (each line of the taglist) and generate a new AlienTag
object based on each line of the taglist. AlienTag expects the
taglist format to be in the default "Text" format, or something that
looks similar.

Line 55-71

This is the main part of the program the part that is executed
first. We use AlienConfig to pull the reader's IP address out of
config.dat, prepare an array to hold our tag data, create the reader
object, and open a connection to it.

Line 76

Fetches the taglist from the reader (r.taglist), and hands it to

build_tag_array().

Lines 79,80

Prints the number of tags, and dumps the array (p is a shortcut to

puts).

Line 83

Sorts the taglist array. The ! after the sort method name indicates
the sort method modifies the object itself, instead of just returning
a sorted copy.

Line 90

Filters the tags using a very loose /.*/ regular expression (it
matches anything). The pretty output is stored in the msg variable,
and it is printed to the screen on the next line.

Line 95

Closes the connection to the reader.

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

11

RUNNING EX_GET_TAGLIST.RB
Make sure the config.dat file in the examples/ folder has the correct connection
information for your reader, then type "ruby ex_get_taglist.rb" at the
command-line. You should see:
$ cd /<pathToYourRubyAPI>/alien-rfid-lib/examples
$ ruby ex_get_taglist.rb
---------------------------------Connected to: David's 9800
Number of tags found: 16
[0000 0000 0000 0000 0000 0008, 0000 0000 0000 0000 0000 0005, 0000 0000 0000 0000 0000
0007, 0000 0000 0000 0000 0000 0006, 0000 0000 0000 0000 0000 000A, 0000 0000 0000
0000 0000 0001, 0000 0000 0000 0000 0000 0004, B00B 1111 0000 0000 0000 0000, 0000
0000 0000 0000 0000 000D, 0000 0000 0000 0000 0000 000C, B00B 0000 0000 0000 0000
0000, 5555 1111 1111 1111 1111 1102, 0000 0000 0000 0000 0000 000B, 0000 0000 0000
0000 0000 0003, 0000 0000 0000 0000 0000 0002, 0000 0000 0000 0000 0000 0009]
Tag List Matches:
Tag #
Tag ID
0
0000 0000 0000 0000 0000 0001
1
0000 0000 0000 0000 0000 0002
2
0000 0000 0000 0000 0000 0003
3
0000 0000 0000 0000 0000 0004
4
0000 0000 0000 0000 0000 0005
5
0000 0000 0000 0000 0000 0006
6
0000 0000 0000 0000 0000 0007
7
0000 0000 0000 0000 0000 0008
8
0000 0000 0000 0000 0000 0009
9
0000 0000 0000 0000 0000 000A
10
0000 0000 0000 0000 0000 000B
11
0000 0000 0000 0000 0000 000C
12
0000 0000 0000 0000 0000 000D
13
5555 1111 1111 1111 1111 1102
14
B00B 0000 0000 0000 0000 0000
15
B00B 1111 0000 0000 0000 0000
----------------------------------

Your Application
Now look at the other examples, play with them, and try some stuff out. More
importantly, think of a problem or use-case that you'd like to solve and try to
implement a solution!
Remember, right now you are still running Ruby code on your PC, and
connecting to the reader over an external socket. When you install your
application on the reader, the exact same code will work the same, except that
you'll be connecting over a local socket on the CommandPortLocal (2300).

12

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Use RAI to Manage Apps on the Reader

In order to conveniently and safely install your application on the reader, you
should use the RAI (Reader Application Interface) utility. The RAI utility is
actually a Ruby script called rai.rb that needs to be copied to a directory
that is in the PATH on your PC to ensure that it is easy and convenient to use
it.
The RAI utility does the job of installing application files onto the reader,
retrieving files, listing the applications installed on the reader and the files
contained in each one, registering your application as a reader "service" and
getting the current status of installed applications.
Here is a walkthrough of RAI in action, using one of the supplied example files,
ex_io_ant.rb. This sample program looks at the reader's ExternalInput value
and, if it is non-zero, sets the AntennaSequence using the ExternalInput as a
bitmask (each bit enables an antenna) and then finally turns AutoMode on. This
is a good example because you can look at the antenna LEDs on the reader to
see what it is doing.
If you don't have the hardware to actuate the ExternalInputs, we'll show you how
to modify the program to read the ExternalOutputs instead (which you can
change manually at the Alien> prompt).

Create and Run ioant on the PC

1. Make a new application directory, called "ioant". That'll be the name of our
program.
C:\>cd \ruby\alien_rfid_lib
C:\ruby\alien_rfid_lib>dir
Directory of C:\ruby\alien_rfid_lib
10/31/2008
10/31/2008
12/17/2008
11/18/2008

04:10 PM
<DIR>
.
04:10 PM
<DIR>
..
03:16 PM
<DIR>
examples
10:35 AM
<DIR>
lib
1 File(s)
289 bytes
4 Dir(s) 12,084,957,184 bytes free

C:\ruby\alien_rfid_lib>mkdir ioant
C:\ruby\alien_rfid_lib>cd ioant

2. Copy the example program into the new ioant folder, changing the name from
ex_io_ant.rb to just ioant.rb. Also, copy config.dat out of the examples
folder.
C:\ruby\alien_rfid_lib\ioant>copy ..\examples\ex_io_ant.rb ioant.rb
1 file(s) copied.
C:\ruby\alien_rfid_lib\ioant>copy ..\examples\config.dat .
1 file(s) copied.

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

13

3. Modify config.dat for our setup. I removed everything except for the
connection information.
C:\ruby\alien_rfid_lib\ioant>e config.dat
(editing file)
C:\ruby\alien_rfid_lib\ioant>type config.dat
#Network Parameters for Reader
reader_ip_address = 10.10.82.72
port = 23
username = alien
password = password

4. (Optional) If you don't have the ability to flip digital inputs connected to your
reader, you can modify the ioant.rb file to look at ExternalOutputs instead,
which you can change manually via a serial connection to the reader or the web
interface. Also, instead of turning AutoMode on (which might reset the
ExternalOutputs to 0 while it is running), you can just do repeated "get taglist"
calls instead.
Modify ioant.rb so that the main code block looks like this (changes are in
bold):
. . .
if r.open(ipaddress)
puts "----------------------------------"
puts 'Connected to ' + r.readername
#read input and init variables
dig_in = r.externaloutput.to_i
old_dig_in = dig_in

# look at outputs instead

done = false
# spin here forever... (or ctrl-c)
until done
dig_in = r.externaloutput.to_i

# look at outputs instead

if dig_in != 0
# Don't do anything if XO=0
if dig_in != old_dig_in
# Change AntSeq if XO changed
r.antennasequence = map_input_to_antennas(dig_in)
end
r.taglist
# Fetch taglist (no AutoMode)
end
old_dig_in = dig_in
sleep 0.1
end

# sleep 0.1 sec, not 1 sec

puts "----------------------------------"
# be nice. Close the connection to the reader.
r.close
end
. . .

14

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

5. Run ioant.rb locally. While it is running, either change your digital inputs, (or
outputs if you modified the example) and you should see the corresponding
antenna LEDs lighting up. Type Ctrl-C to exit (this may leave AutoMode running).
C:\ruby\alien_rfid_lib\ioant>ruby ioant.rb
---------------------------------Connected to David's 9800
(ctrl-c)
ioant.rb:77:in `sleep': Interrupt
from ioant.rb:77

Install the ioant Application on the Reader

Now we'll use the RAI tool to load the ioant application onto your reader. Make
sure RAI has been properly installed by running "rai help" at the command
prompt.
C:\ruby\alien_rfid_lib\ioant>rai help
Alien Reader Application Interface (RAI) ver.1.0.0
Usage: rai.rb [options]
Configure options:
configure (conf,config)

configure authorization options

Transfer options:
put [<file1>[ <file2>...]]
get [<file1>[ <file2>...]]

put file(s) to the reader

retrieve file(s) from the reader

Install options:
register (rg, reg)
-p, --priority <priority>
-c, --cli <cli>
unregister (ur, ureg, unreg)
delete (del)

register application on the reader

application startup priority (70-90), default 80
application Command Language Interpreter (ruby, bin)
unregister application on the reader
delete application on the reader

Status options:
list (l)
[apps|<app>]
status (s) [apps|<app>]

list applications installed on the reader

display status of application on the reader

Common options:
help (h)
version (v, ver)

display help information

display version information

Before RAI can transfer files to your reader, you need to configure it with the
reader's IP address, login credentials, the command interpreter for your app
(ruby), and the default startup priority (in relation to other reader services).

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

15

1. Run "rai conf" to configure RAI. Use your reader's IP address, a username
of "alien", and a password of "a113n". Your command line interpreter (cli) is
"ruby. A startup priority of 80 will work in most cases. The existing reader
services have the following startup priority:
10 serial
20 snmp
40 heartbeat
95 ifmon
C:\ruby\alien_rfid_lib\ioant>rai conf
Enter 'hostname': 10.10.82.72
Enter 'username': alien
Enter 'password': a113n
Enter '
cli': ruby
Enter 'priority': 80

This generates a ".rai" configuration file in your application directory. Once this
configuration file is created RAI won't have to keep asking you for this
information. You can rerun "rai conf" at any time to edit this file.

2. Before you load the files, you need to change config.dat so that when ioant
runs on the reader, it connects to localhost (127.0.0.1) on port 2300.
C:\ruby\alien_rfid_lib\ioant>e config.dat
(editing file)
C:\ruby\alien_rfid_lib\ioant>type config.dat
#Network Parameters for Reader
reader_ip_address = 127.0.0.1
port = 2300
username = alien
password = password

3. Now load the entire set of application files with "rai put" (you must do this
from within the ioant/ directory).
C:\ruby\alien_rfid_lib\ioant>rai put
uploading 'C:/ruby/alien_rfid_lib/ioant/config.dat'...done
uploading 'C:/ruby/alien_rfid_lib/ioant/ioant.rb'...done

At this point, your files are loaded into the proper location on the reader, right
alongside the Alien API libraries. In order to run ioant (manually or automatically
after the reader boots up), you need to register it with the reader subsystem.

4. Verify the files were successfully transferred to the reader with "rai list".
C:\ruby\alien_rfid_lib\ioant>rai list
config.dat
ioant.rb
ioant.sh

16

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Register the ioant Application and Run It

Once your application is loaded on the reader, you register it with the "rai
register" command. This generates a control script for your application, and
links that control script into the reader subsystem along with the other reader
services, such as the Heartbeat, SNMP, Serial interface, and the network
Interface Monitor (ifmon).
You can then use the existing Service command at the Alien> prompt to manage
when your application runs.

1. Register the application on the reader with "rai register". Since this
generates files on the reader and changes the way the reader might operate, you
are asked to confirm this action.

C:\ruby\alien_rfid_lib\ioant>rai register
Register 'ioant' RUBY application as Alien service with PRIORITY=80?
please type 'yes' or 'no':yes

2. Verify that ioant is installed and registered by asking RAI for the list of
applications: "rai list apps". The "r" prefix indicates the application has
been registered as a reader service.

C:\ruby\alien_rfid_lib\ioant>rai list apps

r ioant

3. Check the status of the application/service with "rai status".

C:\ruby\alien_rfid_lib\ioant>rai status
s A 80 ioant

4. Notice that this looks just like what you see when you use the Service
command at the Alien> prompt (I'm doing this over the serial interface).

Alien>Service all status

R A 10 serial
R A 20 snmp
R A 40 heartbeat
s A 80 ioant
R A 95 ifmon

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

17

5. The "s" indicates the service is stopped ("R" indicates Running). The next
letter, "A", indicates the service is configured to Autostart after the reader boots
(a "d" indicates this is disabled). Therefore, our new ioant service is not running,
but will start up whenever the reader boots. Let's start it manually at the Alien>
prompt with "Service ioant start", verify it works, and then stop it and
disable autostart.
Alien>Service ioant start
R A 80 ioant
Alien>ExternalOutput=55 (or actuate your digital inputs)
ExternalOutput = 5
(verify the reader is reading on antennas 0 and 2)
Alien>Service ioant stop
s A 80 ioant
Alien>Service ioant disable
s d 80 ioant

Unregister the ioant Application

If you no longer want your application to be available as a reader service, you
can unregister it with "rai unregister".

C:\ruby\alien_rfid_lib\ioant>rai unregister
Unregister 'ioant' application from being an Alien service?
please type 'yes' or 'no':yes
C:\ruby\alien_rfid_lib\ioant>rai list apps
ioant
(no longer has "r")
Alien>Service all status
R A 10 serial
R A 20 snmp
R A 40 heartbeat
R A 95 ifmon
(missing from list of Services)

18

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

Retrieve Application Files from the Reader

If you want to retrieve application files from the reader log files, data files, etc.
you can use "rai get". Without any further arguments, the get command
retrieves all of the files in the application directory, or you can indicate which
file(s) to get. This action will overwrite any similarly named files in the current
application directory!
C:\ruby\alien_rfid_lib\ioant>rai get
downloading 'config.dat'...done
downloading 'ioant.rb'...done
downloading 'ioant.sh'...done
C:\ruby\alien_rfid_lib\ioant>rai get config.dat ioant.rb
downloading 'config.dat'...done
downloading 'ioant.rb'...done

Remove an Application from the Reader

To completely remove your application files from the reader, use the
"rai delete" command.
C:\ruby\alien_rfid_lib\ioant>rai delete
Delete 'ioant' application from the reader?
please type 'yes' or 'no':yes
C:\ruby\alien_rfid_lib\ioant>rai list apps
(nothing)

Alien developed the Alien RFID Custom Application (ARCA) kit to accommodate
the expanding list of applications for Gen 2 RFID. Alien partners and end users
like you are discovering many new ways to use RFID technology and need the
ability to adapt off-the-shelf readers to new applications. ARCA enables you to
deliver more effective solutions, more quickly for emerging applications. Thanks
for using Alien Technology RFID products.
For support please contact
[email protected].
The Alien RFID Team

ARCA ON-READER PROGRAMMING OVERVIEW

DOC. CONTROL # 8102113-000 REV. A

19