Notes on the documentation

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

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

Disclaimer

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

Trademarks

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

Patent Pending

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

Copyright

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


Overview

The library contains function blocks for acyclic client-server communication between a BC9xxx Bus Controller and other ADS devices in the network. The way in which these blocks operate is not significantly different from that for the PLC runtime system on the PC.

Requirements

The upper 4 digits of the AMS NetID (network address) and the TCP/IP address of the ADS destination device must be in agreement if the IP connection is to be established.

Example:

ADS communication is to be established with an FC310x Profibus card. The card is assigned its own network address during configuration by the TwinCAT System Manager, e.g.: '172.16.2.209.4.1'. This means that it can be considered as an independent ADS device (a remote PC). In order that the IP connection can be established, the first four figures of the network address must agree with the TCP/IP address of the PC in which this card has been configured. This means that there PC's TCP/IP address must be '172.16.2.209'.

Comments

  • The number of IP connections that may be open simultaneously is restricted to four, in order to maintain the use of resources at a minimum.
  • A connection is established automatically when an ADS command is sent.
  • A connection is automatically closed after about 10 seconds if it is not used in that period.A connection that is no longer required can be explicitly closed before this time has elapsed by means of the ADSCLOSE function block.
  • The maximum data size, a bus terminal controller BC9xxx is able to send (e.g. with ADSWRITE or ADSREADRESBC ) or receive (e.g. with ADSREAD or ADSWRITEIND) is limited to 1980 byte.

Function blocks

Name | Description
ADSREADEX | Reading data via ADS.
ADSRDWRTEX | Writing and reading data via ADS.
ADSWRITE | Writing data via ADS.
ADSCLOSE | Closes the IP-Connection to the ADS device.
ADSREADIND | ADSREAD-Indication.
ADSWRITEIND | ADSWRITE-Indication
ADSRDWRTIND | ADSRDWRT-Indication.
ADSREADRESBC | ADSREAD-Response.
ADSWRITERESBC | ADSWRITE-Response.
ADSRDWRTRESBC | ADSRDWRT-Response.


FUNCTION_BLOCK ADSREADEX

This function block allows execution of an ADS read command, to request data from an ADS device.

VAR_INPUT

VAR_INPUT
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    IDXGRP		: UDINT;
    IDXOFFS		: UDINT;
    LEN		: UDINT;
    DESTADDR 		: DWORD;
    READ		: BOOL;
    TMOUT		: TIME;
END_VAR

NETID : Is a string containing the AMS network identifier of the target device to which the ADS command is directed.

PORT : Contains the port number of the ADS device.

IDXGRP : Contains the index group number (32 bit, unsigned) of the requested ADS service. This value is to be found in the ADS table of the addressed device.

IDXOFFS : Contains the index offset number (32 bit, unsigned) of the requested ADS service. This value is to be found in the ADS table of the addressed device.

LEN : Contains the number, in bytes, of the data to be read.

DESTADDR : Contains the address of the buffer which is to receive the data that has been read. The programmer is himself responsible for dimensioning the buffer to a size that can accept ‘LEN’ bytes. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

READ : The ADS command is triggered by a rising edge at this input.

TMOUT : States the time before the function is cancelled.

VAR_OUTPUT

VAR_OUTPUT
    BUSY		: BOOL;
    ERR		: BOOL;
    ERRID		: UDINT;
    COUNT_R		: UDINT;
END_VAR

BUSY : This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs.

ERR : This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘ErrId’.

ERRID : Contains the ADS command-specific or device specific error code of the most recently executed command.

COUNT_R: Number of succesfully returned data bytes.

Example of calling the block in FBD:

PROGRAM MAIN
VAR
    fbAdsReadEx	: ADSREADEX;
    bRead		: BOOL;
    bBusy		: BOOL;
    bError		: BOOL;
    nErrId		: UDINT;
    cbRead		: UDINT;
    Buffer		: ARRAY[1..10] OF BYTE;
END_VAR

In this example, an ADS read command is sent to an ADS device with network address '172.16.2.209.1.1' and port number 801. This port number could, for instance, be used to address the PLC's first run-time system. The service to be executed is encoded in the index group and the index offset parameters. Here, 10 bytes of PLC variable data in the flags area are to be read starting from byte offset 100. If successful, 10 bytes of data are copied to the address of the Buffer variable.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 and above | BC9xxx (165) firmware version >= 0xB6 | TcAdsBC.Lb6


FUNCTION_BLOCK ADSRDWRTEX

This block allows execution of a combined ADS write/read instruction. Data is transmitted to an ADS device (write) and its response data read with one call.

VAR_INPUT

