# tm_reader.h File Reference

Mercury API Reader Interface. More...

`#include "tm_config.h"`
`#include "tmr_types.h"`
`#include "tmr_status.h"`
`#include "tmr_gpio.h"`
`#include "tmr_params.h"`
`#include "tmr_read_plan.h"`
`#include "tmr_tag_auth.h"`
`#include "tmr_tag_data.h"`
`#include "tmr_tag_lock_action.h"`
`#include "tmr_tag_protocol.h"`
`#include "tmr_tagop.h"`
`#include "tmr_serial_reader.h"`

## Classes

struct | TMR_StatsPerAntennaValues
struct | TMR_StatsPerAntennaValuesList
struct | TMR_Reader_StatsValues
struct | TMR_ReadListenerBlock
struct | TMR_AuthReqListenerBlock
struct | TMR_ReadExceptionListenerBlock
struct | TMR_TransportListenerBlock
struct | TMR_StatsListenerBlock
struct | TMR_StatusListenerBlock
struct | TMR_Queue_tagReads
struct | TMR_LicenseOperation
struct | TMR_Reader
struct | TMR_memoryCookie

## Defines

#define | TMR_connect(reader) ((reader)->connect(reader))

## Typedefs

typedef struct TMR_Reader | TMR_Reader
typedef enum TMR_Reader_StatsFlag | TMR_Reader_StatsFlag
typedef struct TMR_StatsPerAntennaValues | TMR_StatsPerAntennaValues
typedef struct TMR_StatsPerAntennaValuesList | TMR_StatsPerAntennaValuesList
typedef struct TMR_Reader_StatsValues | TMR_Reader_StatsValues
typedef void(* | TMR_ReadListener )(TMR_Reader *reader, const TMR_TagReadData *t, void *cookie)
typedef struct TMR_ReadListenerBlock | TMR_ReadListenerBlock
typedef void(* | TMR_AuthReqListener )(TMR_Reader *reader, const TMR_TagReadData *trd, void *cookie, TMR_TagAuthentication *auth)
typedef struct TMR_AuthReqListenerBlock | TMR_AuthReqListenerBlock
typedef void(* | TMR_ReadExceptionListener )(TMR_Reader *reader, TMR_Status error, void *cookie)
typedef struct TMR_ReadExceptionListenerBlock | TMR_ReadExceptionListenerBlock
typedef void(* | TMR_TransportListener )(bool tx, uint32_t dataLen, const uint8_t data[], uint32_t timeout, void *cookie)
typedef struct TMR_TransportListenerBlock | TMR_TransportListenerBlock
typedef void(* | TMR_StatsListener )(TMR_Reader *reader, const TMR_Reader_StatsValues *value, void *cookie)
typedef struct TMR_StatsListenerBlock | TMR_StatsListenerBlock
typedef struct TMR_StatusListenerBlock | TMR_StatusListenerBlock
typedef struct TMR_Queue_tagReads | TMR_Queue_tagReads
typedef enum TMR_LicenseOption | TMR_LicenseOption
typedef struct TMR_LicenseOperation | TMR_LicenseOperation
typedef struct TMR_memoryCookie | TMR_memoryCookie

## Enumerations

enum | TMR_Reader_StatsFlag { , TMR_READER_STATS_FLAG_RF_ON_TIME = (1 << 0), TMR_READER_STATS_FLAG_NOISE_FLOOR_SEARCH_RX_TX_WITH_TX_ON = (1 << 6), TMR_READER_STATS_FLAG_FREQUENCY = (1 << 7), TMR_READER_STATS_FLAG_TEMPERATURE = (1 << 8), TMR_READER_STATS_FLAG_ANTENNA_PORTS = (1 << 9), TMR_READER_STATS_FLAG_PROTOCOL = (1 << 10), TMR_READER_STATS_FLAG_CONNECTED_ANTENNAS = (1 << 11) }
enum | TMR_LicenseOption { TMR_SET_LICENSE_KEY = 0x01, TMR_ERASE_LICENSE_KEY = 0x02 }

## Functions

