# Reader

## Classes

struct | TMR_Reader

## 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_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_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)
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)
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

TMR_Reader encapsulates a connection to a ThingMagic RFID reader device and provides an interface to perform RFID operations such as reading tags and writing tag IDs.

Reads can be done on demand, with the TMR_read() function, or continuously in the background with the TMR_startReading() function. Background reads notify registered listeners of tags that are read.

Operations which take an argument for a tag to operate on may optionally be passed a `NULL` argument. This lets the reader choose what tag to use, but may not work if multiple tags are present. This use is recommended only when exactly one tag is known to be in range.

## Function Documentation

TMR_Status TMR_addAuthReqListener | ( | struct TMR_Reader * | reader,
|  | TMR_AuthReqListenerBlock * | block |
| ) |  |  |

Add a listener to the list of functions that will be called for each background tag read.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_addReadExceptionListener | ( | struct TMR_Reader * | reader,
|  | TMR_ReadExceptionListenerBlock * | block |
| ) |  |  |

Add a listener to the list of functions that will be called for each error that occurs during background tag reading.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_addReadListener | ( | struct TMR_Reader * | reader,
|  | TMR_ReadListenerBlock * | block |
| ) |  |  |

Add a listener to the list of functions that will be called for each background tag read.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_addStatsListener | ( | struct TMR_Reader * | reader,
|  | TMR_StatsListenerBlock * | block |
| ) |  |  |

Add a listener to the list of functions that will be called for each background status response.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_addStatusListener | ( | struct TMR_Reader * | reader,
|  | TMR_StatusListenerBlock * | block |
| ) |  |  |

Add a listener to the list of functions that will be called for each background status response.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_addTransportListener | ( | TMR_Reader * | reader,
|  | TMR_TransportListenerBlock * | block |
| ) |  |  |

Add a listener to the list of functions that will be called for each message sent to or received from the reader.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_connect | ( | struct TMR_Reader * | reader | ) |

Establishes the connection to the reader at the URI specified in the TMR_create() call. The existence of a reader at the address is verified and the reader is brought into a state appropriate for performing RF operations.

Parameters:

  | reader | The reader to connect

Test:

  Connecting to existing reader should succeed.

  Connecting to nonexisting reader should fail.

TMR_Status TMR_create | ( | TMR_Reader * | reader,
|  | const char * | deviceUri |
| ) |  |  |

The TMR_Reader struct being initialized should be preallocated by the user. No memory is allocated during the initialization process, and the reader is not contacted at this point.

Parameters:

  | reader | The TMR_Reader structure to initialize

  deviceUri

  an identifier for the reader to connect to, with a URI syntax. The scheme can be `eapi` for the embedded module protocol, `rql` for the request query language, or `tmr` to guess. The remainder of the URI identifies the stream that the protocol will be spoken over, either a local host serial port device or a TCP network port. Example URIs are:
  - tmr://192.168.10.8/ - Reader at TCP/IP address 192.168.10.8, RQL assumed
  - rql://192.168.10.8/ - RQL reader at TCP/IP address 192.168.10.8
  - tmr:///dev/ttyS1 - reader on serial port /dev/ttyS1, EAPI (serial) assumed
  - eapi:///COM2 - EAPI (serial) reader on serial port COM2
  - llrp+eapi://192.168.10.8 - EAPI tunneled over LLRP to a reader at TCP/IP address 192.168.10.8

Test:

  Call with valid URI should not fail.

  Call with invalid URI should fail.

TMR_Status TMR_create_alloc | ( | TMR_Reader ** | readerPointer,
|  | const char * | deviceUri |
| ) |  |  |

This function is a version of TMR_create() that dynamically allocates the TMR_Reader structure and stores the pointer in *reader.

Parameters:

  `[out]` | readerPointer | Pointer to the TMR_Reader* in which to place the pointer to the newly allocated reader structure. @
  | deviceUri | As described in TMR_create().

Test:

  Call with valid URI should not fail.

  Call with invalid URI should fail.

  Multiple calls with different URIs should return distinct objects.

TMR_Status TMR_destroy | ( | TMR_Reader * | reader | ) |

Closes the connection to the reader and releases any resources that have been consumed by the reader structure.

Parameters:

  | reader | The reader to shut down.

Test:

  Destroying existing connected reader should succed.

  Destroying existing unconnected reader should succeed.

  Destroying already-destroyed reader should fail.

  Destroying reader allocated by TMR_create_alloc() should free the allocated memory.

TMR_Status TMR_executeTagOp | ( | struct TMR_Reader * | reader,
|  | TMR_TagOp * | tagop,
|  | TMR_TagFilter * | filter,
|  | TMR_uint8List * | data |
| ) |  |  |