VAR_INPUT
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    IDXGRP		: UDINT;
    IDXOFFS		: UDINT;
    WRITELEN		: UDINT;
    READLEN		: UDINT;
    SRCADDR 		: DWORD;
    DESTADDR 		: DWORD;
    WRTRD		: BOOL;
    TMOUT		: TIME;
END_VAR

NETID : Is a string containing the AMS network identifier of the target device to which the ADS command is directed.

PORT : Contains the port number of the ADS device.

IDXGRP : Contains the index group number (32 bit, unsigned) of the requested ADS service. This value is to be found in the ADS table of the addressed device.

IDXOFFS : Contains the index offset number (32 bit, unsigned) of the requested ADS service. This value is to be found in the ADS table of the addressed device.

WRITELEN : Contains the number, in bytes, of the data that is to be written.

READLEN : Contains the number, in bytes, of the data to be read.

SRCADDR : Contains the address of the buffer from which the data to be written is to be fetched. The programmer is himself responsible for dimensioning the buffer to such a size that ‘WRITELEN’ bytes can be taken from it. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

DESTADDR : Contains the address of the buffer which is to receive the data that has been read. The programmer is himself responsible for dimensioning the buffer to a size that can accept ‘READLEN’ bytes. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

WRTRD : The ADS command is triggered by a rising edge at this input.

TMOUT : States the time before the function is cancelled.

VAR_OUTPUT

VAR_OUTPUT
    BUSY		: BOOL;
    ERR		: BOOL;
    ERRID		: UDINT;
    COUNT_R		: UDINT;
END_VAR

BUSY : This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs.

ERR : This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘ErrId’.

ERRID : Contains the ADS command-specific or device specific error code of the most recently executed command.

COUNT_R: Number of succesfully readed data bytes.

Example of calling the block in FBD:

PROGRAM MAIN
VAR
    fbAdsRdWrtEx	: ADSRDWRTEX;
    sSymName		: STRING:='MAIN.VARCOUNTER';
    iSymHandle	: UDINT;
    bWriteRead	: BOOL;
    bBusy		: BOOL;
    bError		: BOOL;
    nErrId		: UDINT;
    cbRealReadLen	: UDINT;
END_VAR

In this example, an ADS command is sent to an ADS device with network address '172.16.2.209.1.1' and port number 801. Port number 801 could, for instance, be used to address the PLC's first run-time system. The ADS service is encoded in the index group and the index offset. The handle of a PLC variable with the symbol name 'MAIN.VARCOUNTER' is to be read here and returned to the caller. The WRITELEN input parameter contains the string length of the symbol name, plus one byte for the closing NULL. If successful, 4 bytes of data are copied to the address of the iSymHandle variable.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 and above | BC9xxx (165) firmware version >= 0xB6 | TcAdsBC.Lb6


FUNCTION_BLOCK ADSWRITE

This block permits execution of an ADS write command, for the transfer of data to an ADS device.

VAR_INPUT

VAR_INPUT
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    IDXGRP		: UDINT;
    IDXOFFS		: UDINT;
    LEN		: UDINT;
    SRCADDR 		: DWORD;
    WRITE		: BOOL;
    TMOUT		: TIME;
END_VAR

NETID : Is a string containing the AMS network identifier of the target device to which the ADS command is directed.

PORT : Contains the port number of the ADS device.

IDXGRP : Contains the index group number (32 bit, unsigned) of the requested ADS service. This value is to be found in the ADS table of the addressed device.

IDXOFFS : Contains the index offset number (32 bit, unsigned) of the requested ADS service. This value is to be found in the ADS table of the addressed device.

LEN : Contains the number, in bytes, of the data to be read.

SRCADDR : Contains the address of the buffer from which the data to be written is to be fetched. The programmer is himself responsible for dimensioning the buffer to such a size that ‘LEN’ bytes can be taken from it. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

WRITE : The ADS command is triggered by a rising edge at this input.

TMOUT : States the time before the function is cancelled.

VAR_OUTPUT

VAR_OUTPUT
    BUSY		: BOOL;
    ERR		: BOOL;
    ERRID		: UDINT;
END_VAR

BUSY : This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs.

ERR : This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘ErrId’.

ERRID : Contains the ADS command-specific or device specific error code of the most recently executed command.

Example of calling the block in FBD:

PROGRAM MAIN
VAR
    fbAdsWrite	: ADSWRITE;
    bWrite		: BOOL;
    bBusy		: BOOL;
    bError		: BOOL;
    nErrId		: UDINT;
    Buffer		: ARRAY[1..10] OF BYTE := 1,2,3,4,5,6,7,8,9,0;
END_VAR

