Linear motion system LMS Generic PLC Interface Manual

NYCe 4000

Linear motion systemLMS Generic PLC Interface Manual

ReferenceR911347824

Edition 08

NYCe 4000Linear motion systemLMS Generic PLC Interface Manual

Reference

DOK-NY4000-PLC*IFC*V45-RE08-EN-E

RS-9868b3e6e125748b0a347ea500a5c591-8-en-US-5

Edition Release Date Notes

DOK-NY4000-PLC*IFC*V45-RE01-EN-E 02/2015 First edition 45V02DOK-NY4000-PLC*IFC*V45-RE02-EN-E 07/2015 2nd edition 45V04DOK-NY4000-PLC*IFC*V45-RE03-EN-E 06/2016 3rd edition 45V08DOK-NY4000-PLC*IFC*V45-RE04-EN-E 11/2016 4th edition 45V10DOK-NY4000-PLC*IFC*V45-RE05-EN-E 02/2017 5th edition 45V12DOK-NY4000-PLC*IFC*V45-RE07-EN-E 12/2017 7th edition 45V13DOK-NY4000-PLC*IFC*V45-RE06-EN-E 04/2017 6th edition 45V12 SP1DOK-NY4000-PLC*IFC*V45-RE08-EN-E 03/2018 8th edition 45V14

List of trademarks Microsoft®, Windows 7® and Windows 10® are either registered trademarksor trademarks of Microsoft® Corporation in the United States and/or othercountries.Products in this publication are referred to by their general trade names. Inmost, if not all cases, these designations are claimed as trademarks orregistered trademarks of their respective companies.

Copyright © Bosch Rexroth AG 2018All rights reserved, also regarding any disposal, exploitation, reproduction,editing, distribution, as well as in the event of applications for industrialproperty rights.

Liability The specified data is intended for product description purposes only and shallnot be deemed to be a guaranteed characteristic unless expressly stipulatedin the contract. All rights are reserved with respect to the content of thisdocumentation and the availability of the product.

Published by Bosch Rexroth AGP.O. Box 7170 ■ 5605 JD Eindhoven ■ The Netherlandshttp://www.boschrexroth.com

Title

Type of Documentation

Document Typecode

Internal File Reference

Record of Revision

Bosch Rexroth AG DOK-NY4000-PLC*IFC*V45-RE08-EN-ENYCe 4000 Linear motion system LMS Generic PLC Interface Manual

Table of ContentsPage

1 Generic PLC interface for LMS...................................................................................... 31.1 Introduction............................................................................................................................................. 31.2 Overview................................................................................................................................................. 31.3 Used abbreviations in this manual.......................................................................................................... 5

2 N4k CM Socket Client library......................................................................................... 72.1 Introduction............................................................................................................................................. 72.2 Description N4kCommunication Function Block..................................................................................... 82.2.1 Introduction.......................................................................................................................................... 82.2.2 N4kCommunication Function Block input parameters......................................................................... 82.2.3 N4kCommunication Function Block output parameters...................................................................... 92.3 Description N4kCall Function Block........................................................................................................ 92.3.1 Introduction.......................................................................................................................................... 92.3.2 N4kCall - CM Function Block interface.............................................................................................. 102.4 Description N4kLogger Function Block................................................................................................. 132.4.1 Introduction........................................................................................................................................ 132.4.2 N4kLogger Function Block interface.................................................................................................. 13

3 Client socket communication interface........................................................................ 153.1 TCP/IP client socket interface............................................................................................................... 153.1.1 Introduction........................................................................................................................................ 153.1.2 N4kRequest message....................................................................................................................... 153.1.3 N4kReply message........................................................................................................................... 163.1.4 TCP/IP socket - CM Socket Server interface.................................................................................... 163.2 UDP/IP client socket interface.............................................................................................................. 193.2.1 Introduction........................................................................................................................................ 193.2.2 UDP/IP socket - CM Socket Server interface.................................................................................... 19

4 CM Extension............................................................................................................... 214.1 Introduction........................................................................................................................................... 214.2 Interfaces.............................................................................................................................................. 224.3 How to build the N4kCmExtension DLL................................................................................................ 25

5 Installation package for CM functionality on the PLC.................................................. 27

DOK-NY4000-PLC*IFC*V45-RE08-EN-E Bosch Rexroth AG I/29NYCe 4000 Linear motion system LMS Generic PLC Interface Manual

Table of Contents

Bosch Rexroth AG DOK-NY4000-PLC*IFC*V45-RE08-EN-EII/29NYCe 4000 Linear motion system LMS Generic PLC Interface Manual

1 Generic PLC interface for LMS1.1 Introduction

NYCe 4000 Software LMS supports the PLC programming tool IndraLogic2G using socket communication. The PLC can execute all CM functions andadditional customer-specific functionality (see chapter 4 "CM Extension" onpage 21). The PLC uses the socket communication layer thatcommunicates with the CM Socket Server on the PC. This socketcommunication layer uses IndraLogic-specific PLC libraries to access thesocket interface. See the NYCe 4000 LMS IndraLogic Interface Manual formore information.PLCs other than Bosch Rexroth IndraControl L25, L45, and L65 with theIndraMotion software package can also execute all CM functions, but youhave to implement the socket communication layer (n4kcmsocketclientlibrary) that interfaces to the CM Function Blocks at one side and interfacesto the supplied socket communication interfaces (of the PLC manufacturer) atthe other side.This manual describes the communication interfaces and communicationprotocols between the PLC client and the CM Socket Server

Make sure that the PLC supports little-endian byte storage.