This method provides the direct execution of TagOp commands Reader operates on the first tag found, with applicable tag filtering Reader stops and the call returns immediately after finding one tag and operating on it, unless the command timeout expires first The operation is performed on the antenna specified in /reader/tagop/antenna parameter /reader/tagop/protocol specifies the protocol to be used

Parameters:

  | reader | The reader being operated on
  | tagop | Pointer to the TMR_TagOp which needs to be executed
  | filter | Tag Filter to be used
  `[out]` | data | Data returned as a result of tag operation

TMR_Status TMR_firmwareLoad | ( | TMR_Reader * | reader,
|  | void * | cookie,
|  | TMR_FirmwareDataProvider | provider |
| ) |  |  |

The TMR_firmwareLoad() method attempts to install firmware on the reader, then restart and reinitialize.

Parameters:

  | reader | The reader to operate on
  | cookie | Value to pass to the callback function.
  | provider | Callback function to provide firmware data.

TMR_Status TMR_getNextTag | ( | TMR_Reader * | reader,
|  | TMR_TagReadData * | tagData |
| ) |  |  |

Fetches the next tag from the last TMR_read() operation.

Parameters:

  | reader | The reader being operated on
  `[out]` | tagData | The TMR_TagReadData structure to fill.

Test:

  Call should fail before a read() call.

  Call should fail after a read() call that set *tagCount to zero.

  Call should fill in a tag after a read() call that set *tagCount to a nonzero value.

  Call should succeed exactly as many times as specified by *tagCount.

TMR_Status TMR_gpiGet | ( | TMR_Reader * | reader,
|  | uint8_t * | count,
|  | TMR_GpioPin | state[] |
| ) |  |  |

Get the state of all GPI pins.

Parameters:

  | reader | The reader to operate on.
  `[in]` | count | Pointer to the allocated length of the state array.
  `[out]` | count | Pointer to the number of entries in the state array.
  `[out]` | state | Array of reader pins and the state to set them to.

TMR_Status TMR_gpoSet | ( | TMR_Reader * | reader,
|  | uint8_t | count,
|  | const TMR_GpioPin | state[] |
| ) |  |  |

Set the state of some GPO pins.

Parameters:

  | reader | The reader to operate on.
  | count | The length of the state array.
  | state | Array of reader pins and the state to set them to.

TMR_Status TMR_hasMoreTags | ( | TMR_Reader * | reader | ) |

Return values:

  | TMR_SUCCESS | if there are more tags to be retrieved from the most recent TMR_read() operation.
  | TMR_ERROR_NO_TAGS | if no more tags are available for retrieval.
  | Other | TMR_ERRORs when appropriate.

Parameters:

  | reader | The reader being operated on

Test:

  Call should return false before a read() call.

  Call should return false after a read() call that set *tagCount to zero.

  Call should return true after a read() call that set *tagCount to a nonzero value.

  Call should return true through exactly as many getNextTag() calls as specified by *tagCount.

TMR_Status TMR_loadConfig | ( | struct TMR_Reader * | reader,
|  | char * | filePath |
| ) |  |  |

This function loads the reader configuration parameters from file and applies to module.

Parameters:

  | reader | The reader to operate on.
  | filePath | load reader configurations from filepath.

TMR_Status TMR_paramGet | ( | struct TMR_Reader * | reader,
|  | TMR_Param | key,
|  | void * | value |
| ) |  |  |

Get the value of a reader parameter.

Parameters:

  | reader | The reader to operate on.
  | key | The string identifying the parameter.

  `[out]`

  value

  Pointer to the parameter value. For list types (including TMR_String), the caller must allocate the pointed-to space and set the size of the allocated space in the max field, and the function will write into that space and set the actual length of the data. If the list or string is larger than will fit in the pointed-to space, the length will be larger than the allocated space - be careful iterating over the results if there is a chance of not passing in a large enough structure.

Test:

  Call should fail if key is an invalid parameter name.

  Call should fail if key is valid but unsupported by connected reader.

  Call should succeed if key matches parameter name, independent of case.

TMR_Param TMR_paramID | ( | const char * | name | ) |

Return the TMR_Param ID corresponding to a string name. Only present if TMR_ENABLE_PARAM_STRINGS is set.

Parameters:

  | name | the parameter

Returns:
  The TMR_Param value of the name, or TMR_PARAM_NONE if no such parameter exists.

TMR_Status TMR_paramList | ( | struct TMR_Reader * | reader,
|  | TMR_Param * | keys,
|  | uint32_t * | len |
| ) |  |  |

Get a list of the parameters available

Supported Parameters:

