NUT sensor enhancements (#5411)

source/_components/sensor.nut.markdown

@@ -28,56 +28,83 @@ sensor:
       - battery.runtime
 ```
 
-Configuration variables:
-
-- **name** (*Optional*): Name prefix for defined sensors. Defaults to 'NUT UPS'.
-- **host** (*Optional*): The host name or address of the device that is running NUT. Defaults to localhost.
-- **port** (*Optional*): The port number. Defaults to 3493.
-- **alias** (*Optional*): Name of the ups on the NUT server. Will default to the first UPS name listed.
-- **username** (*Optional*): Username to login to the NUT server. Default is none.
-- **password** (*Optional*): Password to login to the NUT server. Default is none.
-- **resources** array (*Required*): Contains all entries to display.
+{% configuration %}
+  name:
+    description: Name prefix for defined sensors.
+    required: false
+    default: 'NUT UPS'
+    type: string
+  host:
+    description: The host name or IP address of the device that is running NUT.
+    required: false
+    default: localhost
+    type: string
+  port:
+    description: The port number.
+    required: false
+    default: 3493
+    type: int
+  alias:
+    description: Name of the ups on the NUT server.
+    required: false
+    default: Will default to the first UPS name listed.
+    type: string
+  username:
+    description: Username to login to the NUT server.
+    required: false
+    default: none
+    type: string
+  password:
+    description: Password to login to the NUT server.
+    required: false
+    default: none
+    type: string
+  resources:
+    description: Contains all entries to display.
+    required: true
+    type: list
+{% endconfiguration %}
 
 ### {% linkable_title Example  %}
 
-Given the following example output from NUT (Your variables may differ):
+Given the following example output from NUT (your variables may differ):
 
 ```yaml
-'ups.timer.reboot': '0', 
-'battery.voltage': '27.0', 
-'ups.firmware.aux': 'L3 -P ', 
-'ups.mfr': 'American Power Conversion', 
-'battery.runtime.low': '120', 
-'ups.delay.shutdown': '20', 
-'ups.load': '19', 
-'ups.realpower.nominal': '600', 
-'battery.charge.warning': '50', 
-'battery.charge.low': '10', 
-'ups.vendorid': '051d', 
-'ups.timer.shutdown': '-1', 
-'ups.test.result': 'No test initiated', 
-'ups.firmware': '868.L3 -P.D', 
-'battery.mfr.date': '2015/05/08', 
-'ups.serial': '3B1519X19994  ', 
-'ups.productid': '0002', 
-'battery.runtime': '2552', 
-'battery.date': '2001/09/25', 
-'battery.voltage.nominal': '24.0', 
-'battery.type': 'PbAc', 
-'ups.mfr.date': '2015/05/08', 
-'ups.status': 'OL', 
-'ups.model': 'Back-UPS RS1000G', 
-'ups.beeper.status': 'disabled', 
-'battery.charge': '100', 
-'input.sensitivity': 'medium', 
+'ups.timer.reboot': '0'
+'battery.voltage': '27.0'
+'ups.firmware.aux': 'L3 -P '
+'ups.mfr': 'American Power Conversion'
+'battery.runtime.low': '120'
+'ups.delay.shutdown': '20'
+'ups.load': '19'
+'ups.realpower.nominal': '600'
+'battery.charge.warning': '50'
+'battery.charge.low': '10'
+'ups.vendorid': '051d'
+'ups.timer.shutdown': '-1'
+'ups.test.result': 'No test initiated'
+'ups.firmware': '868.L3 -P.D'
+'battery.mfr.date': '2015/05/08'
+'ups.serial': '3B1519X19994  '
+'ups.productid': '0002'
+'battery.runtime': '2552'
+'battery.date': '2001/09/25'
+'battery.voltage.nominal': '24.0'
+'battery.type': 'PbAc'
+'ups.mfr.date': '2015/05/08'
+'ups.status': 'OL'
+'ups.model': 'Back-UPS RS1000G'
+'ups.beeper.status': 'disabled'
+'battery.charge': '100'
+'input.sensitivity': 'medium'
 'input.transfer.low': '88'
-'input.transfer.high': '147', 
-'input.voltage': '121.0', 
-'input.voltage.nominal': '120', 
-'input.transfer.reason': 'input voltage out of range', 
+'input.transfer.high': '147'
+'input.voltage': '121.0'
+'input.voltage.nominal': '120'
+'input.transfer.reason': 'input voltage out of range'
 ```
 
-Use the values from the left hand column.  Support is included for most values with 'ups', 'battery', and 'input' prefixes.
+Use the values from the left hand column. Support is included for most values with 'ups', 'battery', and 'input' prefixes.
 
 ```yaml
 sensor:
@@ -94,3 +121,14 @@ sensor:
       - input.voltage
       - battery.runtime
 ```
+
+### {% linkable_title UPS Status - human-readable version %}
+
+An additional virtual sensor type `ups.status.display` is available translating the UPS status value retrieved from `ups.status` into a human-readable version.
+
+```yaml
+sensor:
+  - platform: nut
+    resources:
+      - ups.status.display
+```