Functions

This section describes API functions to communicate with the Impinj Indy Reader SiP.

Device Management

ipj_get_api_version

uint32_t ipj_get_api_version()

This function returns the API version.

Return:uint32_t

ipj_initialize_iri_device

ipj_error ipj_initialize_iri_device(ipj_iri_device * iri_device)

This function initializes the IRI device data structure.

Parameters:
  • iri_device -

    IRI device data structure

Before using an IRI device, the User application must do the following: allocate or declare IRI device data structure, initialize IRI device data structure (this function), register platform handlers, and connect to the IRI device.

Return:ipj_error

ipj_deinitialize_iri_device

ipj_error ipj_deinitialize_iri_device(ipj_iri_device * iri_device)

This function deinitializes the IRI device data structure.

Parameters:
  • iri_device -

    IRI device data structure

User may deinitialize IRI device after disconnecting from the IRI device. Once the IRI device is deinitialized, the User may de-allocate the IRI device data structure.

Return:ipj_error

ipj_register_handler

ipj_error ipj_register_handler(ipj_iri_device * iri_device, ipj_handler_type handler_type, IPJ_VOID_PFN handler)

This function registers platform and report handlers.

Parameters:
  • iri_device -

    IRI device data structure

  • handler_type -

    Type of handler to register

  • handler -

    Handler pointer

Before using an IRI device, the User application must do the following: allocate or declare IRI device data structure, initialize IRI device data structure, register platform handlers (this function or the _ext-suffixed version), and connect to the IRI device.

User application registers the following platform handlers: platform open port handler, platform close port handler, platform receive handler, platform transmit handler, and platform timestamp handler.

User application registers report handler to handle the following reports: tag operation report, error report, and stop report

Return:ipj_error

ipj_connect

ipj_error ipj_connect(ipj_iri_device * iri_device, IPJ_READER_IDENTIFIER reader_identifier, ipj_connection_type connection_type, ipj_connection_params * params)

This function opens the serial port and connects the Host to the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • reader_identifier -

    Identifier associated with IRI device

  • connection_type -

    Type of connection (Serial/TCP/etc)

  • params -

    Connection parameters (baudrate/etc) (NULL==default)

Before using an IRI device, the User application must do the following: allocate or declare IRI device data structure, initialize IRI device data structure, register platform handlers, and connect to the IRI device (this function).

Return:ipj_error

ipj_disconnect

ipj_error ipj_disconnect(ipj_iri_device * iri_device)

This function disconnects the Host from the IRI device and closes the serial port.

Parameters:
  • iri_device -

    IRI device data structure

User may disconnect from the IRI device after all operations are completed.

Return:ipj_error

ipj_modify_connection

ipj_error ipj_modify_connection(ipj_iri_device * iri_device, ipj_connection_type connection_type, ipj_connection_params * params)

This function modifies the serial port baud rate used to talk to an IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • connection_type -

    Connection modification type

  • params -

    Connection modification parameters

Before modifying an iri connection, the user must have already successfully connected to a device.

Return:ipj_error

ipj_suppress_set_responses

ipj_error ipj_suppress_set_responses(ipj_iri_device * iri_device)

This function allows the user to suppress all ‘set’ and ‘bulk-set’ action responses generated by the reader.

The user will be responsible for checking and dealing with errors on the device.

Return:ipj_error

ipj_resume_set_responses

ipj_error ipj_resume_set_responses(ipj_iri_device * iri_device)

This function allows the user to resume generation of ‘set’ action responses by the reader.

All ‘set’ and ‘bulk-set’ actions will receive an associated response containing success/failure status of the command (This is the default)

Return:ipj_error

ipj_set_receive_timeout_ms

ipj_error ipj_set_receive_timeout_ms(ipj_iri_device * iri_device, uint32_t timeout_ms)

This function allows the user to set the amount of time the receive state machine should wait before returning a timeout error.

Return:ipj_error

Operational Commands

Note

ipj_set/ipj_get and ipj_bulk_set/ipj_bulk_get require the inclusion of bank_index and value_index parameters. These parameters correspond to the position of the value in the key that the user is trying to modify.

The majority of keys are a single value/bank which require a bank_index and value_index of 0. In these cases, we recommend the user use the convenience functions ipj_set_value and ipj_get_value (which masks this detail).

There are also three types of ‘complex’ keys:

  • Key lists - These are individual keys which can contain a list of data. An example of this would be channel tables. In these cases, the user would supply a value_index corresponding to the particular item in the list they would like to access. (These are indexed starting at 0).
  • Banked Keys - These are keys which exist in several ‘banks’ or instances. An example of this would be the SELECT_XXX keys. To access the settings for a select command instance, you would provide its bank number. (These are indexed starting at 0).
  • Banked Key lists - These are keys which contain lists of values, and which also exist as several ‘banks’ or instances. An example of this would be the E_IPJ_KEY_SELECT_MASK_VALUE Key. The value_index would correspond to the mask values for the select command instance, and the bank_index corresponds to the particular select command instance.

The following diagram details this layout:

Image of key bank_index/value_index breakdown

ipj_reset