- /reader/antenna/checkPort
- /reader/antenna/connectedPortList
- /reader/antenna/portList
- /reader/antenna/portSwitchGpos
- /reader/antenna/returnLoss
- /reader/antenna/settlingTimeList
- /reader/antenna/txRxMap
- /reader/asyncofftime
- /reader/baudRate
- /reader/commandTimeout
- /reader/currentTime
- /reader/description
- /reader/extendedEpc
- /reader/gen2/BLF
- /reader/gen2/accessPassword
- /reader/gen2/bap
- /reader/gen2/protocolExtension
- /reader/gen2/q
- /reader/gen2/session
- /reader/gen2/t4
- /reader/gen2/tagEncoding
- /reader/gen2/target
- /reader/gen2/tari
- /reader/gen2/writeEarlyExit
- /reader/gen2/writeMode
- /reader/gen2/writeReplyTimeout
- /reader/gpio/inputList
- /reader/gpio/outputList
- /reader/hostname
- /reader/iso180006b/BLF
- /reader/iso180006b/delimiter
- /reader/iso180006b/modulationDepth
- /reader/licenseKey
- /reader/licensedFeatures
- /reader/manageLicenseKey
- /reader/metadataflags
- /reader/powerMode
- /reader/probeBaudRates
- /reader/radio/enablePowerSave
- /reader/radio/enableSJC
- /reader/radio/portReadPowerList
- /reader/radio/portWritePowerList
- /reader/radio/powerMax
- /reader/radio/powerMin
- /reader/radio/readPower
- /reader/radio/temperature
- /reader/radio/writePower
- /reader/read/asyncOffTime
- /reader/read/asyncOnTime
- /reader/read/plan
- /reader/region/hopTable
- /reader/region/hopTime
- /reader/region/id
- /reader/region/lbt/enable
- /reader/region/minimumFrequency
- /reader/region/quantizationStep
- /reader/region/supportedRegions
- /reader/selectedProtocols
- /reader/statistics
- /reader/stats
- /reader/stats/enable
- /reader/status/antennaEnable
- /reader/status/frequencyEnable
- /reader/status/temperatureEnable
- /reader/tagReadData/enableReadFilter
- /reader/tagReadData/readFilterTimeout
- /reader/tagReadData/recordHighestRssi
- /reader/tagReadData/reportRssiInDbm
- /reader/tagReadData/tagopFailures
- /reader/tagReadData/tagopSuccesses
- /reader/tagReadData/uniqueByAntenna
- /reader/tagReadData/uniqueByData
- /reader/tagReadData/uniqueByProtocol
- /reader/tagop/antenna
- /reader/tagop/protocol
- /reader/transportTimeout
- /reader/trigger/read/Gpi
- /reader/uri
- /reader/userConfig
- /reader/userMode
- /reader/version/hardware
- /reader/version/model
- /reader/version/productGroup
- /reader/version/productGroupID
- /reader/version/productID
- /reader/version/serial
- /reader/version/software
- /reader/version/supportedProtocols

Parameters:

  | reader | The reader to operate on.
  `[out]` | keys | Pointer to the list of parameters. The caller must allocate space for the parameters.
  `[in]` | len | Pointer to the allocated length of the space pointed to by keys.
  `[out]` | len | Pointer to the number of parameters supported by the reader, which may be larger or smaller than the provided array. If it is larger than the provided array, the list is truncated.

Get a list of the parameters available pointer of reader object pointer of TMR_Param pointer to uint32_t

const char* TMR_paramName | ( | TMR_Param | key | ) |

Return the string name corresponding to a TMR_Param value. Only present if TMR_ENABLE_PARAM_STRINGS is set.

Parameters:

  | key | The parameter ID.

Returns:
  The corresponding string name.

TMR_Status TMR_paramSet | ( | struct TMR_Reader * | reader,
|  | TMR_Param | key,
|  | const void * | value |
| ) |  |  |

Set the value of a reader parameter.

Parameters:

  | reader | The reader to operate on.
  | key | The string identifying the parameter.
  | value | The new value to use for the parameter. The caller may not alter the value after passing it to this function.

Test:

  Call should fail if key is an invalid parameter name.

  Call should fail if key is valid but unsupported by connected reader.

  Call should succeed if key matches parameter name, independent of case.

TMR_Status TMR_read | ( | TMR_Reader * | reader,
|  | uint32_t | timeoutMs,
|  | int32_t * | tagCount |
| ) |  |  |

Search for tags for a fixed duration. Once this returns, the tags are retrieved by calling TMR_getNextTag() until TMR_hasMoreTags() returns false.

Parameters:

  | reader | The reader being operated on
  | timeoutMs | The number of milliseconds to search for tags
  `[out]` | tagCount | The number of tags read, or -1 if the number is unknown. If NULL, no value will be stored.

