✏️ [docs] Add documentation about the entities created by qolsysgw (#…

…83)

README.md

@@ -752,6 +752,7 @@ With:
 
 - [The known Qolsys Panel interactions](./docs/qolsys-panel-interactions.md)
 - [Qolsys Gateway's control commands](./docs/qolsysgw-control-commands.md)
+- [Qolsys Gateway's entities](./docs/qolsysgw-entities.md)
 
 
 ## Acknowledgements and thanks

docs/qolsysgw-entities.md

@@ -0,0 +1,86 @@
+# Qolsys Gateway's entities
+
+Qolsys Gateway creates a number of entities in Home Assistant and provides
+attributes enabling to build automations around your Qolsys Panel with as
+much of the information provided through the panel as possible.
+
+> For the sake of simplicity, and because everyone's use of the information
+> is different, some information are only provided as attributes on the
+> entities instead of full-fledged sensors. Home Assistant however allows to
+> easily build a sensor to track an attribute of another sensor; for instance,
+> if you wish to have a sensor giving you the description of the last error
+> raised by Qolsys Gateway, which is available as attribute `desc` on the
+> sensor `qolsys_panel_last_error` (the `qolsys_panel` prefix being the
+> default panel unique ID, which you might have changed in the `qolsysgw`
+> configuration), you could use the following YAML code in your Home Assistant
+> configuration:
+>
+> ```yaml
+> template:
+>   - sensor:
+>       - name: qolsys_panel_last_error_desc
+>         state: "{{state_attr('sensor.qolsys_panel_last_error', 'desc')}}"
+> ```
+
+This document aims at keeping track of the available entities and their
+attributes.
+
+
+## Qolsys State
+
+A `sensor` entity will be provided for each instance of `qolsysgw`,
+keeping track of the errors raised by the Gateway itself. The name
+of the sensor will be in the format `{panel_unique_id}_last_error`
+(default `qolsys_panel_last_error`) and will use the `timestamp`
+device class, its value being the date of the last error raised by
+the Gateway.
+
+The following attributes are provided:
+
+- `type`: the type of error raised by the Gateway
+  (e.g. `UnknownQolsysSensorException`)
+- `desc`: the description of the error raised by the Gateway
+  (e.g. `Sensor type 'xxx' unsupported for sensor yyy`)
+
+## Qolsys Partition
+
+An `alarm_control_panel` entity will be provided for each partition found
+in a panel.
+
+The following attributes are provided:
+
+- `secure_arm`: whether the partition has secure arming enabled, which
+  means the panel would require to receive the user code when arming.
+- `alarm_type`: one of `POLICE`, `FIRE`, `AUXILIARY` or (empty string)
+  when an alarm is triggered on the partition. Set to `null` otherwise.
+- `last_error_type`: the type of the last error received from the panel
+  for that partition (e.g. `DISARM_FAILED`)
+- `last_error_desc`: the description of the last error received from
+  the panel for that partition (e.g. `Invalid usercode`)
+- `last_error_at`: the timestamp of the last error received from the
+  panel for that partition (particularly useful if you're tracking
+  errors sent from the panel and want to identity two occurrences of
+  the same error happening one after the other, since this value will
+  be updated)
+- `disarm_failed`: the number of failures to disarm the panel since
+  it was last armed, or since `qolsysgw` was started
+
+## Qolsys Sensor
+
+A `binary_sensor` entity will be provided for each sensor found in a panel.
+The device class of the sensor will depend on the sensor type as identified
+by the panel.
+
+The following attributes are provided:
+
+- Attributes directly forwarded from the panel:
+  - `group`: the group of the sensor
+  - `state`: the state of the sensor
+  - `zone_type`: the zone type of the sensor
+  - `zone_physical_type`: the zone physical type
+  - `zone_alarm_type`: the zone alarm type
+
+- `tampered`: whether the sensor is currently tampered (note that this
+  attribute will reset to `false` on a restart of the panel as the `SUMMARY`
+  message of the panel does not provide sufficient information to know
+  if a sensor is currently tampered)