TMR_Status | TMR_create (TMR_Reader *reader, const char *deviceUri)
TMR_Status | TMR_create_alloc (TMR_Reader **readerPointer, const char *deviceUri)
TMR_Status | TMR_connect (struct TMR_Reader *reader)
TMR_Status | TMR_destroy (TMR_Reader *reader)
TMR_Status | TMR_read (TMR_Reader *reader, uint32_t timeoutMs, int32_t *tagCount)
TMR_Status | TMR_hasMoreTags (TMR_Reader *reader)
TMR_Status | TMR_getNextTag (TMR_Reader *reader, TMR_TagReadData *tagData)
TMR_Status | TMR_executeTagOp (struct TMR_Reader *reader, TMR_TagOp *tagop, TMR_TagFilter *filter, TMR_uint8List *data)
TMR_Status | TMR_readIntoArray (struct TMR_Reader *reader, uint32_t timeoutMs, int32_t *tagCount, TMR_TagReadData *result[])
TMR_Status | TMR_writeTag (TMR_Reader *reader, const TMR_TagFilter *target, TMR_TagData *data)
TMR_Status | TMR_killTag (TMR_Reader *reader, TMR_TagFilter *target, TMR_TagAuthentication *auth)
TMR_Status | TMR_lockTag (TMR_Reader *reader, TMR_TagFilter *target, TMR_TagLockAction *action)
TMR_Status | TMR_readTagMemBytes (TMR_Reader *reader, TMR_TagFilter *target, uint32_t bank, uint32_t byteAddress, uint16_t byteCount, uint8_t data[])
TMR_Status | TMR_readTagMemWords (TMR_Reader *reader, TMR_TagFilter *target, uint32_t bank, uint32_t wordAddress, uint16_t wordCount, uint16_t data[])
TMR_Status | TMR_writeTagMemBytes (TMR_Reader *reader, TMR_TagFilter *target, uint32_t bank, uint32_t byteAddress, uint16_t byteCount, const uint8_t data[])
TMR_Status | TMR_writeTagMemWords (TMR_Reader *reader, TMR_TagFilter *target, uint32_t bank, uint32_t wordAddress, uint16_t wordCount, const uint16_t data[])
TMR_Status | TMR_gpoSet (TMR_Reader *reader, uint8_t count, const TMR_GpioPin state[])
TMR_Status | TMR_gpiGet (TMR_Reader *reader, uint8_t *count, TMR_GpioPin state[])
TMR_Status | TMR_firmwareLoad (TMR_Reader *reader, void *cookie, TMR_FirmwareDataProvider provider)
bool | TMR_memoryProvider (void *cookie, uint16_t *size, uint8_t *data)
bool | TMR_fileProvider (void *cookie, uint16_t *size, uint8_t *data)
TMR_Status | TMR_paramSet (struct TMR_Reader *reader, TMR_Param key, const void *value)
TMR_Status | TMR_paramGet (struct TMR_Reader *reader, TMR_Param key, void *value)
TMR_Status | TMR_reboot (struct TMR_Reader *reader)
TMR_Status | TMR_paramList (struct TMR_Reader *reader, TMR_Param *keys, uint32_t *len)
void | TMR_paramProbe (struct TMR_Reader *reader, TMR_Param key)
const char * | TMR_paramName (TMR_Param key)
TMR_Param | TMR_paramID (const char *name)
TMR_Status | TMR_addTransportListener (TMR_Reader *reader, TMR_TransportListenerBlock *block)
TMR_Status | TMR_removeTransportListener (TMR_Reader *reader, TMR_TransportListenerBlock *block)
TMR_Status | TMR_addReadListener (struct TMR_Reader *reader, TMR_ReadListenerBlock *block)
TMR_Status | TMR_addAuthReqListener (struct TMR_Reader *reader, TMR_AuthReqListenerBlock *block)
TMR_Status | TMR_removeReadListener (struct TMR_Reader *reader, TMR_ReadListenerBlock *block)
TMR_Status | TMR_addReadExceptionListener (struct TMR_Reader *reader, TMR_ReadExceptionListenerBlock *block)
TMR_Status | TMR_removeReadExceptionListener (struct TMR_Reader *reader, TMR_ReadExceptionListenerBlock *block)
TMR_Status | TMR_addStatusListener (struct TMR_Reader *reader, TMR_StatusListenerBlock *block)
TMR_Status | TMR_removeStatusListener (struct TMR_Reader *reader, TMR_StatusListenerBlock *block)
TMR_Status | TMR_addStatsListener (struct TMR_Reader *reader, TMR_StatsListenerBlock *block)
TMR_Status | TMR_removeStatsListener (struct TMR_Reader *reader, TMR_StatsListenerBlock *block)
TMR_Status | TMR_startReading (struct TMR_Reader *reader)
TMR_Status | TMR_stopReading (struct TMR_Reader *reader)
TMR_Status | TMR_setSerialTransport (char *scheme, TMR_TransportNativeInit nativeInit)
const char * | TMR_strerr (TMR_Reader *reader, TMR_Status status)
TMR_Status | TMR_STATS_init (TMR_Reader_StatsValues *stats)
TMR_Status | TMR_loadConfig (struct TMR_Reader *reader, char *filePath)
TMR_Status | TMR_saveConfig (struct TMR_Reader *reader, char *filePath)

## Detailed Description

Mercury API Reader Interface.

