//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      https://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
:imagesdir: ../../images/users/protocols
:icons: font

== ADS (Automation Device Specification)
image::ads_banner.png[banner,512,167]

The ADS (automation device specification) describes a device-independent and fieldbus independent interface for communication between Beckhoff automation devices running TwinCAT and other devices implementing this interface. https://www.home-assistant.io/integrations/ads/ Source (accessed 7 August 2022)

ADS device concept: https://infosys.beckhoff.com/english.php?content=../content/1033/ams_nat/4275563275.html&id= Source (accessed 7 August 2022)

Specifcation for ADS devices: https://infosys.beckhoff.com/english.php?content=../content/1033/ams_nat/4275563275.html&id= Source (accessed 7 August 2022)

=== Structure AMS/TCP Packet
ADS (Automation Device Specification) is the TwinCAT communication protocol that specifies the interaction between two ADS devices. For example, it defines what operations can be executed on another ADS device, what parameters are necessary for that and what return value is sent after execution.

AMS (Automation Message Specification) specifies the exchange of the ADS data. A major component of the communication protocol is the AmsNetId. This is specified in the AMS/ADS package for the source and target device. An ADS device can be explicitly addressed using the AmsNetId.
Source https://infosys.beckhoff.com/english.php?content=../content/1033/ams_nat/4275563275.html&id= (accessed 7 August 2022)

=== Connection String Options

[cols="2,2a,5a"]
|===
|Name |Value |Description

|Code
2+|`ADS`

|Name
2+|ADS Protocol

|Maven Dependency
2+|
----
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-ads</artifactId>
  <version>{current-last-released-version}</version>
</dependency>
----

|Default Transport:
2+| `tcp`
3+|Supported Operations

|
| `read`
| 

3+|Options

| AmsNetId
| getTargetAmsNetId()
| setTargetAmsNetId(AmsNetId targetAmsNetId)

| AmsNetIdConverter
| 
|

| targetAmsPort
| getDefaultPort(48898)
| Defaults to 48898

|===

[%header, cols=3*]
|===
| Data array
| Size
| Description

| AMS/TCP Header
| 6 bytes
| contains the length of the data packet.

| AMS Header
| 32 bytes
| The AMS/TCP-Header contains the addresses of the transmitter and receiver. In addition the AMS error code , the ADS command Id and some other information.

| ADS Data
| n bytes
| The ADS data range contains the parameter of the single ADS commands. The structure of the data array depends on the ADS command. Some ADS commands require no additional data.

|===

=== More details on
For details about the protocol look here: http://www.beckhoff.com/ 
& (German Handbook: https://download.beckhoff.com/download/Document/automation/twincat3/TwinCAT_3_ADS_INTRO_DE.pdf)