In this example, an ADS command is sent to an ADS device with network address '172.16.2.209.1.1' and port number 801. This port number could, for instance, be used to address the PLC's first run-time system. The service to be executed is encoded in the index group and the index offset parameters. If successful, 10 bytes of data (Buffer variables) are written into the flags area of the destination device, starting at byte offset 100.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 and above | BC9xxx (165) firmware version >= 0xB6 | TcAdsBC.Lb6


FUNCTION_BLOCK ADSCLOSE

The ADSCLOSE function block can be used to close explicitly an IP connection that is no longer required. The number of IP connections that may be open simultaneously is restricted to four, in order to maintain the use of resources at a minimum. A connection is automatically established when ADSREADEX, ADSWRITE or ADSRDWRTEX are called. Unused connections are automatically closed after 10 seconds. If it is necessary to establish a connection to more than four ADS devices during that period, the connections that are not required must first be closed.

VAR_INPUT

VAR_INPUT
    NETID		: T_AmsNetId;
    CLOSE		: BOOL;
    TMOUT		: TIME;
END_VAR

NETID: Is a string containing the AMS network identifier of the target device which connection should be closed.

CLOSE : The ADS command is triggered by a rising edge at this input.

TMOUT : States the time before the function is cancelled.

VAR_OUTPUT

VAR_OUTPUT
    BUSY		: BOOL;
    ERR		: BOOL;
    ERRID		: UDINT;
END_VAR

BUSY : This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs.

ERR : This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘ErrId’.

ERRID : Contains the ADS command-specific or device specific error code of the most recently executed command.

Example of calling the block in FBD:

PROGRAM MAIN
VAR
    fbAdsClose	: ADSCLOSE;
    bClose		: BOOL;
    bBusy		: BOOL;
    bError		: BOOL;
    nErrId		: UDINT;
END_VAR

In this example, a rising edge at the bClose input triggers closure of the IP connection to the ADS device with network address '172.16.2.209.1.1'.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 and above | BC9xxx (165) firmware version >= 0xB6 | TcAdsBC.Lb6


Overview

The expanded ADS function blocks make it possible to create a client-server communication between an ADS device and a PLC task of a bus controller or between two bus controllers (e.g. BC9000). With the ADS device it can be a case of a Windows application (uses the AdsDLL/AdsOcx) or another PLC run-time system. Communication between the ADS device and the PLC task is processed using the following service primitives:

  • Request
  • Indication
  • Response
  • Confirmation

Communication between an ADS device and a PLC task proceeds as follows: an ADS device sends a request to the target device (PLC task). This request is registered in the target device by an indication. The target device (PLC task) thereupon carries out a corresponding service. The service to be carried out is encoded via the index-group/offset parameter. Next the PLC sends a response to the ADS device. The response is registered as confirmation by the ADS source device.

Only one instance of the indication and response function block can meaningfully be used per PLC task. Corresponding with the available ADS services: READ, WRITE and READ & WRITE there is an appropriate indication or response function block for each service.

The ADS devices are addressed via a port address ( PORT ) and a network address (NETID).

Example:

The PLC task of the bus controller BC9000 with the network address: "172.64.23.12.1.1" should be called.

The PLC task of the Bus controller has the Portnumber PORT = 800.

NETID = "172.64.23.12.1.1"

Comments:

  • In order for a request to be routed to the PLC task, the highest-value bit, e.g. IG:=0x80000001, must be entered in the index group parameter when the request is made.
  • The maximum data size, a bus terminal controller BC9xxx is able to send (e.g. with ADSREADRESBC ) or receive (e.g. with ADSWRITEIND) is limited to 1980 byte.

ADS indication/response function blocks

Service | Name | Description
READ | ADSREADIND | ADSREAD-Indication.
 | ADSREADRESBC | ADSREAD-Response
WRITE | ADSWRITEIND | ADSWRITE-Indication
 | ADSWRITERESBC | ADSWRITE-Response
READ & WRITE | ADSRDWRTIND | ADS-READ & WRITE-Indication
 | ADSRDWRTRESBC | ADS-READ & WRITE-Response

Development Environment | Target System | PLC Libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


ADSREADIND

TwinCAT PLC Library: Ads BC

FUNCTION_BLOCK ADSREADIND

The function block registers ADSREAD-Requests at a PLC task as indications and allows them to be processed. The queuing of an indication is reported at the VALID output port by means of a rising edge. The indication is shown to have been processed by a rising edge at the CLEAR in put. A falling edge at the CLEAR input releases the function block for processing further indications. After an indication has been processed a response must be sent to the source device via the ADSREADRESBC function block. The PORT and NETID parameters can be used to address the source device for this purpose. The INVOKEID parameter sorts the responses to the requests for the source device and is also sent back as parameter to the source device.

