RFID::Reader - Abstract base class for an RFID reader

This abstract base class provides a general framework for a generic RFID reader. To actually create a reader, you'll have to use an object corresponding to the type of reader you're using.

This documentation discusses aspects of an RFID reader that apply to all readers.

Here's an example of how you might use a class derived from this one:

    use RFID::Blammo::Reader::TCP;
    my $reader = 
      RFID::Blammo::Reader::TCP->new(PeerAddr => 10.20.30.40,
                                     PeerPort => 4001)
        or die "Couldn't create Blammo reader";
    my $version = $reader->get("ReaderVersion");
    $reader->set(AntennaSequence => [ 4,3,2,1]);
    my @tags = $reader->readtags();
    foreach my $tag (@tags)
    {
	print "I see tag ",$tag->type,".",$tag->id,"\n";
    }

This abstract base class provides a general framework and some utility functions for writing an RFID reader. It also provides emulation for some features which may not be supported by all readers.

Because of its general nature, many of the options and methods described here may not be supported in your specific reader. They are documented here so that all readers that implement these features will implement them in the same manner. To make this clearer, elements of this class that should work for all readers will be marked All Readers, while elements that will only work with some readeres will be marked Some Readers. To find out whether your reader supports a specific reader, consult its documentation.

This method must be supported by All Readers.

Set one or more properties associated with a reader. Depending on implementation, this may send one or more commands to the reader, set an internal flag, or take some other action.

This method takes a hash with the properties to be set as keys, and their new values as values. It returns a list of errors that occured; if no errors occured, it will return an empty list. In a scalar context, that evaluates to the number of errors that occured, so you can test for errors like this:

    my @errs = $reader->set(SomeVariable => "New Value") == 0
      or die "Couldn't set SomeVariable: @errs";

See Properties for the properties that can be set.

This method must be supported by All Readers.

Get various properties of the reader or the internal state of the object. This method takes a list of parameters whose values you'd like to get. In a list context, it returns a hash with the parameters you asked for as the keys, and their values as the values. In a scalar context, it returns the value of the last property requested. If a value for the requested property can't be found, it is set to undef.

For example:

    my $ReaderVersion = $reader->get('ReaderVersion');
    my %props = $reader->get(qw(ReaderVersion AntennaSequence ));

See Properties for the properties that can be retreived with get.

This method must be supported by All Readers.

Read all of the tags in the reader's field, honoring any settings affecting the reading and filtering of tags. This returns a (possibly empty) list of RFID::Tag objects (or objects derived from this type) . For example:

    my @tags = $reader->readtags();
    foreach my $tag (@tags)
    {
	print "I see tag ",$tag->type,".",$tag->id,"\n";
    }

In the event of a serious error, this method will raise an exception with die. If you want your program to keep going in the face of serious errors, you should catch the exception with eval.

Parameters are a hash-style list of parameters that should be set (set) for just this read.

This method is supported by Some Readers.

Request that all tags addressed by the reader go to sleep, causing them to ignore all requests from the reader until they are awakened (waketags). Which tags are addressed by the reader is affected by various settings, possibly including Mask and AntennaSequence.

Parameters are a hash-style list of parameters that should be set (set) for just this read.

In the event of a serious error, this method will raise an exception with die. If you want your program to keep going in the face of serious errors, you should catch the exception with eval.

Request that all tags addressed by the reader which are currently asleep (sleeptags) wake up, causing them to once again pay attention to requests from the reader. Which tags are addressed by the reader is affected by various settings, possibly including Mask and AntennaSequence.

Parameters are a hash-style list of parameters that should be set (set) for just this read.

In the event of a serious error, this method will raise an exception with die. If you want your program to keep going in the face of serious errors, you should catch the exception with eval.

There are various properties that are managed by the get (get) and set (set) methods. Some of these settings will cause one or more commands to be sent to the reader, while other will simply return the internal state of the object. The value for a property is often a string, but can also be an arrayref or hashref.

Some Readers.

An arrayref of the antenna names that should be queried, and in what order. RFID drivers can name their antennas any way they like, though often they will be numbers. For example:

    $reader->set(AntennaSequence => [0,1,2,3]);

The default AntennaSequence is reader-specific.

All Readers.

Control the amount of debugging information sent to STDERR. A higher value for this property will cause more information to be output.

Some Readers.

Set or get a bitmask for the tags. After setting the mask, all commands will only apply to tags whose IDs match the given mask.

The mask format is a string beginning with the bits of the tag as a hex number, optionally followed by a slash and the size of the mask, optionally followed by the bit offset in the tag ID where the comparison should start. For example, to look for 8 ones at the end of a tag, you could use:

    $reader->set(Mask => 'ff/8/88');

A zero-length mask (which matches all tags) is represented by an empty string.

All Readers, possibly through emulation.

A boolean value controlling whether duplicate tags should be removed from the list returned by readtags.

RFID::Tag, RFID::Reader::Serial, RFID::Reader::TCP, http://whereabouts.eecs.umich.edu/code/rfid-perl/, The manual for your particular RFID driver class.

Scott Gifford <gifford@umich.edu>, <sgifford@suspectclass.com>

Copyright (C) 2004-2006 The Regents of the University of Michigan.

See the file LICENSE included with the distribution for license information.