ThingMagic Mercury API User Manual

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.1 and later)
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. Any reproduction of technical data or portions thereof marked with this legend must also reproduce the markings. Any person, other than the U.S. Government, who has been provided access to such data must promptly notify Trimble.
ThingMagic, Mercury, Reads Any Tag, and the ThingMagic logo are trademarks or registered trademarks of Trimble.
Other product names mentioned herein may be trademarks or registered trademarks of Trimble or other companies.
©2014 ThingMagic – a division of Trimble Navigation Limited. ThingMagic and The Engine in RFID are registered trademarks of Trimble Navigation Limited. Other marks may be protected by their respective owners. All Rights Reserved.
ThingMagic, A Division of Trimble 4 Cambridge Center, 12th floor Cambridge, MA 02142
10 Revision A June, 2014
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 sec-
tion.
2/2010 02 Rev1 Added protocol configuration additions for M6e.
Added details/clarification to various content based on customer feed­back.
7/2010 02 Rev1 Added M6e Beta content:
• new/updated parameters for M6e
• C language content
• TagOp info
• Java/JNI appendix
12/2010 03 Rev1 Added performance tuning section.
2/2011 03 Rev1 Added M6 info
5/2011 04 RevA Added updates for M6e and M5e new functionality
• Custom tag commands
• Status reporting
11/2011 05 RevA Added M6 LLRP information
• LLRPReader type
• On reader application build process
1/2012 06 RevA Added M6, M6e, M5e Jan2012 firmware enhancement info:
• /reader/gen2/writeReplyTimeout & writeEarlyExit info added
• new ISO6b configuration parameters: delimiter, modulationDepth
• Gen2.IDS.SL900A command info
2/2012 07 RevA fixed ISO6b Delimiter information
3
Date Version Description
8/2012 08 RevA • 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 .NET specific section with project build requirements
• add new IDS CoolLog command support
9/2013 09 RevA • added read duration details
• updated antenna usage info
• Updated exception details
• android support details
6/2014 10 RevA • added info on StopTriggerReadPlan - return on N tags functionality.
• added info on iOS support to C Language chapter
• created Advanced Customization chapter to provide information about creating new transport layers for all 3 API languages, including example of serial-over-tcp tranport layer.
• info on support for standard WinCE USB drivers and example WinCE reader application added to .NET Language chapter
• added information about new independent LLRP jar file containing only ThingMagic custom custom commands for Java Language
• added info on new reboot() method in Level 2 chapter
• Updated Android section in Java Language chapter and mentioned new example reader app.
4

Contents

Introduction to the MercuryAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Language Specific Reference Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Supported Languages and Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Language Specific Build and Runtime Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Hardware Specific Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Hardware Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
ThingMagic Mercury API Software License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Level 1 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Connecting to Readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Reader Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Create 20 Connect 21 Destroy 22 URI Syntax 22 Region of Operation 23
Reading Tags - The Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Read Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Reader.read() 25 Reader.startReading() 26 Return on N Tags Found 27
Reading Tag Memory 28
ReadListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
ReadExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
TagReadData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
TagData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Writing To Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Status Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Mercury Embedded Modules Developer’s Guide 5
StatusListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
ReaderCommException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
ReaderCodeException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
ReaderParseException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
ReaderFatalException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
FeatureNotSupportedException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Level 2 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Advanced Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
ReadPlan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
SimpleReadPlan 36
StopTriggerReadPlan 37
MultiReadPlan 37
In-Module Multi-Protocol Read. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Selecting Specific Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
TagFilter Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
MultiFilter 39
Gen2.Select 40
ISO180006B.Select 40
Tag Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Advanced Tag Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
TagOp Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Direct Invocation 42
Embedded TagOp Invocation 43
Gen2 Standard TagOps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Gen2.WriteTag 44
Gen2.ReadData 44
Gen2.WriteData 45
Gen2.Lock 45
Gen2.Kill 47
Gen2 Optional TagOps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Gen2.BlockWrite 47
Gen2.BlockPermaLock 48
Gen2 Tag Specific TagOps - Alien Higgs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Gen2.Alien.Higgs2.PartialLoadImage 48
Gen2.Alien.Higgs2.FullLoadImage 48
Gen2.Alien.Higgs3.FastLoadImage 48
Gen2.Alien.Higgs3.LoadImage 49
Gen2.Alien.Higgs3.BlockReadLock 49
6 Mercury Embedded Modules Developer’s Guide
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Gen2.Impinj.Monza4.QTReadWrite 51
Gen2 Tag Specific TagOps - IDS SL900A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Gen2.IDS.SL900A.AccessFifo 51
Gen2.IDS.SL900A.GetBatteryLevel 51
Gen2.IDS.SL900A.GetCalibrationData 51
Gen2.IDS.SL900A.GetLogState 51
Gen2.IDS.SL900A.GetMeasurementSetup 52
Gen2.IDS.SL900A.GetSensorValue 52
Gen2.IDS.SL900A.EndLog 52
Gen2.IDS.SL900A.Initialize 52
Gen2.IDS.SL900A.SetCalibrationData 52
Gen2.IDS.SL900A.SetLogLimit 52
Gen2.IDS.SL900A.SetLogMode 52
Gen2.IDS.SL900A.SetPassword 53
Gen2.IDS.SL900A.SetShelfLife 53
Gen2.IDS.SL900A.SetSFEParameters 53
Gen2.IDS.SL900A.StartLog 53
ISO18000-6B TagOps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Iso180006b.ReadData 53
Iso180006b.WriteData 53
Iso180006b.Lock 54
Advanced Tag Operations [Deprecated] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Killing Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
killTag() 55
Locking Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
lockTag() 55
Tag Memory Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
readTagMemBytes() 55
readTagMemWords() 56
writeTagMemBytes() 56
writeTagMemWord() 56
Antenna Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Mercury Embedded Modules Developer’s Guide 7
Automatic Antenna Switching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Virtual Antenna Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
GPIO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Get/Set Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
GPIO Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Firmware Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Rebooting Readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Protocol License Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Deprecated API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Debug Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
TransportListener Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Configuring Readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Reader Configuration Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
paramGet() 64
paramSet() 64
paramList() 64
Save and Restore Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Reader Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
/reader 65
/reader/antenna 68
/reader/gen2 70
/reader/gpio 75
/reader/iso18000-6b 76
/reader/radio 77
/reader/read 80
/reader/region 81
/reader/status 82
/reader/tagReadData 83
/reader/tagop 85
/reader/version 86
Level 3 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
.NET Language Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
.NET Development Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Mercury API Library (desktop): 91
Mercury API CE Library (embedded Compact Framework) 91
RFID Searchlight: 91
Universal Reader Assistant 1.0 92
8 Mercury Embedded Modules Developer’s Guide
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
C Read Iterator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Build Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
API Changes Required for Different Hardware Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
C Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Protocol-Specific C Compilation Options 98
IOS Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Supported IOS Versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Testing Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
README File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Java Language Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
JNI Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
LLRP ToolKit (LTK) Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Usage 102
Required Windows Runtime Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Android Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Testing Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Tested Android Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Advanced Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Custom Serial Transport Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Changes Required for C#/.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Example 108
Changes Required for C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Example: 110
Changes Required for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Example 112
On Reader Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Mercury Embedded Modules Developer’s Guide 9
Building On-Reader Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Installing the Cross Compiler Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Compiling an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Troubleshooting 116
Installing the Application on the M6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Via NFS Mount 116
Via wget 116
Running an On-Reader Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Connecting the M6 to an NFS Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Exporting an NFS Mount Point 118
Mount the NFS Share on the M6 118
Telnet to the Reader. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Saving the Program to the JFFS2 File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
How UHF RFID Works (Gen2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Transmit Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Reader-to-Tag Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Tag-to-Reader Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Tag Contention Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Optimizing Gen2 settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10 Mercury Embedded Modules Developer’s Guide

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.1 and later)
M5e, M5e-C, USB and Vega (firmware v1.7.1 and later)
Micro (firmware v1.3.1 and later)

Language Specific Reference Guides

