Bruce/VIC-3793 Highest Level SDK Behavior Control (#117)

BruceVonK · Michelle Sintov · commit 807a618baa3a · 2019-04-30T14:51:16.000-07:00
Updated the robot/connection logic for using the `Connection.CONTROL_PRIORITY_LEVEL` instead of a simple `bool` for requesting behavior control.

**This will break people** who have existing `Robot` or `Connection` code that declines behavior control.
diff --git a/anki_vector/connection.py b/anki_vector/connection.py
@@ -52,10 +52,12 @@
 
 class CONTROL_PRIORITY_LEVEL(Enum):
     """Enum used to specify the priority level for the program."""
-
+    #: Runs above mandatory physical reactions, will drive off table, perform while on a slope,
+    #: in the dark, etc.
+    OVERRIDE_BEHAVIORS_PRIORITY = protocol.ControlRequest.OVERRIDE_BEHAVIORS  # pylint: disable=no-member
     #: Runs below Mandatory Physical Reactions such as tucking Vector's head and arms during a fall,
-    #: yet above Trigger-Word Detection.
-    TOP_PRIORITY_AI = protocol.ControlRequest.TOP_PRIORITY_AI  # pylint: disable=no-member
+    #: yet above Trigger-Word Detection.  Default for normal operation.
+    DEFAULT_PRIORITY = protocol.ControlRequest.DEFAULT  # pylint: disable=no-member
 
 
 class _ControlEventManager:
@@ -109,7 +111,7 @@ def is_shutdown(self) -> bool:
         """Detect if the behavior control stream is supposed to shut down."""
         return self._is_shutdown
 
-    def request(self, priority: CONTROL_PRIORITY_LEVEL = CONTROL_PRIORITY_LEVEL.TOP_PRIORITY_AI) -> None:
+    def request(self, priority: CONTROL_PRIORITY_LEVEL = CONTROL_PRIORITY_LEVEL.DEFAULT_PRIORITY) -> None:
         """Tell the behavior stream to request control via setting the :class:`request_event`.
 
         This will signal Connection's :func:`_request_handler` generator to send a request control message on the BehaviorControl stream.
@@ -192,10 +194,11 @@ async def play_animation():
     :param host: The IP address and port of Vector in the format "XX.XX.XX.XX:443".
     :param cert_file: The location of the certificate file on disk.
     :param guid: Your robot's unique secret key.
-    :param requires_behavior_control: True if the connection requires behavior control.
+    :param behavior_control_level: pass one of :class:`CONTROL_PRIORITY_LEVEL` priority levels if the connection
+                                   requires behavior control, or None to decline control.
     """
 
-    def __init__(self, name: str, host: str, cert_file: str, guid: str, requires_behavior_control: bool = True):
+    def __init__(self, name: str, host: str, cert_file: str, guid: str, behavior_control_level: CONTROL_PRIORITY_LEVEL = CONTROL_PRIORITY_LEVEL.DEFAULT_PRIORITY):
         if cert_file is None:
             raise VectorConfigurationException("Must provide a cert file to authenticate to Vector.")
         self._loop: asyncio.BaseEventLoop = None
@@ -213,7 +216,7 @@ def __init__(self, name: str, host: str, cert_file: str, guid: str, requires_beh
         self._ready_signal: threading.Event = threading.Event()
         self._done_signal: asyncio.Event = None
         self._conn_exception = False
-        self._requires_behavior_control = requires_behavior_control
+        self._behavior_control_level = behavior_control_level
         self.active_commands = []
 
     @property
@@ -285,6 +288,27 @@ async def play_animation():
         """
         return self._interface
 
+    @property
+    def behavior_control_level(self) -> CONTROL_PRIORITY_LEVEL:
+        """Returns the specific :class:`CONTROL_PRIORITY_LEVEL` requested for behavior control.
+
+        To be able to directly control Vector's motors, override his screen, play an animation, etc.,
+        the :class:`Connection` will need behavior control. This property identifies the enumerated
+        level of behavior control that the SDK will maintain over the robot.
+
+        For more information about behavior control, see :ref:`behavior <behavior>`.
+
+        .. code-block:: python
+
+            import anki_vector
+
+            with anki_vector.Robot() as robot:
+                print(robot.conn.behavior_control_level) # Will print CONTROL_PRIORITY_LEVEL.DEFAULT_PRIORITY
+                robot.conn.release_control()
+                print(robot.conn.behavior_control_level) # Will print None
+        """
+        return self._behavior_control_level
+
     @property
     def requires_behavior_control(self) -> bool:
         """True if the :class:`Connection` requires behavior control.
@@ -308,14 +332,14 @@ def callback(robot, event_type, event):
                 robot.anim.play_animation_trigger('GreetAfterLongTime')
                 robot.conn.release_control()
 
-            with anki_vector.Robot(requires_behavior_control=False) as robot:
+            with anki_vector.Robot(behavior_control_level=None) as robot:
                 print(robot.conn.requires_behavior_control) # Will print False
                 robot.events.subscribe(callback, anki_vector.events.Events.robot_observed_face)
 
                 # Waits 10 seconds. Show Vector your face.
                 time.sleep(10)
         """
-        return self._requires_behavior_control
+        return self._behavior_control_level is not None
 
     @property
     def control_lost_event(self) -> asyncio.Event:
@@ -347,7 +371,7 @@ async def wait_for_control(conn: anki_vector.connection.Connection):
         """
         return self._control_events.granted_event
 
-    def request_control(self, timeout: float = 10.0):
+    def request_control(self, behavior_control_level: CONTROL_PRIORITY_LEVEL = CONTROL_PRIORITY_LEVEL.DEFAULT_PRIORITY, timeout: float = 10.0):
         """Explicitly request behavior 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.,
@@ -366,14 +390,18 @@ async def auto_reconnect(conn: anki_vector.connection.Connection):
                 conn.request_control(timeout=5.0)
 
         :param timeout: The time allotted to attempt a connection, in seconds.
+        :param behavior_control_level: request control of Vector's behavior system at a specific level of control.
+                    See :class:`CONTROL_PRIORITY_LEVEL` for more information.
         """
+        if not isinstance(behavior_control_level, CONTROL_PRIORITY_LEVEL):
+            raise TypeError("behavior_control_level must be of type CONTROL_PRIORITY_LEVEL")
         if self._thread is threading.current_thread():
-            return asyncio.ensure_future(self._request_control(timeout=timeout), loop=self._loop)
-        return self.run_coroutine(self._request_control(timeout=timeout))
+            return asyncio.ensure_future(self._request_control(behavior_control_level=behavior_control_level, timeout=timeout), loop=self._loop)
+        return self.run_coroutine(self._request_control(behavior_control_level=behavior_control_level, timeout=timeout))
 
-    async def _request_control(self, timeout: float = 10.0):
-        self._requires_behavior_control = True
-        self._control_events.request()
+    async def _request_control(self, behavior_control_level: CONTROL_PRIORITY_LEVEL = CONTROL_PRIORITY_LEVEL.DEFAULT_PRIORITY, timeout: float = 10.0):
+        self._behavior_control_level = behavior_control_level
+        self._control_events.request(self._behavior_control_level)
         try:
             self._has_control = await asyncio.wait_for(self.control_granted_event.wait(), timeout)
         except futures.TimeoutError as e:
@@ -403,7 +431,7 @@ async def wait_for_control(conn: anki_vector.connection.Connection):
         return self.run_coroutine(self._release_control(timeout=timeout))
 
     async def _release_control(self, timeout: float = 10.0):
-        self._requires_behavior_control = False
+        self._behavior_control_level = None
         self._control_events.release()
         try:
             self._has_control = await asyncio.wait_for(self.control_lost_event.wait(), timeout)
@@ -456,10 +484,10 @@ def _connect(self, timeout: float) -> None:
             self._loop = asyncio.new_event_loop()
             asyncio.set_event_loop(self._loop)
             self._done_signal = asyncio.Event()
-            if not self._requires_behavior_control:
+            if not self._behavior_control_level:
                 self._control_events = _ControlEventManager(self._loop)
             else:
-                self._control_events = _ControlEventManager(self._loop, priority=CONTROL_PRIORITY_LEVEL.TOP_PRIORITY_AI)
+                self._control_events = _ControlEventManager(self._loop, priority=self._behavior_control_level)
             trusted_certs = None
             with open(self.cert_file, 'rb') as cert:
                 trusted_certs = cert.read()
@@ -505,8 +533,8 @@ def _connect(self, timeout: float) -> None:
                                                            cpu_version=cpu_version)
             self._loop.run_until_complete(self._interface.SDKInitialization(initialize))
 
-            if self._requires_behavior_control:
-                self._loop.run_until_complete(self._request_control(timeout=timeout))
+            if self._behavior_control_level:
+                self._loop.run_until_complete(self._request_control(behavior_control_level=self._behavior_control_level, timeout=timeout))
         except Exception as e:  # pylint: disable=broad-except
             # Propagate the errors to the calling thread
             setattr(self._ready_signal, "exception", e)
diff --git a/anki_vector/exceptions.py b/anki_vector/exceptions.py
@@ -67,7 +67,7 @@ class VectorControlException(VectorException):
 
     def __init__(self, function):
         msg = (f"Unable to run '{function}' because it requires behavior control.\n\n"
-               "Make sure to request control from Vector either by providing the 'enable_behavior_control' parameter to Robot, "
+               "Make sure to request control from Vector either by providing the 'behavior_control_level' parameter to Robot, "
                "or directly call 'request_control()' on your connection.")
         super().__init__(msg)
 
diff --git a/anki_vector/messaging/behavior.proto b/anki_vector/messaging/behavior.proto
@@ -32,8 +32,10 @@ message ControlRequest {
   enum Priority {
     // Unknown priority. Used for versions that don't understand old priority levels.
     UNKNOWN = 0;
-    // Highest priority level. Directly under mandatory physical reactions.
-    TOP_PRIORITY_AI = 20;
+    // Highest priority level. Suppresses most automatic physical reactions, use with caution. 
+    OVERRIDE_BEHAVIORS = 10;
+    // Normal priority level. Directly under mandatory physical reactions.
+    DEFAULT = 20;
   }
   // Where in the behavior tree the SDK code should be executed.
   Priority priority = 1;
diff --git a/anki_vector/messaging/behavior_pb2.py b/anki_vector/messaging/behavior_pb2.py
diff --git a/anki_vector/robot.py b/anki_vector/robot.py
@@ -30,10 +30,12 @@
 from pathlib import Path
 
 from . import (animation, audio, behavior, camera,
-               connection, events, faces, motors,
-               nav_map, screen, photos, proximity,
-               status, touch, util, viewer, vision,
-               world)
+               events, faces, motors, nav_map, screen,
+               photos, proximity, status, touch, util,
+               viewer, vision, world)
+from .connection import (Connection,
+                         on_connection_thread,
+                         CONTROL_PRIORITY_LEVEL)
 from .exceptions import (VectorConfigurationException,
                          VectorNotReadyException,
                          VectorPropertyValueNotReadyException,
@@ -95,7 +97,9 @@ class Robot:
     :param enable_nav_map_feed: Turn navigation map feed on/off.
     :param show_viewer: Specifies whether to display a view of Vector's camera in a window.
     :param show_3d_viewer: Specifies whether to display a 3D view of Vector's understanding of the world in a window.
-    :param requires_behavior_control: Request control of Vector's behavior system."""
+    :param behavior_control_level: Request control of Vector's behavior system at a specific level of control.  Pass
+                                :code:`None` if behavior control is not needed.
+                                See :class:`CONTROL_PRIORITY_LEVEL` for more information."""
 
     def __init__(self,
                  serial: str = None,
@@ -110,7 +114,7 @@ def __init__(self,
                  enable_nav_map_feed: bool = None,
                  show_viewer: bool = False,
                  show_3d_viewer: bool = False,
-                 requires_behavior_control: bool = True):
+                 behavior_control_level: CONTROL_PRIORITY_LEVEL = CONTROL_PRIORITY_LEVEL.DEFAULT_PRIORITY):
         if default_logging:
             util.setup_basic_logging()
         self.logger = util.get_class_logger(__name__, self)
@@ -133,7 +137,7 @@ def __init__(self,
                              '{"name":"Vector-XXXX", "ip":"XX.XX.XX.XX", "cert":"/path/to/cert_file", "guid":"<secret_key>"}')
 
         #: :class:`anki_vector.connection.Connection`: The active connection to the robot.
-        self._conn = connection.Connection(self._name, ':'.join([self._ip, self._port]), self._cert_file, self._guid, requires_behavior_control=requires_behavior_control)
+        self._conn = Connection(self._name, ':'.join([self._ip, self._port]), self._cert_file, self._guid, behavior_control_level=behavior_control_level)
         self._events = events.EventHandler(self)
 
         # placeholders for components before they exist
@@ -224,7 +228,7 @@ def force_async(self) -> bool:
         return self._force_async
 
     @property
-    def conn(self) -> connection.Connection:
+    def conn(self) -> Connection:
         """A reference to the :class:`~anki_vector.connection.Connection` instance."""
         return self._conn
 
@@ -756,7 +760,7 @@ def __enter__(self):
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.disconnect()
 
-    @connection.on_connection_thread(requires_control=False)
+    @on_connection_thread(requires_control=False)
     async def get_battery_state(self) -> protocol.BatteryStateResponse:
         """Check the current state of the robot and cube batteries.
 
@@ -789,7 +793,7 @@ async def get_battery_state(self) -> protocol.BatteryStateResponse:
         get_battery_state_request = protocol.BatteryStateRequest()
         return await self.conn.grpc_interface.BatteryState(get_battery_state_request)
 
-    @connection.on_connection_thread(requires_control=False)
+    @on_connection_thread(requires_control=False)
     async def get_version_state(self) -> protocol.VersionStateResponse:
         """Get the versioning information for Vector, including Vector's os_version and engine_build_id.
 
@@ -897,7 +901,9 @@ async def callback(robot, event_type, event):
     :param enable_nav_map_feed: Turn navigation map feed on/off.
     :param show_viewer: Specifies whether to display a view of Vector's camera in a window.
     :param show_3d_viewer: Specifies whether to display a 3D view of Vector's understanding of the world in a window.
-    :param requires_behavior_control: Request control of Vector's behavior system."""
+    :param behavior_control_level: Request control of Vector's behavior system at a specific level of control.  Pass
+                                   :code:`None` if behavior control is not needed.
+                                   See :class:`CONTROL_PRIORITY_LEVEL` for more information."""
 
     @functools.wraps(Robot.__init__)
     def __init__(self, *args, **kwargs):
diff --git a/docs/source/proto.html b/docs/source/proto.html
@@ -1167,9 +1167,15 @@ <h3 id="Anki.Vector.external_interface.ControlRequest.Priority">ControlRequest.P
               </tr>
             
               <tr>
-                <td>TOP_PRIORITY_AI</td>
+                <td>OVERRIDE_BEHAVIORS</td>
+                <td>10</td>
+                <td><p>Highest priority level. Suppresses most automatic physical reactions, use with caution.</p></td>
+              </tr>
+            
+              <tr>
+                <td>DEFAULT</td>
                 <td>20</td>
-                <td><p>Highest priority level. Directly under mandatory physical reactions.</p></td>
+                <td><p>Normal priority level. Directly under mandatory physical reactions.</p></td>
               </tr>
             
           </tbody>
diff --git a/examples/tutorials/12_wake_word_subscription.py b/examples/tutorials/12_wake_word_subscription.py
@@ -42,7 +42,7 @@ def on_wake_word(robot, event_type, event, done):
             done.set()
 
     args = anki_vector.util.parse_command_args()
-    with anki_vector.Robot(args.serial, requires_behavior_control=False) as robot:
+    with anki_vector.Robot(args.serial, behavior_control_level=None) as robot:
         done = threading.Event()
         robot.events.subscribe(on_wake_word, Events.wake_word, done)
 