VAR_INPUT

VAR_INPUT
    CLEAR		: BOOL;
END_VAR

CLEAR : With a rising edge at this input an indication is reported as processed and the outputs of the ADSREADIND function block are reset. A falling edge releases the function block for the processing of further indications.

VAR_OUTPUT

VAR_OUTPUT
    VALID		: BOOL;
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    INVOKEID		: UDINT;
    IDXGRP		: UDINT;
    IDXOFFS		: UDINT;
    LENGTH		: UDINT;
END_VAR

VALID : The output is set if an indication was registered from the function block and remains set until the latter was reported as processed by a raising edge at the CLEAR input.

NETID : Is a string, which contains the AMS network identifier of the source device, from which the ADS command was sent.

PORT : Contains the port number of the ADS source device, from which the ADS command was sent.

INVOKEID : Contains a handle of the command, which was sent. The InvokeId is specified from the source device and serves to identify the commands.

IDXGRP : Contains the index group number (32 bit, unsigned) of the requested ADS service.

IDXOFFS : Contains the index offset number (32 bit, unsigned) of the requested ADS service.

LENGTH : Contains the number, in bytes, of the data to be read.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


ADSWRITEIND

FUNCTION_BLOCK ADSWRITEIND

The function block registers ADSWRITE-Requests to a PLC task as indications and allows them to be processed. The queuing of an indication is reported at the VALID output port by means of a rising edge. The indication is shown to have been processed by a rising edge at the CLEAR input. A falling edge at the CLEAR input releases the function block for the processing of further indications. After an indication has been processed a response must be sent to the source device via the ADSWRITERESBC function block. The PORT and NETID parameters can be used to address the source device for this purpose. The INVOKEID parameter sorts the responses to the requests for the source device and is also sent back as parameter to the source device.

VAR_INPUT

VAR_INPUT
    CLEAR		: BOOL;
END_VAR

CLEAR : With a rising edge at this input an indication is reported as processed and the outputs of the ADSWRITEIND function block are reset ( DATAADDR = 0, LENGTH = 0 !). A falling edge releases the function block for the processing of further indications.

VAR_OUTPUT

VAR_OUTPUT
    VALID		: BOOL;
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    INVOKEID		: UDINT;
    IDXGRP		: UDINT;
    IDXOFFS		: UDINT;
    LENGTH		: UDINT;
    DATAADDR 		: DWORD;
END_VAR

VALID : The output is set if an indication was registered from the function block and remains set until the latter was reported as processed by a raising edge at the CLEAR input.

NETID : Is a string, which contains the AMS network identifier of the source device, from which the ADS command was sent.

PORT : Contains the port number of the ADS source device, from which the ADS command was sent.

INVOKEID : Contains a handle of the command, which was sent. The InvokeId is specified from the source device and serves to identify the commands.

IDXGRP : Contains the index group number (32 bit, unsigned) of the requested ADS service.

IDXOFFS : Contains the index offset number (32 bit, unsigned) of the requested ADS service.

LENGTH : Contains the length, in bytes, of the data to be written.

DATAADDR : Contains the address of the data buffer, in which the data written is located.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


ADSRDWRTIND

FUNCTION_BLOCK ADSRDWRTIND

The function block registers ADSRDWRT-Requests to a PLC task as indications and allows them to be processed. The queuing of an indication is reported at the VALID output port by means of a rising edge. The indication is shown to have been processed by a rising edge at the CLEAR input. A falling edge at the CLEAR input releases the function block for the processing of further indications. After an indication has been processed a response must be sent to the source device via the ADSRDWRTRESBC function block. The PORT and NETID parameters can be used to address the source device for this purpose. The INVOKEID parameter sorts the responses to the requests for the source device and is also sent back as parameter to the source device.

VAR_INPUT

VAR_INPUT
    CLEAR		: BOOL;
END_VAR

CLEAR : With a rising edge at this input an indication is reported as processed and the outputs of the ADSRDWRTIND function block are reset. A falling edge releases the function block for the processing of further indications.

VAR_OUTPUT

VAR_OUTPUT
    VALID		: BOOL;
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    INVOKEID		: UDINT;
    IDXGRP		: UDINT;
    IDXOFFS		: UDINT;
    RDLENGTH		: UDINT;
    WRTLENGTH		: UDINT;
    DATAADDR 		: DWORD;
END_VAR

VALID : The output is set if an indication was registered from the function block and remains set until the latter was reported as processed by a raising edge at the CLEAR input.

NETID : Is a string, which contains the AMS network identifier of the source device, from which the ADS command was sent.

PORT : Contains the port number of the ADS source device, from which the ADS command was sent.

