Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Introduction

In the following we show you how you can connect a finger scanner from the ekey company (www.ekey.net) to the Beckhoff hardware and communicate between it and TwinCAT.

Library download


Connection of an ekey finger scanner to an EL6041

The finger scanner has four connections. The data is output on terminals 1 and 2. Terminals 3 and 4 are intended for the power supply (24 V DC). The terminal and the finger scanner must both be set to the same baud rate.

Notice 		Installation
It is essential to follow the manufacturer’s installation instructions.

Connect the finger scanner to the EL6041 terminal as follows:

On the KL6041, pins 1 and 2 (Data +) and pins 5 and 6 (Data -) must be connected to each other.

Terminal settings

Set the KL6041 Terminal with the KS2000 Software to the following values:

  • 22 data bytes in the process image
  • Half duplex
  • Continuous transmission of the FIFO data
  • 19200 baud
  • 8 data bits, no parity
  • 1 stop bit

Setting the finger scanner

The finger scanner is parameterised using appropriate hardware and software, which must be procured from the manufacturer.


Connection of an ekey finger scanner to an EL6021

The finger scanner has four connections. The data is output on terminals 1 and 2. Terminals 3 and 4 are intended for the power supply (24 V DC). The terminal and the finger scanner must both be set to the same baud rate.

Notice 		Installation
It is essential to follow the manufacturer’s installation instructions.

Connect the finger scanner to the EL6021 terminal as follows:

On the EL6021, pins 1 and 2 (Data +) and pins 5 and 6 (Data -) must be connected to each other.

Terminal settings

Set the EL6021 terminal to the following values with the help of the TwinCAT System Manager:

  • 22 data bytes in the process image
  • Half duplex
  • Continuous transmission of the FIFO data
  • 19200 baud
  • 8 data bits, no parity
  • 1 stop bit

Setting the finger scanner

The finger scanner is parameterised using appropriate hardware and software, which must be procured from the manufacturer.


Connection of an ekey finger scanner to an EL6021

Beckhoff Knowledge Base: Communication with an ekey finger scanner

General Information

Hardware documentation in the Beckhoff information system: KL6041- Serial Interface RS422/RS485

Hardware documentation in the Beckhoff information system: EL6021 - Serial Interface RS422/RS485

Notice 		Support
Communication with an ekey finger scanner is supported only with a KL6041/EL6021 and is not available for BC/BX controllers.

Notice 		Baud rate
With a KL6041 all the functions of a finger scanner can be used only with a baud rate of 19200. The maximum baud rate of 115200 is supported only with an EL6021.
Further libraries required

For PC systems (x86) and Embedded PCs (CXxxxx):

  • Standard.lib
  • COMlibV2.lib
  • TcBase.lib
  • TcSystem.lib
  • TcUtilities.lib

Notice 		Memory usage
Some of the PLC program memory is already used up by integrating the library. Depending on the application program, therefore, the remaining memory may not be sufficient.


Integration in TwinCAT (CX9020)

This example describes how a simple PLC program for ekey can be written in TwinCAT and how it is linked with the hardware. The aim is to enable users and fingers to be created and evaluated in the finger scanner.

Unpacking the example files

Hardware

Setting up the components

The following hardware is required:

  • 1x CX9020 Embedded PC
  • 1x KL6041 - Serial Interface RS422/RS485
  • 1x FS UP I 800 ekey module or FS UP REL ekey module
  • 1 KL9010 end terminal

Set up the hardware and the ekey components as described in the respective documents.

This example assumes that the serial number of the finger scanner is known.

Software

Creation of the PLC program

Create a new PLC project for PC-based systems (ARM) and add the TcEkey.lib library.

Next, generate the following global variables:

VAR_GLOBAL
    KL6inData22B     AT%I* : KL6inData22B;
    KL6outData22B    AT%Q* : KL6outData22B;
    stCommandBuffer        : ST_EKEY_CommandBuffer;
END_VAR

KL6inData22B : input variable for the serial terminal.

KL6outData22B : output variable for the serial terminal.

stCommandBuffer: required for communication with ekey.

All blocks with ekey must be executed in one task.

Therefore, create a MAIN program (CFC) in which the FB_EKEY_Communication and FB_EKEY_FingerScanner function blocks are called. Make sure to link the communication block with pComIn, pComOut and stCommandBuffer.

The last eight digits of the serial number are entered at the sSN input of the finger scanner and stCommandBuffer is connected to the global variable stCommandBuffer. To create users and fingers, all other local variables are assigned as shown below.

