Transponder Reader TWN3 Technical Manual Rev. 1.
Elatec GmbH Content 1. Introduction..................................................................................................................... 4 2. Functional Overview....................................................................................................... 4 3. Modes of Operation......................................................................................................... 5 3.1 USB-Device .............................................................................
Elatec GmbH 7.1.6.4 do while Statement.....................................................................................................................25 7.1.6.5 for Statement..............................................................................................................................25 7.1.6.6 switch Statement ........................................................................................................................25 7.1.6.7 break Statement................................
Elatec GmbH 1. Introduction This document is the reference guide for the transponder reader family TWN3. Note: In order to use the functionality, which is described in this document, your TWN3 reader needs a firmware version V4.00 or above. The latest version of the firmware is part of the developer pack. Please revere to section “Updating the Firmware”, if you would like to update the firmware. 2.
Elatec GmbH Let’s take a more detailed view: The diagram below is showing the functional units and how they can be configured: TWNConfig USB Keyboard Emulation Scancode Translation Table TWNConfig TWNConfig TWNConfig TWN3 Device Type Multi125 Selected by Cable Scripting Engine Mifare USB Virtual COM Port HID Prox Transparent Communication V24Interface HID iClass Command for Config Mode Config Mode Legic 3.
Elatec GmbH 3.1 USB-Device A TWN3 USB reader is capable of supporting several modes of operation. 3.1.1 Keyboard Emulation (USB HID Device) This is the default mode for USB devices. No drivers are required for running the device in a typical environment like Windows XP or Linux. Any output from the TWN3 transponder reader to the host is sent like keyboard input from a user. Therefore, any characters are displayed at the current position of the cursor on the screen of the computer.
Elatec GmbH 3.2.2 Pin Assignment Following pin assignment for the DSUB25 plug: Pin Signal 2 RxD from host 3 TxD to host 7 Signal ground 24 5V power supply from the host Following pin assignment for the DSUB9 plug: Pin Signal 3 RxD from host 2 TxD to host 5 Signal ground 9 5V power supply from the host Following pin assignment for the PS/2 plug: Pin Signal 6 RxD from host 2 TxD to host 3 Signal ground 4 5V power supply from the host 4. Installation 4.
Elatec GmbH 4.3 USB-Device (Virtual Serial Port) In order to install a TWN3 reader, which emulates a virtual serial port under Windows XP, keep the drivers nearby and follow these steps: • Plug in the TWN3 reader into your host computer. The following screen should appear (in your native language) Select to install the software from a specific source. • The following screen should appear: Select the directory, where the drivers reside and click continue. The drivers will be installed now.
Elatec GmbH The installation is now completed. In order to find the serial communication port, which is emulated by the TWN3 transponder reader, you may take a look into the device manager: In this example, we find the TWN3 reader at COM7. Depending on the further configuration of the device, you may now test the TWN3 transponder reader with a normal terminal program.
Elatec GmbH 5. Configuration In order to configure a TWN3 transponder reader, the program TWNConfig.exe is required. Configuration is supported under Windows XP or Windows Vista. During configuration, a TWN3 transponder reader is switched into configuration mode. In this mode the entire setup of the device can be done. Configuration is possible both for V24 and USB devices. Note: Please do not connect more than one TWN3 device at a time to your computer during the usage of TWNConfig.
Elatec GmbH TWNConfig is searching and connecting to a TWN3 device. You are now ready to do the required configurations on the device. Note: If you are configuring a USB device the first time, you have to install the appropriate configuration drivers. Please refer to “Installing USB-Drivers for Configuration”. 5.
Elatec GmbH 5.3 Resuming Normal Operation In order to leave configuration mode of the TWN3 device and resume to normal operation click the “Restart” button. Note: Disconnecting the device from the host or a power cycle will not leave configuration mode.
Elatec GmbH 5.4 Selecting Mode of Operation In the tab folder “Mode of Operation” you select the basic mode in which the TWN3 device operates.
Elatec GmbH 5.5 Setting Up the Keyboard Emulation 5.5.1 Table of Scan Codes This tab folder enables you to change the scan codes of the keyboard emulation, which are sent to the host for a specific character. The default setup of the device already contains the mainly used characters ‘0’ – ‘9’, ‘A’ – ‘F’ and the carriage return. This enable the reader to send any hex number and an ENTER to the host computer.
Elatec GmbH In order to do this, you may double-click on an existing entry in the table or specify a new entry by pressing the “Add”-button. In the following dialog you now are able to select the appropriate keys. Please keep in mind, that the keyboard keys are to be specified in relation to a standard U.S. QUERTY keyboard, which is shown below: Source: www.wikipedia.org Note: A maximum of 48 entries in the scan code table are possible. 5.5.
Elatec GmbH 5.6 Installing Scripts In order to install a script on a TWN3 device, perform following actions: • Select a script file (extension “.twn.c”) by clicking the button “Select Script”. • Click the “Compile Script”. This will start the script compiler. • If there is an error detected in the script, the line number and type of error will be displayed. • If the compilation is successful, following screen will appear: The compiled script is now part of the configuration within TWNConfig.
Elatec GmbH 5.7 Miscellaneous Settings Within the tab folder “Misc”, there is only one setting, which influences the behavior on how a carriage return is transferred to the PC. The reason for this is that in keyboard emulation, it makes no sense to send a line feed to the host computer (in fact, there is no key on a keyboard, which does “line feed”). On the other hand, sending a line feed after a carriage return might appear quite normal in a terminal session via serial interface.
Elatec GmbH 5.8 Updating the Firmware In order to update the firmware of a TWN3 device select tab folder “Firmware”. After any successful connection to a TWN3 device, the current directory will be searched for firmware images, which are compatible to the connected device. In order to re-program the firmware of a TWN3 device, click the “Program”-button.
Elatec GmbH 5.9 Export and Import of Configurations Once a device has been configured completely, this configuration can be exported to a file. This makes it much easier to setup many TWN3 devices in the same way: Note: • It is not possible to read the secret area from a TWN3 device. To save a configuration including their secrets, you have to compile the appropriate script, which defines these secrets.
Elatec GmbH 5.10 Installing USB-Drivers for Configuration If the USB TWN3 reader is configured the first time, USB drivers for the configuration mode have to be installed. Here are the steps to do so: • Once you have clicked the “Connect”-button within TWNConfig.exe the first time, the following screen will appear: Select to install the software from a specific source. • The following screen should appear: Select the directory, where the drivers reside and click continue.
Elatec GmbH You are now ready to configure the TWN3 reader. Please Note: If the TWN3 reader is plugged into a different USB port of the host computer, this installation procedure has to be repeated. 6. Transparent Mode Once a TWN3 device has been turned into transparent mode, a direct link will be established between the serial interface (V24 or virtual USB), and the reading module.
Elatec GmbH 6.1 HID Prox Transparent Protocol Due to the nature of the HID Prox transponder, which is read only, the raw data, which will be returned by a successful read, is directly described in this document: If a transponder is read, a ASCII string is sent which is terminated by ‘\r’; The first character represents the number of valid bits, the remaining bytes do contain these bits. Example: Data sent by the reader: 0x1A 0x80 0x80 0x01 0xC0 ‘\r’ Meaning: The first contains 0x1A, which means the followi
Elatec GmbH 7.1.2 Comments In order to place a comment within the source code, two slashes are used. The remaining content of the line will be ignored by the compiler. 7.1.3 Case Sensitivity The TWN3 script language is sensitive to upper and lower case. Examples: byte a; // Valid Byte a; // Invalid byte Byte; // Valid(!) 7.1.4 Preprocessor Directives The preprocessor is removing comments from the source code and processing the preprocessor directives. Currently, there is one directive available. 7.1.4.
Elatec GmbH 7.1.5.2 Arguments If a function has no arguments, the list of arguments has to be left empty (do not write void). In order to declare arguments, write the list of arguments separated by commas. Arguments are passed by value or by reference. In order to pass an argument by reference instead of value, insert the ‘&’ before the identifier of argument.
Elatec GmbH 7.1.6.2 if else Statement An if else statement has the form: if (expression) statement1 else statement2 Statement1 is executed only, if the result of expression is not equal to zero. Otherwise, statement2 is executed. 7.1.6.3 while Statement A while statement has the form: while (expression) statement Statement is executed, as long as the result of expression is not equal to zero. 7.1.6.
Elatec GmbH 7.1.6.7 break Statement Form: break; The break statement can be used in while, do/while, for and switch statements (loop or switch statements). In a loop statement, control is passed directly to the next statement outside of the loop. In a switch statement, control is passed directly to the next statement outside of the switch body. 7.1.6.8 continue Statement Form: continue; The continue statement can be used in while, do/while and for statements (loop statements).
Elatec GmbH 7.1.6.12 Empty Statement A statement, which is doing nothing is the semicolon. Example: for (i=0; i<10; i+=1) ; // Waste some time and do ten times nothing 7.1.7 Storage Types In the TWN3 scripting language, there is only one type of storage defined, which is the byte. A byte is an unsigned integer with a size of 8 bits. 7.1.8 Storage Classes There are following storage classes available: Standard, const and secret. Without using any modifier, the standard storage is used.
Elatec GmbH 7.1.
Elatec GmbH 7.2 Runtime Environment 7.2.1 Include File The file sys.twn.h declares all constants and system function prototypes, which are necessary for accessing the TWN3 transponder reader functionality. It is strongly recommended to include this file in any TWN3 script: #include 7.2.
Elatec GmbH 7.2.5 System Function Calls 7.2.5.
Elatec GmbH 7.2.5.1.1 Generally Available Transponder Operations byte TagSearch(byte &IDData, byte &IDBitCnt, byte &TagType) Search a transponder. This function behaves similar on different types of transponder readers, but not identical. Parameter: byte &IDData byte &IDBitCnt Reference to a bit field (in fact an array of bytes), which receives the ID data. Number of valid bits(!), the ID consists of. byte &TagType Type of tag, which has been found.
Elatec GmbH byte TagWrite(byte Address, byte ByteCnt, byte &Data) Write data to a selected transponder. Parameters: byte Address The address within the address space of the transponder. byte ByteCnt Number of bytes to write. byte &Data Reference to an array of bytes to be written. Return: If the operation was successful, the return value is TRUE, otherwise it is FALSE. 7.2.5.1.
Elatec GmbH 7.2.5.1.3 Mifare Specific Transponder Operations byte MifareLogin(byte &Secret, byte KeyType, byte Sector) In order to do any operations on a sector of a Mifare transponder, a login has to be performed. Parameters: byte &Secret byte KeyType Reference to a array of bytes, which has to contain six bytes. These bytes represent the key for the login process. Specifies, with which key the operation has to be performed. This is one of the defined constants KEYA or KEYB.
Elatec GmbH 7.2.5.2 Functions for Host Communication void HostSendVersion() Send version information of the firmware to the host. This information is sent without a carriage return. Therefore, it is possible to append some more information, i.e. the version of the script, which is currently executed. Parameter: Return: None None. Example: HostSendVersion(); HostSendChar(‘.’); HostSendChar(‘0’); HostSendChar(‘2’); HostSendChar(‘\r’); // Send the firmware version // Send another separator // Send version
Elatec GmbH void HostSendHex(byte &Data, byte BitCnt, byte Width) Convert a number, which is given as a bit field into hexadecimal ASCII format, and send it to the host. Letters are sent in upper case. Parameters: byte &Data byte BitCnt byte Width Return: A reference to an array of bytes, which contains the bit field The number of bits, which are valid within the array of bytes. A maximum of 128 bits can be converted. Specifies the number of digits, the output should contain.
Elatec GmbH byte HostTestCmd(byte &Cmd, byte &CmdLen, byte MaxCmdLen) This command implements a generic method for receiving an array of bytes from the host. This enables the programmer to implement a simple interface, which executes commands sent from the host to the reader. A host command is any sequence of ASCII characters which is terminated by ‘\r’. The character ‘\n’ can be sent optionally but is ignored by the reader.
Elatec GmbH 7.2.5.4 Accessing the Beeper void SetVolume(byte Volume) Set the volume of the beeper. Parameter: byte Volume A value between 0 (beeper turned off) and 4 (maximum volume). Return: None. void Beep(byte Type) Sound some type of beep. Parameter: byte Type Return: Four types of beeps are defined by constants: BEEPLOW: A beep at lower frequency BEEPHIGH: A beep at higher frequency BEEPSUCCESS: A low-high sequence, which is intended to signal a successful operation.
Elatec GmbH void CopyBits(byte &DestBits, byte StartDestBit, byte &SourceBits, byte StartSourceBit, byte BitCount) Copy bits from a source to a destination. Source and destination may be identical and the source section may overlap the destination. Depending on that, the correct method for copying will be chosen. Parameters: byte &DestBits byte StartDestBit Reference to an array of bytes which represent a bit field which is the destination of the copy operation.
Elatec GmbH 7.2.5.6 Byte Operations byte CompBytes(byte &Data1,byte &Data2,byte ByteCount) Compare two byte arrays. Parameters: byte &Data1 Reference to an array of bytes. byte &Data2 Reference to an array of bytes. byte ByteCount Number of bytes (beginning from index 0) to be compared. Return: TRUE: The two arrays are identical. FALSE: The two arrays are not identical void CopyBytes(byte &DestBytes, byte &SourceBytes, byte ByteCount) Copy bytes from a source to a destination.
Elatec GmbH byte ScanHex(byte &Data, byte ByteCnt) Convert an array of bytes containing ASCII characters which represent hexadecimal numbers into their binary representation. The conversion is done in place. This means that after successful conversion, number of valid is half of the given count of ASCII characters (two hex digits represent one binary byte). Parameters: byte &Data Reference to an array of bytes which is the destination for the operation.
Elatec GmbH 7.2.5.8 Retrieving System Information byte GetConnection() Retrieve the physical type of connection (V24 or USB). Parameter: Return: None. Either one of the defined constants: V24: The TWN3 reader is connected via a V24 cable to the host. USB: The TWN3 reader is connected via a USB cable to the host byte GetUSBMode() Retrieve the information if the TWN3 reader is emulating a keyboard or if it is emulating a virtual COM port. Parameter: Return: None.
Elatec GmbH 8.
Elatec GmbH 9.2 FCC Statement 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 received, including interference that may cause undesired operation. Section 15.21 Information to user Changes or modifications not expressly approved by the party responsible for compliance could void the user's authority to operate the equipment Section 15.
Elatec GmbH 10. Trademarks All referenced brands, product names, service names and trademarks mentioned in this document are the property of their respective owners.
