From 985827fd7f93079563646620f3b75d9659045636 Mon Sep 17 00:00:00 2001 From: Vladimir Zahradnik Date: Thu, 2 Apr 2020 21:46:23 +0200 Subject: [PATCH 1/2] Add documentation for Modbus light and fan --- source/_integrations/fan.modbus.markdown | 139 +++++++++++++++++++++ source/_integrations/light.modbus.markdown | 139 +++++++++++++++++++++ source/_integrations/modbus.markdown | 2 + 3 files changed, 280 insertions(+) create mode 100644 source/_integrations/fan.modbus.markdown create mode 100644 source/_integrations/light.modbus.markdown diff --git a/source/_integrations/fan.modbus.markdown b/source/_integrations/fan.modbus.markdown new file mode 100644 index 000000000000..4efcd71f01ac --- /dev/null +++ b/source/_integrations/fan.modbus.markdown @@ -0,0 +1,139 @@ +--- +title: "Modbus Fan" +description: "Instructions on how to integrate Modbus fans into Home Assistant." +ha_category: + - Fan +ha_release: 0.109 +ha_iot_class: Local Push +ha_domain: modbus +--- + +The `modbus` fan platform allows you to control [Modbus](http://www.modbus.org/)-enabled fans. We support two types of Modbus fans — coil-based and register-based. Note that our implementation of Modbus register fan supports only holding registers, because input registers are not writable, and don't give us any control over connected fans. + +## Configuration + +To enable Modbus fans in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +fan: + platform: modbus + coils: + - name: Fan1 + hub: hub1 + slave: 1 + coil: 13 + - name: Fan2 + slave: 2 + coil: 14 + registers: + - name: Fan3 + hub: hub1 + slave: 1 + register: 11 +``` + +{% configuration %} +coils: + description: A list of relevant coils to read from/write to. + required: false + type: map + keys: + hub: + description: The name of the hub. + required: false + default: default + type: string + slave: + description: The number of the slave (can be omitted for tcp and udp Modbus). + required: true + type: integer + name: + description: Name of the switch. + required: true + type: string + coil: + description: Coil number. + required: true + type: integer +registers: + description: A list of relevant registers to read from/write to. + required: false + type: map + keys: + hub: + description: The hub to use. + required: false + default: default + type: string + slave: + description: The number of the slave (can be omitted for tcp and udp Modbus). + required: true + type: integer + name: + description: Name of the switch. + required: true + type: string + register: + description: Register number. + required: true + type: integer + command_on: + description: Value to write to turn on the switch. + required: false + default: 1 + type: integer + command_off: + description: Value to write to turn off the switch. + required: false + default: 0 + type: integer + verify_state: + description: Define if is possible to readback the status of the switch. + required: false + default: true + type: boolean +{% endconfiguration %} + +It's possible to change the default 30 seconds scan interval for the switch state updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation. + +## Examples + +In this section, you find some real-life examples of how to use this fan. + +### Full configuration for a Modbus coil fan + +The example below shows a full configuration for a Modbus coil fan, for which the state is polled from Modbus every 10 seconds. + +```yaml +fan: + platform: modbus + scan_interval: 10 + coils: + - name: Fan1 + hub: hub1 + slave: 1 + coil: 13 + - name: Fan2 + hub: hub1 + slave: 2 + coil: 14 +``` + +### Full configuration for a Modbus register fan + +The example below shows a full configuration for a Modbus register fan, for which the state is polled from Modbus every 15 seconds. + +```yaml +fan: + platform: modbus + scan_interval: 15 + registers: + - name: Fan1 + hub: hub1 + slave: 1 + register: 11 + command_on: 1 + command_off: 0, + verify_state: true +``` \ No newline at end of file diff --git a/source/_integrations/light.modbus.markdown b/source/_integrations/light.modbus.markdown new file mode 100644 index 000000000000..491d416f6bad --- /dev/null +++ b/source/_integrations/light.modbus.markdown @@ -0,0 +1,139 @@ +--- +title: "Modbus Light" +description: "Instructions on how to integrate Modbus lights into Home Assistant." +ha_category: + - Light +ha_release: 0.109 +ha_iot_class: Local Push +ha_domain: modbus +--- + +The `modbus` light platform allows you to control [Modbus](http://www.modbus.org/)-enabled lights. We support two types of Modbus lights — coil-based and register-based. Note that our implementation of Modbus register light supports only holding registers, because input registers are not writable, and don't give us any control over connected lights. + +## Configuration + +To enable Modbus lights in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +light: + platform: modbus + coils: + - name: Light1 + hub: hub1 + slave: 1 + coil: 13 + - name: Light2 + slave: 2 + coil: 14 + registers: + - name: Light3 + hub: hub1 + slave: 1 + register: 11 +``` + +{% configuration %} +coils: + description: A list of relevant coils to read from/write to. + required: false + type: map + keys: + hub: + description: The name of the hub. + required: false + default: default + type: string + slave: + description: The number of the slave (can be omitted for tcp and udp Modbus). + required: true + type: integer + name: + description: Name of the switch. + required: true + type: string + coil: + description: Coil number. + required: true + type: integer +registers: + description: A list of relevant registers to read from/write to. + required: false + type: map + keys: + hub: + description: The hub to use. + required: false + default: default + type: string + slave: + description: The number of the slave (can be omitted for tcp and udp Modbus). + required: true + type: integer + name: + description: Name of the switch. + required: true + type: string + register: + description: Register number. + required: true + type: integer + command_on: + description: Value to write to turn on the switch. + required: false + default: 1 + type: integer + command_off: + description: Value to write to turn off the switch. + required: false + default: 0 + type: integer + verify_state: + description: Define if is possible to readback the status of the switch. + required: false + default: true + type: boolean +{% endconfiguration %} + +It's possible to change the default 30 seconds scan interval for the switch state updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation. + +## Examples + +In this section, you find some real-life examples of how to use this light. + +### Full configuration for a Modbus coil light + +The example below shows a full configuration for a Modbus coil light, for which the state is polled from Modbus every 10 seconds. + +```yaml +light: + platform: modbus + scan_interval: 10 + coils: + - name: Light1 + hub: hub1 + slave: 1 + coil: 13 + - name: Light2 + hub: hub1 + slave: 2 + coil: 14 +``` + +### Full configuration for a Modbus register light + +The example below shows a full configuration for a Modbus register light, for which the state is polled from Modbus every 15 seconds. + +```yaml +light: + platform: modbus + scan_interval: 15 + registers: + - name: Light1 + hub: hub1 + slave: 1 + register: 11 + command_on: 1 + command_off: 0, + verify_state: true +``` \ No newline at end of file diff --git a/source/_integrations/modbus.markdown b/source/_integrations/modbus.markdown index 5692e4a753f1..ce757d399b1d 100644 --- a/source/_integrations/modbus.markdown +++ b/source/_integrations/modbus.markdown @@ -187,3 +187,5 @@ and restart Home Assistant, reproduce the problem, and include the log in the is - [Modbus Climate](/integrations/climate.modbus/) - [Modbus Sensor](/integrations/sensor.modbus/) - [Modbus Switch](/integrations/switch.modbus/) + - [Modbus Fan](/integrations/fan.modbus/) + - [Modbus Light](/integrations/light.modbus/) From 6df0f6b2ce070da3fc90820b8e637db8dcbba4d3 Mon Sep 17 00:00:00 2001 From: Vladimir Zahradnik Date: Sun, 27 Sep 2020 15:32:29 +0200 Subject: [PATCH 2/2] Update Modbus Fan and Lights docs for new config changes --- source/_integrations/fan.modbus.markdown | 142 ++++++++++----------- source/_integrations/light.modbus.markdown | 142 ++++++++++----------- 2 files changed, 130 insertions(+), 154 deletions(-) diff --git a/source/_integrations/fan.modbus.markdown b/source/_integrations/fan.modbus.markdown index 4efcd71f01ac..320d00e3ee2c 100644 --- a/source/_integrations/fan.modbus.markdown +++ b/source/_integrations/fan.modbus.markdown @@ -3,8 +3,8 @@ title: "Modbus Fan" description: "Instructions on how to integrate Modbus fans into Home Assistant." ha_category: - Fan -ha_release: 0.109 -ha_iot_class: Local Push +ha_release: 0.116 +ha_iot_class: Local Polling ha_domain: modbus --- @@ -16,87 +16,69 @@ To enable Modbus fans in your installation, add the following to your `configura ```yaml # Example configuration.yaml entry -fan: - platform: modbus - coils: - - name: Fan1 - hub: hub1 - slave: 1 - coil: 13 - - name: Fan2 - slave: 2 - coil: 14 - registers: - - name: Fan3 - hub: hub1 - slave: 1 - register: 11 +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + + fans: + - name: Fan1 + slave: 1 + coil: 0 + scan_interval: 10 + - name: Fan2 + register: 0 + command_on: 1 + command_off: 0 + scan_interval: 10 ``` {% configuration %} -coils: - description: A list of relevant coils to read from/write to. - required: false +fans: + description: The array contains a list of all your Modbus fans. + required: true type: map keys: - hub: - description: The name of the hub. - required: false - default: default - type: string - slave: - description: The number of the slave (can be omitted for tcp and udp Modbus). - required: true - type: integer name: - description: Name of the switch. + description: Name of the fan. required: true type: string - coil: - description: Coil number. - required: true - type: integer -registers: - description: A list of relevant registers to read from/write to. - required: false - type: map - keys: - hub: - description: The hub to use. - required: false - default: default - type: string slave: description: The number of the slave (can be omitted for tcp and udp Modbus). - required: true + required: false + default: 1 type: integer - name: - description: Name of the switch. + coil: + description: Coil address; can be omitted if a register attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. required: true - type: string + type: integer register: - description: Register number. + description: Holding register address; can be omitted if a coil attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. required: true type: integer command_on: - description: Value to write to turn on the switch. + description: Value to write to turn on the fan. This value can be specified only for register-based fans. required: false default: 1 type: integer command_off: - description: Value to write to turn off the switch. + description: Value to write to turn off the fan. This value can be specified only for register-based fans. required: false default: 0 type: integer verify_state: - description: Define if is possible to readback the status of the switch. + description: Define if is possible to readback the status of the fan. required: false default: true type: boolean + scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: integer + default: 15 {% endconfiguration %} -It's possible to change the default 30 seconds scan interval for the switch state updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation. - ## Examples In this section, you find some real-life examples of how to use this fan. @@ -106,18 +88,21 @@ In this section, you find some real-life examples of how to use this fan. The example below shows a full configuration for a Modbus coil fan, for which the state is polled from Modbus every 10 seconds. ```yaml -fan: - platform: modbus - scan_interval: 10 - coils: - - name: Fan1 - hub: hub1 - slave: 1 - coil: 13 - - name: Fan2 - hub: hub1 - slave: 2 - coil: 14 +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + + fans: + - name: Fan1 + slave: 1 + coil: 13 + scan_interval: 10 + - name: Fan2 + slave: 2 + coil: 14 + scan_interval: 10 ``` ### Full configuration for a Modbus register fan @@ -125,15 +110,18 @@ fan: The example below shows a full configuration for a Modbus register fan, for which the state is polled from Modbus every 15 seconds. ```yaml -fan: - platform: modbus - scan_interval: 15 - registers: - - name: Fan1 - hub: hub1 - slave: 1 - register: 11 - command_on: 1 - command_off: 0, - verify_state: true +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + + fans: + - name: Fan1 + slave: 1 + register: 11 + command_on: 1 + command_off: 0 + verify_state: true + scan_interval: 15 ``` \ No newline at end of file diff --git a/source/_integrations/light.modbus.markdown b/source/_integrations/light.modbus.markdown index 491d416f6bad..0bc388558838 100644 --- a/source/_integrations/light.modbus.markdown +++ b/source/_integrations/light.modbus.markdown @@ -3,8 +3,8 @@ title: "Modbus Light" description: "Instructions on how to integrate Modbus lights into Home Assistant." ha_category: - Light -ha_release: 0.109 -ha_iot_class: Local Push +ha_release: 0.116 +ha_iot_class: Local Polling ha_domain: modbus --- @@ -16,87 +16,69 @@ To enable Modbus lights in your installation, add the following to your `configu ```yaml # Example configuration.yaml entry -light: - platform: modbus - coils: - - name: Light1 - hub: hub1 - slave: 1 - coil: 13 - - name: Light2 - slave: 2 - coil: 14 - registers: - - name: Light3 - hub: hub1 - slave: 1 - register: 11 +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + + lights: + - name: Light1 + slave: 1 + coil: 0 + scan_interval: 10 + - name: Light2 + register: 0 + command_on: 1 + command_off: 0 + scan_interval: 10 ``` {% configuration %} -coils: - description: A list of relevant coils to read from/write to. - required: false +lights: + description: The array contains a list of all your Modbus lights. + required: true type: map keys: - hub: - description: The name of the hub. - required: false - default: default - type: string - slave: - description: The number of the slave (can be omitted for tcp and udp Modbus). - required: true - type: integer name: - description: Name of the switch. + description: Name of the light. required: true type: string - coil: - description: Coil number. - required: true - type: integer -registers: - description: A list of relevant registers to read from/write to. - required: false - type: map - keys: - hub: - description: The hub to use. - required: false - default: default - type: string slave: description: The number of the slave (can be omitted for tcp and udp Modbus). - required: true + required: false + default: 1 type: integer - name: - description: Name of the switch. + coil: + description: Coil address; can be omitted if a register attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. required: true - type: string + type: integer register: - description: Register number. + description: Holding register address; can be omitted if a coil attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. required: true type: integer command_on: - description: Value to write to turn on the switch. + description: Value to write to turn on the light. This value can be specified only for register-based lights. required: false default: 1 type: integer command_off: - description: Value to write to turn off the switch. + description: Value to write to turn off the light. This value can be specified only for register-based lights. required: false default: 0 type: integer verify_state: - description: Define if is possible to readback the status of the switch. + description: Define if is possible to readback the status of the light. required: false default: true type: boolean + scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: integer + default: 15 {% endconfiguration %} -It's possible to change the default 30 seconds scan interval for the switch state updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation. - ## Examples In this section, you find some real-life examples of how to use this light. @@ -106,18 +88,21 @@ In this section, you find some real-life examples of how to use this light. The example below shows a full configuration for a Modbus coil light, for which the state is polled from Modbus every 10 seconds. ```yaml -light: - platform: modbus - scan_interval: 10 - coils: - - name: Light1 - hub: hub1 - slave: 1 - coil: 13 - - name: Light2 - hub: hub1 - slave: 2 - coil: 14 +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + + lights: + - name: Light1 + slave: 1 + coil: 13 + scan_interval: 10 + - name: Light2 + slave: 2 + coil: 14 + scan_interval: 10 ``` ### Full configuration for a Modbus register light @@ -125,15 +110,18 @@ light: The example below shows a full configuration for a Modbus register light, for which the state is polled from Modbus every 15 seconds. ```yaml -light: - platform: modbus - scan_interval: 15 - registers: - - name: Light1 - hub: hub1 - slave: 1 - register: 11 - command_on: 1 - command_off: 0, - verify_state: true +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + + lights: + - name: Light1 + slave: 1 + register: 11 + command_on: 1 + command_off: 0 + verify_state: true + scan_interval: 15 ``` \ No newline at end of file