Go to the task configuration and give the task a lower interval time. More precise information on this can be found in the description of the FB_EKEY_Communication function block.

Load the project to the CX as the boot project and save it.

Configuration in the System Manager

Create a new System Manager project, select the CX as the target system, and search for the associated hardware.

Add the PLC program created above under PLC configuration.

Now link the global variables of the PLC program with the Bus Terminal inputs and outputs, create the allocations, and activate the configuration. Then start the device in run mode.
Your CX is now ready for use.

With the appropriate variables, users and fingers can now be created in the finger scanner and fingers drawn over the line sensor can be evaluated.


Integration in TwinCAT (CX9020)

This example describes how a simple PLC program for ekey can be written in TwinCAT and how it is linked with the hardware. The aim is to enable users and fingers to be created and evaluated in the finger scanner.

Unpacking the example files

Hardware

Setting up the components

The following hardware is required:

  • 1x CX9020 Embedded PC
  • 1x EL6021 – Serial Interface RS422/RS485
  • 1x FS UP I 800 ekey module or FS UP REL ekey module
  • 1x EL9111 end cap

Set up the hardware and the ekey components as described in the respective documents.

This example assumes that the serial number of the finger scanner is known.

Software

Creation of the PLC program

Create a new PLC project for PC-based systems (ARM) and add the TcEkey.lib library.

Next, generate the following global variables:

VAR_GLOBAL
    EL6inData22B     AT%I* : EL6inData22B;
    EL6outData22B    AT%Q* : EL6outData22B;
    stCommandBuffer        : ST_EKEY_CommandBuffer;
END_VAR

EL6inData22B : input variable for the serial terminal.

EL6outData22B : output variable for the serial terminal.

stCommandBuffer: required for communication with ekey.

All blocks with ekey must be executed in one task.

Therefore, create a MAIN program (CFC) in which the FB_EKEY_Communication and FB_EKEY_FingerScanner function blocks are called. Make sure to link the communication block with pComIn, pComOut and stCommandBuffer.

The last eight digits of the serial number are entered at the sSN input of the finger scanner and stCommandBuffer is connected to the global variable stCommandBuffer. To create users and fingers, all other local variables are assigned as shown below.

Go to the task configuration and give the task a lower interval time. More precise information on this can be found in the description of the FB_EKEY_Communication function block.

Load the project to the CX as the boot project and save it.

Configuration in the System Manager

Create a new System Manager project, select the CX as the target system, and search for the associated hardware.

Add the PLC program created above under PLC configuration.

Now link the global variables of the PLC program with the Bus Terminal inputs and outputs, create the allocations, and activate the configuration. Then start the device in run mode.
Your CX is now ready for use.

With the appropriate variables, users and fingers can now be created in the finger scanner and fingers drawn over the line sensor can be evaluated.


FB_EKEY_Communication

This function block is used for background communication with a serial interface.

The cycle time of the PLC task should be no longer than 10 ms.

VAR_INPUT

bEnable            : BOOL;
eMode              : ComSerialLineMode_t;
pComIn             : POINTER TO BYTE;
pComOut            : POINTER TO BYTE;
uiSizeComIn        : UINT;

bEnable: communication with the serial interface is started if this input is TRUE.

eMode: clearly defines the serial hardware employed (KL6041 = SERIALLINEMODE_KL6_22B_STANDARD; EL6021 = SERIALLINEMODE_EL6_22B).

pComIn: pointer to the input variables of the process data of the serial terminal.

pComOut: pointer to the output variables of the process data of the serial terminal.

uiSizeComIn: size of the input process image of the serial terminal.

VAR_OUTPUT

bBusy              : BOOL;
bError             : BOOL;
udiErrorID         : UDINT;

bBusy: this output goes TRUE when a telegram is being transmitted or received.

bError: this output goes TRUE as soon as an error occurs. This error is described via the udiErrId variable.

udiErrorID: this output outputs an error code in the event of an error. bError goes TRUE at the same time.

VAR_IN_OUT

stCommandBuffer    : ST_EKEY_CommandBuffer;

stCommandBuffer: the FB_EKEY_Communication function block is connected to the scanner blocks via this structure.


FB_EKEY_FingerScanner

This function block is used for the operation of, and communication with a finger scanner.

It must be called cyclically and once for each scanner. Please note that the finger scanners are equipped with different functions. Not all functions of this function block are supported by all models.

VAR_INPUT

