IRI Reader and Library Debugging

During the development of an embedded system, it is extremely unlikely that work will proceed without unexpected problems. With surprising frequency, unintended behaviors AKA “bugs” will occur in the system under development. Debugging is the process of resolving these unintended behaviors, and achieving the desired functionality.

This section of the ITK-C documentation describes the resources available to aid in the debugging of systems built around the Indy embedded RFID reader products and IRI host libaries.

IRI Host Library Debugging

The ITK-C and ITK-LT-C IRI host libraries are C libraries that are written to implement an IRI host on a microcontroller, processor, or computer. These libraries must be adapted to the target host platform, and exercised by the host firmware or software. Since the libraries are run on a host, their execution can often be literally debugged using a debugger built into the host program’s IDE.

In addition to this ability to debug the host code, the following resources are available for host library debugging.

IRI Error Codes

Both the IRI host libraries and the Indy Modules implement error codes. These error codes are generated when unexpected operating conditions occur on the host or on the module. They are returned by most of the host API function calls. Error codes will also be printed on the debug UART, UART2, as they occur, as described below in the Error Printing Behavior section. These error codes are documented in detail in the Error Codes section.

During development, error codes should be captured and debugged thoroughly. During production operation, hosts should examine error code occurence and include appropriate responses.

IRI Host Library Console Printf()

The IRI host library includes code to print out IRI packets that are transmitted and receieved by the host. This code is conditionally compiled based on the constants defined in the source code, and by default is not compiled.

To enable host library printing of transmitted and received IRI packets, add the following text to the iri.c source file.

/* Enable debug print of UART traffic */
#define DEBUG_SERIAL_TRAFFIC

The printouts are similar in format to the IRI Packet Printing strings that can be enabled on the debug UART of the modules. These two channels of IRI packet information can be compared to help debug IRI communication errors.

The string printed by the library will begin with a direction indicator:

  • Write - for packets received from the host by the module.
  • Read - for packets transmitted from the module to the host.

The library will then print the number of bytes in the packet, enclosed by square braces, eg [18].

The library will then print the bytes in the packet in hexidecimal, delimited by spaces, eg 8D 70 6A 21 02 40 00 12 08 EE 1A 04 42 02 08 01 BD EA.

IRI packets transmitted from the host to the the module from the host will appear as follows:

Write [18] 8D 70 6A 21 02 40 00 12 08 EE 1A 04 42 02 08 01 BD EA

IRI packets received by the host from the module will appear as follows:

Read  [40] 8D 70 6A 21 02 40 00 28 00 DC 2A 1A 12 18 12 16 0A 0C AB 0E 00 00 00 00 00 00 00 00 00 00 30 F5 91 17 48 E6 B0 38 37 CF

Note

Incomplete packets transmitted or received by the host will not be printed by the library.

IRI Reader Debugging

The Indy Reader Modules have resources and behaviors built in to help debug undesired behaviors. Those resources and behaviors are described below.

IRI Error Codes

Both the IRI host libraries and the Indy Modules implement error codes. These error codes are generated when unexpected operating conditions occur on the host or on the module. The module will store these error codes in keys E_IPJ_KEY_FIRST_ERROR, E_IPJ_KEY_LAST_ERROR, and E_IPJ_KEY_SYSTEM_ERROR, and will also report their occurence to the host via IRI. Error codes will also be printed on the debug UART, UART2, as they occur, as described below in the Error Printing Behavior section. These error codes are documented in detail in the Error Codes section.

During development, error codes should be captured and debugged thoroughly. During production operation, hosts should examine error code occurence and include appropriate responses.

Health and Status Pins/LEDs

The Indy Modules’ HEALTH and STATUS pins indicate the current state of the modules using specific digital voltage patterns. These pins are connected to LEDs on the module development boards so that the patterns can be easily visualized. In customer designs it is Impinj’s recommendation that these pins be connected to an unpopulated header or vias so that they can be monitored if module state is in question. The digital patterns exhibited by each pin are listed below.

HEALTH Pin

The patterns of the HEALTH pin, which is attached to a green LED on the Indy Module development kits, are as follows:

  • Boot:
    • High
  • Idle:
    • 1 second high, 1 second low
  • IRI host communication in progress:
    • Toggle
  • Active:
    • 250ms high, 750 second low
  • Watchdog reset has occurred:
    • Low
  • Recovery mode:
    • Alternate pattern with STATUS pin

STATUS Pin

The patterns of the STATUS pin, which is attached to a yellow LED on the Indy Module development kits, are as follows:

  • Boot:
    • Toggle Once
  • Idle:
    • Off
  • Active:
    • During inventory, when tags are in the field, the high time is between 150ms and 750ms based on the number of tags seen. The low time is 1000ms minus the high time. If there are no tags in the field the pin remains low.
  • Watchdog reset has occurred:
    • Alternate high and low
  • Recovery mode:
    • Alternate pattern with HEALTH pin

Debug UART (UART2)