For language specific command reference see the corresponding language (Java, C#, C) reference Guides included in the API source and libraries package under their respective subdirectories:
Java - [SDK Install Dir]/java/doc/index.html
Introduction to the MercuryAPI 11
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.
12 Introduction to the MercuryAPI

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.
Windows 2000, XP, Vista and Windows 7 applications in the Java Framework
Linux (Intel) and MacOSX applications in the Java Framework
POSIX compliant systems in the C Framework
Windows in the C Framework for SerialReader connections only.
On Reader Applications for LLRPReaders in the C Framework (requires the cross-
compiler toolchain from ThingMagic)
Note
The platform limitations for Java are primarily due to support for low level
serial and USB communication support. For non-serial based products, such as the Astra-EX and M6, the Java API should be usable on any platform.
It is also expected that the API will work on WinCE devices that use Intel x86, ARM, MIPS and Hitachi SH processors.

Language Specific Build and Runtime Details

The document also contains information on unique characteristics, build and runtime requirements relevant to specific languages and platforms in the following sections:
.NET Language Interface - Provides requirements for the development environment
and instructions for creating WinCE USB drivers and installing the WinCE sample app.
C Language Interface - Describes some of the unique characteristics of the C interface
in addition to help with building for embedded platforms. and the iOS environment.
Java Language Interface - Provides details on support for the low level JNI Serial
Interface library required to communicate with SerialReaders along with details on how to build the library for other platforms, including Android devices.
Advanced Customization - Provides instructions for creating a custom serial transport
layer and for using the tcp serial transport layer included in the MercuryAPI SDK.
Introduction to the MercuryAPI 13
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.
14 Introduction to the MercuryAPI

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.
/java/samples_nb - Contains Java code samples and associated NetBeans project
/java/samples - Contains Java code samples for Android Operating System
/c/src/samples - Contains C code samples, including a Makefile (in ../api) for building
the samples.
/c/ios/Samples - Contains C code samples for the IOS Operating System
Example Code
Introduction to the MercuryAPI 15

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.thingmagic.com/devkit.
Hardware Specific Guides
16 Introduction to the MercuryAPI

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. To allow for application requiring maximum compatibility and provide full access to all products functionality the MercuryAPI is conceptually divided into four layers:
Level 1 API - contains basic reader operations and is hardware and implementation
independent.
Level 2 API - contains a more complete set of reader operations, including more
complex variations of items in Level 1.
Level 3 API - contains the set of all operations specific to the different hardware
platforms. Levels 1 and 2 are built using these interfaces. Level 3 is hardware dependent.
Hardware Abstraction
Level 4 API - provides raw access to the underlying reader protocol for each specific
hardware platform. Level 3 is built on these interfaces. This level is not public and not supported for user applications.
Note
This is not a technical division, all four layers are available at all times. For
maximum cross-product compatibility the user must be aware of specific reader capabilities if using classes/interfaces below Level 2.
!
CAUTION!
!
Every level implicitly provides support for multiple tag protocols, including Gen2/ISO18000-6c and ISO18000-6b, even though not all prod­ucts support them. For maximum cross-product compatibility the user must be careful when “switching” from high level, protocol independent tag operations (basic reads and writes) to protocol specific operations, as defined by the protocol specific subclasses of the TagData class.
Introduction to the MercuryAPI 17

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 furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
18 Introduction to the MercuryAPI

Level 1 API

The objects and methods described in this section provide basic reader operations and are hardware and implementation independent.
Level 1 API 19

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.
The user obtains a Reader object by calling a static factory method:
Reader create(String uriString);
The create() method return an instance of a Reader class that is associated with a RFID reader on the communication channel specified by the uriString parameter. There are currently two subclasses of Reader:
Connecting to Readers
URI Syntax of the
SerialReader
The SerialReader class provides access to commands and configuration specific to devices which communicate over and use the embedded modules serial command protocol. These devices include:
– Mercury5e Series (including the M5e, M5e-Compact, M5e-EU, and M5e-PRC)
– USB Reader (M5e-based)
– Vega Reader (M5e-Based)
– Mercury6e Series (including the M6e, M6e-A, and M6e-PRC)
– Micro Series (including the Micro and Micro-LTE)
RqlReader
The RQLReader class provides access to commands and configuration specific to devices which can use the RQL command protocol. These devices include:
– Astra (Not Astra-EX) (v4.1.24 firmware)
LLRPReader
The LLRPReader class provides access to commands and configuration specific to devices which can use the LLRP communication protocol. These devices include:
– Mercury 6 (v4.9.2 firmware and later)
20 Level 1 API
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 Level 2
paramSet(), after the connect(), in order for any RF operations to
succeed.
When attempting to open a connection the API will wait for /reader/transportTimeout for the reader to respond. If a response isn’t received in that period of time an exception will be thrown. Certain transport layers, such as Bluetooth, may require a longer transportTimeout, especially during initial connect.
Region of Operation, /reader/region/id, to be set using
For RQLReader connections this opens a TCP connection to port 8080 (or another port if specified in the URI). For the SerialReaders when the specified serial device is opened the baud rate is “auto-detected”. Once connected the serial device is set to the preferred baud rate (115200 by default, for maximum compatibility with host serial devices). The baud rate can also be manually set, prior to calling Connect(), using the
Configuration Parameters /reader/baudRate, this can avoid attempts using the wrong baud
rate during “auto-detect” for certain types of serial readers.
The connected reader is then queried for information that affects further communication, such as the device model. After the connect() succeeds the be set (unless the hardware only supports one) and is checked for validity, and the default protocol is set to Gen2.
Existing configuration on the device is not otherwise altered.
Region of Operation should
Reader
Note
It is the user’s responsibility to handle device restarts. If a device is restarted it is recommended that the previously existing Reader object be destroyed, and a new Reader object created.
Level 1 API 21
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.
Multiple Reader objects may be obtained for different readers. The behavior of create() called repeatedly with the same URI without an intervening destroy() is not defined.
URI Syntax
The URI argument follows a subset of the standard RFC 3986 syntax:
scheme://authority/path
The scheme defines the protocol that will be used to communicate with the reader. the supported “schemes” for ThingMagic devices are:
tmr - (ThingMagic Reader) indicates the API should attempt to detemine the protocol
and connect accordingly. The API will select among eapi, rql, and llrp, but any custom serial protocols, such as tcp will have to be explicitly specified.
eapi - indicates a connection to a SerialReader type device via a COM port (or a USB
interface acting as a virtual COM port).
rql - indicates a connection to an RqlReader type device.
llrp - indicates a connection to an LLRPReader type device.
The authority specifies an Internet address and optional port number for protocols with network transport (currently only rql), or is left blank to specify the local system.
The path is currently unused for rql and is used to specify the serial communications device to which the reader is attached for eapi. The tmr scheme assumes that the protocol is rql if there is a non-blank authority and a blank path, and the serial protocol if the authority is blank and the path is non-blank. tmr is the preferred scheme.
The C#.NET API allows users to add custom transport interfaces for readers. The samples include the URI “tcp”, which indicates a connection to an device via a TCP bridge.
SerialReader type
22 Level 1 API
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.101/ - typical format to connect to a fixed reader connected on a
network at address “192.168.1.101”. This will try first to connect to an port 5084, if no response then it will try to connect to an
RqlReader on port 8080.
LLRPReader on
eapi:///com1 - typical format to connect to a serial based module on Windows COM1
eapi:///dev/ttyUSB0 - typical format to connect to a USB device named ttyUSB0 on a
Unix system.
rql://reader.example.com/ - typical format to connect to a fixed reader connected on
a network at address “reader.example.com” on the default RQL port of 8080
rql://reader.example.com:2500/ - typical format to connect to a fixed reader
connected on a network at address “reader.example.com” on the non-default RQL port of 2500
llrp://reader.example.com/ - typical format to connect to a fixed reader connected on
a network at address “reader.example.com” on the default, standard LLRP port of 5084
llrp://reader.example.com:2500/ - typical format to connect to a fixed reader
connected on a network at address “reader.example.com” on the non-default LLRP port of 2500
Sample files within the MercuryAPI SDK may be used implement an additional URI (which is not “discovered” by the “tmr” URI):
tcp://reader.example.com/ - custom format to connect to a fixed reader connected
on a network at address “reader.example.com” on the default port of the tcp bridge.
tcp://reader.example.com:2500/ - custom format to connect to a fixed reader
connected on a network at address “reader.example.com” on the non-default tcp port of 2500
Region of Operation
The Region enumeration represents the different regulatory regions that the device may operate in (see reader specific Hardware Guide for supported regions). Supported Region enumeration values are:
Level 1 API 23
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. The supported regions for the connected device are available as a
Configuration Parameters under /reader/region/supportedRegions. Please refer to
the specific device’s User Guide for more information on supported regions.
Reader
24 Level 1 API

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
The result of a read operation is a collection of access to the information about the tag and the metadata associated with each tag read.
The default read behavior is to search for all tags on all detected antennas using all supported protocols. such as setting antennas (see criteria used for the search. These are controlled by the
reader/read/plan parameter of the Reader Configuration Parameters.
Level 2 API can be used for advanced control over read behavior,
Antenna Usage for more details), protocols and filtering
TagReadData objects, which provides
ReadPlan object assigned to the /
Note
Not all antennas are detectable by the readers. The antenna needs to have some DC resistance if it is to be discovered by the antenna detection circuit. If, when using the Level 1 read functionality, reads are not occurring it is possible the antennas are not detectable and require explicit setting in the
ReadPlan.
Reader.read()
The read() method takes a single parameter:
TagReadData[] Reader.read(long duration)
Level 1 API 25
Reading Tags - The Basics
duration - The number of milliseconds to read for. In general, especially with
readers of type avoid filling up the tag buffer. Maximum value is 65535 (65 seconds).
SerialReader, the duration should be kept short (a few seconds) to
It performs the operation synchronously, and then returns an array of objects resulting from the search. If no tags were found then the array will be empty; this is not an error condition.
When performing a synchronous read() operation the tags being read are buffered on the reader and stored in the reader’s Tag Buffer. During a single read() operation tag de­duplication will occur on the reader so re-reads of the same tag will result in the tag’s ReadCount metadata field to be incremented, a new created for each. The reader specific hardware guide should be referenced for information on the size of the Tag Buffer.
TagReadData instance will not be
TagReadData
Note
The C-API read() implementation takes 3 arguments, reader pointer,
duration in milliseconds and the reference to the tag count. The third parameter is an output parameter which gets filled by the read() method. Upon successful completion of read() the method returns TMR_SUCCESS status with the number of tags found. The
C Read Iterator methods need to be
used to retrieve the tags.
Reader.startReading()
The startReading() method is an asynchronous reading method. It does not take a parameter.
void Reader.startReading()
It returns immediately to the calling thread and begins a sequence of reads or a continuous read, depending on the reader, in a separate thread. The reading behavior is controlled by the
Reader Configuration Parameters:
/reader/read/asyncOnTime - sets duration of those reads,
/reader/read/asyncOffTime - sets the delay between the reads.
The results of each read is passed to the application via the listener registered with the addReadListener() method is called with a object for each read that has occurred. In the event of an error during these reads, the
ReadExceptionListener interface is used, and each listener registered with the
addReadExceptionListener() method is called with a ReaderException argument.
The reads are repeated until the stopReading() method is called.
ReadListener interface; each
TagReadData
26 Level 1 API
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., read listeners will be called once for every “/reader/read/ asyncOnTime” milliseconds. On all readers except the M6, M6e and Micro pseudo­asynchronous reading is the only implementation used for background reading operations.
Continuous Reading
The M6, M6e and Micro also support true continuous reading which allows for 100% read duty cycle - with the exception of brief pauses during RF frequency hops. Continuous reading is enabled when streamed to the host processor as they are read.
/reader/read/asyncOffTime is set to zero. In this mode tags are
Note
In continuous mode there is currently no on-reader de-duplication, every tag read will result in a tagread event being raised. This can result in a lot of communication and tag handling overhead which the host processor must be able to handle it. Consider the details on setting Gen2 Session and
Target values, as described in
How UHF RFID Works (Gen2), to decrease the
frequency of tag replies to inventory operations as a way to decrease traffic.
Return on N Tags Found
In addition to reading for the specified timeout or asyncOnTime period and returning all the tags found during that period, it is also possible to return immediately (more specifically, the time granularity is one Gen2 inventory round) upon reading a specified number of tags.
The behavior is invoked by creating a tags and setting it as the active
For optimum performance it is recommended to use a StaticQ setting for appropriate for the specified value of N, where:
/reader/read/plan.
StopTriggerReadPlan with the desired number of
/reader/gen2/q
Level 1 API 27
Reading Tags - The Basics
N <= 2
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.
Q
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. The interface has one method:
void tagRead(Reader r, TagReadData t)
This method is called for each tag read in the background after Reader.startReading() has been invoked.
See the example applications, i.e. readasync.java, for typical implementations.
!
CAUTION!
!
When performing asynchronous read operations the reader is operating in a continuous or pseudo-continuous read mode. During this mode per­forming other tag or reader operations, including GPIO operations, are not supported. As such, other tag and reader operations MUST NOT be performed within the tagRead() ReadListener method. Doing so can have unexpected results.
Embedded TagOp Invocation in order to perform an operation on every tag
Use found, or perform
Reader.read() and iterate through the tags found, perform-
ing the desired tag operations on each.

ReadExceptionListener

Classes that implement the ReadExceptionListener interface may be used as listeners (callbacks) for background reads. The interface has one method:
28 Level 1 API
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.
Level 1 API 29

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
Tags
TagData object representing the particular tag.
TagReadData (or arrays of) objects are the primary results of each tag found.
The actual EPC ID for a Tag can be found by calling the getTag() method which returns a
TagData object.
See the methods available for getting TagData and metadata (including, RSSI, Frequency, Phase, etc. - see Hardware specific user guide for available metadata) from TagReadData in the language specific API Reference.
Read Methods, one for

TagData

An object of the TagData class contains information that represents a particular tag. The methods and constructors of TagData allow access to and creation of TagData (tag’s EPC IDs) using byte and hexidecimal string formats.
TagData objects are used to represent the information on a tag which has been read (contained in the the field using
Interface so TagData objects may be used as such to perform operations, which use
TagFilters, on a tag with a particular EPC.
Subclasses of TagData, such as Gen2.TagData, may contain additional information specific to a particular protocol.
TagReadData object) and for representing data to be written to tag(s) in
Gen2.WriteTag. In addition, the TagData class implements the TagFilter
See the methods available for getting TagData and metadata from TagReadData in the language specific API Reference.
30 Level 1 API

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 memory banks, should be used.
Writing To Tags
Gen2.WriteData, for writing to specific locations in individual
Level 1 API 31

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 support

StatusListener

During Continuous Reading operations it is possible to get status reports at every frequency hop by the reader. A StatusReport object is sent to each Status listener upon receiving the status response. A status report can contain the following information:
Temperature - The current temperature of the reader as detected on the RF board.
Continuous Reading, only the M6e at this time.
Status Reporting
SerialReader type readers which
Frequency - The frequency the reader just completed using. This is the frequency the
noise floor is reported on.
Tx and Rx port - The antenna port that the reader just completed an operation on,
which the status is associated with.
Protocol - The protocol that the reader is currently using.
RF On time - The cumulative time this port has been actively transmitting since the
reader was rebooted or this statistic was reset. (This information can be used with total time to calculate the average transmit duty cycle since reset.)
Noise Floor- The noise floor at the current frequency with TX on. (This information
can be used to measure changes in the amount of reflected power in the RF environment.)
The specific status report fields returned are defined by the
Parameters under /reader/status.
The desired status report fields must be explicitly selected. All default to off (false) to minimize communications overhead.
Reader Configuration
32 Level 1 API

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.

ReaderCodeException

Exceptions
This exception is used for errors reported from the reader device. The class includes a method:
int getCode()
that returns the numeric error code reported by the device. This code can be very useful to ThingMagic Support when debugging a problem.
See the reader specific Hardware Guide for details on the error codes returned.

ReaderParseException

This exception is used when a message was successfully received from the device, but the format could not be understood by the API.

ReaderFatalException

This exception is used in the event of an error in the device or API that cannot be recovered from. All device operations will fail after reception of this exception. This exception indicates a potentially damaging situation has occurred, or the reader is damaged, and the reader has reset.
In the event of receiving a ReaderFatalException error from a reader device, the message returned with the exception will be included in the exception string, in ASCII
Level 1 API 33
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
Parameters for more details on reader supported features.
Reader Configuration
34 Level 1 API

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.
Level 2 API 35

Advanced Reading

ReadPlan

An object of class ReadPlan specifies the antennas, protocol and filters to use for a search (
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
SimpleReadPlan
Read Methods). The ReadPlan used by a search is specified by setting /reader/
Advanced Reading
MultiReadPlan.
A SimpleReadPlan constructor accepts the following parameters:
Tag Protocol - defines the protocol to search on. The default is Gen2. To search on
multiple protocols a
MultiReadPlan should be used.
int[] of antennas - defines which antennas (or virtual antenna numbers) to use in
the search. The default value is a zero-length list.
– When the list of antennas is zero-length the reader will run antenna detection on
each port in
– When the list of antennas is not zero-length, all the specified antennas will be
used, unless include detectable antennas.
See
Antenna Usage for more information on antenna configuration and usage.
/reader/antenna/portList and use all detected antennas.
/reader/antenna/checkPort is enabled in which case the list can only
Note
Not all antennas are detectable by the readers. The antenna needs to have some DC resistance if it is to be discovered by our antenna detection circuit. If, when using the zero-length array method requiring antenna detect, reads are not occurring it is possible the antennas are not detectable and require explicit setting.

TagFilter Interface - defines a subset of tags to search for.
TagOp Invocation - defines a tag operation (ReadData, WriteData, Lock, Kill, etc.) to be
performed on each tag found, as its found. When read operations are performed the
36 Level 2 API
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, the list of all constructors.
TagFilter Interface and weights. See the language specific reference guide for
StopTriggerReadPlan
This sub-class of SimpleReadPlan accepts the following additional parameter and, when set as the active
Tags Found instead of waiting for the full timeout or /reader/read/asyncOnTime to expire:
StopOnTagCount - This class contains an integer field N which specifies the number
of tags read required to trigger the end of the read operation. See
Found for suggestions on optimizing configuration for a particular N value.
/reader/read/plan, will cause the Read Methods operation to Return on N
Return on N Tags
Note
Not currently supported with
Continuous Reading.
MultiReadPlan
A MultiReadPlan object contains an array of other ReadPlan objects. The relative weight of each of the included sub­total read time is allotted to that sub-plan.
For example, if the first plan has a weight of 20 and the second has a weight of 10, the first 2/3 of any read will use the first plan, and the remaining 1/3 will use the second plan).
MultiReadPlan can be used, for example, to search for tags of different protocols on different antennas and search on each for a different amount of time.
!
CAUTION!
The M6e does not currently support MultiReadPlans when operating in
Continuous Reading mode. If a MultiReadPlan is being used on an M6e with
the Reader.StartReading() method then greater than zero.
ReadPlans is used to determine what fraction of the
!
/reader/read/asyncOffTime must be
Level 2 API 37
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 ReadPlans have weight=0. This signals the API to defer to the module for read plan scheduling.
See the MultiProtocolRead
Example Code for language specific code samples.
MultiReadPlan where all child
Note
Your M6e must be
Rebooting Readers installed for multiple protocols in order
to support multi-protocol reads.
38 Level 2 API

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:
Selecting Specific Tags
1. Air Protocol Filtering - When specifying a TagFilter as parameter for
Reading or Advanced Tag Operations [Deprecated], the filter will be applied at the air
protocol level, i.e. to tags “in the field”. That is, only tags matching the TagFilter criteria will be returned in an inventory operation or operated (write, lock, etc.) on.
2. Post Inventory Filtering - Objects of type TagFilter provide a match() method
that can be used to check whether a This filtering is not applied to tags “in the field”.
TagData object matches the TagFilter criteria.
Advanced
Note
Currently, post inventory filtering with match() can only be used to filter against a
The TagData class implements the TagFilter interface and TagData objects may be used as such to match a tag with a specific EPC. The protocol specific classes:
Gen2.Select and ISO180006B.Select, among others, represent the protocol selection
capabilities of their respective protocols and can be used to perform the protocol-specific filtering operations. Applying a filter of one protocol to an operation of another protocol will result in an error.
A
MultiFilter object can be used to create more elaborate filters from a list of simpler filters.
MultiFilters are not currently supported by any readers.
Any TagFilter may match more than one tag in an operation; they do not guarantee uniqueness.
TagData EPC value.
Note
The Mercury4, Mercury5 and Astra readers currently only support TagData
filters. They do not support [Protocol].Select type TagFilters.
MultiFilter
Contains an array of objects that implement the TagFilter Interface. When used as a TagFilter the array of TagFilters in the MultiFilter object will be applied for tag selection.
Level 2 API 39
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.Bank bank, int bitPointer, int bitLength, byte[] mask)
invert = Whether to invert the selection (deselect tags that match the filter criteria
and return/operate on the ones which don’t)
bank = The Gen2.Bank enumeration constant (EPC, TID, USER) indicating the
memory bank to be matched.
bitPointer = The memory bank offset, in bits (zero-based 16 bit multiples), at
which to begin comparing the mask value.
bitLength = The length, in bits (16 bit multiples), of the mask.
mask = The value to compare with the data in the specified memory bank (bank) at
the specified address offset (bitPointer), MSB first.
ISO180006B.Select
The ISO180006B.Select class represents a selection operation in the ISO18000-6b protocol. This class provides the capability to select ISO18000-6B tags based on the value of data stored on the tag. The tag selection criteria can be specified using the
ISO180006B.Select constructor:
ISO180006B.Select(boolean invert, ISO180006b.SelectOp op, int address, byte mask, byte[] data)
invert = Whether to invert the selection (deselect tags that match the filter criteria
and return/operate on the ones which don’t)
op = The type of The operation to use to compare the tag data to the provided data.
See the ISO180006b.SelectOp class info.
address = The address of the tag memory to compare to the provided data.
mask = Bitmask of which of the eight provided data bytes to compare to the tag
memory. Each bit=‘1’ indicates the corresponding byte will be compared. If bit[0]=1 then byte[0] value will be compared with found tags.
data = The data to compare. Exactly eight bytes.
40 Level 2 API
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 [protocol name].
Note
Not all devices support all protocols. The list of supported protocols for a connected device is available in the
version/supportedProtocols. See the specific hardware’s User Guide or
datasheet for more details on its supported protocols.
Reader Configuration Parameters section under /reader/
Reader Configuration Parameters:/reader/
Level 2 API 41