bEnable                     : BOOL;
sSN                         : STRING(8);
bNewFinger                  : BOOL;
byFingerID                  : BYTE;
byUserID                    : BYTE;
bFingerControlRelay         : BOOL;
eEnrollmentFunction         : E_EKEY_EnrollmentFunction;
bRemoveUser                 : BOOL;
bRemoveAllUsers             : BOOL;
byRemoveUserID              : BYTE;
eLedFunction                : E_EKEY_LEDFunction;
diLedClock                  : DINT;
bRelayOn                    : BOOL;
bResetAll                   : BOOL;
bReadTemplate               : BOOL;
bWriteUser                  : BOOL;
bWriteTemplate              : BOOL;
byReadTempFingerID          : BYTE;
byReadTempUserID            : BYTE;
bySetUserID                 : BYTE;
byWriteTempFingerID         : BYTE;
byWriteTempUserID           : BYTE;
stWriteTemplate             : ST_EKEY_FingerTemplate;

bEnable: the function block is processed if this input is TRUE.

sSN: each finger scanner has a unique ID. The ID can be calculated from the last 8 digits of the serial number. The last 8 digits of the serial number of the scanner must be entered at this input. The calculation is performed automatically each time the function block is started.

bNewFinger: sets the finger scanner to teaching mode in order to teach-in a new finger.

byFingerID: finger ID of the finger to be taught in.

byUserID: user ID of the finger to be taught in.

bFingerControlRelay: gives the finger the authorisation during the teach-in to actuate the internal relay on positive recognition of the finger. TRUE: internal relay is actuated, FALSE: internal relay is not actuated.

eEnrollmentFunction: defines the teach-in function. Normal enrollment: the finger is drawn only once over the line sensor. Triple enrollment: the finger is drawn three times over the line sensor. The advantage of the triple enrollment is that several points of recognition can be secured by the repeated scanning.

bRemoveUser: deletes a user from the internal memory of the finger scanner. The user ID to be deleted is specified at the RemoveUserID input.

bRemoveAllUsers: deletes all users from the internal memory of the finger scanner.

byRemoveUserID: see bRemoveUser input.

eLedFunction: defines the functional mode of the onboard LED on the finger scanner. In the case of a change at the input the applied functional mode is executed for the duration of diLedClock. See Enum E_EKEY_LEDFunction for setting options.

diLedClock: Defines the duty cycle of the LED functional mode. Duration is specified in milliseconds (1 = 10 ms; -1 = endless). See eLedFunction input.

bRelayOn: switches the internal relay of the finger scanner, if available.

bResetAll: resets the finger scanner.

bReadTemplate: reads a finger template from the memory of the finger scanner. The User ID and Finger ID of the finger to be read must be specified at the byReadTempUserID and byReadTempFingerID inputs. The template is then output at the stRecTemplate output.

bWriteUser: creates a user in the memory of the finger scanner. The User ID is specified at the bySetUserID input.

bWriteTemplate: transfers a finger template to the memory of the finger scanner. The User ID and Finger ID of the finger to be written must be specified at the byWriteTempUserID and byWriteTempFingerID inputs. The template is specified at the stWriteTemplate input. The user must already have been created before a template can be transferred to the finger scanner. See bWriteUser input.

byReadTempFingerID: see bReadTemplate input.

byReadTempUserID: see bReadTemplate input.

bySetUserID: see bWriteUser input.

byWriteTempFingerID: see bWriteTemplate input.

byWriteTempUserID: see bWriteTemplate input.

stWriteTemplate: see bWriteTemplate input.

VAR_OUTPUT

bBusy                       : BOOL;
bError                      : BOOL;
udiErrorID                  : UDINT;
bBufferOverload             : BOOL;
eState                      : E_EKEY_Command;
bReceived                   : BOOL;
byRecUserID                 : BYTE;
byRecFingerID               : BYTE;
byRecTempUserID             : BYTE;
byRecTempFingerID           : BYTE;
bBadFinger                  : BOOL;
dwBadFingers                : DWORD;
bGoodFinger                 : BOOL;
dwMaxConfigUser             : DWORD;
dwMaxConfigFinger           : DWORD;
stRecTemplate               : ST_EKEY_FingerTemplate;

bBusy: the output goes TRUE when a telegram is being transmitted.

bError: this output goes TRUE as soon as an error occurs. This error is described via the udiErrId variable.

udiErrorID: this output outputs an error code in the event of an error. bError goes TRUE at the same time.

bBufferOverload: indicates whether the communication buffer is full.

