odrive 0.6.9.dev0__py37-none-win_amd64.whl

odrive/pyfibre/fibre/shell.py

@@ -0,0 +1,162 @@
+
+import sys
+import platform
+import threading
+import fibre
+
+async def discovered_device(device,
+                        interactive_variables, objects, discovered_devices,
+                        mount, shutdown_token, logger):
+    """
+    Handles the discovery of new devices by displaying a
+    message and making the device available to the interactive
+    console
+    """
+    mount_result = await mount(device)
+    if mount_result is None:
+        logger.debug("ignoring device")
+        return
+
+    display_name, serial_number, var_name = mount_result
+
+    if serial_number in discovered_devices:
+        verb = "Reconnected"
+        index = discovered_devices.index(serial_number)
+    else:
+        verb = "Connected"
+        discovered_devices.append(serial_number)
+        index = len(discovered_devices) - 1
+
+    var_name = var_name + str(index)
+
+    # Publish new device to interactive console
+    interactive_variables[var_name] = device
+    device.__sealed__ = False
+    try:
+        device.__name__ = var_name
+    finally:
+        device.__sealed__ = True
+    objects.append(device)
+    globals()[var_name] = device # Add to globals so tab complete works
+    logger.notify("{} to {} as {}".format(verb, display_name, var_name))
+
+    # Subscribe to disappearance of the device
+    device._on_lost.add_done_callback(lambda x: lost_device(var_name, shutdown_token, logger))
+
+def lost_device(interactive_name, shutdown_token, logger):
+    """
+    Handles the disappearance of a device by displaying
+    a message.
+    """
+    if not shutdown_token[0]:
+        logger.warn("Oh no {} disappeared".format(interactive_name))
+
+def get_user_name(interactive_variables, obj):
+    queue = [(k, v) for k, v in interactive_variables.items() if isinstance(v, fibre.libfibre.RemoteObject)]
+
+    if not isinstance(obj, fibre.libfibre.RemoteObject):
+        return None
+
+    while len(queue):
+        k, v = queue.pop(0)
+        if v == obj:
+            return k
+        for key in dir(v.__class__):
+            class_member = getattr(v.__class__, key)
+            if not key.startswith('_') and isinstance(class_member, fibre.libfibre.RemoteAttribute):
+                queue.append((k + "." + (key if not class_member._magic_getter else "_" + key + "_property"), class_member._get_obj(v)))
+
+    return "anonymous_remote_object_" + str(self._obj_handle)
+
+def launch_shell(args, mount,
+                interactive_variables,
+                objects,
+                print_banner, print_help,
+                logger):
+    """
+    Launches an interactive python or IPython command line
+    interface.
+    As devices are connected they are made available as
+    "dev0", "dev1", ...
+    The names of the variables can be customized by setting branding_short.
+    """
+
+    discovered_devices = []
+    shutdown_token = [False]
+    globals().update(interactive_variables)
+
+    fibre.libfibre.get_user_name = lambda obj: get_user_name(interactive_variables, obj)
+
+    # Connect to device
+    with fibre.Domain(args.path) as domain:
+        on_discovery = lambda dev: discovered_device(dev, interactive_variables, objects, discovered_devices, mount, shutdown_token, logger)
+        discovery = domain.run_discovery(on_discovery)
+
+        # Check if IPython is installed
+        if args.no_ipython:
+            use_ipython = False
+        else:
+            try:
+                import IPython
+                use_ipython = True
+            except:
+                print("Warning: you don't have IPython installed.")
+                print("If you want to have an improved interactive console with pretty colors,")
+                print("you should install IPython\n")
+                use_ipython = False
+
+        interactive_variables["help"] = lambda: print_help(args, len(discovered_devices) > 0)
+
+        # If IPython is installed, embed IPython shell, otherwise embed regular shell
+        if use_ipython:
+            # Override help function # pylint: disable=W0612
+            help = lambda: print_help(args, len(discovered_devices) > 0) 
+            # to fix broken "%run -i script.py"
+            locals()['__name__'] = globals()['__name__'] 
+
+            if IPython.core.getipython.get_ipython() is None:
+                console = IPython.terminal.embed.InteractiveShellEmbed.instance(banner1='')
+            else:
+                console = IPython.terminal.embed.InteractiveShellEmbed(banner1='')
+
+            # hack to make IPython look like the regular console
+            console.runcode = console.run_cell 
+            interact = console
+
+            # Catch ObjectLostError (since disconnect is not always an error)
+            default_exception_hook = console._showtraceback
+            def filtered_exception_hook(ex_class, ex, trace):
+                if(ex_class.__module__+'.'+ex_class.__name__ != 'fibre.libfibre.ObjectLostError'):
+                    default_exception_hook(ex_class,ex,trace)
+                
+            console._showtraceback = filtered_exception_hook
+        else:
+            # Enable tab complete if possible
+            try:
+                import readline # Works only on Unix
+                readline.parse_and_bind("tab: complete")
+            except:
+                sudo_prefix = "" if platform.system() == "Windows" else "sudo "
+                print("Warning: could not enable tab-complete. User experience will suffer.\n"
+                    "Run `{}pip install readline` and then restart this script to fix this."
+                    .format(sudo_prefix))
+
+            import code
+            console = code.InteractiveConsole(locals=interactive_variables)
+            interact = lambda: console.interact(banner='')
+
+            # Catch ObjectLostError (since disconnect is not alway an error)
+            console.runcode("import sys")
+            console.runcode("default_exception_hook = sys.excepthook")
+            console.runcode("def filtered_exception_hook(ex_class, ex, trace):\n"
+                            "  if ex_class.__module__ + '.' + ex_class.__name__ != 'fibre.libfibre.ObjectLostError':\n"
+                            "    default_exception_hook(ex_class,ex,trace)")
+            console.runcode("sys.excepthook=filtered_exception_hook")
+
+        # Launch shell
+        print_banner()
+        logger._skip_bottom_line = True
+        interact()
+
+        shutdown_token[0] = True
+        discovery.stop()