INVOKEID : Contains a handle of the command, which was sent. The InvokeId is specified from the source device and serves to identify the commands.

IDXGRP : Contains the index group number (32 bit, unsigned) of the requested ADS service.

IDXOFFS : Contains the index offset number (32 bit, unsigned) of the requested ADS service.

RDLENGTH : Contains the length, in bytes, of the data to be read.

WRTLENGTH : Contains the length, in bytes, of the data to be written.

DATAADDR : Contains the address of the data buffer, in which the data written is located.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


ADSREADRESBC

FUNCTION_BLOCK ADSREADRESBC

The ADSREADRES function block is used to acknowledge indications of a PLC task. A response is sent to the ADS source device via a rising edge on the RESPOND input. The source device is addressed via the PORT and NETID parameters. The INVOKEID parameter sorts the responses to the requests for the source device and is adopted by the output of the ADSREADIND function block. An error code can be returned to the ADS source device via the RESULT parameter.

VAR_INPUT

VAR_INPUT
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    INVOKEID		: UDINT;
    RESULT		: UDINT;
    LEN		: UDINT;
    DATAADDR		: DWORD;
    RESPOND		: BOOL;
END_VAR

NETID : Is a string, which contains the AMS network identifier of the source device, to which the ADS command should be sent.

PORT : Contains the port number of the ADS source device, to which the response should be sent.

INVOKEID : Contains a handle of the command, which was sent. The InvokeId is specified from the source device and serves to identify the commands.

RESULT : Contains the error code, which should be sent to the source device.

LEN : Contains the number, in bytes, of the data to be read.

DATAADDR : Contains the address of the data buffer, which should be read.

RESPOND : The function block is activated by a positive edge at this input.

VAR_OUTPUT

VAR_OUTPUT
    BUSY		: BOOL;
END_VAR

BUSY : When the function block is activated this output is set. It remains set until acknowledgement is received.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


ADSWRITERESBC

FUNCTION_BLOCK ADSWRITERESBC

The ADSWRITERES function block is used to acknowledge indications of a PLC task. A response is sent to the ADS source device via a rising edge on the RESPOND input. The source device is addressed via the PORT and NETID parameters. The INVOKEID parameter sorts the responses to the requests for the source device and is adopted by the output of the ADSWRITEIND function block. An error code can be returned to the ADS source device via the RESULT parameter.

VAR_INPUT

VAR_INPUT
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    INVOKEID		: UDINT;
    RESULT		: UDINT;
    RESPOND		: BOOL;
END_VAR

NETID : Is a string, which contains the AMS network identifier of the source device, to which the ADS command should be sent.

PORT : Contains the port number of the ADS source device, to which the ADS command should be sent.

INVOKEID : Contains a handle of the command, which was sent. The InvokeId is specified from the source device and serves to identify the commands.

RESULT : Contains the error code, which should be sent to the source device.

RESPOND : The function block is activated by a positive edge at this input.

VAR_OUTPUT

VAR_OUTPUT
    BUSY		: BOOL;
END_VAR

BUSY : When the function block is activated this output is set. It remains set until acknowledgement is received.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


ADSRDWRTRESBC

FUNCTION_BLOCK ADSRDWRTRESBC

The ADSRDWRTRESBC function block is used to acknowledge indications of a PLC task. A response is sent to the ADS source device via a rising edge on the RESPOND input. The source device is addressed via the PORT and NETID parameters. The INVOKEID parameter sorts the responses to the requests for the source device and is adopted by the output of the ADSRDWRTIND function block. An error code can be returned to the ADS source device via the RESULT parameter.

VAR_INPUT

VAR_INPUT
    NETID		: T_AmsNetId;
    PORT		: T_AmsPort;
    INVOKEID		: UDINT;
    RESULT		: UDINT;
    LEN		: UDINT;
    DATAADDR		: DWORD;
    RESPOND		: BOOL;
END_VAR

NETID : Is a string, which contains the AMS network identifier of the source device, to which the ADS command should be sent.

PORT : Contains the port number of the ADS source device, to which the ADS command should be sent.

INVOKEID : Contains a handle of the command, which was sent. The InvokeId is specified from the source device and serves to identify the commands.

RESULT : Contains the error code, which should be sent to the source device.

LEN : Length, in bytes, of the read data.

DATAADDR : Address of the data buffer, in which the read data is located.

RESPOND : The function block is activated by a positive edge at this input.

VAR_OUTPUT

VAR_OUTPUT
    BUSY		: BOOL;
END_VAR

BUSY : When the function block is activated this output is set. It remains set until acknowledgement is received.

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


Example application with the expanded ADS function blocks