1.2 OverviewThe generic PLC interface to the CM Socket Server architecture is shown infig. 1-1 "Generic PLC architecture" on page 4.

DOK-NY4000-PLC*IFC*V45-RE08-EN-E Bosch Rexroth AG 3/29NYCe 4000 Linear motion system LMS Generic PLC Interface Manual

Generic PLC interface for LMS

application

n4kcmapi.libraryCM Function Blocks

PLC UDP/IPsocket client

PLC

NYCe 4000 API

IEEE 1394bor Ethernet

to NYCe 4000 nodes

“NYCe4000" PC

socket library

TCP/IP server UDP/IP server

CM Socket Server

n4kcommunication n4kcall n4klogger

PLC TCP/IPsocket client

n4kcmsocketclient library

Fig. 1-1: Generic PLC architecture The PLC interface - CM Socket Server connection uses a client-servermodel. ServerThe CM Socket Server executes on the "NYCe4000" PC and handles thecommunication with the PLC. The CM Socket Server interprets the functioncall messages from the PLC, invokes the corresponding NYCe 4000 functionand returns the output arguments to the PLC. The CM Socket Server alsosupports logging error and debug messages from the PLC. ClientThe PLC application can execute CM functions using the CM Socket Server.The N4k CM Socket Client library (n4kcmsocketclient.librarysupplied by Rexroth) has 2 interfaces.

1. The interface with the CM Function Blocks (n4kcmapi.library).

Bosch Rexroth AG DOK-NY4000-PLC*IFC*V45-RE08-EN-E4/29NYCe 4000 Linear motion system LMS Generic PLC Interface Manual


The n4kcmapi.library contains all CM Function Blocks that the PLCapplication can execute, and are available in the NYCe 4000 SoftwareLMS Release.

2. The PLC-specific libraries used to implement the TCP/IP and UDP/IPsocket communication.

The n4kcmsocketclient.library includes the N4kCommunicationFunction Block, N4kCall Function Block, and N4kLogger Function Block andthe PLC-specific socket library to communicate with the PLC. These 3Function Blocks must be implemented. The TCP/IP and UDP/IP socketclients of the PLC must be linked to the n4kcmsocketclient.library.This manual describes the following information.● The Function Block requirements of the n4kcmsocketclient library.● The interface definition of the n4kcmsocketclient library and the socket

communication protocols between the PLC and the CM Socket Server.

1.3 Used abbreviations in this manualThe following table gives a summary of abbreviations used in this manual.

Abbreviation Description

API Application Programming Interface

CM Carrier Management

FB Function Block

IEC 61131-3 IEC standard for PLCs

IP Internet Protocol

LMS Linear Motion System

PLC Programmable Logic Controller

ST Structured Text, IEC 61131-1 programming language

TCP Transmission Control Protocol

UDP User Datagram Protocol

Tab. 1-1: Summary of used abbreviations




2 N4k CM Socket Client library2.1 Introduction

This chapter describes the N4k CM Socket Client library. The LMSapplication on the PLC links the n4kcmsocketclient.library, whichprovides the communication functionality to communicate with the socketserver, NYCeCmSocketServer, using a TCP/IP socket. This mechanismdecouples the PLC application from the (synchronous) execution of thecommand, to maintain the cyclic nature of the PLC program.The n4kcmsocketclient library includes the N4kCall Function Block, theN4kLogger Function Block to log (error) messages and theN4kCommunication Function Block.

The socket communication between the PLC andNYCeCmSocketServer must be operational when CM FunctionBlocks are used in a run-time PLC environment.

A separate task calls the N4kCommunication Function Block to make surethat the socket communication overhead is not part of the main applicationprogram. This N4kCommunication Function Block receives and sends themessages. The application must call the N4kCommunication Function Blockevery 1 ms in a separate task.The N4kCall Function Block stores CM requests in the request queue. TheN4kCommunication Function Block retrieves the pending requests, sends therequests to NYCeCmSocketServer and receives the reply messages fromNYCeCmSocketServer. The replies are stored in the reply queue and areretrieved by the N4kCall Function Block, see fig. 2-1 "Interfaces betweenapplication and n4kcmsocketclient library" on page 7.

N4kCall

requestqueue

replyqueue

N4kLogger

error messages

error messages

N4kCommunication

error messages

application

System libraries

n4kcmsocketclient library

CM Socket Server

Fig. 2-1: Interfaces between application and n4kcmsocketclient library If an error is detected during the processing of the N4kCall Function Block orN4kCommunication Function Block, or in the communication flow fromN4kCall to the System libraries, the error is logged. The log messages areplain text and intended for debugging purposes. The logged messages are


N4k CM Socket Client library

sent to NYCeCmSocketServer when the application program calls theN4kLogMsg instance of the N4kLogger Function Block. The messages arelogged in CM and can be retrieved with NYCeLogger.N4kLogger can queue up to 20 messages. To prevent the loss of messages,the application must call the N4kLogMsg Function Block once every PLCcycle. The application must call the N4kLogMsg Function Block only from onetask.

Messages from CM Function Blocks are logged to the applicationthat has opened the UDP port, thus enables to log the messagesto another (external) logger.

● The N4kCommunication FB is described in chapter 2.2 "Description

N4kCommunication Function Block" on page 8.● The N4kCall FB is described in chapter 2.3 "Description N4kCall

Function Block" on page 9.● The N4kLogger FB is described in chapter 2.4 "Description N4kLogger

Function Block" on page 13.● The socket communication interface is described in chapter 3 "Client

socket communication interface" on page 15.

2.2 Description N4kCommunication Function Block2.2.1 Introduction

