2024.11.2
Home ▸ Integrations ▸

ADS

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.

There is currently support for the following device types within Home Assistant:

Configuration

To enable ADS, add the following lines to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.

# Example configuration.yaml entry
ads:
  device: "127.0.0.1.1.1"
  port: 801

Configuration Variables

Looking for your configuration file?
device string Required

The AMS NetId that identifies the device.

port integer Required

The port that runs the AMS server on the device, typically this would be 801 or 851.

ip_address string (Optional)

The IP address of the ADS device, if not set the first 4 bytes of the device id will be used.

Action

The ADS integration will register the write_by_name action allowing you to write a value to a variable on your ADS device.

{
    "adsvar": ".myvariable",
    "adstype": "int",
    "value": 123
}

Action parameters:

  • adsvar: Name of the variable on the ADS device. To access global variables on TwinCAT2 use a prepending dot .myvariable, for TwinCAT3 use GBL.myvariable.
  • adstype: Specify the type of the variable. Use one of the following: int, byte, uint, bool
  • value: The value that will be written in the variable.

Binary sensor

The ads binary sensor platform can be used to monitor a boolean value on your ADS device.

To use your ADS device, you first have to set up your ADS hub and then add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
binary_sensor:
  - platform: ads
    adsvar: .boolean1

Configuration Variables

Looking for your configuration file?
adsvar string Required

The name of the variable which you want to access on the ADS device.

name string (Optional)

An identifier for the light in the frontend.

device_class string (Optional)

Sets the class of the device, changing the device state and icon that is displayed on the frontend.

Light

The ads light platform allows you to control your connected ADS lights.

To use your ADS device, you first have to set up your ADS hub and then add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
light:
  - platform: ads
    adsvar: GVL.enable_light
    adsvar_brightness: GVL.brightness

Configuration Variables

Looking for your configuration file?
adsvar string Required

The name of the boolean variable that switches the light on

adsvar_brightness string (Optional)

The name of the variable that controls the brightness, use an unsigned integer on the PLC side

name string (Optional)

An identifier for the Light in the frontend

Sensor

The ads sensor platform allows reading the value of a numeric variable on your ADS device. The variable can be of type BOOL, BYTE, INT, UINT, SINT, USINT, DINT, UDINT, WORD, DWORD, REAL, or LREAL.

To use your ADS device, you first have to set up your ADS hub and then add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
sensor:
  - platform: ads
    adsvar: GVL.temperature
    unit_of_measurement: "°C"
    adstype: int

Configuration Variables

Looking for your configuration file?
adsvar string Required

The name of the variable which you want to access.

adstype string (Optional, default: int)

The datatype of the ADS variable, possible values are bool, byte, int, uint, sint, usint, dint, udint, word, dword, real and lreal.

name string (Optional)

An identifier for the sensor.

factor integer (Optional, default: 1)

A factor that divides the stored value before displaying in Home Assistant.

The factor can be used to implement fixed decimals. E.g., set factor to 100 if you want to display a fixed decimal value with two decimals. A variable value of 123 will be displayed as 1.23.

Switch

The ads switch platform accesses a boolean variable on the connected ADS device. The variable is identified by its name.

To use your ADS device, you first have to set up your ADS hub and then add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
switch:
  - platform: ads
    adsvar: .global_bool

Configuration Variables

Looking for your configuration file?
adsvar string Required

The name of the variable which you want to access on the ADS device.

name string (Optional)

An identifier for the switch in the frontend.

Cover

The ads cover platform allows you to control your connected ADS covers.

To use your ADS device, you first have to set up your ADS hub and then add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
cover:
  - platform: ads
    name: Curtain master bed room
    adsvar: covers.master_bed_room_is_closed
    adsvar_open: covers.master_bed_room_open
    adsvar_close: covers.master_bed_room_close
    adsvar_stop: covers.master_bed_room_stop
    device_class: curtain

Configuration Variables

Looking for your configuration file?
adsvar string Required

The name of the boolean variable that returns the current status of the cover (True = closed)

adsvar_position string (Optional)

The name of the variable that returns the current cover position, use a byte variable on the PLC side

adsvar_set_position string (Optional)

The name of the variable that sets the new cover position, use a byte variable on the PLC side

adsvar_open string (Optional)

The name of the boolean variable that triggers the cover to open

adsvar_close string (Optional)

The name of the boolean variable that triggers the cover to close

adsvar_stop string (Optional)

The name of the boolean variable that triggers the cover to stop

name string (Optional)

An identifier for the Cover in the frontend

device_class device_class (Optional)

Sets the class of the device, changing the device state and icon that is displayed on the frontend.

Select

The ads select entity accesses an ENUM (int) variable on the connected ADS device. The variable is identified by its name. You have to set up a corresponding ENUM in the TwinCAT PLC. It is recommended to use explicit values starting from 0.

TYPE E_SampleA :
(
    e1 := 0,
    e2 := 1,
    e3 := 2, 
);
END_TYPE

Valve

The ads valve entity accesses a boolean variable on the connected ADS device. The variable is identified by its name.

To use your ADS device, you first have to set up your ADS hub and then add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
select:
  - platform: ads
    adsvar: MAIN.eMyEnum
    options:
      - "Off"
      - "Setup"
      - "Automatic"
      - "Manual"
      - "Guest"
      - "Error"
valve:
  - platform: ads
    adsvar: MAIN.bValveControl

Configuration Variables

Looking for your configuration file?
adsvar string Required

The name of the variable which you want to access on the ADS device.

options string Required

The available options to select from.

name string (Optional)

An identifier for the valve in the frontend.

Related topics