cifx Device Driver Driver Manual WinAC RTX 2010 Hilscher Gesellschaft für Systemautomation mbh

Transcription

1 Driver Manual cifx Device Driver WinAC RTX 2010 Hilscher Gesellschaft für Systemautomation mbh DOC140702DRV02EN Revision 2 English Released Public

2 Introduction 2/84 Table of Contents 1 Introduction List of revisions Terms, abbreviations and definitions References Legal notes Copyright Important notes Exclusion of liability Export About the driver Requirements Features DVD content System concept Installation Windows components RTX components Configuration access Direct access (Windows based) Remote access to WinAC system (Windows based) Remote access to WinAC system (RTX based) Step by step installation guide Add driver function to a TIA project Loading the CIFXWinAC_TIA example Adding the driver to an existing TIA project Create a new TIA project Programming with the CIFX WinAC Driver Data organization Data blocks (DBs) PLC data types and usage Driver configuration DB_CIFXConfig DB_CIFXConfig / CIFXDriverStructure DB_CIFXConfig / CIFXBoardStruct DB_CIFXConfig / CIFXChannelStruct Setup I/O data update rate Initialization Adding additional boards / channels to the initialization Default content of FB_CIFXDriverInit Reading and writing I/O data Asynchronous packet transfer (SDOs) Packet structure FC_PacketHandling FC_PacketCreate FC_PacketCheck FC_PacketAnswer FC_PacketIndication FB_PacketSend FB_PacketReceive Error checking Driver errors FB and FC errors TIA example program Program Structure Function blocks description FB_CIFXDriverInit FB_CIFXIOReadInput FB_CIFXWriteOutput FB_CIFXPacketReceive... 58

3 Introduction 3/ FB_CIFXPacketSend FB_CIFXReadInformation Error handling Using the SYCON.net XML to SCL Converter Create an PDI-XML from SYCON.net Symbolic signal names in the fieldbus configuration Convert a XML to a SCL file Import SCL code into a TIA project Fieldbus configuration with SYCON.net Fieldbus start-up behavior Auto addressing Handshake of the process data User program monitoring CIFX WinAC Driver internals Driver loading, initialization and removing Driver functions Initialization process I/O data transfer between CIFX cards and process image Start/Stop of the bus communication Watchdog monitoring Packet data transfer Error codes Simatic WinAC RTX error list CIFX WinAC Driver error codes CIFX RTX Driver error codes Appendix List of tables List of figures Contacts...84

4 Introduction 4/84 1 Introduction WinAC (Windows Automation Center) is a product line from the Siemens AG and designed as an integrated solution for Control, HMI, Networking and Data Processing. WinAC is able to use a standard PC as hardware platform to run all of its functionality s. One of the modules is WinLC (Windows Logic Controller) which turns the PC into a SoftPLC. Since offering an Open Development Kit (WinAC RTX ODK), it is possible to extend WinAC by custom functionality s. It is also possible to directly interact with the program scan cycle of WinLC. This functionality s have been used to implement Hilscher s netx Communication InterFaces (CIFX) into the WinAC RTX systems. Authorization: The Hilscher CIFX-WinAC driver requires a license code on the Hilscher CIFX hardware. An "Error" will be reported if there is no license code on the hardware found. 1.1 List of revisions Rev Date Version Chapter Revision V1.000 All Created V SYCON.net V or later needed Table 1: List of revisions 1.2 Terms, abbreviations and definitions Term Description cifx Communication Interface based on netx PCI Peripheral Component Interconnect WDM Windows Driver Model DLL Dynamic Link Library RTDLL RTX Real Time Dynamic Link Library API Application Programming Interface SDO Service Data Object PDO Process Data Object DPM Dual-Port Memory Physical interface to all communication board (DPM is also used for PROFIBUS-DP Master). Table 2: Terms, abbreviations and definitions

5 Introduction 5/ References This document refers to the following documents: [1] Siemens: WinAC_ODK_USER_MANUAL.pdf [2] Hilscher Gesellschaft für Systemautomation mbh: Programming Reference Guide, CIFX API, Revision 2, english, 2013 [3] Hilscher Gesellschaft für Systemautomation mbh: Driver Manual, CIFX Device Driver, IntervalZero RTX, Revision 6, English, 2014 [4] Hilscher Gesellschaft für Systemautomation mbh: Dual-Port Memory Interface Manual, netx based products, Revision 12, english, 2012 Table 3: References

6 Introduction 6/ Legal notes Copyright Hilscher Gesellschaft für Systemautomation mbh All rights reserved. The images, photographs and texts in the accompanying material (manual, accompanying texts, documentation, etc.) are protected by German and international copyright law as well as international trade and protection provisions. You are not authorized to duplicate these in whole or in part using technical or mechanical methods (printing, photocopying or other methods), to manipulate or transfer using electronic systems without prior written consent. You are not permitted to make changes to copyright notices, markings, trademarks or ownership declarations. The included diagrams do not take the patent situation into account. The company names and product descriptions included in this document may be trademarks or brands of the respective owners and may be trademarked or patented. Any form of further use requires the explicit consent of the respective rights owner Important notes The manual, accompanying texts and the documentation were created for the use of the products by qualified experts, however, errors cannot be ruled out. For this reason, no guarantee can be made and neither juristic responsibility for erroneous information nor any liability can be assumed. Descriptions, accompanying texts and documentation included in the manual do not present a guarantee nor any information about proper use as stipulated in the contract or a warranted feature. It cannot be ruled out that the manual, the accompanying texts and the documentation do not correspond exactly to the described features, standards or other data of the delivered product. No warranty or guarantee regarding the correctness or accuracy of the information is assumed. We reserve the right to change our products and their specification as well as related manuals, accompanying texts and documentation at all times and without advance notice, without obligation to report the change. Changes will be included in future manuals and do not constitute any obligations. There is no entitlement to revisions of delivered documents. The manual delivered with the product applies. Hilscher Gesellschaft für Systemautomation mbh is not liable under any circumstances for direct, indirect, incidental or follow-on damage or loss of earnings resulting from the use of the information contained in this publication.

7 Introduction 7/ Exclusion of liability The software was produced and tested with utmost care by Hilscher Gesellschaft für Systemautomation mbh and is made available as is. No warranty can be assumed for the performance and flawlessness of the software for all usage conditions and cases and for the results produced when utilized by the user. Liability for any damages that may result from the use of the hardware or software or related documents, is limited to cases of intent or grossly negligent violation of significant contractual obligations. Indemnity claims for the violation of significant contractual obligations are limited to damages that are foreseeable and typical for this type of contract. It is strictly prohibited to use the software in the following areas: for military purposes or in weapon systems; for the design, construction, maintenance or operation of nuclear facilities; in air traffic control systems, air traffic or air traffic communication systems; in life support systems; in systems in which failures in the software could lead to personal injury or injuries leading to death. We inform you that the software was not developed for use in dangerous environments requiring fail-proof control mechanisms. Use of the software in such an environment occurs at your own risk. No liability is assumed for damages or losses due to unauthorized use Export The delivered product (including the technical data) is subject to export or import laws as well as the associated regulations of different counters, in particular those of Germany and the USA. The software may not be exported to countries where this is prohibited by the United States Export Administration Act and its additional provisions. You are obligated to comply with the regulations at your personal responsibility. We wish to inform you that you may require permission from state authorities to export, re-export or import the product.

8 About the driver 8/84 2 About the driver 2.1 Requirements Software Siemens Siemens SIMATIC WinAC RTX 2010 Siemens SIMATIC Step 7 Professional Hilscher Hilscher SYCON.net (Fieldbus System Configurator) Hilscher CIFX WinAC Driver for WinAC RTX 2010 Hilscher CIFX RTX Driver for IntervalZero RTX 2009 (Hardware driver for ISA, PCI/PCIe cards) Hilscher SYCON.net XML to Siemens SCL Converter Hilscher CIFX (PCI / PCIe based) hardware Table 4: Requirements Version 2010 SP1 V12 or later V or later (Media: Communication Solution DVD) V2.000 or later (Media: NXDRV-WINAC DVD) V or later (Media: NXDRV-WINAC DVD) V or later 2.2 Features Based on the Hilscher CIFX RTX device driver Support of Hilscher PCI and PCIe based netx hardware Unlimited number of netx devices supported Hilscher Master and Slave fieldbus protocols are supported Up to 4 communication channels per Hilscher device supported Cyclic data (input/output) and acyclic data packets (SDOs) are supported Configuration support by SYCON.net XML Conversion of input and output data from and to TIA data representation via XML file Input/Output data block generation via XML configuration to SCL code converter 1:1 mapping of input/output data without a configuration XML file possible I/O data update with hardware processed in background thread Example program for TIA Portal V12 or later

9 About the driver 9/ DVD content Folder Documentation WinAC Driver CIFX RTX Driver Installation CIFX RTX Driver Setup.exe CIFX WINAC Driver Setup.exe Driver TIA_Project XML_to_SCL_Converter Table 5: DVD content Content CIFX-WinAC Driver Documentation CIFX-WinAC Driver Manual CIFX RTX Driver Manual CIFX-WinAC and CIFX RTX Driver installation program Setup program for the CIFX RTX driver including documentation Setup program for the CIFX WinAC driver CIFX WinAC driver DLL (RTDLL) TIA Example Project SYCON.net XML to SCL Converter

10 About the driver 10/ System concept The CIFX WinAC Driver implementation is based on the Siemens SIMATIC WinAC RTX ODK following the definition of ODK Custom Code Extensions (CCX). Siemens SIMATIC WinAC RTX CCX handling Figure 1: WinAC ODK application using CCX The CIFX WinAC Driver offers transparent access to Hilscher CIFX devices. The driver functionality is located in the CIFXWinACDriver.RTDLL (CCX Software) which is called from the WinLC scan cycle via the WinAC ODK calling interface (SFB). Hardware access to the Hilscher hardware (Optional Third-Party Device) is based on the Hilscher CIFX RTX Driver for IntervalZero RTX (CIFXRTXDrv.rtdll). Necessary hardware configuration, firmware and configuration file settings are downloaded by the Hilscher CIFX Driver for Windows and stored in the Windows "Registry" and "Program File" directory. This information is used by the CIFX RTX Driver to get the Hilscher hardware into operation.

11 About the driver 11/84 System overview - hardware configuration Figure 2: System overview - hardware configuration (1) Driver / hardware configuration information Hardware configuration and settings are created by the CIFX Driver for Windows "CIFX Setup Program", installed with the Windows driver and stored in the Windows "Registry". The RTX driver accesses this information to start the hardware.