Advanced Tag Operations

Note
These new TagOp data structures replace the older individual
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. The following groups of TagOps are supported:
Gen2 Standard TagOps
Gen2 Optional TagOps
Gen2 Tag Specific TagOps - Alien Higgs
Gen2 Tag Specific TagOps - NXP G2*
Advanced Tag Operations
Advanced Tag
Gen2 Tag Specific TagOps - Impinj Monza4
ISO18000-6B TagOps
Using TagOp provides a scalable architecture for extending supported tag operations than an ever-increasing number of individual API methods. TagOps have the added benefit of being embeddable in larger structures; e.g., SimpleReadPlan with a TagOp allowing for operations to be automatically performed on every tag found during an
Advanced Reading operation.
Specific tagop structures depend on the structure of the protocol commands. See the
Language Specific Reference Guides TagOp subclasses for detailed information.
Direct Invocation
The Reader.ExecuteTagOp() method provides direct execution of TagOp commands. Using ExecuteTagOp() results in the following behavior:
The reader operates on the first tag found, with applicable tag filtering as specified by
the
TagFilter Interface object passed in ExecuteTagOp().
The command will be attempt for the timeout value specified in the /reader/
commandTimeout.
The reader stops and the call returns immediately after finding one tag and operating
on it, unless the timeout expires first.
The operation is performed on the antenna specified in /reader/tagop/antenna
42 Level 2 API
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. When a
SimpleReadPlan is created with a TagOp specified in the tagOp parameter the following
behavior results:
The specified operation will be executed on each tag as each tag is found during the
Advanced Reading operation.
The specified operation will be performed on the same antenna the tag was read on
during the overall read operation.
The rules of the Advanced Reading operation and specified ReadPlan apply.
Note
Embedded TagOps are only supported with Gen2 (ISO18000-6C) protocol tags and when connected to readers of type SerialReader and RQLReader type M6.
Note
In previous versions of the API this functionality required the use of
API operations. Those operations should no longer be used.
Level 3
Embedded TagOp Success/Failure Reporting
Current reader functionality (May 2011) does not provide a means to report the success or failure of an embedded tagop for each invocation, except for ReadData operations where the presence or absence of the data is an implicity indicator. Summary success/ failure information is available through the following
/reader/tagReadData parameters:
/reader/tagReadData/tagopSuccess
/reader/tagReadData/tagopFailures
Note
Depending on the Gen2
Tag Contention Settings used the operations
Succeeded/Failed counts can be misleading since in Session 0, for example, the tag may respond many times during an inventory round and the command may be attempted many times. This would result in counts higher than the actual number of unique tags the operation succeeded or failed on.
These counters are reset to zero at the beginning of each Reading operation and behave as follows:.
Level 2 API 43
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.WriteTag
Writes the specified EPC ID value to the tag. It is preferred over using Gen2.WriteData because WriteTag will automatically lengthen or shorten the EPC ID, by modifying the PC bits, according to the Tag EPC specified. If WriteData is used, the specified data will be modified but the EPC ID length will not be modified.
Note
Gen2.WriteTag will always use
/reader/gen2/q=0 if set to Gen2.DynamicQ.
For use with large tag populations a StaticQ appropriate for the population size should be used to avoid collisions.
Gen2.ReadData
Reads the specified number of memory words (1 word = 2 bytes) of tag memory from the specified Memory Bank and location.
Note
Currently limited to returning 123 words of data per standalone ReadData invocation or 32 words when performed as an Embedded TagOp Invocation.
When used as an Embedded TagOp Invocation the data read can be used an a unique identifier of the tag by setting with the same EPC ID but different values in the specified Gen2.ReadData memory location to be treated as unique tags during inventories.
Note
Specifying 0 (zero) as the data size to read will result in the entire contents of the specified memory bank (up to the maximums specified above) being returned.
/reader/tagReadData/uniqueByData = true. This allows tags
44 Level 2 API
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. The lock operation to perform is represented as an instance of the
In order to lock Gen2 Memory the desired password must first be written to Reserved Memory. Once the Access passwordhas been written the desired memory can be locked using the AccessPassword. This can be done by either:
Gen2.LockAction Class.
Set /reader/gen2/accessPassword to the correct value and specify 0 in the Gen2.Lock
instance’s password field
Set the password parameter of the Gen2.Lock instance to the correct password.
Gen2.LockAction Class
Instances of this class represent a set of lock and unlock actions on a Gen2 tag. It is based on the LLRP syntax for C1G2Lock.
There are 5 lockable fields within the tag memory (LLRP calls these “DataFields”): EPC, TID, User, Kill Password and Access Password. Each field may be assigned one of 4 possible lock states (LLRP calls these “Privileges”):
Lock: Writes not allowed. If the field is a password, then reads aren’t allowed, either.
Unlock: Reads and Writes allowed.
Permalock: Permanently locked – attempts to Unlock will now fail.
Permaunlock: Permanently unlocked – attempts to Lock will now fail.
Gen2.LockAction encapsulates a field and a lock state. Predefined constants are provided for every possible combination of field and lock state.
Gen2.LockAction.KILL_LOCK
Gen2.LockAction.KILL_UNLOCK
Level 2 API 45
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
Advanced Tag Operations
Gen2.LockAction.TID_PERMAUNLOCK
Gen2.LockAction.USER_LOCK
Gen2.LockAction.USER_UNLOCK
Gen2.LockAction.USER_PERMALOCK
Gen2.LockAction.USER_PERMAUNLOCK
To lock a single field, provide one of these predefined constants to
Gen2 tags allow more than one field to be locked at a time. To lock multiple fields, a Gen2.LockAction constructor is provided to combine multiple Gen2.LockActions with each other.
lockTag().
Example:
new Gen2.LockAction(Gen2.LockAction.EPC_LOCK, Gen2.LockAction.ACCESS_LOCK, Gen2LockAction.KILL_LOCK)
A Gen2.LockAction constructor is also provided which allows explicit setting of mask and action fields. These 10-bit values are as specified in the Gen2 Protocol Specification. Use the constructor:
46 Level 2 API
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.LockBits.USER
Gen2.LockBits.USER_PERM
Gen2.Kill
Sends a kill command to a tag to permanently disable the tag. The tag’s Reserved memory Kill Password must be non-zero for the kill to succeed.