odrive/pyfibre/fibre/utils.py

@@ -0,0 +1,133 @@
+
+import sys
+import time
+import threading
+import platform
+import subprocess
+import os
+
+try:
+    if platform.system() == 'Windows':
+        import win32console
+        # TODO: we should win32console anyway so we could just omit colorama
+        import colorama
+        colorama.init()
+except ImportError:
+    print("Could not init terminal features.")
+    sys.stdout.flush()
+    pass
+
+
+## Log utils ##
+
+# TODO: use "logging" from Python standard library instead of this
+class Logger():
+    """
+    Logs messages to stdout
+    """
+
+    COLOR_DEFAULT = 0
+    COLOR_GREEN = 1
+    COLOR_CYAN = 2
+    COLOR_YELLOW = 3
+    COLOR_RED = 4
+
+    _VT100Colors = {
+        COLOR_GREEN: '\x1b[92;1m',
+        COLOR_CYAN: '\x1b[96;1m',
+        COLOR_YELLOW: '\x1b[93;1m',
+        COLOR_RED: '\x1b[91;1m',
+        COLOR_DEFAULT: '\x1b[0m'
+    }
+
+    _Win32Colors = {
+        COLOR_GREEN: 0x0A,
+        COLOR_CYAN: 0x0B,
+        COLOR_YELLOW: 0x0E,
+        COLOR_RED: 0x0C,
+        COLOR_DEFAULT: 0x07
+    }
+
+    def __init__(self, verbose=True):
+        self._prefix = ''
+        self._skip_bottom_line = False # If true, messages are printed one line above the cursor
+        self._verbose = verbose
+        self._print_lock = threading.Lock()
+        if platform.system() == 'Windows':
+            self._stdout_buf = win32console.GetStdHandle(win32console.STD_OUTPUT_HANDLE)
+
+    def indent(self, prefix='  '):
+        indented_logger = Logger()
+        indented_logger._prefix = self._prefix + prefix
+        return indented_logger
+
+    def print_on_second_last_line(self, text, color):
+        """
+        Prints a text on the second last line.
+        This can be used to print a message above the command
+        prompt. If the command prompt spans multiple lines
+        there will be glitches.
+        If the printed text spans multiple lines there will also
+        be glitches (though this could be fixed).
+        """
+
+        if platform.system() == 'Windows':
+            # Windows <10 doesn't understand VT100 escape codes and the colorama
+            # also doesn't support the specific escape codes we need so we use the
+            # native Win32 API.
+            info = self._stdout_buf.GetConsoleScreenBufferInfo()
+            cursor_pos = info['CursorPosition']
+            scroll_rect=win32console.PySMALL_RECTType(
+                Left=0, Top=1,
+                Right=info['Window'].Right,
+                Bottom=cursor_pos.Y-1)
+            scroll_dest = win32console.PyCOORDType(scroll_rect.Left, scroll_rect.Top-1)
+            self._stdout_buf.ScrollConsoleScreenBuffer(
+                scroll_rect, scroll_rect, scroll_dest, # clipping rect is same as scroll rect
+                u' ', Logger._Win32Colors[color]) # fill with empty cells with the desired color attributes
+            line_start = win32console.PyCOORDType(0, cursor_pos.Y-1)
+            self._stdout_buf.WriteConsoleOutputCharacter(text, line_start)
+
+        else:
+            # Assume we're in a terminal that interprets VT100 escape codes.
+            # TODO: test on macOS
+
+            # Escape character sequence:
+            #   ESC 7: store cursor position
+            #   ESC 1A: move cursor up by one
+            #   ESC 1S: scroll entire viewport by one
+            #   ESC 1L: insert 1 line at cursor position
+            #   (print text)
+            #   ESC 8: restore old cursor position
+
+            self._print_lock.acquire()
+            sys.stdout.write('\x1b7\x1b[1A\x1b[1S\x1b[1L')
+            sys.stdout.write(Logger._VT100Colors[color] + text + Logger._VT100Colors[Logger.COLOR_DEFAULT])
+            sys.stdout.write('\x1b8')
+            sys.stdout.flush()
+            self._print_lock.release()
+
+    def print_colored(self, text, color):
+        if self._skip_bottom_line:
+            self.print_on_second_last_line(text, color)
+        else:
+            # On Windows, colorama does the job of interpreting the VT100 escape sequences
+            self._print_lock.acquire()
+            sys.stdout.write(Logger._VT100Colors[color] + text + Logger._VT100Colors[Logger.COLOR_DEFAULT] + '\n')
+            sys.stdout.flush()
+            self._print_lock.release()
+
+    def debug(self, text):
+        if self._verbose:
+            self.print_colored(self._prefix + text, Logger.COLOR_DEFAULT)
+    def success(self, text):
+        self.print_colored(self._prefix + text, Logger.COLOR_GREEN)
+    def info(self, text):
+        self.print_colored(self._prefix + text, Logger.COLOR_DEFAULT)
+    def notify(self, text):
+        self.print_colored(self._prefix + text, Logger.COLOR_CYAN)
+    def warn(self, text):
+        self.print_colored(self._prefix + text, Logger.COLOR_YELLOW)
+    def error(self, text):
+        # TODO: write to stderr
+        self.print_colored(self._prefix + text, Logger.COLOR_RED)