The N4kCommunication Function Block is a part of the n4kcmsocketclientlibrary and takes care of the communication between the N4kCall FB andN4kLogger FB at one side and the PLC socket libraries to communicate withthe CM Socket Server at the other side. The N4kCommunication FunctionBlock should be called every 1 ms in a separate task. Before any CMFunction Blocks are used the N4kCommunication Function Block must beactive.

Fig. 2-2: N4kCommunication Function Block

2.2.2 N4kCommunication Function Block input parametersThe following table lists the N4kCommunication Function Block inputparameters with a short description.



Parameter Data type Description

Enable BOOL Flag that indicates the called function must beexecuted when the flag is TRUE.

IpAddress STRING The TCP IP address of NYCeCmSocketServer.

Port INT The TCP IP port number used byNYCeCmSocketServer.

Tab. 2-1: N4kCommunication FB input parameters description The N4kCommunication Function Block is started when the Enable flag isset to TRUE. Before the Enable flag is set to TRUE, you must specify the IPaddress and port number used by NYCeCMSocketServer. During theinitialization of the N4kCommunication Function Block a connection is madeto the NYCeCMSocketServer. If no address is specified(IpAddress = '';), the default IP address 192.168.0.1 is used. If the portnumber is not specified (Port = 0;), the default port 4242 is used. SeeNYCe 4000 LMS IndraLogic Interface Manual for more information aboutNYCeCMSocketServer.

2.2.3 N4kCommunication Function Block output parametersThe following table lists the N4kCommunication Function Block outputparameters with a short description.


InOperation BOOL Connection to NYCeCmSocketServer is active whenflag is TRUE.

Error BOOL Connection to NYCeCmSocketServer is broken whenflag is TRUE.

Tab. 2-2: N4kCommunication FB output parameters description The N4kCommunication Function Block is active when the InOperationflag is set to TRUE. Whenever an error occurs, the Error flag is set. The twoflags are mutually exclusive, only one flag is set at any moment.The initialization takes approximately 10 ms in the condition that theinitialization can complete successfully. However, in error conditions theinitialization can take up to approximately 75 seconds before the Error flagis set TRUE. The application must wait until the InOperation flag or theError flag is set TRUE.

The initialization process is a blocking process. Keep this in mindif your application uses a watchdog function.

2.3 Description N4kCall Function Block2.3.1 Introduction

The N4kCall Function Block is part of the n4kcmsocketclient library. TheN4kCall FB handles the CM function calls. The N4kCall Function Block mustbe called as long as the Function Block is active.The N4kCall FB has the following interfaces.



1. Interface of the CM Function Blocks.2. Interface to N4kCommunication Function Block.

The N4kCall Function Block implementation is generic to the PLC platformand application requirements. The interfaces of N4kCall are according to theIEC 61131-3 specifications. The N4kCall FB can be implemented to supportconcurrent messages from multiple processes in a thread-safe manner usinginternal buffers.

2.3.2 N4kCall - CM Function Block interfaceThe N4kCall Function Block is used by the CM Function Blocks and is shownin fig. 2-3 "N4kCall Function Block" on page 10. The data types of the inputand output arguments of the N4kCall are according to IEC 61131-3.

Fig. 2-3: N4kCall Function Block The tab. 2-3 "N4kCall input arguments" on page 10 lists the inputarguments of the N4kCall interface to the CM Function Block API, theassociated data type and a description.

Argument Data type Description

Execute BOOL Flag that indicates the requested function must be executed by theN4kCall FB only when the flag is TRUE. The detection is based on atransition from FALSE to TRUE.

FunctionName STRING(80) String that identifies the requested function for the CM SocketServer function. The function name must be in uppercasecharacters, and the maximum length is 80 characters.

Timeout UINT Value that specifies the timeout value within which the function mustreturn. The value is specified in ms.

InputBuffer POINTER TO USINT Address (pointer) of the data input buffer.

inputargument-1

inputargument-2

inputargument-n- - - - - - -

Fig. 2-4: Input buffer in memoryThe input buffer is an array of input arguments of the CM functioncall. The arguments and associated data types are specific for eachCM function. The input arguments are stored in consecutivememory locations without any padding as shown in the figure.

SizeIn UINT Size of the data input buffer.




OutputBuffer POINTER TO USINT Address (pointer) of the data output buffer.

outputargument-1

outputargument-2

outputargument-n- - - - - - -return

value

Fig. 2-5: Output buffer in memoryThe output buffer contains the return value and, if defined, thereturn arguments of the CM function call from the N4kCall FunctionBlock. The return value and, if defined, the output arguments arestored in consecutive memory locations without any padding asshown in the figure.

SizeOut UINT Size of the allocated data output buffer.

Tab. 2-3: N4kCall input arguments The tab. 2-4 "N4kCall output arguments" on page 11 lists the return valueand output arguments of the CM Function Block API to the N4kCall interface,the associated data type and a description.


Done BOOL Flag that indicates whether the Function Block executed the requestsuccessfully. The flag is set TRUE if the request is successfullyexecuted. The FB must be called until the Done flag or the Errorflag is TRUE.

Active BOOL Flag that indicates whether the Function Block is active. The flag isset TRUE if the FB is active. The FB must be called as long as theActive flag is TRUE.

Error BOOL The Function Block detected an error if the flag is TRUE. The outputargument ErrorID identifies the error. The FB must be called untilthe Error flag or the Done flag is TRUE.

ErrorID N4K_STATUS Error identification number, only valid when the Error flag is TRUE.

Timedout BOOL Flag that indicates whether the reply of a request timed out. Theflag is set TRUE if the time out occurred.

