Python wrapper for the ThingMagic Mercury API
C Python Makefile
Switch branches/tags
Nothing to show
Clone or download
Carbaz and gotthardp Added Power control functionality and some data getters. (#22)
* Added write method. Based on deprecated TMR_writeTag.
* Updated Gitignore.
* Fixed return value to Python boolean.
* Cleaning bracers on one line IF
* WIP: Adding Reader_set_read_powers function.
* Added get antenna list method.
* Vars renamed
* Added get power range method.
* Added get setted read powers method.
* Updated documentation.
Latest commit 7cb8c42 Apr 23, 2018

Python wrapper for the ThingMagic Mercury API

The ThingMagic Mercury API is used to discover, provision and control ThingMagic RFID readers.

Reading RFID tags is as simple as this:

import mercury
reader = mercury.Reader("tmr:///dev/ttyUSB0")

reader.set_read_plan([1], "GEN2")


Import the module mercury and create an mercury.Reader object.

import mercury

Reader Object

Represents a connection to the reader.

mercury.Reader(uri, baudrate=115200)

Object constructor. Connects to the reader:

  • uri identifies the device communication channel:
    • "tmr:///com2" is a typical format to connect to a serial based module on Windows COM2
    • "tmr:///dev/ttyUSB0" is a typical format to connect to a USB device named ttyUSB0 on a Unix system
    • "llrp://" is a typical format to connect to an Ethernet device (works on Linux only)
  • baudrate defines the desired communication speed. Supported values include 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600 and 115200 (default).

For example:

reader = mercury.Reader("tmr:///dev/ttyUSB0", baudrate=9600)


Lists supported regions for the connected device.

For example:

['NA2', 'IN', 'JP', 'PRC', 'EU3', 'KR2', 'AU', 'NZ']


Lists supported radio power range, in centidBm.

For example:

(0, 3000)


Lists available antennas.

For example:

[1, 2]


Lists configured read powers for each antenna. [(antenna, power)]

For example:

[(1, 1800), (2, 3000)]


Controls the Region of Operation for the connected device:

  • region represents the regulatory region that the device will operate in. Supported values are:
    • "NA", North America/FCC
    • "NA2"
    • "NA3"
    • "EU", European Union/ETSI EN 302 208
    • "EU2", European Union/ETSI EN 300 220
    • "EU3", European Union/ETSI Revised EN 302 208
    • "IS", Israel
    • "IN", India
    • "JP", Japan
    • "KR", Korea MIC
    • "KR2", Korea KCC
    • "PRC", China
    • "PRC2"
    • "AU", Australia/AIDA LIPD Variation 2011
    • "NZ", New Zealand

For example:


reader.set_read_plan(antennas, protocol, read_power=default)

Specifies the antennas and protocol to use for a search:

  • antennas list define which antennas (or virtual antenna numbers) to use in the search
  • protocol defines the protocol to search on. Supported values are:
    • "GEN2", UPC GEN2
    • "ISO180006B", ISO 180006B
    • "UCODE", ISO 180006B UCODE
    • "IPX64", IPX (64kbps link rate)
    • "IPX256", IPX (256kbps link rate)
    • "ATA"
  • read_power defines the transmit power, in centidBm, for read operations. If not given, a reader specific default value is used.

For example:

reader.set_read_plan([1], "GEN2")

reader.set_read_powers(antennas, powers)

Set the read power for each listed antenna and return the real setted values. Setted values may differ from those passed due to reader rounding.

  • antennas list define which antennas (or virtual antenna numbers) are going to be setted.
  • powers list define the power, in centidBm, for each antenna. Overrides the value from set_read_plan or reader specific default.
    • Power values must be within the allowed power range.

For example:

setted_powers = reader.set_read_powers([1, 2], [1533, 1912])
[(1, 1525), (2, 1900)]

Performs a synchronous read, and then returns a list of TagReadData objects resulting from the search. If no tags were found then the list will be empty.

  • timeout sets the reading time

For example:

[b'E2002047381502180820C296', b'0000000000000000C0002403']

reader.write(epc_target, epc_code)

Performs a synchronous write and then returns a boolean indicating the success of the operation.

For example:

old_epc = 'E2002047381502180820C296'
new_epc = 'E20020470000000000000012'

reader = Reader('llrp://')
reader.set_read_plan([1], "GEN2")

if reader.write(epc_target=old_epc, epc_code=new_epc):
    print('Rewrited "{}" with "{}"'.format(old_epc, new_epc))
    print('Failed writing "{}" with "{}"'.format(old_epc, new_epc))

reader.start_reading(callback, on_time=250, off_time=0)

Starts asynchronous reading. It returns immediately and begins a sequence of reads or a continuous read. The results are passed to the callback. The reads are repeated until the reader.stop_reading() method is called

  • callback(TagReadData) will be invoked for every tag detected
  • on_time sets the duration, in milliseconds, for the reader to be actively querying
  • off_time duration, in milliseconds, for the reader to be quiet while querying

For example:

reader.start_reading(lambda tag: print(tag.epc))


Stops the asynchronous reading started by reader.start_reading().

For example:



Returns a model identifier for the connected reader hardware.

For example:

M6e Nano

TagReadData Object

Represents a read of an RFID tag:

  • epc corresponds to the Electronic Product Code
  • antenna indicates where the tag was read
  • read_count indicates how many times was the tag read during interrogation
  • rssi is the strength of the signal recieved from the tag

The string representation (repr) of the tag data is its EPC.



Use the Windows installer for the latest release and Python 3.6.

To build an installer for other Python releases you need to:

  • Download the latest Mercury API, e.g.
  • Open mercuryapi- and comment (or delete) the block of typedef for int_fast8_t through uint_fast64_t (8 lines)
  • Download latest pthreads-win32 binaries (.dll and .lib) for your architecture
  • Obtain Microsoft Visual Studio 2017, including the Python extensions
  • Open the Solution and review the
    • Verify the mercuryapi directory
    • Set library_dirs and data_files to the pthreads-win32 you downloaded
    • Set Script Arguments to bdist_wininst -p win32 (default) or bdist_wininst -p amd64
  • Start (without debugging)


First, make sure you have the required packages

yum install patch libxslt gcc readline-devel python-devel


apt-get install patch xsltproc gcc libreadline-dev python-dev

Both Python 2.x and Python 3.x are supported. To use the Python 3.x you may need to install the python3-dev[evel] instead of the python-dev[evel] packages.

Build the module simply by running

cd python-mercuryapi

This will download and build the Mercury API SDK and then it will build the Python module itself.

The make command will automatically determine which Python version is installed. If both 2.x and 3.x are installed, the 3.x takes precedence. To build and install 2.x you need to explicitly specify the Python interpreter to use:

sudo make PYTHON=python

Then, install the module by running

sudo make install

which is a shortcut to running

sudo python install

To access ports like /dev/ttyUSB0 as a non-root user you may need to add this user to the dialout group:

sudo usermod -a -G dialout $USER