mercury-api

Haskell binding to Mercury API for ThingMagic RFID readers.

This package is a Haskell binding to the "Mercury API" C API for ThingMagic RFID readers. It is especially geared toward the SparkFun Simultaneous RFID Reader, which uses ThingMagic's M6e Nano module, but it should work with other ThingMagic readers. (Though currently, only support for serial readers is compiled in.) Most of the function and type names are the same as their counterparts in the C API, with the TMR_ prefix dropped. For more in-depth, language-independent documentation of Mercury API, see Mercury API Programmers Guide.

Latest: Linux: Windows:

Description

This package is a Haskell binding to the Mercury API C API for ThingMagic RFID readers. It is especially geared toward the SparkFun Simultaneous RFID Reader, which uses ThingMagic's M6e Nano module, but it should work with other ThingMagic readers. (Though currently, only support for serial readers is compiled in.) Most of the function and type names are the same as their counterparts in the C API, with the TMR_ prefix dropped. For more in-depth, language-independent documentation of Mercury API, see Mercury API Programmers Guide.

This package includes a copy of the Mercury API C library, so no external libraries are necessary. Several small bug fixes have been applied to the included version of the library. (I have submitted these patches upstream, but I don't know if or when they will be included in the official version.) If you need to upgrade to a newer version of Mercury API than the included one, see UPGRADING.md.

The Haskell binding doesn't support background reads. I recommend that you just spawn a new Haskell thread and do foreground reads instead.

Currently, only support for the serial reader is compiled in, but it probably wouldn't be too hard to enable LLRP support. (I don't have any way to test LLRP, however, as the M6e Nano doesn't support it.)

On Mac OS X, be sure to use the serial device that starts with /dev/cu., not the serial device that starts with /dev/tty..

On Windows, you can type wmic path Win32_SerialPort to list the available COM ports.

Only some parameters and some tagops are currently supported in the Haskell binding. (There are a lot of them, and I only implemented the ones I needed.) If you need support for additional parameters or tagops, please file an issue in GitHub and I will add them.

I have tested this package on Linux, Mac OS X, and Windows, using the SparkFun board.

Here is a minimal example which reads tags at maximum power for 1 second, and then prints the results:

{-# LANGUAGE OverloadedStrings #-}

import qualified Data.Text.IO as T
import qualified System.Hardware.MercuryApi as TMR
import qualified System.Hardware.MercuryApi.Params as TMR

main = do
  rdr <- TMR.create "tmr:///dev/ttyUSB0"
  TMR.paramSetTransportTimeout rdr 10000
  TMR.connect rdr
  TMR.paramSetBasics rdr TMR.REGION_NA2 2700 TMR.sparkFunAntennas
  tags <- TMR.read rdr 1000
  putStrLn $ "read " ++ show (length tags) ++ " tags"
  mapM_ T.putStrLn $ concatMap TMR.displayTagReadData tags
  TMR.destroy rdr

Additional examples are available in the examples directory.

How to build

This package is mostly of interest to Haskell programmers, and if you're a Haskell programmer, you already know how to build it with stack or cabal.

However, some of the utilities like tmr-firmware might be of interest to non-Haskellers, so here is how to build them if you don't know anything about Haskell:

• Install stack.

• Clone this repository.

• Run stack --install-ghc install at the top level of the repository.

• Add ~/.local/bin to your $PATH.

Now the following utilities will be available in your $PATH:

tmr-firmware - write a new firmware image to reader

Usage: tmr-firmware [-u|--uri URI] [-t|--transport-listener] [FILENAME]
  If run without firmware file, just print current firmware version. Firmware
  file can be downloaded from:
  http://www.thingmagic.com/index.php/download-nano-firmware

Available options:
  -h,--help                Show this help text
  -u,--uri URI             Reader to connect to (default tmr:///dev/ttyUSB0)
  -t,--transport-listener  Print bytes sent on serial port


tmr-params - print parameters

Usage: tmr-params [-u|--uri URI] [-t|--transport-listener]

Available options:
  -h,--help                Show this help text
  -u,--uri URI             Reader to connect to (default tmr:///dev/ttyUSB0)
  -t,--transport-listener  Print bytes sent on serial port


tmr-read - read tags

Usage: tmr-read [-u|--uri URI] [-r|--region REGION] [-p|--power CENTI-DBM]
                [-t|--transport-listener] [-l|--long]

Available options:
  -h,--help                Show this help text
  -u,--uri URI             Reader to connect to (default tmr:///dev/ttyUSB0)
  -r,--region REGION       Regulatory region (default na2)
  -p,--power CENTI-DBM     Power level (0-2700, default 2300)
  -t,--transport-listener  Print bytes sent on serial port
  -l,--long                Print lots of information per tag


tmr-write - write a string to user data of tag

Usage: tmr-write [-u|--uri URI] [-r|--region REGION] [-p|--power CENTI-DBM]
                 [-t|--transport-listener] [-R|--rewrite] STRING

Available options:
  -h,--help                Show this help text
  -u,--uri URI             Reader to connect to (default tmr:///dev/ttyUSB0)
  -r,--region REGION       Regulatory region (default na2)
  -p,--power CENTI-DBM     Power level (0-2700, default 2300)
  -t,--transport-listener  Print bytes sent on serial port
  -R,--rewrite             Write to a tag even if written before

Resources

Additional resources:

• RFID Basics
• SparkFun Simultaneous RFID Reader hookup guide
• ThingMagic manuals and firmware

Mercury API in other languages:

• C, Java, and C# - officially supported by Mercury API
• Python binding by Petr Gotthard.