Transponder Reader TWN3 Technical Manual Doc.-Rev. 1.
Elatec GmbH Content 1. FUNCTIONAL OVERVIEW ...................................................................................................................... 4 2. MODES OF OPERATION .......................................................................................................................... 5 2.1 USB-DEVICE ........................................................................................................................................... 6 2.1.
Elatec GmbH 6.2.5 System Function Calls ................................................................................................................... 40 7. FIRMWARE HISTORY ............................................................................................................................ 59 8. TECHNICAL DATA .................................................................................................................................. 60 9. REGULATORY INFORMATION....................
Elatec GmbH 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. 1.
Elatec GmbH Let‟s take a more detailed view: The diagram below is showing the functional units and how they can be configured: TWNConfig TWNConfig TWNConfig TWNConfig TWN3 Device Type MultiISO USB Keyboard Emulation Scancode Translation Table Selected by Cable Multi125 Scripting Engine USB Virtual COM Port IndiTag Mifare Mifare NFC Transparent Communication Legic V24Interface Legic NFC Command for Config Mode Config Mode HID Prox HID iClass 2.
Elatec GmbH 2.1 USB-Device A TWN3 USB reader is capable of supporting several modes of operation: 2.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 2.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 3. Installation 3.
Elatec GmbH 3.2 USB-Device (Keyboard Emulation) Installing a TWN3 reader emulating a keyboard is rather simple due to the fact, that drivers do come with the operating system. Therefore, the device simply can be connected to the host computer and can be immediately used. 3.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.
Elatec GmbH The following screen should appear: Select the directory, where the drivers reside and click continue. The drivers will be installed now. After installation, the following screen should appear: The installation is now completed.
Elatec GmbH 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. 4. 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.
Elatec GmbH 4.1 Entering the Configuration Mode Assuming, that the TWN3 transponder reader is already connected to the host computer, start the program TWNConfig.exe. The following screen will appear: Depending on the physical interface of the TWN3 transponder reader, choose the appropriate port in the top left combo box.
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”. 4.
Elatec GmbH 4.3 Resuming Normal Operation In order to leave the configuration mode of the TWN3 device and resume to normal operation click the “Restart” button.
Elatec GmbH 4.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 4.5 Setting Up the Keyboard Emulation 4.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 often used characters „0‟ – „9‟, „A‟ – „F‟, carriage return and the space character.
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 Notes: A maximum of 48 entries in the scan code table is possible.
Elatec GmbH 4.5.2 Sending ALT Codes You may send ALT codes instead of key strokes on a keyboard. Example: The character „A‟ (ASCII code 65) should be sent to the host. Following sequence is executed: - Press ALT key - Press key „6‟ on the numeric keypad - Release key „6‟ on the numeric keypad - Press key „5‟ on the numeric keypad - Release key „5‟ on the numeric keypad - Release ALT key.
Elatec GmbH 4.6 Installing Scripts In order to install a script on a TWN3 device, perform following actions: Select the tab folder “Scripting”. 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.
Elatec GmbH If the compilation is successful, following screen will appear: The compiled script is now part of the configuration within TWNConfig. Some additional information is displayed on how much storage space is occupied by this script. Up to now, the script has not been saved to the TWN3 device.
Elatec GmbH 4.7 RS232 Settings Within the tab folder “RS232”, you can setup the parameters for the RS232 communication parameters to the host computer. As long as the checkbox “Default Settings” is activated the device will communicate with 9600 Baud and no parity (except version Multi125 which is using even parity in transparent mode). Unchecking the checkbox “Default Settings” will force the device to communicate with the desired baud rate and parity both in scripted and transparent mode.
Elatec GmbH 4.8 Startup Condition in Transparent Mode Within the tab folder “Transparent”, you can setup the state of LEDs an beeper during startup of the device.
Elatec GmbH 4.9 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 storage capacity, the firmware version 4.09 should be programmed into the device first. This firmware fits into any TWN3 device. TWNConfig is then able to determine the storage capacity of the device. Note: Do not use an earlier version of TWNConfig than V1.15 for programming a firmware version later than V4.09! 4.10 Preferences Within the tab folder “Prefs”, there are two settings: Activating the check box “Log protocol into file TWNConfig.
Elatec GmbH 4.11 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 with identical configuration. 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 4.12 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. Note: If the TWN3 reader is plugged into a different USB port of the host computer, this installation procedure has to be repeated. 5. Transparent Mode Once a TWN3 device has been turned into transparent mode, a direct link will be established between the serial interface (RS232 or virtual USB), and the reading module.
Elatec GmbH 5.1 HID Prox Transparent Protocol Due to the fact, the TWN3 HID Prox performs read access only, there are no commands available, which can be sent to the reading module. The data received from the module is formatted as follows: If a transponder is read, a ASCII string is sent which is terminated by carriage return. The first character represents the number of valid bits, the remaining bytes do contain these bits. Two hexadecimal digits represent one byte.
Elatec GmbH 5.3 Controlling LEDs and Beeper Even in transparent mode there are commands available, which allow control of the built-in LEDs and the beeper. The commands depend on the communication protocol of the built-in reader module. Please Note: The parameters and return values are identical to the corresponding system calls LEDSet, LEDGet, SetVolume and Beep. Please see the related documents for a detailed description of the communication in transparent mode.
Elatec GmbH 5.3.2 Get LEDs Please see the system function call LEDGet for a detailed description of the parameter and the return value.
Elatec GmbH 5.3.3 Set Volume Please see the system function call SetVolume for a detailed description of the parameter.
Elatec GmbH 5.3.4 Beep Please see the system function call Beep for a detailed description of the parameter.
Elatec GmbH 6. Scripting 6.1 Language Description The scripting language for TWN3 readers is a simplified version of the language C. The main differences are: There is one data type available, which is a byte. A byte is an unsigned integer with a size of 8 bits. There are no pointers available. Instead, there is a reference operator, which is showing some similarity to the language C++. 6.1.1 Source Code The source for a TWN3 script is given as a text file.
Elatec GmbH 6.1.4.1 #include Directive Include another source file and treat it as a part of the compiled source. There are two possibilities: #include Include the given file, which is located relative to the directory, where TWNConfig.exe resides. #include “mydefs.twn.h” Include the given file, which is located relative to the current directory 6.1.5 Functions Functions may be defined (“prototype”) in order to resolve forward references, or declared directly.
Elatec GmbH 6.1.5.4 Function main A TWN3 script always needs the function main to be implemented. The prototype for the function main is: void main(); After internal initialization, the TWN3 reader will start execution of the script by calling this function main. 6.1.6 Statements A single statement has the form [expression]; This means, a statement is a (optional) expression followed by a semicolon. If only a semicolon without an expression is specified, it is called an empty statement.
Elatec GmbH 6.1.6.5 for Statement A for statement has the form: for ([expression1]; [expression2]; [expression3] statement As first step, expression1 is evaluated. As long as expression2 is not equal to zero, statement is executed. After execution of statement, expression3 is evaluated. Therefore, a for statement can be rewritten as while statement with exactly the same behavior: expression1; while (expression2) { statement expression3; } 6.1.6.
Elatec GmbH 6.1.6.9 return Statement Two forms are possible: Functions, which do not return a value: return; The execution of the current function is stopped. Execution is continued in the calling function. Functions which return a value: return expression; Expression is evaluated, execution is stopped, the result of the expression is passed to the calling function, execution is continued in the calling function. 6.1.6.
Elatec GmbH 6.1.8 Storage Classes There are following storage classes available: Standard, const and secret. Without using any modifier, the standard storage is used. A variable, which is declared in the standard storage class, is allocated in the normal data segment. Examples: byte i; byte a[15]; // A single integer // An array of 15 bytes 6.1.8.1 const An identifier, which is declared as const can be used for calculations at compile time. There is no physical memory occupied during runtime.
Elatec GmbH 6.1.
Elatec GmbH 6.2 Runtime Environment 6.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 6.2.
Elatec GmbH 6.2.5 System Function Calls 6.2.5.
Elatec GmbH 6.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. 6.2.5.1.
Elatec GmbH 6.2.5.1.3 Mifare-, Mifare NFC- and MultiISO-Specific Transponder Operations For TWN3 Mifare and TWN3 MultiISO, there are identical functions available, which directly communicate with the built-in module: 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.
Elatec GmbH byte ModuleReceiveLine(byte &RXData, byte &RXCount, byte MaxRXCount, byte Timeout) Receive a line of text from the module. A line of text is the typical response of the module to a command. Parameters: byte &RXData byte &RXCount byte MaxRXCount byte Timeout Return: Reference to an array of bytes, which contains the received ASCII characters (without carriage return and line feed). The number of received ASCII characters. Specifies the maximum number of characters the array RXData can hold.
Elatec GmbH 6.2.5.1.5 HID iClass Specific Operations byte IClassGeneric(byte &TXData, byte TXCount, byte &RXData, byte RXCount, byte Timeout) Send a specific command to the built in module of a TWN3 HID iClass. Parameters: byte &TXData byte TXCount byte &RXData Reference to an array of bytes which contains the command to be sent to the module. Count of bytes in the specified array of bytes to be sent. byte RXCount Reference to an array of bytes (receive buffer) which receives the answer from the module.
Elatec GmbH 6.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 void HostSendNumber(byte &Data,byte FirstBit,byte BitCnt, byte Radix,byte MinWidth,byte MaxWidth) Convert a number, which is given as a bit field into ASCII format, and send it to the host. The conversion is made in the following sequence: 1. Convert the binary data to a number of digits, which is determined by the parameter MaxWidth. If MaxWidth is 0, then the number of digits is determined by the binary data itself. 2.
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. The maximum number of bytes, (without „\r‟), which can be transferred, is 35 bytes
Elatec GmbH byte LEDGet(byte LED) Get the current status of a LED. Only the status of one LED can be retrieved at a time. Parameter: byte LED Return: Specifies either the value for the green (constant GREEN) or the red (constant RED) LED. The current status of the LED specified by LED. OFF: The LED is off ON: The LED is on BLINK: The LED is blinking 6.2.5.4 Accessing the Beeper void SetVolume(byte Volume) Set the volume of the beeper.
Elatec GmbH 6.2.5.5 Accessing the General Purpose Outputs General purpose outputs are available at TWN3 Mifare NFC and TWN3 Legic NFC. These outputs are available at a separate connector on the PCB. Currently, there are two outputs defined: OUTPUT0 and OUTPUT1. void OutputSet(byte Outputs,byte Status) Set the state of the general purpose output. Parameters: byte Outputs Binary or of the outputs to be switched. byte Status The new status of the specified outputs.
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 byte &SourceBits Reference to an array of bytes which represent a bit field which is the destination of the copy operation.
Elatec GmbH 6.2.5.7 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 void ConvertDigitsToBinary(byte &Dest,byte ByteCnt,byte &Source, byte DigitCnt,byte BitsPerDigit, byte Radix); Convert a packed array of digits stored in an array of bytes into a binary number. Parameters: byte &Dest byte ByteCnt byte &Source A reference to an array of bytes, which receives the result of the conversion The size in bytes of Dest. byte DigitCnt A reference to an array of bytes, where the packed array of digits is stored. The number of digits, which are stored in Source.
Elatec GmbH byte ConvertBinaryToASCII(byte &Dest,byte &Source,byte FirstBit, byte BitCnt,byte Radix,byte MinDigits, byte MaxDigits) Convert a number, which is given as a bit field into ASCII format, and store it in an array of bytes. The conversion is made in the following sequence: 1. Convert the binary data to a number of digits, which is determined by the parameter MaxDigits. If MaxDigits is 0, then the number of digits is determined by the binary data itself. 2.
Elatec GmbH 6.2.5.8 Timer Operations void StartTimer(byte ID, byte Time) Start a timer. After the specified time, the timer goes into the timed-out state, which can be tested by the function TestTimer. A timer is running in real time in the background. This means, that even if other tasks are performed by the script, the time till time-out is still kept correctly. The timed-out state is reached only one time. Parameters: byte ID The ID of a timer which maybe one of the four available timer 0 to 3.
Elatec GmbH void XTEAEncrypt(byte &Data) Encrypt an array of 16 bytes. Parameter: byte &Data Reference to an array of 8 bytes to be encrypted. Return: None. void XTEADecrypt(byte &Data) Decrypt an array of 16 bytes. Parameter: byte &Data Reference to an array of 8 bytes to be decrypted. Return: None. void GetRandomBytes(byte &Data,byte ByteCount) Calculate a number of random values in the range from 0 to 255. Parameter: byte &Data Reference to an array, which receives the random bytes.
Elatec GmbH 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. Either one of the defined constants: USBVCOM: The TWN3 reader is emulating a virtual COM port. USBHID: The TWN3 reader is emulating a keyboard. byte GetDeviceType() Retrieve the information, which family of transponders this device supports. Parameter: Return: None.
Elatec GmbH 7. Firmware History Version Changes V4.02 Initial release V4.07 Send ALT codes Support for TWN3 IndiTag Support for TWN3 MultiISO New functions regarding Mifare (identical to MultiISO): ModuleSendChar, ModuleSendHexByte and ModuleReceiveLine New functions regarding HID iClass: IClassGeneric and IClassTagSearchApp Increased maximum key repeat rate V4.08 Support for ISO14443B (Version MultiISO) V4.
Elatec GmbH 8. Technical Data HID Prox Multi125 Inditag Mifare Housing Mifare NFC Frequency 125 kHz HID iClass Legic Legic NFC 75mA typ. 280mA peak 140mA typ. 200mA peak 13.56 MHz Dimensions 88mm x 56mm x 18mm Power Supply 5V ± 10% via communication cable Supply Current 50mA typ. 140mA peak 130mA typ. 220mA peak 160mA typ. 220mA peak 55mA typ. 120mA peak 65mA typ. 120mA peak Temperature Range 110mA typ. 180mA peak 220mA typ.
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.