Example 1: ADSREAD-Indication/-Response

In the example application, READ requests are sent from a VB application to the PLC task of a BC9000, in order to increment/decrement or reset a PLC counter variable. The READ requests are intercepted as indications at the bus controller, and the desired operation is executed at the counter variable. The bus controller then sends a response with the current value of the counter variable back to the VB application. The value of the counter variable is output on the form. In order to communicate with the PLC task the VB application uses the ActiveX control: AdsOcx. The bus controller must be entered as a remote PC in the TwinCAT system menu in order to be able to route the requests of the VB application to the bus controller via the Ethernet. Here you can unpack the complete sources relating to the example application :

Entering BC9000 as remote PC in the TwinCAT system menu

The TwinCAT system menu can be accessed by clicking the TwinCAT icon->properties in the task bar. Select Add on the AMS router tab. Add. Enter an arbitrary name for the remote PC in the dialog. The network address is entered under AMS Net ID. It consists of the IP address of the BC9000 and two further digits: "1.1". The IP address of the BC9000 is entered again under Address. The IP address must correspond to the address that was set via the dip switches on the bus controller.

The VB application

A connection to the PLC task of the BC9000 is established in the Form_Load routine. The required service in the PLC task is encoded in the index group parameter:

  • IG:0x80000001 -> increment the counter variable;
  • IG:0x80000002 -> decrement the counter variable;
  • IG:0x80000003 -> set the counter variable = 0;
  • IO: 0x0

Important note:

So that the requests can be routed to the PLC task, the highest value bit must be set in the index group parameter. The values of the index group and index offset parameters can be custom defined. In our example, the bus controller detects whether the PLC variable is to be incremented/decremented or reset via the index group and index offset parameters.

Option Explicit

Dim tmpData(1) As Integer
Dim AdsResult    As Integer

Private Sub Command1_Click()

    AdsResult = AdsOcx1.AdsSyncReadReq(&H80000001, &H0, 2, tmpData)
    Label1.Caption = "Ads result:" & AdsResult & " PLC data:" & tmpData(0)

End Sub

Private Sub Command2_Click()
    AdsResult = AdsOcx1.AdsSyncReadReq(&H80000002, &H0, 2, tmpData)
    Label1.Caption = "Ads result:" & AdsResult & " PLC data:" & tmpData(0)

End Sub

Private Sub Command3_Click()
    AdsResult = AdsOcx1.AdsSyncReadReq(&H80000003, &H0, 2, tmpData)
    Label1.Caption = "Ads result:" & AdsResult & " PLC data:" & tmpData(0)

End Sub

Private Sub Form_Load()
    AdsOcx1.AdsAmsServerNetId = "172.16.17.63.1.1"
    AdsOcx1.AdsAmsServerPort = 800 'PLC task number'
End Sub

The PLC program

Create a new PLC project for the bus controller. The following PLC libraries for the bus controller must be integrated under library management: Standard.lb6, PlcHelperBC.lb6 und TcAdsBC.lb6.

The requests are intercepted as indications in the PLC task by an instance of the ADSREADIND function block. Next the index group and index offset parameters and the required data length and validity are checked. In the CASE instruction the desired operation is implemented on the PLC variables. If successful a response is sent back by an instance of the ADSREADRES function block to the caller with the current value of the PLC variables. In the case of an error an appropriate error message. At the end the CLEAR and RESPOND flags are reset in order to be able to process further indications.

PROGRAM MAIN
VAR
    fbREADIND				: ADSREADIND;
    fbREADRESBC			: ADSREADRESBC;

    szNetId				: STRING(23);
    Port				: UINT;
    InvokeId				: UDINT;
    idxGrp				: UDINT;
    idxOffs				: UDINT;
    cbLength				: UDINT;
    ErrorNumber			: UDINT;

    varCounter	AT%MB100		: INT;
END_VAR

fbREADIND( );
fbREADRESBC( );