12 Installation 12/84 3 Installation The Hilscher CIFX WinAC Driver installation is handled in 2 steps. First step is the installation under Windows which has to be processed when the CIFX hardware is installed. This step also includes the hardware setup with the correct firmware and the fieldbus configuration. After the installation under Windows and the hardware configuration is finished, the RTX installation can be done. The RTX installation consists of the CIFX RTX Driver installation, the CIFX WinAC Driver installation and moving the CIFX hardware from Windows to RTX. Note: The Hilscher CIFX Windows Driver installation is necessary to pre-configure the Hilscher hardware. Note: The Hilscher product DVDs does not include any Siemens SIMATIC components. Please contact Siemens how to obtain their products and how to install them. It is recommended to first install the Siemens SIMATIC software including the RTX runtime environment. Necessary components Siemens SIMATIC WinAC RTX-2010 SP1 Hilscher "Communication Solution DVD" This DVD is part of the CIFX hardware delivery and contains the CIFX Device Driver for Windows and SYCON.net fieldbus configuration software for Windows. This DVD also contains all available firmware files, necessary to get the CIFX hardware running. Hilscher "CIFX WinAC Driver DVD" The WinAC driver DVD contains the installation for the basic CIFX RTX Driver, the CIFX WinAC Driver, a TIA example program and a XML to SCL converter.

13 Installation 13/ Windows components The Windows installation consists of 3 components CIFX hardware CIFX Device Driver for Windows SYCON.net (Hilscher fieldbus System Configurator) Note: Hilscher CIFX PC cards do not store any firmware or configuration on the hardware. It is the task of the CIFX Device Driver to load the firmware and the configuration during driver start up. The CIFX Device Driver for Windows is always necessary for the very first setup of the hardware. Configurations done during the first setup are stored in the Windows registry. The CIFX RTX Driver uses this registry information later on to be able to start the CIFX hardware, when the hardware is under control of RTX. The SYCON.net software is necessary for the fieldbus configuration. It is a Windows based application and usually it will be installed on the system where the CIFX hardware is installed. But it is also possible to install SYCON.net on a remote Windows system. Connection between the remote system, holding the SYCON.net installation, and the Windows/RTX runtime system can be established via a TCP connection and a dedicated CIFX TCP-Server tool on the Windows side of the runtime system. 3.2 RTX components The CIFX WinAC Driver comes on an own installation media (DVD) and contains separate installation programs for the CIFX RTX Driver and the CIFX WinAC Driver. IntervalZero RTX components: CIFX RTX Driver for IntervalZero RTX 2009 CIFX WinAC Driver for Siemens SIMATIC WinAC RTX 2010 The installation programs creating the necessary, pre-defined destination directories (usually "program files"), program folders, start menu entries and executing necessary registration procedures. Attention: After the preconfiguration of the CIFX hardware by the "CIFX Driver Setup Program" and SYCON.net, the CIFX hardware must be moved to RTX. Otherwise it is possible that Windows programs are able to access the CIFX hardware at the same time than RTX applications which results in unexpected system and fieldbus behaviors.

14 Installation 14/ Configuration access The fieldbus configuration can be done via several connections to the hardware. Direct Access (Windows based) All components must be installed on the WinAC PC system. Remote Access to WinAC System (Windows based) This is only possible as long as the CIFX hardware is not moved to RTX. The SYCON.net configuration software is installed on the remote PC. The necessary CIFX TCP server must be started on the WinAC system. Remote Access to WinAC System (RTX based) This is only possible if the CIFX hardware is already moved to RTX. The WinAC Logic Controller must be unloaded. The CIFX "Shared Memory Service" must be started on the WinAC RTX system. A CIFX TCP Server must be started on the WinAC Windows system Direct access (Windows based) Figure 3: Configuration: Direct access - WinAC system -> Windows based

15 Installation 15/ Remote access to WinAC system (Windows based) Note: The CIFX TCP Server program can be found on the "Communication Solution DVD". But this is only possible as long as the CIFX hardware is not moved to RTX Remote access to WinAC system (RTX based) Note: The "Shared Memory Service" is part of the CIFX Device Driver for IntervalZero RTX and described in the corresponding driver manual. After the configuration phase, the CIFX TCP Server and the Shared Memory Service must be unloaded before starting the WinAC Logic Controller.

16 Step by step installation guide 16/84 4 Step by step installation guide Note: Prerequisite is that you have already installed the Siemens SIMATIC WinAC RTX package. Step 1: Install the CIFX hardware and the CIFX Device Driver for Windows. Media: "Communication Solution DVD" Documentation:.\Documentation\1. cifx Manuals\EN\PC Cards cifx Software Installation UM xx EN.pdf Installation:.\Driver and Toolkit\Device Driver (NXDRV-WIN)\Installation Step 2: Setup the CIFX hardware by assigning a firmware to the hardware. Media: "Communication Solution DVD" Documentation:.\Documentation\1. cifx Manuals\EN\PC Cards cifx Software Installation UM xx EN.pdf Attention: Decide where to install the configuration software SYCON.net. This can be done either on the WinAC system if there are enough resources or on a remote Windows PC system. Access from the remote Windows PC system to the runtime system can be established by starting the CIFX TCP Server tool on the runtime Windows system. Step 3: Install SYCON.net for the fieldbus configuration (Remote PC or WinAC System) Media: "Communication Solution DVD" AutoRun:.\Communication-Solutions.exe Documentation:.\Documentation\0. Installation and Overview\Installation and Overview IG xx EN.pdf Installation:.\Software\SYCON.net\SYCON.net netx Setup.exe Step 4: Create a fieldbus configuration. Use SYCON.net (remote PC or run-time PC) Step 5: Install the CIFX RTX Driver and the CIFX WinAC Driver (WinAC System). Media: "CIFX WinAC Driver DVD" Documentation:.\Documentation\cifX Device Driver - WinAC DRV xx EN.pdf Installation:.\Installation\CIFX RTX Driver\CIFX RTX Driver Setup.exe.\Installation\CIFX WinAC Driver\CIFX WinAC Driver Setup.exe

17 Step by step installation guide 17/84 Step 6: Move the CIFX hardware from Windows to RTX. Note: Consult the IntervalZero RTX documentation. Step 6.1: Add RTX Support to the CIFX hardware. Open the RTX Properties, select Settings, right click CIFX PCI/PCIeDevice and click Add RTX INF Support. Step 6.2: Update the Windows driver. Open the Windows Device Manager. Select cifx PCI/PCIe Device, right click the entry and select Update Driver Software and afterwards select Browse my computer for driver software.

18 Step by step installation guide 18/84 Step 6.3: Select the new driver. Select Let me pick from a list of device drivers on my computer and then select cifx PCI/PCIe Device RTX Supported. Click Next to run the driver update process. Step 6.4: Verify the result. After updating the driver to RTX, the Windows Device Manager and the RTX Properties will show similar entries. Step 7: Use the CIFXWinaAC_TIA example to verify if hardware access is possible. Step 8: Add the CIFX WinAC driver functions to a new or existing TIA project.

19 Add driver function to a TIA project 19/84 5 Add driver function to a TIA project This chapter describes the usage of the CIFXWinAC_TIA example to add Hilscher fieldbus support to a TIA project. The default steps to use the Hilscher CIFX WinAC Driver Step 1: Copy/paste the driver data structures, FBs / FCs and DBs from the CIFXWinAC_TIA example program to a newly created or existing TIA project. Step 2: Add the driver initialization to your start OBs. Step 3: Configure the CIFX devices using he DB_CIFXConfig data block. Step 4 Call the drivers FBs/FCs functions from the PLC program. Depending to your needs, you can use I/O data function and/or the packet (SDO) functions. 5.1 Loading the CIFXWinAC_TIA example The TIA example is offered as a TIA ZAP archive file which can be retrieved by the TIA Portal. Therefore open the TIA portal, change into Project View and select Project > Retrieve.

20 Add driver function to a TIA project 20/ Adding the driver to an existing TIA project This can be done by opening the TIA example (see above) and copy / past the FBs / FCs / DBs and PLC data types from the example project to your TIA project. Note: The Hilscher hardware does not need any specific hardware settings in the TIA project. Insert the FBs / FCs / PLC data types from the example to the existing TIA project. Figure 4: Example project content Add the driver initialization code from OB100/OB102 into the projects OB100/OB102. //====================================================================== // OB100: COMPLETE RESTART //====================================================================== // CIFX driver initialization and startup handling // Step 1: Setup the DBs to store the INPUT and OUTPUT I/O data // for each Board[n]\Channel[n] later used in the application // Step 2: Call the driver initialization function //====================================================================== // Step 1: Create the DB numbers out of symbolic DBs and an created to hold // the I/O images for INPUT and OUTPUT data "DB_CIFXConfig".tDrv.atBoard[0].atChannel[0].wDB_I_MAP := "FC_GetDBNumber"("DB_I_MAP_Board0_CH0"); "DB_CIFXConfig".tDrv.atBoard[0].atChannel[0].wDB_Q_MAP := "FC_GetDBNumber"("DB_Q_MAP_Board0_CH0"); // call the driver intialization "idb_cifxdriverinit"(o_berror=>"db_cifxinfodata".bcifxdrivererror_init, o_wstatus=>"db_cifxinfodata".wcifxdrivererror_init);

21 Add driver function to a TIA project 21/84 Insert the drivers I/O and/or packet handling functions to your cyclic program function. //====================================================================== // Main OB1: CIFX WinAC Driver Example Program //====================================================================== // Do all tests with Board = 0 and Channel = 0 #icifxboardno := 0; #icifxchannelno := 0; // ============================================ // I/O data function test // ============================================ // Read input data "idb_cifxioreadinput"(i_nboardno:=#icifxboardno, // board number i_nchannelno:=#icifxchannelno, // channel number o_berror=>"db_cifxinfodata".atboardinfo[#icifxboardno].bcifxerror_ioread, o_wstatus=>"db_cifxinfodata".atboardinfo[#icifxboardno].wcifxerror_ioread); // TEST: I/O data #itemp := "DB_Q_MAP_Board0_CH0".Output_1; #itemp:=#itemp + 1; "DB_Q_MAP_Board0_CH0".Output_1 := INT_TO_BYTE(#iTemp); "DB_Q_MAP_Board0_CH0".Output_2 := "DB_I_MAP_Board0_CH0".Input_2; // Write output data "idb_cifxiowriteoutput"(i_nboardno:= #icifxboardno, // board number i_nchannelno:= #icifxchannelno, // chanel number o_berror=>"db_cifxinfodata".atboardinfo[#icifxboardno].bcifxerror_iowrite, o_wstatus=>"db_cifxinfodata".atboardinfo[#icifxboardno].wcifxerror_iowrite); Change DB_CIFXConfig to your needs