Gen2 Optional TagOps

The following tag operations are optional features of the Gen2 tag specification and are supported by many but not all Gen2 tags. These operations are supported by readers of type
SerialReader and the M6.
Gen2.BlockWrite
On tags which support this command, it provides faster writing of data to a tag by writing more than one word at a time over the air, compared to to write over the air to the tag word by word.
Calls to BlockWrite can only specify data of the maximum length which the tag supports in its BlockWrite implementation. For example, Impinj Monza tags only support 2-word
Gen2.WriteData which sends data
Level 2 API 47
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
reader/gen2/writeMode = Gen2.WriteMode.BLOCK_ONLY or BLOCK_FALLBACK
Gen2.WriteData by setting /
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 tag- specific. For example, Alien Higgs3 tags support 4 word blocks.
Gen2.Lock which only allows locking entire memory banks. The block-size is

Gen2 Tag Specific TagOps - Alien Higgs

The following tag operations are custom tag commands supported only on tags using Alien Higgs2 and Higgs3 chips, as implied by the TagOp name. These operations are supported by readers of type
Gen2.Alien.Higgs2.PartialLoadImage
This command writes an EPC with a length of up to 96-bits, plus the Kill and Access passwords without locking in a single command.
SerialReader and the M6.
Note
Does not support the use of a
TagFilter Interface.
Gen2.Alien.Higgs2.FullLoadImage
This command writes an EPC with a length of up to 96-bits, plus the Kill and Access passwords and will also modify the Lock bits (locking the tag according to the Alien Higgs Lock Bits) and the PC Bits.
Note
Does not support the use of a
TagFilter Interface.
Gen2.Alien.Higgs3.FastLoadImage
This command writes an EPC with a length of up to 96-bits, the Kill and Access passwords to Higgs3 tags in a single command, thereby reducing the tag programming time compared to the use of LoadImage or multiple Gen2.WriteData commands.
48 Level 2 API
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.