Tab. 2-4: N4kCall output arguments The flags Done, Active, and Error are mutually exclusive, only one flag isset TRUE at any moment.When the called function returns, the flag Done or the flag Error is set TRUEdepending on the result. Only if the flag Error is set TRUE the outputargument ErrorID contains valid information.The input data is copied in the first PLC cycle, if the flag Execute is TRUE.Any change of the input data during execution of the Function Block isignored. If the flag Execute is set FALSE during the execution of thespecified function, the function continues its execution. Example: CmMoveToPosition● FunctionName: CMMOVETOPOSITION● Input arguments: {



– INT CarrierID– LREAL EndPosition– LREAL Velocity– LREAL Acceleration– LREAL Jerk}

SizeOf(LREAL) SizeOf(LREAL) SizeOf(LREAL)SizeOf(INT)

CarrierID End position Velocity Acceleration JerkSizeOf(LREAL)

Fig. 2-6: Input buffer in memory for the function CmMoveToPosition

● Output argument: {– UDINT NYCE_STATUS}

SizeOf(UDINT)

NYCE_STATUS

Fig. 2-7: Output buffer in memory of the function CmMoveToPosition The tab. 2-5 "N4kCall return status values of the argument ErrorID" on page12 lists the values of the return status, which is of data type N4K_STATUS.The error can be internal to the N4kCall FB, for example when an invalidrequest is received or a time out occurred. The error can also occur if the CMSocket Server failed to execute the requested function.

Return value Value Description

N4K_STATUS_NONE 0 Initial value of the argument.

N4K_STATUS_PROCESSING 1 The N4kCall Function Block is busy processing a request.

N4K_STATUS_READY 2 According to the return value of the CM Socket Server.

N4K_STATUS_ERROR 3 Reply was requested for an inactive message identifier.

N4K_STATUS_TIMEOUT 4 The function did not return within the specified timeout. Thesystem is too busy to execute the request within thespecified time.

N4K_STATUS_EXCEPTION 5 The CM Socket Server generated an exception.

N4K_STATUS_USERTERMINATED 6 No longer used definition.

N4K_STATUS_TOO_MANY_ACTIVE 7 Too many active N4kCall Function Blocks. The maximumnumber of active N4kCall FBs is 40.



Return value Value Description

N4K_STATUS_FAILED 8 ● Size of input or output data does not match expectedspecified size.

● Input or output pointer is NULL.

● Invalid NyceStatus value specified for the functionNYCEGETSTATUSSTRING.

● Invalid ErrorCode value specified for the functionNYCEGETERRORCODESTRING.

● Invalid TrackId value specified for the functionCMREADTRACKDATA.

N4K_STATUS_UNKNOWN_REQUEST 9 The specified function is not known by the CM SocketServer.

N4K_STATUS_INVALID_REQUEST 10 The specified request is badly formatted.

N4K_STATUS_NOT_INITIALIZED 11 The N4kCall Function Block is not active.

N4K_STATUS_INVALID_REPLY 12 The format of the reply message is not as expected.

N4K_STATUS_INVALID_INPUT_DATA 13 Too many data specified, data does not fit in input buffer.

N4K_STATUS_OUT_OF_RESOURCES 14 All communication data buffers are in use.

Tab. 2-5: N4kCall return status values of the argument ErrorID

2.4 Description N4kLogger Function Block2.4.1 Introduction

The N4kLogger Function Block is a part of the n4kcmsocketclient library andhandles log messages from the PLC to the CM Socket Server. Thesemessages are, for example, error logs and debug messages. The logmessages can be used by other NYCe 4000 tools, such as NYCeLogger.The N4kLogger Function Block uses a uni-directional UDP/IP communicationprotocol. The N4kLogger FB has the following interfaces.

1. Interface to log messages.2. Interface UDP/IP socket to CM Socket Server.

The N4kLogger Function Block implementation is specific to the PLC platformand application requirements. The interfaces of N4kLogger are according tothe IEC 61131-3 specifications. The N4kLogger FB can be implemented tosupport concurrent messages from multiple processes in a thread-safemanner using internal buffers.

2.4.2 N4kLogger Function Block interfaceA global instance of the N4kLogger Function Block is available in then4kcmsocketclient.library. This instance, called N4kLogMsg, mustbe called regularly by the application if debug logging is required. TheN4kCommunication program and the N4kCall Function Block use theAddMessage action to log error conditions in the communication flow. Thesemessages are queued internally in N4kLogger, and sent to the server whenthe instance of the Function Block is called.The N4kLogger instance has the following input and output parameters.



Fig. 2-8: N4kLogger Function Block

Parameter Input/output Data type Description

strIPAddress input STRING(80) The UDP IP address ofNYCeCmSocketServer

iPort input UINT The UDP IP port number ofNYCeCmSocketServer

strMsg input STRING(80) The log message

iStatus output INT Status of the N4kLogger0 : initial1 : initializing2 : operational3 : log buffer overflow detected-1 : socket creation failed

Tab. 2-6: N4kLogger instance input and output parameters description If no address is specified (strIPAddress = '';), the default IP address192.168.0.1 is used. If the port number is not specified (iPort = 0;), thedefault port 4242 is used. See NYCe 4000 LMS IndraLogic Interface Manualfor more information about NYCeCMSocketServer.

The input parameters specified in the first call to the N4kLoggerinstance will be used as the server address to which the logmessages are sent.

The N4kLogger Function Block has the actions AddMessage and Reset.The AddMessage action adds a message to the internal queue of theN4kLogger. The queue can hold up to 20 messages. If the queue is full,additional messages are dropped and the return value of iStatus is set to3. The application must call the N4kLogger Function Block to empty thisqueue. The AddMessage action is for internal use, not for the user, andexplained only for understanding of the logging mechanism.


