ANSI X3T6 Technical Committee



Revision History

|Date |Change |

|12/13/98 |Re-formatted document from raw ASCII text, into Microsoft Word '97 |

|12/13/98 |Added password mechanism for tag reads/writes (to be re-named "access id" in the future, per teleconferences in November|

|1/6/99 |Re-released document on website , with editing notes from 12/15/98 meeting |

|1/9/99 |Added revision history (to be removed when document is ratified) 12/15 Editing note #4 |

|1/9/99 |Added table of contents (to be removed when document is ratified) 12/15 Editing note #3 |

|1/10/99 |Addressed editing notes 9, 13, 14, 19, 38, and 51 |

|1/11/99 |Addressed editing notes 11, 17, 18, 20, and 41 |

|1/12/99 |Addressed editing notes 24, 26, 27, 24, 30, 40, 44, and 45 |

| | |

Table of Contents

PART II: APPLICATION PROGRAM INTERFACE 4

1 INTRODUCTION 4

1.1 PURPOSE OF THE API 4

1.2 NOMENCLATURE AND CONVENTIONS 5

2 SUBROUTINE CALLS 6

2.1 SUBROUTINE rfopen() 6

2.1.1 Purpose 6

2.1.2 Synopsis 6

2.1.3 Description 6

2.1.4 Parameters 6

2.1.5 Return Values 7

2.1.6 Status Codes 7

2.1.7 Related Information 9

2.2 SUBROUTINE rfclose() 9

2.2.1 Purpose 9

2.2.2 Synopsis 9

2.2.3 Description 9

2.2.4 Parameters 10

2.2.5 Return Values 10

2.2.6 Status Codes 10

2.2.7 Related Information 11

2.3 rflog() 11

2.3.1 Purpose 11

2.3.2 Synopsis 11

2.3.3 Description 11

2.3.4 Parameters 12

2.3.5 Return Values 12

2.3.6 Status Codes 12

2.3.7 Related Information 12

2.4 SUBROUTINE rfidentify() 12

2.4.1 Purpose 12

2.4.2 Synopsis 12

2.4.3 Description 13

2.4.4 Parameters 13

2.4.5 Control Structure Checklist 13

2.4.6 Applicable Control Flags 14

2.4.7 Return Values 14

2.4.8 Status Codes 15

2.4.9 File 17

2.4.10 Related Information 17

2.5 rfread() and rfwrite() 17

2.5.1 Purpose 17

2.5.2 Synopsis 17

2.5.3 Description 17

2.5.4 Parameters 18

2.5.5 Control Structure Checklist 18

2.5.5.1 Checklist for rfread(), rfwrite() non-multiple: 18

2.5.5.2 Checklist for rfwrite() with Multiple Tags 19

2.5.6 Applicable Control Flags 20

2.5.7 Return Values 21

2.5.8 Status Codes 21

2.5.9 Files and Related Information 23

2.6 rfgetattr() and rfsetattr() 23

2.6.1 Purpose 23

2.6.2 Synopsis 23

2.6.3 Description 24

2.6.4 Parameters 24

2.6.5 Return Values 24

2.6.6 Status Codes 24

2.6.7 File 24

2.6.8 Related Information 24

2.7 rfget_control() 25

2.7.1 Purpose 25

2.7.2 Synopsis 25

2.7.3 Description 25

2.7.4 Parameters 25

2.7.5 Return Values 25

2.7.6 Status Codes 25

2.7.7 File 25

2.7.8 Related Information 26

3 DATA STRUCTURES 26

3.1 DATA STRUCTURE OVERVIEW 26

3.2 STRUCTURE rfcontrol_t 27

3.2.1 Structure Member flag 27

3.2.2 Structure Member timeout_sec 31

3.2.3 Structure Member taglist 31

3.2.4 Structure Member start_tag 31

3.2.5 Structure Member end_tag 32

3.2.6 Structure Member valid_tags 32

3.2.7 Structure Member max_tags 32

3.2.8 Stucture Member status 33

3.2.9 Stucture Member istatus 35

3.2.10 Stucture Member ostatus 35

3.2.11 Stucture Member field_status 37

3.2.12 Stucture Member field_status_save 37

3.2.13 Stucture Member select_list_number 38

3.2.14 Stucture Member select_equation 38

3.2.15 Stucture Member fields 38

3.2.16 Stucture Member field_name 38

3.2.17 Stucture Member field_value 39

3.2.18 Sucture Member tag_field_value 39

3.2.19 Stucture Member access_ids 41

3.2.20 Stucture Member physadrs 42

3.2.21 Stucture Member cust_table 43

3.2.22 Stucture Member cust_file_name 43

3.3 STRUCTURE rfphysadrs_t 43

3.4 STRUCTURE rfaccess_ids_t 44

3.5 STRUCTURE rfattr_t 44

3.6 STRUCTURE rfstatus_t 45

4 SELECTION EQUATION AND TAG TYPE TABLE 45

4.1 SELECTION EQUATION 45

4.1.1 Selection Equation Forms 45

4.1.2 Tokens 46

4.1.3 Select List Number 48

4.2 Tag Type Table 48

5 API CODE EXAMPLES 51

5.1 INTRODUCTION TO CODE EXAMPLES 51

5.2 EXAMPLE INITIAL SETUP 52

5.3 EXAMPLE 1 53

5.4 EXAMPLE 2 53

5.5 EXAMPLE 3 54

5.6 EXAMPLE 4 54

5.7 EXAMPLE 5 54

5.8 EXAMPLE 6 55

5.9 EXAMPLE 7 55

5.10 EXAMPLE 8 56

PART II: APPLICATION PROGRAM INTERFACE

1 INTRODUCTION

1 PURPOSE OF THE API

The Application Program Interface (API) provides a standard mechanism for accessing the device driver of a T6-compliant RFID interrogator. The driver supported by the API provides the following features:

Read and write support including:

• multiple tags in one application command

• multiple fields in one application command

• constant data (all tags) or variable data (per tag) options

• lock option after write or verify

Support of many data types, such as:

• integer (char, short, long)

• strings

Name resolution

• User supplied text data field names, API determines physicaladdress, data size, and data type

• Hierarchical software tag type if desired

• Software tag type handling completely hidden from application

• Name resolution can be bypassed if desired

Selection equations for identification or write multiple

• equation is supplied as simple character string

• equation is parsed into a sequence of select and unselect commands

• can select all tags

• can select by software tag type, supports don't cares for hierarchical software tag type

• software tag type can be specified by number (with don't cares)or by text name

• can select by field data with name resolution

• supports all data types

• supports equal, not equal, greater than, and less than operations

2 NOMENCLATURE AND CONVENTIONS

This API uses a C language structure of type rfcontrol_t. The description of each routine contains a checklist of the fields in the structure that are used by the routine. The following terms are used with respect to the checklist:

require: The function uses this member and the value is typically set by the user (caller).

once: The function uses this member, but the value is typically set up once per application execution and is not changed during the execution of the application.

default: The function uses this member, but the value is typically the default,.

previous: The function uses this member, but the value is typically set by a previous function.

not used: The function does not use this member.

output: The function sets this member.

2 SUBROUTINE CALLS

1 SUBROUTINE rfopen()

1 Purpose

This subroutine opens the interface to the interrogator.

2 Synopsis

#include

#include

rfinterr_t *rfopen(InterrogatorName, Status, ErrorString, CustonInfoTable, CustomInfoFileName)

const char *InterrogatorName;

signed long *Status;

char *ErrorString;

void *CustomInfoTable;

char *CustomInfoFileName;

3 Description

The rfopen() subroutine establishes a connection between the workstation and a interrogator or set of interrogators. The opened interrogator descriptor is used by subsequent subroutines, such as rfread() and rfwrite(), to access the interrogator.

4 Parameters

InterrogatorName String indicating the interrogator name

Status Pointer to a long which can contain error status after the call completes.

ErrorString Pointer to a string which may contain textual error information after the call. If this pointer is non-NULL and the call fails, a string containing printable error information is returned. The maximum length is RF_ERROR_MAX-1.

CustomInfoTable If the pointer is non-NULL, this parameter points to a memory block that contains vendor specific data.

CustomInfoFileName If the pointer is non-NULL, this parameter points to a fully-qualified (including path) filename of a file containing vendor specific configuration data.

5 Return Values

Upon successful completion, a pointer to the opened interrogator descriptor structure, is returned. Otherwise, a NULL pointer is returned and the status is set to indicate the error.

6 Status Codes

RFE_DESC_NO_RFINTERR_MEMORY No memory could be allocated for the rfinterr_t descriptor structure.

RFE_DESC_NO_RFATTR_MEMORY No memory could be allocated for the rfattr_t descriptor structure.

RFE_CONFIG_OPEN The configuration file could not be opened.

RFE_CONFIG_FORMAT The configuration file format is incorrect.

RFE_CONFIG_CLOSE The configuration file could not be closed.

RFE_OPEN_DEBUG_LOG The debug log file could not be opened.

RFE_SET_DEBUG_LOG The debug log could not be set to line buffered.

RFE_INTERR_NAME_NOT_FOUND The interrogator name was not found in the configuration file.

RFE_OPEN_SW_TAG_TYPE_FILE The software tag type file could not be opened.

RFE_SWTT_TABLE_NO_MEMORY No memory could be allocated for the software tag type table.

RFE_SWTT_OVERFLOW Insufficient memory was allocated for the software tag type table. Change the configuration file. (May be changed.)

RFE_CLOSE_SW_TAG_TYPE_FILE The software tag type file could not be closed.

RFE_PORT_LOCKED The I/O port is already open by another process.

RFE_PORT_OPEN The I/O port could not be opened.

RFE_PORT_GETATTR Old attributes could not be obtained for the I/O port.

RFE_PORT_SETATTR New attributes could not be set for the I/O port.

RFE_PORT_BAUD The I/O port baud rate could not be set.

RFE_PORT_FLUSH The I/O port could not be flushed.

RFE_PORT_FLOW Hardware RTS/CTS flow control could not be set for the I/O port.

RFE_PORT_BLOCK_ERROR I/O port read blocking could not be changed for the port.

RFE_PORT_BREAK_ERROR A serial line break could not be processed for the I/O port.

RFE_INTERR_BAUD The interrogator baud rate could not be set.

RFE_INTERR_NOSYNC Initial contact could not be made with the interrogator.

RFE_INTERR_START The interrogator application did not start.

RFE_INTERR_ATTRIBUTE_REJECT An attribute was rejected by the interrogator.

RFE_ATTRIBUTE_REJECT An attribute was rejected by the API.

7 Related Information

The rfclose(), rfgetattr(), rfsetattr() subroutines.

2 SUBROUTINE rfclose()

1 Purpose

Closes the interrogator associated with an interrogator descriptor.

2 Synopsis

#include

#include

signed long rfclose(InterrogatorDescriptor, status)

rfinterr_t *InterrogatorDescriptor;

signed long *status;

3 Description

The rfclose() subroutine closes a connection between the workstation and a interrogator or set of interrogators associated with the InterrogatorDescriptor parameter. It also closes the debug log

associated with the descriptor, and frees other internally-allocated resources.

The rfclose() subroutine attempts to cancel outstanding asynchronous I/O requests on this interrogator descriptor. If the asynchronous I/O requests cannot be canceled, the application is blocked until the requests have completed. All open interrogator descriptors are closed when a process exits.

4 Parameters

InterrogatorDescriptor Specifies a valid open interrogator descriptor

Status Pointer to a long which can contain error status after the call completes.

5 Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the memory location pointed to by Status is set to indicate the error.

6 Status Codes

RFE_SET_ATTR_xx The interrogator attribute xx (to be described) could not be set.

RFE_PORT_GETATTR Old attributes could not be obtained for the I/O port.

RFE_PORT_SETATTR New attributes could not be set for the I/O port.

RFE_PORT_BAUD The I/O port baud rate could not be set.

RFE_INTERR_BAUD The interrogator baud rate could not be set.

RFE_INTERR_NOSYNC Initial contact could not be made with the interrogator.

RFE_PORT_UNLOCK The I/O port could not be unlocked.

RFE_PORT_FLUSH The I/O port could not be flushed.

RFE_PORT_CLOSE The I/O port could not be closed.

7 Related Information

The rfopen() subroutine.

3 rflog()

1 Purpose

Write data to the debug log associated with an interrogator descriptor.

2 Synopsis

#include

#include

signed long rflog(InterrogatorDescriptor, LogString, Status)

rfinterr_t *InterrogatorDescriptor;

char *LogString;

signed long *status;

3 Description

If logging is supported by the driver, the rflog() subroutine writes the informational null-terminated string pointed to by the LogString parameter to the debug log file. The debug log file is opened for the InterrogatorDescriptor as part of the rfopen() function. The rflog() function does not append a new-line character to the file, but rather assumes that any desired new-line characters are included in the string pointed to by LogString.

If logging is not supported by the driver, the rflog() subroutine must still be present in the library, but will take no action, other than to return a status code indicating that logging is not supported.

4 Parameters

InterrogatorDescriptor Specifies a valid open interrogator descriptor

LogString Points to the (null-terminated) string to be written to the log file.

Status Pointer to a long which can contain error status after the call completes.

5 Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the status is set to indicate the error.

6 Status Codes

RF_LOGGING_NOT_SUPPORTED The driver does not support logging.

7 Related Information

The rfopen() subroutine.

4 SUBROUTINE rfidentify()

1 Purpose

Identify RFID tags.

2 Synopsis

#include

#include

signed long rfidentify(InterrogatorDescriptor, ControlPointer)

rfinterr_t *InterrogatorDescriptor;

rfcontrol_t *ControlPointer;

3 Description

The rfidentify() subroutine identifies RFID tags in the field of view of the interrogator referred to by the InterrogatorDescriptor parameter using rules in the rfcontrol_t structure and stores results in the rfcontrol_t structure referenced by the ControlPointer parameter.

4 Parameters

InterrogatorDescriptor Specifies an open interrogator descriptor.

ControlPointer Points to an rfcontrol_t structure.

5 Control Structure Checklist

flag require

ostatus require

select_equation require (if RF_STORE_SELECTION_LIST flag is set)

taglist once

max_tags once

timeout_sec default

start_tag default

select_list_number default

valid_tags output/previous

end_tag output

status output

istatus not used

fields not used

field_status not used

field_status[n] not used

field_name not used

field_name[n] not used

tag_field_value not used

tag_field_value[n] not used

field_value not used

field_value[n] not used

physadrs not used

physadrs[n] not used

6 Applicable Control Flags

RF_STORE_SELECTION_LIST

RF_IDENTIFY_NO_OP

RF_IDENTIFY_STOP_AFTER_ALL_TRIES

RF_IDENTIFY_STOP_AFTER_ONE_IDENTIFIED RF_IDENTIFY_STOP_AFTER_ONE_DETECTED

RF_IDENTIFY_ALL_TAGS

RF_IDENTIFY_INCREMENTAL

7 Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the rfcontrol_t structure status is set to indicate the error.

8 Status Codes

RFE_ID_FULL_TAGLIST The API tag list is already full.

RFE_ID_NO_TAGLIST No tag list array was specified.

RFE_ID_NO_OSTATUS No ostatus array was specified.

RFE_ILLEGAL_FLAG An illegal control flag was specified.

RFE_SELECT_NO_EQUATION No select equation was specified and RF_STORE_SELECTION_LIST was specified.

RFE_SELECT_EQUATION A format error was found in the selection equation.

RFE_ILLEGAL_SWTAGTYPE_ENTRY A format error was found in the software tag type table when parsing a software tag type entry.

RFE_SWTAGTYPE_NOT_FOUND A software tag type matching the equation was not found.

RFE_ILLEGAL_NAME_ENTRY A format error was found in the software tag type table when parsing a name entry.

RFE_NAME_NOT_FOUND A name matching the equation was not found for the software tag type.

RFE_NAME_ADRS_ERROR An illegal value was detected for the address associated with the name.

RFE_NAME_SIZE_ERROR An illegal value was detected for the size, associated with the name.

RFE_NAME_TYPE_ERROR An illegal value was detected for the type associated with the name.

RFE_SELECT_REJECT An attempt was made to alter a interrogator select list which is in use.

RFE_SELECT_LIST_FULL An attempt was made to add a selection command to a full interrogator select list.

RFE_SELECT_ILLEGAL_LIST An invalid interrogator select list number was specified during the selection.

RFE_SELECT_ILLEGAL_COMMAND An attempt was made to add an illegal command to a interrogator select list.

RFE_EMPTY_SELECT_LIST_INTERR An identification was started with an empty interrogator select list.

RFE_ID_ILLEGAL_LIST An invalid interrogator select list number was specified during the identification.

RFE_ID_LIST_FULL_INTERR The interrogator ID list holding identified tags is full.

RFE_COMMAND_REJECT The identification command was rejected by the interrogator.

RFE_ILLEGAL_BYTE_COUNT An illegal byte count was specified to the interrogator.

RF_PANIC_VALID_GE_MAX_1 An internal driver error was detected.

RF_PANIC_ILLEGAL_EQUATION_OPERATION_1 An internal driver error was detected.

RF_PANIC_ILLEGAL_EQUATION_OPERATION_2 An internal driver error was detected.

RF_PANIC_ILLEGAL_NAME_TYPE_3 An internal driver error was detected.

RF_PANIC_SWTAGTYPE_ENTRY_ERROR An internal driver error was detected.

9 File

rfid.h Contains the rfcontrol_t structure and values.

10 Related Information

The rfget_control(), rfread(), and rfwrite() subroutines.

The rfid.h file.

5 rfread() and rfwrite()

1 Purpose

Read or write RFID tags.

2 Synopsis

#include

#include

signed long rfread(InterrogatorDescriptor, ControlPointer)

rfinterr_t *InterrogatorDescriptor;

rfcontrol_t *ControlPointer;

signed long rfwrite(InterrogatorDescriptor, ControlPointer)

rfinterr_t *InterrogatorDescriptor;

rfcontrol_t *ControlPointer;

3 Description

The rfread() and rfwrite() subroutines read or write RFID tags in the field of view of the interrogator referred to by the InterrogatorDescriptor parameter using rules in the rfcontrol_t structure and stores results in the rfcontrol_t structure referenced by the ControlPointer parameter.

4 Parameters

InterrogatorDescriptor Specifies an open interrogator descriptor.

ControlPointer Points to an rfcontrol_t structure.

5 Control Structure Checklist

1 Checklist for rfread(), rfwrite() non-multiple:

flag require

istatus require

ostatus require

fields require

field_name[n] require

tag_field_value[n] require (array data)

field_value[n] require (constant data)

taglist once

max_tags once

field_name once

tag_field_value once (array data)

field_value once (constant data)

timeout_sec default

start_tag default

field_status default

field_status[n] default

physadrs default

physadrs[n] default

valid_tags previous

end_tag previous

status output

select_equation not used

select_list_number not used

2 Checklist for rfwrite() with Multiple Tags

flag require

istatus require

ostatus require

select_equation require

fields require

field_name[n] require

field_value[n] require

taglist once

max_tags once

field_name once

field_value once

timeout_se default

start_tag default

select_list_number default

field_status not used

field_status[n] not used

physadrs not used

physadrs[n] not used

tag_field_value not used

tag_field_value[n] not used

valid_tags output

end_tag output

status output

6 Applicable Control Flags

RF_STORE_SELECTION_LIST rfwrite() multiple tags

RF_READ_DATA rfread()

RF_READ_AND_VERIFY rfread()

RF_RW_CONSTANT rfread(), rfwrite() non-multiple, rfwrite() multiple

RF_RW_ARRAY rfread(), rfwrite() non-multiple

RF_LOCK_DATA rfread(), rfwrite() non-multiple

RF_UNLOCK_DATA rfread(), rfwrite() non-multiple

RF_WRITE_TAGLIST rfwrite() non-multiple

RF_WRITE_MULTIPLE rfwrite() multiple

RF_WRITE_MULTIPLE_START rfwrite() multiple

7 Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the rfcontrol_t structure is set to indicate the error.

8 Status Codes

RFE_ILLEGAL_FLAG An illegal control flag was specified.

RFE_RW_VALUE_NULL A null field_value or tag_field_value entry was specified.

RFE_RW_START_PAST_END The start_tag entry is greater than the end_tag entry.

RFE_RW_END_PAST_VALID The end_tag entry is greater than the valid_tags entry.

RFE_RW_END_PAST_MAX The end_tag entry is greater than the max_tags entry.

RFE_RW_NO_FIELDS The fields entry is zero.

RFE_RW_ISTATUS_NULL The input status pointer is null.

RFE_RW_OSTATUS_NULL The output status pointer is null and one of the field_status pointers is null.

RFE_RW_NAME_RESOLUTION Name resolution is bypassed (a field_name pointer is null) and one of the physadrs pointers is also null.

RFE_RW_NAME_NUL A field name is a zero length string.

RFE_NO_MEMORY Memory could not be allocated for temporary status or name resolution results.

RFE_SELECT_NO_EQUATION No select equation was specified and

RF_STORE_SELECTION_LIST was specified.

RFE_SELECT_EQUATION A format error was found in the selection equation.

RFE_ILLEGAL_SWTAGTYPE_ENTRY A format error was found in the software tag type table when parsing a software tag type entry.

RFE_SWTAGTYPE_NOT_FOUND A software tag type matching the equation was not found.

RFE_ILLEGAL_NAME_ENTRY A format error was found in the software tag type table when parsing a name entry.

RFE_NAME_NOT_FOUND A name matching the equation was not found for the software tag type.

RFE_NAME_ADRS_ERROR An illegal value was detected for the address associated with the name.

RFE_NAME_SIZE_ERROR An illegal value was detected for the size, associated with the name.

RFE_NAME_TYPE_ERROR An illegal value was detected for the type associated with the name.

RFE_EMPTY_SELECT_LIST_INTERR The interrogator select list was empty.

RFE_INVALID_SELECT_LIST An invalid interrogator select list number was specified.

RFE_ID_LIST_FULL_INTERR The interrogator ID list holding tags failing the write multiple is full.

RFE_COMMAND_REJECT The command was rejected by the interrogator.

RF_PANIC_VALID_GE_MAX_2 An internal driver error was detected.

RF_PANIC_ILLEGAL_NAME_SIZE_1 An internal driver error was detected.

RF_PANIC_ILLEGAL_NAME_TYPE_1 An internal driver error was detected.

RF_PANIC_ISTATUS_NULL_1 An internal driver error was detected.

RF_PANIC_ILLEGAL_NAME_SIZE_2 An internal driver error was detected.

RF_PANIC_ILLEGAL_NAME_TYPE_2 An internal driver error was detected.

RF_PANIC_ILLEGAL_EQUATION_OPERATION_1 An internal driver error was detected.

RF_PANIC_ILLEGAL_EQUATION_OPERATION_2 An internal driver error was detected.

RF_PANIC_ILLEGAL_NAME_TYPE_3 An internal driver error was detected.

RF_PANIC_SWTAGTYPE_ENTRY_ERROR An internal driver error was detected.

9 Files and Related Information

The rfget_control() and rfidentify() subroutines.

The rfid.h file, which contains the rfcontrol_t structures and values

6 rfgetattr() and rfsetattr()

1 Purpose

Gets or sets interrogator state or parameters.

2 Synopsis

#include

#include

signed long rfgetattr (InterrogatorDescriptor, AttributePointer,status)

signed long rfsetattr (InterrogatorDescriptor, AttributePointer,status)

rfinterr_t *InterrogatorDescriptor;

rfattr_t *AttributePointer;

signed long *status;

3 Description

The rfgetattr() subroutine gets the parameters associated with the interrogator referred to by the InterrogatorDescriptor parameter and stores them in the rfattr_t structure referenced by the AttributePointer parameter. The rfsetattr subroutine sets the parameters associated with the interrogator referred to by the InterrogatorDescriptor parameter from the rfattr_t structure referenced by the AttributePointer parameter.

Most attributes are non-volatile. Once set, they are never altered by the interrogator. Therefore, only attributes which are being changed need to be transmitted to the interrogator.

4 Parameters

InterrogatorDescriptor Specifies an open interrogator descriptor.

AttributePointer Points to an rfattr structure.

5 Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the status is set to indicate the error.

6 Status Codes

RFE_INTERR_ATTRIBUTE_REJECT An attribute was rejected by the interrogator.

RFE_ATTRIBUTE_REJECT An attribute was rejected by the API.

7 File

rfid.h Contains the rfattr_t structure.

8 Related Information

The rfopen() subroutine.

7 rfget_control()

1 Purpose

This routine initializes the rfcontrol_t structure with default values.

2 Synopsis

#include

#include

signed long rfget_control(ControlPointer)

rfcontrol_t *ControlPointer;

3 Description

The rfget_control() subroutine initializes the rfcontrol_t structure referenced by the ControlPointer parameter. This subroutine may be used to initialize the structures to default values before setting members to application specific values. This assures source code compatibility with future software releases.

4 Parameters

ControlPointer Points to an rfcontrol_t structure.

5 Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned.

6 Status Codes

No error codes have been defined for this routine at the time of this writing.

7 File

rfid.h Contains the rfcontrol_t structure and values.

8 Related Information

The rfidentify, rfread(), and rfwrite() subroutines.

The rfid.h file.

3 DATA STRUCTURES

1 DATA STRUCTURE OVERVIEW

Arguments are generally passed to functions in the form of RFID API specific structure pointers, rather than as a list of values or value pointers. Advantages to this approach include:

• Backward compatibility as the API evolves. By including helper functions in the API which set the structures to default values, members can be added to support new features without breaking existing application code.

• Performance is improved by passing one pointer to a structure rather than passing a long parameter list.

• Since fields are referenced by name, the application code is more nearly self-commenting and less error prone. With a long parameter list, it would be easy to reverse the order of or omit a parameter.

• The same main control structure is used for the main RFID commands (rfidentify, rfread(), rfwrite). Once the user learns the structure, all 3 commands are easily understood.

• The same limited number of structures are passed down through the layers of API and driver code. Each layer uses input fields and updates output fields as appropriate. This leads to simpler maintenance of the API and driver.

2 STRUCTURE rfcontrol_t

The structure rfcontrol_t is the main control structure which the application uses with the

rfidentify, rfread(), and rfwrite() functions. The structure is defined as follows:

typedef struct {

unsigned long flag; /* function rules */

unsigned long timeout_sec; /* maximum allowed time */

rftaglist_t *taglist; /* pointer to tag list */

size_t start_tag; /* first tag to be processed */

size_t end_tag; /* last tag to be processed */

size_t valid_tags; /* number of valid taglist entries */

size_t max_tags; /* maximum size of taglist */

signed long status; /* overall function status */

rfstatus_t *istatus; /* pointer to input status list */

rfstatus_t *ostatus; /* pointer to output status list */

rfstatus_t **field_status; /* pointer to array of arrays of status */

rfstatus_t **field_status_save; /* to saved field_status */

unsigned long select_list_number; /* the selection list number */

char *select_equation; /* pointer to select list */

size_t fields; /* number of fields names */

char **field_name; /* pointer to arrays of names */

void **tag_field_value; /* pointer to array of arrays of values*/

void **field_value; /* pointer to array of constant values */

rfphysadrs_t **physadrs; /* pointer to array of arrays of address*/

rfphysadrs_t **physadrs_save; /* to saved physadrs */

rfaccess_id_t **access_ids; /* ptr to array of lists of passwds (access IDs)*/

void *custom_table; /* ptr to vendor-specific config data */

char *cust_file_name; /* ptr to name of vendor-specific cfg file */

} rfcontrol_t;

The rfcontrol structure passes identification, read, or write rules to their functions and returns results. The structure members are described in the sections to follow.

1 Structure Member flag

The member flag describes the rules to be followed by rfidentify, rfread(), and rfwrite(). It is unchanged by the API / driver.

The values for flag are described below:

RF_STORE_SELECTION_LIST Indicates that a new selection list should be stored in the interrogator. If used in combination with an identification or write multiple flag, the new list is stored before the identify or write is performed. This value should not be used in conjunction with RF_IDENTIFY_INCREMENTAL.

When a write multiple is issued, name resolution determines the physical addresses (write address and possibly selection address) associated with the software tag type in the selection equation. The result is downloaded to the interrogator. This downloaded result can be used multiple times by issuing a write multiple without a storing a selection list.

Since the write data size and type is tied to the software tag type included in the selection equation, the equation must be present even if it is not being stored.

RF_IDENTIFY_NO_OP

RF_IDENTIFY_STOP_AFTER_ALL_TRIES

RF_IDENTIFY_STOP_AFTER_ONE_IDENTIFIED

RF_IDENTIFY_STOP_AFTER_ONE_DETECTED

These rfidentify flags are mutually exclusive.

RF_IDENTIFY _NO_OP no identification is performed, but the select list may be stored.

RF_IDENTIFY _AFTER_ALL_TRIES runs all identification tries.

RF_IDENTIFY _AFTER_ONE_IDENTIFIED skips unused tries after at least one tag is identified.

RF_IDENTIFY _AFTER_ONE_DETECTED stops after a tag is detected, without actually identifying it.

RF_IDENTIFY_INCREMENTAL, RF_IDENTIFY_ALL_TAGS

These rfidentify flags are mutually exclusive and active when RF_IDENTIFY_STOP_AFTER_ALL_TRIES is set.

RF_IDENTIFY_ALL, identifies and reports all selected tags in the field-of-view.

RF_IDENTIFY_INCREMENTAL reports only tags not previously reported.

RF_READ_DATA, RF_READ_AND_VERIFY

These rfread() flags are mutually exclusive.

RF_READ_DATA performs reads and fills in the tag_field_value arrays.

RF_READ_AND_VERIFY performs reads and verifies the data against one of two sources.

RF_RW_CONSTANT, RF_RW_ARRAY

These rfread() and rfwrite() flags are mutually exclusive.

For rfread(), RF_RW_CONSTANT verifies read data against constants in the field_value member. RF_RW_ARRAY verifies read data against values in the tag_field_value array.

For rfwrite(), RF_RW_CONSTANT writes constant data specified in the field_value member. RF_RW_ARRAY writes data specified in the tag_field_value array.

RF_LOCK_DATA, RF_UNLOCK_DATA

These rfread() and rfwrite() flags are mutually exclusive. They are active for rfwrite() or rfread() if RF_READ_AND_VERIFY is set.

RF_LOCK_DATA locks a data field which verifies correctly. Fields which do not verify are not locked.

RF_UNLOCK_DATA unlocks a data field.The unlock function may be disabled by hardware or software for security. In these cases, where a lock is irreversible, an error status will be returned.

RF_WRITE_TAGLIST, RF_WRITE_MULTIPLE

These rfwrite() flags are mutually exclusive.

RF_WRITE_TAGLIST (non-multiple) writes to tags based on the taglist.

RF_WRITE_MULTIPLE writes to tags based on selection criteria.

RF_WRITE_MULTIPLE requires the fields member to be 1 and the RF_RW_CONSTANT flag. If RF_STORE_SELECTION_LIST is set, the write is based on the specified selection criteria and field name. If RF_STORE_SELECTION_LIST is clear, the write is based on the previously set up selection criteria and field name.

RF_WRITE_MULTIPLE_START

This rfwrite() flag is active when RF_WRITE_MULTIPLE is set. If set, the write multiple is started. If clear, the write multiple is not started, but the selection list may be loaded.

RF_SET_ACCESS_ID

This rfread() and rfwrite() flag is used to indicate that access IDs for specified tag fields are to be set to the new values that are provided in the passwords member of the rfcontrol_t structure.

2 Structure Member timeout_sec

The member timeout_sec holds the maximum in seconds allowed time for the command. A value of zero disables the timeout. Zero should typically be used unless the application desires to abort infinite identification tries after a specified time. It is unchanged by the API / driver.

3 Structure Member taglist

This member is initialized to point to the array of rftaglist_t structures. The pointer is unchanged by the API / driver.

For calls to rfidentify(), the array is filled in with the tag identification data. The array size should be at least equal to max_tags.

For rfread() or rfwrite() (non-multiple), it points to the array of target tags for the rfread() or rfwrite(). The array elements are unchanged by the API / driver.

For write multiple, the array is filled in with failing tag identifiers.

4 Structure Member start_tag

This member indexes the first taglist entry to be processed. It is unchanged by the API / driver.

For non-incremental rfidentify() or rfwrite() multiple, it is initialized to the next taglist element to be written. It is typically initialized to zero. For incremental rfidentify(), it is not used. For rfread() and rfwrite() (non-multiple), it is initialized to the first taglist element to be processed. To read or write the entire list, it is typically zero.

5 Structure Member end_tag

This member is initialized to index the last taglist entry to be processed plus 1.

For rfidentify() or rfwrite() (multiple), it is not initialized. It is written by the API / driver to valid_tags.

For rfread() and rfwrite() (non-multiple), it is initialized to the last taglist element to be processed plus 1. To read or write the entire list, it is typically valid_tags. It must be less than or equal to

valid_tags. It is unchanged by the API / driver.

6 Structure Member valid_tags

The structure member valid_tags is an index to the last valid taglist element plus 1 (assuming that taglist is a zero-based array). Equivalently, it holds the number of valid entries in the taglist, assuming that the application started at element 0.

For calls to non-incremental rfidentify() and rfwrite() (multiple), vaild_tags is not initialized. For incremental rfidentify, it indicates the next taglist element to be written. It is updated by the API/driver.

For rfread() and rfwrite() (non-multiple), it is initialized to provide a check against end_tag. It is typically the valid_tags output of the rfidentify(). It is unchanged by the API/driver.

7 Structure Member max_tags

The structure member max_tags initialized to the maximum number of elements in the taglist. It is also related to istatus and ostatus, so the length of those arrays must match. It is unchanged by the API/driver.

For the routines rfidentify() or rfwrite() (multiple), max_tags determines the last tag to be returned from the identification process, which should be no greater than the size of the taglist. A zero value indicates that only overall status is returned.

8 Stucture Member status

The member status, not initialized and written by the API, holds the overall status of the rfidentify, rfread(), or rfwrite() process. These routines return a value of 0 to indicate overall success.

For functions using the flag RF_IDENTIFY_STOP_AFTER_ONE_DETECTED, status describes the result. Zero indicates none detected and one indicates at least one detected.

A function return code of -1 indicates an overall error. The status describes the error.

Error status includes the following:

RFE_BADF The InterrogatorDescriptor parameter does not specify a valid interrogator descriptor.

RFE_NO_MEMORY Memory cannot be temporarily allocated.

RFE_ILLEGAL_FLAG An illegal flag or combination of flags was specified.

RFE_COMMAND_REJECT A command to the radio was rejected. This may occur if the interrogator is not ready to accept commands.

RFE_NO_SELECT_LIST The select_list member is null and the RF_STORE_SELECT_LIST flag is set.

RFE_ID_INVALID_SELECT The selection string cannot be parsed.

RFE_INVALID_SELECT_LIST The interrogator cannot support the specified selection list number.

RFE_ILLEGAL_BYTE_COUNT The interrogator cannot support the specified number of read or write bytes.

RFE_ID_EMPTY_SELECT_LIST_INTERR The interrogator select list is empty. It must be stored before it is used.

RFE_ID_NO_TAGLIST The taglist member is null and the identified tags are to be returned. There is no place to store the returning tag data.

RFE_ID_NO_OSTATUS The ostatus member is null and the identified tags are to be returned. There is no place to store the returning status.

RFE_ID_FULL_TAGLIST The value of the start_tag member is not less than the value of the max_tags member.

RFE_ID_LIST_FULL The interrogator memory allocated for identification became full before all tags were identified. This is most likely the result of multiple incremental identifications.

RFE_RW_END_PAST_VALID The end_tag member is greater than the valid_tags member.

RFE_RW_END_PAST_MAX The value of the end_tag member is greater than the value of the max_tags member.

RFE_RW_NO_FIELDS The fields member is zero.

RFE_RW_NAME_RESOLUTION Neither absolute tag field information nor field name resolution members are provided.

RFE_RW_NAME_NUL A field name provided for name resolution is a zero-length string.

RFE_RW_ISTATUS_NULL The input status pointer istatus is NULL. For rfread() and rfwrite(), input status must be available.

RFE_RW_OSTATUS_NULL For rfread() and rfwrite(), output status must be reported for each field. If the summary status pointer ostatus is NULL and one element of field_status is NULL, there is no array allocated to hold the status.

RFE_WRITE_NOT_CONSTANT The RF_WRITE_MULTIPLE flag requires the RF_RW_CONSTANT flag, since write multiple requires constant data.

RFE_WRITE_FIELDS For a write multiple, fields must be one. The API does not support write multiple to more than one field at a time.

9 Stucture Member istatus

For rfread() and rfwrite() (non-multiple), the structure member istatus holds the input

status array. Input status is not altered by the API.

A zero indicates that the target tag should be processed. A non-zero value inhibits processing.

When processing is inhibited, the input status is copied to the output status.

10 Stucture Member ostatus

The member ostatus points to the array of rfstatus_t entries which will be filled in with the status of the rfidentify(), rfread(), or rfwrite() for each tag. A zero value indicates normal completion.

Errors include (sample list, to be updated):

RF_ID_READ_ERROR The tag was identified but associated data may be incorrect.

RF_FIELD_NOT_FOUND One of the field names could not be resolved into a physical address, length, and type.

RF_FIELD_ADRS_ERROR The field address determined by name resolution is beyond the range handled by the interrogator.

RF_FIELD_SIZE_ERROR The field size determined by name resolution is beyond the range handled by the interrogator.

RF_FIELD_TYPE_ERROR The field type determined by name resolution is not one of the types handled by the API, integer or string.

RF_READ_ERROR One of the fields could not be successfully read.

RF_VERIFY_ERROR One of the fields did not data verify correctly.

RF_WRITE_ERROR One of the fields could not be successfully written.

RF_WRITE_TAG_ERROR One of the fields had the write rejected by the tag. For example, the field might be locked.

RF_LOCK_ERROR One of the fields could not be locked successfully.

RF_LOCK_VERIFY_ERROR One of the fields did not lock verify correctly.

RF_WRITE_LOCKED One of the fields is locked.

RF_PSWD_MISSING One of the fields identified in the operation is access_id protected but no access_id was provided for the field. Whether the missing access_id was a read access_id or a write access_id depends on the operation that resulted in this condition.

RF_PSWD_INCORRECT One of the fields identified in the operation was access_id protected but the access_id provided the field was incorrect. Whether the incorrect access_id was a read access_id or a write access_id depends on the operation that resulted in this condition.

11 Stucture Member field_status

The member field_status is a pointer to an array. Each array element corresponds to one field, and holds a pointer to an array. Each element of this final array of rfstatus_t entries corresponds to one tag. The entries are filled in with the status of the rfread() or rfwrite() for each field of each tag. A zero value indicates normal completion. For other status codes, see ostatus.

Output status can be obtained for each tag (ostatus) or each field of each tag (field_status).

If the ostatus entry is a non-NULL pointer, its array is filled in with tag summary status. If the ostatus entry is NULL (rfread() or rfwrite()), all elements of field_status must be non-NULL. That is, status for a field cannot be completely ignored.

If the field_status, pointer is non-NULL, its elements are examined. If an element is non-NULL, its array is filled in status for the field.

12 Stucture Member field_status_save

The field_status_save member is used internally by the API / driver. It need not be initialized, and its value on exit is unspecified.

13 Stucture Member select_list_number

The select_list_number member holds the select list number. On the interrogator, select lists hold the tag selection criteria. A select list can be used multiple times if the selection criteria are not changed.

Selection criteria are applicable to rfidentify() and rfwrite() multiple.

The API supports select lists 0-255. A given interrogator will typically support fewer.

14 Stucture Member select_equation

The select_equation member points to the selection criteria character string. An empty string indicates that all tags should be selected.

Section 4 of this document describes the select equation format.

15 Stucture Member fields

The fields member contains the number of data fields to be processed for each tag by rfread() and rfwrite() (non-multiple) calls. It is not changed by the API/ driver.

One function call can process multiple data fields.

This member is used by the API / driver in accessing the field_name, tag_field_value, field_value, field_status, and physadrs structure members. Therefore, the size of those arrays must match.

For write multiple, fields must be set to 1.

16 Stucture Member field_name

A field name is the textual name for a tag data field. The API resolves the textual name into a physical tag address, size, and type.

When used as a parameter to rfread() and rfwrite(), the field_name member contains a pointer to an array. Each array element is a pointer to a NUL terminated character string. The string describes a field name. Neither the pointers nor the names are altered by the API / driver

A zero length string is considered an error.

17 Stucture Member field_value

A constant data value for each field can be used for an rfread() verify or an rfwrite() call. It must be used for write multiple, where the data written to each tag must be the same.

The member field_value contains a pointer to an array. Each array element (one for each field) is a pointer to a data value. Neither the pointers nor the values are altered by the API / driver.

The size of the data value must match the size of the data field. For integers, sizes of 1, 2, 3, and 4 bytes are supported. The API assumes the following array element size based on the size of the data field.

1: byte

2: short

3: long

4: long

For short and long elements, unused bytes are ignored on write and verify, but a warning is issued to the debug log if ignored bytes have non-zero bits.

18 Sucture Member tag_field_value

The member tag_field_value is used as an input to rfread(), and holds data to be verified against data read from the tag. The data is not altered by the API / driver.

The member tag_field_value when used as an input to rfwrite(), holds data to be written to the tag. It is only used for non-multiple writes, where the data written to each tag may be different. It is not altered by the API / driver.

The member tag_field_value is a pointer to an array. Each array element corresponds to one field, and holds a pointer to an array. Each element of this final array corresponds to one tag. The pointers are not altered by the API / driver.

Since the array type varies with the data type, it cannot be passed to the API. It is determined from the name resolution size and type.

1 - Integer type Sizes of 1, 2, 3, and 4 bytes are supported. The API assumes the following array element size based on the size of the data field.

1: byte

2: short

3: long

4: long

For short and long elements, unused bytes are set to zero on read. Unused bytes are ignored on write and verify, but a warning is issued to the debug log if ignored bytes have non-zero bits.

2 - String type To support NUL terminated strings, the size of each element must be the size of the data field plus 1.

For operations where the array is an input to the API (e.g. write), bytes are read by the API up to the size of the data field. The extra byte (typically a NUL character, but not checked) is ignored. NUL bytes within the string are also ignored.

For operations where the array is an output from the API (e.g. read), bytes are written by the API up to the size of the data field, and a NUL character is written to the extra byte.

19 Stucture Member access_ids

The structure member access_ids is a pointer to an array. Each element in the array corresponds to one tag field and holds a pointer to an array of rfaccess_id_t structures. Each element of this final array corresponds to one tag.

The rfaccess_id_t structure holds a pointer to a current access_id and a pointer to a new access_id. These two access_id pointers are void pointers that point to an appropriate access_id type for the tag being addressed.

Whether the access_ids contained in the access_ids member of the rfcontrol_t structure are read access_ids or write access_ids depend on the tag operation being performed.

The current_access_id element of the rfaccess_id_t structure contains the current access_id for the specific tag field being referenced. The current_access_id field should be supplied for reads and writes from or to tag fields that have been access_id protected.

The new_access_id element of the rfaccess_id_t structure contains a new access_id for a specific tag field. The new_access_id field should be supplied for any read or write operation that is intended to change a specific tag field’s access_id to a new value (as determined by setting the RF_SET_ACCESS_ID flag.)

The new_access_id element of the rfaccess_id_t structure is also used to remove access_id protection from a specific tag field. This is accomplished by setting the new_access_id element equal to NULL for the desired tag field.

20 Stucture Member physadrs

The structure member physadrs is a pointer to an array of structures of type rfphysadrs_t. Each element of physadrs corresponds to one field of a tag. The rfphysadrs_t structure holds the field address, size, and type which result from name resolution. The element address of the rfphysadrs_t stucture is the absolute tag memory address of a field. The element size of the structure is the size in bytes of the field. The element type describes the data format.

Note about name resolution: If fields are accessed through the field_name member, the API translates this name into an absolute tag address, size, and type. This process is called name resolution, and requires a data base lookup based on the software tag type associated with the tag.

There are times that the application may wish to bypass name resolution, possibly to improve performance. One example might be a captive application where the software tag type is predetermined. Another example is a read-modify-write operation where the name resolution during the read can be reused during the write.

If the field_name pointer is NULL, name resolution is bypassed. If field_name is non-NULL, but one of the pointer entries in the array (for one field) is NULL, name resolution is bypassed for that field.

If both field_name and the field_name array entry are non-NULL, name resolution is performed for that field. If not, the physadrs member is checked. If the physadrs pointer is NULL, the API must perform name resolution for all fields. If name resolution is bypassed for any field, an error is reported.

If the physadrs pointer is non-NULL, the array is checked. If an element of the array (one element for each field) is NULL, the API / driver cannot not use that field. If name resolution is bypassed for that field, an error is reported.

If all elements for a field are non-NULL, the API can use the physadrs array for that field. The API uses the array in one of two ways.

1 - If name resolution is enabled for that field, the contents of the array (the physadrs_t structures) are ignored by the API. Instead, they are written with the results of the name resolution.

2 - If name resolution is bypassed for that field, the absolute address, size, and type are used for that field. If an individual tag element is invalid, an error is reported for that tag only.

21 Stucture Member cust_table

The structure member cust_table is a pointer to a table that contains vendor-specific configuration data. This member is a void pointer, which allows applications to pass through to the driver pointers to vendor-specific (and vendor-defined) data structures, without altering the definition of the API for each vendor.

22 Stucture Member cust_file_name

The structure member cust_file_name is a pointer to a string containing the name of a file that contains custom (manufacturer-specific) configuration data.

3 STRUCTURE rfphysadrs_t

The structure rfphysadrs_t contains name resolution information, as described in the synopsis of the physadrs member of the rfcontrol_t structure. The rfphysadrs_t structure is defined as follows:

typedef struct {

unsigned long adrs;

unsigned long size;

unsigned long type;

} rfphysadrs_t;

4 STRUCTURE rfaccess_ids_t

The structure type rfaccess_ids_t is described in the synopsis of the access_ids member of the rfcontrol_t structure type. The definition of the rfaccess_id_t structures type is as follows:

typedef struct{

void *current_access_id;

void *new_access_id;

} rfaccess_ids_t;

5 STRUCTURE rfattr_t

The structure type rfattr_t is used as a parameter to the functions rfsetattr() and rfgetattr() functions. A copy of this structure is maintained internally by the API / driver for each open interrogator. It is initialized by rfopen(), changed by rfsetattr(), and read by rfgetattr(). The definition of the structure is as follows:

typedef struct {

unsigned char select_tries;

unsigned char unselect_tries;

unsigned char identification_tries;

unsigned char id_antenna_tries;

unsigned char read_tries;

unsigned char write_tries;

unsigned char lock_tries;

unsigned char write_multiple_tries;

unsigned char address_range_check;

unsigned char hw_tag_type_check;

unsigned char field_strength;

unsigned char antennas[8];

unsigned char debug;

unsigned long simulated_tags;

unsigned char simulate_errors;

unsigned long baud;

} rfattr_t;

A detailed description of the fields can be found in the interrogator documentation.

6 STRUCTURE rfstatus_t

The type rfstatus_t is used for reporting function status.

typedef signed long rfstatus_t;

Negative numbers are reserved for error conditions set by the API / driver.

Positive numbers are user defined.

4 SELECTION EQUATION AND TAG TYPE TABLE

1 SELECTION EQUATION

The selection equation is used by the identification and write (multiple) processes. The equation is a NUL terminated string.

1 Selection Equation Forms

Four forms are supported.

Form 1:

"" (A NULL string).

This form causes all tags in the field-of-view to be selected.

Form 2:

"SWTAGTYPE == 0303xxxxxxxx"

This form causes all tags with the software tag type equal to this value to be selected (xx indicates a don't care). The value must begin with a number.

Form 3:

"SWTAGTYPE == TRANSPORT.PACKAGE"

This form operates in the same manner as Form 2, but with the software tag type defined by name rather than by value. The name must begin with an uppercase letter.

Form 4:

"SWTAGTYPE == TRANSPORT.PACKAGE && ZIP != 068"

"SWTAGTYPE == 0303xxxxxxxx && ZIP != 068"

Tag selection is based on software tag type and one arithmetic operation on one field which exists for the software tag type.

2 Tokens

The forms described in Section 4.1.1 are comprised of tokens. Equation tokens (name, logical and arithmetic operator, values) are separated by white space (space, tab).

Tokens 1 and 2:

For forms 2, 3, and 4, the first token must be SWTAGTYPE and the second token must be ==. That is, for all but form 1, part of the expression must be selection based on a software tag type.

Token 3:

For forms 3 and 4, Token 3 can be software tag type text. This text must match a software tag type table entry. The text is mapped to a software tag type number, which may include don't cares. For forms 2 and 4, Token 3 can be a software tag type number. The number is a hexadecimal number (lowercase), where xx indicates a don't care byte.

Token 4:

For form 4, Token 4 must be &&. That is, type 4 selects based upon a software tag type and one named field.

Token 5:

Token 5 is a name, which must match a software tag type table name which is valid for the selected software tag type.

Token 6:

Token 6 is an arithmetic operation. Supported operations are:

== equal

!= not equal

> greater than

< less than

Token 7:

Token 7 is a value (on which operations can be performed). Operations on integer fields are straightforward. The token is treated as a decimal number, and converted to a one-, two-, three-, or four-byte unsigned integer based on the size obtained from the software tag type table.

Integer values must be the numbers 0-9. For string fields, the value in the equation is converted a null-terminated ASCII string. Arithmetic operations are performed up to the length of the string in the equation or the size of the field, whichever is less.

String values use any printable ASCII character.

For example, this software tag type table entry describes a ZIP code as a 10 byte string:

ZIP+4 10 s

A typical value might be 06850-2318.

If the equation includes "... && ZIP != 068", selection is based upon only the first 3 bytes, ignoring the other 7.

3 Select List Number

The interrogator retains selection criteria, which can be referred to by a structure member called select_list_number. If the selection criteria have not changed, they can be specified by number, avoiding reforming and storing the selection list.

For a new equation, it can be stored in the interrogator prior to or as part of an identification or write multiple process.

2 Tag Type Table

The software tag type table has two functions:

1 - Tag selection - This maps textual tag selection equations into tag group select and group unselect commands.

2 - Name resolution - This maps the logical (textual) name of a field to a physical tag memory addresses.

The table has the following entries:

Software tag type number: The software tag type determines the field names present on a tag. Given the field name, it determines the tag physical memory location, size, and the type of field. The software tag type is a series of six hex numbers (using lowercase) with the leftmost number at the lowest address. Type 000000000000 is reserved. The value xx indicates a don't care byte.

Note: This definition presumes that the mapping is independent of the hardware tag type. Tags might be accessed differently depending upon the hardware tag type, but the names should be at the same address. This further assumes that names relocate based on the software tag type, but that the size, content, and format remains the same for a logical name.

Software tag type name: This is a dotted character string (using uppercase), with a field for each byte. There is a one to one correspondence between numbers and names. Don't care names are omitted. The name gives an alternate means of describing a software tag type which might be more natural for an application. Lowercase is used for the number and uppercase for the name. This allows the API to determine that the software tag type feeddeadbeef is a hexadecimal umber and not a name.

Logical Name: The textual name of the field. Names are case sensitive.

Address: The physical byte address of the field. For multibyte addressing, the lowest address is used. Addresses are specified in hexadecimal.

Size: The size in bytes of the field.

Integers of 1, 2,3 or 4 bytes are supported. Strings of 1 to 32 bytes are supported.

Type: The type of the field can be either a string or an integer.

The most significant byte of integers is written or read at the lower address on the tag. For strings, data is written or read in order of byte address on the tag. The workstation endian type is irrelevant.

Note: A C language character string is a null-terminated ASCII character array. If the length of the string including the null is not equal to the size of the data field, during selection, string data is matched up to the size of the equation value or the size of the field, whichever is smaller.

For read and write, the size of the field is used.

Sample Software Tag Type Table

# SW Tag Type Name Adrs Size Type

01xxxxxxxxxx MANUF

UPC 10 4 i

MFGR 14 2 i

SECURITY 16 1 i

0101xxxxxxxx MANUF.SOURCE

MODEL 20 2 i

0102xxxxxxxx MANUF.DIST

PO 20 4 i

0103xxxxxxxx MANUF.RETAIL

SALE_DATE 20 6 s

PRICE 2a 2 i

02xxxxxxxxxx PERSON

NAME 10 32 s

03xxxxxxxxxx TRANSPORT

0301xxxxxxxx TRANSPORT.PALLET

PO 10 8 i

0302xxxxxxxx TRANSPORT.BOX

PO 10 8 i

0303xxxxxxxx TRANSPORT.PACKAGE

ZIP 10 20 s

METHOD 1a 1 s

5 API CODE EXAMPLES

1 INTRODUCTION TO CODE EXAMPLES

These examples show the fundamental features of the API. They omit more advanced features and error checking for clarity. In the examples,

• The user never needs to manipulate the tag list, know about sw tag types, or even how many tags were identified.

• Incremental identification is trivial. No tag list manipulation is required.Upon return, read and write functions can be called as before. The updated list is automatically used.

• Identification status (failing tags) are passed to the read and write operations effortlessly. Following read and write operations are skipped with no user code required.

• It's not much harder to read or write 3 fields than 1. Just specify how many to read, what the names are, and where the results should go. (See example 5).

• Data is returned in the user's natural format (char, short, long, string).

• Nearly all the structure members can be set up once at the top of the program. They never change through the life of the application.

• The pointer to pointer stuff is simple boilerplate which is set up once.

• Each read/write operation returns status per tag. This array is indexed identically with the data.

• The read and write operations process all identified tags with no user coding.

• The advanced features are available, but invisible if not used. Features can be added while maintaining backward-compatibility with existing user code.

2 EXAMPLE INITIAL SETUP

The following code is the initial setup used for the eight examples.

#include "rfid.h"

#define MAX_TAGS 100

#define MAX_FIELDS 3

int main()

{

signed long status; /* return status */

rfinterr_t *Interrogator; /* interrogator control structure */

rfattr_t Attribute; /* interrogator attribute structure */

rfcontrol_t Control; /* function control structure */

rftaglist_t Taglist[MAX_TAGS]; /* the tag list */

rfstatus_t id_status[MAX_TAGS]; /* id results */

rfstatus_t rw_status[MAX_TAGS]; /* read/write results */

unsigned char color[MAX_TAGS]; /* char array to hold */

/* returning color */

unsigned short size[MAX_TAGS]; /* short array to hold */

/* returning size */

unsigned long model[MAX_TAGS]; /* long array to hold */

/*returning model */

unsigned char paid; /* write data */

/* Here's the pointer to pointer setup, done once

per program. It's boilerplate code which can be

copied from program to program intact. */

char *field_name[MAX_FIELDS];

void *field_value[MAX_FIELDS];

void *tag_field_value[MAX_FIELDS];

rfget_control(&Control);

Control.field_name = field_name;

Control.field_value = field_value;

Control.tag_field_value = tag_field_value;

3 EXAMPLE 1

This example opens an interrogator for Doorway 1.

Interrogator = rfopen("Doorway 1",&status,0);

4 EXAMPLE 2

This example changes an interrogator attribute.

rfgetattr(Interrogator,&Attribute,&status); /* get old attrs */

Attribute.identification_tries = 2; /* modify an attrs */

rfsetattr(Interrogator,&Attribute,&status); /* store attrs */

5 EXAMPLE 3

This example changes identifies the tags in the field-of-view.

Control.flag = (RF_STORE_SELECTION_LIST | RF_IDENTIFY_ALL_TAGS); Control.select_equation = ""; /* select all */

Control.taglist = Taglist;

Control.max_tags = MAX_TAGS;

Control.ostatus = id_status;

rfidentify(Interrogator,&Control);

6 EXAMPLE 4

This example reads model numbers from all tags that were identified in Example 3.

Control.flag = RF_READ_DATA; /* read command */

Control.istatus = id_status; /* input status from identify */

Control.ostatus = rw_status; /* resulting status per tag */

Control.fields = 1; /* read one field */

field_name[0] = "MODEL"; /* name of the field to read */

tag_field_value[0] = model; /* data appears here */

rfread(Interrogator,&Control);

7 EXAMPLE 5

This example reads 3 fields at once.

Control.fields = 3;

field_name[1] = "SIZE";

tag_field_value[1] = size;

field_name[2] = "COLOR";

tag_field_value[2] = color;

rfread(Interrogator,&Control);

8 EXAMPLE 6

This example indicates to all tags that something has been "paid".

Control.flag = RF_RW_CONSTANT; /* write same value to all tags */

field_name[0] = "PAID"; /* name of the field to write */

field_value[0] = &paid;

paid = 1; /* 1 means paid */

rfwrite(Interrogator,&Control);

9 EXAMPLE 7

This example incrementally identifies tags.

Control.flag = RF_IDENTIFY_INCREMENTAL;

rfidentify(Interrogator,&Control);

10 EXAMPLE 8

This example closes the interrogator interface.

rfclose(Interrogator,&status);

return(0);

} /* end of example program */

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download