Gen2 Tag Specific TagOps - NXP G2*

The following tag operations are custom tag commands supported only on tags using NXP G2xL, G2iL and/or G2iM chips. The commands are supported on all chip types as their names imply. These operations are currently only supported by readers of type
SerialReader and the M6.
Gen2.NXP.G2I.SetReadProtect and
Gen2.NXP.G2X.SetReadProtect
Causes all tag access command, all Gen2 TagOps and Gen2.NxpSetReadProtect, Gen2.NxpChangeEAS, Gen2.NxpEASAlarm and Gen2.NxpCalibrate to be disabled until a
Gen2.NXP.G2I.ResetReadProtect and Gen2.NXP.G2X.ResetReadProtect is sent.
Gen2.NXP.G2I.ResetReadProtect and
Gen2.NXP.G2X.ResetReadProtect
Restores normal operation to a tag which is in ReadProtect mode due to receiving
Gen2.NXP.G2I.SetReadProtect and Gen2.NXP.G2X.SetReadProtect.
Note
Gen2.NXP.G2X.ResetReadProtect cannot be used through
Invocation, only via Direct Invocation. However the G2I version can and can be
used with G2x tags.
Embedded TagOp
Gen2.NXP.G2I.ChangeEas and Gen2.NXP.G2X.ChangeEas
Sets or resets the EAS system bit. When set, the tag will return an alarm code if an “EAS Alarm” command is received.
Level 2 API 49
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 and it does not support
Embedded TagOp Invocation, only via Direct Invocation
TagFilter Interface usage.
Gen2.NXP.G2I.Calibrate and Gen2.NXP.G2X.Calibrate
Calibrate causes the tag to return a random data pattern that is useful in some frequency spectrum measurements.
Note
Calibrate can only be sent when the tag is in the Secured state, when the access password is non-zero.
Gen2.NXP.G2I.ChangeConfig
Used to toggle the bits of the G2i* tag’s Gen2.ConfigWord. Specify ‘true’ for each field of the Gen2.NXP.G2I.ConfigWord to toggle that setting.
Different version of the G2i* tags support different features. See tag data sheet for specific bits supported.
The Gen2.NXP.G2I.ChangeConfig command can ONLY be sent in the Secured state, i.e. requires a non- zero password. Caution should be used when using this through an
Embedded TagOp Invocation. Since this command toggles the specified fields, if the tag
responds twice (or an even number of times) during an inventory round the end result will be no change.

Gen2 Tag Specific TagOps - Impinj Monza4

The following tag operations are custom tag commands supported only on tags using Impinj Monza4 and Monza5 chips. These operations are supported by readers of type
SerialReader and the M6.
50 Level 2 API
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.

Gen2 Tag Specific TagOps - IDS SL900A

