VIC-13744 Add 'name' field to Robot class constructor for mDNS discovery (#167)

paulaluri · msintov · commit a3bd5b607e43 · 2019-04-30T14:51:16.000-07:00
Add support for mDNS in sdk Robot object init

E.g., anki_vector.Robot(name="Vector-A1B2")

If the name param matches the 'name' field in sdk_config.ini,
the SDK will start an mDNS browser to find Vector. If
successful, it will use the discovered IP--otherwise,
it will use the default means (ip param or 'ip' field
in config).
diff --git a/anki_vector/behavior.py b/anki_vector/behavior.py
@@ -982,7 +982,7 @@ def __init__(self,
                  behavior_activation_timeout: int = 10):
         config = config if config is not None else {}
         self.logger = util.get_class_logger(__name__, self)
-        config = {**util.read_configuration(serial, self.logger), **config}
+        config = {**util.read_configuration(serial, name=None, logger=self.logger), **config}
         self._name = config["name"]
         self._ip = ip if ip is not None else config["ip"]
         self._cert_file = config["cert"]
diff --git a/anki_vector/mdns.py b/anki_vector/mdns.py
@@ -0,0 +1,127 @@
+# Copyright (c) 2019 Anki, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License in the file LICENSE.txt or at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This contains the :class:`VectorMdns` class for discovering Vector (without already knowing
+the IP address) on a LAN (Local Area Network) over mDNS.
+
+mDNS (multicast DNS) is a protocol for sending UDP packets containing a DNS query to all
+devices on your Local Area Network. If a device knows how to answer the DNS query, it
+will respond by multicasting a UDP packet containing the relevant DNS records.
+"""
+from threading import Condition
+import sys
+
+
+class VectorMdns:  # pylint: disable=too-few-public-methods
+    """`VectorMdns` provides a static method for discovering a Vector on the same LAN as
+    the SDK program and retrieving its IP address.
+    """
+
+    @staticmethod
+    def find_vector(name: str, timeout=5):
+        """
+        :param name: A name like `"Vector-A1B2"`. If :code:`None`, will search for any Vector.
+        :param timeout: The discovery will timeout in :code:`timeout` seconds. Default value is :code:`5`.
+        :returns: **dict** or **None** -- if Vector found, **dict** contains keys `"name"` and `"ipv4"`
+
+        .. testcode::
+
+            import anki_vector
+            vector_mdns = anki_vector.mdns.VectorMdns.find_vector("Vector-A1B2")
+
+            if vector_mdns is not None:
+              print(vector_mdns['ipv4'])
+            else:
+              print("No Vector found on your local network!")
+        """
+
+        # synchronously search for Vector for up to 5 seconds
+        vector_name = name  # should be like 'Vector-V3C7'
+        return VectorMdns._start_mdns_listener(vector_name, timeout)
+
+    @staticmethod
+    def _start_mdns_listener(name, timeout):
+        try:
+            from zeroconf import ServiceBrowser, Zeroconf
+        except ImportError:
+            sys.exit("Cannot import from Zeroconf: Do `pip3 install --user zeroconf` to install")
+
+        # create a Condition object and acquire the underlying lock
+        cond = Condition()
+        cond.acquire()
+
+        # instantiate zeroconf and our MdnsListner object for listening to events
+        zeroconf = Zeroconf()
+        vector_fullname = None
+
+        if name is not None:
+            vector_fullname = name + ".local."
+
+        listener = _MdnsListener(vector_fullname, cond)
+
+        # browse for the _ankivector TCP MDNS service, sending events to our listener
+        ServiceBrowser(zeroconf, "_ankivector._tcp.local.", listener)
+
+        # block until 'timeout' seconds or until we discover vector
+        cond.wait(timeout)
+
+        # close zeroconf
+        zeroconf.close()
+
+        # return an IPv4 string (or None)
+        if listener.ipv4 is None:
+            return None
+
+        return {'ipv4': listener.ipv4, 'name': listener.name}
+
+
+class _MdnsListener:
+    """_MdnsListener is an internal helper class which listens for mDNS messages.
+
+    :param name_filter: A String to filter the mDNS responses by name (e.g., `"Vector-A1B2"`).
+    :param condition: A Condition object to be used for signaling to caller when robot has been discovered.
+    """
+
+    def __init__(self, name_filter: str, condition):
+        self.name_filter = name_filter
+        self.cond = condition
+        self.ipv4 = None
+        self.name = ""
+
+    @staticmethod
+    def _bytes_to_str_ipv4(ip_bytes):
+        return str(ip_bytes[0]) + "." +  \
+            str(ip_bytes[1]) + "." +  \
+            str(ip_bytes[2]) + "." +  \
+            str(ip_bytes[3])
+
+    def remove_service(self, zeroconf, mdns_type, name):
+        # detect service removal
+        pass
+
+    def add_service(self, zeroconf, mdns_type, name):
+        # detect service
+        info = zeroconf.get_service_info(mdns_type, name)
+
+        if (self.name_filter is None) or (info.server.lower() == self.name_filter.lower()):
+            # found a match for our filter or there is no filter
+            self.cond.acquire()
+            self.ipv4 = _MdnsListener._bytes_to_str_ipv4(info.address)   # info.address is IPv4 (DNS record type 'A')
+            self.name = info.server
+
+            # cause anything waiting for this condition to end waiting
+            # and release so the other thread can continue
+            self.cond.notify()
+            self.cond.release()
diff --git a/anki_vector/robot.py b/anki_vector/robot.py
@@ -39,6 +39,7 @@
                          VectorUnreliableEventStreamException)
 from .viewer import (ViewerComponent, Viewer3DComponent)
 from .messaging import protocol
+from .mdns import VectorMdns
 
 
 class Robot:
@@ -80,6 +81,8 @@ class Robot:
     :param serial: Vector's serial number. The robot's serial number (ex. 00e20100) is located on the underside of Vector,
                    or accessible from Vector's debug screen. Used to identify which Vector configuration to load.
     :param ip: Vector's IP address. (optional)
+    :param name: Vector's name (in format :code:`"Vector-XXXX"`) to be used for mDNS discovery. If a Vector with the given name
+                 is discovered, the :code:`ip` parameter (and config field) will be overridden.
     :param config: A custom :class:`dict` to override values in Vector's configuration. (optional)
                    Example: :code:`{"cert": "/path/to/file.cert", "name": "Vector-XXXX", "guid": "<secret_key>"}`
                    where :code:`cert` is the certificate to identify Vector, :code:`name` is the name on Vector's face
@@ -106,6 +109,7 @@ class Robot:
     def __init__(self,
                  serial: str = None,
                  ip: str = None,
+                 name: str = None,
                  config: dict = None,
                  default_logging: bool = True,
                  behavior_activation_timeout: int = 10,
@@ -123,7 +127,13 @@ def __init__(self,
         self.logger = util.get_class_logger(__name__, self)
         self._force_async = False
         config = config if config is not None else {}
-        config = {**util.read_configuration(serial, self.logger), **config}
+        config = {**util.read_configuration(serial, name, self.logger), **config}
+
+        if name is not None:
+            vector_mdns = VectorMdns.find_vector(name)
+
+            if vector_mdns is not None:
+                ip = vector_mdns['ipv4']
 
         self._name = config["name"]
         self._ip = ip if ip is not None else config["ip"]
diff --git a/anki_vector/util.py b/anki_vector/util.py
@@ -1079,11 +1079,17 @@ def grpc_interface(self):
         return self._robot.conn.grpc_interface
 
 
-def read_configuration(serial: str, logger: logging.Logger) -> dict:
+def read_configuration(serial: str, name: str, logger: logging.Logger) -> dict:
     """Open the default conf file, and read it into a :class:`configparser.ConfigParser`
