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.
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.
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.
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:
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.
The Indy Reader Modules have resources and behaviors built in to help debug undesired behaviors. Those resources and behaviors are described below.
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.
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.
The patterns of the HEALTH pin, which is attached to a green LED on the Indy Module development kits, are as follows:
The patterns of the STATUS pin, which is attached to a yellow LED on the Indy Module development kits, are as follows:
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).
At startup, the Debug UART prints out some information about the operation of the module.
The following information is printed in order:
[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]
At startup, the module may print additional characters on the debug UART to indicate certain conditions. A list of those characters is reproduced below.
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 |
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:
The Debug UART print for typical RS500 bootload operation is shown below:
Upgrade Agent Reset...
<3lELLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL
<3WJ>
[AppInfo]
[Version:1.6.7.240]
[/AppInfo]
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)
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.
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:
The string printed by the module will begin with a direction indicator:
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.
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>
Setting the 0x08 flag in the E_IPJ_KEY_TEST_DEBUG_PORT key enables printing of Indy Debug Data on the Debug UART.
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.
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.
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
Prompts the module to print some operating parameters in the following format:
[Health]
[LastTxTs:0]
[LastRxTs:0]
[CurrentTs:845477]
[Temperature:26]
[BaudRate:115107]
[/Health]
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]
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]
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.
Prompts the module to perform a factory reset, erasing its Stored Settings configuration.
Prompts the module to perform a soft reset, similar to the ipj_reset() function.
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]
Prompts the module to stop the debug inventory command initiated with *S.
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