The following tag operations are custom tag commands supported only on tags using IDS SL900A chips. These operations are supported by readers of type
LLRPReader. Further details about the IDS SL900A tag silicon and the supported custom
commands can be found on the IDS Microchip website (http://www.ids-microchip.com/) and the Cool-Log command set specification (http://www.ids-microchip.com/doc/an/IDS­SL900A-AN6-Cool-log.pdf).
Sample codelets using the SL900A custom commands can be found in the C# /Samples/ Codelets/SL900A directory of the MercuryAPI SDK, v1.11.2 or later.
SerialReader and
The current set of supported IDS SL900A custom commands are as follows:
Gen2.IDS.SL900A.AccessFifo
The ACCESS FIFO command can read and write data from the FIFO and can also read the FIFO status register.
Gen2.IDS.SL900A.GetBatteryLevel
The GET BATTERY LEVEL command starts the AD conversion on the battery voltage and returns the voltage level with the battery type (1.5V or 3V).
Gen2.IDS.SL900A.GetCalibrationData
The GET CALIBRATION DATA command reads the calibration data field and the SFE parameters field.
Gen2.IDS.SL900A.GetLogState
The GET LOG STATE command reads the status of the logging process. The command can be used to quickly determine the current state of the product, together with the Shelf life and the Limit counter.
Level 2 API 51
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.Initialize
The INITIALIZE command clears the System status field, the Limit counters and sets the Delay time field and the Application data field. The Initialize command is needed before the START LOG command as it will clear the pointers and counters. If the application needs to run the logging process from the previous point on, the Initialize command ca be left out.
Gen2.IDS.SL900A.SetCalibrationData
The SET CALIBRATION DATA write to the calibration block in the EEPROM memory. The calibration data is preset during manufacturing, but can also be changed in the application if needed. The update the calibration values in the calibration registers. The calibration registers are automatically updated with each
SET CALIBRATION DATA will write only to the EEPROM, but it will not
START LOG command.
Gen2.IDS.SL900A.SetLogLimit
The SET LOG LIMIT command writes the 4 limits that are used in the logging process. All 4 limits are 10 bits long.
Gen2.IDS.SL900A.SetLogMode
The SET LOG MODE command sets the logging form, storage rule, enables sensors that are used in the logging process and sets the logging interval (in 1 second steps).
52 Level 2 API
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. Those parameters include the range preset values for the external sensor inputs, external sensor types and the also the sensor that will be used for limits comparison.
Gen2.IDS.SL900A.StartLog
The START LOG command starts the logging process. It refreshes the data in the calibration registers, enables the RTC, writes the Start time and sets the Active bit in the “System status” field in the EEPROM.

ISO18000-6B TagOps

Note
Cannot be used through and must be invoked with an Iso180006b.TagData
Iso180006b.ReadData
Read the specified number of data bytes starting at the specified byte-offset memory location.
Iso180006b.WriteData
Write the specified data starting at the specified byte-offset memory location.
Embedded TagOp Invocation, only via Direct Invocation
TagFilter Interface.
Level 2 API 53
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
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.
ISO180006B.LockAction class.
54 Level 2 API

Advanced Tag Operations [Deprecated]

Advanced Tag Operations [Deprecated]
!
The following individual tag operation methods are being deprecated in favor of the new ment 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. 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.
All of the following methods will use the timeout value specified in the
commandTimeout.
CAUTION!
TagOp Invocation class and its subclasses. All new develop-
!
/reader/

Killing Tags

killTag()
void killTag(TagFilter target, TagAuthentication auth)

Locking Tags

lockTag()
void lockTag(TagFilter target, TagLockAction lock)

Tag Memory Access

readTagMemBytes()
byte[] readTagMemBytes(TagFilter filter, int bank, int address, int length)
Level 2 API 55
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. The search cycles through the antennas, moving to the next antenna when no more tags are found on the current antenna.
Note: The cycle resets and restarts on the first antenna each time Reader.read()is re-issued or, in
the case of Reader.startReading(), after each /reader/read/asyncOnTime period.
In this case the amount of time spent reading on each antenna is non-deterministic and there is no guarantee all antennas will be used in any specific time period. It will stay on an antenna as long as there are still tags being read.
2. Create a SimpleReadPlan for each antenna and combine them into a MultiReadPlan giving each a relative weight based on the desired percentage of time spent on it and use that MultiReadPlan as your
/reader/read/plan setting.

Virtual Antenna Settings

The M6e and M5e-Family of reader devices have built-in support for using Multiplexers, supporting up to eight antenna ports on the M5e and 16 on the M6e, and combining monostatic and bistatic antenna operation. For more information on how the Multiplexer support works at the module level please see the M5eFamilyDevGuide_May09.pdf or later.
In the MercuryAPI the configuration of multiple antennas and bistatic/monostatic operation on M5e-Family products is done using the
reader/antenna/portSwitchGpos configuration parameters.
Auto Configuration
When using the most recent version of reader firmware and the MercuryAPI the readers will self-identify their configuration and the ports settings will be automatically configured. The type of reader will be provided in the parameter
/reader/antenna/txRxMap and /
/reader/version/productGroup. For
Level 2 API 57
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. Once configured the virtual antenna number for each antenna configuration setting will be used in place of the physical port number in API calls, such as in
SimpleReadPlan.
The map between virtual antenna numbers and physical antenna ports specified in
reader/antenna/txRxMap will be used to filter the detected antennas - antenna ports that
are detected but have no corresponding virtual antenna in the map will not be used. The map will also be used to translate from specified antenna numbers to antenna ports.
/
Vega Reader Example
In order to map the virtual port numbers to correspond to the antenna port
labels on the Vega reader you must set the portSwitchGpos to use one GPOutput line to control the 1 to 2 multiplexer used by Vega (as noted in the Vega User Guide) and setup the txRxmap:
r.paramSet("/reader/antenna/portSwitchGpos", new int[]{1});
r.paramSet("/reader/antenna/txRxMap", new int[][]{new
int[]{1,2,2}, new int[]{2,5,5}, new int[]{3,1,1}});
58 Level 2 API

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 by the reader are provided in the
The gpiGet() and gpoSet() methods use an array Reader.GpioPin objects which contain pin ids and values.
Note
The gpoSet() method is not guaranteed to set all output pins
simultaneously.
/reader/gpio/inputList parameter. The pin numbers supported as outputs
GPIO Support
/reader/gpio/outputList parameter.
Note
The gpiGet() method returns the state for all GPI pins.
Note
See specific devices User Guide for pin number to physical pin mapping.

GPIO Direction

M6e Only
The direction (input or output) of the GPIO pins on the M6e are configurable. The configuration of the pins can be configured by setting the the the /reader/gpio/outputList parameters.
M6e Only
/reader/gpio/inputList and
Level 2 API 59

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 for details) connected to a firmware image. It is the user’s responsibility to have an appropriate firmware file. No password is required.
Firmware Updates
Language Specific Reference Guides
60 Level 2 API

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.
Rebooting Readers
Level 2 API 61

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 key.
Once set the key is stored persistently in flash and does not need to be repeatedly set.
Note
See

Deprecated API

Reader Configuration Parameters /reader/licenseKey to the provided license
Example Code for language specific examples of how to set the key.
Protocol License Keys
SerialReader method:
public byte[] cmdSetProtocolLicenseKey(byte[] key) throws ReaderException
Parameters:
key - license key
Returns:
Supported protocol bit mask
62 Level 2 API

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.
void message(boolean tx, byte[] data, int timeout)
When data is sent to the device, message() is invoked with tx set to true.
Debug Logging
When data is received from the device, message() is invoked with tx set to false. The timeout originally specified by the caller is also returned.
The data field includes every byte that is sent over the connection, including framing bytes and CRCs.
To remove a TransportListener from an object so that it no longer is notified of message packets call removeTransportListener():
void removeTransportListener(Reader.TransportListener listener)
Note
For most users raw, transport layer packet information will not be very useful but can be a critical tool for ThingMagic Support to debug a problem. To facilitate debugging it is recommended that TransportListener logging be available in all applications.
Level 2 API 63

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 configuration of the devices antennas.
paramGet()
The paramGet() method retrieves the value of a particular named parameter. The returned type is generic (Object) and must be cast to the appropriate type.
/reader/antenna provide information about and allow
Configuring Readers
paramSet()
The paramSet() method sets a new value for a parameter. The type of the value that is passed must be appropriate for the parameter. Not all parameters can be set.
paramList()
The function String[] paramList() returns a list of the parameters supported by the Reader instance. Readers of different types (serial, RQL, etc.) support different configuration parameters.

Save and Restore Configuration

M6e Only
The M6e supports configuration settings to be saved in flash providing configuration persistence across reboot. Currently (M6e FW v.1.B) the following settings can be saved across reboots:
/reader/region/id
/reader/tagop/protocol
64 Level 2 API
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
userConfig parameter to a SerialReader.UserConfigOp with the appropriate
parameter.
See the configurations on the M6e.
Example Code Codelets\SavedConfig for an example of saving and restoring

Reader Configuration Parameters