22 Add driver function to a TIA project 22/ Create a new TIA project Please consult the Siemens SIMATIC STEP7 Professional documentation how to use TIA. Step 1: Create a new TIA project. Step 2: Include a SIMATIC PC Station. Step 3: Change to the hardware configuration open the hardware catalog, select SIMATIC PC Station and insert, from the entry Controller the WinLC RTX entry into the configuration. The driver does not need any information from the STEP7 hardware configuration and therefore answer all following questions with No. Figure 5: TIA project: Create a new project

23 Add driver function to a TIA project 23/84 Step 2: Include a SIMATIC PC Station. Figure 6: TIA project: Add new device Step3: Add the necessary project settings (consult the TIA documentation). Figure 7: TIA project: PC station settings Note: The Hilscher hardware does not need any specific settings in the TIA project.

24 Add driver function to a TIA project 24/84 Step4: Add the FBs / FCs / DBs and PLC data types from the CIFXWinAC_TIA example to your TIA project (or use the example as a starting project and change it to your needs). Step5: Add the driver startup function to OB100/OB102 and the cyclic functions either to OB1 or your specific cyclic OB. Figure 8: TIA project: OB100 and OB1 entries Note: After creating the TIA project and adding FBs / FC / DBs etc. to it, it is necessary to configure the CIFX WinAC Driver. The configuration takes place in the DB_CIFXConfig.

25 Programming with the CIFX WinAC Driver 25/84 6 Programming with the CIFX WinAC Driver The usage of the CIFX WinAC Driver is shown in a TIA SCL based example project (CIFXWinACExample_TIA). This example shows the usage of the driver functions and can be used as a starting point for own projects or as a resource to take the FBs/FCs/DBs and PLC data types (data structures) necessary to work with the driver from. All driver data are organized in data blocks (DBs) and based on PLC data type structure definitions to be able to work fully symbolic oriented with the driver. Hilscher CIFX communication devices have a structured data layout. Each hardware can have several (up to 4) communication channels where each channel is dedicated to a specific fieldbus protocol stack. This means that it is possible that one CIFX hardware can have more than one communication channel. Figure 9: Typical communication channel layout By default, CIFX hardware (board) offer one physical connection to a fieldbus system and so only one communication channel is offered. On Real-Time Ethernet systems it is possible to have a second communication channel offering RAW Ethernet communication possibilities. For traditional fieldbus systems like PROFIBUS, CANopen and DeviceNet, Hilscher offers also dual channel PC cards. On such PC cards, each channel is located in an own communication channel and can be driven independently from each other. And also combinations of fieldbus system on one board are available.

26 Programming with the CIFX WinAC Driver 26/ Data organization Data blocks (DBs) Global configuration data block (the only one which has to be changed): DB_CIFXConfig global configuration data block Note: Only boards which are defined in the DB_CIFXConfig data block can be used. The user has to define either a board name (sboardname, e. g. CIFX0, CIFX1, ) or a slot number (nslotnumber = 1...9). Global Data Driver Data atboard[0] DB_CIFXConfig atchannel[0] atchannel[1] atchannel[2] Communication Channel 0 Communication Channel 1 CIFX Board 0 atchannel[3] atchannel[0] atboard[1] atboard[2] atboard[3] atchannel[1] atchannel[2] atchannel[3] atchannel[0]..[3] atchannel[0]..[3] Communication Channel 0 Communication Channel 1 CIFX Board 1 Figure 10: Data organization: DB_CIFXConfig

27 Programming with the CIFX WinAC Driver 27/84 Each device uses at least 2 I/O data blocks, which has to be defined in the DB_CIFXConfig: DB_I_MAP_BOARDn_CHm Input data block, board number(n)/channel number (m) DB_Q_MAP_BOARDn_CHm Output data block, board number(n)/channel number (m) Figure 11: Data organization: DB_CIFXConfig-DB_I_MAP / DB_Q_MAP Additional data blocks: DB_CIFXInfoData Board/Channel/Status related information Communication Channel 1 Communication Channel 0 CIFX Board 1 Communication Channel 1 Communication Channel 0 CIFX Board 0 Figure 12: Data organization: DB_CIFXInfoData

28 Programming with the CIFX WinAC Driver 28/84 DB_CIFXPacketData Packet related data Communication Channel 1 Communication Channel 0 CIFX Board 1 Communication Channel 1 Communication Channel 0 CIFX Board 0 Figure 13: Data organization: DB_CIFXPacketData Note: Do not change the structure and length of any data block, except the DB_I_MAP_BOARDn_CHm / DB_Q_MAP_BOARDn_CHm blocks, because underlying CIFX WinAC Driver functions are accessing these blocks. Note: If more than one CIFX board is used, it is necessary to extend the arrays in the data blocks to correspond to the number of used boards and number of communication channels per board.

29 Programming with the CIFX WinAC Driver 29/ PLC data types and usage PLC data type structures are extensively used to allow a symbolic addressing of the driver data. PLC data types used by DBs: DB name Structure name Description DB_CIFXConfig DB_CIFXInfoData DB_CIFXPAcketData CIFXDriverStruct CIFXBoardStruct CIFXChannelStruct CIFXInfoDataStruct CIFXBoardInfoStruct CIFXChannelInfoStruct CIFXCommonStatusStruct CIFXExtendedStatusStruct CIFXExtendedStateStruct CIFXPacketBoardStruct CIFXPacketChannelStruct CIFXPacketStruct Global driver data Board structure (array of boards) Communication channel structure (array of channels) Global information Board information (array of boards) Communication channel (array of channels) Common fieldbus protocol status (array of channels) Extended fieldbus protocol status (array of channels) Extended state entry Packet states and buffers for each board (array of boards) Packet channel structure for each channel (array of channels) Send and receive packet buffer (one per channel) Table 6: PLC data types used by DBs CIFXPacketHeaderStruct Structure of the packet header

30 Programming with the CIFX WinAC Driver 30/ Driver configuration The configuration of the CIFX WinAC Driver and the used CIFX hardware takes place in the DB_CIFXConfig data block (all other FBs / FCs are based on this data block). Note: How many communication channels are offered by a device depends on the hardware and firmware (usually 1). The layout of communication boards with their communication channels corresponds to the data organization and structures in the DB_CIFXConfig data block. Necessary setting DB_CONFIG settings Parameter name Value Description sboardname or nslotnumber e.g. "cifx0" or e.g. 3 A board can be selected either by its name (created by the driver) or if a hardware rotary switch is available and set to a value <> 0. This corresponds to the settings under Windows. wdb_i_map e.g A DB number which should receive the input data values from the fieldbus system. wdb_q_map e.g A DB number which holds the output data values from the fieldbus system. Optional settings DB_CONFIG Settings Parameter Name Value Description sxmlconfigurationfile e.g. "C:\Temp\Test.xml Configuration file settings if a symbolic I/O data blocks should be used. nioupdatetime 1..n I/O update time in milliseconds(default = 2ms) dinumofboardarrayentries 1..n Number of board structures in DB_CIFXConfig. This must be adjusted if more than one board should be used nnumberofchannelstructs 1..n Number of communication channel structures per board given in DB_CIFXConfig. This must be adjusted if more than one board should be used

31 Programming with the CIFX WinAC Driver 31/ DB_CIFXConfig Note: DB_CIFXConfig can be adapted to multiple boards with multiple communication channels and is preconfigured for ONE CIFX board with ONE communication channel, which is the common layout for all Hilscher devices. - Values marked as [IN] can be changed - Values marked with [OUT] are created by the driver DB_CIFXConfig data block Figure 14: View of DB_CIFXConfig DB_CIFXConfig consist of three data structures (defined under PLC data types): CIFXDriverStructure General driver information, settings and global handles CIFXBoardStruct Information and settings in a per CIFX board structure CIFXChannelStruct Communication channel information and settings structure per board The structured layout allows DB_CIFXConfig to be adjusted to the used devices with their communication channels and the CIFX WinAC Driver will use the same structures to store board specific information during the start-up phase of the hardware and takes user settings from them.

32 Programming with the CIFX WinAC Driver 32/84 Structure overview Structure: DB_CIFXConfig Value name wodkhandle CIFXDriverStructure atboard[0] atboard[n] Description ODK handle returned by CREA_COM Global driver information and settings Board structure array (default = 1 / no max.) atchannel[0] Communication channel 1st structure (default = 1 / max. = 4) atchannel[...] Board number (2nd structure) atchannel[0] atchannel[...] The wodkhandle is the global ODK handle used to access a custom code extension (CCX) from the PLC program and returned by executing CREA_COM initialization. This handle is necessary for any further functions calls to the CIFX WinAC driver DB_CIFXConfig / CIFXDriverStructure This is the global driver structure. The driver structure contains general information and settings for all handled boards. Structure: CIFXDriverStructure Value name Direction Data type Description dwdrivererror [OUT] DWord Driver error 0 = No error See error list at the end of this manual swinacdriverversion [OUT] String[30] Hilscher WinAC driver name and version as a readable string srtxdriverversion [OUT] String[30] Hilscher RTX driver name and version as a readable string dinumofavailableboards [OUT] DInt Number of available boards, found by the CIFX RTX driver idrivertraceloglevel [IN] Int Trace Logging Level 0 = OFF 1 = DEBUG 2 = INFO 4 = WARNING 8 = ERROR 15 = ALL Trace logs can be activated for debug, troubleshooting and error diagnostics purposes, depending on the chosen level. Logs are written to the RTXServer console window. dinumofboardarrayentries [IN] DInt Number of elements in the board array structure default = 1 This information will be used by the CIFX WinAC driver to verify how many board information blocks are available to store board data.