Author:
  Brian Fiegel

Date:
  4/18/2009

## Define Documentation

#define TMR_connect | ( | reader |  | ) | ((reader)->connect(reader))

The fact that these functions are implemented via macros is an implementation detail, not something for the public API documentation.

## Typedef Documentation

typedef void(* TMR_AuthReqListener)(TMR_Reader *reader, const TMR_TagReadData *trd, void *cookie, TMR_TagAuthentication *auth)

Type of functions to be registered as tagauth request callbacks

Parameters:

  | reader | Reader object
  | trd | TagReadData object
  | cookie | Arbitrary data structure to be passed to callback
  | auth | [OUTPUT] Tag authentication value to initialize based on inputs

typedef struct TMR_AuthReqListenerBlock TMR_AuthReqListenerBlock

User-allocated structure containing the callback pointer and the value to pass to that callback.

typedef struct TMR_LicenseOperation TMR_LicenseOperation

Manage License Operation structure

typedef enum TMR_LicenseOption TMR_LicenseOption

Options for license key operation

typedef struct TMR_memoryCookie TMR_memoryCookie

Cookie for state storage of a TMR_memoryProvider.

typedef struct TMR_Queue_tagReads TMR_Queue_tagReads

Private: should not be used by user level application.

typedef struct TMR_Reader TMR_Reader

TMR_ENABLE_JNI_SERIAL_READER_ONLY is used for building JNI project, and is defined from Makefile.jni

typedef enum TMR_Reader_StatsFlag TMR_Reader_StatsFlag

Reader Stats Flag Enum

typedef struct TMR_Reader_StatsValues TMR_Reader_StatsValues

This object is returned from TMR_cmdGetReaderStats

typedef void(* TMR_ReadExceptionListener)(TMR_Reader *reader, TMR_Status error, void *cookie)

Type of functions to be registered as read error callbacks

typedef struct TMR_ReadExceptionListenerBlock TMR_ReadExceptionListenerBlock

User-allocated structure containing the callback pointer and the value to pass to that callback.

typedef void(* TMR_ReadListener)(TMR_Reader *reader, const TMR_TagReadData *t, void *cookie)

Type of functions to be registered as read callbacks

typedef struct TMR_ReadListenerBlock TMR_ReadListenerBlock

User-allocated structure containing the callback pointer and the value to pass to that callback.

typedef void(* TMR_StatsListener)(TMR_Reader *reader, const TMR_Reader_StatsValues *value, void *cookie)

Type of functions to be registered as Status read callbacks

typedef struct TMR_StatsListenerBlock TMR_StatsListenerBlock

User-allocated structure containing the callback pointer and the value to pass to that callback.

typedef struct TMR_StatsPerAntennaValues TMR_StatsPerAntennaValues

Per Antenna stats

typedef struct TMR_StatsPerAntennaValuesList TMR_StatsPerAntennaValuesList

Object to hold the per antenna stats

typedef struct TMR_StatusListenerBlock TMR_StatusListenerBlock

User-allocated structure containing the callback pointer and the value to pass to that callback.

typedef void(* TMR_TransportListener)(bool tx, uint32_t dataLen, const uint8_t data[], uint32_t timeout, void *cookie)

Type of functions to be registered as transport callbacks

typedef struct TMR_TransportListenerBlock TMR_TransportListenerBlock

User-allocated structure containing the callback pointer and the value to pass to that callback.

## Enumeration Type Documentation

enum TMR_LicenseOption

Options for license key operation

Enumerator:

  TMR_SET_LICENSE_KEY | Set Valid License Key
  TMR_ERASE_LICENSE_KEY | Erase License Key

enum TMR_Reader_StatsFlag

Reader Stats Flag Enum

Enumerator:

  TMR_READER_STATS_FLAG_RF_ON_TIME | Total time the port has been transmitting, in milliseconds. Resettable
  TMR_READER_STATS_FLAG_NOISE_FLOOR_SEARCH_RX_TX_WITH_TX_ON | Noise floor with the TX on for the antennas were last configured for searching
  TMR_READER_STATS_FLAG_FREQUENCY | Current frequency in units of Khz
  TMR_READER_STATS_FLAG_TEMPERATURE | Current temperature of the device in units of Celsius
  TMR_READER_STATS_FLAG_ANTENNA_PORTS | Current antenna
  TMR_READER_STATS_FLAG_PROTOCOL | Current protocol
  TMR_READER_STATS_FLAG_CONNECTED_ANTENNAS | Current connected antennas

## Function Documentation

bool TMR_fileProvider | ( | void * | cookie,
|  | uint16_t * | size,
|  | uint8_t * | data |
| ) |  |  |

This function can be used as a callback to TMR_firmwareLoad when the firmware image exists as a file.

