# Beckhoff ADS

> Conectar PLC Beckhoff TwinCAT sobre ADS/AMS: la ruta AMS, el puerto del runtime, las rutas de símbolo y las longitudes de lectura.

El driver **Beckhoff ADS** habla con PLC Beckhoff TwinCAT sobre ADS, el protocolo de
automatización de TwinCAT transportado sobre rutas AMS. Usted direcciona los valores por
su ruta de símbolo dentro del programa del PLC, así que lo que escribe es lo que declara
el proyecto de TwinCAT. Agregue un dispositivo bajo el driver Beckhoff ADS en el
[Connector](connector); el panel muestra solo los campos que usa este protocolo.

## Conexión {#connection}

| Campo | Significado | Valor inicial |
| --- | --- | --- |
| **Host o IP** | La dirección IP del PLC. Su AMS Net Id se deriva de esta dirección como `{ip}.1.1`. Salvo que **AMS Net Id del PLC** lo indique, el AMS Net Id del PLC es esta dirección seguida de `.1.1`; un nombre se resuelve antes a su dirección IPv4. | vacío |
| **Puerto** | El puerto AMS del runtime de destino: el 851 es el runtime de PLC 1 de TwinCAT 3, y los demás runtimes de TwinCAT 3 cuentan hacia arriba desde ahí (852, 853, …). Un campo vacío muestra 851 en gris y se usa ese runtime, que es también como se lee un dispositivo guardado con 0. | 851 |
| **IP local (AMS)** | La dirección IP propia de esta estación, de la que se deriva su AMS Net Id como `{ip}.1.1`. Tiene que coincidir con la ruta AMS configurada en el PLC. Un campo vacío usa la dirección de esta estación en la red que llega al PLC, que muestra en gris; un valor escrito en el campo se usa en su lugar. | vacío |
| **AMS Net Id del PLC** | El AMS Net Id propio del PLC, para un PLC cuyo id no es su dirección IP seguida de `.1.1`: seis números de 0 a 255 separados por puntos, tal como lo muestra TwinCAT XAE en **SYSTEM > Routes**, pestaña **NetId Management**, **Target NetId**. Un campo vacío usa la dirección IPv4 del host seguida de `.1.1`, que muestra en gris. Un valor que no es un AMS Net Id deja el dispositivo desconectado y dice qué escribir. | vacío |
| **Intervalo de sondeo (ms)** | El periodo de lectura de todo el dispositivo, para los tags que no lo invaliden. | 1,000 |

El encabezado del dispositivo muestra el endpoint armado, por ejemplo
`ads://192.168.0.1:192.168.0.50:851` (IP local, IP del PLC, puerto AMS). Cada tag puede
poner su propio **Intervalo de sondeo (ms)**; un valor de 0 en el tag cae en el
intervalo del dispositivo.