IF ( fbREADIND.VALID ) THEN
    szNetId := fbREADIND.NETID;
    Port := fbREADIND.PORT;
    InvokeId := fbREADIND.INVOKEID;
    idxGrp := fbREADIND.IDXGRP;
    idxOffs := fbREADIND.IDXOFFS;
    cbLength := fbREADIND.LENGTH;
    fbREADIND(  CLEAR := TRUE ); 		(*clear indication entry*)
    ErrorNumber := 0;

    IF idxOffs = 0 THEN
        IF  cbLength >= 2 THEN
            CASE idxGrp OF
                16#80000001:
                    varCounter := varCounter  + 1;

                16#80000002:
                    varCounter := varCounter  - 1;

                16#80000003:
                    varCounter := 0;
            ELSE
                ErrorNumber := 1793;  (* ADS error: Service is not supported by server*)
            END_CASE
        ELSE
            ErrorNumber := 1797;  (*ADS error:Parameter size not correct*)
        END_IF
    ELSE
        ErrorNumber := 1795;	(*ADS error: Invalid index offset*)
    END_IF

    fbREADRESBC.NETID := szNetId;
    fbREADRESBC.PORT := Port;
    fbREADRESBC.INVOKEID := InvokeId;
    fbREADRESBC.RESULT := ErrorNumber;

    IF ErrorNumber = 0 THEN
        fbREADRESBC( LEN := SIZEOF(varCounter),DATAADDR := ADR(varCounter), RESPOND := TRUE );
    ELSE
        fbREADRESBC( LEN := 0,DATAADDR :=0, RESPOND := TRUE );
    END_IF

END_IF

