From ebc11d71ed78016cac1bdc547bafae3ea4c8c4a3 Mon Sep 17 00:00:00 2001 From: Shay Levy Date: Sat, 2 Apr 2022 15:59:28 +0300 Subject: [PATCH] Document new configuration with unique id support (#41) --- README.md | 101 ++++++++++++++++++++++++++++------------------- info.md | 101 ++++++++++++++++++++++++++++------------------- legacy-config.md | 92 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+), 80 deletions(-) create mode 100644 legacy-config.md diff --git a/README.md b/README.md index 9ca913e..23dd183 100644 --- a/README.md +++ b/README.md @@ -22,37 +22,47 @@ The `rpi_gpio` binary sensor platform allows you to read sensor values of the GP ### Configuration +[Legacy binary sensor configuration](https://github.com/thecode/ha-rpi_gpio/blob/main/legacy-config.md#binary-sensor) + To use your Raspberry Pi's GPIO in your installation, add the following to your `configuration.yaml` file: ```yaml # Basic configuration.yaml entry binary_sensor: - platform: rpi_gpio - ports: - 11: PIR Office - 12: PIR Bedroom + sensors: + - port: 11 + name: "PIR Office" + - port: 12 + name: "PIR Bedroom" ``` ```yaml # Full configuration.yaml entry binary_sensor: - platform: rpi_gpio - bouncetime: 80 - invert_logic: true - pull_mode: "DOWN" - ports: - 11: PIR Office - 12: PIR Bedroom + sensors: + - port: 11 + name: "PIR Office" + unique_id: "pir_office_sensor_port_11" + bouncetime: 80 + invert_logic: true + pull_mode: "DOWN" + - port: 12 + name: "PIR Bedroom" + unique_id: "pir_bedroom_sensor_port_12" ``` ### Options -| Key | Required | Default | Type | Description | -| -------------- | -------- | --------------------- | --------|------------------------------------------------------------------ | -| `bouncetime` | no | `50` | integer | The time in milliseconds for port debouncing | -| `invert_logic` | no | `false` (ACTIVE HIGH) | boolean | If `true`, inverts the output logic to ACTIVE LOW | -| `pull_mode` | no | `UP` | string | Type of internal pull resistor to use: `UP` - pull-up resistor, `DOWN` - pull-down resistor | -| `ports` | yes | | list | List of used ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) and corresponding names | +| Key | Required | Default | Type | Description | +| -------------- | -------- | --------------------- | --------|------------------------------------------------------------------------------------------------------------ | +| `sensors` | yes | | list | List of sensor IO ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) | +| `name` | yes | | string | The name for the binary sensor entity | +| `unique_id` | no | | string | An ID that uniquely identifies the sensor. Set this to a unique value to allow customization through the UI | +| `bouncetime` | no | `50` | integer | The time in milliseconds for port debouncing | +| `invert_logic` | no | `false` (ACTIVE HIGH) | boolean | If `true`, inverts the output logic to ACTIVE LOW | +| `pull_mode` | no | `UP` | string | Type of internal pull resistor to use: `UP` - pull-up resistor, `DOWN` - pull-down resistor | For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#General_purpose_input-output_(GPIO)_connector) about the Raspberry Pi. @@ -94,20 +104,22 @@ cover: - relay_pin: 12 state_pin: 13 name: "Right door" + unique_id: "right_door_cover_port_13" ``` ### Options -| Key | Required | Default | Type | Description | -| ----------------- | -------- | ------- | ------- | ---------------------------------------------------------------- | -| `relay_time` | no | `0.2` | float | The time that the relay will be on for in seconds | -| `invert_relay` | no | `false` | boolean | Invert the relay pin output so that it is active-high (True) | -| `state_pull_mode` | no | `UP` | string | The direction the State pin is pulling. It can be `UP` or `DOWN` | -| `invert_state` | no | `false` | boolean | Invert the value of the State pin so that 0 means closed | -| `covers` | yes | | list | List of covers | -| `relay_pin` | yes | | integer | The pin of your Raspberry Pi where the relay is connected | -| `state_pin` | yes | | integer | The pin of your Raspberry Pi to retrieve the state | -| `name` | no | | string | The name for the cover entity | +| Key | Required | Default | Type | Description | +| ----------------- | -------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------- | +| `relay_time` | no | `0.2` | float | The time that the relay will be on for in seconds | +| `invert_relay` | no | `false` | boolean | Invert the relay pin output so that it is active-high (True) | +| `state_pull_mode` | no | `UP` | string | The direction the State pin is pulling. It can be `UP` or `DOWN` | +| `invert_state` | no | `false` | boolean | Invert the value of the State pin so that 0 means closed | +| `covers` | yes | | list | List of covers | +| `relay_pin` | yes | | integer | The pin of your Raspberry Pi where the relay is connected | +| `state_pin` | yes | | integer | The pin of your Raspberry Pi to retrieve the state | +| `name` | no | | string | The name for the cover entity | +| `unique_id` | no | | string | An ID that uniquely identifies the cover. Set this to a unique value to allow customization through the UI | ### Remote Raspberry Pi Cover @@ -119,38 +131,46 @@ The `rpi_gpio` switch platform allows you to control the GPIOs of your [Raspberr ### Configuration +[Legacy switch configuration](https://github.com/thecode/ha-rpi_gpio/blob/main/legacy-config.md#switch) + To use your Raspberry Pi's GPIO in your installation, add the following to your `configuration.yaml` file: ```yaml # Basic configuration.yaml entry switch: - platform: rpi_gpio - ports: - 11: Fan Office - 12: Light Desk + switches: + - port: 11 + name: "Fan Office" + - port: 12 + name: "Light Desk" ``` ```yaml # Full configuration.yaml entry switch: - platform: rpi_gpio - invert_logic: true - ports: - 11: Fan Office - 12: Light Desk + switches: + - port: 11 + name: "Fan Office" + unique_id: "fan_office_switch_port_11" + - port: 12 + name: "Light Desk" + unique_id: "light_desk_switch_port_12" + invert_logic: true ``` ### Options -| Key | Required | Default | Type | Description | -| -------------- | -------- | ------- | --------------- | --------------------------------------------------- | -| `invert_logic` | no | `false` | boolean | If true, inverts the output logic to ACTIVE LOW | -| `ports` | yes | | list | List of used ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) and corresponding names | +| Key | Required | Default | Type | Description | +| -------------- | -------- | ------- | --------| ----------------------------------------------------------------------------------------------------------- | +| `switches` | yes | | list | List of switch IO ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) | +| `name` | yes | | string | The name for the switch entity | +| `unique_id` | no | | string | An ID that uniquely identifies the switch. Set this to a unique value to allow customization through the UI | +| `invert_logic` | no | `false` | boolean | If true, inverts the output logic to ACTIVE LOW | For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#General_purpose_input-output_(GPIO)_connector) about the Raspberry Pi. -**Note that a pin managed by Home Assistant is expected to be exclusive to Home Assistant.** - A common question is what does Port refer to, this number is the actual GPIO #, not the pin #. For example, if you have a relay connected to pin 11 its GPIO # is 17. @@ -158,6 +178,7 @@ For example, if you have a relay connected to pin 11 its GPIO # is 17. # Basic configuration.yaml entry switch: - platform: rpi_gpio - ports: - 17: Speaker Relay + switches: + - port: 17 + name: "Speaker Relay" ``` diff --git a/info.md b/info.md index 8c86e75..f8578a3 100644 --- a/info.md +++ b/info.md @@ -10,37 +10,47 @@ The `rpi_gpio` binary sensor platform allows you to read sensor values of the GP ### Configuration +[Legacy binary sensor configuration](https://github.com/thecode/ha-rpi_gpio/blob/main/legacy-config.md#binary-sensor) + To use your Raspberry Pi's GPIO in your installation, add the following to your `configuration.yaml` file: ```yaml # Basic configuration.yaml entry binary_sensor: - platform: rpi_gpio - ports: - 11: PIR Office - 12: PIR Bedroom + sensors: + - port: 11 + name: "PIR Office" + - port: 12 + name: "PIR Bedroom" ``` ```yaml # Full configuration.yaml entry binary_sensor: - platform: rpi_gpio - bouncetime: 80 - invert_logic: true - pull_mode: "DOWN" - ports: - 11: PIR Office - 12: PIR Bedroom + sensors: + - port: 11 + name: "PIR Office" + unique_id: "pir_office_sensor_port_11" + bouncetime: 80 + invert_logic: true + pull_mode: "DOWN" + - port: 12 + name: "PIR Bedroom" + unique_id: "pir_bedroom_sensor_port_12" ``` ### Options -| Key | Required | Default | Type | Description | -| -------------- | -------- | --------------------- | --------|------------------------------------------------------------------ | -| `bouncetime` | no | `50` | integer | The time in milliseconds for port debouncing | -| `invert_logic` | no | `false` (ACTIVE HIGH) | boolean | If `true`, inverts the output logic to ACTIVE LOW | -| `pull_mode` | no | `UP` | string | Type of internal pull resistor to use: `UP` - pull-up resistor, `DOWN` - pull-down resistor | -| `ports` | yes | | list | List of used ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) and corresponding names | +| Key | Required | Default | Type | Description | +| -------------- | -------- | --------------------- | --------|------------------------------------------------------------------------------------------------------------ | +| `sensors` | yes | | list | List of sensor IO ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) | +| `name` | yes | | string | The name for the binary sensor entity | +| `unique_id` | no | | string | An ID that uniquely identifies the sensor. Set this to a unique value to allow customization through the UI | +| `bouncetime` | no | `50` | integer | The time in milliseconds for port debouncing | +| `invert_logic` | no | `false` (ACTIVE HIGH) | boolean | If `true`, inverts the output logic to ACTIVE LOW | +| `pull_mode` | no | `UP` | string | Type of internal pull resistor to use: `UP` - pull-up resistor, `DOWN` - pull-down resistor | For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#General_purpose_input-output_(GPIO)_connector) about the Raspberry Pi. @@ -82,20 +92,22 @@ cover: - relay_pin: 12 state_pin: 13 name: "Right door" + unique_id: "right_door_cover_port_13" ``` ### Options -| Key | Required | Default | Type | Description | -| ----------------- | -------- | ------- | ------- | ---------------------------------------------------------------- | -| `relay_time` | no | `0.2` | float | The time that the relay will be on for in seconds | -| `invert_relay` | no | `false` | boolean | Invert the relay pin output so that it is active-high (True) | -| `state_pull_mode` | no | `UP` | string | The direction the State pin is pulling. It can be `UP` or `DOWN` | -| `invert_state` | no | `false` | boolean | Invert the value of the State pin so that 0 means closed | -| `covers` | yes | | list | List of covers | -| `relay_pin` | yes | | integer | The pin of your Raspberry Pi where the relay is connected | -| `state_pin` | yes | | integer | The pin of your Raspberry Pi to retrieve the state | -| `name` | no | | string | The name for the cover entity | +| Key | Required | Default | Type | Description | +| ----------------- | -------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------- | +| `relay_time` | no | `0.2` | float | The time that the relay will be on for in seconds | +| `invert_relay` | no | `false` | boolean | Invert the relay pin output so that it is active-high (True) | +| `state_pull_mode` | no | `UP` | string | The direction the State pin is pulling. It can be `UP` or `DOWN` | +| `invert_state` | no | `false` | boolean | Invert the value of the State pin so that 0 means closed | +| `covers` | yes | | list | List of covers | +| `relay_pin` | yes | | integer | The pin of your Raspberry Pi where the relay is connected | +| `state_pin` | yes | | integer | The pin of your Raspberry Pi to retrieve the state | +| `name` | no | | string | The name for the cover entity | +| `unique_id` | no | | string | An ID that uniquely identifies the cover. Set this to a unique value to allow customization through the UI | ### Remote Raspberry Pi Cover @@ -107,38 +119,46 @@ The `rpi_gpio` switch platform allows you to control the GPIOs of your [Raspberr ### Configuration +[Legacy switch configuration](https://github.com/thecode/ha-rpi_gpio/blob/main/legacy-config.md#switch) + To use your Raspberry Pi's GPIO in your installation, add the following to your `configuration.yaml` file: ```yaml # Basic configuration.yaml entry switch: - platform: rpi_gpio - ports: - 11: Fan Office - 12: Light Desk + switches: + - port: 11 + name: "Fan Office" + - port: 12 + name: "Light Desk" ``` ```yaml # Full configuration.yaml entry switch: - platform: rpi_gpio - invert_logic: true - ports: - 11: Fan Office - 12: Light Desk + switches: + - port: 11 + name: "Fan Office" + unique_id: "fan_office_switch_port_11" + - port: 12 + name: "Light Desk" + unique_id: "light_desk_switch_port_12" + invert_logic: true ``` ### Options -| Key | Required | Default | Type | Description | -| -------------- | -------- | ------- | --------------- | --------------------------------------------------- | -| `invert_logic` | no | `false` | boolean | If true, inverts the output logic to ACTIVE LOW | -| `ports` | yes | | list | List of used ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) and corresponding names | +| Key | Required | Default | Type | Description | +| -------------- | -------- | ------- | --------| ----------------------------------------------------------------------------------------------------------- | +| `switches` | yes | | list | List of switch IO ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) | +| `name` | yes | | string | The name for the switch entity | +| `unique_id` | no | | string | An ID that uniquely identifies the switch. Set this to a unique value to allow customization through the UI | +| `invert_logic` | no | `false` | boolean | If true, inverts the output logic to ACTIVE LOW | For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#General_purpose_input-output_(GPIO)_connector) about the Raspberry Pi. -**Note that a pin managed by Home Assistant is expected to be exclusive to Home Assistant.** - A common question is what does Port refer to, this number is the actual GPIO #, not the pin #. For example, if you have a relay connected to pin 11 its GPIO # is 17. @@ -146,6 +166,7 @@ For example, if you have a relay connected to pin 11 its GPIO # is 17. # Basic configuration.yaml entry switch: - platform: rpi_gpio - ports: - 17: Speaker Relay + switches: + - port: 17 + name: "Speaker Relay" ``` diff --git a/legacy-config.md b/legacy-config.md new file mode 100644 index 0000000..06d468e --- /dev/null +++ b/legacy-config.md @@ -0,0 +1,92 @@ +# Legacy binary sensor and switch configuration + +**This configuration is used for backward compatibility and should not be used for new installations.** + +## Binary Sensor + +The `rpi_gpio` binary sensor platform allows you to read sensor values of the GPIOs of your [Raspberry Pi](https://www.raspberrypi.org/). + +### Configuration + +To use your Raspberry Pi's GPIO in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Basic configuration.yaml entry +binary_sensor: + - platform: rpi_gpio + ports: + 11: PIR Office + 12: PIR Bedroom +``` + +```yaml +# Full configuration.yaml entry +binary_sensor: + - platform: rpi_gpio + bouncetime: 80 + invert_logic: true + pull_mode: "DOWN" + ports: + 11: PIR Office + 12: PIR Bedroom +``` + +### Options + +| Key | Required | Default | Type | Description | +| -------------- | -------- | --------------------- | --------|------------------------------------------------------------------ | +| `bouncetime` | no | `50` | integer | The time in milliseconds for port debouncing | +| `invert_logic` | no | `false` (ACTIVE HIGH) | boolean | If `true`, inverts the output logic to ACTIVE LOW | +| `pull_mode` | no | `UP` | string | Type of internal pull resistor to use: `UP` - pull-up resistor, `DOWN` - pull-down resistor | +| `ports` | yes | | list | List of used ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) and corresponding names | + +For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#General_purpose_input-output_(GPIO)_connector) about the Raspberry Pi. + +## Switch + +The `rpi_gpio` switch platform allows you to control the GPIOs of your [Raspberry Pi](https://www.raspberrypi.org/). + +### Configuration + +To use your Raspberry Pi's GPIO in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Basic configuration.yaml entry +switch: + - platform: rpi_gpio + ports: + 11: Fan Office + 12: Light Desk +``` + +```yaml +# Full configuration.yaml entry +switch: + - platform: rpi_gpio + invert_logic: true + ports: + 11: Fan Office + 12: Light Desk +``` + +### Options + +| Key | Required | Default | Type | Description | +| -------------- | -------- | ------- | --------------- | --------------------------------------------------- | +| `invert_logic` | no | `false` | boolean | If true, inverts the output logic to ACTIVE LOW | +| `ports` | yes | | list | List of used ports ([BCM mode pin numbers](https://pinout.xyz/resources/raspberry-pi-pinout.png)) and corresponding names | + +For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#General_purpose_input-output_(GPIO)_connector) about the Raspberry Pi. + +**Note that a pin managed by Home Assistant is expected to be exclusive to Home Assistant.** + +A common question is what does Port refer to, this number is the actual GPIO #, not the pin #. +For example, if you have a relay connected to pin 11 its GPIO # is 17. + +```yaml +# Basic configuration.yaml entry +switch: + - platform: rpi_gpio + ports: + 17: Speaker Relay +```