ADS solo contesta a las estaciones para las que el PLC tiene una ruta AMS:
[Preparar el PLC](#prepare-the-plc) dice qué ruta agregar y dónde.

## Preparar el PLC {#prepare-the-plc}

Un PLC TwinCAT solo contesta ADS a una estación para la que su router AMS tiene una
ruta. Sin la ruta, el router acepta la conexión en el puerto TCP 48898 y luego la
cierra o nunca contesta, así que la conexión falla aunque el camino de red esté
perfecto. Agregue una vez en el PLC una ruta estática para esta estación:

| Campo del diálogo Add Route de TwinCAT | Valor |
| --- | --- |
| Nombre: **Route Name (Target)** | Cualquier nombre; el aviso sugiere el nombre de equipo de esta estación. |
| Net id: **AmsNetId** | La dirección de esta estación seguida de `.1.1`, que es lo que el driver deriva de la **IP local (AMS)**. |
| Transporte: **Transport Type** | El transporte `TCP_IP` |
| Dirección: **Address Info** | La dirección de esta estación, con **IP Address** seleccionado. |
| Tipo de ruta: **Target Route** y **Remote Route** | `Static` y `None` |

En TwinCAT XAE, elija el PLC como sistema de destino y abra **SYSTEM > Routes**,
pestaña **Static Routes**, y luego Add. En el escritorio del propio PLC, el icono
de TwinCAT del área de notificación abre la misma lista con **Router > Edit Routes**.

La dirección es la de esta estación en la red que llega al PLC. Un equipo con varias
tarjetas de red tiene una dirección en cada una, y la ruta solo vale para la que
nombra. Mientras la **IP local (AMS)** está vacía, el driver usa la dirección de la
tarjeta por la que Windows llega al PLC, que el campo muestra en gris: esa es la
dirección que nombra la ruta. Un valor escrito en el campo se usa en su lugar, y la
ruta tiene que nombrar ese.

Cuando el router del PLC rechaza la estación por falta de la ruta, la página del
dispositivo lo dice en un aviso que ocupa el lugar del error del driver: la ruta lista
para agregar (su nombre, el AMS Net Id de esta estación, su dirección y el transporte,
cada uno con un botón para copiar) y dónde la agrega TwinCAT. El aviso desaparece solo
en cuanto el PLC contesta, y el registro y el agente leen la misma ruta. Un puerto que
rechaza la conexión o se queda callado se dice como lo que es, no como una ruta que
falta.

La estación direcciona al PLC por su AMS Net Id, y el router del PLC solo contesta
por el suyo: un PLC cuyo AMS Net Id no es el que usa la estación tampoco contesta
nunca, lo que se ve exactamente igual que una ruta que falta. Cuando el PLC ya tiene la
ruta y aun así no contesta, revise su AMS Net Id en TwinCAT XAE en **SYSTEM > Routes**,
pestaña **NetId Management**, **Target NetId**, y escríbalo en **AMS Net Id del PLC**;
el aviso nombra el que usa la estación.

## El direccionamiento {#addressing}

Un tag de Beckhoff se direcciona con dos campos de la tarjeta Fuente del tag:

| Campo | Significado | Valores aceptados | Valor inicial |
| --- | --- | --- | --- |
| **Símbolo** | La ruta de símbolo de la variable dentro del programa del PLC. Obligatorio. | texto libre, por ejemplo `MAIN.fValue` | vacío |
| **Longitud de lectura (bytes, en blanco = automático)** | Cuántos bytes transferir por lectura. En blanco, la lectura se dimensiona a partir del tipo de dato. | 1 en adelante, o en blanco | en blanco |

La ruta de símbolo es exactamente lo que muestra TwinCAT: las variables de programa como
`MAIN.fValue`, las listas de variables globales como `GVL.MachineSpeed` o
`GVL_Settings.rSetpoint`. El driver resuelve el símbolo por su nombre en el PLC y lee sus
bytes crudos. Las longitudes de lectura automáticas son:

| Tipo de dato | Longitud de lectura automática |
| --- | --- |
| Boolean | 1 byte |
| Int32 | 4 bytes |
| Float | 4 bytes |
| String | 16 bytes |

Para un String de más de 16 caracteres, ponga la **Longitud de lectura** de modo que
cubra el tamaño declarado (un `STRING(80)` de TwinCAT necesita 80 bytes de texto). La
línea de solo lectura **Dirección de origen (bus)** de la tarjeta Fuente muestra la
dirección armada conforme usted edita.

Una lectura que el PLC rechaza, como la de un símbolo que no tiene o que no deja leer,
deja el tag sin valor, y el motivo del tag nombra el código de error ADS y lo que
significa, por ejemplo `ADS error 0x710 (no symbol by that name)`. La conexión sigue
arriba y los demás tags siguen leyendo; el motivo se va con la siguiente lectura que el
PLC conteste.

## Los tipos de dato {#data-types}

El selector de **Tipo de dato** ofrece los cuatro tipos que el driver sabe transportar:

| Tipo de dato | Contraparte en el PLC | Notas |
| --- | --- | --- |
| Boolean | BOOL | 1 byte, distinto de cero es verdadero |
| Int32 | DINT | little-endian, igual que el PLC |
| Float | REAL | little-endian, igual que el PLC |
| String | STRING | el texto hasta el primer NUL del búfer de lectura |

El orden de bytes es el little-endian propio del PLC y se maneja automáticamente; no hay
opción de orden de bytes. Una lectura de String decodifica el búfer devuelto hasta el
primer terminador NUL, así que el relleno que queda detrás de un texto corto nunca se
cuela en el valor. Los demás anchos de TwinCAT (INT, LREAL, WORD, …) no se ofrecen:
exponga una variable así en el programa del PLC como uno de los cuatro tipos de arriba
para poder leerla aquí.

## Las escrituras {#writes}

Los tags cuyo **Acceso** es Lectura y escritura o Solo escritura se pueden escribir.
Una escritura resuelve el mismo símbolo y escribe los bytes del valor: 1 byte para
Boolean, 4 bytes para Int32 y Float. Una escritura de String deja toda la **Longitud de
lectura** del tag: los bytes UTF-8 del texto al frente y ceros detrás, así que un texto
más corto escrito sobre uno más largo reemplaza el valor entero y no sobrevive nada del
anterior. Un texto que no cabe en la longitud declarada se rechaza, con la longitud
nombrada en el diario técnico, nunca se recorta para que quepa. Un tag nuevo arranca como
Solo lectura.

Una escritura que el PLC rechaza, como la de un símbolo que no deja escribir, regresa
rechazada con el código de error ADS y lo que significa, por ejemplo
`ADS error 0x704 (the symbol may not be written)`, y la conexión sigue arriba.

## El descubrimiento {#discovery}

En este driver ADS no tiene descubrimiento por difusión, así que el Connector no muestra
botón Descubrir. Agregue el dispositivo y sus símbolos a mano.

## Bueno saber {#good-to-know}

- La ruta AMS es el motivo habitual por el que falla una primera conexión: el AMS Net Id
  de la ruta en el PLC tiene que ser exactamente la IP de la estación más `.1.1`, y la
  página del dispositivo da la ruta entera que hay que agregar.
- El driver le pide al PLC un handle para cada símbolo una vez por conexión y devuelve
  los handles cuando la conexión se cierra. Después de una descarga al PLC, un handle que
  el PLC ya no acepta se reemplaza en la siguiente lectura, así que el tag sigue leyendo
  con el programa nuevo; un símbolo que la descarga renombró o quitó deja su tag sin
  valor, con `ADS error 0x710 (no symbol by that name)`, hasta que los nombres vuelvan a
  coincidir.
- Un PLC inalcanzable no cuesta nada al arrancar: el dispositivo sigue reintentando en
  segundo plano y sus tags se leen con mala calidad hasta que la conexión llega.