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.


Overview

TwinCAT IO with FC310x, FC510x and FC520x

TwinCAT IO contains the device drivers and the configuration software (TwinCAT System Manager) for the FC310x, FC510x and FC520x PC cards under Windows NT, 2000 and XP.
The FcIoApi DLL provides the interfaces for freely selectable Windows applications for accessing the process data of these PC cards.


Overview

Regarding the configuration of the fieldbus via the TwinCAT System Manager please refer to the descriptions of the following PC cards: FC310x, FC510x, and FC520x, which also contain detailed descriptions of the respective diagnostics interfaces.

In addition to the fieldbus configuration, an IO task for re-triggering the associated fieldbus card has to be set up in the TwinCAT System Manager. The cycle time of the IO task corresponds to the fieldbus cycle time. To this end, at least one fieldbus device variable (FC310x, FC510x or FC520x) has to be linked with an IO task variable.


Setting up an IO task

An IO task has to be set up in the TwinCAT System Manager tree under Real-time configuration:

Right-click on Additional tasks for adding a task (IO task):

The task name can be modified in the dialog that appears:

The IO task settings can now be adjusted in the right half of the window:

Click on the Auto start check box in order to adjust the fieldbus cycle time under Cycle ticks. The port for the FcIoApi DLL function calls is also required, all other parameters can remain unchanged.

Linking the IO task with the fieldbus device

At least one IO task variable has to be linked with the fieldbus device. This is done via the IO task inputs in the tree:

Right-clicking brings up a pop-up menu through which a new variable can be appended:

In the variable dialog, the variable name, start address (address in the process image of the IO task), and variable type can be specified:

Now select the variable assigned to the fieldbus device by clicking on the Linked w. button in the "Variable" tab in the window on the right:

The variables available for linking are now displayed in the "Variable link" dialog. Select the associated variable and confirm with OK:

The "Variable" tab now shows the link information.

Starting the fieldbus

Finally, save the project in the registry (via the registry icon in the System Manager) and start TwinCAT (via the TwinCAT icon in the TwinCAT System Manager or in the Icon bar at the bottom right).

The fieldbus should now start up. The states can be diagnosed or outputs set via the System Manager.

Documents

The functionalities of the Beckhoff PCI card FC310x (as Master and Slave) for use under TwinCAT (NCI, PTP, PLC and IO) is described below.

The following sections also apply to the PROFIBUS connection for the CX1000 (CX1500-M310 (master) or CX1500-B310 (slave)); the name FC310x then also refers to the CX1500-M310 master or CX1500-B310 slave connection.


Access to fieldbus process data

Consistent access via the IO task only works for fieldbus variables that are linked to the IO task. As shown above for an input variable configuration, for all fieldbus variables to be accessed consistently, associated IO task variables have to be created and linked with them. The access function offsets refer to the addresses of the IO task variables (the BoxErrorCounter variable is allocated to address 0 of the input process image of the IO task):

The process image of the IO task can be exported in the form of an H file by right-clicking on the IO task in the tree:

StartImageUpdate

long StartImageUpdate(int portNo, int time, int outpLength, int inpLength);

The StartImageUpdate function must be called once during start-up of the application for initiating the timer that ensures consistent access to the process data. The port portNo of the IO task, the time cycle time time in ms, and the length of the input or output process image inpLength or outpLength of the IO task (according to the addresses generated during variable definition) must be specified. Within the timer routine the input process image of the IO task is read consistently and held in the local buffer, enabling fast access to the input process data via the function ReadInputs. The output process image of the IO task is only consistently updated with the local process image, if the local process image was accessed by calling WriteOutputs. The WriteOutputs call is therefore very quick.

Return values:

0: no error

-1: Timer could not be started

-2: AMS address could not be read

-3: Not enough memory for local process image

-4: Timer already running

StartImageUpdateWithWd

long StartImageUpdateWithWd(int portNo, int time, int outpLength, int inpLength, int wdTime);

The function StartImageUpdateWithWd has the same functionality as StartImageUpdate, although in addition it starts a watchdog. The watchdog is re-triggered when the functions ReadInputs or WriteOutputs are called. If this is not the case during the watchdog time, an IO reset is carried out for all devices (this leads to the outputs being disabled), and the outputs in the process image are set to 0.

StopImageUpdate

long StopImageUpdate(void);

The function StopImageUpdate only has to be called if the DLL is not automatically unloaded on termination of the application (e.g. for applications based on LabVIEW-CVI).

