Loading...
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 crosscompiler 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
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
Introduction to the MercuryAPI |
15 |
Hardware Specific Guides
Hardware Specific Guides
The MercuryAPI is intended to allow cross-product development. However, due to differences in product features and functionality, 100% compatibility is not possible and specific feature differences are not all clearly described in this Guide. It is important to read the product specific hardware guide to fully understand the features and functionality available for each product. Product hardware guides are available on the ThingMagic website rfid.thingmagic.com/devkit.
16 |
Introduction to the MercuryAPI |
Hardware Abstraction
Hardware Abstraction
The MercuryAPI is intended to allow cross-product development. The same application can be used to connect, configure and control any ThingMagic product. However, due to differences in product features and functionality, 100% compatibility would not be possible without limiting the capabilities of the API. 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.
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.
! |
C A U T I O N ! |
! |
|
|
|
Every level implicitly provides support for multiple tag protocols, including Gen2/ISO18000-6c and ISO18000-6b, even though not all products 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
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 URI Syntax of the uriString parameter. There are currently two subclasses of Reader:
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 Region of Operation, /reader/region/id, to be set using 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.
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 Reader 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 Region of Operation should 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.
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 SerialReader type device via a TCP bridge.
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 LLRPReader on port 5084, if no response then it will try to connect to an RqlReader on port 8080.
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 Reader Configuration Parameters under /reader/region/supportedRegions. Please refer to the specific device’s User Guide for more information on supported regions.
24 |
Level 1 API |
Reading Tags - The Basics
Reading Tags - The Basics
Read Methods
Reader Object provides multiple ways of reading/inventorying tags. The tag reading methods:
Reader.read()
Reader.startReading()
issue one or more search commands to the device to satisfy the user’s request for searches of a particular duration, duty cycle, antennas, and protocols.
The result of a read operation is a collection of TagReadData objects, which provides 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. Level 2 API can be used for advanced control over read behavior, such as setting antennas (see Antenna Usage for more details), protocols and filtering criteria used for the search. These are controlled by the ReadPlan object assigned to the / reader/read/plan parameter of the Reader Configuration Parameters.
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 SerialReader, the duration should be kept short (a few seconds) to avoid filling up the tag buffer. Maximum value is 65535 (65 seconds).
It performs the operation synchronously, and then returns an array of TagReadData objects resulting from the search. If no tags were found then the array will be empty; this is not an error condition.
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 deduplication 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 TagReadData instance will not be created for each. The reader specific hardware guide should be referenced for information on the size of the Tag Buffer.
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 ReadListener interface; each listener registered with the addReadListener() method is called with a TagReadData 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.
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 pseudoasynchronous 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 /reader/read/asyncOffTime is set to zero. In this mode tags are streamed to the host processor as they are read.
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 StopTriggerReadPlan with the desired number of tags and setting it as the active /reader/read/plan.
For optimum performance it is recommended to use a StaticQ setting for /reader/gen2/q appropriate for the specified value of N, where:
Level 1 API |
27 |
Reading Tags - The Basics
N <= 2Q
For example, if return on N tags is 3, then optimal Q is 2, but there is a chance that module may find and report 4 tags.
See sample codelets in the SDK.
Note
Not currently supported with Continuous Reading.
Reading Tag Memory
Additional methods for reading individual tags are available in the Level 2 API.
ReadListener
Classes that implement the ReadListener interface may be used as listeners (callbacks) for background reads. 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.
! |
C A U T I O N ! |
! |
|
|
|
When performing asynchronous read operations the reader is operating in a continuous or pseudo-continuous read mode. During this mode performing 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.
Use Embedded TagOp Invocation in order to perform an operation on every tag found, or perform Reader.read() and iterate through the tags found, performing 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
Tags
TagReadData
An object of the TagReadData class contains the metadata (see the Hardware Specific Guides for details on available tag read metadata for each product) about the tag read as well as the TagData object representing the particular tag.
TagReadData (or arrays of) objects are the primary results of Read Methods, one for each tag found.
The actual EPC ID for a Tag can be found by calling the getTag() method which returns a TagData object.
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.
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 TagReadData object) and for representing data to be written to tag(s) in the field using Gen2.WriteTag. In addition, the TagData class implements the TagFilter 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.
See the methods available for getting TagData and metadata from TagReadData in the language specific API Reference.
30 |
Level 1 API |
Loading...