Parameters:

  | cookie | FILE * pointing to the file to read from.
  `[in]` | size | The number of bytes requested.
  `[out]` | size | The number of bytes returned.
  | data | Pointer to buffer to fill.

Returns:
  true if there is more firmware data to return.

TMR_Status TMR_killTag | ( | TMR_Reader * | reader,
|  | TMR_TagFilter * | target,
|  | TMR_TagAuthentication * | auth |
| ) |  |  |

Deprecated:
  This method is deprecated

Sends a kill command to a tag.

Parameters:

  | reader | The reader being operated on.
  | target | The tag to kill, or `NULL` to kill the first tag seen.
  | auth | The authentication needed to kill the tag.

Returns:
  TMR_ERROR_NO_TAG_FOUND if no tag matching the filter could be found.

TMR_Status TMR_lockTag | ( | TMR_Reader * | reader,
|  | TMR_TagFilter * | target,
|  | TMR_TagLockAction * | action |
| ) |  |  |

Deprecated:
  This method is deprecated

Sends a lock command to a tag.

Parameters:

  | reader | The reader being operated on.
  | target | The tag to kill, or `NULL` to kill the first tag seen.
  | action | The locking action to apply.

Returns:
  TMR_ERROR_NO_TAG_FOUND if no tag matching the filter could be found.

bool TMR_memoryProvider | ( | void * | cookie,
|  | uint16_t * | size,
|  | uint8_t * | data |
| ) |  |  |

This function can be used as a callback to TMR_firmwareLoad when the firmware image exists in system memory. The cookie is a pointer to a TMR_memoryCookie that is initialized with the start of the firmware image in memory and its size.

Parameters:

  | cookie | TMR_memoryCookie value.
  `[in]` | size | The number of bytes requested.
  `[out]` | size | The number of bytes returned.
  | data | Pointer to buffer to fill.

Returns:
  true if there is more firmware data to return.

void TMR_paramProbe | ( | struct TMR_Reader * | reader,
|  | TMR_Param | key |
| ) |  |  |

pointer to TMR_Reader pointer to TMR_Param

Initialize a TMR_TagOp as a Higgs2 Partial Load Image operation with the provided parameters.

Parameters:

  | tagop | Pointer to the tagop structure to initialize.
  | killPassword | kill password
  | accessPassword | access password
  | epc | EPC to write

TMR_Status TMR_writeTag | ( | TMR_Reader * | reader,
|  | const TMR_TagFilter * | target,
|  | TMR_TagData * | data |
| ) |  |  |

Deprecated:
  This method is deprecated

Write a new EPC to an existing tag.

The `/reader/tagop/antenna` parameter controls which antenna will be used for the write operation. The `/reader/tagop/protocol` parameter controls which protocol will be used.

Parameters:

  | reader | The reader being operated on
  | target | The existing tag to write.
  | data | The EPC to write to the tag

Note:
  target is not supported on serial or Astra readers and only TagData filters are supported on other fixed readers.

Returns:
  TMR_ERROR_NO_TAG_FOUND if no tag matching the filter could be found.

Test:

  Call should fail if reader is not connected.

  Upon success, a subsequent TMR_read() should find the new tag ID.

TMR_Status TMR_writeTagMemBytes | ( | TMR_Reader * | reader,
|  | TMR_TagFilter * | target,
|  | uint32_t | bank,
|  | uint32_t | byteAddress,
|  | uint16_t | byteCount,
|  | const uint8_t | data[] |
| ) |  |  |

Deprecated:
  This method is deprecated

Write 8-bit bytes to the memory bank of a tag. If the tag's fundamental memory unit is larger than 8 bits, trying to write sub-unit quantities will produce an error.

Parameters:

  | reader | The reader to operate on.
  | target | The tag to write to, or `NULL`.
  | bank | The tag memory bank to write to.
  | byteAddress | The byte address to start writing to.
  | byteCount | The number of bytes to write.
  | data | The bytes to write.

TMR_Status TMR_writeTagMemWords | ( | TMR_Reader * | reader,
|  | TMR_TagFilter * | target,
|  | uint32_t | bank,
|  | uint32_t | wordAddress,
|  | uint16_t | wordCount,
|  | const uint16_t | data[] |
| ) |  |  |

Deprecated:
  This method is deprecated

Write 16-bit words to the memory bank of a tag. If the tag's fundamental memory unit is larger than 16 bits, trying to write sub-unit quantities will produce an error.

Parameters:

  | reader | The reader to operate on.
  | target | The tag to write to, or `NULL`.
  | bank | The tag memory bank to write to.
  | wordAddress | The word address to start writing to.
  | wordCount | The number of words to write.
  | data | The words to write.