strMsg STRING(80) Message to send to the log server.

Tab. 2-7: AddMessage action input parameter description The Reset action resets the connection to CM. This action is for internal useonly.



3 Client socket communication interface3.1 TCP/IP client socket interface3.1.1 Introduction

The N4kCall - TCP/IP client socket interface specifies the layout of theN4kCall messages communicated between the CM Socket Server and thePLC client using TCP/IP sockets. The CM function call is encapsulated in anN4kRequest message and sent to the CM Socket Server. The CM SocketServer responds with the return value of the function call in an N4kReplymessage.

3.1.2 N4kRequest messageThe N4kRequest message consists of a header and a data field.

N4k Request Header N4k Request Data (maximum 1024 bytes)

Fig. 3-1: N4kRequest message The N4kRequest Header contains the following fields.

Name Data type Size (bytes) Description

uiLength UINT 2This field specifies the total length of the N4kRequest message. The totallength is the byte count of the N4k Request Header and the N4k RequestData.

usiMsgID USINT 1Unique message ID. The N4kReply message from the CM Socket Server to aspecific N4kRequest message contains the same message ID which enablesthe PLC client to link a response to that specific request.

uiSizeIn UINT 2 This field specifies the number of bytes in the InputBuffer in N4kRequestData.

uiSizeOut UINT 2 This field specifies the expected number of data bytes in the reply messagefrom the CM Socket Server.

Tab. 3-1: N4kRequest Header fields The N4kRequest Data is a byte stream that consists of a function name andthe input buffer as specified in chapter 2.3.2 "N4kCall - CM Function Blockinterface" on page 10.

'FUNCTIONNAME\0' InputBuffer

Fig. 3-2: N4kRequest Data Example: N4kRequest message for CmMoveToPosition


Client socket communication interface

'CMMOVETOPOSITION\0'uiLength uiSizeOutuiSizeInusiMsgID

N4kRequest Header N4kRequest Data

SizeOf(LREAL) SizeOf(LREAL) SizeOf(LREAL)SizeOf(INT)

CarrierID End position Velocity Acceleration

SizeOf(FunctionName) + 12 bytes 2 bytes2 bytes1 byte

Jerk

SizeOf(LREAL)

Fig. 3-3: N4kRequest message for the function CmMoveToPosition

3.1.3 N4kReply messageThe N4kReply message contains the CM function call response from the CMSocket Server. The PLC client expects one N4kReply message from the CMSocket Server for every N4kRequest. The N4kReply message consists of aheader and a data field.

N4k Reply Header N4k Reply Data (maximum 1280 bytes)

Fig. 3-4: N4kReply message The N4kReply Header contains the following fields.

Name Data type Size (bytes) Description

uiLength UINT 2 This field specifies the total length of the N4kReply message. The total lengthis the byte count of the N4k Reply Header and the N4k Reply Data.

usiMsgID USINT 1 Unique message ID (of the associated N4kRequest message).

uiStatus USINT 1This flag indicates whether the N4kRequest function call is handledsuccessfully by the CM Socket Server. The value N4K_STATUS_READYindicates that the function is successfully executed by the CM Socket Server.

Tab. 3-2: N4kReply Header fields The N4kReply Data is a byte stream of the output buffer which consists of thereturn value and, if defined, the return arguments of the CM function call fromthe N4kCall Function Block. See chapter 2.3.2 "N4kCall - CM Function Blockinterface" on page 10 for the description of the output buffer. Example: N4kReply message of CmMoveToPosition

NYCE_STATUSuiLength uiStatususiMsgID

N4kReply Header N4kReply Data

SizeOf(UDINT)2 bytes 1 byte1 byte

Fig. 3-5: N4kReply message from the function CmMoveToPosition

3.1.4 TCP/IP socket - CM Socket Server interfaceTCP is a reliable connection-oriented protocol. Every TCP message requiresan acknowledge reply from the receiver of the TCP message. The N4kCallmessages are encapsulated in the TCP byte stream and subsequentlyencapsulated in the IP byte stream to be transmitted to the receiver. The TCPmodel requires that a connection must be established between the client and



the server. A TCP connection is established with the function connect. Themessages are transmitted and received with the functions send and recv,respectively. When the TCP connection is no longer needed, the connectionis terminated with the functions shutdown and close.Suggested construction of the N4kCommunication FB

socket( )

setsockopt( )

shutdown( )

close( )

connect( )

recv( ) or select( )

send( )

PLC TCP client

CM Socket Server

TCP/IP server

Fig. 3-6: Required steps to establish and use a TCP connection Program:

socketID socket( family, type, protocol )

The function socket creates a new socket as endpoint for communication ofa certain socket type and allocates the required system resources. Thefunction has 3 arguments. The argument family specifies the addressfamily and must be set to AF_INET. The argument type defines the service,and is always set to SOCK_STREAM. The argument protocol specifies theactual communication protocol used, and is set to 0. The function socketreturns -1 if an error occurred, else a socket descriptor identifier is returned. Program:setsockopt( socketID, level, optionName, optionValue, optionValueLen )

The function setsockopt set the socket options, and has 5 arguments. Theargument socketID is the value returned from the socket function. Theargument level specifies the protocol and must be set to IPPROTO_TCP.The argument optionName must be set to TCP_NODELAY for performance



reasons. The argument optionValue is a pointer to the option value whichmust be set to -1 (DINT optionValue = -1). The argument optionValueLenis the size of the optionValue variable. Program:

connect( socketID, socketAddr, socketAddrLen )

The function connect is used on the client side to establish a connectionwith the CM Socket Server. The function assigns a free local portnumber to asocket, and sets up a new TCP connection. The function has 3 arguments.The argument socketID specifies the socket descriptor identifier obtainedfrom the function socket. The argument socketAddr is a pointer to theaddress parameters. The address structure depends on the address family ofthe socket. The address family must be set to AF_INET. The IP address andport number depend on the CM Socket Server. The default portnumber is4242. The argument socketAddrLen specifies the size of the socketaddress structure. The function connect returns -1 if an error occurred, else0 is returned. Program:

send( socketID, message, messageLen, flag )

The function send sends a message via the socket connection. The functionhas 4 arguments. The argument socketID specifies the socket descriptoridentifier. The argument message is a pointer to the N4kRequest message.The argument messageLen specifies the number of data bytes to be sentand must be equal to the uiLength field of the N4kRequest Header. Theargument flag is platform-dependent, set the value to 0. The function sendreturns the actual number of data bytes sent. Program:

int recv( socketID, receiveBuffer, bufferLen, flag )

The function recv receives the N4kReply message from the CM SocketServer. The function has 4 arguments. The argument socketID specifiesthe socket descriptor identifier. The argument receiveBuffer is a pointerto an allocated buffer to hold the N4kReply message. The argumentbufferLen specifies the size of the allocated buffer. The argument flag isplatform-dependent, set the value to 0. The function recv returns the actualnumber of data bytes received. recv might not return the completemessage. You must call recv until you gathered the complete expectedmessage. Note that the function recv blocks if no data is available.Optionally, the non-blocking function select can be used to check whetheran N4kReply message is available from the CM Socket Server. Program:

int shutdown( socketID, how )



The function shutdown terminates the connection between the client and theCM Socket Server. The argument socketID specifies the socket descriptoridentifier. The argument how must be set to SHUT_RDWR. Program:

int close( socketID )

The function close closes the socket. The system resources allocated to thesocket are released, and the connection is terminated. The function has oneargument, socketID which specifies the socket descriptor identifier.

3.2 UDP/IP client socket interface3.2.1 Introduction

Applications using a generic PLC can define a custom N4kLogger FunctionBlock and its interface with the PLC application. Note that the log messagesmust be free-formatted text, terminated with a '\0' character. The length ofthe log message is maximum 80 characters.

3.2.2 UDP/IP socket - CM Socket Server interfaceUDP is a simple transport layer protocol. A UDP message uses aconnectionless, unreliable datagram protocol and does not require anacknowledge reply. The PLC application can send a log message to the CMServer. The message is encapsulated in a UDP datagram and subsequentlyencapsulated in an IP datagram to be transmitted to the receiver. UDP doesnot guarantee that the datagrams reach the receiver, or that the order ofdatagrams is preserved across a network. Every UDP datagram is defined byits length which is part of the data sent.

socket( )

close( )

sendto(log messages)

PLC UDP client

CM Socket Server

UDP/IP server

Fig. 3-7: Required steps to use a UDP connection No connections are established between the client and the server in the UDPmodel. Instead, the PLC client sends datagrams (log messages) to the server



with the function sendto. The function sendto requires only the addressand port number of the CM Socket Server. Program:

socketID socket( family, type, protocol )

The function socket creates a new socket as endpoint for communication ofa certain socket type and allocates the required system resources. Thefunction has 3 arguments. The argument family specifies the addressfamily and must be set to AF_INET. The argument type defines the service,and is always set to SOCK_DGRAM. The argument protocol specifies theactual communication protocol used, and is set to 0. The function socketreturns -1 if an error occurred, else a socket descriptor is returned whichuniquely identifies the socket. Program:

status sendto( socketID, message, messageLen, flags, sockAddr, addrLen )

The function sendto sends log messages to the CM Socket Server. Thefunction has 6 arguments. The argument socketID specifies the socketdescriptor identifier obtained from the function socket. The argumentmessage is a pointer that specifies the memory address of the N4kLogmessage to be sent. The argument messageLen specifies the length of theN4kLog message in bytes, including the '\0' character. The argumentflags must be set to 0. The argument socketAddr is a structure whichdepends on the address family of the socket. The address family must be setto AF_INET. The IP address and port number depend on the CM SocketServer. The default portnumber is 4242. The argument addrLen specifiesthe size of the socket address structure. Program:

int close( socketID )

As no connection is established, the function close only releases theallocated system resources and the socket descriptor. The function has oneargument. socketID specifies the socket descriptor identifier.



4 CM Extension4.1 Introduction

The N4kCmExtension DLL offers a flexible mechanism to add NYCe 4000commands and functionality, which is not provided by the CarrierManagement layer, to a PLC application. The application developer cancreate an extension module which adds the desired functionality. Thismechanism gives the LMS application access to NYCe 4000 APIfunctionality.

PLC application

commandsTCP/IP Socket

NYCe commands

socket server thread (NyceCmSocketServer.exe)

Extension DLL (n4kcmextension.dll)

CM commands status requests

PLC Client DLL (N4kCmPlc.dll)

status requests

status requests