odrive/release_api.py

@@ -0,0 +1,184 @@
+import enum
+import hashlib
+import os
+import re
+from typing import Optional
+
+import appdirs
+
+from odrive.api_client import ApiClient
+from odrive.crypto import safe_b64decode, safe_b64encode
+from odrive.hw_version import HwVersion
+
+class ReleaseApi():
+    BASE_URL = '/releases'
+
+    def __init__(self, api_client: 'ApiClient'):
+        self._api_client = api_client
+
+    async def get_index(self, release_type: str):
+        outputs = await self._api_client.call('GET', ReleaseApi.BASE_URL + '/' + release_type + '/index')
+        return ReleaseIndex(outputs['files'], outputs['commits'], outputs['channels'])
+
+    async def load(self, manifest: dict, force_download: bool = False):
+        """
+        Downloads a firmware file and saves it in a cache directory.
+        If the file was already cached before, it is loaded from disk instead
+        (unless force_download is True).
+        Returns the path of the cached file.
+        """
+        cache_dir = os.path.join(appdirs.user_cache_dir("odrivetool", "ODrive Robotics"), 'firmware')
+        os.makedirs(cache_dir, exist_ok=True)
+        cache_path = os.path.join(cache_dir, manifest['content_key'] + '.elf')
+
+        if force_download or not os.path.isfile(cache_path):
+            content = await self._api_client.download(manifest['url'])
+            with open(cache_path, 'wb') as fp:
+                fp.write(content)
+
+        return cache_path
+
+
+class VersionRelationship(enum.Enum):
+    UNKNOWN = enum.auto()
+    EQUAL = enum.auto()
+    UPGRADE = enum.auto()
+    DOWNGRADE = enum.auto()
+
+class ChannelNotFoundError(Exception):
+    pass
+
+class FirmwareNotFoundError(Exception):
+    pass
+
+class ReleaseIndex():
+    def __init__(self, files, commits, channels):
+        self._files = {safe_b64decode(f['content']): f for f in files}
+        self._commits = commits
+        for c in commits:
+            c['content'] = safe_b64decode(c['content'])
+        for c in commits:
+            if 'board' in c:
+                c['board'] = HwVersion.from_tuple(c['board'])
+        self._open_channels = {c['channel']: c['commits'] for c in channels if not c['closed']}
+        self._closed_channels = {c['channel']: c['commits'] for c in channels if c['closed']}
+
+    @property
+    def open_channel_names(self):
+        return list(self._open_channels.keys())
+
+    def _get_filtered_versions(self, channel_info: list, has_file: Optional[str], **qualifiers: dict) -> list:
+        """
+        Returns a list of version info objects where all qualifiers match and
+        where the version name is contained in channel_info.
+
+        The list is ordered "most relevant first".
+
+        Specifically, it is sorted on two levels:
+            version name (as ordered in channel_info)
+            variant ("internal" before "public" before other or unspecified)
+        """
+        if 'product' in qualifiers:
+            import warnings
+            warnings.warn('The "product" qualifier is deprecated. Use "board" instead.', DeprecationWarning, stacklevel=0)
+
+        version_infos = [
+            c for c in self._commits
+            if (c['commit_hash'] in channel_info) and (has_file is None or has_file in c.get('index', [])) and all((k in c) and (c[k] == v) for k, v in qualifiers.items())
+        ]
+        return sorted(version_infos, key=lambda c: (
+            channel_info.index(c['commit_hash']),
+            {'internal': 0, 'public': 1}.get(c.get('variant', None), 2)))
+
+    def _get_channel_info(self, channel: str):
+        if channel in self._open_channels:
+            return self._open_channels[channel]
+        elif channel in self._closed_channels:
+            return self._closed_channels[channel]
+        else:
+            raise ChannelNotFoundError(f"Channel {channel} not found.")
+
+    def _get_manifest(self, version_info, file: Optional[str] = None):
+        content_key = version_info['content']
+
+        url = self._files[content_key]['url']
+        if not file is None:
+            base_url = url[:url.rfind('/')] # substring up to last /
+            url = base_url + '/' + file
+
+        return {
+            'content_key': safe_b64encode(content_key),
+            'commit_hash': version_info['commit_hash'],
+            'release_date': self._files[content_key]['release_date'],
+            'url': url
+        }
+
+    def get_latest(self, channel: str, file: Optional[str] = None, **qualifiers: dict):
+        """
+        Checks for the latest firmware on the specified channel with the specified
+        qualifiers (product, app).
+
+        If the specified channel is not found or empty, an exception is thrown.
+        Returns a metadata manifest for the release that was found.
+        """
+        channel_info = list(reversed(self._get_channel_info(channel)))
+        filtered_versions = self._get_filtered_versions(channel_info, has_file=file, **qualifiers)
+
+        if len(filtered_versions) == 0:
+            raise FirmwareNotFoundError()
+
+        return self._get_manifest(filtered_versions[0], file)
+
+    def get_version(self, version: str, file: Optional[str] = None, **qualifiers: dict):
+        """
+        Looks up the release information for the specified commit with the
+        specified qualifiers (product, app).
+
+        Returns a metadata manifest for the release that was found.
+        """
+        filtered_versions = self._get_filtered_versions(channel_info=[version], has_file=file, **qualifiers)
+
+        if len(filtered_versions) == 0:
+            raise FirmwareNotFoundError()
+
+        return self._get_manifest(filtered_versions[0], file)
+
+    def compare(self, from_version: Optional[str], to_version: str, channel: str, **qualifiers: dict):
+        """
+        Checks if the specified transition is an upgrade or not.
+        """
+
+        return VersionRelationship.UNKNOWN # TODO
+
+        if from_version is None:
+            return VersionRelationship.UNKNOWN
+
+        filtered_commits = self._get_filtered_versions(**qualifiers)
+
+        short_hashes = {h[:8]: h for h in filtered_commits.keys()}
+        from_version = short_hashes.get(from_version, from_version)
+        
+        if not from_version in filtered_commits or not to_version in filtered_commits:
+            return VersionRelationship.UNKNOWN
+        
+        from_file = filtered_commits[from_version]
+        to_file = filtered_commits[to_version]
+
+        if from_file == to_file:
+            return VersionRelationship.EQUAL
+        
+        filtered_channel_commits = self._get_filtered_channel_commits(channel, filtered_commits)
+
+        if not from_file in filtered_channel_commits or not to_file in filtered_channel_commits:
+            return VersionRelationship.UNKNOWN
+        
+        if filtered_channel_commits.index(from_file) < filtered_channel_commits.index(to_file):
+            return VersionRelationship.UPGRADE
+        else:
+            return VersionRelationship.DOWNGRADE
+
+
+def format_version(version: str):
+    if re.match("^[0-9a-fA-F]*$", version) and (len(version) == 8 or len(version) == 40):
+        return version.lower()[:8]
+    return version