33 Programming with the CIFX WinAC Driver 33/ DB_CIFXConfig / CIFXBoardStruct The board structure contains information and settings on a per board base. The driver will insert the information collected during the driver startup. For driver calls which accessing board functions, the PLC program has to provide the corresponding structure. Structure: CIFXBoardStruct Value name Direction Data Type Description sboardname [IN] String[30] Board name (e.g. "CIFX0") Boards are usually selected by their device name. If a board should be opened, the CIFX WinAC Driver will compare the given name with the internal device name and only accepts the board if a board with the given name exists. Note: Board names are created by the driver in the order the driver finds the boards. This order can change if a board fails! A board can also be selected by its slot number (see nslotnumber), in this case, name can be left empty. nslotnumber [IN / OUT] DInt The slot number is given by a hardware rotary switch and used to uniquely identify a board. A board name is not necessary in this case. The slot number is the preferred identification method if more than one board is used. Shown if the device name sboarname is used dwboardhandle [OUT] DWord Board handle This handle is created by the driver if the board was successfully opened. The handle is used to identify the board on any further calls to EXEC_COM. dwboarderror [OUT] DWord Board error 0 = No error See error list at the end of this manual ndevicenumber [OUT] DInt Board product number Product number of the give board. This number is describes the type of hardware and can also be found on the device label nserialnumber [OUT] DInt The unique serial number of the board. This number can also be found on the device label navailablechannels [OUT] DInt The driver will insert the information how many communication channels are offered by the hardware. nnumberofchannelstructs [IN] DInt Number elements in the channel array default = 1 This information will be used by the CIFX WinAC Driver to verify how many channels information blocks are available to store channel specific data Note: sboardname or nslotnumber are used to define a board. The given name or slot number is used to access the hardware. These values are identical to the values the underlying CIFX RTX Driver uses to identify the boards and to initialize the boards with the stored firmware and configuration files, defined under Windows.

34 Programming with the CIFX WinAC Driver 34/ DB_CIFXConfig / CIFXChannelStruct The communication channel structure is created for each communication channel on a device, if DB_CIFXConfig offers such a structure. Like the board structure, this one is also filled with channel specific information during the startup of the driver. For driver calls which accessing a channel, the PLC program has to provide the corresponding structure. Structure: CIFXChannelStruct Value name Direction Data type Description dwchannelhandle [OUT] DWord The channel handles are automatically created by the driver, if a board is opened by the PLC program. These handles are internally used by the driver to identify a communication channel. dwerror [OUT] DWord Channel error 0 = No error See error list at the end of this manual wcomclass [OUT] Word The communication class defines if the fieldbus system is a master or slave device. (e.g. 0x0003 = Slave) wprotocolclass [OUT] Word The protocol class defines the fieldbus protocol (e.g. 0x0004 = CANopen) finputimagewithstate [OUT] Bool If this flag is set, slave state information is located at the end of the I/O input process data image (see DB_I_MAP). This information is only valid for aster devices. ninputimagesize [OUT] Int Maximum size in bytes of the I/O input process data image offered by communication channel. If the defined size definition of DB_I_MAP is foutputimagewithstate [OUT] Bool State of the output process data is located in the DB_Q_MAP noutputimagesize [OUT] Int Size of the output process data image in DB_Q_MAP sxmlconfigurationfile [IN] String[80] XML configuration file for symbolic addressing nioupdatetime [IN] Int Configured I/O process data update time (default: 2ms) wdb_i_map [IN] Word Data block to store the input process data wdb_q_map [IN] Word Data block holding the output process data

35 Programming with the CIFX WinAC Driver 35/ Setup I/O data update rate The CIFX WinAC Driver does not directly access the I/O image from the hardware. The I/O data are buffered in an internal I/O buffer area. For the I/O data update with the hardware, the driver generates a so called background thread for each device. The standard update rate is 2 milliseconds. The update rate for each communication channel can be changed via the nioupdatetime value in the global configuration block DB_CIFXConfig. Note: If nioupdatetime is set to 0, the driver uses a default value of 2 ms. I/O update rate settings nioupdatetime New update rate in milliseconds default 2ms The default time is internally set by the driver. to change it just insert a value unequal to zero and restart the logic controller Attention: Depending on the fieldbus system, the configuration and the number of connected slaves, the default update rate can be too fast. In such a case the Read/Write functions of the CIFX-WinAC Driver returning an error 0x800C0022 (DEVICE IO data exchange failed). In this case try to increase the nioupdatetime for the specific board/channel.

36 Programming with the CIFX WinAC Driver 36/ Initialization During the initialization, the driver searches available Hilscher boards and insert the number of available boards into the driver structure (dinumofavailableboards) located in DB_CIFXConfig. The Initialization takes place in OB100 / OB102 where the FB_CIFXDriverInit should be called. Example content for OB100 / OB102 //====================================================================== // OB100: COMPLETE RESTART //====================================================================== // CIFX dirver initialization and startup handling // Step 1: Setup the DBs to store the INPUT and OUTPUT I/O data // for each Board[n]\Channel[n] later used in the application // Step 2: Call the driver initialization function //====================================================================== // Step 1: Create the DB numbers out of symbolic DBs and an created to hold // the I/O images for INPUT and OUTPUT data "DB_CIFXConfig".tDrv.atBoard[0].atChannel[0].wDB_I_MAP := "FC_GetDBNumber"("DB_I_MAP_Board0_CH0"); "DB_CIFXConfig".tDrv.atBoard[0].atChannel[0].wDB_Q_MAP := "FC_GetDBNumber"("DB_Q_MAP_Board0_CH0"); // call the driver intialization "idb_cifxdriverinit"(o_berror=>"db_cifxinfodata".bcifxdrivererror_init, o_wstatus=>"db_cifxinfodata".wcifxdrivererror_init); Note: The driver initialization function block FB_CIFXDriverInit will return as soon as an error is detected without finishing the complete initialization. FB_CIFX_DriverInit opens the CIFX WinAC driver and always initializes board number 0 and communication channel 0. If additional boards / channels should be used, than the initialization part in FB_CIFXDriverInit must be extended.

37 Programming with the CIFX WinAC Driver 37/ Adding additional boards / channels to the initialization The whole initialization, including open board "0" and starting the fieldbus communication is done in FB_CIFXDriverInit. After a successful driver open call (dwboarderror = 0) the board/channel structure for the given board can be used. Board and communication channels, inside a board, are selected by their "BoardNumber" and "ChannelNumber" where both values are used as an index into the board (atboard[n]) and channel (atchannel[n]) structure. If more than one board should be used, the FB_CIFXDriverInit must be extended for each additional board which must be opened. // // Call SubCommand 1 (CMDOpenBoard) // Run initialisation for all configured/available boards // // Initialize Board number 0, repeat this for any further boards #wboardno := 0; #EXEC_COM_Instance(OBJHandle:=#wOdkHandle, Command:=1, InputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo], OutputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo], STATUS=>#o_wStatus); IF WORD_TO_INT(#o_wStatus) <> 0 THEN #o_berror := true; RETURN; END_IF; And the bus communication of the communication channels must be started. // // Call SubCommand 5 (CMDStartBUS) // Start BUS communication on the given Board/Channel // #wchannelno := 0; #EXEC_COM_Instance(OBJHandle:=#wOdkHandle, Command:=5, InputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo].atChannel[#wChannelNo], OutputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo].atChannel[#wChannelNo], STATUS=>#o_wStatus); IF WORD_TO_INT(#o_wStatus) <> 0 THEN #o_berror := true; RETURN; END_IF;

38 Programming with the CIFX WinAC Driver 38/ Default content of FB_CIFXDriverInit //====================================================================== // FB: CIFXDriverInit // - Reset ERROR // - Create COM Object (CREA COM) on first start // - Open CIFX driver and execute "Driver Init command (0) //====================================================================== // Reset all errors #o_berror := false; // assume there is no error #o_wstatus := 0; // Reset function status // Initialize ODK handle "DB_CIFXConfig".wOdkDrvHandle := 16#FFFF; // Open ODK interface // // Call CREA_COM to load the CIFX WinAC driver // #CREA_COM_Instance(PROGID:='*RTSS:cifXWinACDriver.rtdll', STATUS=>#wOdkHandle); // Store the ODK handle "DB_CIFXConfig".wOdkDrvHandle := #wodkhandle; // store the ODK handle in global driver DB IF WORD_TO_INT(#wOdkHandle) < 0 THEN #o_wstatus := #wodkhandle; #o_berror := true; RETURN; END_IF; // // Call SubCommand 0 (CMDOpenDriver) // Open the CIFX RTX driver and read possible driver errors and the number of // installed boards // #EXEC_COM_Instance(OBJHandle:=#wOdkHandle, Command:=0, InputData:="DB_CIFXConfig", OutputData:="DB_CIFXConfig", STATUS=>#o_wStatus); IF WORD_TO_INT(#o_wStatus) <> 0 THEN #o_berror := true; RETURN; END_IF; // // Call SubCommand 1 (CMDOpenBoard) // Run initialisation for all configured/available boards // // Initialize Board number 0, repeat this for any further boards #wboardno := 0; #EXEC_COM_Instance(OBJHandle:=#wOdkHandle, Command:=1, InputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo], OutputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo], STATUS=>#o_wStatus); IF WORD_TO_INT(#o_wStatus) <> 0 THEN #o_berror := true; RETURN; END_IF; // // Read Hardware Information from the board and channel // #idb_cifxreadinformation(i_ncmd:=1, // Read Board and Channel information i_nboardno:=0, i_nchannelno:=0, o_berror=>"db_cifxinfodata".atboardinfo[#wboardno].bcifxerror_info, o_wstatus=>"db_cifxinfodata".atboardinfo[#wboardno].wcifxerror_info);