Fig. 4-1: Interface between PLC and NYCe 4000 via CM Extension When NYCeCmSocketServer starts, it searches for an optional extensionmodule, which is a dynamic link library, named "n4kcmextension.dll". Ifthat DLL is found, then whenever a not-recognized CM command is receivedfrom the application, NYCeCmSocketServer checks the extension DLLwhether the extension DLL contains a function of that name. If the extensionDLL contains a function of that name, the function is called, else the errorN4K_STATUS_UNKNOWN_REQUEST is returned. This return status can occur,for example, if there is a typo in the function name specified in the string. Thisis not checked by the compiler.Each library function implemented in the extension DLL is called byNYCeCmSocketServer using a separate thread. Therefore, called libraryfunctions will not block CM functions, and these library functions will not blockeach other. You can always call a blocking library function, for example aprogrammed wait operation or a synchronization operation.The following restrictions apply to the use of functions in the extension DLL.● No extension function may be called before CmInitialize.● No extension function may be called after CmShutdown.● The disconnect operation of an axis in a library function is not allowed,

because the disconnection of the axis is a disconnection for the entireprocess.

It is recommended that functions that configure the system are executedimmediately after CmInitialize.On the CD-ROM you can find an example of the use of N4kCmExtension.For more information, please contact Bosch Rexroth.


CM Extension

4.2 InterfacesN4kCmExtension consists of 2 parts. One part is the interface to NYCe 4000which is implemented in the cm.dll library. The other part is implementedon the PLC.At the CM side, the socket server interfaces with the NYCe 4000 API via thelibrary n4kcmextension.dll. The interface to n4kcmextension.dll is afunction table where each function can be called in an identical form.Program:

BOOL FUNC_NAME(const FUNC_INPUT *pInput, unsigned int nSizeIn, NYCE_STATUS *pOutput, unsigned int nSizeOut);

Declaration Direction Description

FUNC_NAME - Definition of the function name as identified in the PLCFunction Block.

*pInput input

Pointer to a buffer that holds all input argument datafor the CM function. The sequence of the parametersin the input buffer must match the sequence ofparameters as defined by the specified CM function.

nSizeIn input Size of the input buffer in bytes.

*pOutput output Pointer to a buffer that holds the return value of theCM function and output arguments, if any.

nSizeOut output Size of the output buffer in bytes.

Tab. 4-1: CM Extension function definition Example: CM Extension for NhiDefineDigitalIOActiveStateProgram:

/* definitions */typedef CM_INT CMX_SLOT_ID;typedef CM_INT CMX_DIG_IO_NR;typedef CM_INT CMX_ACTIVE_STATE;typedef struct{ CMX_SLOT_ID slotId; CMX_DIG_IO_NR digIONr;} CMX_DIGITAL_IO_ID;typedef struct{ NHI_NODE nodeId; CMX_DIGITAL_IO_ID digIoId; CMX_ACTIVE_STATE activeState;} CMX_NODE_DEFINEDIGITALIOACTIVESTATE_PARS_INPUT;/* ------------------------------------------------------------------- * CM Extension function NODE_DEFINEDIGIOACTIVESTATE * ------------------------------------------------------------------- */CMX_FUNCTION BOOL NODE_DEFINEDIGIOACTIVESTATE( const CMX_NODE_DEFINEDIGITALIOACTIVESTATE_PARS_INPUT *pInput, unsigned int nSizeIn, NYCE_STATUS *pOutput, unsigned int nSizeOut ){ NYCE_STATUS nyceStatus = NYCE_OK;


CM Extension

NYCE_DIGITAL_IO_ID digIoId; // Each function should verify its input and output parameters as much as possible // before executing any NYCE API call, and return FALSE if any parameter is in error. if ( (pInput != NULL) && (pOutput != NULL) && ( (sizeof(pInput->nodeId) + sizeof(pInput->digIoId) + sizeof(pInput->activeState)) == nSizein) && (sizeof( *pOutput ) == nSizeOut) ) { digIoId.slotId = (NYCE_SLOT_ID)pInput->digIoId.slotId; digIoId.digIONr = (NYCE_DIG_IO_NR)pInput->digIoId.digIONr; nyceStatus = NhiDefineDigitalIOActiveState(pInput->nodeId, digIoId, ((NYCE_ACTIVE_STATUS)pInput->activeState)); *pOutput = nyceStatus; return ( TRUE ); } else { // check of Input and Output parameters failed, API function is not called. return ( FALSE ); }}

The N4kCall Function Block realizes the access to the functions of theCarrier Management layer. The interface of the CM functions is declared incmapi.h. Each instance of the N4kCall FB has arguments to specify therequested CM function, pass input data to the CM function, and receive resultinformation from the CM function. Example: N4kCall Function Block NhiDefineDigitalIOActiveStateProgram:

TYPE NYCE_DIGITAL_IO_ID :STRUCT slotId: NYCE_SLOT_ID; digIONr: NYCE_DIG_IO_NR;END_STRUCTEND_TYPETYPE NYCE_SLOT_ID :{ NYCE_SLOT0 := 0, NYCE_SLOT1 := 1, NYCE_SLOT2 := 2, NYCE_SLOT3 := 3, NYCE_SLOT4 := 4, NYCE_SLOT5 := 5, NYCE_SLOT6 := 6, NYCE_SLOT7 := 7, NYCE_MCU_SLOT := 8, NYCE_INDRA_SLOT := 9, NO_SLOT := 15};TYPE NODE_DEFINEDIGITALIOACTIVESTATE_IN :STRUCT nodeId: DINT; digIoId: NYCE_DIGITAL_IO_ID; activeState: NYCE_ACTIVE_STATE;END_STRUCTEND_TYPEFUNCTION_BLOCK NhiDefineDigitalIOActiveStateVAR_INPUT Execute: BOOL; NodeId: DINT; DigIoId: NYCE_DIGITAL_IO_ID; ActiveState: NYCE_ACTIVE_STATE;END_VARVAR_OUTPUT


CM Extension

Done: BOOL := FALSE; Active: BOOL := FALSE; Error: BOOL := FALSE; ErrorID: NYCE_STATUS;END_VARVAR strFunctionName: STRING := 'NODE_DEFINEDIGIOACTIVESTATE'; functionIn: NODE_DEFINEDIGITALIOACTIVESTATE_IN; N4kCallFunction: N4kCall; functionOut: NYCE_STATUS;END_VAR(* Start executing the command. *)IF Execute AND NOT Active AND NOT Done AND NOT Error THEN Active := TRUE; (* Copy input parameter(s). *) functionIn.nodeId := NodeId; functionIn.digIoId := DigIoId; functionIn.activeState := ActiveState;(* Execute Command. *)ELSIF Active THEN IF N4kCallFunction.Done THEN IF functionOut = NYCE_OK THEN Done := TRUE; ELSE Error := TRUE; ErrorID := functionOut; END_IF ELSIF N4kCallFunction.Error THEN Error := TRUE; ErrorID := CM_N4KCALL_ERROR + INT_TO_UDINT(N4kCallFunction.ErrorID); END_IF IF Done OR Error THEN Active := FALSE; END_IF(* Stop executing command. *)ELSIF NOT Execute AND (Done OR Error) THEN Done := FALSE; Error := FALSE;END_IF(* Call N4kCall Function Block. *)N4kCallFunction(Execute := Active, FunctionName := strFunctionName, Timeout := 2000, SizeIn := SIZEOF(functionIn), InputBuffer := ADR(functionIn), SizeOut := SIZEOF(functionOut), OutputBuffer := ADR(functionOut));

If needed, the PLC application must define data structures that are used inthe input and output buffers. The definition of these data structures mustmatch the CM data type definition as specified in the cmapi.h interface. tab.4-2 "Data types in the CM and PLC environment" on page 24 gives anoverview how data types of the CM layer are mapped on the PLC data types.

CM data type Memory space① PLC data type Memory space

①

CM_BOOL 8 BOOL 8

CM_INT 16 INT 16

CM_UINT 16 UINT 16

CM_DINT 32 DINT 32

CM_UDINT 32 UDINT 32

NYCE_STATUS 32 UDINT 32

CM_REAL 32 REAL 32

CM_LREAL 64 LREAL 64


CM Extension

CM data type Memory space① PLC data type Memory space

①

string n*8 STRING n*8

enumeration ② 32 INT 16

① Memory space is expressed in bits.② CM data type enumerations are casted from 32 bits to the PLC

data type INT of 16 bits.Tab. 4-2: Data types in the CM and PLC environment

4.3 How to build the N4kCmExtension DLLAfter the NYCe 4000 Software LMS is installed on the PC all files to build ann4kcmextension.dll are available on the hard drive. All files are stored in<installationDirectory>\dev\indralogic\n4kcmextensiondll.The default installation directory is "C:\Program Files\Rexroth\NYCe4000\".Do the following steps to build the n4kcmextension.dll.

1. Start Microsoft Visual Studio.2. Open the solution file "cm_ext.sln".3. Select the menu item "Build → Build Solution" to build an

n4kcmextension.dll.The solution supports "Debug" and "Release" builds for the 32-bit andthe 64-bit platform.


CM Extension


5 Installation package for CM functionality on the PLCThe installation package consists of the following files.● n4kcmsocketclient.library and n4kcmsocketclient.exp

This is a library that contains the Function Blocks for the socketcommunication. The library is created using the IndraWorks 2nd

generation environment. This generated library is a general library. Theimplementation of the Function Blocks, data types, variables andconstants in this library can be opened and changed in the PLCenvironment. In this way you can change the implementation of thislibrary as required for your specific PLC platform. The ASCII filen4kcmsocketclient.exp contains the library implementation inStructured Text language.

● n4kcmapi.library and n4kcmapi.expThis is a library that contains the Function Blocks for the CarrierManagement (CM) functionality.The library is created using the IndraWorks 2nd generation environment.The generated library is a general library. The implementation of theFunction Blocks, data types, variables and constants in this library canbe opened and changed in the PLC environment. In this way you canchange the implementation of this library. The ASCII filen4kcmapi.exp contains the library implementation in Structured Textlanguage. The interface for the CM Function Blocks is described in theNYCe 4000 LMS IndraLogic Interface Manual.– n4kcmapi_mlc25.library and n4kcmapi_mlc25.exp

These two files have the same functionality asn4kcmapi.library and n4kcmapi.exp, but must be used withthe MLC25 PLC, because this PLC does not support structurepacking.

● nyce4000lmslab.xiwpThis is an example project. With the two libraries or ASCII text files it ispossible to create a PLC application that executes the CM functionalitywith a PLC. The example project contains an application created withIndraWorks 2nd generation for the MLC L65 PLC. It contains a programwhich calls several CM Function Blocks. It also contains a program thatcalls the socket communication Function Blocks. Both programs areadded to the Task Configuration. The n4kcmapi.library and then4kcmsocketclient.library are added to the Library Manager.You have to add the libraries to the repository. Then the program can bebuilt.


Installation package for CM functionality on the PLC


Notes


Bosch Rexroth AGElectric Drives and ControlsP.O. Box 13 5797803 Lohr, GermanyBgm.-Dr.-Nebel-Str. 297816 Lohr, GermanyPhone +49 9352 18 0Fax +49 9352 18 8400www.boschrexroth.com/electrics

*R911347824*R911347824

DOK-NY4000-PLC*IFC*V45-RE08-EN-E

http://www.boschrexroth.com/electrics

Documents

Linear motion system LMS Generic PLC Interface Manual