Documentation improvements

vmakeev · Feb 12, 2023 · aaebba1 · aaebba1
1 parent 4552f71
commit aaebba1
Show file tree

Hide file tree

Showing 13 changed files with 224 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -4,26 +4,32 @@ Home Assistant custom component for control TP-Link Easy Smart switches over LAN
 
 [![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)
 [![License](https://img.shields.io/github/license/vmakeev/hass_tplink_easy_smart)](https://github.com/vmakeev/hass_tplink_easy_smart/blob/master/LICENSE.md)
+![Active installations](https://raw.githubusercontent.com/vmakeev/custom_badges_updater/main/tplink_easy_smart.svg)
 
 [![Release](https://img.shields.io/github/v/release/vmakeev/hass_tplink_easy_smart)](https://github.com/vmakeev/hass_tplink_easy_smart/releases/latest)
 [![ReleaseDate](https://img.shields.io/github/release-date/vmakeev/hass_tplink_easy_smart)](https://github.com/vmakeev/hass_tplink_easy_smart/releases/latest)
-![Maintained](https://img.shields.io/maintenance/yes/2022)
+![Maintained](https://img.shields.io/maintenance/yes/2023)
 
 ## Key features
 
 - obtaining information about all ports:
   - connection status
   - actual connection speed
   - configured connection speed
+  - Poe status
+  - Poe details (priority, power limits, actual power/current/voltage, power delivery class)
 - ports management:
   - enable or disable specific ports
-- hardware and firmware version of the switch
+  - setting PoE parameters on the specified ports (enable/disable, priority, power limits)
+- obtaining hardware and firmware version of the switch
+- obtaining information about total PoE consumption
+- setting limits on total PoE consumption
 
 ## Supported models
 
 |                                         Name                                          |  Revision | Confirmed |           Notes                         |
 |---------------------------------------------------------------------------------------|-----------|-----------|-----------------------------------------|
-| [TL-SG1016PE](https://www.tp-link.com/en/business-networking/poe-switch/tl-sg1016pe/) |     V1    |    Yes    | All features are available              |
+| [TL-SG1016PE](https://www.tp-link.com/en/business-networking/poe-switch/tl-sg1016pe/) |   V1, V3  |    Yes    | All features are available              |
 | Other Easy Smart switches with web-based user interface                               | --------- |    No     | Will most likely work                   
 
 ## Installation
@@ -40,71 +46,43 @@ Copy `tplink_easy_smart` folder from [latest release](https://github.com/vmakeev
 
 Configuration > [Integrations](https://my.home-assistant.io/redirect/integrations/) > Add Integration > [TP-Link Easy Smart](https://my.home-assistant.io/redirect/config_flow_start/?domain=tplink_easy_smart)
 
+
 ### Advanced options
 
-You can perform advanced component configuration by clicking the `CONFIGURE` button after adding it. Advanced settings include:
-* Data update interval
-* Enabling or disabling [port state switches](#port-state)
+You can perform advanced component configuration by clicking the `CONFIGURE` button after adding it. 
 
-## Sensors
+![Integration](docs/images/integration.png)
 
-### Network information
+Advanced settings include:
+|                                          Name                                           |  Default   |
+|-----------------------------------------------------------------------------------------|------------|
+| Update interval                                                                         | 30 seconds |
+| Enabling or disabling [port state switches](docs/controls.md#port-state-switch)         |  Disabled  |
+| Enabling or disabling [port PoE state switches](docs/controls.md#port-poe-state-switch) |  Disabled  |
 
-The component allows you to get the network information of the switch. 
-The sensor value is the IP address of the switch.
 
-There is one sensor that is always present:
-* `sensor.<integration_name>_network_info`
+![Options 1/2](docs/images/options_1.png)
 
-The sensor exposes the following attributes:
+![Options 2/2](docs/images/options_2.png)
 
-|     Attribute     |          Description          |
-|-------------------|-------------------------------|
-| `mac`             | The MAC address or the switch |
-| `gateway`         | Default gateway               |
-| `netmask`         | Subnet mask                   |
+## Sensors
 
+* Network information ([read more](docs/sensors.md#network-information))
+* PoE consumption ([read more](docs/sensors.md#poe-consumption))
 
 ## Binary sensors
 
-### Port status
-
-The component allows you to get the status of each port.
-
-There are several sensors that are always present:
-* `binary_sensor.<integration_name>_port_<port_number>_state`
+* Port status ([read more](docs/sensors.md#port-status))
+* Port PoE status ([read more](docs/sensors.md#port-poe-status))
 
-Each sensor exposes the following attributes:
-
-|     Attribute        |          Description         |
-|----------------------|------------------------------|
-| `number`             | The number of the port       |
-| `speed`              | Actual connection speed*     |
-| `speed_config`       | Configured connection speed* |
-
-\* the connection speed is represented by the following values:
-
-|    Value    |        Description        |
-|-------------|---------------------------|
-| `Link Down` | The link is down          |
-| `Auto`      | Automatic speed selection |
-| `10MH`      | 10 Mbps, half-duplex      |
-| `10MF`      | 10 Mbps, full duplex      |
-| `100MH`     | 100 Mbps, half-duplex     |
-| `100MF`     | 100 Mbps, full duplex     |
-| `1000MF`    | 1000 Mbps, full duplex    |
-
-_Note: The sensor will be unavailable if the port is not enabled (see [port state switch](#port-state))._
 
 ## Switches
 
-### Port state
-
-The component allows you to enable and disable each port.
+* Port state ([read more](docs/controls.md#port-state-switch))
+* Port PoE state ([read more](docs/controls.md#port-poe-state-switch))
 
-By default, adding these switches is disabled, but you can add them via [options](#advanced-options).
 
-There are several switches:
-* `switch.<integration_name>_port_<port_number>_enabled`
+## Services
 
-_Note: don't use this feature if you don't know what you are doing._
+* Set the PoE power limit ([read more](docs/services.md#set-the-poe-power-limit))
+* Set PoE settings for a specific port ([read more](docs/services.md#set-poe-settings-for-a-specific-port))
diff --git a/docs/controls.md b/docs/controls.md
@@ -0,0 +1,25 @@
+# Controls
+
+## Switches
+
+### Port state switch
+
+The component allows you to enable and disable each port.
+
+By default, adding these switches are disabled, but you can add them via [options](../README.md#advanced-options).
+
+There are several switches:
+* `switch.<integration_name>_port_<port_number>_enabled`
+
+_Note: don't use this feature if you don't know what you are doing._
+
+### Port PoE state switch
+
+The component allows you to enable and disable PoE for each supported port.
+
+By default, adding these switches are disabled, but you can add them via [options](../README.md#advanced-options).
+
+There are several switches:
+* `switch.<integration_name>_port_<port_number>_poe_enabled`
+
+_Note: don't use this feature if you don't know what you are doing._
diff --git a/docs/images/integration.png b/docs/images/integration.png
diff --git a/docs/images/options_1.png b/docs/images/options_1.png
diff --git a/docs/images/options_2.png b/docs/images/options_2.png
diff --git a/docs/images/sensor_network_info.png b/docs/images/sensor_network_info.png
diff --git a/docs/images/sensor_poe_consumption.png b/docs/images/sensor_poe_consumption.png
diff --git a/docs/images/sensor_port_poe_state.png b/docs/images/sensor_port_poe_state.png
diff --git a/docs/images/sensor_port_state.png b/docs/images/sensor_port_state.png
diff --git a/docs/images/service_set_general_poe_limit.png b/docs/images/service_set_general_poe_limit.png
diff --git a/docs/images/service_set_port_poe_settings.png b/docs/images/service_set_port_poe_settings.png
diff --git a/docs/sensors.md b/docs/sensors.md
@@ -0,0 +1,126 @@
+# Sensors
+
+## Network information
+
+The component allows you to get the network information of the switch. 
+The sensor value is the IP address of the switch.
+
+![Network info sensor](images/sensor_network_info.png)
+
+There is one sensor that is always present:
+* `sensor.<integration_name>_network_info`
+
+The sensor exposes the following attributes:
+
+|     Attribute     |          Description          |
+|-------------------|-------------------------------|
+| `mac`             | The MAC address or the switch |
+| `gateway`         | Default gateway               |
+| `netmask`         | Subnet mask                   |
+
+
+## PoE consumption
+
+The component allows you to get the PoE information of the switch. 
+The sensor value is the actual PoE consumption of the switch in watts.
+
+![PoE consumption sensor](images/sensor_poe_consumption.png)
+
+There is one sensor that is always present:
+* `sensor.<integration_name>_poe_consumption`
+
+The sensor exposes the following attributes:
+
+|     Attribute     |                 Description                  |
+|-------------------|----------------------------------------------|
+| `power_limit_w`   | The actual PoE limit                         |
+| `power_remain_w`  | Remaining power until the limit is exhausted |
+
+
+## Port status
+
+The component allows you to get the status of each port.
+
+![PoE consumption sensor](images/sensor_port_state.png)
+
+
+There are several sensors that are always present:
+* `binary_sensor.<integration_name>_port_<port_number>_state`
+
+Each sensor exposes the following attributes:
+
+|     Attribute        |          Description         |
+|----------------------|------------------------------|
+| `number`             | The number of the port       |
+| `speed`              | Actual connection speed*     |
+| `speed_config`       | Configured connection speed* |
+
+\* the connection speed is represented by the following values:
+
+|    Value    |        Description        |
+|-------------|---------------------------|
+| `Link Down` | The link is down          |
+| `Auto`      | Automatic speed selection |
+| `10MH`      | 10 Mbps, half-duplex      |
+| `10MF`      | 10 Mbps, full duplex      |
+| `100MH`     | 100 Mbps, half-duplex     |
+| `100MF`     | 100 Mbps, full duplex     |
+| `1000MF`    | 1000 Mbps, full duplex    |
+
+_Note: The sensor will be unavailable if the port is not enabled (see [port state switch](controls.md#port-state-switch))._
+| `power_remain_w`  | Remaining power until the limit is exhausted |
+
+
+## Port PoE status
+
+The component allows you to get the PoE status of each port.
+
+![PoE consumption sensor](images/sensor_port_poe_state.png)
+
+There are several sensors that are always present:
+* `binary_sensor.<integration_name>_port_<port_number>_poe_state`
+
+Each sensor exposes the following attributes:
+
+|     Attribute        |                   Description                  |
+|----------------------|------------------------------------------------|
+| `priority`           | Port power priority in case of power shortage* |
+| `power_limit`        | Power consumption limit**                      |
+| `power_w`            | Actual power consumption in watts              |
+| `current_ma`         | Actual current in milliamps                    |
+| `voltage_v`          | Actual voltage in volts                        |
+| `pd_class`           | Actual power delivery class***                 |
+| `power_status`       | Actual PoE status****                          |
+
+**\*** the priority is represented by the following values:
+* `High`
+* `Middle`
+* `Low`
+
+**\*\*** if the power consumption limit is set manually, it will be displayed as a number. In other cases, it will be represented by one of the following values:
+* `Auto`
+* `Class 1`
+* `Class 2`
+* `Class 3`
+* `Class 4`
+
+**\*\*\*** the power delivery class is represented by the following values:
+* `Class 0`
+* `Class 1`
+* `Class 2`
+* `Class 3`
+* `Class 4`
+
+**\*\*\*\*** the power status is represented by the following values:
+* `On`
+* `Off`
+* `Turning on`
+* `Overload`
+* `Short`
+* `Non-standard PD`
+* `Voltage high`
+* `Voltage low`
+* `Hardware fault`
+* `Overtemperature`
+
+_Note: The sensor will be unavailable if the port PoE is not enabled (see [port PoE state switch](controls.md#port-poe-state-switch))._
diff --git a/docs/services.md b/docs/services.md
@@ -0,0 +1,43 @@
+# Services
+
+The component provides access to some services that can be used in your automations or other use cases.
+
+
+## Set the PoE power limit
+
+Service name: `tplink_easy_smart.set_general_poe_limit`
+
+Example:
+```
+service: tplink_easy_smart.set_general_poe_limit
+data:
+  mac_address: 11:22:33:AA:BB:CC
+  power_limit: 49.5
+```
+
+![Service call](images/service_set_general_poe_limit.png)
+
+Sets the system PoE power limit.
+
+
+## Set PoE settings for a specific port
+
+Service name: `tplink_easy_smart.set_port_poe_settings`
+
+Example:
+```
+service: tplink_easy_smart.set_port_poe_settings
+data:
+  mac_address: 11:22:33:AA:BB:CC
+  port_number: 1
+  enabled: true
+  priority: Middle
+  power_limit: Manual
+  manual_power_limit: 12.3
+```
+
+![Service call](images/service_set_port_poe_settings.png)
+
+Sets PoE settings for a specific port. 
+
+`manual_power_limit` value is limited to the range `[1..30]` and will be ignored if `power_limit` is not set to `Manual`