(*reset fb's*)
IF NOT fbREADRESBC.BUSY THEN
    fbREADIND( CLEAR := FALSE );
    fbREADRESBC( RESPOND := FALSE );
END_IF

Here you can unpack the complete sources relating to the example application: Example application with the expanded ADS function blocks


Example 2

Example 2: ADSWRITE-Indication/-Response

The VB application sends an array with 10 integer values to the PLC task of a BC9000 bus controller. In the PLC task of the bus controller, the data received should be copied into an array variable for further processing. The VB application uses ActiveX Control for communicating with the bus controller: AdsOcx. The bus controller must be entered as a remote PC in the TwinCAT system menu in order to be able to route the requests of the VB application to the bus controller via the Ethernet. Here you can unpack the complete sources relating to the example application:

Entering BC9000 as remote PC in the TwinCAT system menu

The TwinCAT system menu can be accessed by clicking the TwinCAT icon->properties in the task bar. Select Add on the AMS router tab.Enter an arbitrary name for the remote PC in the dialog. The network address is entered under AMS Net ID. It consists of the IP address of the BC9000 and two further digits: "1.1". The IP address of the BC9000 is entered again under Address. The IP address must correspond to the address that was set via the dip switches on the bus controller.

The VB application

A connection to the PLC task of the BC9000 is established in the Form_Load routine (port 800 and network address "172.16.17.63.1.1"). The first four digits of the network address correspond to the IP address of the bus controller. The desired service from the PLC task is encoded in the index group and index offset parameters. E.g.:

  • IG:0x80000005 and
  • IO:0x00000007-> Copy the sent data into the array in the PLC.

The VB application uses the AdsSyncWriteReq method to send 20 bytes of data to the bus controller. The values transmitted last are added to a list for monitoring purposes.

Important note:

So that the requests can be routed to the PLC task, the highest value bit must be set in the index group parameter. The values of the index group and index offset parameters can be custom defined. In our example, the bus controller detects that it should copy the data received into an array via the index group and index offset parameters.

Option Explicit

Dim AdsResult     As Integer
Dim arrData(0 To 9)   As Integer

Private Sub cmdWrite_Click()
    Call List1.Clear

    Dim i As Long
    For i = LBound(arrData) To UBound(arrData)
        arrData(i) = arrData(i) + 1 'change values
        Call List1.AddItem("arrData(" & i & ") = " & arrData(i))
    Next i

    'calculate the byte length parameter
    Dim cbWriteSize As Long
    cbWriteSize = (UBound(arrData) - LBound(arrData) + 1) * LenB(arrData(LBound(arrData)))

    AdsResult = AdsOcx1.AdsSyncWriteReq(&H80000005, &H7, cbWriteSize, arrData) 'send data to PLC
    Label1.Caption = "Ads result: " & AdsResult

End Sub

Private Sub Form_Load()
    AdsOcx1.AdsAmsServerNetId =  "172.16.17.63.1.1"
    AdsOcx1.AdsAmsServerPort = 800 'PLC task number of the BC9000 buscontroller'

    Dim i As Long
    For i = LBound(arrData) To UBound(arrData)
        arrData(i) = i    'init data
    Next i
End Sub

The PLC program

Create a new PLC project for the bus controller. The following PLC libraries for the bus controller must be integrated under library management: Standard.lb6, PlcHelperBC.lb6 und TcAdsBC.lb6.

In the PLC task of the bus controller, an instance of the ADSWRITEIND function block is used to receive the data, and an instance of the ADSWRITERESBC function block is used to acknowledge receipt of the data. In the PLC task, the requests are intercepted as so-called indications by the ADSWRITEIND function block. The validity of the parameters index group and index offset and the transmitted data length is then checked for validity, and the data received are copied into an array variable. A response is then sent back to the caller from an instance of the ADSWRITERESBC function block (including an error code, if appropriate). This indicates to the VB application that the transmitted data were received successfully.

Important note:

With the rising edge at the CLEAR input of the ADSWRITEIND function block the address pointer to the most recently sent data becomes invalid ( == ZERO ). For this reason the sent data is first copied into the PLC variable before the CLEAR input is set to TRUE. At the end the CLEAR and RESPOND flags are reset in order to be able to process further indications.

PROGRAM MAIN
VAR
    fbWRITEIND			: ADSWRITEIND;
    fbWRITERESBC			: ADSWRITERESBC;

    szNetId				: STRING(23);
    Port				: UINT;
    InvokeId				: UDINT;
    idxGrp				: UDINT;
    idxOffs				: UDINT;
    cbLength				: UDINT;
    ErrorNumber			: UDINT;

    arrInt				: ARRAY[0..9] OF INT;
END_VAR

fbWRITEIND( );
fbWRITERESBC( );

IF ( fbWRITEIND.VALID ) THEN
    szNetId 		:= fbWRITEIND.NETID;
    Port 		:= fbWRITEIND.PORT;
    InvokeId 		:= fbWRITEIND.INVOKEID;
    idxGrp 		:= fbWRITEIND.IDXGRP;
    idxOffs 		:= fbWRITEIND.IDXOFFS;
    cbLength 		:= fbWRITEIND.LENGTH;
    ErrorNumber 	:= 0;

    CASE idxGrp OF
        16#80000005:

            CASE idxOffs OF
                16#00000007:
                    IF  cbLength <= SIZEOF( arrInt ) THEN
                        IF ( MEMCPY( ADR( arrInt ), fbWRITEIND.DATAADDR, UDINT_TO_INT(cbLength) ) =  0 ) THEN
                            ErrorNumber := 4000; (*MEMCPY fail*)
                        END_IF
                    ELSE
                        ErrorNumber := 1798;  (* ADS error: invalid parameter value(s)*)
                    END_IF
            ELSE
                ErrorNumber := 1795;	(*ADS error: Invalid index offset*)
            END_CASE

    ELSE
        ErrorNumber := 1794; (*ADS error: invalid index group*)
    END_CASE

    fbWRITEIND(  CLEAR := TRUE ); 		(*clear indication entry*)

    fbWRITERESBC.NETID := szNetId;
    fbWRITERESBC.PORT := Port;
    fbWRITERESBC.INVOKEID := InvokeId;
    fbWRITERESBC.RESULT := ErrorNumber;
    fbWRITERESBC( RESPOND :=  TRUE );	(*send response*)

END_IF

(*reset fb's*)
IF NOT fbWRITERESBC.BUSY THEN
    fbWRITEIND( CLEAR := FALSE );
    fbWRITERESBC( RESPOND := FALSE );
END_IF

Here you can unpack the complete sources relating to the example application: Example application with the expanded ADS function blocks


T_AmsNetId

TYPE T_AmsNetId

TYPE T_AmsNetId : STRING(23);
END_TYPE

The variable of this type is a string containing the AMS network identifier of the target device to which the ADS command is directed. The string consists of six numerical fields, separated by dots. Each numerical field contains a number between 1 and 254. Valid AMS network addresses are, for example, "1.1.1.2.7.1" or "200.5.7.170.1.7".

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


T_AmsPort

TYPE T_AmsPort

TYPE T_AmsPort : UINT;
END_TYPE

ADS devices in the TwinCAT network are identified by an AMS network address and a port number. The following port numbers are invariably specified on every individual TwinCAT system. Table with some specified ADS port numbers:

ADS device | Port number
PLC Run-time system of bus controller BCxxxx | 800
Camshaft controller value | 900
PLC on PC | Run-time system 1 :801 Run-time system 2 :811 Run-time system 3 :821 Run-time system 4 :831
NC | 500
Reserved | 400
I/O | 300
Real-time kernel | 200
Message system | 100

Development environment | Target system type | PLC libraries to include
TwinCAT v2.7.0 Build > 517 TwinCAT v2.8.0 Build > 729 | BC9xxx (165) firmware version >= 0xB7 | TcAdsBC.Lb6


Device specific error codes

BC9xxx return codes

Value (hex) | Description
0x8000 | Invalid AMS NetId
0x8001 | reserved
0x8002 | Tx connection error
0x8003 | Connection close error
0x8004 | Timeout error
0x8005 | Connection is busy
0x8006 | Tx error
0x8007 | Invalid parameter
0x8010 | IP-Connection is in use by another AMS/ADS service
0x8011 | Warning, connection already closed
0x8800 | No valid network configuration
0x8F00 | Resource error
0x8901 | ADS length error