875-0049-10 RevA Mercury API Programmer’s Guide For: Mercury API v1.23.0 and later Supported Hardware: M6 and Astra-EX (firmware v4.19.1 and later) M6e (firmware v1.13.1 and later) Micro (firmware v1.3.0 and later) M5e, M5e-C, USB and Vega (firmware v1.7.
Government Limited Rights Notice: All documentation and manuals were developed at private expense and no part of it was developed using Government funds. The U.S. Government’s rights to use, modify, reproduce, release, perform, display, or disclose the technical data contained herein are restricted by paragraph (b)(3) of the Rights in Technical Data — Noncommercial Items clause (DFARS 252.227-7013(b)(3)), as amended from time-to-time.
Revision Table Date Version Description 6/2009 01 Rev1 First Draft for MercuryAPI RC1 8/2009 01 Rev1 Updates to Reader methods for changes in v1.1 updates to gpoSet and gpiGet methods other updates for official v1.1. release. 12/2009 02 Rev1 Added info on automatic antenna switching to Virtual Antennas section. 2/2010 02 Rev1 Added protocol configuration additions for M6e. Added details/clarification to various content based on customer feedback.
Date 8/2012 Version 08 RevA Description • Added details on C porting • Added details about transportTimeout to Connect info • Removed Select/Filter limitation when Continuous Reading • Added details on locking tags • Improved Performance Tuning section with details on more settings. • added software license info • added .
Contents Introduction to the MercuryAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Language Specific Reference Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Supported Languages and Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Language Specific Build and Runtime Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StatusListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 ReaderCommException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 ReaderCodeException . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Gen2 Tag Specific TagOps - NXP G2* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Gen2.NXP.G2I.SetReadProtect and Gen2.NXP.G2X.SetReadProtect 49 Gen2.NXP.G2I.ResetReadProtect and Gen2.NXP.G2X.ResetReadProtect 49 Gen2.NXP.G2I.ChangeEas and Gen2.NXP.G2X.ChangeEas 49 Gen2.NXP.G2I.EasAlarm and Gen2.NXP.G2X.EasAlarm 50 Gen2.NXP.G2I.Calibrate and Gen2.NXP.G2X.Calibrate 50 Gen2.NXP.G2I.ChangeConfig 50 Gen2 Tag Specific TagOps - Impinj Monza4 . . . . . . . . . . . . . .
Automatic Antenna Switching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Virtual Antenna Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 GPIO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Get/Set Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Universal Reader Assistant 2.0 92 USB Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 WinCE Driver Installation Procedure 92 WinCE Sample Application Installation Procedure 92 C Language Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 C Language Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building On-Reader Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Installing the Cross Compiler Environment . . . . . . . . . . . . . . . . . . . . .
Introduction to the MercuryAPI The MercuryAPI is intended to provide a common programming interface to all ThingMagic products. This MercuryAPI Programmer’s Guide provides detailed information about the programming interface and how to use it to connect, configure and control ThingMagic products. This version of the MercuryAPI Guide is intended for use with the following hardware firmware versions: M6 and Astra-EX (firmware v4.19.1 and later) M6e (firmware v1.13.
C#/.NET - [SDK Install Dir]/cs/MercuryAPIHelp/index.html C - [SDK Install Dir]/c/doc/index.html Note All code examples in this document will be written in Java, unless otherwise noted.
Supported Languages and Environments Supported Languages and Environments The MercuryAPI is currently written in Java, C# and C and is supported in the following environments: Managed code in the .NET Compact Framework v2.0 SP2, callable from .NET applications written in any language on any Windows platform supporting the Compact Framework v2.0. Note: .NET interface does not support LLRPReaders on WinCE and Windows Mobile platforms.
Supported Languages and Environments On Reader Applications - Describes how to build and install C language applications on LLRPReaders. Performance Tuning - Describe how to tailor the reader’s settings to fit your unique RFID environment.
Example Code Example Code In addition to using this guide, there are several example application and code samples that should be helpful in getting started writing applications with the MercuryAPI. Please see the following directories in the MercuryAPI zip package for example code: /cs/samples - Contains C# code samples in the ./Codelets directory and several example applications with source code. All samples include Visual Studio project files.
Hardware Specific Guides Hardware Specific Guides The MercuryAPI is intended to allow cross-product development. However, due to differences in product features and functionality, 100% compatibility is not possible and specific feature differences are not all clearly described in this Guide. It is important to read the product specific hardware guide to fully understand the features and functionality available for each product. Product hardware guides are available on the ThingMagic website rfid.
Hardware Abstraction Hardware Abstraction The MercuryAPI is intended to allow cross-product development. The same application can be used to connect, configure and control any ThingMagic product. However, due to differences in product features and functionality, 100% compatibility would not be possible without limiting the capabilities of the API.
ThingMagic Mercury API Software License ThingMagic Mercury API Software License Copyright (c) 2009 - 2014 Trimble Navigation Limited Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is fu
Level 1 API The objects and methods described in this section provide basic reader operations and are hardware and implementation independent.
Connecting to Readers Connecting to Readers Reader Object Create The operations of the MercuryAPI are centered around a single object that represents the state of the reader. This object is called “Reader”. Except when otherwise specified, all functions described in this document are of the Reader class.
Connecting to Readers – Astra-EX Connect The communication channel is not established until the connect() method is called. Calling: void connect() will establish a connection and initialize the device with any pre-configured settings. Calling connect() on an already connected device has no effect. Note SerialReaders require the Region of Operation, /reader/region/id, to be set using Level 2 paramSet(), after the connect(), in order for any RF operations to succeed.
Connecting to Readers Destroy When the user is done with the Reader, Reader.destroy() should be called to release resources that the API has acquired, particularly the serial device or network connection: void destroy() In languages that support finalization, this routine should be called automatically; however, since languages that support finalization do not generally guarantee when or whether they will be invoked, explicitly calling the destroy() method to guarantee release is highly recommended.
Connecting to Readers URI Examples Please note the specific format of the URI path will depend on the OS and drivers being used. The following are some common examples but it is not an exhaustive list. tmr:///com2 - typical format to connect to a serial based module on Windows COM2. tmr:///dev/cu.usbserial - common format for the USB interface on MacOSX. tmr:///dev/ACM0 or tmr:///dev/USB0 - common format for Linux depending on the USB driver being used. tmr://192.168.1.
Connecting to Readers Reader.Region.NA (North America/FCC) Reader.Region.EU3 (European Union/ETSI Revised EN 302 208) Reader.Region.KR2 (Korea KCC) Reader.Region.PRC (China) Reader.Region.IN (India) Reader.Region.JP (Japan) Reader.Region.AU (Australia/AIDA LIPD Variation 2011) Reader.Region.NZ (New Zealand) Reader.Region.OPEN (No region restrictions enforced) Reader.Region.NONE (No region Specified) Note The available, supported regions are specific to each hardware platform.
Reading Tags - The Basics Reading Tags - The Basics Read Methods Reader Object provides multiple ways of reading/inventorying tags. The tag reading methods: Reader.read() Reader.startReading() issue one or more search commands to the device to satisfy the user’s request for searches of a particular duration, duty cycle, antennas, and protocols.
Reading Tags - The Basics duration - The number of milliseconds to read for. In general, especially with readers of type SerialReader, the duration should be kept short (a few seconds) to avoid filling up the tag buffer. Maximum value is 65535 (65 seconds). It performs the operation synchronously, and then returns an array of TagReadData objects resulting from the search. If no tags were found then the array will be empty; this is not an error condition.
Reading Tags - The Basics Note The C# version of this API uses the native delegate/event mechanism with delegates called TagReadHandler and ReadExceptionHandler and events named TagRead and ReadException, rather than the Java-style listener mechanism. Pseudo-Asynchronous Reading In pseudo-asynchronous reading a synchronous search is looped over and over again running indefinitely in a separate thread. Tags are off-loaded once every synchronous search is completed. i.e.
Reading Tags - The Basics N <= 2Q For example, if return on N tags is 3, then optimal Q is 2, but there is a chance that module may find and report 4 tags. See sample codelets in the SDK. Note Not currently supported with Continuous Reading. Reading Tag Memory Additional methods for reading individual tags are available in the Level 2 API. ReadListener Classes that implement the ReadListener interface may be used as listeners (callbacks) for background reads.
Reading Tags - The Basics void tagReadException(Reader r, ReaderException re) This method is called for any Exceptions that occurs during a background tag read after Reader.startReading() has been invoked. See the example applications for typical implementations.
Tags Tags TagReadData An object of the TagReadData class contains the metadata (see the Hardware Specific Guides for details on available tag read metadata for each product) about the tag read as well as the TagData object representing the particular tag. TagReadData (or arrays of) objects are the primary results of Read Methods, one for each tag found. The actual EPC ID for a Tag can be found by calling the getTag() method which returns a TagData object.
Writing To Tags Writing To Tags Write operations should be performed using the functionality described in the Advanced Tag Operations section. Specifically, for writing to Gen2 tags, the Gen2.WriteTag, for writing the EPC ID of tags, and Gen2.WriteData, for writing to specific locations in individual memory banks, should be used.
Status Reporting Status Reporting Status information about the reader and the environment the reader is operating in is available both while the reader is idle and during active background reading. Note Status reporting is currently only available for SerialReader type readers which support Continuous Reading, only the M6e at this time. StatusListener During Continuous Reading operations it is possible to get status reports at every frequency hop by the reader.
Exceptions Exceptions In the event of an error, methods of this interface may throw a ReaderException, which will contain a string describing the error. Several subtypes exist: ReaderCommException This exception is used in the event of a detected failure of the underlying communication mechanism (timeout, network fault, CRC error, etc). This class includes a method: byte[] getReaderMessage() that returns the message where the failure was detected.
Exceptions form and should be provided immediately to ThingMagic Support along with the code which caused the ReaderFatalException. FeatureNotSupportedException The method being invoked or parameter being passed is not supported by the connected reader. Please see the reader specific Hardware Guide and Reader Configuration Parameters for more details on reader supported features.
Level 2 API The objects and methods described in this section provide a more complete set of reader operations, including more complex variations of items in Level 1. The Level 2 API is intended to be hardware and implementation independent.
Advanced Reading Advanced Reading ReadPlan An object of class ReadPlan specifies the antennas, protocol and filters to use for a search (Read Methods). The ReadPlan used by a search is specified by setting /reader/ read/plan in Reader Configuration Parameters. The three current subclasses are: SimpleReadPlan StopTriggerReadPlan MultiReadPlan Each ReadPlan object contains a numeric weight parameter that controls the fraction of the search used by that plan when combined in a MultiReadPlan.
Advanced Reading data read will be stored in the resulting TagReadData Data field. int weight - default value is 1000. See MultiReadPlan for how weights are used. boolean useFastSearch - optimizes performance for small tag populations moving through the RF field at high speeds. Constructors exist to create SimpleReadPlan objects with various combinations of antennas, TagFilter Interface and weights. See the language specific reference guide for the list of all constructors.
Advanced Reading In-Module Multi-Protocol Read M6e Only The M6e supports reader-scheduled, multi-protocol reads This allows you to specify a set of protocols and the M6e schedules on its own, reading on all protocols and return the results without repeated communications with the client application to switch protcols. To allow M6e to use multi-protocol search, create a MultiReadPlan where all child ReadPlans have weight=0. This signals the API to defer to the module for read plan scheduling.
Selecting Specific Tags Selecting Specific Tags TagFilter Interface TagFilter is an interface type that represents tag read filtering operation. Currently classes which implement the TagFilter Interface provide two ways to filter tags: 1. Air Protocol Filtering - When specifying a TagFilter as parameter for Advanced Reading or Advanced Tag Operations [Deprecated], the filter will be applied at the air protocol level, i.e. to tags “in the field”.
Selecting Specific Tags Note Currently, the sequence in which the TagFilters are applied is not guaranteed. Gen2.Select The Gen2.Select class represents selection operations specific to the Gen2 protocol. This class provides the capability to select Gen2 tags based on the value in any Gen2 tag memory bank, except RESERVED. The tag selection criteria can be specified using the Gen2.Select constructor: Gen2.Select(boolean invert, Gen2.
Selecting Specific Tags Tag Protocol The TagProtocol enumeration represents RFID protocols. It is used in many places where a protocol is selected or reported. Some possible values are: TagProtocol.GEN2 TagProtocol.ISO180006B TagProtocol.IPX64 (64kbps link rate) TagProtocol.IPX256 (256kbps link rate) Each protocol may have several configuration parameters associated with it. These parameters can be found in the Reader Configuration Parameters section under /reader/ [protocol name].
Advanced Tag Operations Advanced Tag Operations Note These new TagOp data structures replace the older individual Advanced Tag Operations [Deprecated] and Level 3 API. TagOp Invocation A TagOp is a data structure which encapsulates all the arguments of a particular, protocol-specific command.
Advanced Tag Operations The /reader/tagop/protocol parameter selects the RFID Tag Protocol to use and can affect the semantics of the command, as some commands are not supported by some protocols. Embedded TagOp Invocation TagOps may also be executed as a side effect of an Advanced Reading operation.
Advanced Tag Operations Reader.read() -Counters resets to 0 at beginning of call and accumulates values until call completes. Reader.startReading() -Counters reset to 0 when Reader.StartReading is called and accumulate values until StartReading() is called again. Counter values can be retrieved while the read is still active. Reader.StopReading has no effect on counters. Gen2 Standard TagOps The following tag operations are supported by ALL Gen2 tags and all Reader Types. Gen2.
Advanced Tag Operations Gen2.WriteData Writes the specified data to the tag memory location specified by the Memory Bank and location parameters. Note Currently limited to writing 123 words of data per WriteData invocation. By default this method will perform a word by word write but it can be made to attempt a Gen2.BlockWrite by setting /reader/gen2/writeMode = Gen2.WriteMode.BLOCK_ONLY or BLOCK_FALLBACK. Gen2.Lock Sends a command to a tag to lock and/or unlock segments of tag memory.
Advanced Tag Operations Gen2.LockAction.KILL_PERMALOCK Gen2.LockAction.KILL_PERMAUNLOCK Gen2.LockAction.ACCESS_LOCK Gen2.LockAction.ACCESS_UNLOCK Gen2.LockAction.ACCESS_PERMALOCK Gen2.LockAction.ACCESS_PERMAUNLOCK Gen2.LockAction.EPC_LOCK Gen2.LockAction.EPC_UNLOCK Gen2.LockAction.EPC_PERMALOCK Gen2.LockAction.EPC_PERMAUNLOCK Gen2.LockAction.TID_LOCK Gen2.LockAction.TID_UNLOCK Gen2.LockAction.TID_PERMALOCK Gen2.LockAction.TID_PERMAUNLOCK Gen2.LockAction.USER_LOCK Gen2.
Advanced Tag Operations Gen2.LockAction(int mask, int action) to create a Gen2.LockAction object with the specified mask and action. The following symbolic constants are provided for convenience in handling Gen2 lock mask and action bitmasks. Perform a binary OR on these to pass multiple lock/unlock settings. Gen2.LockBits.ACCESS Gen2.LockBits.ACCESS_PERM Gen2.LockBits.KILL Gen2.LockBits.KILL_PERM Gen2.LockBits.EPC Gen2.LockBits.EPC_PERM Gen2.LockBits.TID Gen2.LockBits.TID_PERM Gen2.
Advanced Tag Operations BlockWrites. This means that in order to write more than 2 words multiple calls must be made. Gen2.BlockWrite can also be made the default behavior of Gen2.WriteData by setting / reader/gen2/writeMode = Gen2.WriteMode.BLOCK_ONLY or BLOCK_FALLBACK Gen2.BlockPermaLock On tags which support this command, it allows User Memory to be selectively, permanently write-locked in individual sub-portions. Compare BlockPermaLock with standard Gen2.
Advanced Tag Operations Gen2.Alien.Higgs3.LoadImage This command writes Reserved, EPC and User Memory to the Higgs3 tags in a single command, thereby reducing the tag programming time compared to the use of multiple Gen2.WriteData commands. Gen2.Alien.Higgs3.BlockReadLock This command allows four-word blocks of User Memory to be read locked. Once read locked the correct Access Password will be required to read the contents of the locked blocks with Gen2.ReadData.
Advanced Tag Operations Gen2.NXP.G2I.EasAlarm and Gen2.NXP.G2X.EasAlarm sets or resets the EAS system bit. When set, the tag will return an alarm code if an “EAS Alarm” command is received. The response to the EAS Alarm command contains 8 bytes of EAS Alarm Data Note Cannot be used through Embedded TagOp Invocation, only via Direct Invocation and it does not support TagFilter Interface usage. Gen2.NXP.G2I.Calibrate and Gen2.NXP.G2X.
Advanced Tag Operations Gen2.Impinj.Monza4.QTReadWrite Controls the switching of Monza 4QT between the Private and Public profiles. The tag MUST be in the Secured state, i.e. non-zero Access Password, to succeed. The specific settings provide protection of data through public and private data profiles and the use of short range reading options. See the Impinj Monza 4 datasheet (IPJ_Monza4Datasheet_20101101.pdf), availalbe from Impinj, for more details.
Advanced Tag Operations Gen2.IDS.SL900A.GetMeasurementSetup The GET MEASUREMENT SETUP command will read the current system setup of the chip.. Gen2.IDS.SL900A.GetSensorValue The GET SENSOR VALUE command starts the AD conversion on the specified sensor and returns the value. Gen2.IDS.SL900A.EndLog The END LOG command stops the logging procedure and turns off the real time clock. It also clears the Active flag that is store in the “System status” field in the EEPROM. Gen2.IDS.SL900A.
Advanced Tag Operations Gen2.IDS.SL900A.SetPassword The SET PASSWORD command writes a 32-bit password to the EEPROM. The password protection for the specified area is automatically enabled if the password is any other value except 0. Gen2.IDS.SL900A.SetShelfLife The SET SHELF LIFE command programs parameters for the dynamic shelf life algorithm. Gen2.IDS.SL900A.SetSFEParameters The SET SFE PARAMETERS command writes the Sensor Front End parameters to the memory.
Advanced Tag Operations Iso180006b.Lock Sends a command to a tag to lock segments of tag memory. The lock operation to perform is represented as an instance of the ISO180006B.LockAction class. ISO180006B.LockAction class Instances of this class represent the single lock action of locking a particular byte of tag memory on ISO18000-6b tags. Use the constructor. ISO180006B.LockAction(int address) to construct a ISO180006B.LockAction object for the specified address.
Advanced Tag Operations [Deprecated] Advanced Tag Operations [Deprecated] ! C A U T I O N ! ! The following individual tag operation methods are being deprecated in favor of the new TagOp Invocation class and its subclasses. All new development should use these data structures instead of the older individual tag operations. The Level 2 API methods that operate on individual tags use the reader-level /reader/ tagop/antenna parameter to select the antenna on which the command is issued.
Advanced Tag Operations [Deprecated] readTagMemWords() short[] readTagMemWords(TagFilter filter, int bank, int address, int length) writeTagMemBytes() void writeTagMemBytes(TagFilter filter, int bank, int address, byte[] data) writeTagMemWord() void writeTagMemWord(TagFilter filter, int bank, int address, short[] data) 56 Level 2 API
Antenna Usage Antenna Usage Automatic Antenna Switching Only one antenna can be active at a time, when multiple antennas are specified they are switched on, one at a time, in the order specified. It stops when the search timeout expires or stopReading() is issued, as appropriate. The exact method of switching depends on your code. There are two main methods you can use for switching antennas: 1. Setup the list of antennas in a single ReadPlan and let the reader handle the switching.
Antenna Usage example, if the reader is identified as a Vega, the settings define in Vega Reader Example which previously had to be manually configured will be automatically set. Manual Configuration The portSwitchGpos parameter defines which GPOutput lines will be used for antenna switching and, consequently how many ports are supported. The txRxMap parameter defines the mapping of virtual port numbers to physical TX and RX ports.
GPIO Support GPIO Support Get/Set Value Reader.GpioPin[] gpiGet() void gpoSet(Reader.GpioPin[] state) If the reader device supports GPIO pins, the gpiGet() and gpoSet() methods can be used to manipulate them. The pin numbers supported as inputs by the reader are provided in the /reader/gpio/inputList parameter. The pin numbers supported as outputs by the reader are provided in the /reader/gpio/outputList parameter. The gpiGet() and gpoSet() methods use an array Reader.
Firmware Updates Firmware Updates void firmwareLoad(java.io.InputStream firmware) The firmwareLoad() method attempts to install firmware on the reader. The argument is a language specific data structure or pointer (see Language Specific Reference Guides for details) connected to a firmware image. It is the user’s responsibility to have an appropriate firmware file. No password is required.
Rebooting Readers Rebooting Readers void reboot() The reboot() method reboots the reader or module. Note The Reboot method is not supported over the RQLReader interface and cannot be used to reboot Mercury4/5 and Astra readers.
Protocol License Keys Protocol License Keys M6e Only The M6e has the ability to support multiple protocols. The basic M6e supports Gen2 (ISO18000-6C) only. To enable additional protocols a license key must be purchased (contact sales@thingmagic.com for details). Once a license key is obtained it is installed by setting the Reader Configuration Parameters /reader/licenseKey to the provided license key. Once set the key is stored persistently in flash and does not need to be repeatedly set.
Debug Logging Debug Logging TransportListener Interface The TransportListener interface provides a method of snooping on raw, transport-layer packets sent to and received from any device. The class that is interested in observing raw message packets implements this interface, and the object created with that class is registered with: void addTransportListener(TransportListener listener) Once registered data transmitted or receive will cause the message() method to be invoked.
Configuring Readers Configuring Readers Reader Configuration Methods Each Reader Object has a set of named parameters which provide device metadata and/ or provide configuration settings. The names of parameters are strings; case insensitive. Related parameters are grouped together in a filesystem-style layout, for example, the parameters under /reader/antenna provide information about and allow configuration of the devices antennas.
Configuring Readers /reader/baudRate Future firmware upgrades will support saving other configuration values. To Save a configuration, simple set the parameters as desired then set the /reader/ userConfig parameter to a SerialReader.UserConfigOp with the appropriate parameter. See the Example Code Codelets\SavedConfig for an example of saving and restoring configurations on the M6e.
Configuring Readers M5e Notes - The module always boots into 9600 baud resulting in a connection delay due to the first attempt of connecting at the default /reader/baudRate of 115200. This delay can be avoided by setting /reader/baudRate to 9600 before calling Reader.Connect() then setting it again to the desired faster rate after the connect. M6e Notes- The M6e boot baud rate can be modified.
Configuring Readers /reader/powerMode Type: SerialReader.PowerMode Default value: From reader Writable: yes Products: M5e (and derived products), M6e Controls the power-consumption mode of the reader as a whole. M6e Notes- Certain power modes require special command protocols in order to “wake up” the module before the beginning of the first command. Setting the powerMode prior to calling reader.Connect() allows the connect sequence to issue the appropriate signals, speeding up the connect.
Configuring Readers /reader/uri Type: String Default value: From reader Writable: no Products: all Gets the URI string used to connect to the reader from the Reader Object. /reader/userConfig Type: SerialReader.UserConfigOp Default value: null Writable: yes Products: M6e Enables M6e configuration Saving and Restoring. See Save and Restore Configuration.
Configuring Readers /reader/antenna/connectedPortList Type: Array of integers Writable: no Products: M5e, M6e, M6 Contains the numbers of the antenna ports where the reader has detected antennas. Changing the /reader/antenna/portSwitchGpos parameter may change the value this parameter. /reader/antenna/portList Type: Array of integers Writable: no Products: all Contains the number of the antenna ports supported by the device. These numbers may not be consecutive or ordered.
Configuring Readers (NOTE: the settlingTime is associated with the TX port, the paired RX port is not relevant), and the second element is the settling time in microseconds. Ports not listed are assigned a settling time of zero. /reader/antenna/txRxMap Type: array of array of 3 integers Default value: all the antennas in /reader/antenna/portList in monostatic mode. i.e.
Configuring Readers /reader/gen2/accessPassword Type: Gen2.Password Default value: 0 Writable: yes Products: all The Gen2 access password that is used for all tag operations. If set to a non-zero value it must match the value stored in the tag’s Reserved Memory | Access Password or tag operations on that tag will fail, even if the memory operated on is not locked. /reader/gen2/writeMode Type: Enum Default value: Gen2.WriteMode.
Configuring Readers /reader/gen2/BLF Type: Integer Default value: 250 Writable: yes Products: M6e, M6 Sets the Gen2 backscatter link frequency, in KHz. See the M6e Hardware Guide for full configuration options and supported BLF values. See Tag-to-Reader Settings for details. Note It is important that the /reader/baudRate is greater than /reader/gen2/BLF, in equivalent frequency units.
Configuring Readers /reader/gen2/millerm [Deprecated] Type:Gen2.MillerM Default value: Gen2.MillerM.M4 Writable: yes Products: M5e (and derived products) Controls the Gen2 Miller M value used for communications with the tag. /reader/gen2/tagEncoding Type:Gen2.TagEncoding Default value: Gen2.TagEncoding.M4 Writable: yes Products: M5e (and derived products), M6e, M6 Controls the tag encoding method (Miller options or FM0) used for communications with Gen2 tags.
Configuring Readers /reader/gen2/target Type: Gen2.Target Default value: Gen2.Target.A Writable: yes Products: all Controls the target algorithm used for read operations. See Tag Contention Settings for details. /reader/gen2/Tari Type:Gen2.Tari Default value: From reader Writable: yes Products: M6e, M6 Controls the Tari value used for communications with Gen2 tags. See the M6e Hardware Guide for full configuration options. See Reader-to-Tag Settings for details.
Configuring Readers – Min. timeout = 1000us. /reader/gen2/writeEarlyExit Type: Boolean Default value: True Writable: yes Products: M5e, M6e True = Early Exit - If the tag’s response to a word write is detected it moves onto the next word write, otherwise waits for timeout value: /reader/gen2/writeReplyTimeout. False = Fixed Wait Time - Always waits the specified /reader/gen2/writeReplyTimeout per word write. Using Fixed Wait Time results in a consistent time for each write operation.
Configuring Readers M6e - Set to an array of ints (1 through 4) to configure GPIO lines as outputs. /reader/iso18000-6b /reader/iso18000-6b/BLF Type: Iso18000-6b.LinkFrequency Default value: M4/5 = From reader; M6e = ISO18000-6b.LinkFrequency.LINK160KHZ Writable: yes Products: M4, M5, M6e, M6 This sets the backscatter (return) link frequency used by the ISO18000-6b protocol. See the M6e Hardware Guide and M4/5 MercuryOS Advanced User Guide for full configuration options.
Configuring Readers /reader/iso18000-6b/delimiter Type: Iso18000-6b.Delimiter Default value: DELIMITER4 Writable: yes Products: M6e ISO18000-6B tags support two delimiter settings on the transmitter. Not all tags support both delimiters and some tags require the delimiter be set to DELIMITER1. Ceratin tags, in addition to setting the delimiter to 1, also require a TagFilter be specified of the class ISO180006B.
Configuring Readers /reader/radio/powerMax Type: integer Writable: no Products: all Maximum value that the reader accepts for transmit power. /reader/radio/powerMin Type: integer Writable: no Products: all Minimum value that the reader accepts for transmit power. /reader/radio/portReadPowerList Type: array of array of integers Default value: From reader Writable: yes Products: M5e (and derived products), M6e, M6 List of per-port transmit power values for read operations.
Configuring Readers will use the global write power level: /reader/radio/writePower) /reader/radio/readPower Type: integer Default value: From reader Writable: yes Products: all The global transmit power setting, in centidBm, for read operations (except where overridden by /reader/radio/portReadPowerList).
Configuring Readers /reader/read /reader/read/asyncOffTime Type: integer Default value: 0 Writable: yes Products: all The duration, in milliseconds, for the reader to be quiet while querying, RF Off time, on the reader during background, asynchronous read operations invoked via Reader.startReading(). This parameter and /reader/read/asyncOnTime together set the frequency and duty cycle of the background operation.
Configuring Readers /reader/region /reader/region/id Type: Reader.Region Default value: Specified in Reader Object create() method. Writable: yes Products: all Controls the Region of Operation for the device. It may not be settable on all device types. /reader/region/supportedRegions Type: Reader.Region[] Writable: no Products: all List of supported regions for the connected device.
Configuring Readers /reader/region/hopTime Type: integer Default value: From reader Writable: yes Products: M5e (and derived products), M6e Controls the frequency hop time, in milliseconds, used by the reader. /reader/region/lbt/enable Type: boolean Writable: yes Default value: based on the Region chosen Products: M5e (and derived products) Enables/disables LBT in the region specified. Note: Not all regions support LBT.
Configuring Readers /reader/status/frequencyEnable Type: boolean Writable: yes Default value: false Products: M6e Enables/disables the frequency field in StatusListener reports. /reader/status/temperatureEnable Type: boolean Writable: yes Default value: false Products: M6e Enables/disables the temperature field in StatusListener reports.
Configuring Readers /reader/tagReadData/reportRssiInDbm Type: boolean Default value: From reader Writable: yes Products: all This is the setting that controls the units for the RSSI metadata. /reader/tagReadData/uniqueByAntenna Type: boolean Default value: From reader Writable: yes Products: M5e (and derived products), M6e, M6 Controls whether reads on different antennas are reported separately.
Configuring Readers /reader/tagReadData/tagopFailures Type: integer Default value: none Writable: no Products: M5e (and derived products), M6e, M6 Number of Embedded TagOp Invocation operations which failed. /reader/tagop /reader/tagop/antenna Type: integer Default: First element of /reader/antenna/connectedPortList Writable: yes Products: all Specifies the antenna used for tag operations other than reads (reads use /reader/read/ plan).
Configuring Readers /reader/version /reader/version/hardware Type: String Writable: no Products: all Contains a version identifier for the reader hardware. /reader/version/model Type: String Writable: no Products: all Contains a model identifier for the reader hardware. /reader/version/productGroup Type: String Writable: no Products: all Contains the Product group type (“Module”, “Ruggedized Reader”, “USB Reader”) that helps define the physical port settings, allowing Auto Configuration.
Configuring Readers /reader/version/software Type: String Writable: no Products: all Contains a version identifier for the reader’s software. /reader/version/supportedProtocols Type: array of TagProtocol Writable: no Products: all Contains the protocols that the connected device supports.
Configuring Readers 88 Level 2 API
Level 3 API The Level 3 API provides per-command access to the individual elements of the underlying device control protocol. Level 3 is not portable across hardware types. Level 3 commands are not dependant on the state of the device or of the reader configuration; the same command with the same parameters will always send the same message to the reader.
Level 3 API
.NET Language Interface The .NET interface provides an API supporting the primary Windows development platform. Depending on the specific version of Windows being developed for there are limitations on the development tools that can be used. Whenever possible the MercuryAPI SDK libraries and applications make use of free, standard Visual Studio and .NET Frameworks.
Windows Mobile 6 Professional SDK Universal Reader Assistant 1.0 Visual Studio 2008 Express or better .NET 2.0 or newer Universal Reader Assistant 2.0 Visual Studio 2010 Express or better Optional - install free WiX add on to build installer - http://wix.codeplex.com/ .NET 4.0 or newer USB Drivers Starting with release 1.23.0 of the MercuryAPI SDK, there is support for the USB CDC/ ACM drivers for WinCE 5.0, 6.0, and 7.0.
2. Locate the WinceReadApp.CAB file . 3. Copy this CAB file into your WinCE device. By double clicking it, you will install the winceReadApp application in the WInCE device and it will create a shortcut in the windows “Start/Programs” folder. Note This application is intended for demonstration purposes only and has not been fully tested by ThingMagic nor qualified on a wide variety of platforms .
.NET Language Interface
C Language Interface The C language interface is designed primarily to provide support for embedded systems. The structure of the interface is designed to provide a pseudo object-oriented programming model that mimics the Java and .NET interfaces as much as possible. The C API will work similarly as the other languages, as described in the previous sections of the Guide, with mostly language syntax and semantics differences. It uses similarly named API calls (e.g. substitute TMR_* for Reader.
C Language Features C Language Features For clarity of definition, C99 datatypes (bool, uintN_t) are used. If these types are not defined on the target platform, a substitute typedef for bool can be define, but a custom stdint.h must be created to define specific integer sizes in terms of the target environment.
Build Considerations Build Considerations The full source code of the C API is provided. The API source code includes sample build processes for desktop and embedded environments (Makefile and Visual Studio project). It is recommend these be used as starting points for building custom applications. Client code only needs to include a single header file, tm_reader.h to use the API. API Changes Required for Different Hardware Platforms The API has a couple layers of encapsulation.
Build Considerations #define TMR_ENABLE_SERIAL_TRANSPORT_LLRP //not currently supported #define TMR_ENABLE_ISO180006B #define TMR_ENABLE_BACKGROUND_READS //not supported on Windows #define TMR_ENABLE_ERROR_STRINGS #define TMR_ENABLE_PARAM_STRINGS #define TMR_SR_MAX_ANTENNA_PORTS The minimum #defines that must currently be specified are: TMR_ENABLE_SERIAL_READER - enables support for the ThingMagic serial command protocol, but does not specify how that reader is connected.
IOS Support IOS Support The MercuryAPI C API includes a sample IOS application that can connect to serial readers through a serial cable such as the Redpark C2-DB9V. The full source and project files are in SDKROOT\c\ios. The tools used for this sample are as follows: Development Environment Xcode IDE Supported IOS Versions Version 6 and above Testing Environment iPad, IOS version 7.1.4 iPad Mini, IOS version 7.
IOS Support Creating an APP ID 100 C Language Interface
Java Language Interface JNI Library The java interface, when connecting to readers of type SerialReader, requires the use of a JNI Serial Driver library to handle the low level serial port communications. The mercuryapi.jar includes libraries supporting the following environments: Linux on x86 Linux on AMD64 Windows on x86 (see Required Windows Runtime Libraries) MacOSX For other platforms the library will have to be custom built.
LLRP ToolKit (LTK) Support LLRP ToolKit (LTK) Support The MercuryAPI SDK provides a full LTKJava distribution which includes ThingMagic custom extensions: tkjava-1.0.0.6.jar. If the user prefers to use another source of LTKjava code, such as the open source version from Sourceforge, the ThingMagic custom extensions are available in a separate jar file: ltkthingmagic.jar. Usage In classpath, custom jar(tkthingmagic.jar) should be defined before standard ltkjava jar.
Required Windows Runtime Libraries Required Windows Runtime Libraries In order to run the Java APIs, more specifically the JNI Serial Driver, on Windows the latest C runtime libraries must be installed. These can be downloaded and installed from Microsofts website here: http://www.microsoft.com/downloads/details.aspx?familyid=766A6AF7-EC73-40FFB072-9112BAB119C2&displaylang=en Select the correct architecture (IA64,x64 or x86), download and install.
Android Support Android Support The MercuryAPI SDK includes a sample Android application that can connect to serial readers over bluetooth, USB, and networked readers. The full source and project files are in SDKROOT\java\samples\android.
Advanced Customization Custom Serial Transport Naming Starting with version 1.23.0 of the MercuryAPI SDK, users can write their own custom serial transport layer to handle different types of serial connections, and create a unique URI name for it. The SDK provides an example of this for serial connections over TCP networks, for each of the supported OS’s. Two devices have been tested with this implementation.
Custom Serial Transport Naming Call the factory function with the already-parsed URI (e.g., Reader rdr = CreateSerialReader(uri)) For new functions, the user needs to modify the code in two places: Create one new file to implement the serial transport. (We already have files encapsulating the implementations of SerialReader and LlrpReader.) Initialize the dispatch table in your application code before calling Reader.Create().
Custom Serial Transport Naming Changes Required for C#/.NET Starting with version 1.23.0 of the MercuryAPI SDK, we have added a serial transport dispatch table to store the transport scheme name and factory init functions. We have also modified the Create() method to use the dispatch table for serial readers. In order to use a new transport layer, the user needs to create their own serial transport layer which inerits from SerialTransport.cs.
Custom Serial Transport Naming Example In MercuryAPI, we have added support for a TCP serial bridge. The TCP serial bridge allows the user to connect to a serial reader using TCP/IP and a port number. We have added the custom transport file for TCP serial bridge. The following code example shows how to implement it in C#. class Program { static void Main(string[] args) { …… Reader.SetSerialTransport("tcp",SerialTransportTCP.CreateSerialReader ); // Add the custom transport scheme before calling Create().
Custom Serial Transport Naming Changes Required for C Starting with version 1.23.0 of the MercuryAPI SDK, we have added a serial transport dispatch table to store the transport scheme name and factory init functions. We have also modified the TMR_create() to use the dispatch table for serial readers. So in order to use a new transport layer, the user needs to touch the Mercury C API in one place only: In TMR_Serial_transport.h, you will need to add the prototype of the factory init function.
Custom Serial Transport Naming Example: In MercuryAPI we have added support for a TCP serial bridge. The TCP serial bridge allows the user to connect to a serial reader using TCP/IP and a port number. We have added the custom transport file for TCP serial bridge. The following code example shows how to implement it in C. main () { ……..
Custom Serial Transport Naming Changes Required for Java Starting with version 1.23.0 of the MercuryAPI SDK, we have added a serial transport dispatch table (“Hashmap”) to store the transport scheme name and serial transport object. We have also modified the create() method to use the dispatch table for serial readers. In order to use a new transport layer, the user needs to create their own serial transport layer which implements SerialTransport.java .
Custom Serial Transport Naming Example In MercuryAPI we have added support for a TCP serial bridge. The TCP serial bridge allows the user to connect to a serial reader using TCP/IP and a port number. We have added the custom transport file for TCP serial bridge. The following code example shows how to implement it in Java. class CustomTransport { public static void Main(string[] args) { …… Reader.setSerialTransport("tcp",new SerialTransportTCP.
On Reader Applications The M6 Reader, starting with firmware v4.9.2 and MercuryAPI v1.11.1, supports running custom applications on the reader, built using the MercuryAPI C Language interface. Most programs written using the C API can be compiled to run as a client application or run on the reader.
Building On-Reader Applications Building On-Reader Applications Requirements The following items are needed to run APIs on the reader. The MercuryAPI SDK v1.11 or later. (available on rfid.thingmagic.com/devkit) The M6 On-Reader cross-compiler environment (available on rfid.thingmagic.com/devkit) A host PC running a modern Linux distribution. – Tested with Ubuntu 12.04 LTS An M6 or Astra-EX Reader. GCC version 4.4.3 or 4.5.2. GCC v4.6 fails to build LTK library.
Building On-Reader Applications Installing the Cross Compiler Environment Precompiled Linux binaries for the cross compiler are available on the ThingMagic website. The easiest way to setup the environment and build applications is to download the cross-compiler environment (available on rfid.thingmagic.com/devkit) and extract it into the root directory (/). This installs the necessary files and libraries into /usr/local.
Building On-Reader Applications Troubleshooting The build process for on-reader applications requires some Linux utilities that aren’t installed as part of many default Linux distributions. If errors reporting missing executables occur during the build you can use the Linux apt-get install utility to install the necessary binaries. For example, the error: SDKROOT/c/src/api/lib/install_LTKC.sh: 37: patch: not found indicates the patch binaries are missing.
Building On-Reader Applications Running an On-Reader Application Once the binary is installed on the Reader it can be executed as you would from a Linux host or the binary or a shell script invoking the binary can be configured to run at boot time. To start the application at boot you can place it in the reader’s /tm/etc/inittab file. If you do this, the operating system starts that program when the system boots and restarts it in the event of a crash.
Building On-Reader Applications getty:unknown:/sbin/getty 115200 /dev/ttyS1 snmpd:unknown:/bin/run_snmp.sh update_passwd:unknown:/usr/sbin/update_passwd.sh userprogram:unknown:/tm/bin/userprogram ! C A U T I O N ! ! Do not delete any lines from this file. The reader may not work properly if all the programs do not start.
Building On-Reader Applications Saving the Program to the JFFS2 File System The root MercuryOS filesystem runs out of a ramdisk that is loaded from the flash memory device on boot. This filesystem is read/write while the reader is running, however any changes made to the filesystem are gone when you reboot the reader. The JFFS2 filesystem mounted at /tm is different. Any files you place in the /tm directory or any of its subdirectories are saved to flash and restored when the system is restarted.
Building On-Reader Applications 120 On Reader Applications
Performance Tuning The following sections describe how to enhance or tailor the reader’s settings to fit your unique RFID environment.
How UHF RFID Works (Gen2) How UHF RFID Works (Gen2) At its most basic level, the reader powers up the tag at the same time it is communicating with it. A good analogy for this kind of system would be if two people are trying to send messages from one mountaintop to another at night, where one has only a flashlight (representing the reader) and the other has a mirror (representing the tag).
How UHF RFID Works (Gen2) Transmit Power /reader/radio/readPower /reader/radio/writePower Although not directly related to Gen2 settings, the role of transmit power is so central to successful RFID applications, a few words must be said about it. In order to have successful communications between a reader and a tag, the tag must be able to be powered-up by the reader’s signal. No communication at all occurs if the tag remains dormant and does not respond to the reader.
How UHF RFID Works (Gen2) channels, but in the EU region where there are only 4 channels, this could become an issue. In this case, you would want to try increasing the Tari to decrease the link rate and see if the performance of the first reader improves. Tag-to-Reader Settings /reader/gen2/BLF /reader/gen2/tagEncoding The tag uses a slightly different signaling method to communicate back to the reader than the reader uses to communicate with the tag.
How UHF RFID Works (Gen2) /reader/gen2/target The remaining Gen2 settings control how soon, and how often, a tag responds to a reader. If all tags in the field responded immediately to the reader, their responses would collide and the reader would rarely be able to decode responses from any tags. To avoid this, the Gen2 protocol provides a variable number of time slots in which tags can respond.
How UHF RFID Works (Gen2) Session “0”: Prepare to respond again as soon as RF power drops Session “1”: Prepare to respond again between 0.5 and 5 seconds after first response Session “2” or “3”: Do not respond again for at least 2 seconds Selection of the session setting is nearly always based on the expected number of tags in the field. You usually want all tags in the field to have had a chance to respond once before the first tags start responding again.
Optimizing Gen2 settings Optimizing Gen2 settings If the previous information on Gen2 settings is new to you, the task of optimizing all these settings together will likely appear daunting to you at this point. Fortunately, we have created a step-by-step procedure for achieving the desired results. 1. Set the reader up to achieve the maximum read distance possible (Tari=6.
Optimizing Gen2 settings 128 Performance Tuning