The following are all the available parameters broken down by grouping:
/reader
/reader/baudRate
Type: integer
Default value: 115200
Writable: yes
/reader/
Products: M5e (and derived products), M6e
This parameter (present on serial readers only) controls the speed that the API uses to communicate with the reader once communication has been established. When a Reader.Connect() occurs the serial baud rate is “auto-detected” by attempting supported baud rates in the following order:
1. value of /reader/baudRate
2. 9600
3. 115200
4. 921600
5. remaining supported baud rates in increasing order
Once connected if the connection baud rate is not the same as the value of /reader/ baudRate the module’s baudrate will be changed to /reader/baudRate.
Level 2 API 65
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. If the M6e boot baud rate is
changed it is recommended to set /reader/baudRate to the saved M6e boot baud rate prior to Reader.Connect() to avoid the penalty of trying incorrect rates during auto-detect.
/reader/commandTimeout
Type: int
Default value: 1000
Writable: yes
Products: all
Sets the timeout, in milliseconds, used by how long the reader will continue to attempt a tag Operation before giving up. If it succeeds before the specified timeout the operation completes and returns. If it hasn't succeeded after repeatedly trying for the timeout period, it gives up and returns an exception.
Advanced Tag Operations. This timeout specifies
/reader/licenseKey
Type: Array of bytes
Default value: From reader
Writable: yes (not readable)
Products: M6e
Used to install licensed features, such as additional protocols
66 Level 2 API
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.
/reader/transportTimeout
Type: int
Default value: 1000
Writable: yes
Products: all
The number of milliseconds to allow for transport of the data over level 4 transport layer. Certain transport layers, such as Bluetooth, may require longer timeouts.
/reader/userMode
Type: SerialReader.UserMode
Default value: From reader
Writable: yes
Products: M5e (and derived products)
Sets a number of protocol specific parameters for particular usecases.
Level 2 API 67
/reader/uri
Type: String
Default value: From reader
Writable: no
Products: all
Configuring Readers
Gets the URI string used to connect to the reader from the
/reader/userConfig
Type: SerialReader.UserConfigOp
Default value: null
Writable: yes
Products: M6e
Enables M6e configuration Saving and Restoring. See
/reader/antenna
/reader/antenna/checkPort
Type: boolean
Default value: From reader
Writable: yes
Reader Object.
Save and Restore Configuration.
Products: M5e (and derived products), M6e, M6
Controls whether the reader checks each antenna port for a connected antenna before using it for transmission. Make sure all connected antennas are detectable before turning this on.
On the M6 this is enabled by default and also turns antenna detection on at boot time. This results in the Web Interface | Status page reflecting which antennas are connected, detectable and available for usage. If disabled then antennas to transmit on must always be explicitly specified.
68 Level 2 API
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 parameter.
/reader/antenna/portSwitchGpos parameter may change the value this
/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. Changing the may change this parameter.
/reader/antenna/portSwitchGpos parameter
/reader/antenna/portSwitchGpos
Type: Array of integers
Writable: yes
Products: M5e (and derived products), M6e
Controls which of the reader’s GPO pins are used for antenna port switching. The elements of the array are the numbers of the GPO pins, as reported in /reader/gpoList.
/reader/antenna/settlingTimeList
Type: array of array of integers
Default value: From reader
Writable: yes
Products: M5e (and derived products), M6e
A list of per transmit port settling time values. Each list element is a length-two array; the first element is the
Level 2 API 69
Antenna Usage number as defined by /reader/antenna/txRxMap
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. for
the M5e = [[1,1,1],[2,2,2]]
Writable: yes
Products: M5e (and derived products), M6e
A configurable list that associates transmit ports with receive ports (and thus selects monostatic mode or bistatic mode for each configuration) and assigns a number to each. Each list element is a length three array, [ [ A, B, C], ...], where:
Antenna Usage
A is the virtual antenna number
B is the transmit (TX) physical port number
C is the receive (RX) physical port number.
The reader will restrict which combinations are valid.
Example: Using an M5e configured for both monostatic and bistatic operation, with the bistatic configuration (TX=1, RX=2) assigned virtual port 1 and the monostatic configuration (TX=1, RX=1) assigned virtual port 2:
r.paramSet("/reader/antenna/txRxMap", new int[][]{new int[]{1,1,2}, new int[]{2,1,1}});
/reader/gen2
See the Performance Tuning sections: How UHF RFID Works (Gen2) and Optimizing Gen2
settings for details on how the following settings related to reader performance and how to
select the best settings for your usecase.
70 Level 2 API
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.WORD_ONLY
Writable: yes
Products: M6e, M6
Controls whether write operations will use the optional Gen2 BlockWrite command instead of writing block (word) by block until all the data is written. Using BlockWrite can result in significantly faster write operations, however, not all Gen2 tags support BlockWrite.Three modes are supported:
WORD_ONLY - Use single-word Gen2 Write only. Guaranteed to work with all Gen2
tags.
BLOCK_ONLY - Use multi-word Gen2 BlockWrite only. Not all tags support
BlockWrite. If a write is attempted in this mode on a non-supporting tag it will fail and an exception will be thrown.
BLOCK_FALLBACK - Try BlockWrite first then, if it fails, retry a standard Write.
Level 2 API 71
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. If its not then the reader could be reading data faster than the transport can handle and send and the reader’s buffer might fill up.
/reader/gen2/q
Type: Gen2.Q
Default value: Gen2.DynamicQ
Writable: yes
Products: all
Controls whether the reader uses a dynamic, reader controlled, Q algorithm or uses a static, user defined value, and that static value. The value of Q only makes a difference if it is considerably too high or considerably too low. If it is considerably too low, all slots will contain collisions and no tags will be read. If it is considerably too high, then many slots will pass with no tag attempting to communicate in that slot. The number of slots is 2^Q, so for 7 tags, a Q of 4 should be ideal. Each slot takes approximately 1 microsecond, so the overall affect of empty slots is not significant to the overall performance unless the Q is extremely high.
The Q value will not affect the write success rate.
See
Tag Contention Settings for details.
72 Level 2 API
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. See the [product] Hardware Guide for full configuration options. See
Reader Settings for details.
Tag-to-
/reader/gen2/session
Type: Gen2.Session
Default value: Gen2.Session.S0
Writable: yes
Products: all
Controls the session that tag read operations are conducted in. See
Settings for details.
Tag Contention
Level 2 API 73
/reader/gen2/target
Type: Gen2.Target
Default value: Gen2.Target.A
Writable: yes
Products: all
Configuring Readers
Controls the target algorithm used for read operations. See details.
Tag Contention Settings for
/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.
/reader/gen2/writeReplyTimeout
Type: Integer
Default value: 20000
Writable: yes
Products: M5e, M6e
Controls the time, in microseconds, each word write operation (a
Gen2.WriteData consists of multiple word write operations) will wait for a tag response
before moving to next word write. Great caution must be taken when changing this parameter. Not all tags take the same amount of time to complete each word write. If the time is shortend to less than the time a tag takes to perform each word write, the write operation will fail. The Gen2 specification dictates that all tags must complete and respond to a word write in 20ms or less. Some tags take less than 3ms, some close to 20ms
– Max. timeout = 21000us
Gen2.WriteTag and
74 Level 2 API
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 per word write.
Using Fixed Wait Time results in a consistent time for each write operation. With Early Exit the time it takes to write a tag can vary since in some cases the word response will be detected and the write operation will immediatly move onto the next word write and in other cases the response is missed and the full timout must expire before moving to the next word.
/reader/gen2/writeReplyTimeout
/reader/gpio
/reader/gpio/inputList
Type: Array of integer
Writable: no (yes for the M6e)
Products: all
Contains the numbers of the GPIO pins available as input pins on the device.
M6e - Set to an array of ints (1 through 4) to configure GPIO lines as inputs.
/reader/gpio/outputList
Type: Array of integer
Writable: no (yes for the M6e)
Products: all
Contains the numbers of the GPIO pins available as output pins on the device.
Level 2 API 75
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.
/reader/iso18000-6b/modulationDepth
Type: Iso18000-6b.ModulationDepth
Default value: MODULATION99PERCENT
Writable: yes
Products: M6e
In some cases using the smaller modulation depth of 11% will result in improved read range and read reliability as it allows more power to be transmitted to the tag. However, the smaller modulation depth can also result in a greater reduction in performance when interference is present.
76 Level 2 API
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
– GROUP_SELECT_EQ
– GROUP_SELECT_NE
– GROUP_SELECT_GT
– GROUP_SELECT_LT
– GROUP_UNSELECT_EQ
– GROUP_UNSELECT_NE
– GROUP_UNSELECT_GT
– GROUP_UNSELECT_LT
ISO180006B.Select , specifically, one of the following:
/reader/radio
/reader/radio/enablePowerSave
Type: boolean
Default value: False
Writable: yes
Products: M6e
Controls the M6e Transmit Mode. When enabled the M6e power consumption is reduced during RF operations but is no longer 100% compliant with the Gen2 DRM spectral mask. See the M6e Hardware Guide for more details on Transmit Modes.
Level 2 API 77
/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.
Configuring Readers
/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. Each list element is a length­two array. The first element is the port number, and the second element is the power level in centidBm. Ports not listed are assigned a per-port power level of 0 (which indicates it will use the global read power level:
/reader/radio/readPower)
/reader/radio/portWritePowerList
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 write operations. Each list element is a length­two array. The first element is the port number, and the second element is the power level in centidBm. Ports not listed are assigned a per-port power level of 0 (which indicates it
78 Level 2 API
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).
/reader/radio/writePower
Type: integer
Default value: From reader
Writable: yes
Products: all
The global transmit power setting, in centidBm, for write operations (except where overridden by
/reader/radio/portWritePowerList).
/reader/radio/temperature
Type: integer
Writable: no
Products: M5e (and derived products), M6e
Contains the temperature of the reader radio, in degrees C.
Level 2 API 79
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.
/reader/read/asyncOnTime
Type: integer
Default value: 250
Writable: yes
Products: all
Sets the duration, in milliseconds, for the reader to be actively querying, RF On time, on the reader during background, asynchronous read operations invoked via
Reader.startReading()..
/reader/read/plan
Type: ReadPlan
Default value:
Writable: yes
Products: all
Controls the antennas, protocols, embedded tagOps and filters used for (different than and protocol for single tag operations).
SimpleReadPlan (default protocol, automatic set of antennas)
Read Methods
/reader/tagop/antenna and /reader/tagop/protocol which sets the antenna
80 Level 2 API
/reader/region
/reader/region/id
Type: Reader.Region
Configuring Readers
Default value: Specified in
Writable: yes
Products: all
Controls the
Region of Operation for the device. It may not be settable on all device types.
Reader Object create() method.
/reader/region/supportedRegions
Type: Reader.Region[]
Writable: no
Products: all
List of supported regions for the connected device.
/reader/region/hopTable
Type: Array of integer
Default value: From reader
Writable: yes
Products: M5e/M5e-C (and derivative products), M6e
Controls the frequencies used by the reader. The entries are frequencies for the reader to use, in kHz. Allowed frequencies will be limited by the device in use and the
region/id setting.
Level 2 API 81
/reader/
/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
Configuring Readers
Products: M5e (and derived products)
Enables/disables LBT in the region specified. Note: Not all regions support LBT.
/reader/status
/reader/status/antennaEnable
Type: boolean
Writable: yes
Default value: false
Products: M6e
Enables/disables the antenna field in
StatusListener reports.
82 Level 2 API
/reader/status/frequencyEnable
Type: boolean
Writable: yes
Default value: false
Products: M6e
Configuring Readers
Enables/disables the frequency field in
/reader/status/temperatureEnable
Type: boolean
Writable: yes
Default value: false
Products: M6e
Enables/disables the temperature field in
/reader/tagReadData
/reader/tagReadData/recordHighestRssi
Type: boolean
Default value: From reader
Writable: yes
StatusListener reports.
StatusListener reports.
Products: M5e (and derived products), M6e, M6
Controls whether to discard previous, lower Return Signal Strength (RSSI) values of a tag read when multiple reads of the same tag occur during a read operation. If enabled and a read occurs with a higher RSSI value all TagReadData metadata will be updated.
Level 2 API 83
/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
Configuring Readers
Products: M5e (and derived products), M6e, M6
Controls whether reads on different antennas are reported separately.
/reader/tagReadData/uniqueByData
Type: boolean
Default value: From reader
Writable: yes
Products: M5e (and derived products), M6e, M6
Controls whether reads with different data memory values are reported separately when reading tag data.
/reader/tagReadData/tagopSuccess
Type: integer
Default value: none
Writable: no
Products: M5e (and derived products), M6e, M6
Number of Embedded
TagOp Invocation operations which succeeded.
84 Level 2 API
/reader/tagReadData/tagopFailures
Type: integer
Default value: none
Writable: no
Products: M5e (and derived products), M6e, M6
Configuring Readers
Number of Embedded
TagOp Invocation operations which failed.
/reader/tagop
/reader/tagop/antenna
Type: integer
Default: First element of
Writable: yes
Products: all
Specifies the antenna used for tag operations other than reads (reads use
plan). Its value must be one of the antenna numbers reported in the /reader/antenna/ portList parameter.
/reader/tagop/protocol
Type: TagProtocol
Writable: yes
/reader/antenna/connectedPortList
/reader/read/
Products: all
Specifies the protocol used for protocols used for
Level 2 API 85
Read Methods.
Advanced Tag Operations [Deprecated]. Does not affect the
/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
Configuring Readers
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.
/reader/version/serial
Type: String
Writable: no
Products: all
Contains a serial number of the reader, the same number printed on the barcode label.
86 Level 2 API
/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
Level 2 API 87
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 commands validate their inputs to the extent necessary for communication with the reader device (for example, limiting values to the number of bits permitted in the protocol) but otherwise leave error checking to the device. Unless otherwise specified, errors returned by the device are reported via instances of 3 methods begin with “cmd”.
ReaderCodeException. All Level
If any Level 3 methods seem to be required to achieve the desired functionality we recommend you contact support@thingmagic.com to discuss before using.
!
Making use of any commands in Level 3 or below guarantees cross-prod­uct compatibility will be broken. These methods should only be used when equivalent functionality is not available in Level 1 or Level 2. Level 3 APIs are not guaranteed to be the same on different versions of the MercuryAPI.
Level 3 functionality does not support the asynchronous operations in Level 1 and Level 2. Level 3 operations are strictly synchronous, blocking method calls and cannot be performed in parallel with other threads interacting with SerialReader devices.
Level 3 API 89
CAUTION!
WARNING!
!
90 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. However, in some cases, Windows Mobile application development, for example, development requires the use of the Professional version of Visual Studio.
The following section describes some of the platform and version constraints for the various sample applications included in the MercuryAPI SDK.