Return values:

0: no error

-5: DLL no longer active

ReadInputs

long ReadInputs(int offset, int length, unsigned char * pData);

The function ReadInputs is used to read the local input process image or parts thereof. The following parameters are transferred: the offset within the input process image of the IO task, the length of the data to be read, and a pointer pData to a memory area into which the input data can be copied.

Return values:

0: no error

-1: Timer not running

-2: Offset too large

-5: DLL no longer active

WriteOutputs

long WriteOutputs(int offset, int length, unsigned char * pData);

The function WriteInputs is used to write to the local input process image or parts thereof. The following parameters are transferred: the offset within the output process image of the IO task, the length of the data to be read, and a pointer pData to a memory area into which the output data can be copied.

Return values:

0: no error

-1: Timer not running

-2: Offset too large

-5: DLL no longer active


Access to fieldbus process data

TwinCAT IO and FCxxxx

Direct DP-RAM access

As an alternative to consistent access via the IO task, direct access to the DP-RAM is also available. Only WORD consistency is possible, although access is very fast, and the maximum dead time (age of a read variable or delay time until a variable is sent to the fieldbus after writing) is the same as the cycle time of the IO task. Please note that that the fieldbus output variables that are written via direct access must not be linked with IO task variables, since they would be overwritten again by the IO task. The offsets of the access functions refer to the fieldbus device variable addresses, i.e. the address should be looked up under the "Variable" tab for the associated variable in the fieldbus devices (address 4.1 in the example shown):

With FC310x PROFIBUS PC cards please note that the 4 bytes preceding the first input and output variable of a PROFIBUS slave are used for the PROFIBUS protocol header (i.e. the smallest variable offset for the FC310x is also 4). Writing of these respective 4 bytes would lead to PROFIBUS malfunction. Therefore, only those areas actually containing variables should be accessed directly. An overview can be displayed at the bottom of the window on the right by clicking on the process image of the device in the tree:

Options for printing the list or copying it to Excel, for example, are available through right-clicking on the list.

The access functions have to use the DP-RAM address that is shown under PCI bus/slot on the "FC310x", "FC510x" or "FC520x" tab when the fieldbus device is clicked in the tree:

ReadInputsDirect

long _stdcall ReadInputsDirect(unsigned long dpRamAddress, int offset, int length, unsigned char * pData);

The ReadInputsDirect function is used for reading fieldbus device input variables directly from the DP-RAM. Calling of this function is very fast (approx. 1.5 µs per word). The DP-RAM address dpRamAddress of the fieldbus device, the offset and the length of the input variables in the DP-RAM and a pointer pData to a memory area into which the input data can be copied are transferred.

Return values:

0: no error

-1: DP-RAM pointer could not be allocated

-2: Offset too large

-3: DP-RAM address is different than for previous calls of ReadInputsDirect or WriteOutputsDirect

-5: DLL no longer active

WriteOutputsDirect

long _stdcall WriteOutputsDirect(unsigned long dpRamAddress, int offset, int length, unsigned char * pData);

The WriteOutputsDirect function is used for writing fieldbus device input variables directly into the DP-RAM. Calling of this function is very fast (approx. 1.5 µs per area). The DP-RAM address dpRamAddress of the fieldbus device, the offset and the length of the output variables in the DP-RAM and a pointer pData to the output data are transferred.

Return values:

0: no error

-1: DP-RAM pointer could not be allocated

-2: Offset too large

-3: DP-RAM address is different than for previous calls of ReadInputsDirect or WriteOutputsDirect

-5: DLL no longer active

GetDirectInputPointer

void * GetDirectInputPointer(unsigned long dpRamAddress);

The function GetDirectInputPointer can be used to obtain a pointer to the input process image in the DP-RAM. The addresses of the input variables have to be taken from the System Manager as described above. The DP-RAM address dpRamAddress of the fieldbus device has to be transferred.

Return values:

0: Error

!= 0: Pointer to DP-RAM input variables

GetDirectOutputPointer

void * GetDirectOutputPointer(unsigned long dpRamAddress);

The function GetDirectOutputPointer can be used to obtain a pointer to the output process image in the DP-RAM. The addresses of the output variables have to be taken from the System Manager as described above. The DP-RAM address dpRamAddress of the fieldbus device has to be transferred.

Return values:

0: Error

!= 0: Pointer to DP-RAM input variables