0% found this document useful (0 votes)

248 views

Cifx API PR 05 EN

cifX API PR 05 EN

Uploaded by

julio perez

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

248 views

Cifx API PR 05 EN

cifX API PR 05 EN

Uploaded by

julio perez

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 118

Programming Reference Guide

CIFX API

Hilscher Gesellschaft für Systemautomation mbH

Table of contents
1 Introduction............................................................................................................................................. 4
1.1 About this document ...................................................................................................................... 4
1.2 List of revisions............................................................................................................................... 4
1.3 Terms, abbreviations and definitions ............................................................................................. 5
1.4 References to documents .............................................................................................................. 5
2 Application note ..................................................................................................................................... 6
2.1 Component overview for host applications .................................................................................... 6
2.2 Component overview for netX applications .................................................................................... 7
2.3 Availability of API functions ............................................................................................................ 8
3 API basics ............................................................................................................................................. 11
3.1 DPM layout, devices and channels .............................................................................................. 12
3.2 Basic fieldbus data handling ........................................................................................................ 13
3.3 Fieldbus-specific information and functions ................................................................................. 13
4 CIFX API (Application Programming Interface) ................................................................................. 14
4.1 API header files ............................................................................................................................ 14
4.2 Driver functions ............................................................................................................................ 14
4.3 System Device functions .............................................................................................................. 15
4.4 Communication Channel functions .............................................................................................. 16
4.5 Structure definitions ..................................................................................................................... 18
4.5.1 Driver information ............................................................................................................................ 18
4.5.2 Board information ............................................................................................................................ 18
4.5.3 System channel information ............................................................................................................ 19
4.5.4 Communication channel information ............................................................................................... 21
4.6 Driver related functions ................................................................................................................ 22
4.6.1 xDriverOpen .................................................................................................................................... 22
4.6.2 xDriverClose .................................................................................................................................... 23
4.6.3 xDriverGetInformation ..................................................................................................................... 24
4.6.4 xDriverGetErrorDescription ............................................................................................................. 25
4.6.5 xDriverEnumBoards ........................................................................................................................ 26
4.6.6 xDriverEnumChannels..................................................................................................................... 27
4.6.7 xDriverRestartDevice....................................................................................................................... 28
4.6.8 xDriverMemoryPointer ..................................................................................................................... 29
4.7 System device specific functions ................................................................................................. 31
4.7.1 xSysdeviceOpen ............................................................................................................................. 31
4.7.2 xSysdeviceClose ............................................................................................................................. 32
4.7.3 xSysdeviceInfo ................................................................................................................................ 33
4.7.4 xSysdeviceReset ............................................................................................................................. 34
4.7.5 xSysdeviceBootstart ........................................................................................................................ 35
4.7.6 xSysdeviceGetMBXState ................................................................................................................ 36
4.7.7 xSysdevicePutPacket ...................................................................................................................... 37
4.7.8 xSysdeviceGetPacket...................................................................................................................... 38
4.7.9 xSysdeviceDownload ...................................................................................................................... 39
4.7.10 xSysdeviceFindFirstFile................................................................................................................... 41
4.7.11 xSysdeviceFindNextFile .................................................................................................................. 42
4.7.12 xSysdeviceUpload ........................................................................................................................... 43
4.7.13 xSysdeviceExtendedMemory .......................................................................................................... 44
4.8 Channel-specific functions ........................................................................................................... 48
4.8.1 xChannelOpen ................................................................................................................................ 48
4.8.2 xChannelClose ................................................................................................................................ 49
4.8.3 xChannelDownload ......................................................................................................................... 50
4.8.4 xChannelFindFirstFile...................................................................................................................... 51
4.8.5 xChannelFindNextFile ..................................................................................................................... 52
4.8.6 xChannelUpload .............................................................................................................................. 53
4.8.7 xChannelGetMBXState ................................................................................................................... 54
4.8.8 xChannelPutPacket ......................................................................................................................... 55
4.8.9 xChannelGetPacket......................................................................................................................... 56
4.8.10 xChannelGetSendPacket ................................................................................................................ 57
4.8.11 xChannelReset ................................................................................................................................ 58
4.8.12 xChannelInfo ................................................................................................................................... 59
4.8.13 xChannelIOInfo ............................................................................................................................... 60

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
Introduction 3/118
4.8.14 xChannelWatchdog ......................................................................................................................... 61
4.8.15 xChannelConfigLock ....................................................................................................................... 62
4.8.16 xChannelHostState.......................................................................................................................... 63
4.8.17 xChannelBusState ........................................................................................................................... 64
4.8.18 xChannelControlBlock ..................................................................................................................... 65
4.8.19 xChannelCommonStatusBlock ........................................................................................................ 66
4.8.20 xChannelExtendedStatusBlock ....................................................................................................... 67
4.8.21 xChannelUserBlock ......................................................................................................................... 68
4.8.22 xChannelIORead ............................................................................................................................. 69
4.8.23 xChannelIOWrite ............................................................................................................................. 70
4.8.24 xChannelIOReadSendData ............................................................................................................. 71
4.8.25 PLC I/O image functions.................................................................................................................. 72
4.8.26 DMA functions ................................................................................................................................. 81
4.8.27 Notification functions ....................................................................................................................... 82
4.8.28 Fieldbus synchronization handling .................................................................................................. 91
5 Simple C-application example ............................................................................................................ 94
5.1 The Main() function ...................................................................................................................... 94
5.2 System device example ............................................................................................................... 95
5.3 Communication channel example ................................................................................................ 97
5.4 Board and channel enumeration ................................................................................................ 101
6 General protocol stack handling ...................................................................................................... 102
6.1 Overview .................................................................................................................................... 102
6.2 Protocol stack configuration ....................................................................................................... 105
6.3 Cyclic data exchange ................................................................................................................. 107
7 Error codes ......................................................................................................................................... 108
8 Appendix ............................................................................................................................................. 113
8.1 List of tables ............................................................................................................................... 113
8.2 List of figures .............................................................................................................................. 113
8.3 Legal notes ................................................................................................................................. 114
8.4 Contacts ..................................................................................................................................... 118

CIFX API | Programming Reference Guide

1 Introduction
1.1 About this document
This manual describes the CIFX/COMX/netX Application Programming Interface (CIFX API) and
the containing functions, offered for all Hilscher standard devices based on netX controller
hardware.
Aim of the API is to provide applications a target and fieldbus independent programming interface
to netX based hardware running a standard Hilscher fieldbus protocol or firmware which meet the
Hilscher netX dual port memory (netX DPM) definitions, described in the 'netX Dual Port Memory
Interface' manual (see reference [1]).
The API is designed to give the user easy access to all of the communication board functionalities.
In addition, Hilscher also offers a free of charge cifX Toolkit (C-source code based) which allows to
write own drivers based on the Hilscher netX DPM definitions including the CIFX API functions (the
toolkit is described in a separate cifX/netX Toolkit manual, see reference [2]).

1.2 List of revisions

Rev Date Name Chapter Revision
1 2012-12-11 RMA all Extracted from the CIFX Device Driver - Windows DRV 21 EN.pdf
2 2013-02-18 RMA 4.8.28 Section Fieldbus synchronization handling added.
7 Tables in chapter Error codes revised.
3 2014-10-08 RMA Note for xSysdeviceDownload and xChannelDownload inserted.
SSP 4.8.17 Description of xChannelBusState extended.
RMA 4.8.27 Description for Notification functions added.
4 2015-07-25 RMA Some writings fixed.
4.5.3 SYSTEM_CHANNEL_SYSTEM_STATUS_BLOCK structure updated.
4.8.22 / note of the default xChannelIORead()/xChannelIOWrite handling added
4.8.23
4.8.25 Description of the PLC I/O image functions updated.
5 2018-08-28 RMA 2.3 Section Availability of API functions: List of API functions updated.
4.7.9 Section xSysdeviceDownload: Table of available download modes added.
4.8.22 Section xChannelIORead: Note added.
4.8.23 Section xChannelIOWrite: Note added.
Table 1: List of revisions

CIFX API | Programming Reference Guide

1.3 Terms, abbreviations and definitions

Term Description
netX Hilscher highly integrated network controller
rcX Hilscher Real Time Communication System for netX
cifX Communication Interface based on netX
comX Communication Module based on netX
API Application Programming Interface
DPM Dual-Port Memory
Physical memory area, connected to a host processor.
Standard interface to Hilscher communication boards like CIFX/COMX or netX evaluation boards
(Attention: DPM may also be used as a shortcut for PROFIBUS-DP Master field bus protocol).
SHM Shared Memory
System memory area shared between different processes inside a software application
SPI Serial Peripheral Interface
RPC Remote Procedure Calls
DPM Manual Description of the standard Hilscher DPM layout and functionality
netX Transport Diagnostics and remote access functions to netX based remote devices via serial interfaces
CIFX Toolkit C source-code based implementation of the standard Hilscher DPM access functions
SDO Service Data Object
PDO Process Data Object
Table 2: Terms, abbreviations and definitions

1.4 References to documents

This document refers to the following documents:
[1] Hilscher Gesellschaft für Systemautomation mbH: DPM Manual,
netX Dual-Port Memory Interface DPM Manual, Revision 14, English, 2018.
Description of the standard Hilscher DPM layout and functionality
[2] Hilscher Gesellschaft für Systemautomation mbH: Toolkit Manual,
cifX/netX Toolkit - DPM, Revision 10, English, 2018.
C source-code based implementation of the standard Hilscher DPM access functions
[3] Hilscher Gesellschaft für Systemautomation mbH: Program Reference Guide,
netX Diagnostic and Remote Access, Fundamentals Revision 2, English, 2011.

Hilscher Gesellschaft für Systemautomation mbH: Program Reference Guide,

netX Diagnostic and Remote Access, Host Device Revision 3, English, 2013.

Hilscher Gesellschaft für Systemautomation mbH: Program Reference Guide,

netX Diagnostic and Remote Access, Target Device Revision 3, English, 2010

Table 3: References to documents

CIFX API | Programming Reference Guide

2 Application note
2.1 Component overview for host applications
Hilscher offers the CIFX API on different platforms and as different applications (DLL / library or C
source code). Usually the API comes with an operating system driver or with the CIFX Toolkit.
The use of the API also implies the physical hardware connection to the netX hardware. While a
device driver uses memory functions to access the DPM, the toolkit also allows the implementation
of alternative hardware access functions like DPM via SPI or custom access functions like DPM via
a custom USB protocol.
The netX Transport DLL is a special implementation of the CIFX API, including hardware access
via serial interfaces (e. g. USB/serial/Ethernet connections). This component is able to convert
CIFX API function calls either into appropriate packet based commands (rcX packets, described in
reference [1]) or into a dedicated binary format which enables the execution of the API functions on
a remote system (similar to RPC - remote procedure calls).

CIFX API Components

CIFX - API

Customer CIFX Driver netX Transport

(e.g. Windows / Linux) (e.g. Windows / Linux)

CIFX / netX CIFX / netX

Driver Interface Driver Interface Remote rcX
(optional) CIFX API Packet
(RPC)

CIFX / netX
Device Driver
CIFX Toolkit

CIFX Toolkit

Hardware Interface
Physical DPM Physical USB / serial / Ethernet
via SPI DPM access

Figure 1: CIFX API components

 Physical DPM interface

The DPM hardware interface, with direct access to the memory, offers the entire defined API
functions.
 Physical DPM via SPI
The netX hardware offers a SPI interface accepting encoded memory access functions
(memory read / write functions) to the DPM. These SPI commands are decoded by the
hardware / firmware and executed on the internal DPM of the netX device.
 USB / serial / Ethernet access
Another possibility to access a netX device is the use of serial interfaces
(USB/serial/Ethernet). In this case, CIFX API function calls are converted (described in the
netX Diagnostic and Remote Access manual, see reference [3]), transferred and processed
by the remote netX device.
This type of communication does not offer all of the CIFX API functions. Especially functions
related to mapped memory areas like xChannelPLC...() functions.

2.2 Component overview for netX applications

Hilscher also provides the application development directly on the netX communication controller.
The CIFX API is also available in this environment.

netX Communication Controller

User Application

CIFX - API

Fieldbus Protocol Stack

Figure 2: Component Overview for netX applications

CIFX API | Programming Reference Guide

2.3 Availability of API functions

Following table lists the available API functions regarding to the used environment and the physical
hardware connection.

Function Short Description DPM DPM USB / serial / netX

via Ethernet
SPI
RPC | Packet
xDriverOpen Opens the driver X X X|X X
xDriverClose Closes the driver X X X|X X
xDriverGetInformation Retrieves driver information X X X|X X
xDriverGetErrorDescription Retrieves an error code description X X X|X X
xDriverEnumBoards Enumerate available boards/devices X X X|X X
xDriverEnumChannels Enumerate available channels on a X X X|X X
specific board
xDriverRestartDevice Restart a device X X O|O O
xDriverMemoryPointer Get/Release a pointer to the dual port X O O|O X
memory.
Only be used for debugging. purpose
Table 4: List of API functions – Driver functions

Function Short Description DPM DPM USB / serial / netX

via Ethernet
SPI
RPC | Packet
xSysdeviceOpen Opens a connection a system device X X X|X X
xSysdeviceClose Closes a connection to a system device X X X|X X
xSysdeviceInfo Get System device information X X X|X X
xSysdeviceReset Perform a device reset X X X|X X(3)
xSysdeviceBootstart Perform a device boot start X X O|O O
xSysdeviceGetMBXState Retrieves the system mailbox state X X X|X X
xSysdeviceGetPacket Read a pending packet X X X|X X
xSysdevicePutPacket Send a packet X X X|X X
xSysdeviceDownload Downloads a file/configuration/firmware X X X|X X
xSysdeviceFindFirstFile Find the first file in the given directory X X X|X X
xSysdeviceFindNextFile Find the next file entry in the given X X X|X X
directory
xSysdeviceUpload Uploads a file/configuration/firmware X X X|X X
xSysdeviceExtendedMemory Get a pointer to the extended memory X(1) O O|O O
area
Table 5: List of API functions – System Device functions

CIFX API | Programming Reference Guide

Function Short Description DPM DPM USB / serial / netX

