RFID::LLRP::Link

SYNOPSIS

This module provides routines to connect and gracefully disconnect an LLRP session, as well as to support reading LLRP messages from the link.

DESCRIPTION

This package provides the necessary routines to establish and disestablish an LLRP session. It provides a routine for reading complete LLRP messages from the link.

This module is designed to do as little as possible... for example, it does not derive from the socket class. Instead, it establishes the connection and returns the socket for the caller to handle.

PRACTICAL EXAMPLE

        use RFID::LLRP::Builder qw(encode_message decode_message);
        use RFID::LLRP::Link qw(reader_connect reader_disconnect read_message);
        
        my $doc = <<'EOT';
        <?xml version="1.0" encoding="UTF-8"?>
        <GET_READER_CAPABILITIES MessageID="0">
                <RequestedData>0</RequestedData>
        </GET_READER_CAPABILITIES>
        EOT
        my $sock = reader_connect ('speedway-xx-yy-zz');
        $sock->send (encode_message ($doc));
        print (decode_message read_message ($sock))->toString (1);
        reader_disconnect ($sock);

DETAILS

API

reader_connect ($name)

This function will connect to the reader whose name is specified as $name. $name may be an IP address or a DNS name.

It handles reading the READER_EVENT_NOTIFICATION which indicates whether the connection is now valid for LLRP traffic. If the reader is busy the session is closed and nothing is returned.

If the reader is not busy with another client, the socket is returned.

If called in list context, this routine will also return $sock, $doc, $buf in that order. $buf is the undecoded LLRP binary READER_EVENT_NOTIFICATION, and $doc is the XML DOM object of the same message but decoded.

reader_accept

This function will accept a single LLRP connection.

It handles reading the READER_EVENT_NOTIFICATION which indicates whether the connection is now valid for LLRP traffic. If the reader is busy the session is closed and nothing is returned.

If the reader is not busy with another client, the socket is returned.

If called in list context, this routine will also return $sock, $doc, $buf in that order. $buf is the undecoded LLRP binary READER_EVENT_NOTIFICATION, and $doc is the XML DOM object of the same message but decoded.

reader_disconnect ($sock)

This function will gracefully close the provided socket. Use this on the socket returned when calling reader_connect().

It is important that you disconnect from the reader, or else subsequent connections to the reader may fail.

parse_envelope ($buf)

This utility function will permit decoding the envelope of a raw LLRP byte string. It returns $ver, $msg_type, $msg_len and $msg_id, in that order.

read_bytes ($socket, $size, $timeout)

This utility function will read $size bytes from $socket with a $timeout second timeout. Upon timeout it will die with ``Error: receive timed out\n''

If no $timeout parameter is provided it will default to 5 seconds.

If you wish to block on read_bytes indefinitely, provide a negative value for $timeout.

The bytes read, if any, are returned as a Perl string.

If you do not know whether to immediately expect any response, you should call this routine from within an eval {} construct.

Programmers should eschew this function in favor of read_message().

read_message ($socket, $timeout)

This utility function will read a complete LLRP message from the specified $socket with a configurable seconds timeout. Upon timeout it will die with ``Error: receive timed out\n''

If no $timeout parameters is provided it will default to 5 seconds.

If you wish to block on read_message() indefinitely, provide a negative value for $timeout.

The LLRP binary-formatted message is returned as a Perl string.

monitor ($sock, TimeFence => ?, Timeout => ?, ReturnUpon|ErrorUpon => [...], Count => {} )

monitor() expects the socket followed by a hash of named parameters. Any parameter except for $sock may be omitted. Omitting TimeFence and/or Timeout indicates that the omitted timeout mechanisms should not be used. If none of timeout, fence, ReturnUpon, and ErrorUpon is provided, then the only thing that will stop monitor() from running is an exception in the internal LLRP routines.

This function reads LLRP messages until one of the following events occurs:

  1. time() surpasses TimeFence
  2. There has been no message received in Timeout seconds
  3. One of the XPath queries named in ReturnUpon matches a received message
  4. One of the XPath queries named in ErrorUpon matches a received message In this case, monitor will die with an error message.

ReturnUpon and ErrorUpon Custom Handlers

