A connection to an ADS device, usually a TwinCAT PLC, over TCP or Secure ADS.

{:ok, plc} = ADS.Client.start_link(host: "10.0.0.5", net_id: "5.36.69.176.1.1")

{:ok, 1500} = ADS.Client.read(plc, "MAIN.nSpeed")
:ok = ADS.Client.write(plc, "MAIN.nSpeed", 1600)
{:ok, %{"nSpeed" => 1600, "fTemp" => 21.5}} = ADS.Client.read(plc, "MAIN.stPump")
{:ok, [{:ok, 1600}, {:ok, true}]} = ADS.Client.read_many(plc, ["MAIN.nSpeed", "MAIN.bOn"])

{:error, :device_symbol_not_found} = ADS.Client.read(plc, "MAIN.nNone")

The client talks to one system, by its AMS NetId, and to the PLC runtime on AMS port 851 unless told otherwise: ams_port: for the client, or port: for one request. Every request gets its result within its timeout, as a value: the client never exits the caller, and it never logs. The errors are those listed in ADS.

Routes

A TwinCAT system talks only to clients it has a route for: the client's NetId and its address, added in TwinCAT's engineering, its system tray menu or a target's web interface. The client's NetId is :local_net_id, by default its IP address on the connection with .1.1 added. To a client without a route, the system closes the connection, and the client tries again. So it does to a second connection from a NetId it's already connected to: clients on one machine to the same system share one client, or each has a NetId and a route of its own.

Variables by name

read/3 and write/4 reach a variable by its name, as the PLC knows it, "MAIN.nSpeed" or "GVL.astPumps[2].fTemp". The client asks the PLC for a handle of the name, and for the descriptions of its type (see ADS.Symbol and ADS.DataType), and keeps both for as long as the connection lasts. Values are Elixir terms as in ADS.Type: a structure is a map, an array a list. A handle that has gone stale, as after an online change, is looked up again, once.

type: gives the type instead, which saves asking for its description, and also reaches data by index group and offset:

{:ok, 1500} = ADS.Client.read(plc, "MAIN.nSpeed", type: :int)
{:ok, 42} = ADS.Client.read(plc, {0x4020, 0}, type: :dint)
:ok = ADS.Client.write(plc, {0x4020, 4}, [1, 2, 3], type: {:array, :int, [{1, 3}]})

read_many/3 and write_many/3 read and write many at once, in sum commands of up to 500, or one at a time with a device that has none. symbols/2 and data_types/2 upload all of the PLC's descriptions, and request/3 sends any ADS command (see ADS.Command).

Notifications

subscribe/3 asks the PLC to send a variable's value when it changes, or every cycle, to the subscriber, the caller by default:

{:ok, ref} = ADS.Client.subscribe(plc, ["MAIN.nSpeed", "MAIN.bOn"], cycle_time: 100)

# the current values at once, then each change
receive do
  {ADS.Client, ^ref, {:value, "MAIN.nSpeed", speed, %DateTime{}}} -> speed
end

A subscription ends with unsubscribe/2, or when the subscriber exits. Beckhoff recommends at most 550 notifications for a device.

Many requests at once

Up to :max_pending requests are on the way at once, matched to their answers by invoke id; more wait in the client, within their own timeouts. Callers may share a client, and send_request/3 lets one process have many requests out.

Connections

start_link/1 returns at once, and the client connects in the background: a request made while it's connecting waits for the connection. When the connection drops, the client connects again by itself, after 100 ms at first and up to 5 seconds between attempts (:backoff), and adds its subscriptions' notifications again. While it's down, requests fail at once with {:error, :closed}, and status/1 says why. Two requests in a row that time out with nothing at all heard since the first was sent mean the connection is dead, and the client reconnects.

Secure ADS

secure: connects to port 8016 with TLS 1.2, as ADS.Secure describes, in one of three ways:

# a pre-shared key, as in the PLC's StaticRoutes.xml
secure: [psk: {"scada", "secret"}]

# certificates from a CA both sides trust
secure: [cacertfile: "ca.pem", certfile: "scada.crt", keyfile: "scada.key"]

# self-signed: the PLC's certificate known by its fingerprint, and a route added once
secure: [fingerprint: "6E:3B:...", certfile: "scada.pem", keyfile: "scada.key",
         add_route: {"Administrator", "1"}]

The PLC's NetId comes in its answer, so net_id: may be left out.

Options

• :host - the PLC's host name or address (required)
• :net_id - the PLC's AMS NetId, such as "5.36.69.176.1.1" (required, except with secure:)
• :ams_port - the AMS port of the device (default 851, the first PLC runtime)
• :local_net_id - the client's NetId, as the PLC's route has it (default the client's IP address on the connection, with .1.1)
• :local_ams_port - the client's AMS port (default one picked from 32768 to 65535, the range for clients)
• :port - the TCP port (default 48898, or 8016 with secure:)
• :secure - Secure ADS, as above
• :timeout - how long a request may take, in ms, waiting its turn included (default 5000)
• :max_pending - how many requests may be on the way at once (default 32)
• :connect_timeout - in ms (default 5000)
• :backoff - {first, longest} wait between attempts to connect, in ms (default {100, 5000})
• :max_size - the most data an answer may have, in bytes (default 16 MB)
• :codepage - of the system's strings of one byte to a character: its STRINGs, the names and comments of its symbols and types, its host name, routes and adapters, and Secure ADS's host name and login (default :windows_1252; see ADS.Codepage)
• :name - to register the process