Doc updates (#81)

Michelle Sintov · Michelle Sintov · commit 922fbba9149d · 2019-04-30T14:51:16.000-07:00
diff --git a/anki_vector/behavior.py b/anki_vector/behavior.py
@@ -202,6 +202,15 @@ async def say_text(self, text: str, use_vector_voice: bool = True, duration_scal
     async def set_eye_color(self, hue: float, saturation: float) -> protocol.SetEyeColorResponse:
         """Set Vector's eye color.
 
+        Eye color settings examples:
+         |  Teal: Set hue to 0.42 and saturation to 1.00.
+         |  Orange: Set hue to 0.05 and saturation to 0.95.
+         |  Yellow: Set hue to 0.11 and saturation to 1.00.
+         |  Lime: Set hue to 0.21 and saturation to 1.00.
+         |  Sapphire: Set hue to 0.57 and saturation to 1.00.
+         |  Purple: Set hue to 0.83 and saturation to 0.76.
+         |  Green: Set hue to 0.30 and saturation to 1.00.
+
         .. testcode::
 
             import anki_vector
diff --git a/anki_vector/connection.py b/anki_vector/connection.py
@@ -376,10 +376,10 @@ async def _request_control(self, timeout: float = 10.0):
             raise VectorControlTimeoutException(f"Surpassed timeout of {timeout}s") from e
 
     def release_control(self, timeout: float = 10.0):
-        """Explicitly request control. Typically used after detecting :func:`control_lost_event`.
+        """Explicitly release control. Typically used after detecting :func:`control_lost_event`.
 
         To be able to directly control Vector's motors, override his screen, play an animation, etc.,
-        the :class:`Connection` will need behavior control. This function will acquire control
+        the :class:`Connection` will need behavior control. This function will release control
         of Vector's behavior system. This will raise a :class:`VectorControlTimeoutException` if it fails
         to receive a control_lost event before the timeout.
 
diff --git a/anki_vector/nav_map.py b/anki_vector/nav_map.py
@@ -371,7 +371,7 @@ def latest_nav_map(self) -> NavMapGrid:
                 latest_nav_map = robot.nav_map.latest_nav_map
         """
         if not self._nav_map_feed_task or self._nav_map_feed_task.done():
-            raise Exception("Nav map not initialized")
+            raise Exception("Nav map not initialized. Check that Robot parameter enable_nav_map_feed is set to True.")
         return self._latest_nav_map
 
     def init_nav_map_feed(self, frequency: float = 0.5) -> None:
diff --git a/anki_vector/robot.py b/anki_vector/robot.py
@@ -812,6 +812,9 @@ async def get_version_state(self) -> protocol.VersionStateResponse:
             import anki_vector
             with anki_vector.Robot() as robot:
                 version_state = robot.get_version_state()
+                if version_state:
+                    print("Robot os_version: {0}".format(version_state.os_version))
+                    print("Robot engine_build_id: {0}".format(version_state.engine_build_id))
         """
         get_version_state_request = protocol.VersionStateRequest()
         return await self.conn.grpc_interface.VersionState(get_version_state_request)
diff --git a/anki_vector/screen.py b/anki_vector/screen.py
@@ -155,7 +155,10 @@ async def set_screen_with_image_data(self, image_data: bytes, duration_sec: floa
 
                 # Convert the image to the format used by the Screen
                 screen_data = anki_vector.screen.convert_image_to_screen_data(image_file)
-                robot.screen.set_screen_with_image_data(screen_data, 4.0)
+
+                duration_s = 4.0
+                robot.screen.set_screen_with_image_data(screen_data, duration_s)
+                time.sleep(duration_s)
 
         :param image_data: A :class:`bytes` object representing all of the pixels (16bit color in rgb565 format)
         :param duration_sec: The number of seconds the image should remain on Vector's face.
@@ -184,7 +187,9 @@ def set_screen_to_color(self, solid_color: color.Color, duration_sec: float, int
             import anki_vector
 
             with anki_vector.Robot() as robot:
-                robot.screen.set_screen_to_color(anki_vector.color.Color(rgb=[255, 128, 0]), duration_sec=1.0)
+                duration_s = 4.0
+                robot.screen.set_screen_to_color(anki_vector.color.Color(rgb=[255, 128, 0]), duration_sec=duration_s)
+                time.sleep(duration_s)
 
         :param solid_color: Desired color to set Vector's Screen.
         :param duration_sec: The number of seconds the color should remain on Vector's face.
diff --git a/anki_vector/status.py b/anki_vector/status.py
@@ -116,6 +116,11 @@ def is_docking_to_marker(self) -> bool:
     def is_picked_up(self) -> bool:
         """True if Vector is currently picked up (in the air).
 
+        If :py:attr:`is_being_held` is true, then :py:attr:`is_picked_up` is always True.
+
+        :py:attr:`is_picked_up` uses the IMU data to determine if the robot is not on a stable surface with his treads down.
+        If the robot is on its side, :py:attr:`is_picked_up` is True.
+
         .. testcode::
 
             import anki_vector
@@ -287,6 +292,9 @@ def are_wheels_moving(self) -> bool:
     def is_being_held(self) -> bool:
         """True if Vector is being held.
 
+        :py:attr:`is_being_held` uses the IMU to look for tiny motions
+        that suggest the robot is actively being held in someone's hand.
+
         .. testcode::
 
             import anki_vector
diff --git a/examples/tutorials/06_face_image.py b/examples/tutorials/06_face_image.py
@@ -47,8 +47,10 @@ def main():
         # Convert the image to the format used by the Screen
         print("Display image on Vector's face...")
         screen_data = anki_vector.screen.convert_image_to_screen_data(image_file)
-        robot.screen.set_screen_with_image_data(screen_data, 4.0)
-        time.sleep(5)
+
+        duration_s = 4.0
+        robot.screen.set_screen_with_image_data(screen_data, duration_s)
+        time.sleep(duration_s)
 
 
 if __name__ == "__main__":
