Enhance HLK-FM22x documentation with additional configuration variabl…

…es and error handling details

components/hlk_fm22x.rst

@@ -84,9 +84,11 @@ Sensor
 Text Sensor
 -----------
 
-Configuration variables:
+- **version**: The module's firmware version.
+  All options from :ref:`Text Sensor <config-text_sensor>`.
 
-- All options from :ref:`Text Sensor <config-text_sensor>`.
+- **last_face_name**: The last matched enrolled face as set by :ref:`hlk_fm22x-on_face_scan_matched`.
+  All options from :ref:`Text Sensor <config-text_sensor>`.
 
 
 .. _hlk_fm22x-on_face_scan_matched:
@@ -95,14 +97,14 @@ Configuration variables:
 --------------------------------
 
 With this configuration option you can write complex automations whenever a face scan is matched to an enrolled face.
-To use the variable, use a :ref:`lambda <config-lambda>` template, the matched face id is available inside that lambda under the variable named ``face_id``.
+To use the variables, use a :ref:`lambda <config-lambda>` template, the matched face id is available inside that lambda under the variable named ``face_id`` and the face name under the variable named ``name``.
 
 .. code-block:: yaml
 
     on_face_scan_matched:
       - text_sensor.template.publish:
           id: face_state
-          state: !lambda 'return "Authorized face " + to_string(face_id)";'
+          state: !lambda 'return "Authorized face " + name + " (" + to_string(face_id) + ")";'
       # Pushing a tag_scanned event based on face_id
       - homeassistant.tag_scanned: !lambda |-
           switch (face_id) {
@@ -135,13 +137,14 @@ With this configuration option you can write complex automations whenever an unk
 --------------------------------
 
 With this configuration option you can write complex automations whenever a scan fails, e.g. when no face is visible. This is different from ``on_face_scan_unmatched`` which is triggered when an unknown face is scanned. 
+To use the variable, use a :ref:`lambda <config-lambda>` template, the error number is available inside that lambda under the variable named ``error``.
 
 .. code-block:: yaml
 
     on_face_scan_invalid:
       - text_sensor.template.publish:
           id: face_state
-          state: "Invalid face"
+          state: !lambda 'return "Invalid face. Error number: " + to_string(error);'
 
 
 .. _hlk_fm22x-on_face_info:
@@ -151,8 +154,9 @@ With this configuration option you can write complex automations whenever a scan
 
 With this configuration option you can write complex automations whenever face information is available.
 The module sends face info during enrollment and scanning, and it's mostly useful for debugging.
-To use the variable, use a :ref:`lambda <config-lambda>` template, the status is available inside that lambda under the variable named ``status``.
-A zero value means normal, and the datasheet contains various error status codes (e.g. 6 for the face being too far)
+To use the variables, use a :ref:`lambda <config-lambda>` template, the status is available inside that lambda under the variable named ``status``.
+A zero value means normal, and the datasheet contains various error status codes (e.g. 6 for the face being too far).
+There are additional values to determine the position (`left`, `top`, `right`, `bottom`) of the face in the frame as well as its rotation (`yaw`, `pitch`, `roll`).
 
 .. code-block:: yaml
 
@@ -182,6 +186,7 @@ A zero value means normal, and the datasheet contains various error status codes
 With this configuration option you can write complex automations whenever an enrollment step for a face is successful.
 To use the variables, use a :ref:`lambda <config-lambda>` template, the slot number enrolled into is available inside that lambda under the variable named ``faec_id``.
 Note that the value is only valid after the face has been enrolled in all directions (otherwise it will be -1).
+The direction value is a bitmask representing the directions that have been captured so far. A value of `0x1f` means all directions have been captured and the face id should be valid.
 
 .. code-block:: yaml
 
@@ -196,13 +201,14 @@ Note that the value is only valid after the face has been enrolled in all direct
 --------------------------------
 
 With this configuration option you can write complex automations whenever a face failed to be enrolled.
+To use the variable, use a :ref:`lambda <config-lambda>` template, the error number is available inside that lambda under the variable named ``error``.
 
 .. code-block:: yaml
 
     on_enrollment_failed:
       - text_sensor.template.publish:
           id: face_state
-          state: !lambda 'return "Failed to enroll face";'
+          state: !lambda 'return "Failed to enroll face. Error: " + to_string(error);'
 
 
 ``hlk_fm22x.enroll`` Action
@@ -312,11 +318,14 @@ Sample code
       on_face_scan_invalid:
         - homeassistant.event:
             event: esphome.test_node_face_scan_invalid
+            data:
+              error: !lambda 'return error;'
       on_face_scan_matched:
         - homeassistant.event:
             event: esphome.test_node_face_scan_matched
             data:
               face_id: !lambda 'return face_id;'
+              name: !lambda 'return name;'
       on_face_scan_unmatched:
         - homeassistant.event:
             event: esphome.test_node_face_scan_unmatched
@@ -325,16 +334,19 @@ Sample code
             event: esphome.test_node_face_info
             data:
               status: !lambda 'return status;'
+              left: !lambda 'return left;'
+              ...
       on_enrollment_done:
         - homeassistant.event:
             event: esphome.test_node_enrollment_done
             data:
               face_id: !lambda 'return face_id;'
+              direction: !lambda 'return direction;'
       on_enrollment_failed:
         - homeassistant.event:
             event: esphome.test_node_enrollment_failed
             data:
-              face_id: !lambda 'return face_id;'
+              error: !lambda 'return error;'
 
     api:
       actions: