From cdb5667373a72771171cd5f756cfaab712ebc8e2 Mon Sep 17 00:00:00 2001
From: Dennis Holzmann <dennis.holzmann@uni-bielefeld.de>
Date: Thu, 21 Nov 2024 11:16:17 +0100
Subject: [PATCH] update person perception documentation

---
 .../personPerception/WaitForPerson.java       | 36 ++++++++++++-------
 .../oneshot/SearchPeople.java                 | 18 +++++-----
 2 files changed, 32 insertions(+), 22 deletions(-)

diff --git a/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/WaitForPerson.java b/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/WaitForPerson.java
index 1da32331..357fc62d 100644
--- a/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/WaitForPerson.java
+++ b/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/WaitForPerson.java
@@ -23,23 +23,33 @@
 
 /**
  * Use this state to wait until a person is recognized in front of the robot.
- *
+ * The person should stand in a cone in front of the robot defined by #_MAX_DIST and #_MAX_ANGLE
+ * This skill loops till the robot recognized a person in front.
  * <pre>
- * options:
- * (optional) #_TIMEOUT(in ms)    -> enable timeout after x ms
- * (optional) #_MAX_DIST(meter)   -> max Person Distance
- * (optional) #_MAX_ANGLE(rad)    -> max Person Angle (in both directions)
+ * 
+ * Options:
+ *  #_TIMEOUT:          [long] Optional (default: -1)
+ *                          -> enable timeout after x ms. -1 means not time out
+ * #_MAX_DIST:          [double] Optional (default: 2.0)
+ *                          -> max person distance in meter
+ * #_MAX_ANGLE:         [double] Optional (default: 0.4)
+*                            -> max Person Angle in radiant(in both directions)
  *
- * slots:
- * PersonDataSlot: [PersonData] [Write] -> saves the found person to this slot
+ * Slots:
+ * PersonDataSlot: [PersonData] [Write] 
+ *      -> saves the found person to this slot
  *
- * possible return states are:
- * success             -> person found
- * success.timeout     -> timeout
- * fatal               -> a hard error occurred e.g. Slot communication error
+ * ExitTokens:
+ *  success:             -> person found
+ *  success.timeout:     -> timeout
+ *  fatal:               -> a hard error occurred e.g. Slot communication error
  *
- * this skill loops till the robot recognized a person in front.
- * Default is no timeout.
+ * Sensors:
+ *  PersonSensor: [PersonDataList]
+ *      -> Used to detect people
+ *  PositionSensor: [PositionData]
+ *      -> Used to read the current robot position
+ * 
  * </pre>
  *
  * 
diff --git a/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/oneshot/SearchPeople.java b/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/oneshot/SearchPeople.java
index c1188820..8518044a 100644
--- a/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/oneshot/SearchPeople.java
+++ b/bonsai_skills/src/main/java/de/unibi/citec/clf/bonsai/skills/personPerception/oneshot/SearchPeople.java
@@ -56,8 +56,6 @@
  * Slots:
  *  PersonDataListSlot:             [PersonDataList] [Write]
  *      -> All found persons in a list
- *  PositionDataSlot:             [PositionData] [Read]
- *      -> the robot position to calculate relative angle, and setting the modified yaw in positional part of personData.
  *
  * ExitTokens:
  *  success.people:         There has been at least one person perceived in the given timeout interval satisfying the optional given angle and distance parameters.
@@ -66,8 +64,12 @@
  *  error:                  There has been an exception while writing to slot or calling the actuator.
  *
  * Sensors:
- *  PersonSensor:       [PersonDataList]
- *      -> Read in currently seen persons
+ *  PositionSensor: [PositionData]
+ *      -> Used to read the current robot position
+ *
+ * Actuators:
+ *  PeopleActuator: [DetectPeopleActuator]
+ *      -> Used to detect people
  *
  * </pre>
  *
@@ -120,9 +122,7 @@ public void configure(ISkillConfigurator configurator) {
         search_timeout = configurator.requestOptionalInt(KEY_TIMEOUT, (int) search_timeout);
         actuator_timeout = configurator.requestOptionalInt(KEY_ACTUATOR_TIMEOUT, (int) actuator_timeout);
 
-        if (search_timeout > 0) {
-            tokenSuccessNoPeople = configurator.requestExitToken(ExitStatus.SUCCESS().withProcessingStatus("noPeople"));
-        }
+        tokenSuccessNoPeople = configurator.requestExitToken(ExitStatus.SUCCESS().withProcessingStatus("noPeople"));
         tokenSuccessPeople = configurator.requestExitToken(ExitStatus.SUCCESS().withProcessingStatus("people"));
         tokenError = configurator.requestExitToken(ExitStatus.ERROR());
 
@@ -220,8 +220,8 @@ public ExitToken execute() {
                 //continue;
             }
             if (localPersonPos.getDistance(new Point2D(0.0, 0.0, LengthUnit.METER), LengthUnit.MILLIMETER) > searchRadius) {
-                logger.info("search distance is: " + searchRadius + ". person to far away: "
-                        + localPersonPos.getDistance(new Point2D(0.0, 0.0, LengthUnit.METER), LengthUnit.MILLIMETER));
+                logger.info("search distance is: " + searchRadius + "mm. person to far away: "
+                        + localPersonPos.getDistance(new Point2D(0.0, 0.0, LengthUnit.METER), LengthUnit.MILLIMETER) + " mm.");
                 continue;
             }