Platform and Report Handlers

This section describes the platform and report handler functions called by the IRI host library. The platform handler functions define how the IRI host library interacts with the resources of the host device on which the library runs, including device memory, peripherals, etc. The report handler functions define how the IRI host library handles event reports from Indy Modules, including tag operation reports, GPIO reports, etc. The functions should be customized per the requirements of a given Indy Module use case. Impinj provides example implementations of the platform handlers in the platform port examples included in the IRI Code Examples.

At runtime, the IRI host configures the handlers by registering the handler functions using the ipj_register_handler() function. In the IRI Code Examples provided by Impinj, the functions are registered in the ipj_util_register_handlers() function contained in ipj_util.c.

Platform Handler Definitions

READER_CONTEXT

typedef void * IPJ_READER_CONTEXT

IPJ_READER_CONTEXT is a HANDLE to the serial port.

READER_IDENTIFIER

typedef void * IPJ_READER_IDENTIFIER

IPJ_READER_IDENTIFIER is a reference used by the platform to open serial port IPJ_READER_IDENTIFIER is also used by report handler to allow the application to associate reports with a given reader in systems with multiple readers.

READER_USER_IDENTIFIER

typedef uint32_t IPJ_READER_USER_IDENTIFIER

IPJ_READER_USER_IDENTIFIER is a reference used by the host application IPJ_READER_USER_IDENTIFIER is an alternative to the IPJ_READER_IDENTIFIER which can also used by report handler to allow the application to associate reports with a given reader in systems with multiple readers.

This is set by the user and is not required by the platform.

VOID_PFN

typedef void(* IPJ_VOID_PFN)(void)

IPJ_VOID_PFN is a pointer to a platform handler routine.

Platform Handler Interface

The platform handler functions define how the IRI host library interacts with the resources of the host device on which the library runs, including device memory, peripherals, etc. When customizing the IRI host library to run on a specific hardware platform, these functions will require modification to match that specific host platform.

For examples of ports to different platforms, see the example platform_*.c code in the IRI Code Examples.

PLATFORM_OPEN_PORT_HANDLER

typedef uint32_t (* PLATFORM_OPEN_PORT_HANDLER)(IPJ_READER_CONTEXT *reader_context, IPJ_READER_IDENTIFIER reader_identifier, ipj_connection_type connection_type, ipj_connection_params *params)

typedef uint32_t (* PLATFORM_OPEN_PORT_HANDLER_EXT)(void *opaque_args, IPJ_READER_CONTEXT *reader_context, IPJ_READER_IDENTIFIER reader_identifier, ipj_connection_type connection_type, ipj_connection_params *params)

This function opens the serial port.

IRI library calls this function to open the serial port using IPJ_READER_IDENTIFIER as a reference to the serial port.

This function provides IPJ_READER_CONTEXT to the IRI library.

PLATFORM_CLOSE_PORT_HANDLER

typedef uint32_t (* PLATFORM_CLOSE_PORT_HANDLER)(IPJ_READER_CONTEXT reader_context)

typedef uint32_t (* PLATFORM_CLOSE_PORT_HANDLER_EXT)(void *opaque_args, IPJ_READER_CONTEXT reader_context)

This function closes the serial port.

IRI library calls this function to close the serial port.

PLATFORM_TRANSMIT_HANDLER

typedef uint32_t (* PLATFORM_TRANSMIT_HANDLER)(IPJ_READER_CONTEXT reader_context, uint8_t *message_buffer, uint16_t buffer_size, uint16_t *number_bytes_written)

typedef uint32_t (* PLATFORM_TRANSMIT_HANDLER_EXT)(void *opaque_args, IPJ_READER_CONTEXT reader_context, uint8_t *message_buffer, uint16_t buffer_size, uint16_t *number_bytes_written)

This function transmits the data to the Indy Module.

PLATFORM_RECEIVE_HANDLER

typedef uint32_t (* PLATFORM_RECEIVE_HANDLER)(IPJ_READER_CONTEXT reader_context, uint8_t *message_buffer, uint16_t buffer_size, uint16_t *number_bytes_received, uint16_t timeout_ms)

typedef uint32_t (* PLATFORM_RECEIVE_HANDLER_EXT)(void *opaque_args, IPJ_READER_CONTEXT reader_context, uint8_t *message_buffer, uint16_t buffer_size, uint16_t *number_bytes_received, uint16_t timeout_ms)

This function receives data from the Indy Module.

PLATFORM_TIMESTAMP_MS_HANDLER

typedef uint32_t (* PLATFORM_TIMESTAMP_MS_HANDLER)()

typedef uint32_t (* PLATFORM_TIMESTAMP_MS_HANDLER_EXT)(void *opaque_args)

This function provides a timestamp in milliseconds.

PLATFORM_SLEEP_MS_HANDLER

typedef void(* PLATFORM_SLEEP_MS_HANDLER)(uint32_t milliseconds)

typedef void(* PLATFORM_SLEEP_MS_HANDLER_EXT)(void *opaque_args, uint32_t milliseconds)

This function causes the host platform to sleep for a specified number of milliseconds.

PLATFORM_FLUSH_PORT_HANDLER

typedef uint32_t (* PLATFORM_FLUSH_PORT_HANDLER)(IPJ_READER_CONTEXT reader_context)

typedef uint32_t (* PLATFORM_FLUSH_PORT_HANDLER_EXT)(void *opaque_args, IPJ_READER_CONTEXT reader_context)

This function provides facilities to flush the communication port.

PLATFORM_MODIFY_CONNECTION_HANDLER

typedef uint32_t (* PLATFORM_MODIFY_CONNECTION_HANDLER)(IPJ_READER_CONTEXT reader_context, ipj_connection_type connection_type, ipj_connection_params *params)

typedef uint32_t (* PLATFORM_MODIFY_CONNECTION_HANDLER_EXT)(void *opaque_args, IPJ_READER_CONTEXT reader_context, ipj_connection_type connection_type, ipj_connection_params *params)

This function provides facilities to change the properties of the host<>device connection.

Report Handler Interface

The report handler functions define how the IRI host library handles event reports from Indy Modules, including tag operation reports, GPIO reports, etc. These functions will require modification depending on the RFID use case. They are generally used to store or act upon information received from Indy Modules.

There are numerous examples of when to use the report handlers in the Configuration Examples, most notably in the Reading Data from Reports section.

REPORT_HANDLER

typedef ipj_error (* REPORT_HANDLER)(struct ipj_iri_device *iri_device, ipj_report_id report_id, void *report)

typedef ipj_error (* REPORT_HANDLER_EXT)(void *opaque_args, struct ipj_iri_device *iri_device, ipj_report_id report_id, void *report)

This function is called when a complete report is received by the IRI library.

DIAGNOSTIC_HANDLER

typedef void(* DIAGNOSTIC_HANDLER)(struct ipj_iri_device *iri_device, ipj_error error)

typedef void(* DIAGNOSTIC_HANDLER_EXT)(void *opaque_args, struct ipj_iri_device *iri_device, ipj_error error)

This function is called when an error condition is detected by the IRI library.