via Ethernet
SPI RPC | Packet
xChannelOpen Opens a communication channel X X X|X X
xChannelClose Closes a communication channel X X X|X X
Asynchronous services (Packets) X
xChannelGetMBXState Retrieve the channels mailbox state X X X|X X
xChannelGetPacket Read packet from the channel mailbox X X X|X X
xChannelPutPacket Send a packet to the channel mailbox X X X|X X
xChannelGetSendPacket Read back the packet sent X X X|O X
Device Administrational/Informational functions X
xChannelDownload Download a file/configuration to the X X X|X X
channel
xChannelReset Reset the channel X X X|X X(4)
xChannelInfo Retrieve channel specific information X X X|O X
xChannelWatchdog Activate/Deactivate/Trigger Watchdog X X X|O X
xChannelHostState Set the Application state flag X X X|O X
(signal application is running or not)
xChannelBusState Set the bus state flag X X X|X X
(start or stop fieldbus communication)
xChannelControlBlock Access the Channels control block X X X|X X
xChannelCommonStatusBlock Access to the common status block X X X|X X
xChannelExtendedStatusBlock Access to the extended status block X X X|X X
xChannelUserBlock Access user block (not implemented X X X|X X
yet!)
Cyclic Data services (I/O's)
xChannelIORead Instructs the device to place the latest X X X|O X
data into the DPM and passes them to
the user
xChannelIOWrite Copies the data to the DPM and waits X X X|O X
for the firmware to retrieve them
xChannelIOReadSendData Reads back the last send data X X X|O X
Cyclic Data services (I/O's, PLC optimized)
xChannelPLCMemoryPtr Get a pointer to the IO Block X O(2) O|O X
xChannelPLCActivateRead Instruct the firmware to place the latest X O(2) O|O X
input data into the dual port (no wait for
completion)
xChannelPLCActivateWrite Instruct the firmware to retrieve the latest X O(2) O|O X
output data from the dual port (no wait
for completion)
xChannelPLCIsReadReady Checks if the last Read Activation has X O(2) O|O X
finished
xChannelPLCIsWriteReady Checks if the last Write Activation has X O(2) O|O X
finished

CIFX API | Programming Reference Guide

Function Short Description DPM DPM USB / serial / netX

via Ethernet
SPI RPC | Packet
DMA services
xChannelDMAState Activate/Deactivate DMA mode X(1) O O|O O
Bus synchronous operation
xChannelSyncState Wait for a synchronization event or X X(5) O|O O
trigger/acknowledge a sync event
Notification services (only available in Interrupt mode)
xChannelRegisterNotification Register a notification callback X X(5) O|O O
xChannelUnregisterNotification Un-register a notification callback X X(5) O|O O
Table 6: List of API functions – Communication Channel functions

Notes:

(1) PCI / PCIe hardware only

(2) Special implementation necessary
(3) A system reset will reset the whole device. Boot start is not implemented.
(4) A system reset will reset the whole device
(5) Notifications only available in interrupt mode

CIFX API | Programming Reference Guide

3 API basics
As described before, the CIFX API is the common, fieldbus protocol independent, function
interface to Hilscher CIFX/COMX and netX based devices.
It is based on the Hilscher netX DPM (dual-port memory) definition and abstracts the access to the
netX based hardware and the Hilscher netX protocol firmware running on the netX.
The API offers a set of functions grouped into 'Driver' related, 'System Device' related and
'Communication Channel' related functions.
Each of the group covers device specific functions by providing a set of API functions necessary
for the specific handling.

Functional Groups in the CIFX-API:

 Driver related functions
Administration of multiple devices in a standardized way
 System Device related functions
General device functions (e.g. system reset, download, device information)
 Communication Channel related functions
Fieldbus protocol stack handling

CIFX API | Programming Reference Guide

3.1 DPM layout, devices and channels

The DPM layout divides the interface to a netX device into several areas (channels) where each
channel has its own structure, predefined information and functionality and can be handled
independently from other channels.

A standard netX firmware offers up to 8 channels with three different channel definitions.

General DPM Layout:

System Handshake
4 x Communication Channel 2 x User Channel
Channel Channel

Dual-Port Memory

0 65535

Channel Definition:

 System Channel (also named System Device)

The main channel is the 'System Channel' also named 'System Device'. It is always available
and used for administration functions belonging to the whole device, like hardware reset,
firmware download etc.
 Communication Channels
Communication channels representing a fieldbus connection (a fieldbus protocol stack) with
its information and functionalities.
Up to four communication channels are possible.
 User Channels
User channels are the third type of channels and designed for user applications, running on
the netX chip in parallel to fieldbus protocol stack (two user channels are possible).

The Handshake Channel is necessary for special device functionalities like interrupt handling and
DPM access synchronization and therefore it has no user API functions offering access to this
channel.

CIFX API function names correspond to the function groups and channel definitions.
 xSysdevice..........() Functions and functionalities corresponding to the system channel
functionalities
 xChannel..............() Functions and functionalities corresponding communication channel
and its needs
 xDriver…..............() Functions to handle multiple devices in a common way

CIFX API | Programming Reference Guide

3.2 Basic fieldbus data handling

NetX devices are providing two basic mechanisms to transfer user data between a fieldbus
protocol stack and user applications.
First one is the cyclic process data transfer mechanism (Transfer of the Process Data Image) and
the second one is the asynchronous data transfer mechanism (Packet Oriented Data Transfer).

Other information like configuration, diagnostic and device specific administration functions are
also based on the asynchronous data transfer mechanism.

 Asynchronous Data Transfer (Packet Oriented Data Transfer)

Data are transferred by using a data structure named rcX packet. Packet transfer between a
host system and the cifX hardware takes place via a, so called, mailbox system. This method
is used to transfer of SDO, administration, configuration and diagnostic data.

 Cyclic Process Data Transfer (Process Data Image Transfer)

Data are located in a process data image. This method is used for I/O based protocols (PDO
transfer).
Input and output data are located in separate memory areas which can be handled
independently.

Note: A complete description of the fieldbus data handling can be found in the netX Dual Port
Memory Interface manual

3.3 Fieldbus-specific information and functions

Beside the general device data in the DPM each fieldbus protocol stack comes with its own
specific data and functions. This specific information can be found in the corresponding protocol
API manuals.

Note: Fieldbus specific information and functionalities can be found in the corresponding
protocol API manuals (e. g. PROFIBUS DP Master Protocol API 15 EN.pdf).

CIFX API | Programming Reference Guide

4 CIFX API (Application Programming Interface)

The API offers functions grouped into 'Driver', 'System Channel' and 'Communication Channel'
related functions.

4.1 API header files

The API comes with a single C header file.
API definition file: cifXUser.h
Error definitions: cifXError.h

4.2 Driver functions

The driver related functions are used to handle a driver and offers functions to identify the
connected hardware.

Function Description
xDriverOpen Opens the driver, allowing access to every driver function
xDriverClose Closes an open connection to the driver
xDriverGetInformation Retrieves driver information (e.g. Version)
xDriverGetErrorDescription Retrieves an English description of a cifX driver error code
xDriverEnumBoards Enumerate through all boards/devices the driver is managing
xDriverEnumChannels Enumerate through all channels located on a specific board
xDriverRestartDevice Restart a device
xDriverMemoryPointer Get/Release a pointer to the dual port memory.
This function should only be used for debugging.
purpose
Table 7: Driver functions

CIFX API | Programming Reference Guide

4.3 System Device functions

Each communication board owns a System Device allowing generic access to the device. This
'System Device' only offers a small mailbox and system global status information and should not
be used to communicate with a protocol stack directly.

Function Description
xSysdeviceOpen Opens a connection to a boards system device
xSysdeviceClose Closes a connection to a system device
xSysdeviceInfo Get System device specific information (e.g. mailbox size)
xSysdeviceReset Perform a device reset
xSysdeviceBootstart Perform a device boot start.
This will activate the 2nd Stage bootloader. An available firmware will not be started.
Note: Only possible on FLASH based devices.
xSysdeviceGetMBXState Retrieves the system mailbox state
xSysdeviceGetPacket Retrieves a pending packet from the system mailbox
xSysdevicePutPacket Send a packet to the system mailbox
xSysdeviceDownload Downloads a file/configuration/firmware to the device
xSysdeviceFindFirstFile Find the first file entry in the given directory
xSysdeviceFindNextFile Find the next file entry in the given directory
xSysdeviceUpload Uploads a file/configuration/firmware from the device
xSysdeviceExtendedMemory Get a pointer to an available extended memory area
Table 8: System Device functions

CIFX API | Programming Reference Guide

4.4 Communication Channel functions

Each protocol stack is represented as a Communication Channel.
Communication channels owning a set of functions, allowing every possible interaction with the
protocol stack.
The CIFX API functions are protocol stack independent and used for all available Hilscher netX
based protocol stacks. Only the data content is protocol specific and must be interpreted by the
user application.

Communication Channel functions:

Function Description
xChannelOpen Opens a connection to a communication channel
xChannelClose Closes a connection
Asynchronous services (Packets)
xChannelGetMBXState Retrieve the channels mailbox state
xChannelGetPacket Retrieve a pending packet from the channel mailbox
xChannelPutPacket Send a packet to the channel mailbox
xChannelGetSendPacket Read back the last sent packet
Device Administrational/Informational functions
xChannelDownload Download a file/configuration to the channel
xChannelReset Reset the channel
xChannelInfo Retrieve channel specific information
xChannelWatchdog Activate/Deactivate/Trigger the channel Watchdog
xChannelHostState Set the application state flag in the application COS flags, to
signal the hardware if an application is running or not
xChannelBusState Set the bus state flag in the application COS state flags, to
start or stop fieldbus communication.
xChannelControlBlock Access the channel control block
xChannelCommonStatusBlock Access to the common status block
xChannelExtendedStatusBlock Access to the extended status block
xChannelUserBlock Access user block (not implemented yet!)
Cyclic Data services (I/O's)
xChannelIORead Instructs the device to place the latest data into the DPM and
passes them to the user
xChannelIOWrite Copies the data to the DPM and waits for the firmware to
retrieve them
xChannelIOReadSendData Reads back the last send data
Cyclic Data services (I/O's, PLC optimized)
xChannelPLCMemoryPtr Get a pointer to the I/O memory block
xChannelPLCActivateRead Instruct the firmware to place the latest input data into the I/O
memory block (no wait for completion)
xChannelPLCActivateWrite Instruct the firmware to retrieve the latest output data from
the I/O memory block (no wait for completion)
xChannelPLCIsReadReady Checks if the last read activation has finished
xChannelPLCIsWriteReady Checks if the last write activation has finished

CIFX API | Programming Reference Guide

Function Description
DMA services
xChannelDMAState Activate/Deactivate DMA mode
Bus synchronous operation
xChannelSyncState Wait for synchronization events or trigger / acknowledge a
sync event
Notification services (only available in Interrupt mode)
xChannelRegisterNotification Register a notification callback
xChannelUnregisterNotification Un-register a notification callback
Table 9: Communication Channel functions

CIFX API | Programming Reference Guide

4.5 Structure definitions

Note: All structures are byte packed, for easy portability and data exchange via the DPM.

4.5.1 Driver information

When querying the driver information the following structure is expected in the function call.
DRIVER_INFORMATION
Element Type Description
abDriverVersion uint8_t[32] Human readable driver name and version
ulBoardCnt uint32_t Number of handled boards
Table 10: Driver information structure

4.5.2 Board information

The board information structure is used, when enumerating boards.
BOARD_INFORMATION
Element Type Description
lBoardErrror uint32_t Global board error (currently not used always 0)
abBoardName uint8_t[16] This is the name of the board which can be used for
opening a channel or the system device on it.
abBoardAlias uint8_t[16] This is an alternate, user-definable name for the device
ulBoardID uint32_t Unique driver created board identifier
ulSystemError uint32_t Boot-up/System error, when trying to handle device
ulPhysicalAddress uint32_t Physical address of the device's DPM
ulIrqNumber uint32_t Interrupt number assigned to the device
bIrqEnabled uint32_t Defines if the interrupt is used by the driver, or if the
driver works in polling mode for this device
ulChannelCnt uint32_t Number of available channels
ulDpmTotalSize uint32_t Total size of the dual port in bytes
tSystemInfo SYSTEM_CHANNEL_SYSTEM_INFO_BLOCK (see below)
Table 11: Board information structure

CIFX API | Programming Reference Guide

4.5.3 System channel information

The following structures are returned on calls to xSysdeviceInfo() depending on the passed
command parameter:

Command: CIFX_INFO_CMD_SYSTEM_INFORMATION

SYSTEM_CHANNEL_SYSTEM_INFORMATION
Element Type Description
ulSystemError uint32_t Boot-up/System error, when trying to handle device
ulDpmTotalSize uint32_t Total size of the dual port in bytes
ulMBXSize uint32_t Size of the system mailbox in bytes
ulDeviceNumber uint32_t Device number (as found on the matrix label)
ulSerialNumber uint32_t Serial number (as found on the matrix label)
ulOpenCnt uint32_t Number of times this device is open
Table 12: System channel information

Command: CIFX_INFO_CMD_SYSTEM_INFO_BLOCK

SYSTEM_CHANNEL_SYSTEM_INFO_BLOCK
Element Type Description
abCookie uint8_t[4] System channel identifier MUST be "netX"
ulDpmTotalSize uint32_t Total size of the dual port in bytes
ulDeviceNumber uint32_t Device number (as found on the matrix label)
ulSerialNumber uint32_t Serial number (as found on the matrix label)
ausHwOptions uint16_t[4] Array of hardware options for all four possible ports of the netX
usManufacturer uint16_t Manufacturer ID
usProductionDate uint16_t Production date code
ulLicenseFlags1 uint32_t Hilscher dedicated license flags (e.g. fieldbus license)
ulLicenseFlags2 uint32_t Hilscher dedicated license flags (e.g. additional information)
usNetxLicenseID uint16_t Special netX user license information
usNetxLicenseFlags uint16_t Dedicated netX user license information
usDeviceClass uint16_t Hardware device class (e.g. CIFX / COMX etz.)
bHwRevision uint8_t Hardware revision
bHwCompatibility uint8_t Hardware compatibility list
bDevIdNumber uint8_t Device identification number (rotary switch)
bReserved uint8_t unused/reserved
usReserved uint16_t unused/reserved
Table 13: System channel info block

CIFX API | Programming Reference Guide

Command: CIFX_INFO_CMD_SYSTEM_CHANNEL_BLOCK

SYSTEM_CHANNEL_CHANNEL_INFO_BLOCK
Element Type Description
abInfoBlock uint8_t[8][16] Channel information in the system channel
Table 14: System Channel - Channel Info Block

Area definitions in cifXUser.h:

CIFX_MAX_NUMBER_OF_CHANNEL_DEFINITION =8
CIFX_SYSTEM_CHANNEL_DEFAULT_INFO_BLOCK_SIZE = 16

Note: To evaluate the content of the abInfoBlock array, refer to the netX DPM Interface
Manual and the rcX_User.h, structure NETX_CHANNEL_INFO_BLOCK.

Command: CIFX_INFO_CMD_SYSTEM_CONTROL_BLOCK

SYSTEM_CHANNEL_SYSTEM_CONTROL_BLOCK
Element Type Description
ulSystemCommandCOS uint32_t System channel host COS flags
ulReserved uint32_t unused/reserved
Table 15: System channel control block

Command: CIFX_INFO_CMD_SYSTEM_STATUS_BLOCK

SYSTEM_CHANNEL_SYSTEM_STATUS_BLOCK
Element Type Description
ulSystemCOS uint32_t System channel device COS flags
ulSystemStatus uint32_t Actual system state
ulSystemError uint32_t Actual system error
ulBootError uint32_t Error code from the second stage bootloader (only valid if
Cookie="BOOT")
ulTimeSinceStart uint32_t Time since system start in seconds
usCpuLoad uint16_t CPU load in 0,01% units (10000 => 100%)
usReserved uint16_t Reserved for later use
ulHWFeatures Uint32_t Information about hardware features (e.g. MRAM / RTC)
abReserved uint8_t[36] unused/reserved
Table 16: System channel status block

CIFX API | Programming Reference Guide

4.5.4 Communication channel information

The following structure is returned on calls to xChannelInfo() or when enumerating channels on a
Board using xDriverEnumChannels():

CHANNEL_INFORMATION
Element Type Description
abBoardName uint8_t[16] This is the name of the board which can be used for opening a channel or
the system device on it.
abBoardAlias uint8_t[16] This is an alternate, user-definable name for the device
ulDeviceNumber uint32_t Device number (as found on the matrix label)
ulSerialNumber uint32_t Serial number (as found on the matrix label)
usFWMajor uint16_t Major version number of firmware
usFWMinor uint16_t Minor version number of firmware
usFWBuild uint16_t Build number of firmware
usFWRevision uint16_t Revision version number of firmware
bFWNameLength uint8_t Length of firmware name
abFWName uint8_t[63] Firmware name
usFWYear uint16_t Build year of firmware
bFWMonth uint8_t Build month of firmware (1..12)
bFWDay uint8_t Build day of firmware (1..31)
ulChannelError uint32_t Communication channel error from the "Common Status Block"
ulOpenCnt uint32_t Number of calls to xChannelOpen for this channel
ulPutPacketCnt uint32_t Number of successful transmitted packets
ulGetPacketCnt uint32_t Number of successfully received packets
ulMailboxSize uint32_t Mailbox size in Bytes
ulIOInAreaCnt uint32_t Number of I/O Input areas
ulIOOutAreaCnt uint32_t Number of I/O output areas
ulHskSize uint32_t RCX_HANDSHAKE_SIZE_8BIT (0x01) or
RCX_HANDSHAKE_SIZE_16BIT (0x02)
ulNetxFlags uint32_t Actual netX communication flags (usNetxCommFlag)
ulHostFlags uint32_t Actual host communication flags (usHostCommFlags)
ulHostCOSFlags uint32_t Actual applicaton COS flags (ulApplicationCOS of Control Block)
ulDeviceCOSFlags uint32_t Actual communication COS flags (ulCommunicationCOS of Common
Status Block)
Table 17: Channel information structure

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

Example:
DRIVER_INFORMATION tDriverInfo = {0};
int32_t lRet = xDriverGetInformation(NULL, sizeof(tDriverInfo), &tDriverInfo);
if( lRet == CIFX_NO_ERROR)
{
}

CIFX API | Programming Reference Guide

4.6.4 xDriverGetErrorDescription
Look up function for driver errors. The function returns a human-readable error description (English
only).

Function call:
int32_t xDriverGetErrorDescription( int32_t lError,
char* szBuffer,
uint32_t ulBufferLen)

Arguments:

Argument Data type Description

lError int32_t Error value returned by any driver function
szBuffer String Pointer to a ASCII string buffer, to place returned text in
ulBufferLen uint32_t length of the string buffer for returned data

Return values:

CIFX_NO_ERROR if the function succeeds.

Example:
// Read driver error description
char szError[1024] ={0};
xDriverGetErrorDescription( lError, szError, sizeof(szError));

CIFX API | Programming Reference Guide

4.6.5 xDriverEnumBoards
Enumerate all currently handled boards/cards of the driver.

Function call:
int32_t xDriverEnumBoards( CIFXHANDLE hDriver,
uint32_t ulBoard,
uint32_t ulSize
void* pvBoardInfo)

Arguments:

Argument Data type Description

hDriver CIFXHANDLE Handle to the driver (returned by xDriverOpen)
ulBoard uint32_t Board number to return info for.
This must be incremented from zero until an error is
returned to query all boards
ulSize uint32_t length of the Structure passed in pvBoardInfo
pvBoardInfo void* Pointer to returned BOARD_INFORMATION structure

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

Example:
int32_t lBoardRet;
do {
BOARD_INFORMATION tBoardInfo = {0};
lBoardRet = xDriverEnumBoards(NULL, ulBoardIdx++, sizeof(tBoardInfo), &tBoardInfo);

if(lBoardRet == CIFX_NO_ERROR)
{
}
} while(lBoardRet == CIFX_NO_ERROR);

CIFX API | Programming Reference Guide

4.6.6 xDriverEnumChannels
Enumerate all available channels on a board/card.

Function call:
int32_t xDriverEnumChannels( CIFXHANDLE hDriver,
uint32_t ulBoard,
uint32_t ulChannel
uint32_t ulSize
void* pvChannelInfo)

Arguments:

Argument Data type Description

hDriver CIFXHANDLE Handle to the driver (returned by xDriverOpen)
ulBoard uint32_t Board number to return info for (constant during channel
enumeration).
ulChannel uint32_t Channel number to enumerate.
This must be incremented from zero until an error is
returned to query all channels
ulSize uint32_t length of the Structure passed in pvBoardInfo
pvChannelInfo void* Pointer to returned CHANNEL_INFORMATION structure

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

Example:
int32_t lChannelRet;
do {
CHANNEL_INFORMATION tChannelInfo = {0};
lChannelRet = xDriverEnumChannels(NULL, ulBoardIdx, ulChannelIdx++,
sizeof(tChannelInfo), &tChannelInfo);
if(lChannelRet == CIFX_NO_ERROR)
{

}
} while(lChannelRet == CIFX_NO_ERROR);

CIFX API | Programming Reference Guide

4.6.7 xDriverRestartDevice
The function can be used to restart a netX board. The driver processes the same functions like on
a power on reset (reset the hardware and download the bootloader, firmware and configuration
files etc.).
A restart is necessary on PCI based netX boards if a running firmware should be updated or
changed. Because on such boards the firmware is not stored in a FLASH file system and updating
the firmware while it is running in RAM is not possible.
On Windows based systems a restart can also be performed using the Windows Device Manager
to deactivate/activate the board.

Note: A restart is only performed if no application has an open handle to the board or one of
its communication channels.

Function call:
int32_t APIENTRY xDriverRestartDevice( CIFXHANDLE hDriver,
char* szBoardName,
void* pvData);

Arguments:

Argument Data type Description

hDriver CIFXHANDLE Handle to the driver (returned by xDriverOpen)
szBoardName String Identifier for the Board.
(e.g. "cifX<Board Number>")
pvData void* For further extensions can be NULL

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.6.8 xDriverMemoryPointer
Return a pointer to the dual port memory of a board/channel. This function should only be used for
debugging purposes, because the function only maps the card memory into the processes memory
area.

Function call:
int32_t xDriverMemoryPointer ( CIFXHANDLE hDriver,
uint32_t ulBoard,
uint32_t ulCmd,
void* pvMemoryInfo)

Arguments:

Argument Data type Description

hDriver CIFXHANDLE Handle to the driver (returned by xDriverOpen)
ulBoard uint32_t Board number to return pointer for.
ulCmd uint32_t Maps the dual port memory for direct access from an
application
1 = CIFX_MEM_PTR_OPEN
Map a user specific memory area
2 = CIFX_MEM_PTR_USR -> not supported
Release the dual port pointer (same memory structure
MUST be passed)
3 = CIFX_MEM_PTR_CLOSE
pvMemoryInfo void* Pointer to returned MEMORY_INFORMATION structure
Note: The Parameter ulChannel must be inserted!

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

Description of the MEMORY_INFORMATION Structure:

Value Data type Description

pvMemoryID void* Identifier of the memory area
ppvMemoryPtr void** Memory pointer
pulMemorySize uint32_t* Complete size of the mapped memory
ulChannel uint32_t* Requested channel number
pulChannelStartOffset uint32_t* Start offset of the requested channel
pulChannelSize uint32_t* Memory size of the requested channel

CIFX API | Programming Reference Guide

MEMORY_INFORMATION Structure:
/*****************************************************************************/
/*! Memory Information structure */
/*****************************************************************************/
typedef __CIFx_PACKED_PRE struct MEMORY_INFORMATIONtag
{
void* pvMemoryID; /*!< Identification of the memory area */
void** ppvMemoryPtr; /*!< Memory pointer */
uint32_t* pulMemorySize; /*!< Complete size of the mapped memory */
uint32_t ulChannel; /*!< Requested channel number */
uint32_t* pulChannelStartOffset;/*!< Start offset of the requested channel */
uint32_t* pulChannelSize; /*!< Memory size of the requested channel */
} __CIFx_PACKED_POST MEMORY_INFORMATION;

Example:
//=============================================================================
// Test memory pointer
//
//
//=============================================================================
void TestMemoryPointer( void)
{
unsigned char abBuffer[100] = {0};

// Open channel
uint32_t ulMemoryID = 0;
unsigned char* pabDPMMemory = NULL;
uint32_t ulMemorySize = 0;
uint32_t ulChannelStartOffset = 0;
uint32_t ulChannelSize = 0;
long lRet = CIFX_NO_ERROR;

MEMORY_INFORMATION tMemory = {0};

tMemory.pvMemoryID = &ulMemoryID; // Identification of the memory area
tMemory.ppvMemoryPtr = (void**)&pabDPMMemory; // Memory pointer
tMemory.pulMemorySize = &ulMemorySize; // Complete size of the mapped memory
tMemory.ulChannel = CIFX_NO_CHANNEL; // Requested channel number
tMemory.pulChannelStartOffset = &ulChannelStartOffset; // Start offset of the requested channel
tMemory.pulChannelSize = &ulChannelSize; // Memory size of the requested channel

// Open a DPM memory pointer

lRet = xDriverMemoryPointer( NULL, 0, CIFX_MEM_PTR_OPEN, &tMemory);
if(lRet != CIFX_NO_ERROR)
{
// Failed to get the memory mapping
ShowError( lRet);
} else
{
// We have a memory mapping 1
// Read 100 Bytes
memcpy( abBuffer, pabDPMMemory, sizeof(abBuffer));

memcpy( pabDPMMemory, abBuffer, sizeof(abBuffer));

}

// Return the DPM memory pointer

lRet = xDriverMemoryPointer( NULL, 0, CIFX_MEM_PTR_CLOSE, &tMemory);
ShowError( lRet);

CIFX API | Programming Reference Guide

4.7 System device specific functions

CIFX API | Programming Reference Guide

4.7.4 xSysdeviceReset
This function performs a firmware restart. Depending on the hardware and the implementation in
the firmware, this could be a software restart or a complete hardware reset.
Usually a software reset is performed.

Note: All channels will be reset.

Function call:
int32_t xSysdeviceReset( CIFXHANDLE hSysdevice
uint32_t ulTimeout)

Arguments:

Argument Data type Description

hSysdevice CIFXHANDLE Handle of the system device
ulTimeout uint32_t Timeout in ms to wait for reset to complete

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.7.5 xSysdeviceBootstart
Perform a boot start on the hardware. This is necessary if the 2nd Stage Bootloader should be
activated while an executable Firmware is available.

Note: All channels will be reset.

Note: This function is only available on so called FLASH based devices where the 2nd Stage
Bootloader is stored in the FLASH of the hardware.

Function call:
int32_t xSysdeviceBootstart( CIFXHANDLE hSysdevice
uint32_t ulTimeout)

Arguments:

Argument Data type Description

hSysdevice CIFXHANDLE Handle of the system device
ulTimeout uint32_t Timeout in ms to wait for reset to complete

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

CIFX API | Programming Reference Guide

4.7.9 xSysdeviceDownload
Downloading files to the board via the system device.
Due to the limited size of the mailbox these downloads are slower than using the channels mailbox
and should only be used if the channel's firmware is not running yet.
Download mode definitions can be found in the cifXUser.h file.
Available download modes:
Definition Mode Description
DOWNLOAD_MODE_FIRMWARE 1 Download a firmware file (file extension *.nxf)
DOWNLOAD_MODE_CONFIG 2 Download a fieldbus configuration file (file extension *.nxd)
DOWNLOAD_MODE_FILE 3 Download any file (file extension *.*)
DOWNLOAD_MODE_BOOTLOADER 4 Special download mode only supported by the 2nd Stage
bootloader to update itself in FLASH memory
DOWNLOAD_MODE_LICENSECODE 5 Download a license file (file extension *.nxl)
License files containing license flags which are stored on the
hardware.
DOWNLOAD_MODE_MODULE 6 Download a firmware module file (file extension *.nxo)
Firmware modules are dynamically loadable and require a so-
called base firmware

Note: xSysdeviceDownload() is not working if called with

DOWNLOAD_MODE_FIRMWARE on so called "RAM based devices" like on CIFX
PCI/PCIe cards or devices where the firmware is not stored into Flash.

It is not possible to use this function to download a firmware, because of the

circumstance that a firmware running in RAM is not able to update itself in RAM at the
same time.

Value Data type Description

pvMemoryID void* Identifier of the memory area
pvMemoryPtr void* Memory pointer to the extended memory area
ulMemorySize uint32_t Size of the extended memory area
ulMemoryType uint32_t Type of the extended memory area (e.g. MRAM)

CIFX API | Programming Reference Guide

ulMemoryInformation:
Extended Memory
31..16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
RAM Type:
0 = None
1 = MRAM 64*16 Bit (1 MBit/128 KB
Reserved

Access Type:
00 = No access
01 = external access (host)
10 = internal access
11 = external and internal access reserved
Unused set to 0

Note: ulMemoryType defines the type of the assembled/offered memory by the hardware.
The type is defined in the hardware security memory.

Available definitions (see rcX_User.h):

#define RCX_SYSTEM_EXTMEM_TYPE_MSK 0x0000000F
#define RCX_SYSTEM_EXTMEM_TYPE_NONE 0x00000000
#define RCX_SYSTEM_EXTMEM_TYPE_MRAM_128K 0x00000001

#define RCX_SYSTEM_EXTMEM_ACCESS_MSK 0x000000C0

#define RCX_SYSTEM_EXTMEM_ACCESS_NONE 0x00000000
#define RCX_SYSTEM_EXTMEM_ACCESS_EXTERNAL 0x00000040
#define RCX_SYSTEM_EXTMEM_ACCESS_INTERNAL 0x00000080
#define RCX_SYSTEM_EXTMEM_ACCESS_BOTH 0x000000C0

Note: RCX_SYSTEM_EXTMEM_ACCESS_EXTERNAL defines exclusive access by a host

application while RCX_SYSTEM_EXTMEM_ACCESS_INTERNAL defines exclusive
access by the firmware.
RCX_SYSTEM_EXTMEM_ACCESS_BOTH defines access for the firmware and host
application. In this case, first half of the memory is reserved for the host application,
starting at offset 0 and the second half of the memory is used by the firmware, starting
at offset memory size / 2.

CIFX API | Programming Reference Guide

CIFX_EXTENDED_MEMORY_INFORMATION structure:
/*****************************************************************************/
/*! Extended memory information structure */
/*****************************************************************************/
typedef __CIFx_PACKED_PRE struct CIFX_EXTENDED_MEMORY_INFORMATIONtag
{
void* pvMemoryID; /*!< Identification of the memory area */
void* pvMemoryPtr; /*!< Memory pointer */
uint32_t ulMemorySize; /*!< Memory size of the Extended memory area */
uint32_t ulMemoryType; /*!< Memory type information */

} __CIFx_PACKED_POST CIFX_EXTENDED_MEMORY_INFORMATION;

Example:
//=============================================================================
// Test memory pointer
//
//
//=============================================================================
void TestExtendedMemoryPointer( void)
{
CIFXHANDLE hSysdevice = NULL;
int32_t lRet = CIFX_NO_ERROR;
uint8_t abBuffer[100] = {0};

printf("\n--- Test Extended Memory Pointer ---\r\n");

lRet = xSysdeviceOpen( NULL, "CIFX0", &hSysdevice);

if ( CIFX_NO_ERROR != lRet)
{
ShowError( lRet);
} else
{
CIFX_EXTENDED_MEMORY_INFORMATION tExtMemory = {0};

// Open a DPM memory pointer

lRet = xSysdeviceExtendedMemory( hSysdevice, CIFX_GET_EXTENDED_MEMORY_INFO,
&tExtMemory);
if(lRet != CIFX_NO_ERROR)
{
// Failed to get the memory mapping
ShowError( lRet);
} else
{
/* Get an extended memory pointer */
lRet = xSysdeviceExtendedMemory( hSysdevice, CIFX_GET_EXTENDED_MEMORY_POINTER,
&tExtMemory);
if(lRet != CIFX_NO_ERROR)
{
// Failed to get the memory mapping
ShowError( lRet);
}else
{
// We have a memory mapping
uint8_t* pbExtMem = (uint8_t*)tExtMemory.pvMemoryPtr;

while( 1 == 1)
{
// Read 100 Bytes
memcpy( abBuffer, pbExtMem, sizeof(abBuffer));

printf("Read data from the extended memory (%d bytes):\n",

sizeof(abBuffer));
DumpData( abBuffer, sizeof(abBuffer));

CIFX API | Programming Reference Guide

printf("Increment the read data:\n");

for ( uint32_t ulIdx =0; ulIdx < sizeof(abBuffer); ulIdx++)
{
abBuffer[ulIdx] +=1;
}

printf("Write data back to the extened memory:\n");

memcpy( pbExtMem, abBuffer, sizeof(abBuffer));

printf("Type (A) for again and (S) to stop the extended read/write test:\n");
if( 'S' == (toupper (_getch())) )
{
break;
}
}
lRet = xSysdeviceExtendedMemory( hSysdevice, CIFX_FREE_EXTENDED_MEMORY_POINTER,
&tExtMemory);
if(lRet != CIFX_NO_ERROR)
{
// Failed to free the memory mapping
ShowError( lRet);
}
}
}

/* Close the system device */

lRet = xSysdeviceClose( hSysdevice);
if ( CIFX_NO_ERROR != lRet)
{
ShowError( lRet);
}
}

// Test done
printf("\n Extended Memory Pointer test done\r\n");

CIFX API | Programming Reference Guide

4.8 Channel-specific functions

Channels (Communication Channels) are the access to a specific fieldbus system running on the
netX hardware. Each channel has its own memory area in the DPM and can be handled
independently from other channels.

4.8.1 xChannelOpen
Open a connection to a communication / user channel on the given board.

Function call:
int32_t xChannelOpen( CIFXHANDLE hDriver,
char* szBoard,
uint32_t ulChannel,
CIFXHANDLE* phChannel)

Arguments:

Argument Data type Description

hDriver CIFXHANDLE Handle to the driver (returned by xDriverOpen)
szBoard char* Identifier for the Board. Can by cifX<BoardNumber> or the
associated alias.
ulChannel uint32_t Channel number to open
phChannel CIFXHANDLE* Returned handle to the channel, to be used on all other
channel functions

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.8.2 xChannelClose
Close a connection to a communication channel.

Function call:
int32_t xChannelClose( CIFXHANDLE hChannel)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel that is to be closed.

CIFX API | Programming Reference Guide

4.8.17 xChannelBusState
Toggle the 'Bus State Flag' in the communication channel handshake flags. Using this flag, the
host application allows or disallows the firmware to open network connections. If set
(CIFX_BUS_STATE_ON), the netX firmware tries to open network connections; if cleared
(CIFX_BUS_STATE_OFF), no connections are allowed and open connections are closed (See
reference [1] for further information).
In generally a fieldbus stack allows the configuration of the field bus start-up behavior. This can be
either 'automatic startup' or 'controlled startup'. If the stack is configured in 'controlled startup' (i.e.
the 'Bus State Flag' is cleared) it will not activate the bus communication until it receives a
CIFX_BUS_STATE_ON state in its handshake flags.

Note: Setting the ‘Bus State flag’ to CIFX_BUS_STATE_ON successfully does not
necessarily mean that the fieldbus stack has established a connection to the fieldbus
system. The routine will signal an absent connection by returning the error code
CIFX_DEV_NO_COM_FLAG (even though toggle of the ‘Bus state flag’ has
succeeded).

Function call:
int32_t xChannelBusState( CIFXHANDLE hChannel,
uint32_t ulCmd,
uint32_t* pulState,
uint32_t ulTimeout)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulCmd uint32_t Bus State Commands:
Clears the BUS state flag
0 = CIFX_BUS_STATE_OFF
Sets the bus state flag
1 = CIFX_BUS_STATE_ON
Read the actual state of the bus state flag
2 = CIFX_BUS_STATE_GETSTATE
pulState uint32_t* Actual state returned
ulTimeout uint32_t Timeout in milliseconds.
If not 0, the function will wait until the communication has
reached the chosen state.

Return values:

CIFX_NO_ERROR if the function succeeds.

CIFX_DEV_NO_COM_FLAG if the function succeeds but fieldbus stack does not communicate.
If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

CIFX API | Programming Reference Guide

4.8.22 xChannelIORead
The function reads the input process data image of a communication channel and afterwards it
instructs the fieldbus protocol to update input data image with actual (latest) fieldbus data.
If the function returns error CIFX_NO_COM_FLAG, the protocol stack does not have an active
network connection and the input data are not up to date. The protocol stack must be started and
configured (see errors CIFX_DEV_NOT_READY / CIFX_DEV_NOT_RUNNING).

Note: On the basis of the implementation, xChannelIORead() delivers the input data from the
"last" call of xChannelIORead() and not the "latest" input data from the fieldbus system.
This has the advantage that the function has not to wait for the data update of the
fieldbus protocol which could need a significant time which are several hundred
microseconds up to milliseconds depending to the configuration and the number of
devices connected to the fieldbus system. But also the limitation that the age of the
input data are depending of the cycle time used to call xChannelIORead().

Function call:
int32_t xChannelIORead( CIFXHANDLE hChannel,
uint32_t ulAreaNumber,
uint32_t ulOffset,
uint32_t ulDataLen,
void* pvData,
uint32_t ulTimeout)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulAreaNumber uint32_t Number of the I/O Input area to get data from
ulOffset uint32_t Offset inside area to start reading data from
ulDataLen uint32_t Length of the data being retrieved
pvData void* Pointer to the return data buffer
ulTimeout uint32_t Timeout in ms to wait for I/O handshake completion of the
channel (if configured)

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.8.23 xChannelIOWrite
The function writes the output process data image of a communication channel and instructs the
fieldbus protocol to send the data to the fieldbus system.
The function can also be used to initialize the output data image the first time, before the fieldbus
system starts the network data transfer. The fieldbus protocol will always be informed to update the
internal output data image by the written data, even if the functions detects that no bus
communication is running (error return CIFX_NO_COM_FLAG).
The only requirement is a started and configured fieldbus protocol (see errors
CIFX_DEV_NOT_READY / CIFX_DEV_NOT_RUNNING).

Note: The function xChannelIOWrite() does not wait until the data are taken by the hardware
or physically transferred by the fieldbus system, because this depends at least on the
fieldbus connection and the cycle time of the fieldbus system which are usually
unknown.

Function call:
int32_t xChannelIOWrite( CIFXHANDLE hChannel,
uint32_t ulAreaNumber,
uint32_t ulOffset,
uint32_t ulDataLen,
void* pvData,
uint32_t ulTimeout)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulAreaNumber uint32_t Number of the I/O Output area to send data to
ulOffset uint32_t Offset inside area to start writing data to
ulDataLen uint32_t Length of the data being send
pvData void* Pointer to the send data buffer
ulTimeout uint32_t Timeout in ms to wait for I/O handshake completion of the
channel (if configured)

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.8.24 xChannelIOReadSendData
Read back the actual content of the output process data image from a communication channel.

Function call:
int32_t xChannelIOReadSendData( CIFXHANDLE hChannel,
uint32_t ulAreaNumber,
uint32_t ulOffset,
uint32_t ulDataLen,
void* pvData)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulAreaNumber uint32_t Number of the I/O Output area to get data from
ulOffset uint32_t Offset inside area to start reading data from
ulDataLen uint32_t Length of the data being received
pvData void* Pointer to the returned data buffer

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.8.25 PLC I/O image functions

Note: Do not use xChannelIORead()/xChannelIOWrite() functions while using the PLC

functions. If PLC functions are used, the application is responsible to synchronize I/O
data access by using the xChannelPLCIsReady...()/xChannelPLCActivate...()
functions. There is no internal synchronization mechanism available to synchronize
access states between xChannelIORead()/xChannelIOWrite() and the PLC functions.
Mixing the functions will result in unpredictable I/O states.

Some of the PLC programs (Programmable Logic Controller also known as SoftPLCs) are using an
own process data image layout. Such programs need to copy the process data, from the local
buffers, necessary for the standard xChannelIORead()/xChannelIOWrite() functions, into their own
data image layout. In such a case, process data are always copied two times. First time between
the cards I/O process data image and the local function buffers offered by the application and the
second time between the local buffers and the PLC specific process images.
PLC functions are design to save the copy between the cards I/O process data image and the local
function buffers (done by xChannelIORead()/xChannelIOWrite()).
Therefore xChannelIORead() and xChannelIOWrite() are split into separate functions. One function
to get data pointers to the input and output process data image which can be used by the
application to directly access the cards I/O process data image. And two other functions to control
and synchronize the access to the cards I/O process image data between the user application and
the fieldbus protocol, running on the card.
 xChannelPLCMemoryPtr
Getting the data pointers to the cards I/O process data image
 xChannelPLCActivateRead() / xChannelPLCActivateWrite()
Activate the data exchange of the cards I/O process data image with the fieldbus protocol
running on the card
 xChannelPLCIsReadReady() / xChannelPLCIsWriteReady()
Check if the fieldbus protocol has finished the access to the crads I/ process data image and
if the application is allowed to access the data
Important for the use of the functions is a prior call to the xChannelPLCMemoryPtr() function. This
will deliver the necessary pointers to the I/O process data image.

Note: If the PLC functions are used, the application is responsible to synchronize the data
access between the host and the communication channel.

Before closing an application, all memory pointers retrieved by calling xChannelPLCMemoryPtr(),

(command CIFX_MEM_PTR_OPEN) should be returned to the system to avoid memory leaks.
Pointers are returned by calling xChannelPLCMemoryPtr() using the CIFX_MEM_PTR_CLOSE
command.

CIFX API | Programming Reference Guide

4.8.25.1 xChannelPLCMemoryPtr
Retrieve a memory pointer to the I/O data area for a PLC (Programmable Logic Controller). This
enables an application to write data directly to the dual port memory (I/O data image) without doing
a combined handshake like in xChannelIORead() or xChannelIOWrite().
Before closing an application, all retrieved pointers should be released to avoid system memory
leaks. Releasing a pointer is done by calling xChannelPLCMemoryPtr() using the
CIFX_MEM_PTR_CLOSE command.

Function call:
int32_t xChannelPLCMemoryPtr( CIFXHANDLE hChannel,
uint32_t ulCmd,
void* pvMemoryInfo)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulCmd uint32_t PLC Memory Pointer Commands:
Acquire a memory pointer
1 = CIFX_MEM_PTR_OPEN
Map a user specific memory area
2 = CIFX_MEM_PTR_USR -> not supported
Release a memory pointer
3 = CIFX_MEM_PTR_CLOSE
pvMemoryInfo void* Pointer to PLC_MEMORY_INFORMATION structure.
This structure describes the requested area and also
contains the returned memory pointer on success

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

Description of the PLC_MEMORY_INFORMATION Structure:

Value Data type Description

pvMemoryID void* Identifier of the memory area
ppvMemoryPtr void** Memory pointer
ulAreaDefinition uint32_t Input / Output area
ulAreaNumber uint32_t Area number (0..1)
pulIOAreaStartOffset uint32_t* Buffer to store the I/O area start offset
pulAreaSize uint32_t* Buffer to store the size of the I/O area

PLC_MEMORY_INFORMATION Structure:
/*****************************************************************************/
/*! PLC Memory Information structure */
/*****************************************************************************/
typedef __CIFx_PACKED_PRE struct PLC_MEMORY_INFORMATIONtag
{
void* pvMemoryID; /*!< Identification of the memory area */
void** ppvMemoryPtr; /*!< Memory pointer */
uint32_t ulAreaDefinition; /*!< Input/output area */
uint32_t ulAreaNumber; /*!< Area number */
uint32_t* pulIOAreaStartOffset; /*!< Start offset */
uint32_t* pulIOAreaSize; /*!< Memory size */
} __CIFx_PACKED_POST PLC_MEMORY_INFORMATION;

Example:
//=============================================================================
// Test PLC Functions
//
//
//=============================================================================
void TestPLCFunctions( void)
{
unsigned char abBuffer[1000] = {0};
uint32_t ulState = 0;

printf("\n--- Test PLC functions ---\r\n");

long lRet = CIFX_NO_ERROR;

/* Open channel */
CIFXHANDLE hDevice = NULL;
lRet = xChannelOpen(NULL, "CIFx0", 0, &hDevice);
if(lRet != CIFX_NO_ERROR)
{
ShowError(lRet);
} else
{
/* Start PLC functions */
unsigned char* pabDPMMemory = NULL;
uint32_t ulAreaStartOffset = 0;
uint32_t ulAreaSize = 0;
long lRet = CIFX_NO_ERROR;
long lRetIN = CIFX_NO_ERROR;
long lRetOUT = CIFX_NO_ERROR;

/* Define the memory structures for Input data */

PLC_MEMORY_INFORMATION tMemory = {0};
tMemory.pvMemoryID = NULL; // Identification of the memory area
tMemory.ppvMemoryPtr = (void**)&pabDPMMemory; // Memory pointer
tMemory.ulAreaDefinition = CIFX_IO_INPUT_AREA; // Input/output area
tMemory.ulAreaNumber = 0; // Area number
tMemory.pulIOAreaStartOffset = &ulAreaStartOffset; // Start offset of the requested channel
tMemory.pulIOAreaSize = &ulAreaSize; // Memory size of the requested channel

/* Define the memory structures for Output data */

CIFX API | Programming Reference Guide

PLC_MEMORY_INFORMATION tMemory_OUT = {0};

tMemory_OUT.pvMemoryID = NULL; // Identification of the memory
area
tMemory_OUT.ppvMemoryPtr = (void**)&pabDPMMemory_OUT; // Memory pointer
tMemory_OUT.ulAreaDefinition = CIFX_IO_OUTPUT_AREA; // Input/output area
tMemory_OUT.ulAreaNumber = 0; // Area number
tMemory_OUT.pulIOAreaStartOffset = &ulAreaStartOffset_OUT; // Start offset of the requested
channel
tMemory_OUT.pulIOAreaSize = &ulAreaSize_OUT; // Memory size of the requested
channel

/* Open a DPM memory pointer */

if ( (CIFX_NO_ERROR != (lRetIN = xChannelPLCMemoryPtr( hDevice, CIFX_MEM_PTR_OPEN, &tMemory)) )
||
(CIFX_NO_ERROR != (lRetOUT = xChannelPLCMemoryPtr( hDevice, CIFX_MEM_PTR_OPEN,
&tMemory_OUT))) )
{
// Failed to get the memory mapping
ShowError( lRetIN);
ShowError( lRetOUT);
} else
{
uint32_t ulWaitBusCount = 100;

/* Signal application is ready */

lRet = xChannelHostState( hDevice, CIFX_HOST_STATE_READY, &ulState, 100);
if( CIFX_NO_ERROR != lRet)
{
ShowError(lRet);
}

/* Wait until BUS is up and running */

printf("\r\nWait until BUS communication is available!\r\n");
do
{
lRet = xChannelBusState( hDevice, CIFX_BUS_STATE_ON, &ulState, 100);
if( CIFX_NO_ERROR != lRet)
{
if( CIFX_DEV_NO_COM_FLAG != lRet)
{
ShowError(lRet);
break;
}
} else if( 1 == ulState)
{
/* Bus is ON */
printf("\r\nBUS is ON!\r\n");
break;
}
} while ( --ulWaitBusCount > 0);

if( 0 == ulWaitBusCount)
{
ShowError(lRet);
}

/*----------------------*/
/* Start cyclic data IO */
/*----------------------*/
if( CIFX_NO_ERROR == lRet)
{
printf("\n Press any key to stop \r\n");
while (!_kbhit())
{
// We have a memory mapping, check if access to the DPM is allowed
uint32_t ulReadState = 0;
uint32_t ulWriteState = 0;

/*----------------------------------------*/
/* Check if we can access the INPUT image */
/*----------------------------------------*/

lRet = xChannelPLCIsReadReady ( hDevice, 0, &ulReadState);

if( CIFX_NO_ERROR != lRet)
{

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
CIFX API (Application Programming Interface) 76/118
ShowError( lRet);
} else if( 1 == ulReadState)
{
/* It is allowed to read the image */
/* Read 100 Bytes */
memcpy( abBuffer, pabDPMMemory, sizeof(abBuffer));

/* Activate transfer */
lRet = xChannelPLCActivateRead ( hDevice, 0);
if( CIFX_NO_ERROR != lRet)
ShowError( lRet);
}

/*-----------------------------------------*/
/* Check if we can access the OUTPUT image */
/*-----------------------------------------*/
lRet = xChannelPLCIsWriteReady ( hDevice, 0, &ulWriteState);
if( CIFX_NO_ERROR != lRet)
{
ShowError( lRet);
} else if( 1 == ulWriteState)
{
/* It is allowed to write the image */
pabDPMMemory_OUT[0]++;
pabDPMMemory_OUT[1] = abBuffer[1];

lRet = xChannelPLCActivateWrite ( hDevice, 0);

if( CIFX_NO_ERROR != lRet)
ShowError( lRet);
}
}

/* clean keyboard buffer */

_getch();
}
}

lRet = xChannelBusState( hDevice, CIFX_BUS_STATE_OFF, &ulState, 100);

if(CIFX_NO_ERROR != lRet)
{
ShowError(lRet);
}

lRet = xChannelHostState( hDevice, CIFX_HOST_STATE_NOT_READY, &ulState, 100);

if(CIFX_NO_ERROR != lRet)
{
ShowError(lRet);
}

/* Return the DPM memory pointer */

if ( NULL != pabDPMMemory)
{
lRet = xChannelPLCMemoryPtr( hDevice, CIFX_MEM_PTR_CLOSE, &tMemory);
if(lRet != CIFX_NO_ERROR)
/* Failed to return memory pointer */
ShowError( lRet);
}

/* Return the DPM memory pointer */

if ( NULL != pabDPMMemory_OUT)
{
lRet = xChannelPLCMemoryPtr( hDevice, CIFX_MEM_PTR_CLOSE, &tMemory_OUT);
if(lRet != CIFX_NO_ERROR)
/* Failed to return memory pointer */
ShowError( lRet);
}

// Close channel
if( hDevice != NULL) xChannelClose(hDevice);
}

printf("\n Test PLC functions done\r\n");

}

CIFX API | Programming Reference Guide

4.8.25.2 xChannelPLCActivateRead
Instruct the communication channel to refresh the input process data image. The end of the update
cycle must be checked by the application using the function xChannelPLCIsReadReady()

Note: Do not call this function while the actual state is 'not finished' (check with the
corresponding xChannelPLCIs......Ready() function), otherwise the result is
unpredictable.

Function call:
int32_t xChannelPLCActivateRead( CIFXHANDLE hChannel,
uint32_t ulAreaNumber)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulAreaNumber uint32_t Number of the I/O area to request a input data refresh

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

CIFX API | Programming Reference Guide

4.8.26 DMA functions

4.8.26.1 xChannelDMAState
Toggle the 'DMA Enable Flag' in the communication channel handshake flags. This function can be
used to change the I/O image transfer from DPM to bus-master-DMA mode. If PLC memory
functions are used, the I/O image pointers need to be re-read after enabling/disabling DMA mode.

Note: DMA is only possible on PCI based hardware. On none PCI based hardware, this
function is not available and will return with an error

Function call:
int32_t xChannelDMAState( CIFXHANDLE hChannel,
uint32_t ulCmd,
uint32_t* pulState)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulCmd uint32_t DMA State Commands:
Disable DMA mode
0 = CIFX_DMA_STATE_OFF
Enable DMA mode
1 = CIFX_DMA_STATE_ON
Get actual DMA state
2 = CIFX_DMA_STATE_GETSTATE
pulState uint32_t* Actual state returned

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.8.27 Notification functions

Notification functions can be used for devices running in interrupt mode. These functions are
registering a callback for pre-defined events from the hardware.
The callback function is called if the corresponding event occurs on the device.

Note: Notification functions are only available for devices running in interrupt mode.

Available Notifications

Notification Definition Description

Packet transfer CIFX_NOTIFY_RX_MBX_FULL Receive mailbox full
(packet available)
CIFX_NOTIFY_TX_MBX_EMPTY Send mailbox is empty
(packet can be send)
I/O data transfer CIFX_NOTIFY_PD0_IN Input area 0 has been processed
(see below)
CIFX_NOTIFY_PD1_IN Input area 1 has been processed
(see below)
CIFX_NOTIFY_PD0_OUT Output area 0 has been processed
(see below)
CIFX_NOTIFY_PD1_OUT Output area 1 has been processed
(see below)
Synchronization CIFX_NOTIFY_SYNC Fieldbus synchronous event occurred
Communication Flag State CIFX_NOTIFY_COM_STATE Communication state of the communication
channel has changed

4.8.27.1 Packet transfer notifications

Packet transfer is used for asynchronous command/confirmation data (e. g. SDOs).
Packet data are handled via a mailbox system. In interrupt mode the actual state of the mailbox
system (send/receive mailbox) can be signaled by notifications (see above).

CIFX API | Programming Reference Guide

4.8.27.2 I/O data transfer notifications

The result of the I/O handling and the corresponding notifications which can be signaled to the user
application are depending on the configured I/O data exchange mode. This also effect the handling
in the user application, when it is reasonable to call xChannelIORead() and xChannelIOWrite().

Note: "I/O Data Transfer" notifications depending on the so called “I/O Exchange Mode”
configured on the device. These modes are defining how notifications are created by
the device state changes. The callback functions are called if the driver detects a state
change in the device handshake flags. How the application processes the notification is
part of the application development and must correspond to the configured mode
settings of the device. Handshake modes are described in [1].

Handshake modes are defining which part (device/host) is the active part.

Following modes are known:

I/O Exchange mode Description

uncontrolled No data access synchronization between host and device. Both systems are running
independent of each other and data are exchanged without taking care about data
consistency.
Notification: NONE
buffered The host activates the data transfer between device and host.
host controlled Actual I/O data from the fieldbus system and from the host are always stored in the local I/O
(default) buffers on the device.
If the host requests new input data (calling xChannelIORead()), the device will copy the
currently available input data from the local buffer to the DPM (PDx_IN area) and signals "data
updated" (1). The host can read the new input data with the next call to xChannelIORead().
If the host writes new output data to the DPM (PDx_OUT area) by calling xChannelIOWrite().
The device, will copy the data from the DPM to the local output buffer and signals "data
updated" (2) if the copy is done.
(1) Notification for the input data: CIFX_NOTIFY_PDx_IN
(2) Notification for the output data: CIFX_NOTIFY_PDx_OUT
buffered ATTENTION:
device controlled By default NOT supported from Hilscher Stacks
The device will start to copy the actual input data from the fieldbus system to the DPM
(PDx_IN area) and signals "input data updated" (1). The user has to call xChannelIORead() to
read the input data from the DPM. All further input data received by the fieldbus are stored in
the device local input buffer until the host reads the data again.
The device requests new output data from the host (2) and until the host has written new data,
output data are send from the local device buffer to the fieldbus system. If the host writes new
output data (calling xChannelIOWrite()) , the device copies the data to the local output buffer
and requests (2) new output data as soon as the copy of the data is done.
(1) Notification for the input data: CIFX_NOTIFY_PDx_IN
(2) Notification for the output data: CIFX_NOTIFY_PDx_OUT

CIFX API | Programming Reference Guide

Data Exchange Mode - Buffered Host Controlled I/O:

Buffered Host Controlled: I/O Read Buffered Host Controlled: I/O Write
Application DPM netX Device Fieldbus Application DPM netX Device Fieldbus

1 Input Input
1 Input Input

Output Output Output Output

2 Input Input
2 Input Input
xChannelIORead()
xChannelIOWrite()
Output Output Output Output

Input Update
3 Done Input Input
3 Input Input
Output Update
Output Output Done Output Output

Figure 3: Data Exchange Mode: Buffered Host Controlled I/O

I/O Read I/O Write

Step Description Step Description

1 Fieldbus protocol reads input data from the 1 Fieldbus protocol sends the output data stored
fieldbus system and stores the data in the in the internal "Output Buffer" to the fieldbus
internal "Input Buffer" system
2 Application uses xChannelIORead() which 2 Application calls xChannelIOWrite() which write
reads the actual data from the DPM (Dual- the actual user data to the DPM (Dual-Ported
Ported Memory) PD-IN area and signals the Memory) PD-OUT area and signals the card to
card to update the PD-IN area. update the internal "Output Buffer".
3 The stack copies the actual data form the 3 The stack copies the data from the DPM PB-
internal "Input Buffer" (holding the latest input OUT area to the internal "Output Buffer".
data) to the DPM PD-IN area.
After the data copy, the protocol stack signals After the data copy, the protocol stack signals
"Input Update Done" which schedules a "Output Update Done" which schedules a
CIFX_NOTIFY_PDx_IN notification. CIFX_NOTIFY_PDx_OUT notification.

Note: In these modes, the notifications just inform the application when the input data are
copied from the device local input buffer to the DPM and when the output data are
copied from the DPM to the device local output buffer. There is no synchronization with
any fieldbus data cycle.

CIFX API | Programming Reference Guide

Data Exchange Mode - Buffered Device Controlled I/O

Buffered Device Controlled: I/O Read Buffered Device Controlled: I/O Write
Application DPM netX Device Fieldbus Application DPM netX Device Fieldbus
I/O read data
1 available Input Input
1 Input Input
I/O waiting for
output data
Output Output Output Output

2 Input Input
2 Input Input

Output Output Output Output

3 Input Input
3 Input Input
xChannelIORead()
xChannelIOWrite()
Output Output Output Output

Figure 4: Data Exchange Mode: Buffered Device Controlled I/O

I/O Read I/O Write

Step Description Step Description

1 Fieldbus protocol reads input data from the 1 The device takes the output date from the DPM
fieldbus system and stores the data in the (PDx_OUT area) and copies it to the device
internal "Input Buffer", copies the data to the local "Output Buffer".
DPM (PDx_IN) area. After the copy the device requests new output
After writing the input data to the DPM data by signaling a CIFX_NOTIFY_PDx_OUT
(PDx_IN), the device signals "I/O read data notification.
available" scheduling a CIFX_NOTIFY_PDx_IN
notification.
2 Any further data from a bus cycle will be stored 2 The device sends the stored output with any
in the device local input buffer. further bus cycle
3 If the host reads the input data (by calling 3 If the host writes new output data to the DPM
xChannelIORead()), the device is signaled (PDx_OUT) by calling xChannelIOWrite(). The
"Input data done" than the device is able to device is signaled "New output data
update the input data again. available".

Note: The application determines when read input or write output data. The notification
informs the application when read or write is possible. There is no synchronization with
any fieldbus data cycle.

CIFX API | Programming Reference Guide

Determining the Configured "I/O Exchange Mode":

The configured I/O data exchange (host controlled/device controlled) can be read from the
communication channels "Common Status Block" (bPDInHskMode / (bPDOutHskMode). The block
can be read and evaluated by the user application using the xChannelCommonStatusBlock()
function.
The "Common Status Block" is described in the "netX Dual-Port Memory Interface DPM Manual".

Following data exchanges mode definitions are available:

/* Block definition: I/O Mode */
#define RCX_IO_MODE_DEFAULT 0x0000 /*!< I/O mode default, for compability reasons this
value is identical to 0x4 (buffered host controlled) */
#define RCX_IO_MODE_BUFF_DEV_CTRL 0x0002 /*!< I/O mode buffered device controlled */
#define RCX_IO_MODE_UNCONTROLLED 0x0003 /*!< I/O mode bus synchronous device controlled */
#define RCX_IO_MODE_BUFF_HST_CTRL 0x0004 /*!< I/O mode buffered host controlled */

Note: Possible data exchanges modes are fieldbus protocol specific and described in the
corresponding fieldbus "Protocol API" manual.

CIFX API | Programming Reference Guide

4.8.27.3 Bus synchronization notifications

The notification functions offering a bus synchronization event if supported by the fieldbus protocol.

Note: "Synchronization" notifications" depending on the so called “Synchronization Mode”

configured on the device.

Host Controlled Synchronization Device Controlled Synchronization

Application DPM netX Device Fieldbus Application DPM netX Device Fieldbus

1 1 Sync event
xChannelSyncState() Start bus cycle recogniced Bus event
Sync Flag Sync Flag

2 Sync command 2
done
Sync Flag Sync Flag
xChannelSyncState()

Figure 5: Bus synchronization notifications

Host Controlled Synchronization Device Controlled Synchronization

Step Description Step Description

1 The application starts to send a synchronization 1 If the fieldbus protocol recognizes the
command configured sync event, is signals a "Sync
xChannelSyncState(CIFX_SYNC_SIGNAL_CMD) to event recognized" and scheduled a
the device. CIFX_NOTIFY_SYNC notification.
Depending on the configuration the
synchronization command (e.g. start bus cycle) is
executed by the device.
2 The device signals "Sync command done", by 2 Application has to call
scheduling a CIFX_NOTIFY_SYNC notification if xChannelSyncState(CIFX_SYNC_SIGNAL_ACK)
the command is processed. before a new bus event is signaled again.

Determining the Configured "Synchronization Mode":

The configured synchronization mode (host controlled/device controlled) can be read from the
communication channels "Common Status Block" (bSyncHskMode). The block can be read and
evaluated by the user application using the xChannelCommonStatusBlock() function.
The "Common Status Block" is described in the "netX Dual-Port Memory Interface DPM Manual".
Following synchronization mode definitions are available:
/* Block definition: Synchronization Mode */
#define RCX_SYNC_MODE_OFF 0x00
#define RCX_SYNC_MODE_DEV_CTRL 0x01
#define RCX_SYNC_MODE_HST_CTRL 0x02

Note: Possible synchronization modes are fieldbus protocol specific and described in the
corresponding fieldbus "Protocol API" manual

CIFX API | Programming Reference Guide

4.8.27.4 PFN_NOTIFY_CALLBACK - Callback function definition

Note: The registered callback function will be invoked as soon as the callback is registered
and the corresponding event is valid. This could also happen while the user application
is still in the xChannelRegisterNotification() function call.

void NotificationCallback( uint32_t ulNotification,

uint32_t ulDataLen,
void* pvData
void* pvUser);

Arguments:

Argument Data type Description

ulNotification uint32_t Occurred event
ulDataLen uint32_t Length of additional data
pvData void* Additional Data (depends on ulNotification)
pvUser void* User parameter from registration

Possible Notification Events:

ulNotification Passed Data Description

CIFX_NOTIFY_RX_MBX_FULL Pointer to Signaled when receive mailbox
CIFX_NOTIFY_RX_MBX_FULL_DATA_T becomes full and a data packet is
structure containing the total number of available to read.
packets waiting to be read from the device.
CIFX_NOTIFY_TX_MBX_EMPTY Pointer to Send mailbox becomes empty and
CIFX_NOTIFY_TX_MBX_EMPTY_DATA_T a new packet can be send to the
structure containing the maximum amount device.
of packets which can be send to the device.
CIFX_NOTIFY_PD0_IN none Input area 0 has been processed
CIFX_NOTIFY_PD1_IN none Input area 1 has been processed
CIFX_NOTIFY_PD0_OUT none Output area 0 has been processed
CIFX_NOTIFY_PD1_OUT none Output area 1 has been processed
CIFX_NOTIFY_SYNC none Bus synchronization notification,
signals the SYNC event on the
fieldbus/device occurred.
CIFX_NOTIFY_COM Pointer to Communication flag notification.
CIFX_NOTIFY_COM_STATE_T structure Signals state changes of the
containing the actual state of the COM-flag COM-flag (set or cleared).

CIFX API | Programming Reference Guide

4.8.27.5 xChannelRegisterNotification
Register an event callback for channel events.
Depending on the event type additional information is passed in the callback. If a callback is
already registered for the given event, the function will return an error.
It is not possible to register multiple applications for the same notification.

Function call:
int32_t xChannelRegisterNotification( CIFXHANDLE hChannel,
uint32_t ulNotification,
PFN_NOTIFY_CALLBACK pfnCallback,
void* pvUser);

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulNotification uint32_t Possible Notification:
1 = CIFX_NOTIFY_RX_MBX_FULL
2 = CIFX_NOTIFY_TX_MBX_EMPTY
3 = CIFX_NOTIFY_PD0_IN
4 = CIFX_NOTIFY_PD1_IN
5 = CIFX_NOTIFY_PD0_OUT
6 = CIFX_NOTIFY_PD1_OUT
7 = CIFX_NOTIFY_SYNC
8 = CIFX_NOTIFY_COM
pfnCallback PFN_NOTIFY_CALLBACK Function to be called if event occurs
pvUser void* Parameter passed to callback

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.8.27.6 xChannelUnregisterNotification
Un-registers a previously registered notification event callback function for channel events.

Function call:
int32_t xChannelUnregisterNotification( CIFXHANDLE hChannel,
uint32_t ulNotification,);

Arguments:

Argument Data type Description

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

4.8.28 Fieldbus synchronization handling

Certain fieldbus protocol stacks are offering so call synchronization functionalities to synchronize
devices connected to a fieldbus system.
Such synchronization functions are handled independent from of the cyclic I/O data transfer.

General Definition:

In general, synchronization handling distinguishes between device synchronization and host

synchronization operation. The difference between the two modes is the component (host / device)
which activates the synchronization and the response to the synchronization signal (event).
 Host Controlled Synchronization
In this mode, the host signals a synchronization to the hardware and the hardware has to
respond to this signal
 Device Controlled Synchronization
In this case, the device starts to signal a synchronization event and the host has to
acknowledge the reception of the synch signal.
Synchronization must be handled by the user application and can be done in polling mode (not
preferred) and interrupt mode of the hardware. In interrupt mode the drivers notification function is
used to handle synchronization event via a user callback function.

Synchronization Handling in Polling Mode:

In polling mode the xChannelSyncState() function is used to activate

(CIFX_SYNC_SIGNAL_CMD) or to acknowledge (CIFX_SYNC_ACKNOWLEDGE_CMD) a
synchronization signal, depending on the configured fieldbus synchronization mode (host
controlled / device controlled).
xChannelSyncState() can also be used to check (ulTimeout == 0) or to wait (ulTimeout != 0) for a
device synchronization signal. Or until a new host synchronization command can be initiated.

Synchronization Handling in Interrupt Mode:

In interrupt mode, the drivers register notification function is used to handle synchronization events.
A user application is able to register a callback function for synchronization events
(CIFX_SYNC_EVENT). The registered callback function will be executed if either the device is
signaling a synchronization event or if the device acknowledges a synchronization command
initiated by the host application.
 Device Synchronization Mode
The host has to register for a synchronization event and if the event occurs (callback function
is invoked) the host has to acknowledge the event using the
xChannelSyncState(...CIFX_SYNC_ACKNOWLEDGE_CMD...).
 Host Synchronization Mode
The host calls xChannelSyncState(...CIFX_SYNC_SIGNAL_CMD...) to signal a
synchronization. The registered callback function will be invoked if the device acknowledges
the command.

CIFX API | Programming Reference Guide

Verifying Synchronization Misses:

xChannelSyncState() offers a pointer to an error counter buffer (pulErrorCount). This counter can
be used by the user application to determine the lost of a synchronization signals.
A changing error counter value between two subsequent xChannelSyncState() calls indicates a
lost signal. This means, in "Host Controlled Mode", the device was not quick enough to process the
previous command and in "Device Controlled Mode", the host has not acknowledged the
synchronization signal until the next synchronization signal was initiated.

Determining the Configured Synchronization Mode:

The configured synchronization mode (host controlled / device controlled) can be read from the
communication channels "Common Status Block" (bSyncHskMode). The block can be read and
evaluated by the user application using the xChannelCommonStatusBlock() function.
The "Common Status Block" is described in the "netX Dual-Port Memory Interface DPM Manual".
Currently the following synchronization modes are defined.
/* Block definition: Synchronization Mode */
#define RCX_SYNC_MODE_OFF 0x00
#define RCX_SYNC_MODE_DEV_CTRL 0x01
#define RCX_SYNC_MODE_HST_CTRL 0x02

Also the synchronization error counter (bErrorSyncCnt) and the synchronization source
(bSyncSource) can be evaluated from the "Common Status Block".

CIFX API | Programming Reference Guide

Note: Fieldbus synchronization must be supported by the used fieldbus protocol stack.
Please consult the corresponding fieldbus "Protocol API" manual to make sure
synchronization is supported.

Note: Synchronization operation assumes a corresponding fieldbus configuration.

Note: Fieldbus synchronization is a time critical process and should be processed as fast as
possible. On Windows operating systems, responds times to synchronization events
are not guaranteed and can lead in serious jitter. Usually synchronization will be
handled in interrupt mode.

The xChannelSyncState() function can also be used in polling mode using a timeout
and the CIFX_SYNC_WAIT_CMD command, but this will not change the Windows
operating system respond timing issues.

Function call:
int32_t xChannelSyncState(CIFXHANDLE hChannel,
uint32_t ulCmd,
uint32_t ulTimeout
uint32_t* pulErrorCount)

Arguments:

Argument Data type Description

hChannel CIFXHANDLE Handle of the channel.
ulCmd uint32_t Synchronization Commands:
Signal sync to device
1 = CIFX_SYNC_SIGNAL_CMD
Acknowledge a sync that has been set by the device
2 = CIFX_SYNC_ACKNOWLEDGE_CMD
Wait for sync being signaled by device (Device Controlled), or
until host can signal new Sync State (Host Controlled)
3 = CIFX_SYNC_WAIT_CMD
ulTimeout uint32_t Timeout in ms to wait until bits can be signaled or have been
signaled by the device
pulErrorCount uint32_t* Returned Actual Sync Error counter

Return values:

CIFX_NO_ERROR if the function succeeds.

If the function fails, a nonzero error code from chapter Error codes from page 108 is returned. You
can use the function xDriverGetErrorDescription() to get a description of this error.

CIFX API | Programming Reference Guide

5 Simple C-application example

The simple C application demonstrates the minimum functions which must be called to enable an
application to work with a CIFX/COMX/netX based hardware.
The example is named CIFXDEMO and the source, including a Microsoft Visual C++ 6.0 project,
can be found on the Hilscher system CDs.

5.1 The Main() function

/*****************************************************************************/
/*! The main function
* \return 0 on success */
/*****************************************************************************/
int main(int argc, char* argv[])
{
CIFXHANDLE hDriver = NULL;
int32_t lRet = CIFX_NO_ERROR;

UNREFERENCED_PARAMETER(argc);
UNREFERENCED_PARAMETER(argv);

/* Open the cifX driver */

lRet = xDriverOpen(&hDriver);

if(CIFX_NO_ERROR != lRet)
{
printf("Error opening driver. lRet=0x%08X\r\n", lRet);
} else
{
/* Example how to find a cifX/comX board */
EnumBoardDemo(hDriver);

/* Example how to communicate with the SYSTEM device of a board */

SysdeviceDemo(hDriver, "cifX0");

/* Example how to communicate with a communication channel on a board */

ChannelDemo(hDriver, "cifX0", 0);

/* Close the cifX driver */

xDriverClose(hDriver);
}
return 0;
}

CIFX API | Programming Reference Guide

5.2 System device example

/*****************************************************************************/
*! Function to demonstrate system device functionality (Packet Transfer)
* \return CIFX_NO_ERROR on success */
/*****************************************************************************/
int32_t SysdeviceDemo(CIFXHANDLE hDriver, char* szBoard)
{
int32_t lRet = CIFX_NO_ERROR;
CIFXHANDLE hSys = NULL;

printf("---------- System Device handling demo ----------\r\n");

/* Driver/Toolkit successfully opened */

lRet = xSysdeviceOpen(hDriver, szBoard, &hSys);

if(CIFX_NO_ERROR != lRet)
{
printf("Error opening SystemDevice!\r\n");
} else
{
SYSTEM_CHANNEL_SYSTEM_INFO_BLOCK tSysInfo = {0};
uint32_t ulSendPktCount = 0;
uint32_t ulRecvPktCount = 0;
CIFX_PACKET tSendPkt = {0};
CIFX_PACKET tRecvPkt = {0};

/* System channel successfully opened, try to read the System Info Block */
if( CIFX_NO_ERROR != (lRet = xSysdeviceInfo(hSys,
CIFX_INFO_CMD_SYSTEM_INFO_BLOCK,
sizeof(tSysInfo),
&tSysInfo)))
{
printf("Error querying system information block\r\n");
} else
{
printf("System Channel Info Block:\r\n");
printf("DPM Size : %u\r\n", tSysInfo.ulDpmTotalSize);
printf("Device Number : %u\r\n", tSysInfo.ulDeviceNumber);
printf("Serial Number : %u\r\n", tSysInfo.ulSerialNumber);
printf("Manufacturer : %u\r\n", tSysInfo.usManufacturer);
printf("Production Date : %u\r\n", tSysInfo.usProductionDate);
printf("Device Class : %u\r\n", tSysInfo.usDeviceClass);
printf("HW Revision : %u\r\n", tSysInfo.bHwRevision);
printf("HW Compatibility : %u\r\n", tSysInfo.bHwCompatibility);
}

CIFX API | Programming Reference Guide

/* Do a simple Packet exchange via system channel */

xSysdeviceGetMBXState(hSys, &ulRecvPktCount, &ulSendPktCount);
printf("System Mailbox State: MaxSend = %u, Pending Receive = %u\r\n",
ulSendPktCount, ulRecvPktCount);

if(CIFX_NO_ERROR != (lRet = xSysdevicePutPacket(hSys,

&tSendPkt,
PACKET_WAIT_TIMEOUT)))
{
printf("Error sending packet to device!\r\n");
} else
{
printf("Send Packet:\r\n");
DumpPacket(&tSendPkt);

xSysdeviceGetMBXState(hSys, &ulRecvPktCount, &ulSendPktCount);

printf("System Mailbox State: MaxSend = %u, Pending Receive = %u\r\n",
ulSendPktCount, ulRecvPktCount);

if(CIFX_NO_ERROR != (lRet = xSysdeviceGetPacket(hSys,

sizeof(tRecvPkt),
&tRecvPkt,
PACKET_WAIT_TIMEOUT)) )
{
printf("Error getting packet from device!\r\n");
} else
{
printf("Received Packet:\r\n");
DumpPacket(&tRecvPkt);

xSysdeviceGetMBXState(hSys, &ulRecvPktCount, &ulSendPktCount);

printf("System Mailbox State: MaxSend = %u, Pending Receive = %u\r\n",
ulSendPktCount, ulRecvPktCount);
}
}

/* Close the system device */

xSysdeviceClose(hSys);
}

printf(" State = 0x%08X\r\n", lRet);

printf("----------------------------------------------------\r\n");

return lRet;
}

CIFX API | Programming Reference Guide

5.3 Communication channel example

/*****************************************************************************/
/*! Function to demonstrate communication channel functionality
* Packet Transfer and I/O Data exchange
* \return CIFX_NO_ERROR on success */
/*****************************************************************************/
int32_t ChannelDemo(CIFXHANDLE hDriver, char* szBoard, uint32_t ulChannel)
{
CIFXHANDLE hChannel = NULL;
int32_t lRet = CIFX_NO_ERROR;

printf("---------- Communication Channel demo ----------\r\n");

lRet = xChannelOpen(hDriver, szBoard, ulChannel, &hChannel);

if(CIFX_NO_ERROR != lRet)
{
printf("Error opening Channel!");
} else
{
CHANNEL_INFORMATION tChannelInfo = {0};
CIFX_PACKET tSendPkt = {0};
CIFX_PACKET tRecvPkt = {0};
/* Read and write I/O data (32Bytes). Output data will be incremented each
cyle */
uint8_t abSendData[32] = {0};
uint8_t abRecvData[32] = {0};
uint32_t ulCycle = 0;
uint32_t ulState = 0;

/* Channel successfully opened, so query basic information */

if( CIFX_NO_ERROR != (lRet = xChannelInfo(hChannel,
sizeof(CHANNEL_INFORMATION),
&tChannelInfo)))
{
printf("Error querying system information block\r\n");
} else
{
printf("Communication Channel Info:\r\n");
printf("Device Number : %u\r\n", tChannelInfo.ulDeviceNumber);
printf("Serial Number : %u\r\n", tChannelInfo.ulSerialNumber);
printf("Firmware : %s\r\n", tChannelInfo.abFWName);
printf("FW Version : %u.%u.%u build %u\r\n",
tChannelInfo.usFWMajor,
tChannelInfo.usFWMinor,
tChannelInfo.usFWRevision,
tChannelInfo.usFWBuild);
printf("FW Date : %02u/%02u/%04u\r\n",
tChannelInfo.bFWMonth,
tChannelInfo.bFWDay,
tChannelInfo.usFWYear);
printf("Mailbox Size : %u\r\n", tChannelInfo.ulMailboxSize);
}

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
Simple C-application example 98/118
/* Do a basic Packet Transfer */
if(CIFX_NO_ERROR != (lRet = xChannelPutPacket( hChannel,
&tSendPkt,
PACKET_WAIT_TIMEOUT)))
{
printf("Error sending packet to device!\r\n");
} else
{
printf("Send Packet:\r\n");
DumpPacket(&tSendPkt);

if(CIFX_NO_ERROR != (lRet = xChannelGetPacket(hChannel,

sizeof(tRecvPkt),
&tRecvPkt,
PACKET_WAIT_TIMEOUT)) )
{
printf("Error getting packet from device!\r\n");
} else
{
printf("Received Packet:\r\n");
DumpPacket(&tRecvPkt);
}
}

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
Simple C-application example 99/118
/* Do a basic IO data transfer */
/* Set Host Ready to signal the filed bus an application is ready */
lRet = xChannelHostState(hChannel,
CIFX_HOST_STATE_READY,
&ulState,
HOSTSTATE_TIMEOUT);

if(CIFX_NO_ERROR != lRet)
{
printf("Error setting host ready!\r\n");
} else
{
/* Switch on the bus if it is not automatically running (see configuration
options) */
lRet = xChannelBusState( hChannel, CIFX_BUS_STATE_ON, &ulState, 0L);
if(CIFX_NO_ERROR != lRet)
{
printf("Unable to start the filed bus!\r\n");
} else
{

/* Do I/O Data exchange until a key is hit */

while(!kbhit())
{
if(CIFX_NO_ERROR != (lRet = xChannelIORead(hChannel,
0, 0, sizeof(abRecvData),
abRecvData,
IO_WAIT_TIMEOUT)))
{
printf("Error reading IO Data area!\r\n");
break;
} else
{
printf("IORead Data:");
DumpData(abRecvData, sizeof(abRecvData));

if(CIFX_NO_ERROR != (lRet = xChannelIOWrite(hChannel,

0, 0, sizeof(abRecvData),
abRecvData,
IO_WAIT_TIMEOUT)))
{
printf("Error writing to IO Data area!\r\n");
break;
} else
{
printf("IOWrite Data:");
DumpData(abSendData, sizeof(abSendData));

/* Create new output data */

memset(abSendData, ulCycle + 1, sizeof(abSendData));
}
}
}
}
}

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
Simple C-application example 100/118
/* Switch off the bus */
xChannelBusState( hChannel, CIFX_BUS_STATE_OFF, &ulState, 0L);

/* Set Host not ready to stop bus communication */

xChannelHostState(hChannel, CIFX_HOST_STATE_NOT_READY,
&ulState,
HOSTSTATE_TIMEOUT);

/* Close the communication channel */

xChannelClose(hChannel);
}

if(CIFX_NO_ERROR != lRet)
{
char szBuffer[256] = {0};
xDriverGetErrorDescription(lRet, szBuffer, sizeof(szBuffer));
printf(" State = 0x%08X <%s>\r\n", lRet, szBuffer);
} else
{
printf(" State = 0x%08X\r\n", lRet);
}
printf("----------------------------------------------------\r\n");

return lRet;
}

CIFX API | Programming Reference Guide

5.4 Board and channel enumeration

/*****************************************************************************/
/*! Function to demonstrate the board/channel enumeration
* \return CIFX_NO_ERROR on success */
/*****************************************************************************/
void EnumBoardDemo(CIFXHANDLE hDriver)
{
uint32_t ulBoard = 0;
BOARD_INFORMATION tBoardInfo = {0};

printf("---------- Board/Channel enumeration demo ----------\r\n");

/* Iterate over all boards */

while(CIFX_NO_ERROR == xDriverEnumBoards(hDriver, ulBoard, sizeof(tBoardInfo),
&tBoardInfo))
{
uint32_t ulChannel = 0;
CHANNEL_INFORMATION tChannelInfo = {0};

printf("Found Board %.10s\r\n", tBoardInfo.abBoardName);

if(strlen( (char*)tBoardInfo.abBoardAlias) != 0)
printf(" Alias : %.10s\r\n", tBoardInfo.abBoardAlias);
printf(" DeviceNumber : %u\r\n", tBoardInfo.tSystemInfo.ulDeviceNumber);
printf(" SerialNumber : %u\r\n", tBoardInfo.tSystemInfo.ulSerialNumber);
printf(" Board ID : %u\r\n", tBoardInfo.ulBoardID);
printf(" System Error : 0x%08X\r\n", tBoardInfo.ulSystemError);
printf(" Channels : %u\r\n", tBoardInfo.ulChannelCnt);
printf(" DPM Size : %u\r\n", tBoardInfo.ulDpmTotalSize);

CIFX API | Programming Reference Guide

6 General protocol stack handling

This chapter describes the general usage of the CIFX API in conjunction with a fieldbus protocol
stack.

6.1 Overview
Driver Initialization Optional: Board and Channel Enumeration

xDriverOpen()
xDriverEnumBoards()

xDriverEnumChannels()
Channel Handling - Channel Open

xChannelOpen()
Optional: Reading Board Information

xChannelHostState() xSysdeviceOpen()
- CIFX_HOST_STATE_READY

xChannelConfigLock() xSysdeviceInfo()
- CIFX_CONFIGURATION_UNLOCK

xSysdeviceClose()

Stack Configuration
Optional: Open PLC Memory Pointer for PLC Functions

xChannelPLCMemoryPtr(...CIFX_MEM_PTR_OPEN...)

Channel Handling - Activate BUS Communication

xChannelConfigLock()
- CIFX_CONFIGURATION_LOCK

xChannelBusState()
- CIFX_BUS_STATE_ON

Cyclic Data Transfer

Channel Handling - Close Channel

xChannelBusState()
-CIFX_BUS_STATE_OFF

xChannelConfigLock()
- CIFX_CONFIGURATION_UNLOCK

xChannelHostState()
- CIFX_HOST_STATE_NOT_READY
Optional: Close PLC Memory Pointer for PLC Functions

xChannelPLCMemoryPtr( ..CIFX_MEM_PTR_CLOSE..)
xChannelClose()

Driver De-initialization

xDriverClose()

CIFX API | Programming Reference Guide

Driver Initialization

 xDriverOpen() Open the Driver

Reading Driver Information (Optional)

 xDriverEnumBoards() Enumerate all available Boards
 xDriverEnumChannels() Enumerate channels on a given board
Reading Board Information (Optional)
 xSysdeviceOpen() Open the system device of a board
 xSysdeviceInfo() Read board information board via system channel
 xSysdeviceClose() Close the system channel

Channel Handling - Open Channel

 xChannelOpen() Open a communication channel

 Optional: Read the channel I/O memory pointers if the PLC functions xChannelPLC... are
used for I/O data transfer
xChannelPLCMemoryPtr(...CIFX_PLC_MEM_PTR_OPEN...)
 xChannelHostState(...CIFX_HOST_STATE_READY...) Signal Application is online
Wait until channel is READY if the timeout <> 0
Standard Timeout = 1000ms
 xChannelConfigLock(CIFX_CONFIGURATION_UNLOCK) Unlock the configuration

==> Stack Configuration

Channel Handling - Activate BUS Communication

 xChannelConfigLock(...CIFX_CONFIGURATION_LOCK...) Locking of the configuration

 xChannelBusState(...CIFX_BUS_STATE_ON...) Switch BUS to ON
Timeout <> 0, waits until BUS is ON
Standard Timeout: 5000ms

CIFX API | Programming Reference Guide

==> Cyclic Data Transfer

Channel Handling - Close Channel

 xChannelBusState(...CIFX_BUS_STATE_OFF...) Switch off BUS Communication

Timeout <> 0, the function waits until the BUS is OFF
Standard Timeout: 5000ms
 xChannelConfigLock(...CIFX_CONFIGURATION_UNLOCK...) Unlock the Configuration
Unlock the configuration for further changes
 xChannelHostState(...CIFX_HOST_STATE_NOT_READY...) User Application Closed
Signal the protocol stack, no application is online
 xChannelClose() Close Channel

Driver De-initialization

 xDriverClose() Close the cifX Driver

CIFX API | Programming Reference Guide

6.2 Protocol stack configuration

Stack Configuration
Master Protocol Stack Slave Protocol Stack

via rcX Packet via Database (.NXD) via rcX Packet via Database (.NXD)

Send configuration packet

xChannelReset() xChannelDownload() xChannelDownload()
to the protocol stack

Send configuration packet

to the protocol stack

Send bus parameter to

xChannelReset() xChannelReset() xChannelReset()
the protocol stack

Master Stack Configuration - via rcX Packet

 xChannelReset(...CIFX_CHANNELINIT...) Deactivate actual configuration

Maximum Timeout: 10000ms
 Send configuration
This is described in the protocol API manual
 Send Bus Parameter
This is described in the protocol API manual
Configuration is activated automatically after writing the BUS parameters

Master Stack Configuration - via Database

 xChannelDownload(...DOWNLOAD_CONFIGURATION...) Download a database

 xChannelReset(...CIFX_CHANNELINIT...) Activate actual configuration
Maximum Timeout: 10000ms

Slave Stack Configuration: via rcX Packets

 Send configuration data

 xChannelReset(...CIFX_CHANNELINIT...) Activate the configuration
Maximum Timeout: 10000ms
 Optional: Set watchdog time (RCX_SET_WATCHDOG_TIME_REQ) via xChannelPutPacket() /
xChannelGetPacket() )
Standard Put/GetPacket() Timeout: 1000ms

CIFX API | Programming Reference Guide

 xChannelDownload(...DOWNLOAD_CONFIGURATION...) Download a database

 xChannelReset(...CIFX_CHANNELINIT...) Activate actual configuration
Maximum Timeout: 10000ms

CIFX API | Programming Reference Guide

6.3 Cyclic data exchange

Cyclic Data Exchange

xChannelWatchDog(...CIFX_WATCHDOG_START...)

I/O Read / Write PLC Functions

xChannelPLCWriteReady() xChannelPLCReadReady()

xChannelIORead()
xChannelIOWrite() Write output data directly to the Read input data directly from the
cards DPM cards DPM

xChannelPLCActivateWrite() xChannelPLCActivateRead()

Cyclic end?

yes

xChannelWatchDog(...CIFX_WATCHDOG_STOP...)

Activate / Trigger Watchdog

 xChannelWatchdog (...CIFX_WATCHDOG_START...) Activate/Trigger Watchdog

 Note: xChannelWatchdog() must be called, with the parameter CIFX_WATCHDOG_START,
within the configured watchdog time.

Using I/O Read/Write Functions

 xChannelIORead() / xChannelIOWrite() Read / Write I/O Data

Using PLC Functions

 xChannelPLCIsWriteReady() / xChannelPLCIsReadReady() Use PLC Functions

Check if DPM access is allowed
 .... Read / Write data from/to the DPM I/O image areas
 xChannelPLCActivateRead() / xChannelPLCActivateWrite() Activate I/O Data Transfer
Activate data transfer (DPM is switched to hardware)

Deactivate Watchdog

 xChannelWatchdog (...CIFX_WATCHDOG_STOP...) Deactivate Watchdog

CIFX API | Programming Reference Guide

7 Error codes
Error code Symbol / Description
0x00000000 CIFX_NO_ERROR
No error

0x800Axxxx General error codes

Error code Symbol / Description

0x800A0001 CIFX_INVALID_POINTER
Invalid pointer (e.g. NULL was passed to the function)
0x800A0002 CIFX_INVALID_BOARD
No board with the given name / index available
0x800A0003 CIFX_INVALID_CHANNEL
No channel with the given index available
0x800A0004 CIFX_INVALID_HANDLE
An invalid handle was passed to the function
0x800A0005 CIFX_INVALID_PARAMETER
Invalid parameter passed to the function
0x800A0006 CIFX_INVALID_COMMAND
Command parameter is invalid
0x800A0007 CIFX_INVALID_BUFFERSIZE
The supplied buffer does not match the expected size
0x800A0008 CIFX_INVALID_ACCESS_SIZE
Invalid access size (e.g. I/O area size is exceeded by given offset and length)
0x800A0009 CIFX_FUNCTION_FAILED
Generic function failure
0x800A000A CIFX_FILE_OPEN_FAILED
A file could not be opened
0x800A000B CIFX_FILE_SIZE_ZERO
File size is zero
0x800A000C CIFX_FILE_LOAD_INSUFF_MEM
Insufficient memory to load file a file to RAM
0x800A000E CIFX_FILE_READ_ERROR
Error reading file data
0x800A000F CIFX_FILE_TYPE_INVALID
The given file is invalid for the operation
0x800A0010 CIFX_FILE_NAME_INVALID
Invalid filename given
0x800A0011 CIFX_FUNCTION_NOT_AVAILABLE
Function is not available on the driver
0x800A0012 CIFX_BUFFER_TOO_SHORT
The passed buffer is too short to receive all of the requested data

CIFX API | Programming Reference Guide

Error code Symbol / Description

0x800A0013 CIFX_MEMORY_MAPPING_FAILED
Error mapping the dual port memory for later memory access
0x800A0014 CIFX_NO_MORE_ENTRIES
No more entries available. Returned by enumeration functions (e.g. xDriverEnumBoards(),
directories etc.)
0x800A0015 CIFX_CALLBACK_MODE_UNKNOWN
Unknown callback handling mode
0x800A0016 CIFX_CALLBACK_CREATE_EVENT_FAILED
Failed to create callback events
0x800A0017 CIFX_CALLBACK_CREATE_RECV_BUFFER
Failed to create callback receive buffer
0x800A0018 CIFX_CALLBACK_ALREADY_USED
Another application has already registered a callback for the given event
0x800A0019 CIFX_CALLBACK_NOT_REGISTERED
A callback was not registered before
0x800A001A CIFX_INTERRUPT_DISABLED
Device interrupt is disabled. The executed function expects an enabled hardware interrupt
(depending on the driver this must be done either by the device configuration or driver setup
program).
Table 18: General Error Codes

0x800Bxxxx Driver-related error codes

Error code Symbol / Description
0x800B0001 CIFX_DRV_NOT_INITIALIZED
Driver was not correctly initialized during startup or driver is already closed
0x800B0002 CIFX_DRV_INIT_STATE_ERROR
Initialization state error. Hardware does not show correct or expected states and information in the
DPM after a reset or boot start
0x800B0003 CIFX_DRV_READ_STATE_ERROR
Driver read state error
0x800B0004 CIFX_DRV_CMD_ACTIVE
The called function is in use by another program instance or application
0x800B0005 CIFX_DRV_DOWNLOAD_FAILED
General error during download (e.g. bootloader could not be downloaded or started)
0x800B0006 CIFX_DRV_WRONG_DRIVER_VERSION
Wrong driver version
0x800B0030 CIFX_DRV_DRIVER_NOT_LOADED
CIFX driver is not loaded / running. Failed to open or start the driver, returned by xDriverOpen()
0x800B0031 CIFX_DRV_INIT_ERROR
Failed to initialize the driver
0x800B0032 CIFX_DRV_CHANNEL_NOT_INITIALIZED
Channel not initialized (e.g. xChannelOpen() not called)

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
Error codes 110/118
0x800Bxxxx Driver-related error codes
Error code Symbol / Description
0x800B0033 CIFX_DRV_IO_CONTROL_FAILED
Function call into the driver failed
(e.g. used by the Windows API DLL to signal problems in IO-Control driver calls)
0x800B0034 CIFX_DRV_NOT_OPENED
Driver was not opened by calling xDriverOpen()
Table 19: Driver-related error codes

0x800Cxxxx Device / Communication-related error codes

Error code Symbol / Description
0x800C0010 CIFX_DEV_DPM_ACCESS_ERROR
Dual port memory not accessible (e.g. board not found, wrong dual port memory content)
0x800C0011 CIFX_DEV_NOT_READY
Device is not ready (NSF_READY or NCF_READY flag is not set)
The system device or communication channel is not working
0x800C0012 CIFX_DEV_NOT_RUNNING
Device is not running (NCF_RUNNING flag is not set). The communication channel is not configured
0x800C0013 CIFX_DEV_WATCHDOG_FAILED
Watchdog test failed
0x800C0015 CIFX_DEV_SYSERR
Error in handshake flags
0x800C0016 CIFX_DEV_MAILBOX_FULL
Send mailbox is full. The PutPacket() function was not able to write a packet to the device mailbox.
Either the mailbox state does not show empty or no more resources on the device available.
(NSF_SEND_MBX_ACK / HSF_SEND_MBX_CMD or NCF_SEND_MBX_ACK /
HCF_SEND_MBX_CMD flags in wrong state or mailbox counter usPackagesAccepted = 0)
0x800C0017 CIFX_DEV_PUT_TIMEOUT
Send packet timeout. The PutPacket() function was not able to write a packet to the device mailbox
and the wait time in PutPacket() has expired. Either the mailbox state does not show empty or no
more resources on the device available.
(NSF_SEND_MBX_ACK / HSF_SEND_MBX_CMD or NCF_SEND_MBX_ACK /
HCF_SEND_MBX_CMD flags in wrong state or mailbox counter usPackagesAccepted = 0)
0x800C0018 CIFX_DEV_GET_TIMEOUT
Receive packet timeout. GetPacket() function was not able to read a packet from the device and the
wait time in GetPacket() has expired. Either the mailbox state does not show a packet available or
the device has not sent a packet.
(NSF_RECV_MBX_CMD / HSF_RECV_MBX_ACK or NCF_RECV_MBX_CMD /
HCF_RECV_MBX_ACK flags in wrong state or mailbox counter usWaitingPackages = 0)
0x800C0019 CIFX_DEV_GET_NO_PACKET
No packet available. The GetPacket() function was called with timeout = 0 and the function was not
able to read a packet from the device. Either the mailbox state does not show a packet available or
the device has not sent a packet.
(NSF_RECV_MBX_CMD / HSF_RECV_MBX_ACK or NCF_RECV_MBX_CMD /
HCF_RECV_MBX_ACK flags in wrong state or mailbox counter usWaitingPackages = 0)

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
Error codes 111/118
0x800Cxxxx Device / Communication-related error codes
Error code Symbol / Description
0x800C001A CIFX_DEV_MAILBOX_TOO_SHORT
Mailbox is to short for the given packet. The packet send by PutPacket() does not fit into the mailbox.
0x800C0020 CIFX_DEV_RESET_TIMEOUT
Reset command timeout. The device was not reaching READY state, in the given reset timeout, after
the application has initiated a reset (RCX_COMM_COS_READY flag not set).
0x800C0021 CIFX_DEV_NO_COM_FLAG
Communication flag not set. The fieldbus protocol stack has no communication to the fieldbus
devices. Either the cable is disconnected or no other device is connected to the wire
(NCF_COMMUNICATING flag not set).
0x800C0022 CIFX_DEV_EXCHANGE_FAILED
I/O data exchange failed. Function xChannelIORead() or xChannelIOWrite() fails, because the
device does not allow to access the I/O data image.
(NCF_PDIN / NCF_PDOUT flags are not in the state allowing access to the I/O process data image)
0x800C0023 CIFX_DEV_EXCHANGE_TIMEOUT
I/O data exchange timeout. The given timeout in xChannelIORead() / xChannelIOWrite() expires
while the function is waiting to get access to the process data image.
(NCF_PDIN / NCF_PDOUT flags are not in the state allowing access to the I/O process data image)
0x800C0024 CIFX_DEV_COM_MODE_UNKNOWN
Unknown I/O data exchange mode (mode is not within 0..5)
0x800C0025 CIFX_DEV_FUNCTION_FAILED
Device function failed
0x800C0026 CIFX_DEV_DPMSIZE_MISMATCH
DPM size differs from configuration, The firmware signals a communication channel size which does
not fit into the maximum DPM size defined by the hardware or defined by the user.
0x800C0027 CIFX_DEV_STATE_MODE_UNKNOWN
Unknown state mode
0x800C0028 CIFX_DEV_HW_PORT_IS_USED
Device is accessed either by another application or another instance.
- Driver / device can't be unloaded, open connection to the system device or a communication
channels still active
- xChannelOpen() can't be executed because it is currently used by another application
0x800C0029 CIFX_DEV_CONFIG_LOCK_TIMEOUT
Failed lock the communication channels configuration within the given time. xChannelConfigLock()
wait time expired (RCX_COMM_COS_CONFIG_LOCKED flag not set).
0x800C002A CIFX_DEV_CONFIG_UNLOCK_TIMEOUT
Failed to unlock the communication channel configuration within the given time.
xChannelConfigLock() wait time expired (RCX_COMM_COS_CONFIG_LOCKED flag not cleared)
0x800C002B CIFX_DEV_HOST_STATE_SET_TIMEOUT
Wait time expires during xChannelHostState() without reaching CIFX_HOST_STATE_READY.
(The function was not able to set the RCX_APP_COS_APP_READY flag or the device has not
acknowledged the new status in time)
0x800C002C CIFX_DEV_HOST_STATE_CLEAR_TIMEOUT
Wait time expires during xChannelHostState() without reaching CIFX_HOST_STATE_NOT_READY
(The function was not able to clear the RCX_APP_COS_APP_READY flag or the device has not
acknowledged the new status in time)

CIFX API | Programming Reference Guide

DOC121201PR05EN | Revision 5 | English | 2018-08 | Released | Public © Hilscher, 2012-2018
Error codes 112/118
0x800Cxxxx Device / Communication-related error codes
Error code Symbol / Description
0x800C002D CIFX_DEV_INITIALIZATION_TIMEOUT
Timeout during device / channel initialization
0x800C002E CIFX_DEV_BUS_STATE_ON_TIMEOUT
Wait time expires during xChannelBusState() without reaching CIFX_BUS_STATE_ON
(RCX_COMM_COS_BUS_ON flag not set)
Using a timeout, the function will activate fieldbus communication and waits until communication to
another fieldbus device is available (NCF_COMMUNICATION flag is set)
0x800C002F CIFX_DEV_BUS_STATE_OFF_TIMEOUT
Wait time expires during xChannelBusState() without reaching CIFX_BUS_STATE_OFF.
(The function was not able to clear the RCX_APP_COS_BUS_ON flag or the device has not
acknowledged the new status in time and still signals bus communication is active by
RCX_COM_COS_BUS_ON).
0x800C0040 CIFX_DEV_MODULE_ALREADY_RUNNING
Firmware module (NXO) download and start failed because a module is already running
0x800C0041 CIFX_DEV_MODULE_ALREADY_EXISTS
Firmware module (NXO) download was skipped because the module already exists
0x800C0050 CIFX_DEV_DMA_INSUFF_BUFFER_COUNT
Number of configured DMA buffers insufficient (at least 8 buffers are expected)
Or xChannelDMAState() is used without previously configured DMA buffers.
0x800C0051 CIFX_DEV_DMA_BUFFER_TOO_SMALL
DMA buffers size too small (min size 256Byte)
0x800C0052 CIFX_DEV_DMA_BUFFER_TOO_BIG
DMA buffers size too big (max size 63,75KByte)
0x800C0053 CIFX_DEV_DMA_BUFFER_NOT_ALIGNED
DMA buffer alignment failed (must be 256Byte)
0x800C0054 CIFX_DEV_DMA_HANSHAKEMODE_NOT_SUPPORTED
I/O process data exchange mode "uncontrolled" not allowed when DMA transfer is activated
0x800C0055 CIFX_DEV_DMA_IO_AREA_NOT_SUPPORTED
I/O process data area index in DMA mode not supported (only area 0 possible)
0x800C0056 CIFX_DEV_DMA_STATE_ON_TIMEOUT
Failed to set DMA transfer to "ON" within the given wait time in xChannelDMAState().
(The device has not acknowledged the new status or not set the RCX_COM_COS_DMA flag)
0x800C0057 CIFX_DEV_DMA_STATE_OFF_TIMEOUT
Failed to set DMA transfer to "OFF" within the given wait time in xChannelDMAState().
(The device has not acknowledged the new status or not cleared the RCX_COM_COS_DMA flag)
0x800C0058 CIFX_DEV_SYNC_STATE_INVALID_MODE
Device is in invalid mode for the command initiated by xChannelSyncState().
The mode must be either "SYNC Host Controlled" (RCX_SYNC_MODE_HST_CTRL) or "SYNC
Device Controlled" (RCX_SYNC_MODE_DEV_CTRL)
0x800C0059 CIFX_DEV_SYNC_STATE_TIMEOUT
Wait time expired during xChannelSyncState(..,CIFX_SYNC_WAIT_CMD, ).
Device does not signal the expected synchronization handshake flag state
Table 20: Device / Communication-related error codes

CIFX API | Programming Reference Guide

8 Appendix
8.1 List of tables
Table 1: List of revisions...................................................................................................................................................... 4
Table 2: Terms, abbreviations and definitions ..................................................................................................................... 5
Table 3: References to documents ..................................................................................................................................... 5
Table 4: List of API functions – Driver functions .................................................................................................................. 8
Table 5: List of API functions – System Device functions.................................................................................................... 8
Table 6: List of API functions – Communication Channel functions .................................................................................. 10
Table 7: Driver functions ................................................................................................................................................... 14
Table 8: System Device functions ..................................................................................................................................... 15
Table 9: Communication Channel functions ...................................................................................................................... 17
Table 10: Driver information structure ............................................................................................................................... 18
Table 11: Board information structure ............................................................................................................................... 18
Table 12: System channel information .............................................................................................................................. 19
Table 13: System channel info block ................................................................................................................................. 19
Table 14: System Channel - Channel Info Block ............................................................................................................... 20
Table 15: System channel control block ............................................................................................................................ 20
Table 16: System channel status block ............................................................................................................................. 20
Table 17: Channel information structure ........................................................................................................................... 21
Table 18: General Error Codes ....................................................................................................................................... 109
Table 19: Driver-related error codes ............................................................................................................................... 110
Table 20: Device / Communication-related error codes .................................................................................................. 112

8.2 List of figures

Figure 1: CIFX API components .......................................................................................................................................... 6
Figure 2: Component Overview for netX applications ......................................................................................................... 7
Figure 3: Data Exchange Mode: Buffered Host Controlled I/O .......................................................................................... 84
Figure 4: Data Exchange Mode: Buffered Device Controlled I/O ...................................................................................... 85
Figure 5: Bus synchronization notifications ....................................................................................................................... 87

CIFX API | Programming Reference Guide

8.3 Legal notes

All rights reserved.
The images, photographs and texts in the accompanying materials (in the form of a user's manual,
operator's manual, Statement of Work document and all other document types, support texts,
documentation, etc.) are protected by German and international copyright and by international
trade and protective provisions. Without the prior written consent, you do not have permission to
duplicate them either in full or in part using technical or mechanical methods (print, photocopy or
any other method), to edit them using electronic systems or to transfer them. You are not permitted
to make changes to copyright notices, markings, trademarks or ownership declarations.
Illustrations are provided without taking the patent situation into account. Any company names and
product designations provided in this document may be brands or trademarks by the
corresponding owner and may be protected under trademark, brand or patent law. Any form of
further use shall require the express consent from the relevant owner of the rights.

Important notes

Utmost care was/is given in the preparation of the documentation at hand consisting of a user's
manual, operating manual and any other document type and accompanying texts. However, errors
cannot be ruled out. Therefore, we cannot assume any guarantee or legal responsibility for
erroneous information or liability of any kind. You are hereby made aware that descriptions found
in the user's manual, the accompanying texts and the documentation neither represent a
guarantee nor any indication on proper use as stipulated in the agreement or a promised attribute.
It cannot be ruled out that the user's manual, the accompanying texts and the documentation do
not completely match the described attributes, standards or any other data for the delivered
product. A warranty or guarantee with respect to the correctness or accuracy of the information is
not assumed.
We reserve the right to modify our products and the specifications for such as well as the
corresponding documentation in the form of a user's manual, operating manual and/or any other
document types and accompanying texts at any time and without notice without being required to
notify of said modification. Changes shall be taken into account in future manuals and do not
represent an obligation of any kind, in particular there shall be no right to have delivered
documents revised. The manual delivered with the product shall apply.
Under no circumstances shall Hilscher Gesellschaft für Systemautomation mbH be liable for direct,
indirect, ancillary or subsequent damage, or for any loss of income, which may arise after use of
the information contained herein.

CIFX API | Programming Reference Guide

Liability disclaimer

The hardware and/or software was created and tested by Hilscher Gesellschaft für
Systemautomation mbH with utmost care and is made available as is. No warranty can be
assumed for the performance or flawlessness of the hardware and/or software under all application
conditions and scenarios and the work results achieved by the user when using the hardware
and/or software. Liability for any damage that may have occurred as a result of using the hardware
and/or software or the corresponding documents shall be limited to an event involving willful intent
or a grossly negligent violation of a fundamental contractual obligation. However, the right to assert
damages due to a violation of a fundamental contractual obligation shall be limited to contract-
typical foreseeable damage.
It is hereby expressly agreed upon in particular that any use or utilization of the hardware and/or
software in connection with
 Flight control systems in aviation and aerospace;
 Nuclear fission processes in nuclear power plants;
 Medical devices used for life support and
 Vehicle control systems used in passenger transport
shall be excluded. Use of the hardware and/or software in any of the following areas is strictly
prohibited:
 For military purposes or in weaponry;
 For designing, engineering, maintaining or operating nuclear systems;
 In flight safety systems, aviation and flight telecommunications systems;
 In life-support systems;
 In systems in which any malfunction in the hardware and/or software may result in physical
injuries or fatalities.
You are hereby made aware that the hardware and/or software was not created for use in
hazardous environments, which require fail-safe control mechanisms. Use of the hardware and/or
software in this kind of environment shall be at your own risk; any liability for damage or loss due to
impermissible use shall be excluded.

CIFX API | Programming Reference Guide

Warranty

Hilscher Gesellschaft für Systemautomation mbH hereby guarantees that the software shall run
without errors in accordance with the requirements listed in the specifications and that there were
no defects on the date of acceptance. The warranty period shall be 12 months commencing as of
the date of acceptance or purchase (with express declaration or implied, by customer's conclusive
behavior, e.g. putting into operation permanently).
The warranty obligation for equipment (hardware) we produce is 36 months, calculated as of the
date of delivery ex works. The aforementioned provisions shall not apply if longer warranty periods
are mandatory by law pursuant to Section 438 (1.2) BGB, Section 479 (1) BGB and Section 634a
(1) BGB [Bürgerliches Gesetzbuch; German Civil Code] If, despite of all due care taken, the
delivered product should have a defect, which already existed at the time of the transfer of risk, it
shall be at our discretion to either repair the product or to deliver a replacement product, subject to
timely notification of defect.
The warranty obligation shall not apply if the notification of defect is not asserted promptly, if the
purchaser or third party has tampered with the products, if the defect is the result of natural wear,
was caused by unfavorable operating conditions or is due to violations against our operating
regulations or against rules of good electrical engineering practice, or if our request to return the
defective object is not promptly complied with.

Costs of support, maintenance, customization and product care

Please be advised that any subsequent improvement shall only be free of charge if a defect is
found. Any form of technical support, maintenance and customization is not a warranty service, but
instead shall be charged extra.

Additional guarantees

Although the hardware and software was developed and tested in-depth with greatest care,
Hilscher Gesellschaft für Systemautomation mbH shall not assume any guarantee for the suitability
thereof for any purpose that was not confirmed in writing. No guarantee can be granted whereby
the hardware and software satisfies your requirements, or the use of the hardware and/or software
is uninterruptable or the hardware and/or software is fault-free.
It cannot be guaranteed that patents and/or ownership privileges have not been infringed upon or
violated or that the products are free from third-party influence. No additional guarantees or
promises shall be made as to whether the product is market current, free from deficiency in title, or
can be integrated or is usable for specific purposes, unless such guarantees or promises are
required under existing law and cannot be restricted.

CIFX API | Programming Reference Guide

Confidentiality

The customer hereby expressly acknowledges that this document contains trade secrets,
information protected by copyright and other patent and ownership privileges as well as any related
rights of Hilscher Gesellschaft für Systemautomation mbH. The customer agrees to treat as
confidential all of the information made available to customer by Hilscher Gesellschaft für
Systemautomation mbH and rights, which were disclosed by Hilscher Gesellschaft für
Systemautomation mbH and that were made accessible as well as the terms and conditions of this
agreement itself.
The parties hereby agree to one another that the information that each party receives from the
other party respectively is and shall remain the intellectual property of said other party, unless
provided for otherwise in a contractual agreement.
The customer must not allow any third party to become knowledgeable of this expertise and shall
only provide knowledge thereof to authorized users as appropriate and necessary. Companies
associated with the customer shall not be deemed third parties. The customer must obligate
authorized users to confidentiality. The customer should only use the confidential information in
connection with the performances specified in this agreement.
The customer must not use this confidential information to his own advantage or for his own
purposes or rather to the advantage or for the purpose of a third party, nor must it be used for
commercial purposes and this confidential information must only be used to the extent provided for
in this agreement or otherwise to the extent as expressly authorized by the disclosing party in
written form. The customer has the right, subject to the obligation to confidentiality, to disclose the
terms and conditions of this agreement directly to his legal and financial consultants as would be
required for the customer's normal business operation.

Export provisions

The delivered product (including technical data) is subject to the legal export and/or import laws as
well as any associated regulations of various countries, especially such laws applicable in
Germany and in the United States. The products / hardware / software must not be exported into
such countries for which export is prohibited under US American export control laws and its
supplementary provisions. You hereby agree to strictly follow the regulations and to yourself be
responsible for observing them. You are hereby made aware that you may be required to obtain
governmental approval to export, reexport or import the product.

CIFX API | Programming Reference Guide

8.4 Contacts

Headquarters

Germany
Hilscher Gesellschaft für
Systemautomation mbH
Rheinstrasse 15
65795 Hattersheim
Phone: +49 (0) 6190 9907-0
Fax: +49 (0) 6190 9907-50
E-Mail: [email protected]
Support
Phone: +49 (0) 6190 9907-99
E-Mail: [email protected]

Subsidiaries

China Japan
Hilscher Systemautomation (Shanghai) Co. Ltd. Hilscher Japan KK
200010 Shanghai Tokyo, 160-0022
Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521
E-Mail: [email protected] E-Mail: [email protected]
Support Support
Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521
E-Mail: [email protected] E-Mail: [email protected]

France Korea
Hilscher France S.a.r.l. Hilscher Korea Inc.
69500 Bron Seongnam, Gyeonggi, 463-400
Phone: +33 (0) 4 72 37 98 40 Phone: +82 (0) 31-789-3715
E-Mail: [email protected] E-Mail: [email protected]
Support
Phone: +33 (0) 4 72 37 98 40 Switzerland
E-Mail: [email protected] Hilscher Swiss GmbH
4500 Solothurn
India Phone: +41 (0) 32 623 6633
Hilscher India Pvt. Ltd. E-Mail: [email protected]
Pune, Delhi, Mumbai Support
Phone: +91 8888 750 777 Phone: +49 (0) 6190 9907-99
E-Mail: [email protected] E-Mail: [email protected]

Italy USA
Hilscher Italia S.r.l. Hilscher North America, Inc.
20090 Vimodrone (MI) Lisle, IL 60532
Phone: +39 02 25007068 Phone: +1 630-505-5301
E-Mail: [email protected] E-Mail: [email protected]
Support Support
Phone: +39 02 25007068 Phone: +1 630-505-5301
E-Mail: [email protected] E-Mail: [email protected]

CIFX API | Programming Reference Guide

Evans TB Businessanalytics03 9781292339009
100% (1)
Evans TB Businessanalytics03 9781292339009
334 pages
Quality Assurance Manual For Cpa
No ratings yet
Quality Assurance Manual For Cpa
21 pages
VSX UserGuide Ver705
No ratings yet
VSX UserGuide Ver705
158 pages
Broadcast-Quality Up/Cross/Downconverter: Installation and Operation Manual
No ratings yet
Broadcast-Quality Up/Cross/Downconverter: Installation and Operation Manual
86 pages
Delphi 7 - ASTA v3.0 For Delphi 7 - Manual
No ratings yet
Delphi 7 - ASTA v3.0 For Delphi 7 - Manual
684 pages
ADM2 Reference
No ratings yet
ADM2 Reference
618 pages
Programming FPGAs: Getting Started with Verilog
From Everand
Programming FPGAs: Getting Started with Verilog
Simon Monk
3.5/5 (2)
Fritzing for Inventors: Take Your Electronics Project from Prototype to Product
From Everand
Fritzing for Inventors: Take Your Electronics Project from Prototype to Product
Simon Monk
No ratings yet
EAGLE Management Manual: Industrial ETHERNET Firewall/VPN-System
No ratings yet
EAGLE Management Manual: Industrial ETHERNET Firewall/VPN-System
240 pages
TIB RV Com Reference
No ratings yet
TIB RV Com Reference
338 pages
Cifx Netx Application Programmers Guide XX EN
No ratings yet
Cifx Netx Application Programmers Guide XX EN
53 pages
Inspect Ug
No ratings yet
Inspect Ug
180 pages
VXMLRef 007-02542-0025 R4.21 v01
No ratings yet
VXMLRef 007-02542-0025 R4.21 v01
232 pages
Excel Adding
No ratings yet
Excel Adding
210 pages
VSX UserGuide Ver705 PDF
No ratings yet
VSX UserGuide Ver705 PDF
158 pages
SDK Programming Guide
100% (2)
SDK Programming Guide
606 pages
Tib BW Palette Reference
No ratings yet
Tib BW Palette Reference
748 pages
Mass Frontier 7.0
No ratings yet
Mass Frontier 7.0
430 pages
CANopen_Master_DTM_OI_14_EN
No ratings yet
CANopen_Master_DTM_OI_14_EN
157 pages
Inspect Ug PDF
No ratings yet
Inspect Ug PDF
180 pages
Tib Adadb Concepts
No ratings yet
Tib Adadb Concepts
52 pages
ADADB UserGuide
No ratings yet
ADADB UserGuide
358 pages
Tib BW Palette Reference
No ratings yet
Tib BW Palette Reference
790 pages
Net Customisation User Guide
100% (2)
Net Customisation User Guide
88 pages
Servo Valve
No ratings yet
Servo Valve
29 pages
TIB Emswcf 1.2.0 User
No ratings yet
TIB Emswcf 1.2.0 User
126 pages
Compass Reference
No ratings yet
Compass Reference
206 pages
Map Server
No ratings yet
Map Server
758 pages
Tib Adsbl Configuration and Deployment PDF
No ratings yet
Tib Adsbl Configuration and Deployment PDF
356 pages
ADR3 UserGuide
No ratings yet
ADR3 UserGuide
560 pages
RV Cobol
No ratings yet
RV Cobol
386 pages
KNX Net Ip
No ratings yet
KNX Net Ip
68 pages
Map Server
No ratings yet
Map Server
758 pages
Map Server
No ratings yet
Map Server
758 pages
SYCONnet Netdevice OI 11 EN
No ratings yet
SYCONnet Netdevice OI 11 EN
44 pages
Product Description 7 1 5
No ratings yet
Product Description 7 1 5
138 pages
Tib Bwpluginrestjson Users Guide
No ratings yet
Tib Bwpluginrestjson Users Guide
143 pages
RV Administration
No ratings yet
RV Administration
320 pages
The MapServer Documentation Release 6-4-0
No ratings yet
The MapServer Documentation Release 6-4-0
774 pages
Tecplotsv Ug
No ratings yet
Tecplotsv Ug
60 pages
DB2 REXX Language Support PDF
No ratings yet
DB2 REXX Language Support PDF
26 pages
Tib RV CPP Reference
No ratings yet
Tib RV CPP Reference
422 pages
Tib Ems Users Guide
No ratings yet
Tib Ems Users Guide
528 pages
Hawk Admin
50% (2)
Hawk Admin
374 pages
VSP Provisioning Guide For Open Systems
No ratings yet
VSP Provisioning Guide For Open Systems
650 pages
Tib Ems Users Guide
No ratings yet
Tib Ems Users Guide
382 pages
GNU Wget 1.15
No ratings yet
GNU Wget 1.15
70 pages
Tib Ems Users Guide
100% (1)
Tib Ems Users Guide
414 pages
CandleScanner User Guide 4.0.3
No ratings yet
CandleScanner User Guide 4.0.3
92 pages
Tib Designer Palettes
No ratings yet
Tib Designer Palettes
271 pages
PCNSE 8.1 - Study - Guide - 2018.07
0% (1)
PCNSE 8.1 - Study - Guide - 2018.07
196 pages
Tib Adadb Concepts
No ratings yet
Tib Adadb Concepts
66 pages
Tib Adfiles Examples
No ratings yet
Tib Adfiles Examples
126 pages
IBM Netcool Impact 7.1 Best Practices v1.0-FIRST-EDITION1
No ratings yet
IBM Netcool Impact 7.1 Best Practices v1.0-FIRST-EDITION1
78 pages
PHP The Right Way
No ratings yet
PHP The Right Way
51 pages
swb_ug
No ratings yet
swb_ug
238 pages
Programming the Photon: Getting Started with the Internet of Things
From Everand
Programming the Photon: Getting Started with the Internet of Things
Christopher Rush
5/5 (1)
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
From Everand
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
Christopher Rush
5/5 (1)
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet
Facility Management: Business Process Integration
From Everand
Facility Management: Business Process Integration
Alexander Redlein
No ratings yet
Teardowns: Learn How Electronics Work by Taking Them Apart
From Everand
Teardowns: Learn How Electronics Work by Taking Them Apart
Bryan Bergeron
No ratings yet
Benefits of semantic data models. A study in the European goods transport industry
From Everand
Benefits of semantic data models. A study in the European goods transport industry
Andreas A. Pelekies
No ratings yet
Pollution Prevention: Methodology, Technologies and Practices
From Everand
Pollution Prevention: Methodology, Technologies and Practices
Kenneth L. Mulholland
No ratings yet
Support Through The Website: ™ Electrical Connections I/O Connections
No ratings yet
Support Through The Website: ™ Electrical Connections I/O Connections
2 pages
Matrix 120 Reference Manual PDF
No ratings yet
Matrix 120 Reference Manual PDF
188 pages
Solution Guide Tires - English
No ratings yet
Solution Guide Tires - English
24 pages
In-Sight 2000 Series Vision Sensor: Reference Guide
No ratings yet
In-Sight 2000 Series Vision Sensor: Reference Guide
54 pages
Hirschmann Catalogue
No ratings yet
Hirschmann Catalogue
116 pages
In-Sight 7600/7800 Series Vision System: Manual
No ratings yet
In-Sight 7600/7800 Series Vision System: Manual
92 pages
SMA Custom Objects: Object Instantiation
No ratings yet
SMA Custom Objects: Object Instantiation
5 pages
Studio HST Object
No ratings yet
Studio HST Object
8 pages
Task Toolkit Manual For Indusoft Web Studio V6.1+Sp3
No ratings yet
Task Toolkit Manual For Indusoft Web Studio V6.1+Sp3
28 pages
Technical Note - Indusoft Web Studio Limits: Task Number of Worksheets Number of Rows Per Worksheet Remarks
No ratings yet
Technical Note - Indusoft Web Studio Limits: Task Number of Worksheets Number of Rows Per Worksheet Remarks
1 page
Technical Note - SNMP Interface October 30th, 2011 - Rev. B
No ratings yet
Technical Note - SNMP Interface October 30th, 2011 - Rev. B
8 pages
Twincat Remote Communication From Wince Devices
No ratings yet
Twincat Remote Communication From Wince Devices
6 pages
Smart Self-Powered Serial Converter: 1203-SSS (Series B) FRN 3.xxx
No ratings yet
Smart Self-Powered Serial Converter: 1203-SSS (Series B) FRN 3.xxx
60 pages
Indusoft Thin Client Setup and Troubleshooting Guide: Before You Begin
No ratings yet
Indusoft Thin Client Setup and Troubleshooting Guide: Before You Begin
7 pages
Compact 16-Point 24V DC Sink/Source High-Speed Input Module: Installation Instructions
No ratings yet
Compact 16-Point 24V DC Sink/Source High-Speed Input Module: Installation Instructions
16 pages
440L Guardshield Type 4 Light Curtains Used On Plastics
No ratings yet
440L Guardshield Type 4 Light Curtains Used On Plastics
44 pages
AB Compact Logix User Manual
No ratings yet
AB Compact Logix User Manual
324 pages
1489 Circuit Breaksers
No ratings yet
1489 Circuit Breaksers
18 pages
0 D768 A8 BD 01
No ratings yet
0 D768 A8 BD 01
4 pages
PPSC Asistent
No ratings yet
PPSC Asistent
2 pages
Ohana, Josh - Resume
No ratings yet
Ohana, Josh - Resume
3 pages
Bayesian Inference For Kendall S Rank Correlation Coefficient
No ratings yet
Bayesian Inference For Kendall S Rank Correlation Coefficient
7 pages
Viva Questions For SQL & Java For STD 12 QUESTIONS
No ratings yet
Viva Questions For SQL & Java For STD 12 QUESTIONS
5 pages
Changing School Management
No ratings yet
Changing School Management
54 pages
APM2018
No ratings yet
APM2018
26 pages
MarketScreenerUserGuide PDF
No ratings yet
MarketScreenerUserGuide PDF
15 pages
AP 8 BOL - PDF Version 1
No ratings yet
AP 8 BOL - PDF Version 1
38 pages
NetApp - Create A New Volume On VFiler (7-Mode) - VNotions
No ratings yet
NetApp - Create A New Volume On VFiler (7-Mode) - VNotions
9 pages
WHT Certificate
No ratings yet
WHT Certificate
1 page
Labus Cont AY 2020 2021
No ratings yet
Labus Cont AY 2020 2021
9 pages
euro-ncap-protocol-crash-avoidance-lane-departure-collisions-v09
No ratings yet
euro-ncap-protocol-crash-avoidance-lane-departure-collisions-v09
39 pages
HSCC - NEIGRIHMS - Shillong Est-E 1 - R1
No ratings yet
HSCC - NEIGRIHMS - Shillong Est-E 1 - R1
11 pages
TOP 21 Oracle Fusion HCM Interview Questions
100% (1)
TOP 21 Oracle Fusion HCM Interview Questions
3 pages
Grade 10 ICSE - Commercial Studies Ch-1 Notes
No ratings yet
Grade 10 ICSE - Commercial Studies Ch-1 Notes
2 pages
Powershell
No ratings yet
Powershell
4 pages
Areas of AICTE Training and Learning (ATAL) Academy FDP's
No ratings yet
Areas of AICTE Training and Learning (ATAL) Academy FDP's
2 pages
Auto Sales in Nepal: Case Study
No ratings yet
Auto Sales in Nepal: Case Study
8 pages
Cyanotype Day 5 Lesson Plan
No ratings yet
Cyanotype Day 5 Lesson Plan
3 pages
20-60-10-mp
No ratings yet
20-60-10-mp
6 pages
Aml Kyc Notice PDF
50% (2)
Aml Kyc Notice PDF
4 pages
mh0302 Mechatronics 2011
No ratings yet
mh0302 Mechatronics 2011
4 pages
Online PPT Entrepreneurship Unit 1
No ratings yet
Online PPT Entrepreneurship Unit 1
63 pages
Advanced Setup Guide AOS v5 - 19
No ratings yet
Advanced Setup Guide AOS v5 - 19
28 pages
HP LaserJet P2015 Series Printer - Status-Light Patterns - c00763669 - HP Business Support Center
No ratings yet
HP LaserJet P2015 Series Printer - Status-Light Patterns - c00763669 - HP Business Support Center
11 pages
Daily Stock Position
No ratings yet
Daily Stock Position
2 pages
CISD Retail Linkage Pins & Bearing Promo Kit Overview UPDATED
No ratings yet
CISD Retail Linkage Pins & Bearing Promo Kit Overview UPDATED
12 pages