39 Programming with the CIFX WinAC Driver 39/84 IF WORD_TO_INT(#o_wStatus) <> 0 THEN #o_berror := true; RETURN; END_IF; // // Call SubCommand 5 (CMDStartBUS) // Start BUS communication on the given Board/Channel // #wchannelno := 0; #EXEC_COM_Instance(OBJHandle:=#wOdkHandle, Command:=5, InputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo].atChannel[#wChannelNo], OutputData:="DB_CIFXConfig".tDrv.atBoard[#wBoardNo].atChannel[#wChannelNo], STATUS=>#o_wStatus); IF WORD_TO_INT(#o_wStatus) <> 0 THEN #o_berror := true; RETURN; END_IF;

40 Programming with the CIFX WinAC Driver 40/ Reading and writing I/O data The I/O data exchange with the CIFX hardware is controlled by two function blocks (FB_CIFXIOReadInput and FB_CIFXIOWriteOutput). Both FBs using the parameters i_nboardno and i_nchannelno to address the input/output DBs given in DB_CIFX_Config for each board/channel. Input Data: DB_CIFXConfig.tDrv.atBoard[#wBoardNo].atChannel[#wCIFXChannelNo].wDB_I_MAP Output data: DB_CIFXConfig.tDrv.atBoard[#wBoardNo].atChannel[#wCIFXChannelNo].wDB_Q_MAP In the TIA example program, the input and output FBs are called from OB1: //====================================================================== // Main OB1: CIFX WinAC Driver Example Program //====================================================================== // Do all tests with Board = 0 and Channel = 0 #icifxboardno := 0; #icifxchannelno := 0; // ============================================ // I/O data function test // ============================================ // Read input data "idb_cifxioreadinput"(i_nboardno:=#icifxboardno, // board number i_nchannelno:=#icifxchannelno, // channel number o_berror=>"db_cifxinfodata".atboardinfo[#icifxboardno].bcifxerror_ioread, o_wstatus=>"db_cifxinfodata".atboardinfo[#icifxboardno].wcifxerror_ioread); // TEST: I/O data #itemp := "DB_Q_MAP_Board0_CH0".Output_1; #itemp:=#itemp + 1; "DB_Q_MAP_Board0_CH0".Output_1 := INT_TO_BYTE(#iTemp); "DB_Q_MAP_Board0_CH0".Output_2 := "DB_I_MAP_Board0_CH0".Input_2; // Write output data "idb_cifxiowriteoutput"(i_nboardno:= #icifxboardno, // board number i_nchannelno:= #icifxchannelno, // chanel number o_berror=>"db_cifxinfodata".atboardinfo[#icifxboardno].bcifxerror_iowrite, o_wstatus=>"db_cifxinfodata".atboardinfo[#icifxboardno].wcifxerror_iowrite); Note: FB_CIFXIOReadInput and FB_CIFXIOWriteOutput can also be moved to any other cyclic OB. In general, inputs are read on the beginning of the cycle while outputs are written at the end of the cycle. Note: I/O data could have a different data representation than TIA (TIA = "Big Endian"). I/O data are convertible by the CIFX WinAC Driver, if the driver has configuration information delivered by a PDI XML file (see SYCON.net configuration). Otherwise I/O data are moved 1:1 between the CIFX hardware and the input/output data blocks.

41 Programming with the CIFX WinAC Driver 41/ Asynchronous packet transfer (SDOs) The CIFX WinAC Driver also supports Asynchronous Packet Transfers. Packet handling consists of either a request/response sequence where the user application initiates the transfer or an indication/confirmation sequence which is initiated by hardware. Note: SDOs are handled as fieldbus protocol specific types of packets. Asynchronous packet handling (SDO) is processed by a single FC (FC_PacketHandling) which can be called (cyclically) from anywhere in the PLC program. Reading and writing of asynchronous packets from/to the hardware is done via FB_CIFXPacketSend / FB_CIFXPacketReceive and the packet data are stored in a board/channel specific data blocks in DB_CIFXPacketData. Attention: CIFX cards are working with Little Endian data representation while TIA uses a Big Endian data representation. I/O data are convertible by the CIFX WinAC Driver while packet data are not, because the data content depends on the packet commands and these commands are unknown by the driver. Converting the packet data into the correct data representation is part of the PLC program. The whole packet handling consists of several FCs and FBs and one data block holding the packet buffers. Function / Data block name FC_PacketHandling FC_PacketCreate FC_PacketCheck FC_PacketIndication FB_CIFXPacketSend FB_CIFXPacketReceive DB_CIFXPacketData Description Main handling function Create a command packet in the send packet buffer. Note: This is an example function and must be adapted to the needs of the application. Check answer packet given in the receive packet buffer against the command given in the send packet buffer. Note: This is an example function and must be adapted to the created command packets. If an indication is received, this function should create an appropriate confirmation and send it back to the device. Note: This is an example function and must be extended to the indications which should be handled by the user program. Low level send function, passes one packet from the send packet buffer to the hardware. Low level send function, passes one packet from the send packet buffer to the hardware. Global data buffer per board/channel, holding the send/recv packet buffer and state information for the packet handling.

42 Programming with the CIFX WinAC Driver 42/84 PLC data types CIFXPacketHeader CIFXPacketStruct CIFXPacketChannelStruct CIFXPacketBoardStruct Description Structure describing the packet header Complete packet structure including header and data area (a packet can have a max. data size of 1596 bytes) Channel depending packet data structure including packet state information and one send and one receive packet buffer. Abstraction of the CIFXPacketChannelStruct as an array. Because each board can have up to 4 independent communication channels. Note: If SDO handling is not used, all FCs/FBs and the DB_CIFXPacketData block can be removed from the program. Packet transfer is not time critical and does not need to be done in very short millisecond cycles. Usually a cycle time of 10 to 20 ms should be sufficient, but if necessary it could also be called every 1 millisecond. The example program calls the handling from OB1: //====================================================================== // Main OB1: CIFX WinAC Driver Example Program //======================================================================... // ============================================ // Packet function test // ============================================ // Try to send/receive packets (SDOs) "FC_PacketHandling"(i_nBoardNo:=#iCIFXBoardNo, i_nchannelno:=#icifxchannelno, i_tpktdata:="db_cifxpacketdata".atboard[#icifxboardno].atchannel[#icifxchannelno]);

43 Programming with the CIFX WinAC Driver 43/ Packet structure The declaration of the packet data blocks corresponds to the RCX packet data format (see below). DB_CIFXPacketData: Figure 15: DB_CIFXPacketData Packet structure Packet structure - PLC data type = CIFXPacketStruct Structure Element Description theader dwdestination Packet destination (0x20 = default) dwsource Packet source (user defined e.g. 0x1234) dwdestinationid dwsourceid: dwlength dwid dwstate dwcmd Packet destination reference (0 = default) Packet source reference (0 = default) Packet data length in byte (amount of data in tdata) Packet identification (packet number) Packet state (0 = state OK) Packet command code / answer code dwextension/dwroute reserved (set to 0) tdata tdata[] Packet data byte area (content will be command/ answer specific) Note: A detailed description of system specific packets (RCX packets) can be found in the netx Dual-Port Memory Interface manual (reference [4]). Fieldbus protocol specific commands are described in the corresponding Protocol API Manual.

44 Programming with the CIFX WinAC Driver 44/ FC_PacketHandling This FC is the main function which handles the packet handling sequence. It will always check the hardware for incoming packets by calling FB_CIFXPacketReceive. If a packet is received, the handling calls FC_PacketCheck, to test if the received packet is a response (answer) to a previous sanded request (command) or an indication (command from the hardware). Answer packets will be verified against the command and if the answer is correct, the packet data can be evaluated by the PLC program. If an indication is received, the FC_PacketIndication is called in which the indication can be handled by the PLC program. If no packet is active, the handling function calls FC_CreatePacket to create a command packet and send this packet to the hardware. //====================================================================== // FC: FC_PacketHandling // Packet handling //====================================================================== // Packet handling is described in the "netx Dual Port Memory Interface Manual" // // Default packet handling // 1. Cyclic receive packets // 2. Verify type of packet received // - If an correct answer, processuser data in the answer packet // - If unknown packet received, just count them // - If an indication is received, create a corresponding response // 3. Create a command packet // // Program flow is maintained by the information in DB_CIFXPacketData //====================================================================== //====================================================================== // Read packet from hardware //====================================================================== // Try to receive a packet from the hardware. #pany := #i_tpktdata.trecvpkt; //"DB_CIFXPacketData".atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].tRecvPkt; // Receive a packet from a device "idb_cifxpacketreceive"(i_nboardno := #i_nboardno, i_nchannelno := #i_nchannelno, i_ppacket := #pany, o_ndr => #bndr, o_berror => #berror, o_wstatus => #wstatus); IF #bndr = TRUE THEN // We have received a packet, store the state for later #i_tpktdata.bpacketavailable := TRUE; ELSIF #berror THEN // We have a function error. // Full error is stored in DB_CIFXConfig.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].dwError. //... #dwerror := "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].dwError; END_IF; //====================================================================== // Handle packet //====================================================================== IF #i_tpktdata.bpacketavailable = TRUE THEN // Check what type of packet we have received "FC_PacketCheck"(i_tRecvPkt := #i_tpktdata.trecvpkt, i_tsendpkt := #i_tpktdata.tsendpkt, o_banswerreceived => #banswer, o_banswerunknown => #banswerunknown, o_bindicationreceived => #bindication); // We received an answer to a command IF #banswer = TRUE THEN // Check the state of the answer IF #i_tpktdata.trecvpkt.theader.dwstate <> 0 THEN // The answer packet shows a status error //...

45 Programming with the CIFX WinAC Driver 45/84 #dwerror := #i_tpktdata.trecvpkt.theader.dwstate; ELSE // We got the correct answer //... // Do something with the packet data // End packe transfer // // PROCESS THE CONTENT OF THE PACKET DATA "FC_PacketAnswerData"(i_nBoardNo := #i_nboardno, i_nchannelno := #i_nchannelno, i_trecvpkt := #i_tpktdata.trecvpkt); // #i_tpktdata.bcommandactive := FALSE; END_IF; END_IF; // We have received an UNKNOWN packet IF #banswerunknown = TRUE THEN // We have received a packet but not the one we waiting for #i_tpktdata.diunknowpacketcount := #i_tpktdata.diunknowpacketcount + 1; END_IF; // We have received an indication packet IF #bindication = TRUE THEN // Process indication "FC_PacketIndication"(i_nBoardNo := #i_nboardno, i_nchannelno := #i_nchannelno, i_trecvpkt := #i_tpktdata.trecvpkt, o_bindicationfault => #bindication, o_berror => #berror, o_wstatus => #wstatus); IF #berror = TRUE THEN // Failed to answer the indication packet #i_tpktdata.dierrorpacketcount := #i_tpktdata.dierrorpacketcount + 1; END_IF; END_IF; // We have finished the packet processing #i_tpktdata.bpacketavailable := FALSE; END_IF; //====================================================================== // Create a packet //====================================================================== IF #i_tpktdata.bcommandactive = FALSE THEN // Create a new send packet "FC_PacketCreate"(i_dwPktNumber := DINT_TO_DWORD(#i_tPktData.diPacketNumber), i_tsendpkt := #i_tpktdata.tsendpkt, o_ndr => #bndr); // Increment the packet number for the next send packet to have a unique packet ID // The packet ID will be verified in FC_PacketCheck #i_tpktdata.dipacketnumber := #i_tpktdata.dipacketnumber + 1; // Sent a packet to the device // Load pany to send packet buffer #pany := #i_tpktdata.tsendpkt; "idb_cifxpacketsend"(i_nboardno := #i_nboardno, i_nchannelno := #i_nchannelno, i_ppacket := #pany, o_berror => #berror, o_wstatus => #wstatus); IF #berror = TRUE THEN // Failed to send the packet #i_tpktdata.dierrorpacketcount := #i_tpktdata.dierrorpacketcount + 1; ELSE // Successfully send the packet, now we have to wait for the answer #i_tpktdata.bcommandactive := TRUE; END_IF; END_IF;

46 Programming with the CIFX WinAC Driver 46/ FC_PacketCreate Example which creates a "Firmware Identify Request" command for the hardware. //====================================================================== // FC: FC_PacketCreate // This function can be used to create a send packet. // The packet is created in the given i_tsendpkt buffer. // //====================================================================== // Packet handling is described in the "netx Dual Port Memory Interface Manual" // // ATTENTION: The packet HEADER comes in correct "BIG_ENDIAN" format // and is directly usable in WINAC. // Packet DATA ARE NOT CONVERTED and comming in LITTLE_ENDIAN // format and must be converted before used! //====================================================================== // EXAMPLE packet: "Firmware Identify Request" = 0x00001EB6 #o_ndr := FALSE; // Packet header given in PLC data format and will be converted by the CIFX WinAC Driver #i_tsendpkt.theader.dwdestination := 16# ; // Destination #i_tsendpkt.theader.dwsource := 0; // Source #i_tsendpkt.theader.dwid := #i_dwpktnumber; // Packet ID #i_tsendpkt.theader.dwstate := 0; // Packet state #i_tsendpkt.theader.dwcmd := DW#16#00001EB6; // Packet command => "Firmware Identify Request" #i_tsendpkt.theader.dwlength := 16# ; // Length of additional user data following theader // Packet data MUST be converted to "LITTLE_ENDIAN" format #i_tsendpkt.tdata[0] := 0; // Request user dat => Channel number 0..3 (communication channel) #o_ndr := TRUE; FC_PacketCheck General packet checking which evaluates the packet type (answer or indication) and check if the application waits for the answer. //====================================================================== // FC: FC_PacketCheck // Check the received packet if it is an answer or command. // If an asnwer packet is received, compare it against the send packet // to find out if this is the answer we waiting for. //====================================================================== // Packet handling is described in the "netx Dual Port Memory Interface Manual" // // ATTENTION: The packet HEADER comes in correct "BIG_ENDIAN" format // and is directly usable in WINAC. // Packet DATA ARE NOT CONVERTED and comming in LITTLE_ENDIAN // format and must be converted before used! //====================================================================== #o_bindicationreceived := FALSE; // Indication packet received #o_banswerreceived := FALSE; // Answer packet received #o_banswerunknown := FALSE; // Unknown answer packet received // // Packet processing // // We have a received a packet in i_trecvpkt and we have to check if it is an // answer (response) or a command (indication) packet // // This is done by checking the lowest bit in "dwcmd": // - dwcmd bit0 = 1 => ANSWER (Response) // - dwcmd bit0 = 0 => COMMAND (Indication) // // Check for command or answer packet // IF 0 = (#i_trecvpkt.theader.dwcmd AND DW#16#1) THEN // // This is a COMMAND packet //

47 Programming with the CIFX WinAC Driver 47/84 ELSE #o_bindicationreceived := TRUE; // // This is an ANSWER packet // // dwcmd bit0 = 1 => This is a answer packet // This is an answer to a previous command sended down to the hardware // 1. Check if the received answer compares to our command and if the packet ID is identical // 2. If known, check the state of the answer // dwstate = 0 => successfully handled by the device // dwstate <> 0 => command rejected by the device // Check which answer we got IF (#i_trecvpkt.theader.dwcmd AND DW#16#FFFE) = #i_tsendpkt.theader.dwcmd AND #i_trecvpkt.theader.dwid = #i_tsendpkt.theader.dwid THEN // This is an answer we expecting, return the packet status #o_banswerreceived := TRUE; ELSE // // This is an answer we are NOT expecting // #o_banswerunknown := TRUE; END_IF; END_IF; FC_PacketAnswer This function evaluates the content of the answer packet and must be adapted to the needs of the PLC program. The example sends a "Firmware Identify Request" and the answer holds several information from the hardware. Attention: CIFX cards are working with Little Endian data representation while TIA uses a Big Endian data representation. Packet data are received in Big Endian data representation and must be converted by the PLC program. //====================================================================== // FC: FC_PacketAnswer // Answer packet handling //====================================================================== // Packet handling is described in the "netx Dual Port Memory Interface Manual" // // Default packet handling // 1. Verify the type of the answer packet // 2. Get the answer data from the packet // //====================================================================== // // Check the answer type we have received IF #i_trecvpkt.theader.dwcmd = DW#16#1EB7 THEN // This is the answer of our example packet // // Command code: // // dwcmd = 0x00001EB7 => Identify Channel Firmware Confirmation // // Data Structure: // // RCX_FIRMWARE_IDENTIFY_CNF_DATA_T // The data are starting at i_trecvpkt.tdata // // Data Structure Content: // // /* IDENTIFY FIRMWARE CONFIRMATION */

48 Programming with the CIFX WinAC Driver 48/84 // #define RCX_FIRMWARE_IDENTIFY_CNF RCX_FIRMWARE_IDENTIFY_REQ+1 // typedef struct RCX_FW_VERSION_Ttag // { // UINT16 usmajor; /* firmware major version */ // UINT16 usminor; /* firmware minor version */ // UINT16 usbuild; /* firmware build */ // UINT16 usrevision; /* firmware revision */ // } RCX_FW_VERSION_T; // // typedef struct RCX_FW_NAME_Ttag // { // UINT8 bnamelength; /* length OF firmware name */ // UINT8 abname[63]; /* firmware name */ // } RCX_FW_NAME_T; // // typedef struct RCX_FW_DATE_Ttag // { // UINT16 usyear; /* firmware creation year */ // UINT8 bmonth; /* firmware creation month */ // UINT8 bday; /* firmware creation day */ // } RCX_FW_DATE_T; // // typedef struct RCX_FW_IDENTIFICATION_Ttag // { // RCX_FW_VERSION_T tfwversion; /* firmware version */ // RCX_FW_NAME_T tfwname; /* firmware name */ // RCX_FW_DATE_T tfwdate; /* firmware date */ // } RCX_FW_IDENTIFICATION_T; // // typedef struct RCX_FIRMWARE_IDENTIFY_CNF_DATA_Ttag // { // RCX_FW_IDENTIFICATION_T tfirmwareidentification; /* firmware ID */ // } RCX_FIRMWARE_IDENTIFY_CNF_DATA_T; // // Get the Firmware version from the received packet data area #wmajor := #i_trecvpkt.tdata[0]; // UINT16 usmajor; /* firmware major version */ #wminor := #i_trecvpkt.tdata[2]; // UINT16 usmajor; /* firmware major version */ #wbuild := #i_trecvpkt.tdata[4]; // UINT16 usmajor; /* firmware major version */ #wrevision := #i_trecvpkt.tdata[6]; // UINT16 usmajor; /* firmware major version */ END_IF; FC_PacketIndication This is an example for the packet indication handling which must be adapted to the needs of the PLC program. Attention: CIFX hardware are working with Little Endian data representation while TIA uses a Big Endian data representation. Packet data which are sent to the hardware must be converted by the PLC program to the Little Endian data representation. //====================================================================== // FC: FC_PacketConfirmation // This function creates a confirmation from a received packet. // //====================================================================== // Packet handling is described in the "netx Dual Port Memory Interface Manual" // // ATTENTION: The packet HEADER comes in correct "BIG_ENDIAN" format // and is directly usable in WINAC. // Packet DATA ARE NOT CONVERTED and comming in LITTLE_ENDIAN // format and must be converted before used! //====================================================================== #o_bindicationfault := FALSE; #o_berror := FALSE; #o_wstatus := 0; // We expecting an Indication packet in the i_trecvpkt buffer

49 Programming with the CIFX WinAC Driver 49/84 IF (#i_trecvpkt.theader.dwcmd AND DW#16# ) <> 0 THEN // This is not a command! #o_bindicationfault := TRUE; RETURN; END_IF; // If the command (Indication) is unknown // 1. Create a negative answer by setting dwcmd bit0 = 1 // 2. Set packet length dwlength = 0 // 3. Insert an error state into dwstate = RCX_UNKNOWN_COMMAN = 0xC // 4. Call FB_CIFXPacketSend() to send the answer (there will be no answer on an answer packet) // Check if we know the indication (0xFFF0 is just an example) IF #i_trecvpkt.theader.dwcmd = DW#16#FFF0 THEN // This commando we know, create a positive answer #i_trecvpkt.theader.dwcmd := DINT_TO_DWORD(DWORD_TO_DINT(#i_tRecvPkt.tHeader.dwCmd) + 1); #i_trecvpkt.theader.dwstate := 0; #i_trecvpkt.theader.dwlength := 0; ELSE // This command is unknown, create a negative answer by setting: // dwcmd bit0 = 1 // dwstate = RCX_UNKNOWN_COMMAND = 0xC // dwlength = 0 #i_trecvpkt.theader.dwcmd := DINT_TO_DWORD(DWORD_TO_DINT(#i_tRecvPkt.tHeader.dwCmd) + 1); #i_trecvpkt.theader.dwlength := 0; #i_trecvpkt.theader.dwstate := 16#C ; END_IF; #pany := #i_trecvpkt; // Answer the received "Indication" "idb_cifxpacketsend"( i_nboardno:=#i_nboardno, i_nchannelno:=#i_nchannelno, i_ppacket:=#pany, o_berror=>#o_berror, o_wstatus=>#o_wstatus);

50 Programming with the CIFX WinAC Driver 50/ FB_PacketSend Low level function sending one packet to the hardware. //====================================================================== // FB: CIFXSendPacket // // Packets are asynchronous commands which can be sent to the hardware // A packet consists of an Packet header and an user data area // which contains the packet data. // NOTE: Packet data have to be inserted in // "Little Endian" data representation //====================================================================== #o_berror := FALSE; // assume there is no error #o_wstatus := 0; // Reset function status // // Call SubCommand 13 (CMDSendPacket) // Send a packet to the hardware // #pany := #i_ppacket; #EXEC_COM_Instance(OBJHandle:="DB_CIFXConfig".wOdkDrvHandle, Command:=13, InputData:="DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo], OutputData:=#pAny, STATUS=>#o_wStatus); IF WORD_TO_INT(#o_wStatus) <> 0 THEN #o_berror := TRUE; END_IF; FB_PacketReceive Low level function tries to receive one packet from the hardware. //====================================================================== // FB: CIFXPacketReceive // // Packets are asynchronous commands/responses which can be sent to the hardware // A packet consists of a packet header and an user data area which // contains the packet data. // NOTE: Packet data are given in "Little Endian // data representation //====================================================================== #o_ndr := FALSE; // New data received #o_berror := FALSE; // assume there is no error #o_wstatus := 0; // Reset function status // // Call SubCommand 14 (CMDReceivePacket) // Receive a packet // #anypointer := #i_ppacket; #EXEC_COM_Instance(OBJHandle:="DB_CIFXConfig".wOdkDrvHandle, Command:=14, InputData:="DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo], OutputData:=#anyPointer, // Buffer to store the packet STATUS=>#o_wStatus); IF WORD_TO_INT(#o_wStatus) = 0 THEN // We have a new packet received #o_ndr := TRUE; ELSIF #o_wstatus = DW#16#9070 THEN // No packet received (status = 0x ) #o_ndr := FALSE; ELSE // This is a function error #o_berror := TRUE; END_IF;

51 Programming with the CIFX WinAC Driver 51/ Error checking Each hardware board and the corresponding communication channels have their own data structure in the DB_CIFXConfig data block containing an error variable. These error variables are set by the WinAC driver functions if an error occurs in one of the underlying driver functionalities Driver errors

52 Programming with the CIFX WinAC Driver 52/ FB and FC errors Because of the fact that all functions are able to handle multiple boards with multiple channels, each function has a board and channel number as an input parameter and for the error indication an error flag and error value which is returned. This allows the PLC program to handle all board / channels in the same way by just passing the board/channel number to the functions and error returns are stored independent for each board/channel. Error flags and error values returned by FBs and FCs are placed into DB_CIFXInfoData. Value Type Description bcifxerror_init Bool Error during initialization wcifxerror_init Word Initialization error value bcifxerror_ioread Bool Error in I/O read function wcifxerror_ioread Word I/O read error value bcifxerror_iowrite Bool Error in I/O write function wcifxerror_iowrite Word I/O write error bcifxerror_info Bool Error in read info function wcifxerror_info Word Read info error value Note: The error values returned by any FB and FC are limited to a "Word" which is also a limitation of the Siemens WinAC ODK. Driver errors are "DWord" based. This means the retuning error values just holding the "lower part" of the original driver error. The full driver error number is stored in DB_CIFXConfig.

53 Programming with the CIFX WinAC Driver 53/ TIA example program This section describes the TIA example program, which is part of the CIFX WinAC Driver. Program Name: CIFXWinAXExample_TIA The program allows to run as many Hilscher devices as installed under RTX simultaneously and independent of their fieldbus systems. All necessary configuration data and runtime states are placed into one single data block named DB_CIFXConfig. This data block contains all necessary handles and device configuration data to select a board (CIFX card) and the information about device specific data blocks which are used during runtime. The program design allows an easy integration of the CIFX WinAC Driver into an existing TIA project.

54 Programming with the CIFX WinAC Driver 54/ Program Structure Location Function Parameters / Handling OB100 / OB102 FB_CIFXDriverInit Initialization of the CIFX WinAC Driver Parameter: Error Bit: o_berror=> "DB_CIFXInfoData".bCifxDriverError_Init Error Status: o_wstatus=>"db_cifxinfodata".wcifxdrivererror_init Functions: Calling CREA_COM to load the CIFX WinAC Driver DLL Calling EXEC_COM(CMDDrvInit) to open the CIFX WinAC Driver Calling EXEC_COM(CMDOpenBoard) to open a specific board Calling FB_CIFXReadInformation to read board specific information Calling EXEC_COM(CMDStartBUS) to start the fieldbus communication OB1 FB_CIFXIOReadInput Read input process data form a defined CIFX board/communication channel Parameter: Board number: i_nboardno:=0 Channel number: i_nchannelno:=0 Error Bit: o_berror=> "DB_CIFXInfoData".atBoardInfo[#iCIFXBoardNo].bCifxError_IORead Error Status: o_wstatus=> "DB_CIFXInfoData".atBoardInfo[#iCIFXBoardNo].wCifxError_IORead Functions Calling EXEC_COM(CMDReadInputData) FB_CIFXIOWriteOutput Write output process data to a defined CIFX board/communication channel Parameter: Board number: i_nboardno:=0 Channel number: i_nchannelno:=0 Error Bit: o_berror=> "DB_CIFXInfoData".atBoardInfo[#iCIFXBoardNo].bCifxError_IOWrite Error Status: o_wstatus=> "DB_CIFXInfoData".atBoardInfo[#iCIFXBoardNo].wCifxError_IOWrite Functions Calling EXEC_COM( CMDWriteOutputData) FC_PacketHandling Handle asynchronous packet transfer. Parameter: Board number: i_nboardno:= #icifxboardno Channel number: i_nchannelno:= #icifxchannelno Packet data: i_pktdata:= "DB_CIFXPacketData".atBoard[#iCIFXBoardNo].atChannel[#iCIFXChannelNo] Functions Calling DB_CIFXPacketReceive Calling FC_PacketAnswer Calling FC_PacketIndication Calling FC_PacketCreate Calling FB_CIFXPacketSend

55 Programming with the CIFX WinAC Driver 55/84 FB_CIFXReadInformation Read information from the CIFX hardware. Parameter: Command ID: i_ncmd:= n 1 = Read board information 2 = Read Common Status Block 2 = Read Extended Status Block i_nboardno:= #icifxboardno Board number: Channel number: i_nchannelno:= #icifxchannelno Error Bit: o_berror=> "DB_CIFXInfoData".atBoardInfo[#iCIFXBoardNo].bCifxError_Info Status: o_wstatus=> "DB_CIFXInfoData".atBoardInfo[#iCIFXBoardNo].wCifxError_Inf Functions Calling EXEC_COM( CMDReadBoardInformation) Calling EXEC_COM( CMDReadChannelInformation) Calling EXEC_COM( CMDReeadCommonStatus) Calling EXEC_COM( CMDReadExtendedStatus) Table 7:TIA Example: Program structure

56 Programming with the CIFX WinAC Driver 56/ Function blocks description Note: Error state values returned by EXEC_COM calls are restricted to WORD values. The CIFX WinAC Driver error values are defined as DWORD values, not supported by EXEC_COM. Therefore all function block (FBs) return values are defined as WORD, delivering the low WORD of the error value. Full DWORD errors values are stored in the corresponding BORAD/CHANNEL structure in DB_CIFXConfig data block. Error values are described in the chapter Error codes on page FB_CIFXDriverInit Description Initializes the CIFX WinAC Driver and delivers device specific information in the DB_CIFXConfig necessary for the later device handling. Note: This FB uses the global DB_CIFXConfig data block to store errors and driver specific information. Function Parameters Direction Type Parameter Description out BIT o_berror Error bit set if an error occur out WORD o_wstatus Error value returned of the ODK / CIFX WinAC Driver function Used Data Blocks "DB_CIFXConfig" "DB_CIFXInfoData" Additional Functions CREA_COM CMDOpenDriver CMDOpenBoard FB_CIFXReadInformation CMDStartBUS Table 8: FB: FB_CIFXDriverInit

57 Programming with the CIFX WinAC Driver 57/ FB_CIFXIOReadInput Description Read the input process data from the CIFX hardware given by board/channel number. The input data are stored into a data block defined by a data block number. The data block number is taken form the board/channel entry in the DB_CIFXConfig data block. Function Parameter Direction Type Parameter Description in Int i_nboardno Board index in the DB_CIFXConfig atboard[] array in Int i_nchannelno Channel index in the DB_CIFXConfig atchannel array out BIT o_berror Error bit set if an error occur out WORD o_wstatus Error value returned of the ODK / CIFX WinAC Driver function Used Data Block Information "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo] "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].wDB_I_MAP CIFX WinAC Driver Function CMDReadInputData Table 9: FB: FB_CIFXIOReadOutput FB_CIFXWriteOutput Description Writes the output process data to the CIFX hardware defined by board/channel number. The output data are taken from a data block defined by a data block number. The data block number is taken from board/channel entry in the DB_CIFXConfig data block. Function Parameter Direction Type Parameter Description in Int i_nboardno Board index in the DB_CIFXConfig atboard[] array in Int i_nchannelno Channel index in the DB_CIFXConfig atchannel array out BIT o_berror Error bit set if an error occur out WORD o_wstatus Error value returned of the ODK / CIFX WinAC Driver function Used Data Block Information "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo] "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].wDB_Q_MAP CIFX WinAC Driver Function CMDWriteOutputData Table 10: FB: FB_CIFXIOWriteOutput

58 Programming with the CIFX WinAC Driver 58/ FB_CIFXPacketReceive Description A packet is a defined data structure to transfer acyclic data (e.g. SDOs, asynchronous fieldbus protocol services) between a user application and a Hilscher communication hardware. FB_CIFXPacketReceive allow asking the hardware if such an asynchronous packet waits on the hardware to be processed by the user application. If available the packet is transferred into a user defined data block. The content of the packet must be processed by the user application (SPS program), because the content of the packet also depends on the used fieldbus system and is unknown to the transport functionality of the driver. The read FB uses a data block (DB_CIFXPacketData) to store a received data packet. Function Parameter Direction Type Parameter Description in Int i_uboardno Board number which should be used in Int i_nchannelno Channel number which should be used in Any i_ppacket Pointer to a data block to store a packet out Bool o_ndr New data received out Bool o_berror Error bit set on error out WORD o_wstatus Error value Used Data Block Information "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo] "DB_CIFXPacketData".atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].tRecvPkt CIFX WinAC Driver Function CMDReceivePacket Table 11: FB: FB_CIFXPacketReceive

59 Programming with the CIFX WinAC Driver 59/ FB_CIFXPacketSend Description A packet is a defined data structure to transfer acyclic data (e. g. SDOs, asynchronous fieldbus protocol services) between a user application and a Hilscher communication hardware. FB_CIFXPacketSend allows sending of commands/answers to the hardware. A command/answer packet must be created in a data block using the pre-defined packet structure (DB_CIFXPacketData). The pointer to the data block must be passed to the write FB. The hardware, where the packet should be sent to, is defined by a board/channel number. Function Parameter Direction Type Parameter Description in Int i_uboardno Board number which should be used in Int i_nchannelno Channel number which should be used in Any i_ppacket Pointer to the send data packet out Bool o_berror Error bit set on error out WORD o_wstatus Error value Used Data Block Information "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo] "DB_CIFXPacketData".atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].tSendPkt CIFX WinAC Driver Function CMDReceivePacket Table 12: FB: FB_CIFXPacketSend

60 Programming with the CIFX WinAC Driver 60/ FB_CIFXReadInformation Description Hilscher CIFX devices are also offering various information structures (e.g. board/channel information, Common/Extended state information). This FB can be used to read all of these information structures. All information is stored in the DB_CIFXInfoData block, where each of the information has its own data area and data structure (PLC data type) definition. The FB returns with an appropriate error if one of the functions fails. Function Parameter Direction Type Parameter Description in Int i_ncmd Read information command 1 = Read board and channel information 2 = Read COMMON status block 3 = Read EXTENDED status block Int i_uboardno Board number which should be used in Int i_nchannelno Channel number which should be used out Bool o_berror Error bit set on error out WORD o_wstatus Error value Used Data Block Information "DB_CIFXConfig".Param.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo] "DB_CIFXInfoData" CIFX WinAC Driver Function CMDGetBoardInformation CMDGetChannelInformation CMDGetCommonStatus CMDGetExtendedStatus Table 13: FB: FB_CIFXReadInformation

61 Programming with the CIFX WinAC Driver 61/ Error handling All function blocks are returning an error state (bool "o_berror" and an error value (WORD "o_werror"). These values are stored in DB_CIFXInfoData (error bit and error value) for each FB/FC call. But CIFX WinAC Driver and CIFX RTX Driver errors values are DWORD based and could not be completely returned via the EXEC_COM calls into the user application. Therefore such errors are also written into the DB_CIFXConfig data block defined by the board and channel number. Possible error values PLC tag name bcifxerror_init wcifxstatus_init bcifxerror_info wcifxstatus_info bcifxerror_ioread wcifxstatus_ioread bcifxerror_iowrite wcifxstatus_iowrite bcifxerror_pktread wcifxstatus_pktread Description FB_CIFXDriverInit() Error indication bit ( 0 = no error / 1 = Error) Error Value FB_CIFXReadInformation () Error indication bit ( 0 = no error / 1 = Error) Error Value FB_CIFXIOReadData() Error indication bit ( 0 = no error / 1 = Error) Error Value FB_IOWriteData() Error indication bit ( 0 = no error / 1 = Error) Error Value FB_CIFXPacketReceive() Error indication bit ( 0 = no error / 1 = Error) Error Value Used data block to store FB/FC error return values "DB_CIFXInfoData" Used data block to store the CIFX WinAC driver DWORD error values "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].dwBoardError "DB_CIFXConfig".tDrv.atBoard[#i_nBoardNo].atChannel[#i_nChannelNo].dwError

62 Using the SYCON.net XML to SCL Converter 62/84 7 Using the SYCON.net XML to SCL Converter Main data which are processed by the PLC program are digital input and output data. Hilscher s hardware offers these data in two memory areas called "Process Data Input" and "Process Data Output" image. Input data are "normally" read from the hardware and written 1 by 1 to an input data block (DB_I_MAP) while output data are taken from the output data block (DB_Q_MAP) and written 1 by 1 to the hardware. Because of the different data representation and data alignment of TIA and the Hilscher hardware and also of the data representation delivered by the fieldbus systems, a 1:1 access to the I/O image could lead into serious conversion overhead in the PLC program. Data representation / alignment TIA Hilscher device data Fieldbus I/O data Data representation Big Endian Little Endian Little/Big Endian Data alignment Byte = Byte Data types > Byte = Word Byte Byte/Word A 1:1 image access always needs the additional definition of the data offsets and data types in the PLC program and these data are only available from the SYCON.net fieldbus configuration, which must be manually inserted in the PLC program. Address Table Example of a configured PROFIBUS module in SYCON.net: Length Address Data size of the module in the I/O image Offset of the module data in the I/O image

63 Using the SYCON.net XML to SCL Converter 63/84 Another point is symbolic addressing of input output data. SYCON.net offers the export of the process data information (PDI) into an XML file, while TIA offers the generation of data blocks by importing SCL code. The CIFX WinAC Driver offers a "SCOYN.net XML to SCL Converter" able to convert SYCOn.net PDI XML files into SCL files containing the layout of the input and output data blocks corresponding to the SYCON.net I/O data configuration. Major benefit by using the converter is the possibility of the CIFX WinAC Driver to do the data converting and the adaptation of the data alignment inside the driver, preventing the data conversion in the PLC program. Furthermore, this enables the PLC program to use symbolic names, defined by the SYCON.net configuration, to access the input and output data.

64 Using the SYCON.net XML to SCL Converter 64/ Create an PDI-XML from SYCON.net After creating the fieldbus configuration by SYCON.net, this configuration can be exported into an XML file. Figure 16: SYCON.net: Export XML

65 Using the SYCON.net XML to SCL Converter 65/ Symbolic signal names in the fieldbus configuration In the fieldbus configuration, SYCON.net generates unique device and signal names. These names are stored in the (PDI) XML export file and used when the SCL DB code is created. Figure 17: SYCON.net: Symbolic names Note: Depending to the fieldbus system and the version of SYCON.net it may be possible to change device names and signal names (see figure above). If this is not supported by SYCON.net only the pre-created symbols are usable. It is possible to change the created SCL file before a data block is generated.

66 Using the SYCON.net XML to SCL Converter 66/ Convert a XML to a SCL file The XML to SCL converter is installed with the CIFX WinAC driver. Setup the converter program - Field Input file: select the directory and XML file you have created by SYCON.net. - Field Output file: select the directory where the SCL file should be stored. - Select the format of the signal names in the SCL (default SignalName). Figure 18: SYCON.et XML to Siemens SCL Converter (1)

67 Using the SYCON.net XML to SCL Converter 67/84 Click Convert to run the converter. The state of the conversion is shown in the log entry box. Figure 19: SYCON.et XML to Siemens SCL Converter (2) The XML to SCL converter will generate 2 SCL files. One describes the input data block structure (1_xxxxxxx-IN-...). The second one describes the output data block (1_xxxxxx-OUT-...). Example of created files Figure 20: SYCON.et XML to Siemens SCL Converter Example files

68 Using the SYCON.net XML to SCL Converter 68/84 Example content of a generated SCL code for INPUT data: // // Block for HILSCHER CIFX INPUT (converted data) DATA_BLOCK "DB_CIFX_CIFX_DP_DPM_CIFX_DP_DPM 1 1 Profibus_IN" { S7_Optimized_Access := 'FALSE' } VERSION : 0.1 STRUCT Input_1 : BYTE; // Offset(XML/SCL): 0/0; XML Type: byte Input_2 : BYTE; // Offset(XML/SCL): 1/1; XML Type: byte dummy_0 : BYTE; // Filling bytes for DWORD alignment dummy_1 : BYTE; // Filling bytes for DWORD alignment SlaveConfig : ARRAY[0..15] of Byte; // Offset(XML/SCL): 0/4; XML Type: SlaveState : ARRAY[0..15] of Byte; // Offset(XML/SCL): 0/20; XML Type: SlaveDiag : ARRAY[0..15] of Byte; // Offset(XML/SCL): 0/36; XML Type: md5checksum : ARRAY[0..15] of Byte; END_STRUCT; BEGIN md5checksum[0] := 16#67; md5checksum[1] := 16#55; md5checksum[2] := 16#00; md5checksum[3] := 16#65; md5checksum[4] := 16#9D; md5checksum[5] := 16#79; md5checksum[6] := 16#1E; md5checksum[7] := 16#BB; md5checksum[8] := 16#AC; md5checksum[9] := 16#43; md5checksum[10] := 16#A0; md5checksum[11] := 16#52; md5checksum[12] := 16#71; md5checksum[13] := 16#ED; md5checksum[14] := 16#A6; md5checksum[15] := 16#E7; END_DATA_BLOCK // // Block for HILSCHER CIFX INPUT (converted data) DATA_BLOCK "DB_CIFX_CIFX_DP_DPM_CIFX_DP_DPM 1 1 Profibus_OUT" { S7_Optimized_Access := 'FALSE' } VERSION : 0.1 STRUCT Output_1 : BYTE; // Offset(XML/SCL): 0/0; XML Type: byte Output_2 : BYTE; // Offset(XML/SCL): 1/1; XML Type: byte md5checksum : ARRAY[0..15] of Byte; END_STRUCT; BEGIN md5checksum[0] := 16#67; md5checksum[1] := 16#55; md5checksum[2] := 16#00; md5checksum[3] := 16#65; md5checksum[4] := 16#9D; md5checksum[5] := 16#79; md5checksum[6] := 16#1E; md5checksum[7] := 16#BB; md5checksum[8] := 16#AC; md5checksum[9] := 16#43; md5checksum[10] := 16#A0; md5checksum[11] := 16#52; md5checksum[12] := 16#71; md5checksum[13] := 16#ED; md5checksum[14] := 16#A6; md5checksum[15] := 16#E7; END_DATA_BLOCK

69 Using the SYCON.net XML to SCL Converter 69/ Import SCL code into a TIA project In the TIA project open External source files and select Add new external file. Select the created SCL file. Right click to the file and select Generate blocks from source, this will create a data block from the SCL file.

70 Using the SYCON.net XML to SCL Converter 70/84 Example data block created by an SCL file Note: It is possible input and output data blocks containing additional information not configured in the SYCON.net fieldbus configuration (see red marked data). These data are diagnostic information automatically added by SYCON.net to the PDI XML file and necessary for the diagnostic handling. Setting the input and output data block numbers into DB_CIFXConfig To configure a board with the created data block number, create the block number from the block name and insert the number into the corresponding board/channel structure in the DB_CIFXConfig data block. In the example program, this is done in the OB100/OB102 before the CIFX WinAC driver is initialized. //====================================================================== // OB100: CIFX dirver initialization and startup handling // Step 1: Setup the DBs to store the INPUT and OUTPUT I/O data // for each Board[n]\Channel[n] later used in the application // Step 2: Call the driver initialization function //====================================================================== // Step 1: Create the DB numbers out of symbolic DBs and an created to hold // the I/O images for INPUT and OUTPUT data "DB_CIFXConfig".Param.atBoard[0].atChannel[0].wDB_I_MAP := "FC_GetDBNumber"("DB_I_MAP_Board0_CH0"); "DB_CIFXConfig".Param.atBoard[0].atChannel[0].wDB_Q_MAP := "FC_GetDBNumber"("DB_Q_MAP_Board0_CH0"); // call the driver intialization "idb_cifxdriverinit"(o_berror=>"bcifxerror_init", o_wstatus=>"wcifxstatus_init");