Test:

  Call should fail if reader is not connected.

  If call is successful as per TMR_Error, *tagCount should be modified and contain a positive value.

TMR_Status TMR_readIntoArray | ( | struct TMR_Reader * | reader,
|  | uint32_t | timeoutMs,
|  | int32_t * | tagCount,
|  | TMR_TagReadData * | result[] |
| ) |  |  |

Wrapper routine that searches for tags, allocates space for the results, and returns the results in a single array.

Parameters:

  | reader | The reader being operated on
  | timeoutMs | The number of milliseconds to search for tags
  `[out]` | tagCount | The number of tags found and the size of the allocated array.
  `[out]` | result | The array of tag read data.

Test:

  Call should fail if reader is not connected.

  If call is successful as per TMR_Error, *tagCount should be modified and contain a positive value, and *result should be modified and contain the corresponding number of tag read values.

Out param "result" should be freed after using it.

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

Read 8-bit bytes from the memory bank of a tag.

Parameters:

  | reader | The reader being operated on.
  | target | The tag to read from, or `NULL`.
  | bank | The tag memory bank to read from.
  | byteAddress | The byte address to start reading at.
  | byteCount | The number of bytes to read
  `[out]` | data | The read data.

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

Read 16-bit words from the memory bank of a tag.

Parameters:

  | reader | The reader being operated on.
  | target | The tag to read from, or `NULL`.
  | bank | The tag memory bank to read from.
  | wordAddress | The word address to start reading at.
  | wordCount | The number of words to read
  `[out]` | data | The read data.

TMR_Status TMR_reboot | ( | struct TMR_Reader * | reader | ) |

Reboot the reader

Parameters:

  | reader | The reader to operate on.

TMR_Status TMR_removeReadExceptionListener | ( | struct TMR_Reader * | reader,
|  | TMR_ReadExceptionListenerBlock * | block |
| ) |  |  |

Remove a listener from the list of functions that will be called for each error that occurs during background tag reading.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_removeReadListener | ( | struct TMR_Reader * | reader,
|  | TMR_ReadListenerBlock * | block |
| ) |  |  |

Remove a listener from the list of functions that will be called for each background tag read.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_removeStatsListener | ( | struct TMR_Reader * | reader,
|  | TMR_StatsListenerBlock * | block |
| ) |  |  |

Remove a listener from the list of functions that will be called for each background status response.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_removeStatusListener | ( | struct TMR_Reader * | reader,
|  | TMR_StatusListenerBlock * | block |
| ) |  |  |

Remove a listener from the list of functions that will be called for each background status response.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_removeTransportListener | ( | TMR_Reader * | reader,
|  | TMR_TransportListenerBlock * | block |
| ) |  |  |

Remove a listener from the list of functions that will be called for each message sent to or received from the reader.

Parameters:

  | reader | The reader to operate on.
  | block | A structure containing a pointer to the listener function and a user-supplied cookie value to pass to the function when called.

TMR_Status TMR_saveConfig | ( | struct TMR_Reader * | reader,
|  | char * | filePath |
| ) |  |  |

This function saves the current reader configuration parameters and its values to a file.

Parameters:

  | reader | The reader to operate on.
  | filePath | save reader configurations from filepath.

TMR_Status TMR_setSerialTransport | ( | char * | scheme,
|  | TMR_TransportNativeInit | nativeInit |
| ) |  |  |

Stores the transport init function against the provided scheme.

Parameters:

  | scheme | the transport scheme name.
  | nativeInit | reference to the init function.

Currently set serial transport is only supported for serial readers only.

TMR_Status TMR_startReading | ( | struct TMR_Reader * | reader | ) |

Start reading tags in the background. The tags found will be passed to the registered read listeners, and any errors that occur during reading will be passed to the registered exception listeners. Reading will continue until stopReading() is called. The read listeners will be called from a background thread.

Parameters:

  | reader | The reader to operate on.

TMR_Status TMR_STATS_init | ( | TMR_Reader_StatsValues * | stats | ) |

This function will initialize the TMR_StatValues structure with the default values

Initialize a TMR_StatValues structure with the default vales

Parameters:

  | stats | Pointer to the TMR_StatValues structure to initialize.

TMR_Status TMR_stopReading | ( | struct TMR_Reader * | reader | ) |

Stop reading tags in the background. This function will wait until the reader has stopped.

Parameters:

  | reader | The reader to operate on.

const char* TMR_strerr | ( | TMR_Reader * | reader,
|  | TMR_Status | status |
| ) |  |  |

This function will convert the error codes into proper error messages.

Parameters:

  | reader | The reader which resulted in error
  | status | The status code which is to be converted