Thingmagic Mercury API v1.23.0 Manual do Utilizador

875-0049-10 RevAMercury APIProgrammer’s Guide For: Mercury API v1.23.0 and laterSupported Hardware: M6 and Astra-EX (firmware v4.19.1 and later)M6e (

10 Mercury Embedded Modules Developer’s GuideBuilding On-Reader Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IOS Support100 C Language InterfaceCreating an APP ID

Java Language Interface 101 Java Language InterfaceJNI LibraryThe java interface, when connecting to readers of type SerialReader, requires the use o

LLRP ToolKit (LTK) Support102 Java Language InterfaceLLRP ToolKit (LTK) SupportThe MercuryAPI SDK provides a full LTKJava distribution which includes

Required Windows Runtime LibrariesJava Language Interface 103Required Windows Runtime LibrariesIn order to run the Java APIs, more specifically the JN

Android Support104 Java Language InterfaceAndroid SupportThe MercuryAPI SDK includes a sample Android application that can connect to serial readers o

Advanced Customization 105 Advanced CustomizationCustom Serial Transport NamingStarting with version 1.23.0 of the MercuryAPI SDK, users can write th

Custom Serial Transport Naming106 Advanced CustomizationCall the factory function with the already-parsed URI (e.g., Reader rdr = CreateSerialReader

Custom Serial Transport NamingAdvanced Customization 107Changes Required for C#/.NETStarting with version 1.23.0 of the MercuryAPI SDK, we have added

Custom Serial Transport Naming108 Advanced CustomizationExampleIn MercuryAPI, we have added support for a TCP serial bridge. The TCP serial bridge all

Custom Serial Transport NamingAdvanced Customization 109Changes Required for CStarting with version 1.23.0 of the MercuryAPI SDK, we have added a seri

Introduction to the MercuryAPI 11 Introduction to the MercuryAPIThe MercuryAPI is intended to provide a common programming interface to all ThingMagi

Custom Serial Transport Naming110 Advanced CustomizationExample:In MercuryAPI we have added support for a TCP serial bridge. The TCP serial bridge all

Custom Serial Transport NamingAdvanced Customization 111Changes Required for JavaStarting with version 1.23.0 of the MercuryAPI SDK, we have added a s

Custom Serial Transport Naming112 Advanced CustomizationExampleIn MercuryAPI we have added support for a TCP serial bridge. The TCP serial bridge allo

On Reader Applications 113 On Reader ApplicationsThe M6 Reader, starting with firmware v4.9.2 and MercuryAPI v1.11.1, supports running custom applica

Building On-Reader Applications114 On Reader ApplicationsBuilding On-Reader ApplicationsRequirementsThe following items are needed to run APIs on the

Building On-Reader ApplicationsOn Reader Applications 115Installing the Cross Compiler EnvironmentPrecompiled Linux binaries for the cross compiler ar

Building On-Reader Applications116 On Reader ApplicationsTroubleshootingThe build process for on-reader applications requires some Linux utilities tha

Building On-Reader ApplicationsOn Reader Applications 117Running an On-Reader ApplicationOnce the binary is installed on the Reader it can be executed

Building On-Reader Applications118 On Reader Applicationsgetty:unknown:/sbin/getty 115200 /dev/ttyS1snmpd:unknown:/bin/run_snmp.shupdate_passwd:unknow

Building On-Reader ApplicationsOn Reader Applications 119Saving the Program to the JFFS2 File SystemThe root MercuryOS filesystem runs out of a ramdis

12 Introduction to the MercuryAPIC#/.NET - [SDK Install Dir]/cs/MercuryAPIHelp/index.htmlC - [SDK Install Dir]/c/doc/index.htmlNoteAll code exampl

Building On-Reader Applications120 On Reader Applications

Performance Tuning 121 Performance TuningThe following sections describe how to enhance or tailor the reader’s settings to fit your unique RFID envir

How UHF RFID Works (Gen2)122 Performance TuningHow UHF RFID Works (Gen2)At its most basic level, the reader powers up the tag at the same time it is c

How UHF RFID Works (Gen2)Performance Tuning 123Transmit Power/reader/radio/readPower/reader/radio/writePowerAlthough not directly related to Gen2 sett

How UHF RFID Works (Gen2)124 Performance Tuningchannels, but in the EU region where there are only 4 channels, this could become an issue. In this cas

How UHF RFID Works (Gen2)Performance Tuning 125/reader/gen2/targetThe remaining Gen2 settings control how soon, and how often, a tag responds to a rea

How UHF RFID Works (Gen2)126 Performance TuningSession “0”: Prepare to respond again as soon as RF power dropsSession “1”: Prepare to respond agai

Optimizing Gen2 settingsPerformance Tuning 127Optimizing Gen2 settingsIf the previous information on Gen2 settings is new to you, the task of optimizi

Optimizing Gen2 settings128 Performance Tuning

Supported Languages and EnvironmentsIntroduction to the MercuryAPI 13Supported Languages and EnvironmentsThe MercuryAPI is currently written in Java,

Supported Languages and Environments14 Introduction to the MercuryAPIOn Reader Applications - Describes how to build and install C language applicat

Example CodeIntroduction to the MercuryAPI 15Example CodeIn addition to using this guide, there are several example application and code samples that

Hardware Specific Guides16 Introduction to the MercuryAPIHardware Specific GuidesThe MercuryAPI is intended to allow cross-product development. Howeve

Hardware AbstractionIntroduction to the MercuryAPI 17Hardware AbstractionThe MercuryAPI is intended to allow cross-product development. The same appli

ThingMagic Mercury API Software License18 Introduction to the MercuryAPIThingMagic Mercury API Software LicenseCopyright (c) 2009 - 2014 Trimble Navig

Level 1 API 19 Level 1 APIThe objects and methods described in this section provide basic reader operations and are hardware and implementation indep

Government Limited Rights Notice: All documentation and manualswere developed at private expense and no part of it was developed usingGovernment funds

Connecting to Readers20 Level 1 APIConnecting to ReadersReader ObjectCreateThe operations of the MercuryAPI are centered around a single object that r

Connecting to ReadersLevel 1 API 21– Astra-EXConnectThe communication channel is not established until the connect() method is called. Calling:void

Connecting to Readers22 Level 1 APIDestroyWhen the user is done with the Reader, Reader.destroy() should be called to release resources that the API h

Connecting to ReadersLevel 1 API 23URI ExamplesPlease note the specific format of the URI path will depend on the OS and drivers being used. The follo

Connecting to Readers24 Level 1 APIReader.Region.NA (North America/FCC)Reader.Region.EU3 (European Union/ETSI Revised EN 302 208)Reader.Region.K

Reading Tags - The BasicsLevel 1 API 25Reading Tags - The BasicsRead MethodsReader Object provides multiple ways of reading/inventorying tags. The tag

Reading Tags - The Basics26 Level 1 APIduration - The number of milliseconds to read for. In general, especially with readers of type SerialReader,

Reading Tags - The BasicsLevel 1 API 27NoteThe C# version of this API uses the native delegate/event mechanism with delegates called TagReadHandler an

Reading Tags - The Basics28 Level 1 APIN <= 2QFor example, if return on N tags is 3, then optimal Q is 2, but there is a chance that module may fin

Reading Tags - The BasicsLevel 1 API 29void tagReadException(Reader r, ReaderException re)This method is called for any Exceptions that occurs during

3Revision TableDate Version Description6/2009 01 Rev1 First Draft for MercuryAPI RC18/2009 01 Rev1 Updates to Reader methods for changes in v1.1update

Tags30 Level 1 APITagsTagReadDataAn object of the TagReadData class contains the metadata (see the Hardware Specific Guides for details on available t

Writing To TagsLevel 1 API 31Writing To TagsWrite operations should be performed using the functionality described in the Advanced Tag Operations sect

Status Reporting32 Level 1 APIStatus ReportingStatus information about the reader and the environment the reader is operating in is available both whi

ExceptionsLevel 1 API 33ExceptionsIn the event of an error, methods of this interface may throw a ReaderException, which will contain a string describ

Exceptions34 Level 1 APIform and should be provided immediately to ThingMagic Support along with the code which caused the ReaderFatalException.Featur

Level 2 API 35 Level 2 APIThe objects and methods described in this section provide a more complete set of reader operations, including more complex

Advanced Reading36 Level 2 APIAdvanced ReadingReadPlanAn object of class ReadPlan specifies the antennas, protocol and filters to use for a search (Re

Advanced ReadingLevel 2 API 37data read will be stored in the resulting TagReadData Data field.int weight - default value is 1000. See MultiReadPlan

Advanced Reading38 Level 2 APIIn-Module Multi-Protocol ReadM6e OnlyThe M6e supports reader-scheduled, multi-protocol reads This allows you to specify

Selecting Specific TagsLevel 2 API 39Selecting Specific TagsTagFilter InterfaceTagFilter is an interface type that represents tag read filtering opera

48/2012 08 RevA • Added details on C porting• Added details about transportTimeout to Connect info• Removed Select/Filter limitation when Continuou

Selecting Specific Tags40 Level 2 APINoteCurrently, the sequence in which the TagFilters are applied is not guaranteed.Gen2.SelectThe Gen2.Select clas

Selecting Specific TagsLevel 2 API 41Tag ProtocolThe TagProtocol enumeration represents RFID protocols. It is used in many places where a protocol is

Advanced Tag Operations42 Level 2 APIAdvanced Tag OperationsNoteThese new TagOp data structures replace the older individual Advanced Tag Operations [

Advanced Tag OperationsLevel 2 API 43The /reader/tagop/protocol parameter selects the RFID Tag Protocol to use and can affect the semantics of the c

Advanced Tag Operations44 Level 2 APIReader.read() -Counters resets to 0 at beginning of call and accumulates values until call completes.Reader.s

Advanced Tag OperationsLevel 2 API 45Gen2.WriteDataWrites the specified data to the tag memory location specified by the Memory Bank and location para

Advanced Tag Operations46 Level 2 APIGen2.LockAction.KILL_PERMALOCK Gen2.LockAction.KILL_PERMAUNLOCKGen2.LockAction.ACCESS_LOCK Gen2.LockActio

Advanced Tag OperationsLevel 2 API 47Gen2.LockAction(int mask, int action)to create a Gen2.LockAction object with the specified mask and action.The fo

Advanced Tag Operations48 Level 2 APIBlockWrites. This means that in order to write more than 2 words multiple calls must be made.Gen2.BlockWrite can

Advanced Tag OperationsLevel 2 API 49Gen2.Alien.Higgs3.LoadImageThis command writes Reserved, EPC and User Memory to the Higgs3 tags in a single comma

Mercury Embedded Modules Developer’s Guide 5 ContentsIntroduction to the MercuryAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Advanced Tag Operations50 Level 2 APIGen2.NXP.G2I.EasAlarm and Gen2.NXP.G2X.EasAlarmsets or resets the EAS system bit. When set, the tag will return a

Advanced Tag OperationsLevel 2 API 51Gen2.Impinj.Monza4.QTReadWriteControls the switching of Monza 4QT between the Private and Public profiles. The ta

Advanced Tag Operations52 Level 2 APIGen2.IDS.SL900A.GetMeasurementSetupThe GET MEASUREMENT SETUP command will read the current system setup of the ch

Advanced Tag OperationsLevel 2 API 53Gen2.IDS.SL900A.SetPasswordThe SET PASSWORD command writes a 32-bit password to the EEPROM. The password protecti

Advanced Tag Operations54 Level 2 APIIso180006b.LockSends a command to a tag to lock segments of tag memory. The lock operation to perform is represen

Advanced Tag Operations [Deprecated]Level 2 API 55Advanced Tag Operations [Deprecated]CAUTION!!!The following individual tag operation methods are bei

Advanced Tag Operations [Deprecated]56 Level 2 APIreadTagMemWords()short[] readTagMemWords(TagFilter filter, int bank, int address, int length)writeTa

Antenna UsageLevel 2 API 57Antenna UsageAutomatic Antenna SwitchingOnly one antenna can be active at a time, when multiple antennas are specified they

Antenna Usage58 Level 2 APIexample, if the reader is identified as a Vega, the settings define in Vega Reader Example which previously had to be manua

GPIO SupportLevel 2 API 59GPIO SupportGet/Set ValueReader.GpioPin[] gpiGet()void gpoSet(Reader.GpioPin[] state)If the reader device supports GPIO pins

6 Mercury Embedded Modules Developer’s GuideStatusListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Firmware Updates60 Level 2 APIFirmware Updatesvoid firmwareLoad(java.io.InputStream firmware)The firmwareLoad() method attempts to install firmware on

Rebooting ReadersLevel 2 API 61Rebooting Readersvoid reboot()The reboot() method reboots the reader or module.NoteThe Reboot method is not supported o

Protocol License Keys62 Level 2 APIProtocol License KeysM6e OnlyThe M6e has the ability to support multiple protocols. The basic M6e supports Gen2 (IS

Debug LoggingLevel 2 API 63Debug LoggingTransportListener InterfaceThe TransportListener interface provides a method of snooping on raw, transport-lay

Configuring Readers64 Level 2 APIConfiguring ReadersReader Configuration MethodsEach Reader Object has a set of named parameters which provide device

Configuring ReadersLevel 2 API 65/reader/baudRateFuture firmware upgrades will support saving other configuration values. To Save a configuration, s

Configuring Readers66 Level 2 APIM5e Notes - The module always boots into 9600 baud resulting in a connection delay due to the first attempt of conn

Configuring ReadersLevel 2 API 67/reader/powerModeType: SerialReader.PowerModeDefault value: From readerWritable: yesProducts: M5e (and derived produc

Configuring Readers68 Level 2 API/reader/uriType: StringDefault value: From readerWritable: noProducts: allGets the URI string used to connect to the

Configuring ReadersLevel 2 API 69/reader/antenna/connectedPortListType: Array of integersWritable: noProducts: M5e, M6e, M6Contains the numbers of the

Mercury Embedded Modules Developer’s Guide 7Gen2 Tag Specific TagOps - NXP G2* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Configuring Readers70 Level 2 API(NOTE: the settlingTime is associated with the TX port, the paired RX port is not relevant), and the second element i

Configuring ReadersLevel 2 API 71/reader/gen2/accessPasswordType: Gen2.PasswordDefault value: 0Writable: yesProducts: allThe Gen2 access password that

Configuring Readers72 Level 2 API/reader/gen2/BLFType: IntegerDefault value: 250Writable: yesProducts: M6e, M6Sets the Gen2 backscatter link frequency

Configuring ReadersLevel 2 API 73/reader/gen2/millerm [Deprecated]Type:Gen2.MillerMDefault value: Gen2.MillerM.M4Writable: yesProducts: M5e (and deriv

Configuring Readers74 Level 2 API/reader/gen2/targetType: Gen2.TargetDefault value: Gen2.Target.AWritable: yesProducts: allControls the target algorit

Configuring ReadersLevel 2 API 75– Min. timeout = 1000us./reader/gen2/writeEarlyExitType: BooleanDefault value: TrueWritable: yesProducts: M5e, M6eT

Configuring Readers76 Level 2 APIM6e - Set to an array of ints (1 through 4) to configure GPIO lines as outputs./reader/iso18000-6b/reader/iso18000-

Configuring ReadersLevel 2 API 77/reader/iso18000-6b/delimiterType: Iso18000-6b.DelimiterDefault value: DELIMITER4Writable: yesProducts: M6eISO18000-6

Configuring Readers78 Level 2 API/reader/radio/powerMaxType: integerWritable: noProducts: allMaximum value that the reader accepts for transmit power.

Configuring ReadersLevel 2 API 79will use the global write power level: /reader/radio/writePower)/reader/radio/readPowerType: integerDefault value: Fr

8 Mercury Embedded Modules Developer’s GuideAutomatic Antenna Switching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Configuring Readers80 Level 2 API/reader/read/reader/read/asyncOffTimeType: integerDefault value: 0Writable: yesProducts: allThe duration, in millisec

Configuring ReadersLevel 2 API 81/reader/region/reader/region/idType: Reader.RegionDefault value: Specified in Reader Object create() method.Writable:

Configuring Readers82 Level 2 API/reader/region/hopTimeType: integerDefault value: From readerWritable: yesProducts: M5e (and derived products), M6eCo

Configuring ReadersLevel 2 API 83/reader/status/frequencyEnableType: booleanWritable: yesDefault value: falseProducts: M6eEnables/disables the frequen

Configuring Readers84 Level 2 API/reader/tagReadData/reportRssiInDbmType: booleanDefault value: From readerWritable: yesProducts: allThis is the setti

Configuring ReadersLevel 2 API 85/reader/tagReadData/tagopFailuresType: integerDefault value: noneWritable: noProducts: M5e (and derived products), M6

Configuring Readers86 Level 2 API/reader/version/reader/version/hardwareType: StringWritable: noProducts: allContains a version identifier for the rea

Configuring ReadersLevel 2 API 87/reader/version/softwareType: StringWritable: noProducts: allContains a version identifier for the reader’s software.

Configuring Readers88 Level 2 API

Level 3 API 89 Level 3 APIThe Level 3 API provides per-command access to the individual elements of the underlying device control protocol. Level 3 i

Mercury Embedded Modules Developer’s Guide 9Universal Reader Assistant 2.0 92USB Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

90 Level 3 API

.NET Language Interface 91 .NET Language InterfaceThe .NET interface provides an API supporting the primary Windows development platform. Depending o

92 .NET Language InterfaceWindows Mobile 6 Professional SDKUniversal Reader Assistant 1.0Visual Studio 2008 Express or better.NET 2.0 or newerUn

.NET Language Interface 932. Locate the WinceReadApp.CAB file .3. Copy this CAB file into your WinCE device. By double clicking it, you will ins

94 .NET Language Interface

C Language Interface 95 C Language InterfaceThe C language interface is designed primarily to provide support for embedded systems. The structure of

C Language Features96 C Language InterfaceC Language FeaturesFor clarity of definition, C99 datatypes (bool, uintN_t) are used. If these types are no

Build ConsiderationsC Language Interface 97Build ConsiderationsThe full source code of the C API is provided. The API source code includes sample buil

Build Considerations98 C Language Interface#define TMR_ENABLE_SERIAL_TRANSPORT_LLRP //not currently supported#define TMR_ENABLE_ISO180006B#define TMR_

IOS SupportC Language Interface 99IOS SupportThe MercuryAPI C API includes a sample IOS application that can connect to serial readers through a seria