You can provide a subroutine reference as a custom handler in place of XPath strings. Returning 'true' triggers 'return' if it's a part of a ReturnUpon array. Returning 'true' triggers 'die' if the subroutine reference is part of a ErrorUpon array.

Count Hash

Pass an anonymous hash with key 'Count' to count up occurances of a set of XPath queries. The keys of the hash are XPath queries. The associated values are references to scalars. Monitor will initialize the scalar variables to zero.

Counts are always performed before the ReturnUpon and ErrorUpon handlers.

QualifyCore => 0 or 1

See the description of QualifyCore given for transact().

MaxQueue => 0 or more

Depending on the Timeout and TimeFence limits, and the ReturnUpon and ErrorUpon rules you set, monitor() could block for a long time.

If provided and greater than zero, the MaxQueue parameter is used to determine the maximum number of recent messages up to and including the timeout or rule match that will be retained (and returned).

0 or not present means ``keep all messages'' 1 or more means ``keep at most MaxQueue count of messages.''

Monitor returns:

The timeout string (Timeout [inactivity] or TimeUp [hit fence]) or the decoded message that matched if called in scalar context
The timeout string or decoded message, followed by all messages which occured from the time the monitor operation started up until the match or timeout occured. If there was a match, the final message is the message that matched. You can tell the difference between a timeout and a match since the first parameter will be a reference or not, depending (use the ref call).

It is anticipated that monitor() will be called multiple times with the same $time_fence. This permits running, for example, 20 seconds of inventory. Eventually you will call monitor() and it will return with 'TimeUp' indicating that the operation has completed.

The $timeout parameter is provided mainly for cases where you expect a specific response to a command in a fairly short period of time. If it doesn't come, ('Timeout') will be returned instead.

transact ($socket, $doc, %encode_params)

This high-level routine will perform a complete LLRP transaction: it transmits the provided document, first transforming it from string or file to an XML DOM tree, if necessary.

The allowed %encode_params include:

  1. Timeout => maximum time to wait
  2. Trace => 1 (print LLRP-XML decoded messages as received) or undef (no trace)
  3. BadNewsOK => 1 (don't raise exception on bad status) or undef (raise exceptions on bad status)
  4. Force => 1 (Best effort to encode a message with errors) or undef (raise exceptions)
  5. Tree => 1 (DOM object is provided) or undef (string or file is provided)
  6. File => 1 (String represents a file path) or undef (XML document provided in string form)
  7. QualifyCore => 0 or 1

    QualifyCore allows you to control whether XML returned to you puts LLRP parameters and fields into the LTK-XML namespace.

    This is important for XPath 1.0 queries, which is the only kind XML::LibXML supports. Elements that are in ``no-namespace'' do not need to be qualified with a prefix. This tends to make XPath query strings much easier to read and type.

    0 => Core parameters and fields are to be placed in ``no-namespace'',

    1 => Core parameters and fields are to be placed in LLRP core namespace

    Note that since we use Sub::Exporter, you can specialize the monitor() and transact() routines at import time, and never have to pass QualifyCore again.

In ``list context'' transact returns the ($req, $rsp, @ntf).

  1. $req an XML DOM tree representing the original request
  2. $rsp an XML DOM tree representing the reader response
  3. @ntfs a list of XML DOM tree objects including messages strictly between $req and $rsp
fasttran ($socket, $msg, %encode_params)

This special-purpose routine will perform a complete LLRP transaction: it transmits the provided binary message and waits for a status response. It is a lightweight alternative to transact for cases when you can't afford decoding the XML to a DOM tree during the transaction.

The allowed %encode_params include:

  1. Timeout => maximum time to wait
  2. Trace => 1 (print LLRP-XML decoded messages as received) or undef (no trace)
  3. BadNewsOK => 1 (don't raise exception on bad status) or undef (raise exceptions on bad status)

In ``list context'' transact returns the ($status_code, @ntf).

  1. $status_code is an integer representing the transactions status. 0 is 'Success.'
  2. @ntfs a list of all binary LLRP messages received from the reader including the message causing fasttran to return control to the caller.

AUTHOR

John R. Hogerhuis

Kunal Singh

BUGS

None

SEE ALSO

EPCGlobal LLRP Specification

COPYRIGHT

Copyright 2007, 2008 Impinj, Inc.

Licensed under the Apache License, Version 2.0 (the ``License''); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an ``AS IS'' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.