odrive/rich_text.py

@@ -0,0 +1,134 @@
+
+import enum
+from typing import Iterable, Union, Optional, List, Tuple, Sequence, cast
+
+class Style(enum.IntEnum):
+    NONE = 0x00
+    BOLD = 0x01
+    ITALIC = 0x02
+    UNDERLINE = 0x04
+
+class Color(enum.Enum):
+    DEFAULT = enum.auto() # the terminal's default color
+    COLOR_MASK = enum.auto()
+    RED = enum.auto()
+    YELLOW = enum.auto()
+    GREEN = enum.auto()
+    CYAN = enum.auto()
+    BLUE = enum.auto()
+    MAGENTA = enum.auto()
+    GRAY = enum.auto()
+
+
+class RichText():
+    """
+    Represents a text consisting of styled/colored string segments.
+    """
+    segments: List[Tuple[str, Color, Color, Style]]
+
+    def __init__(self, val: Union[str, 'RichText', Sequence[Union[str, 'RichText']]], foreground: Optional[Color] = None, background: Optional[Color] = None, style: Optional[Style] = None):
+        """
+        val: A string, a RichText object or a list of strings or RichText
+        objects.
+        style: If specified, overrides the style of all segments in `val`.
+        If not specified, uncolored strings are set to the default color.
+        """
+
+        if not (isinstance(val, tuple) or isinstance(val, list)):
+            val = [cast(Union[str, 'RichText'], val)]
+
+        self.segments = []
+        for segment in val:
+            if isinstance(segment, str):
+                self.segments.append((segment, Color.DEFAULT, Color.DEFAULT, Style.NONE))
+            elif isinstance(segment, RichText):
+                self.segments.extend(segment.segments)
+            else:
+                raise Exception("unsupported argument")
+        
+        # Override attributes
+        for i, (seg_str, seg_foreground, seg_background, seg_style) in enumerate(self.segments):
+            if not style is None:
+                seg_style = style
+            if not foreground is None:
+                seg_foreground = foreground
+            if not background is None:
+                seg_background = background
+            self.segments[i] = (seg_str, seg_foreground, seg_background, seg_style)
+
+        # Remove empty segments
+        i = 0
+        while i < len(self.segments):
+            if self.segments[i][0] == '':
+                self.segments.pop(i)
+            else:
+                i += 1
+
+        # Coalesce segments with identical attributes
+        i = 1
+        while i < len(self.segments):
+            if self.segments[i - 1][1:] == self.segments[i][1:]:
+                self.segments[i - 1] = (self.segments[i - 1][0] + self.segments.pop(i)[0],) + self.segments[i - 1][1:]
+            else:
+                i += 1
+
+    def __add__(self, other):
+        if isinstance(other, str) or isinstance(other, RichText):
+            return RichText([self, other])
+        else:
+            raise NotImplementedError(f"can only concatenate str and RichText (not {type(other).__name__}) to RichText.")
+
+    def __radd__(self, other):
+        if isinstance(other, str) or isinstance(other, RichText):
+            return RichText([other, self])
+        else:
+            raise NotImplementedError(f"can only concatenate RichText to str and RichText (not {type(other).__name__}).")
+    
+    def __repr__(self):
+        return ''.join([s[0] for s in self.segments])
+
+    def join(self, others: Iterable[Union['RichText', str]]):
+        """
+        Analogous to str.join()
+        """
+        segments: List[Union[str, RichText]] = []
+        for item in others:
+            segments.append(self)
+            segments.append(item)
+        return RichText(segments[1:]) if len(segments) > 0 else RichText("")
+
+    def replace(self, old: str, new: str):
+        new_segments = [
+            RichText(seg[0].replace(old, new), *seg[1:])
+            for seg in self.segments
+        ]
+        return RichText(new_segments)
+
+_VT100Colors = {
+    Color.DEFAULT: 39,
+    Color.GREEN: 92,
+    Color.CYAN: 96,
+    Color.YELLOW: 93,
+    Color.RED: 91,
+    Color.GRAY: 97,
+}
+
+def print_rich_text(text: RichText):
+    """
+    Prints `text` to stdout using VT100 escape codes for styling.
+    """
+    assert isinstance(text, RichText), type(text)
+    output = ''
+    for substr, foreground, background, style in text.segments:
+        output += '\x1b[0' # reset all text attributes
+        output +=  ';' + str(_VT100Colors[foreground])
+        output +=  ';' + str(_VT100Colors[background] + 10)
+        if style & Style.BOLD:
+            output += ';1'
+        if style & Style.UNDERLINE:
+            output += ';4'
+        output += 'm' + substr
+
+    if len(text.segments) > 0:
+        output += '\x1b[0m' # reset all attributes
+    print(output)