eState: indicates the state of the finger scanner.

bReceived: is TRUE when a telegram is being received. Changes to FALSE when the telegram has been received.

byRecUserID: indicates the received User ID in case of the positive recognition of a finger.

byRecFingerID: indicates the received Finger ID in case of the positive recognition of a finger.

byRecTempUserID: indicates the User ID of a received template.

byRecTempFingerID: indicates the Finger ID of a received template.

bBadFinger: indicates whether the finger on the scanner is invalid (no authorisation; not correctly identified).

dwBadFingers: Counter for invalid fingers. See bBadFinger output.

bGoodFinger: indicates whether the finger on the scanner is valid.

dwMaxConfigUser: indicates how many users have been taught into in the finger scanner. This value is taken directly from the finger scanner and is not calculated by the function block. This value may deviate if there is no communication with the finger scanner.

dwMaxConfigFinger: indicates how many fingers have been taught into the finger scanner in total. This value is taken directly from the finger scanner and is not calculated by the function block. This value may deviate if there is no communication with the finger scanner.

stRecTemplate: outputs a received finger template. see bReadTemplate input.

VAR_IN_OUT

stCommandBuffer             : ST_EKEY_CommandBuffer;

stCommandBuffer: the FB_EKEY_Communication function block is connected to the scanner blocks via this structure.


E_EKEY_EnrollmentFunction

TYPE E_EKEY_EnrollmentFunction :
(
    eEKEYEnrollNoChange     := 0,
    eEKEYEnrollTripple      := 1,
    eEKEYEnrollNormal       := 2
);
END_TYPE


E_EKEY_LEDFunction

TYPE E_EKEY_LEDFunction :
(
    eEKEYLedArrowOff                    := 13,
    eEKEYLedArrowLeft                   := 14,
    eEKEYLedArrowRight                  := 15,
    eEKEYLedArrowBoth                   := 16,
    eEKEYLedBlinkLeftRightOff           := 17,
    eEKEYLedBlinkLeftRightOn            := 18,
    eEKEYLedBlinkRightLeftOff           := 19,
    eEKEYLedBlinkRightLeftOn            := 20,
    eEKEYLedBlinkBoth                   := 21,
    eEKEYLedBlinkLeftRight              := 22,
    eEKEYLedBlinkLeftLeftRight          := 23,
    eEKEYLedBlinkLeftRightRight         := 24,
    eEKEYLedArrowLeftRed                := 25,
    eEKEYLedArrowRightRed               := 26,
    eEKEYLedArrowBothRed                := 27,
    eEKEYLedArrowLeftYellow             := 28,
    eEKEYLedArrowRightYellow            := 29,
    eEKEYLedArrowBothYellow             := 30,
    eEKEYLedArrowLeftGreenRightRed      := 31,
    eEKEYLedArrowLeftGreenRightYellow   := 32,
    eEKEYLedArrowLeftRedRightGreen      := 33,
    eEKEYLedArrowLeftYellowRightGreen   := 34,
    eEKEYLedArrowLeftRedRightYellow     := 35,
    eEKEYLedArrowLeftYellowRightRed     := 36
);
END_TYPE


ST_EKEY_CommandBuffer

TYPE ST_EKEY_CommandBuffer :
STRUCT
    stSend              : ARRAY[0..EKEY_MAX_SEND_BUFFER_SIZE] OF ST_EKEY_SendData;
    stReceive           : ARRAY[0..EKEY_MAX_NR_OF_READER] OF ST_EKEY_RecData;
    bSendBufferBlocked  : BOOL;
    uiIndex             : UINT;
END_STRUCT
END_TYPE


Error Codes

