Update ADS documentation (#4145)

source/_components/ads.markdown

@@ -7,33 +7,15 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-logo: home-assistant.png
+logo: beckhoff.png
 ha_category: Hub
-ha_release: 0.60
+ha_release: "0.60"
 ha_iot_class: "Local Push"
 ---
 
-The ADS (automation device specification) describes a device-independent and
+The ADS (automation device specification) describes a device-independent and fieldbus independent interface for communication between [Beckhoff](https://www.beckhoff.com/) automation devices running [TwinCAT](http://www.beckhoff.hu/english.asp?twincat/default.htm) and other devices implementing this interface.
-fieldbus-independent interface for communication between Beckhoff® automation
-devices running TwinCAT® and other devices implementing this interface.
-
-Configuration parameters:
-
-{% configuration %}
-  device:
-    required: true
-    description: The AMS NetId that identifies the device
-    type: string
-  port:
-    required: true
-    description: The port that runs the AMS server on the device, typically this would be 801 or 851
-    type: integer
-  ip_address:
-    required: false
-    description: The IP-Address of the ADS device, if not set the first 4 bytes of the device id will be used
-    type: string
-{% endconfiguration %}
 
+To enable ADS, add the following lines to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry
@@ -42,10 +24,24 @@ ads:
   port: 48898
 ```
 
-## Service
+{% configuration %}
+  device:
+    required: true
+    description: The AMS NetId that identifies the device.
+    type: string
+  port:
+    required: true
+    description: The port that runs the AMS server on the device, typically this would be 801 or 851.
+    type: int
+  ip_address:
+    required: false
+    description: The IP address of the ADS device, if not set the first 4 bytes of the device id will be used.
+    type: string
+{% endconfiguration %}
 
-The ADS component will register the service `write_by_name` allowing you to
+## {% linkable_title Service %}
-write a value to a variable on your ADS device.
+
+The ADS component will register the service `write_by_name` allowing you to write a value to a variable on your ADS device.
 
 ```json
 {
@@ -57,9 +53,7 @@ write a value to a variable on your ADS device.
 
 Service parameters:
 
-- **adsvar**: name of the variable on the ADS device. To access global variables
+- **adsvar**: Name of the variable on the ADS device. To access global variables on *TwinCAT2* use a prepending dot `.myvariable`, for TwinCAT3 use
-on *TwinCAT2* use a prepending dot `.myvariable`, for TwinCAT3 use
+`GBL.myvariable`.
-`GBL.myvariable`
+- **adstype**: Specify the type of the variable. Use one of the following: `int`, `byte`, `uint`, `bool`
-- **adstype**: specify the type of the variable. Use one of the following:
+- **value**: The value that will be written in the variable.
-`int`, `byte`, `uint`, `bool`
-- **value**: the value that will be written in the variable

source/_components/binary_sensor.ads.markdown

@@ -7,16 +7,15 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-logo: home-assistant.png
+logo: beckhoff.png
 ha_category: Binary Sensor
-ha_release: 0.60
+ha_release: "0.60"
 ha_iot_class: "Local Push"
 ---
 
-The binary sensor can be used to monitor a boolean value on your ADS device.
+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
+To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
-hub](/components/ads/) and then add the following to your `configuration.yaml`
 file:
 
 ```yaml
@@ -26,19 +25,17 @@ binary_sensor:
     adsvar: .boolean1
 ```
 
-Configuration variables:
-
 {% configuration %}
   adsvar:
     required: true
-    description: The name of the variable which you want to access on the ADS device
+    description: The name of the variable which you want to access on the ADS device.
     type: string
   name: 
     required: false
-    description: An identifier for the light in the frontend
+    description: An identifier for the light in the frontend.
     type: string
   device_class:
     required: false
-    description:  The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend
+    description: The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend.
     type: string
 {% endconfiguration %}

source/_components/light.ads.markdown

@@ -7,14 +7,15 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-logo: home-assistant.png
+logo: beckhoff.png
 ha_category: Light
-ha_release: 0.60
+ha_release: "0.60"
 ha_iot_class: "Local Push"
 ---
 
-To use your ADS device, you first have to set up your [ADS
+The `ads` light platform allows you to control your connecte ADS lights.
-hub](/components/ads/) and then add the following to your `configuration.yaml`
+
+To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
 file:
 
 ```yaml
@@ -25,8 +26,6 @@ light:
     adsvar_brightness: GVL.brightness
 ```
 
-Configuration variables:
-
 {% configuration %}
   adsvar:
     required: true
@@ -40,4 +39,4 @@ Configuration variables:
     required: false
     description: An identifier for the Light in the frontend
     type: string
-{% endconfiguration %}
+{% endconfiguration %}

source/_components/sensor.ads.markdown

@@ -7,17 +7,15 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-logo: home-assistant.png
+logo: beckhoff.png
 ha_category: Sensor
-ha_release: 0.60
+ha_release: "0.60"
 ha_iot_class: "Local Push"
 ---
 
-The `ADS` sensor platform allows reading the value of a numeric variable on
+The `ads` sensor platform allows reading the value of a numeric variable on your ADS device. The variable can be of type *INT*, *UINT* or *BYTE*.
-your ADS device. The variable can be of type *INT*, *UINT* or *BYTE*.
 
-To use your ADS device, you first have to set up your [ADS
+To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
-hub](/components/ads/) and then add the following to your `configuration.yaml`
 file:
 
 ```yaml
@@ -29,29 +27,25 @@ sensor:
     adstype: int
 ```
 
-Configuration variables:
-
 {% configuration %}
   adsvar:
     required: true
-    description: The name of the variable which you want to access
+    description: The name of the variable which you want to access.
     type: string
   adstype:
     required: false
-    description: The datatype of the ADS variable, possible values are int, uint, byte
+    description: The datatype of the ADS variable, possible values are int, uint, byte.
     default: int
     type: string
   name:
     required: false
-    description: An identifier for the sensor
+    description: An identifier for the sensor.
     type: string
   factor:
     required: false
-    description: A factor that divides the stored value before displaying in Home Assistant
+    description: A factor that divides the stored value before displaying in Home Assistant.
     default: 1
     type: integer
 {% endconfiguration %}
 
-The *factor* can be used to implement fixed decimals. E.g., set *factor* to 100
+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`.
-if you want to display a fixed decimal value with two decimals. A variable
-value of `123` will be displayed as `1.23`.

source/_components/switch.ads.markdown

@@ -7,17 +7,15 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-logo: home-assistant.png
+logo: beckhoff.png
 ha_category: Switch
-ha_release: 0.60
+ha_release: "0.60"
 ha_iot_class: "Local Push"
 ---
 
-An ADS switch accesses a boolean variable on the connected ADS device. The
+The `ads` switch platform accesses a boolean variable on the connected ADS device. The variable is identified by its name.
-variable is identified by its name.
 
-To use your ADS device, you first have to set up your [ADS
+To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
-hub](/components/ads/) and then add the following to your `configuration.yaml`
 file:
 
 ```yaml
@@ -26,15 +24,14 @@ switch:
   - platform: ads
     adsvar: .global_bool
 ```
-Configuration variables:
 
 {% configuration %}
   adsvar:
     required: true
-    description: The name of the variable which you want to access on the ADS device
+    description: The name of the variable which you want to access on the ADS device.
     type: string
   name: 
     required: false
-    description: An identifier for the switch in the frontend
+    description: An identifier for the switch in the frontend.
     type: string
-{% endconfiguration %}
+{% endconfiguration %}