The Indy Reader Modules have a secondary UART port named UART2 that is used to print useful information about the operation of the modules. Unlike the IRI UART (UART1), which only communicates via IRI packets, UART2 prints plain-text characters on the TX pin and accepts some commands on the RX pin. The behavior of the debug UART is described in this section.

The Debug UART shares the default configuration of UART1: 115,200 Baud, 8-N-1 (8 data bits, no parity bit, 1 stop bit).

Startup Behavior

At startup, the Debug UART prints out some information about the operation of the module.

The following information is printed in order:

  • The module will print a < character when the bootloader begins to execute.
  • The module will print a character corresponding to the bootloader version in the module.
    • If the module is forced to stay in the bootloader by jumpering the Wakeup pin to 3.3V, no more bytes will be printed to the UART.
  • The module will print characters corresponding to any error conditions that may have caused a reset, such as a watchdog timer reset.
  • The module will print the string WJ> to indicate that execution has jumped to the application image.
    • The module may print additional characters during this step to indicate other conditions that have occurred on the module. For more details, see the Debug UART Startup Debug Characters section below.
  • The module will print out the version of the application image in the following format:
[AppInfo]
[Version:1.6.7.240]
[/AppInfo]

A normal complete startup debug UART print sequence will appear as follows:

<3WJ>
[AppInfo]
[Version:1.6.7.240]
[/AppInfo]
Debug UART Startup Debug Characters

At startup, the module may print additional characters on the debug UART to indicate certain conditions. A list of those characters is reproduced below.

Debug UART Startup Debug Characters
Condition Character
Bootloader start <
Bootloader end >
Watchdog reset w
Reset r
Bootloader l
No watchdog reset X
Bad application version V
Bootloader erase block E
Bootloader read block R
Bootloader load block L
Jump to application J
Jump to ST S
Critical error !
Sleep D
Wakeup pin P
Bad image I

Bootloading Behavior

The Debug UART prints information when the bootloader is employed to upgrade the application image on the module, or to load a stored settings image.

When bootloading, the module:

  • Prints a string to indicate that the module has been reset to perform a bootload: Upgrade Agent Reset...
  • Prints the standard reset <3 text to indicate that the bootloader has started and its current version
  • Prints l to indicate that it has been forced to stay in the bootloader to perform a bootload
  • Prints E to indicate that the targeted image location has been erased
  • Prints L for each block of flash successfully written
  • Resets again when bootloading has completed
  • Prints the standard reset string again, this time proceeding to the application image as usual.

The Debug UART print for typical RS500 bootload operation is shown below:

Upgrade Agent Reset...

<3lELLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL
<3WJ>
[AppInfo]
[Version:1.6.7.240]
[/AppInfo]

Error Printing Behavior

The Debug UART will print out error codes as they occur. Error codes are printed out with their category and error ID separated, along with their 4 info parameters, in the following format:

Error [<category>,<ID>] (parameter1,parameter2,parameter3,parameter4)

For example, if a E_IPJ_ERROR_API_INVALID_PARAMETER error occurs, the following string will be printed:

Error [2,0xb] (0,0,0,0)

Test Debug UART Behavior

The Debug UART can be configured to print certain data depending on operating conditions using the key E_IPJ_KEY_TEST_DEBUG_PORT. This key has multiple bit-fields that can be set to enable different printouts, which are explained below.

IRI Packet Printing - 0x01

The Debug UART is capable of printing sent and received IRI packets in a human readable format. This behavior can be enabled in two ways:

  1. By setting the bit-field 0x01 in key E_IPJ_KEY_TEST_DEBUG_PORT.
  2. By sending the Toggle Host Tx/Rx Data command (H) on the Debug UART.

The string printed by the module will begin with a direction indicator:

  • HostTx - for packets received from the host by the module.
  • HostRx - for packets transmitted from the module to the host.

The module will then print the number of bytes in the packet, enclosed by square braces, eg [24].

The module will then print the bytes in the packet in hexidecimal, delimited by spaces, eg 8d 70 6a 21 2 40 0 18 0 ec 1a a 32 8 22 6 8 b 18 0 20 0 df ea.

IRI packets received by the module from the host will appear as follows:

HostTx[24] 8d 70 6a 21 2 40 0 18 0 ec 1a a 32 8 22 6 8 b 18 0 20 0 df ea

IRI packets transmitted from the module to the host will appear as follows:

HostRx[26] 8d 70 6a 21 2 40 0 1a 0 ee 22 c 32 a 22 8 8 b 10 5 18 0 20 0 f7 e5

Note

Incomplete packets transmitted or received will not be printed by the module.

Test Command Printing - 0x02

Setting the 0x02 flag in the E_IPJ_KEY_TEST_DEBUG_PORT key enables printing of test command configuration and results on the Debug UART.

Test commands and their parameters will be printed as follows:

Test [8] <1,0,0,0> <0x1,0x0,0x0,0x0>
Indy Debug Data Printing - 0x08

Setting the 0x08 flag in the E_IPJ_KEY_TEST_DEBUG_PORT key enables printing of Indy Debug Data on the Debug UART.

