RFID1356i SDK TM Software Developer’s Kit For use with the RFID1356i TM Contactless Read/Write Reader www.RFIDeas.com © 1996-2003 RF IDeas, Inc.
LICENSE AGREEMENT End-User License Agreement for RF IDeasTM SOFTWARE and HARDWARE – RFID1356, RFID1356i, RF IDeas’ AIR ID® , AIR ID® LT, pcProx USB, and pcProx® Contactless and Proximity Activated Readers, Software Developer’s Kit, and Proximity Reader Protocol(s).
* You may not reproduce or otherwise emulate, in whole or in part, any form the protocol(s) defined within this PRODUCT for use without a RF IDeas PRODUCT. * Redistributable Code. If you are authorized and choose to redistribute Sample Code (“Redistributables”) as described in Section 1.
Returns RF IDeas products which require Limited Warranty service during the warranty period shall be delivered to the nearest authorized dealer or sent directly to RF IDeas at the address below with proof of purchase and a Return Materials Authorization (RMA) Number provided by RF IDeas technical support Dept. Replacement parts or complete boards become the property of RF IDeas.
Congratulations on the purchase of your RFID1356i Software Developer’s Kit. We at RF IDeas hope you enjoy using your new Smart Card Contactless Identification System as much as we enjoyed creating and developing it! Please share your comments and suggestions! Thank you, The Staff at RF IDeas Need Assistance? Call: 847-870-1723 Fax: 847-483-1129 E-mail: TechSupp@RFIDeas.com Mail to: RF IDeas Inc. 4238B Arlington Heights Rd. #244 Arlington Heights, IL 60004 © 1996-2003 RF IDeas, Inc.
FCC Compliance Statements AIR ID LT Badge - FCC ID M9MMU100 This device complies with Part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) This device must accept any interference that may cause undesired operation. AIR ID LT Base Unit - FCC ID M9MBU100 This device complies with Part 15 of the FCC rules.
Table of Contents LICENSE AGREEMENT .............................................................................................................................2 SOFTWARE PRODUCT LICENSE .............................................................................................................2 Limited Warranty ......................................................................................................................................3 Returns.....................................................
Library Error Codes ...................................................................................................................................30 Public Interface Error bits:......................................................................................................................30 Private Interface Error bits: ....................................................................................................................30 Error Recovery .............................................
Overview This document will guide the developer through the various documents, specifications, and sample code TM contents of the RFID1356i Contactless Read/Write SDK (Software Developer’s Kit). The RFID1356i serial port contactless read/write reader is fully supported in this SDK. If you are interested in the USB port SDK, please call RF IDeas for more information. The RFID1356i uses drivers supplied with the operating system, however there is a DLL library required that is supplied by RF IDeas.
RFID1356i API Release Information Version 1.1.0 - April. 19, 2002 Further pre-release refinement. Version 1.0.0 - April. 12, 2002 This document describes the interface to the RFID1356i "iClassAPI.dll" Dynamic Link Library. This library provides a RS-232c serial interface to the pcProx1356 ‘device’ which is equipped with a HID iClass Reader capable of reading and writing the HID iClass 2Kbit and 16Kbit cards and reading the serial number from a MIFARE card.
Disk Contents C++ Command Exerciser Application © 1996-2003 RF IDeas, Inc.
© 1996-2003 RF IDeas, Inc.
Function Reference Summary BOOL APIENTRY GetLibVersion( short* piVerMaj, short* piVerMin, short* piVerDev ); BOOL APIENTRY USBConnect( long* plDID ); BOOL APIENTRY USBDisconnect( void ); long APIENTRY GetLastLibErr( void ); BOOL APIENTRY ReadCfg( void ); BOOL APIENTRY WriteCfg( void ); BOOL APIENTRY ResetFactoryDflts( void ); BOOL APIENTRY GetFlags( tsCfgFlags* psCfgFlgs ); BOOL APIENTRY SetFlags( tsCfgFlags* psCfgFlgs ); BOOL APIENTRY GetIDBitCnts( tsIDBitCnts* psIDBitCnts ); BOOL APIENTRY SetIDBitCnts( ts
short APIENTRY GetActDev( void ); BOOL APIENTRY SetActDev( short iNdx ); short APIENTRY GetLUID( void ); BOOL APIENTRY SetLUID( short LUID ); short APIENTRY GetDID( void ); © 1996-2003 RF IDeas, Inc.
Function Details BSHRT APIENTRY GetLibVersion( short* piVerMaj, short* piVerMin, short* piVerDev ); Parameters: piVerMaj – pointer (reference) to integer to receive the Major version piVerMin – pointer (reference) to integer to receive the Minor version piVerDev – pointer (reference) to integer to receive the Development version Returns non-zero always. The intended interpretation of the Version is ‘v VerMaj.VerMin.VerDev’.
BSHRT APIENTRY ReadCfg( void ); Parameters: [none] Returns non-zero on Success, zero otherwise. A call to this function pulls all configuration information from the current active device to local Library memory space where it may be manipulated by the user application using the Getxxx() and Setxxx() functions. BSHRT APIENTRY WriteCfg( void ); Parameters: [none] Returns non-zero on Success, zero otherwise.
BSHRT APIENTRY GetFlags( tsCfgFlags* psCfgFlgs ); Parameters: psCfgFlgs – pointer to structure to receive Configuration Flags info. Returns non-zero on Success, zero otherwise. BSHRT APIENTRY SetFlags( tsCfgFlags* psCfgFlgs ); Parameters: psCfgFlgs – pointer to structure containing new Configuration Flags info. Returns non-zero on Success, zero otherwise. This call does NOT write the configuration items to the device, just to local Library storage.
BSHRT APIENTRY GetFlags2( tsCfgFlags2* psCfgFlgs2 ); Parameters: psCfgFlgs – pointer to structure to receive Configuration Flags (2) info. Returns non-zero on Success, zero otherwise. BSHRT APIENTRY SetFlags2( tsCfgFlags2* psCfgFlgs2 ); Parameters: psCfgFlgs – pointer to structure containing new Configuration Flags (2) info. Returns non-zero on Success, zero otherwise. This call does NOT write the configuration items to the device, just to local Library storage.
BSHRT APIENTRY GetLEDCtrl( tsLEDCtrl *psLEDCtrl ); Parameters: psLEDCtrl – pointer to structure to receive LED control info. Returns non-zero on Success, zero otherwise. BSHRT APIENTRY SetLEDCtrl( tsLEDCtrl *psLEDCtrl ); Parameters: psLEDCtrl – pointer to structure containing new LED control info. Returns non-zero on Success, zero otherwise. This call does NOT write the configuration items to the device, just to local Library storage.
short APIENTRY GetDevCnt( void ); Parameters: [none] Returns the number of pcProxUSB devices found on this machine in USBConnect(). short APIENTRY GetActDev( void ); Parameters: [none] Returns the current Active Device, an index into a list, 0 – (GetDevCnt()-1). BSHRT APIENTRY SetActDev( short iNdx ); Parameters: iNdx – selects a new Active Device for processing. Returns non-zero on Success, zero otherwise.
[future release] BSHRT APIENTRY GetHIDGuid)( GUID *pGuid ); Parameters: pGuid – pointer to a GUID structure that will receive the GUID of this particular interface class. It may be treated as an 8-byte array. Returns non-zero on Success, zero otherwise. This call is required if your App will register for Device Interface change notifications. [future release] BSHRT APIENTRY ChkAddArrival( char *szName ); Parameters: szName – The ‘friendly’ name of the device as reported in a device notification.
long APIENTRY GetLastICSWErr( long lBufSz, char *szErrBuf ); Parameters: lBufSz – specifies the maximum size in bytes of szErrBuf. szErrBuf – contains NULL terminated string describing the last Status Word. Return Value: Returns the HID iClass reader Status Word which defines the text in szErrBuf. BSHRT APIENTRY CommCnct( tsCommParms* pCommParms ); Opens a Comm port for communication to the device. The sCommParms structure contains information on baud rate, parity, and number of stop bits.
BSHRT APIENTRY ic_Select_Current_Key( long lRKey ); Parameters: lRKey - Reader key location for card authentication, valid for locations 1 thru 7. Return Value: Returns non-zero if successful, zero on failure. Call GetLastICSWErr() for more detail on failure. BSHRT APIENTRY ic_Select_Card( long lCAA, long lRKey, long lCTypes, long *pCType, BYTE *pCSNBuf ); Parameters: lCAA – Card App area (1 or 2) to authenticate against (0 for no authentication). lRKey – Reader key to use in authentication (if lCAA != 0).
BSHRT APIENTRY ic_Read( long lBlkLen, long lBlkAddr, BYTE *pRetBuf ); Parameters: lBlkLen – Number of Blocks to read (bytes = blocks x 8). lBlkAddr – Starting Block address. pRetBuf – pointer to buffer (size = lBlkLen x 8) to receive the card data. Return Value: Returns non-zero if successful, zero on failure. Call GetLastICSWErr() for more detail on failure. BSHRT APIENTRY ic_Write( long lBlkLen, long lBlkAddr, BYTE *pSndBuf ); Parameters: lBlkLen – Number of Blocks to write (bytes = blocks x 8).
BSHRT APIENTRY ic_LoadKeyInRdr( long lRKey, BYTE *pNewKey ); This function will perform necessary steps to load a new key into iClass reader EEPROM at the specified location. A call to ic_Select_Current_Key() is then used to select this key as the authentication key against card reads and writes. Parameters: lRKey – Reader key location, valid for locations 1 thru 7. pNewKey – pointer to the new 8-byte key to be loaded. Return Value: Returns non-zero if successful, zero on failure.
iIDDispLen = 5 iFACDispLen = 3 sTimeParms: iBitStrmTO = 80 msec iIDHoldTO = 1500 msec iIDLockOutTm = 2500 msec iUSBKeyPrsTm = 20 msec iUSBKeyRlsTm = 20 msec sCfgFlags2: All Flags are set to Zero sIDDispParms2: iLeadChrCnt = 0 iLeadChr0 = 0 iLeadChr1 = 0 iLeadChr2 = 0 © 1996-2003 RF IDeas, Inc.
‘C’ Reference See file: pcProxUSBAPI.h for Structure and Function Prototypes. //---------------------// Typical ‘C’ Program Flow: //---------------------#include “pcProxUSBAPI.h” // Static declarations of function pointers...
//---------------------void main() { short iVerMaj, iVerMin, iVerDev; BOOL brc; long lrc, lDeviceID; short iIDBitCnt, i, iDevCnt; tsCfgFlags devFlags; BYTE IDBuf[16]; // really only need 8 byte storage but what the hey if( !InitUSBProxLib() ) exit(1); brc = fnGetLibVersion( &iVerMaj, &iVerMin, &iVerDev ); if( brc ) { // display / squirrel away the Library version info... } brc = fnUSBConnect( &lDeviceID ); ' connect to the device if( !brc ) { // Device is not on the USB or other scarry thoughts...
Sub Main() Dim iVerMaj, iVerMin, iVerDev As Integer Dim brc As Boolean Dim lrc, lDeviceID As Long Dim iIDBitCnt As Integer Dim devFlags As tsCfgFlags Dim IDBuf As tsIDBuf ' 8-byte ID return buffer brc = GetLibVersion( iVerMaj, iVerMin, iVerDev ) If brc <> False Then ' display / squirrel away the Library version info... End If brc = USBConnect( lDeviceID ) ' connect to the device If brc = False Then ' Device is not on the USB or other scarry thoughts...
Library Error Codes Returned from GetLastLibErr() Public Interface Error bits: USBConnect ReadCfg WriteCfg ResetFactoryDflts Get(Structure) NULL Pointe ReadCfg not called Set(Structure) NULL Pointer GetActiveID 0x0001xxxx 0x0002xxxx 0x0004xxxx 0x0008xxxx 0x0010xxxx 0x00100001 0x00100002 0x0020xxxx 0x00200001 0x0100xxxx where ‘xxxx’ represents Private Interface Error Bits. Private Interface Error bits: USBDeviceConnect 0x00xx, xx= 1:Couldn't open SETUPAPI.DLL 2:Unresolved SETUPAPI.
Error Recovery The device not being plugged into the USB port is the normal cause of error encountered in the ‘USBConnect’ call. There is nothing that needs to be done (or that can be done) in the application, plugging the device in or un-plugging then re-plugging the device in should fix this problem. Errors encountered in the ‘ReadCfg’, ‘WriteCfg’, ‘SetFactoryDflts’, and ‘GetActiveID’ calls are usually caused by the device being un-plugged after the call to ‘USBConnect’ is done.
USB Keys as Used by the Device The iFACIDDelim and iELDelim are set to one of the following sUSBKey::ucKeyCode values. The USB key codes do not have the ‘shifted’ state as part of the key code. Rather, this information is included in a ‘modifier’ byte that travels with the key code. Since the USB key codes (of interest) are all < 128, the Library uses the high bit of the key code byte to extend the definitions to ‘shifted’ keys.
{0x1A | 0x80, "W"}, {0x1B | 0x80, "X"}, {0x1C | 0x80, "Y"}, {0x1D | 0x80, "Z"}, //... {0x1E, "1"}, {0x1F, "2"}, {0x20, "3"}, {0x21, "4"}, {0x22, "5"}, {0x23, "6"}, {0x24, "7"}, {0x25, "8"}, {0x26, "9"}, {0x27, "0"}, {0x1E | 0x80, "!"}, {0x1F | 0x80, "@"}, {0x20 | 0x80, "#"}, {0x21 | 0x80, "$"}, {0x22 | 0x80, "%"}, {0x23 | 0x80, "^"}, {0x24 | 0x80, "&"}, {0x25 | 0x80, "*"}, {0x26 | 0x80, "("}, {0x27 | 0x80, ")"}, //... {0x28, "ENTER"}, {0x29, "ESC"}, {0x2A, "BKSPC"}, {0x2B, "TAB"}, {0x2C, "SPACE"}, //...
{0x4B, "PGUP"}, {0x4C, "DELETE"}, {0x4D, "END"}, {0x4E, "PGDN"}, {0x4F, "RIGHT"}, {0x50, "LEFT"}, {0x51, "DOWN"}, {0x52, "UP"}, {0x54, "KP /"}, {0x55, "KP *"}, {0x56, "KP - MINUS"}, {0x57, "KP +"}, {0x58, "KP ENTER"}, {0xFF, NULL}, // cut this list short }; © 1996-2003 RF IDeas, Inc.
USB Keyboard ID Display Format The following discussion pertains to the Display Properties when pcProx is used in the keystroke send mode of operation, i.e. the HaltKBSends configuration flag is cleared thereby enabling keyboard sends of the ID. The Library call ‘GetActiveID’ will return a binary 8-byte ID which is only affected by the leading / trailing parity bit counts. The binary ID is stripped of the parity bits if these settings are nonzero. Other display properties do NOT affect the binary ID.
CfgFlags.bFrcBitCntEx = 0; // Force Rx'd bit count to be exact to be valid CfgFlags.bStripFac = 0; // Strip the FAC from the ID (not discarded) CfgFlags.bHaltKBSnd = 1; // Don't Send keys to USB (GetActiveID mechanism may be used always) IDBitCnts.iLeadParityBitCnt = 0; // Wiegand Leading Parity bit count to be stripped IDBitCnts.
OCX Filter Included with the SDK is an ActiveX control to aid software developers in splitting the bitstream read from the proximity card into parity, facility, and ID codes. Note: As with other OCX ActiveX routines you will need to register the OCX using a Windows registry tool such as REGSVR32.EXE. Example to register under Windows 2000: ‘regsvr32 rfidProxfilter.ocx’ Example to de-register under Windows 2000: ‘regsvr32 rfidProxfilter.