+    If :code:`serial is not None`, this method will try to find a configuration with serial
+    number :code:`serial`, and raise an exception otherwise. If :code:`serial is None` and
+    :code:`name is not None`, this method will try to find a configuration which matches
+    the provided name, and raise an exception otherwise. If both :code:`serial is None` and
+    :code:`name is None`, this method will return a configuration if exactly `1` exists, but
+    if multiple configurations exists, it will raise an exception.
 
     :param serial: Vector's serial number
-    :param logger: Logger object
+    :param name: Vector's name
     """
     home = Path.home() / ".anki_vector"
     conf_file = str(home / "sdk_config.ini")
@@ -1093,20 +1099,34 @@ def read_configuration(serial: str, logger: logging.Logger) -> dict:
     sections = parser.sections()
     if not sections:
         raise VectorConfigurationException('Could not find the sdk configuration file. Please run `python3 -m anki_vector.configure` to set up your Vector for SDK usage.')
-    if serial is None and len(sections) == 1:
-        serial = sections[0]
-        logger.warning("No serial number provided. Automatically selecting {}".format(serial))
-    elif serial is None:
-        raise VectorConfigurationException("Found multiple robot serial numbers. "
-                                           "Please provide the serial number of the Robot you want to control.\n\n"
-                                           "Example: ./01_hello_world.py --serial {{robot_serial_number}}")
-
-    serial = serial.lower()
+    elif (serial is None) and (name is None):
+        if len(sections) == 1:
+            serial = sections[0]
+            logger.warning("No serial number or name provided. Automatically selecting {}".format(serial))
+        else:
+            raise VectorConfigurationException("Found multiple robot serial numbers. "
+                                               "Please provide the serial number or name of the Robot you want to control.\n\n"
+                                               "Example: ./01_hello_world.py --serial {{robot_serial_number}}")
+
     config = {k.lower(): v for k, v in parser.items()}
-    try:
-        dict_entry = config[serial]
-    except KeyError:
-        raise VectorConfigurationException("Could not find matching robot info for given serial number: {}. "
-                                           "Please check your serial number is correct.\n\n"
-                                           "Example: ./01_hello_world.py --serial {{robot_serial_number}}", serial)
-    return dict_entry
+
+    if serial is not None:
+        serial = serial.lower()
+        try:
+            return config[serial]
+        except KeyError:
+            raise VectorConfigurationException("Could not find matching robot info for given serial number: {}. "
+                                               "Please check your serial number is correct.\n\n"
+                                               "Example: ./01_hello_world.py --serial {{robot_serial_number}}", serial)
+    else:
+        for keySerial in config:
+            for key in config[keySerial]:
+                if config[keySerial][key] == name:
+                    return config[keySerial]
+                elif config[keySerial][key].lower() == name.lower():
+                    logger.warning("Using case-insensitive name match found in config. Set 'name' field to match 'Vector-A1B2' format.")
+                    return config[keySerial]
+
+        raise VectorConfigurationException("Could not find matching robot info for given name: {}. "
+                                           "Please check your name is correct.\n\n"
+                                           "Example: ./01_hello_world.py --name {{robot_name}}", name)
diff --git a/docs/source/advanced-tips.rst b/docs/source/advanced-tips.rst
@@ -11,8 +11,32 @@ Moving Vector between WiFi networks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When you move Vector from one WiFi network to another (using the Vector App),
-or if your Vector's IP changes,  you will also need to make some changes to
-your SDK setup. To assist in this migration, the ``anki_vector.configure``
+or if your Vector's IP changes, the SDK will need to determine Vector's new IP address.
+There are two ways to accomplish this. 
+
+****************************
+1. Automatic: mDNS Discovery
+****************************
+
+The SDK will automatically discover your Vector, even on a new WiFi network, 
+when you connect as follows::
+
+    import anki_vector
+
+    with anki_vector.Robot(name="Vector-A1B2") as robot:
+        # The sdk will try to connect to 'Vector A1B2', 
+        # even if its IP address has changed. 
+        pass
+
+You will need to install the ``zeroconf`` package to use this feature::
+
+    pip3 install --user zeroconf
+
+*******************************
+2. Manual: Update Configuration
+*******************************
+
+Alternatively, you can manually make changes to your SDK setup. To assist in this migration, the ``anki_vector.configure``
 executable submodule provides a ``-u`` parameter to quickly reconnect to Vector.
 
 To update your connection, you will need to find the IP address on
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -19,6 +19,7 @@ The API
     anki_vector.exceptions
     anki_vector.faces
     anki_vector.lights
+    anki_vector.mdns
     anki_vector.messaging
     anki_vector.motors
     anki_vector.nav_map