Raw IRI Packet Printing - 0x10

Setting the 0x10 flag in the E_IPJ_KEY_TEST_DEBUG_PORT key enables printing of raw IRI packets on the Debug UART.

This behavior is similar to that of the IRI Packet Printing behavior enabled using 0x01, but differs in that it prints IRI packets byte by byte as they are received or transmitted at the module, and not all at once when they are fully assembled in the transmit or receive buffers.

For example, a packet received from the host would first appear in bursts on the Raw interface:

HostRawTx[2] 8d 70
HostRawTx[8] 6a 21 2 40 0 1b 0 ef
HostRawTx[17] 1a d 2a b 22 9 8 8d 8 10 11 18 0 20 0 e6 4f

And then appear as a complete packet on the normal IRI packet printout:

HostTx[27] 8d 70 6a 21 2 40 0 1b 0 ef 1a d 2a b 22 9 8 8d 8 10 11 18 0 20 0 e6 4f

Note that the total byte count and contents are the same between both printouts.

Debug UART Commands

The Debug UART supports a small number of commands that can be used to prompt the module to immediately respond with information about configuration and operation, or to change its configuration in some way.

These commands are listed in detail below.

Note

Support for these commands varies by application image version, and their behavior is subject to change without notice.

Command List - ?

Transmitting the ? character to the Debug UART will prompt the module to print a list of supported commands over the UART.

Each command is listed with its command code, follows by a brief description.

This list will be formatted as follows:

Debug Console Functions:
T: Status
A: Application info
D: Image info
H: Toggle Host Tx/Rx data
*F: Factory Reset
*R: Soft Reset
*S: Start Inventory [. Tag Report]
*s: Stop Inventory
*C: Dump Impinj Settings RAM region
Status - T

Prompts the module to print some operating parameters in the following format:

[Health]
[LastTxTs:0]
[LastRxTs:0]
[CurrentTs:845477]
[Temperature:26]
[BaudRate:115107]
[/Health]
Application Info - A

Prompts the module to print information about the currently loaded application image to the debug port in the following format:

[AppInfo]
[Product:RS500]
[Version:1.6.7.240]
[CRC:0xe8c9d249]
[CIID:57]
[CalInfo:0xfe]
[SKU:1]
[LotDate:11114]
[Serial:5]
[HWRev:0]
[ProductKey:0x69c01348]
[StoredSettings:0]
[/AppInfo]
Image Info - D

Prompts the module to print information about all currently loaded images, including the bootloader, application, stored settings, and Impinj settings, to the debug port in the following format:

[ImageInfo]
[Type:Bootstrap]
[TimeStamp:Jan 10 2014 17:58:58]
[Location:0x8000000]
[Size:0x3000]
[Version:1.0.2.240]
[CRC:0x8a6d5f26]
[/ImageInfo]

[ImageInfo]
[Type:Application]
[TimeStamp:Nov 10 2016 14:55:02]
[Location:0x8003000]
[Size:0x1c000]
[Version:1.6.7.240]
[CRC:0xe8c9d249]
[/ImageInfo]

[ImageInfo]
[Type:StoredSettings]
[TimeStamp: ]
[Location:0x801f000]
[Size:0x800]
[Version:0.0.0.0]
[CRC:0x5a764497]
[/ImageInfo]

[ImageInfo]
[Type:IpjSettings]
[TimeStamp: ]
[Location:0x801f800]
[Size:0x800]
[Version:0.0.0.0]
[CRC:0x4f87522f]
[/ImageInfo]
Toggle Host Tx/Rx Data - H

Prompts the module to enable or disable printing logs of all IRI packets successfully sent and received to the debug port.

This has the same functionality as setting bit 0x01 of the key E_IPJ_KEY_TEST_DEBUG_PORT.

The format of these logs is described above in the section Test Debug UART Behavior IRI Packet Printing.

Factory Reset - *F

Prompts the module to perform a factory reset, erasing its Stored Settings configuration.

Soft Reset - *R

Prompts the module to perform a soft reset, similar to the ipj_reset() function.

Start Inventory - *S

Prompts the module to perform an RFID inventory with the current key settings, printing a test string and one period per tag seen. The module will transmit IRI packets with tag operation reports to the host while performing this debug command.

Note

When executing this test command, the module will obey the AUTOSTOP keys, such as E_IPJ_KEY_AUTOSTOP_DURATION_MS, etc, but will not print the [/Inventory] end of inventory marker. The debug command must be terminated with *s to end the debug command.

The output on the debug UART when this command is called (and stopped) is as follows:

[Inventory]
..................................
[/Inventory]
Stop Inventory - *s

Prompts the module to stop the debug inventory command initiated with *S.

Dump Impinj Settings RAM Region - *C

Prompts the module to print out the Impinj Settings contents of RAM on the Debug UART.

Individual lines will contain a specific range of RAM, and appear as follows:

[0x801FFF0]:0xFFFFFFFF 0xFFFFFFFF 0xFFFFFFFF 0xFFFFFFFF