LLRP Toolkit for C PlusPlus (LTKCPP)

Version 1.0.0.5

Author:

Gordon Waidhofer

OVERVIEW OF THE LLRP Tool Kit for C++ Last updated 28 Jan 2008

INTRODUCTION ============

This is a high level overview of and orientation to the LLRP Tool Kit for C++ (LTKCPP) on Linux and Windows.

The most recent versions of and news about the LLRP Tool Kit is available on SourceForge.net

http://sourceforge.net/projects/llrp-toolkit/

This document is organized: WHAT IT IS -- a summary for an apps programmer HOW IT WORKS -- orientation to the internals LIST OF FILES -- small description of each source file TODO LIST -- what still needs to be done and known problems

WHAT IT IS ==========

From the application C++ programmer's view:

• There is a C++ class definition for each LLRP message and parameter type
• An application constructs messages as "element trees" of these structures.
• Using a transaction layer, an element tree is encoded into a "binary frame" and sent to the LLRP compatible RFID reader.
• Messages from the reader are decoded into element trees.
• Applications traverse the element trees to retrieve results and tag data
• Applications are responsible to be sure element trees are properly deallocated

HOW IT WORKS ============

The LTKCPP library code has two major parts.

The first part is the base types, classes, and subroutines. These are written by hand.

The second part is generated code. The code generators are written in XSLT and process ../Definitions/Core/llrp-1x0-def.xml. For each LLRP message and parameter type, generated are:

• A C++ class
• A type descriptor -- name, type number, constructor function pointer, etc.
• A set of member functions to encode/decode the classes.

The generated encode/decode functions act through an abstract interface. For example, the generated function that encodes an ROBoundarySpec does not know whether the abstract encoder is being used to generate a LLRP binary frame or XML text.

The model for decode is a little tricky to understand at first:

• Identify the message or parameter type.
• Look in a type registry to find the type descriptor.
• Call the generated decodeFields() function.
• The remainder of the message or parameter is considered a sequence of subparameters. Each are decoded by the method described here.
• As each subparameter is decoded it is appended to an all-list.
• Once all subparameters have been decoded, a generated assimilateSubParameters() function is called to walk the all-list and update the individual struct members.

Errors during encode/decode are generally handled by setting values in an error details structure and then terminating. The error details include an error number, a string, and sometimes a reference type descriptor and/or field descriptor. With rare exception, this is enough information for the application programmer to determine what went wrong with the application program.

LIST OF FILES =============

Documentation/ Directory for LTKCPP-specific documentation. Empty at this time.

Examples/ Directory of example applications.

Examples/example1.cpp Implements the "LLRP Hello World" program. It does a five second inventory five times. Requires a LLRP reader. Runs from the command line (not a GUI).

Examples/Example-Makefile The Makefile that is copied to the example directory of each binary distribution. The copy is named "Makefile" and gets include files and libraries from directory .. (dot-dot, the parent dir).

Examples/Makefile Makefile for the examples.

INSTALL.TXT Terse instructions for obtaining and building LTKCPP

Library/ The principal directory of LTKCPP.

Library/gencode.bat A Windows command script for running the MSXML code generator on windows. This must be run by hand before using Visual Studio to build the library and programs. Requires MSXML.EXE which can be downloaded at no charge from Microsoft.com. There are instructions within this gencode.bat file.

Library/LLRP.org/ Directory that contains the LLRP.org extension C++ files. It is combined with ../Definitions/LLRP.org/LLRPOrgExampleDef.xml These extensions don't really do anything, they are just used for testing and to demonstrate how the LTK implementations build extensions.

Library/LLRP.org/llrporg_ltkcpp_genout.cpp Library/LLRP.org/llrporg_ltkcpp.h Wrappers that combine and condition the generated C++ source and header files for LLRP.org extensions.

Library/LLRP.org/Makefile Makefile for LLRP.org extensions.

Library/ltkcpp_array.cpp Helper functions for array types, like utf8v "strings"

Library/ltkcpp_base.h Base classes of LTKCPP, hand coded. Base classes include: Elements -- common between messages and parameters Messages -- base class for LLRP messages Parameters -- base class for LLRP parameters TypeDescriptors -- info about element types, eg name, typenum FieldDescriptors -- info about fields within elements NamespaceDescriptors -- info about an XML namespace, eg prefix, URI VendorDescriptors -- info about a vendor, eg name, PEN Decoders -- abstract interface for decoders: external->elements Encoders -- abstract interface for decoders: elements->external TypeRegistry -- used to help look up the right TypeDescriptor ErrorDetails -- helps explain what went wrong

Library/ltkcpp_connection.cpp Library/ltkcpp_connection.h Implements a simple transaction interface for conveying messages to/from a remote reader. It does not try to be all things to all people. Rather it is an important reference to aid developers of application-specific transaction layers.

Library/ltkcpp_element.cpp Subroutines for elements (parameters and messages)

Library/ltkcpp_encdec.cpp Subroutines for encoders and decoders

Library/ltkcpp_error.cpp Subroutines for ErrorDetails

Library/ltkcpp_framedecode.cpp Frame decoder, translates "LLRP Binary" into element trees. Conforms, of course, the Decoder abstract definition (see ltkcpp_base.h)

Library/ltkcpp_frameencode.cpp Frame encoder, translates element trees into "LLRP Binary". Conforms, of course, the Encoder abstract definition (see ltkcpp_base.h)

Library/ltkcpp_frameextract.cpp Used to identify and extract a single "LLRP Binary" frame from a byte buffer. LLRP frames can be coallesced in a network socket. This does the first level interpretation of the bytes so that the frames can be individually processed.