.NET Development Requirements

Mercury API Library (desktop):

Visual Studio 2005 Express or better
.NET 2.0 or newer

Mercury API CE Library (embedded Compact Framework)

Visual Studio 2008 Pro
No newer versions -VS2010 no longer supports Windows CE 5 / Mobile 6
.NET 2.0 Compact Framework or newer

RFID Searchlight:

Visual Studio 2008 Pro
No newer versions -VS2010 no longer supports Windows CE 5 / Mobile 6
.NET 3.5 Compact Framework or newer
.NET Language Interface 91
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. This feature also includes a sample application developed on WinCE to demonstrate the native USB driver functionality.

WinCE Driver Installation Procedure

1. The drivers for WinCE are included under the “...\cs\Drivers” directory.
2. In the Drivers directory, there are separate sub-directories for each version of WinCE:
WinCE-5.0, WinCE-6.0 and WinCE-7.0. Under these directories, you will find usb\installer. Within this directory will be a “.sln” solution file:
USBSerCabInstaller.sln for WinCE-5.0
USBSer6.sln for WinCE-6.0
USBSer7.sln for WinCE-7.0
3. Build the solution in Visual Studio 2008 Pro. It will generate a “.CAB” of the same name in the “Debug” directory.
4. Copy the CAB file to your WinCE device and double click on it, it will install USB serial driver for your WinCE device.

WinCE Sample Application Installation Procedure

1. WinCE-ReadApp application is included in the following path “...\cs\Samples\exe”
92 .NET Language Interface
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 93
94 .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.*) in C for all the operations outlined in the API Guide, and they will be used in the same manner.
In order to best support embedded systems it avoids large memory buffers and dynamic memory allocation (where possible, interfaces are created so that if dynamic allocation is available, the user can take advantage of it without difficulty and), has several memory­saving features including the ability to build only a subset of the API (strip out unused protocols, advanced features, etc.).
The following section will provide details to help understand the unique aspects of the C interface as compared to Java and .NET, and how to build C API applications for embedded systems.
Note
Currently the C API does not support the RQLReader interface and cannot be used to control Mercury4/5 and Astra readers, only SerialReaders (M5e and M5e-C, M6e, USB, Vega) and Astra-EX/M6 v4.9.2 and later.
Note
Requires GCC v4.4.2 or newer
Note
The C API is not supported on Windows for the M6 and Astra-EX.
C Language Interface 95

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.
Types with multiple fields to set, such as TMR_ReadPlan or TMR_Filter, have constructor macros, such as TMR_RP_init_simple() to set the fields of the structure compactly and conviently

C Read Iterator

To avoid dynamically allocating large buffers, the TMR_read function doesn't automatically create a list of TMR_TagReadData. Instead, you must repeatedly call TMR_hasMoreTags(reader) and TMR_getNextTag(reader, &tagread) to extract tag reads from the module.
C Language Features
TMR_Status err = TMR_read(reader, timeout, &tagCount);
if (TMR_SUCCESS != err) { FAIL(err); }
while (TMR_SUCCESS == TMR_hasMoreTags(reader))
{TMR_TagReadData trd;
err = TMR_getNextTag(reader, &trd);
if (TMR_SUCCESS != err) { FAIL(err); }
}
If dynamic memory allocation can be used, a convenience method is provided called
TMR_readIntoArray()
TMR_TagReadData* tagReads;
TMR_Status err = TMR_read(reader, timeout, &tagCount;
if (TMR_SUCCESS != err) { FAIL(err); }
TMR_readIntoArray(reader, timeout, &tagCount, &tagReads)
while (TMR_SUCCESS == TMR_hasMoreTags(reader))
{TMR_TagReadData trd;
err = TMR_getNextTag(reader, &trd);
if (TMR_SUCCESS != err) { FAIL(err); }
}
96 C Language Interface

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. The important layer for porting purposes, when dealing with serial communications based modules, is the transport layer which handles the host/controller and reader communications. This involves sending commands to and listening for/receiving responses from the module. This layer is platform specific and is contained in the serial_transport_[posix|win32|dummy].c file.
To make the API work for your hardware architecture, you need to take the empty version of these functions in serial_transport_dummy.c and write your own Serial/UART commands (modeled after one of the prototypes provided for Windows or Posix systems) to make sure the specified arguments are passed and provide the correct returns/ exceptions.
The higher levels of encapsulation take care of encoding/decoding the reader commands. There is no need to worry about header, length, checksum, etc., simply send that array out over the serial interface and listen for the response.
For more details on building and porting the C API on different platforms, particularly Win32, see the two README files in [SDK install dir]/c, README.PORTING and README.WIN32.

C Conditional Compilation

For very storage-constrained systems, the C implementation provides compilation conditionals to selectively remove parts of the system. Edit tm_config.h to comment out the #defines of features you do not want.
For descriptions, see Mercury C API
#define TMR_ENABLE_SERIAL_READER
Language Specific Reference Guides for tm_config.h
#define TMR_ENABLE_SERIAL_TRANSPORT_NATIVE
#define TMR_MAX_SERIAL_DEVICE_NAME_LENGTH 64
C Language Interface 97
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. This is factored out into a "serial transport" layer to allow for future alternatives to the *_NATIVE interface.
TMR_ENABLE_SERIAL_TRANSPORT_NATIVE - supports standard serial ports
(both UART-based and USB - anything that goes through the OS native serial driver.)
Protocol-Specific C Compilation Options
Gen2 and iPX protocol support are included in all builds and cannot be excluded but ISO18000-6B protocol may be disabled (TMR_ENABLE_ISO180006B) when building the C API.
98 C Language Interface

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
IOS Support

Testing Environment

iPad, IOS version 7.1.4
iPad Mini, IOS version 7.1
iPhone
iPod

README File

Under the C directory, there is a text file named README.IOS. It provides information about:
IOS code organization in the MercuryAPI distribution
How to build the Mercury API for IOS
How to build and run the sample appl.ication on an IOS device
How to generate “.ipa” file and install it in IOS devices
Device Provisioning / Profile Creation
Creating a CSR Certificate
Generating a provision profile
How to obtain the UDID
C Language Interface 99
Creating an APP ID
IOS Support
100 C Language Interface
Loading...