Value (hex) | Value (dec) | Description
0x0000 | 0 | No error.
0x8001 | 32769 | Input parameters have changed during reception.
0x8002 | 32770 | Overflow of the send buffer.
0x800A | 32778 | End of the string.
0x800B | 32779 | String may not contain any zero characters.
0x8014 | 32788 | Invalid data pointer.
0x8015 | 32789 | Invalid data pointer for received data.
0x8016 | 32790 | Invalid length of received data.
0x8017 | 32791 | End of the data block.
0x8018 | 32792 | Invalid size of the process data.
0x8101 | 33025 | Operating mode is not supported.
0x8102 | 33026 | Invalid channel number.
0x83E8 | 33768 | Unknown master.
0x83E9 | 33769 | CRC error.
0x83EA | 33770 | Error during enrollment.
0x83EB | 33771 | Error.
0x83EC | 33772 | Finger scanner timeout.
0x83ED | 33773 | Error while reading the template.
0x83EE | 33774 | Error during transmission.
0x83EF | 33775 | Serial number has not been set.
0x83F0 | 33776 | Enrollment function is not supported (see E_EKEY_EnrollmentFunction).
0x83F1 | 33777 | LED function is not supported (see E_EKEY_LEDFunction).
0x83F2 | 33778 | Time for LED function lies outside the valid range (-1 - 2147483647).
0x83F3 | 33779 | Operating mode is not supported (see eMode of FB_EKEY_Communication).
0x9001 | 36865 | Invalid baud rate.
0x9002 | 36866 | Invalid number of data bits.
0x9003 | 36867 | Invalid number of stop bits.
0x9004 | 36868 | Invalid parity.
0x9005 | 36869 | Invalid handshake.
0x9006 | 36870 | Invalid number of registers.
0x9007 | 36871 | Invalid register.
0x9008 | 36872 | COM timeout.


Teaching in a finger

In order to teach in a finger, the finger must be given a User ID and a Finger ID. The maximum number of fingers that can be saved in the finger scanner depends on the respective model.

Normal enrollment

The User ID is specified at the byUserID input and the Finger ID at the byFingerID input of the FB_EKEY_FingerScanner. The finger scanner is placed in teach-in mode by a rising edge on the bNewFinger input and the status LED begins to light orange.

A finger can now be read in. Please observe the correct finger position when drawing it over the scanner (see documentation for the finger scanner). If the finger has been read in correctly, the status LED changes to green and the finger scanner reverts automatically from teach-in mode to normal mode.

If the finger was not identified correctly, the status LED changes to red and the process is repeated. The finger must then be drawn over the finger scanner again. Please start only when the LED lights up orange again.

The finger scanner switches automatically back to normal mode after approximately 10 seconds if there is no activity in teach-in mode.

Description of the LEDs

Description | LED function | Status LED left | Status LED right
waiting for finger | orange | off | off
Extraction | orange (flashing) | off | off
Enrollment OK | green (2 sec.) | off | off
Enrollment not OK | red (2 sec.) | off | off

Triple enrollment

The process is the same as in Normal enrollment, except that the steps are carried out three times in total.

Description of the LEDs

Description | LED function | Status LED left | Status LED right
waiting for finger | orange | off | off
Extraction | orange (flashing) | off | off
Extraction OK | green (1 sec.) | off | off
Quality poor - retrying | orange | red | off
2nd pass
waiting for finger | orange | off | off
Extraction | orange (flashing) | off | off
Extraction OK | green (1 sec.) | off | off
Quality poor - retrying | orange | red | off
3rd pass
waiting for finger | orange | off | off
Extraction | orange (flashing) | off | off
Extraction OK | green (1 sec.) | off | off
Quality poor - retrying | orange | red | off
Quality good – enrollment OK | green (2 sec.) | green (2 sec.) | green (2 sec.)


Transfer of finger templates

In order to read out a finger template, a unique User ID and Finger ID must be transmitted together with the query.
If the template is to be transferred to another finger scanner, then the user must be created beforehand if he does not already exist.

Reading out a template

Specify a unique User ID and Finger ID at the byReadTempUserID and byReadTempFingerID inputs. The readout is started by a rising edge on the bReadTemplate input. A finger template may have a size of several hundred bytes, therefore the entire process can take a few seconds. The received template is output at the stRecTemplate output.

If a telegram is lost or a communication error occurs during the procedure, the bError output is set to TRUE. The precise cause of the error can be taken from the error code displayed at the udiErrorID output.

Writing a template

When transferring a finger template to another finger scanner, the respective user must first be created, if he does not already exist, so that the finger template can be properly accepted.
In order to create a user on the finger scanner, transfer a User ID to the bySetUserID input. The user is created on the finger scanner by a rising edge on the bWriteUser input. If the user was properly created, the value of the dwMaxConfigUser output increases.

The transfer of the template can begin once the user has been created on the scanner or if he already exists.

In order to transfer a finger template, the correct User ID must be specified at the byWriteUserID input, the correct Finger ID at the byWriteFingerID input and the matching finger template at the stWriteTemplate input when transmitting. Transmission is started by a rising edge on the bWriteTemplate input. A finger template may have a size of several hundred bytes, therefore the entire process can take a few seconds.
If the finger template was properly transferred, the value at the dwMaxConfigFinger output increases.