Library/ltkcpp_frame.h Declarations for ltkcpp_frame*.cpp

Library/ltkcpp_gen_cpp.xslt XSLT code generator for C++ definitions. This is where the generated encode/decode/etc functions are. Used to process ../../Definition/Core/llrp-1x0-def.xml into a transient file named out_ltkcpp.inc. Similarly used to process extension definitions. Requires xsltproc(1)

Library/ltkcpp_gen_h.xslt XSLT code generator for C++ declarations (class declarations). This is where the structs are defined for each message and parameter. Used to process ../../Definition/Core/llrp-1x0-def.xml into a transient file named out_ltkcpp.h. Similarly used to process extension definitions. Requires xsltproc(1)

Library/ltkcpp_genout.cpp Wrapper that combines platform headers, LTKCPP base headers, and the generated out_ltkcpp.inc. After the code generation this file is ready to compile.

Library/ltkcpp.h API C header file. This is the one applications #include. It #includes out_ltkcpp.h along with platform and LTKCPP header files.

Library/ltkcpp_hdrfd.cpp Contains FieldDescriptors (see ltkcpp_base.h) for message and parameter header fields.

Library/ltkcpp_platform.h Header file that #includes the right files for the current platform. It uses #ifdef linux, etc. This is where basic typedefs, like llrp_u32_t, are done.

Library/ltkcpp_typeregistry.cpp A type registry is a collection of pointers to type descriptors. During decode, a decoder might ask a type registry to find the type descriptor for message type number 123.

Library/ltkc_xmltextencode.c XML text encoder, translates element trees into XML text. It is essentially a pretty-printer. Conforms, of course, the Encoder abstract definition (see ltkc_base.h) The output is a string saved to a caller supplied buffer. It is mostly a trouble-shooting aid.

Library/ltkc_xmltext.h Declarations for ltkc_xmltext*.c

Library/Makefile Makefile for the library.

Makefile Top-level makefile. Builds the library, tests, and examples.

README.TXT This file that you are reading.

Release/ Directory where binary distributions are built

Release/Makefile Makefile to build binary distributions

Release/std/ generated This directory is created and populated with the standard LLRP library and headers.

Tests/ Directory of test programs.

Tests/dx10?.cpp All dx10?.cpp (dx101, dx102, etc) are stand-alone tests of the library. No reader is required.

Tests/dx101.cpp Reads a file containing LLRP binary frames. For each frame:

• Decode it into an element tree
• Encode it into XML text
• Encode it into an LLRP frame
• Compare the original input frame to the one produced by the encoder
• Destruct the element tree. It is used as a regression to make sure things work consistently and to verify there are no memory leaks. Runs from the command line (not a GUI).

Tests/dx20?.cpp All dx20?.cpp (dx201, dx202, etc) are tests of the library that require a reader to talk to.

Tests/dx201.cpp Does a simple inventory operation with some bells and whistles. It also does extra queries. Along with the basic library this exercises the ltkcpp_connection.[ch] transaction layer. Runs from the command line (not a GUI).

Tests/Makefile Makefile for the test programs.

Tests/RUN101 A shell script that runs dx101 with certain inputs and validation tools. Reports PASS/FAIL.

Tests/RUN201 A shell script that runs dx201 with certain validation and measurement tools. Used to characterize CPU and memory utilization.

VS_LTKCPP/ Visual Studio directory. The projects here reference the source files above. General options for all projects:

• Precompiled headers are turned off.
• Code generation uses Multi-threaded DLL and Multi-threaded Debug DLL
• For the three console applications, ..\.. added as include dir
• For dx201 and example1, added Ws2_32.lib to linker input

VS_LTKCPP/dx101/ VS_LTKCPP/dx101/dx101.vcproj Builds dx101 (see above)

VS_LTKCPP/dx201/ VS_LTKCPP/dx201/dx201.vcproj Builds dx201 (see above)

VS_LTKCPP/example1/ VS_LTKCPP/example1/example1.vcproj Builds example1 (see above)

VS_LTKCPP/libltkcpp/ VS_LTKCPP/litltkcpp/libltkcpp.vcproj Builds libraries for base LTKCPP library including the core protocol support. The libraries are Debug/libltkcpp_d.lib and Release/libltkcpp_r.lib. Warning level reduced to 2 for ltkcpp_genout.cpp.

VS_LTKCPP/libltkcppllrporg VS_LTKCPP/libltkcppllrporg/libltkcppllrporg.vcproj Builds libraries for the LLRP.org example extension. The libraries are Debug/libltkcppllrporg_d.lib and Release/libltkcppllrporg_r.lib. Warning level reduced to 2 for llrporg_ltkcpp_genout.cpp. This is an example and doesn't really do anything nor is it used by anything.

VS_LTKCPP/Makefile Makefile to support the top-level Makefile 'clean' target. Also has target 'fugazi' that create (touch(1)) the library files so that Release/Makefile can be tested.

VS_LTKCPP/VS_LTKCPP.ncb VS_LTKCPP/VS_LTKCPP.sln VS_LTKCPP/VS_LTKCPP.suo Visual studio config files. Probably only the .sln is important.

TODO LIST =========

• Need to settle question of formatting whether u1 fields are implictly boolean or not
• Need to finish comments, especially ltkcpp_base.h
• Need a decoder for XML text (XML text -> element tree)
• MAYBE: Need encoder and decoder for XML DOM trees
• Need a test for accessors (dx102)
• Need a test for XML encode/decode (dx103) (needs XML encode/decode first)
• On Windows, need a way to compare the dx101 output to the golden file
• Windows prior to WinXP does not have getaddrinfo(). Probably should step back to gethostbyname()
• Need to test on more versions of Visual Studio

---