ipj_error ipj_reset(ipj_iri_device * iri_device, ipj_reset_type reset_type)

This function resets the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • reset_type -

    Type of reset to perform

State of the IRI device is not preserved across resets.

Return:ipj_error

ipj_set

ipj_error ipj_set(ipj_iri_device * iri_device, ipj_key key, uint32_t bank_index, uint32_t value_index, uint32_t value)

This function sets the value of the specified key code on the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • key -

    Key code to set

  • bank_index -

    Key code bank_index to set (applicable for key codes with more than one copy)

  • value_index -

    Key code value_index to set (applicable for key codes with lists)

  • value -

    Value to set

Return:ipj_error

ipj_set_value

Note

This function is a simplified version of ipj_set which assumes a bank_index and value_index of 0

ipj_error ipj_set_value(ipj_iri_device * iri_device, ipj_key key, uint32_t value)

This function sets the value of the specified key code on the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • key -

    Key code to set

  • value -

    Value to set

Return:ipj_error

ipj_get

ipj_error ipj_get(ipj_iri_device * iri_device, ipj_key key, uint32_t bank_index, uint32_t value_index, uint32_t * value)

This function retrieves the value of the specified key code from the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • key -

    Key code to get

  • bank_index -

    Key code bank_index to get (applicable if more than one copy of a key)

  • value_index -

    Key code value_index to get (applicable for key code with lists)

  • value -

    Data buffer to store retrieved value

Return:ipj_error

ipj_get_value

Note

This is a simplified version of ipj_get which assumes a bank_index and value_index of 0

ipj_error ipj_get_value(ipj_iri_device * iri_device, ipj_key key, uint32_t * value)

This function retrieves the value of the specified key code from the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • key -

    Key code to get

  • value -

    Data buffer to store retrieved value

Return:ipj_error

ipj_bulk_set

ipj_error ipj_bulk_set(ipj_iri_device * iri_device, ipj_key_value * key_value, uint32_t key_value_count, ipj_key_list * key_list, uint32_t key_list_count)

This function sets the value of the specified key codes on the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • key_value -

    Array of key codes and values to set

  • key_value_count -

    Number of key codes and values to set

  • key_list -

    Array of key codes to set (used for key codes with lists)

  • key_list_count -

    Number of keys codes (with lists) to set

Return:ipj_error

ipj_bulk_get

ipj_error ipj_bulk_get(ipj_iri_device * iri_device, ipj_key_value * key_value, uint32_t key_value_count, ipj_key_list * key_list, uint32_t key_list_count)

This function retrieves the values of the specified key codes from the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • key_value -

    Array of key codes to retrieve

  • key_value_count -

    Number of key codes and values to retrieve

  • key_list -

    Array of key codes to retrieve (used for key codes with lists)

  • key_list_count -

    Number of keys codes (with lists) to retrieve

Return:ipj_error

ipj_get_info

ipj_error ipj_get_info(ipj_iri_device * iri_device, ipj_key key, ipj_key_info * key_info)

This function retrieves the value of the specified key code from the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • key -

    Key code to get info

  • key_info -

    Information about the specified key code

Return:ipj_error

ipj_start

ipj_error ipj_start(ipj_iri_device * iri_device, ipj_action action)

This function starts the specified action or operation on the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • action -

    Actions or operations to start

This function is used to start inventory to read tags.

Return:ipj_error

ipj_resume

Note

This feature is not available in this release and will return a ..._NOT_IMPLEMENTED error code if called.

ipj_error ipj_resume(ipj_iri_device * iri_device, ipj_action action)

This function resumes the specified action or operation on the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • action -

    Actions or operations to be resumed

This function is used to resume operations after the IRI device has halted.

Return:ipj_error

ipj_stop

ipj_error ipj_stop(ipj_iri_device * iri_device, ipj_action action)

This function stops the specified action or operation on the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

  • action -

    Actions or operations to be stopped

This function is used to stop inventory to read tags.

Return:ipj_error

ipj_receive

ipj_error ipj_receive(ipj_iri_device * iri_device)

This function processes incoming reports from the IRI device.

Parameters:
  • iri_device -

    IRI device data structure

User calls this function to process incoming data. This function requests available data from the platform receive handler, buffers data, and checks for complete reports. This function returns immediately if there is not sufficient data for a report. Once a complete report is received, this function calls the report handler before returning.

User decides when to call this function. For example, User can poll or wait for an interrupt from the system. User responsibility to call this function to keep the receive buffer from overflowing.

Return:ipj_error

ipj_flash_handle_loader_block

ipj_error ipj_flash_handle_loader_block(ipj_iri_device * iri_device, uint32_t len, uint8_t * data)

This function takes in an IRI_Loader chunk and processes it accordingly.

Parameters:
  • iri_device -

    IRI device data structure

  • len -

    Length of the data chunk (in bytes)

  • data -

    Pointer to the data chunk to be processed

Return:ipj_error

IPJ_CLEAR_STRUCT

void IPJ_CLEAR_STRUCT (struct);

IPJ_CLEAR_STRUCT is a convenience macro provided to clear out IRI related structures before use.

We recommend using this macro on every data structure passed into an IRI function to ensure proper behavior.