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:
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:
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:
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/Impinj/ Directory that contains the Impinj extension C++ files. It is combined with ../Definitions/Impinj/*def.xml
Library/Impinj/impinj_ltkcpp_genout.cpp Library/Impinj/impinj_ltkcpp.h Wrappers that combine and condition the generated C++ source and header files for Impinj general extensions like Tag Direction, Search Mode, etc.
Library/Impinj/impinjinternal_ltkcpp_genout.cpp Library/Impinj/impinjinternal_ltkcpp.h Wrappers that combine and condition the generated C++ source and header files for Impinj internal extensions like TCS. These are never release in any form outside of Impinj.
Library/Impinj/Makefile Makefile for Impinj extensions, both general and internal.
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/oem/ generated This directory is created and populated with the standard LLRP library and headers plus the general Impinj extension headers and library.
Release/std/ generated This directory is created and populated with the standard LLRP library and headers.
Release/tcs/ generated This directory is created and populated with the standard LLRP library and headers plus the general Impinj extension headers and library plus the internal Impinj extension headers and library
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:
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:
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/libltkcppimpinj VS_LTKCPP/libltkcppimpinj/libltkcppimpinj.vcproj Builds libraries for the Impinj general extensions. The libraries are Debug/libltkcppimpinj_d.lib and Release/libltkcppimpinj_r.lib. Warning level reduced to 2 for impinj_ltkcpp_genout.cpp.
VS_LTKCPP/libltkcppimpinjinternal VS_LTKCPP/libltkcppimpinjinternal/libltkcppimpinjinternal.vcproj Builds libraries for the Impinj internal extensions. The libraries are Debug/libltkcppimpinjinternal_d.lib and Release/libltkcppimpinjinternal_r.lib. Warning level reduced to 2 for impinjinternal_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 =========
1.5.9