reachy-mini 1.0.0__py3-none-any.whl

reachy_mini/__init__.py

@@ -0,0 +1,4 @@
+"""Reachy Mini SDK."""
+
+from reachy_mini.apps.app import ReachyMiniApp  # noqa: F401
+from reachy_mini.reachy_mini import ReachyMini  # noqa: F401

reachy_mini/apps/__init__.py

@@ -0,0 +1,24 @@
+"""Metadata about apps."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict
+
+
+class SourceKind(str, Enum):
+    """Kinds of app source."""
+
+    HF_SPACE = "hf_space"
+    LOCAL = "local"
+    INSTALLED = "installed"
+
+
+@dataclass
+class AppInfo:
+    """Metadata about an app."""
+
+    name: str
+    source_kind: SourceKind
+    description: str = ""
+    url: str | None = None
+    extra: Dict[str, Any] = field(default_factory=dict)

reachy_mini/apps/app.py

@@ -0,0 +1,121 @@
+"""Reachy Mini Application Base Class.
+
+This module provides a base class for creating Reachy Mini applications.
+It includes methods for running the application, stopping it gracefully,
+and creating a new app project with a specified name and path.
+
+It uses Jinja2 templates to generate the necessary files for the app project.
+"""
+
+import threading
+import traceback
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict
+
+from jinja2 import Environment, FileSystemLoader
+
+from reachy_mini.reachy_mini import ReachyMini
+
+
+class ReachyMiniApp(ABC):
+    """Base class for Reachy Mini applications."""
+
+    def __init__(self) -> None:
+        """Initialize the Reachy Mini app."""
+        self.stop_event = threading.Event()
+        self.error: str = ""
+
+    def wrapped_run(self, *args: Any, **kwargs: Any) -> None:
+        """Wrap the run method with Reachy Mini context management."""
+        try:
+            with ReachyMini(*args, **kwargs) as reachy_mini:
+                self.run(reachy_mini, self.stop_event)
+        except Exception:
+            self.error = traceback.format_exc()
+            raise
+
+    @abstractmethod
+    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
+        """Run the main logic of the app.
+
+        Args:
+            reachy_mini (ReachyMini): The Reachy Mini instance to interact with.
+            stop_event (threading.Event): An event that can be set to stop the app gracefully.
+
+        """
+        pass
+
+    def stop(self) -> None:
+        """Stop the app gracefully."""
+        self.stop_event.set()
+        print("App is stopping...")
+
+
+def make_app_project(app_name: str, path: Path) -> None:
+    """Create a new Reachy Mini app project with the given name at the specified path.
+
+    Args:
+        app_name (str): The name of the app to create.
+        path (Path): The directory where the app project will be created.
+
+    """
+    TEMPLATE_DIR = Path(__file__).parent / "templates"
+    env = Environment(loader=FileSystemLoader(TEMPLATE_DIR))
+
+    def render_template(filename: str, context: Dict[str, str]) -> str:
+        template = env.get_template(filename)
+        return template.render(context)
+
+    base_path = Path(path).resolve() / app_name
+    if base_path.exists():
+        print(f"❌ Folder {base_path} already exists.")
+        return
+
+    module_name = app_name.replace("-", "_")
+    class_name = "".join(word.capitalize() for word in module_name.split("_"))
+
+    base_path.mkdir()
+    (base_path / module_name).mkdir()
+
+    # Generate files
+    context = {
+        "app_name": app_name,
+        "package_name": app_name,
+        "module_name": module_name,
+        "class_name": class_name,
+    }
+
+    (base_path / module_name / "__init__.py").touch()
+    (base_path / module_name / "main.py").write_text(
+        render_template("main.py.j2", context)
+    )
+    (base_path / "pyproject.toml").write_text(
+        render_template("pyproject.toml.j2", context)
+    )
+    (base_path / "README.md").write_text(render_template("README.md.j2", context))
+
+    print(f"✅ Created app in {base_path}/")
+
+
+def main() -> None:
+    """Run the command line interface to create a new Reachy Mini app project."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Create a new Reachy Mini app project."
+    )
+    parser.add_argument("app_name", type=str, help="Name of the app to create.")
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path.cwd(),
+        help="Path where the app project will be created.",
+    )
+
+    args = parser.parse_args()
+    make_app_project(args.app_name, args.path)
+
+
+if __name__ == "__main__":
+    main()

reachy_mini/apps/manager.py

@@ -0,0 +1,183 @@
+"""App management for Reachy Mini."""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from importlib.metadata import entry_points
+from threading import Thread
+from typing import TYPE_CHECKING, Any, Optional
+
+from pydantic import BaseModel
+
+from . import AppInfo, SourceKind
+from .sources import hf_space, local_common_venv
+
+if TYPE_CHECKING:
+    from .app import ReachyMiniApp
+
+
+class AppState(str, Enum):
+    """Status of a running app."""
+
+    STARTING = "starting"
+    RUNNING = "running"
+    DONE = "done"
+    STOPPING = "stopping"
+    ERROR = "error"
+
+
+class AppStatus(BaseModel):
+    """Status of an app."""
+
+    info: AppInfo
+    state: AppState
+    error: str | None = None
+
+
+@dataclass
+class RunningApp:
+    """Information about a running app."""
+
+    app: "ReachyMiniApp"
+    thread: Thread
+    status: AppStatus
+
+
+class AppManager:
+    """Manager for Reachy Mini apps."""
+
+    def __init__(self) -> None:
+        """Initialize the AppManager."""
+        self.current_app = None  # type: RunningApp | None
+        self.logger = logging.getLogger("reachy_mini.apps.manager")
+
+    async def close(self) -> None:
+        """Clean up the AppManager, stopping any running app."""
+        if self.is_app_running():
+            await self.stop_current_app()
+
+    # App lifecycle management
+    # Only one app can be started at a time for now
+    def is_app_running(self) -> bool:
+        """Check if an app is currently running."""
+        return self.current_app is not None and self.current_app.status.state in (
+            AppState.STARTING,
+            AppState.RUNNING,
+            AppState.ERROR,
+        )
+
+    async def start_app(self, app_name: str, *args: Any, **kwargs: Any) -> AppStatus:
+        """Start the app, raises RuntimeError if an app is already running."""
+        if self.is_app_running():
+            raise RuntimeError("An app is already running")
+
+        (ep,) = entry_points(group="reachy_mini_apps", name=app_name)
+        app = ep.load()()
+
+        def wrapped_run() -> None:
+            assert self.current_app is not None
+
+            try:
+                self.current_app.status.state = AppState.RUNNING
+                self.logger.getChild("runner").info(f"App {app_name} is running")
+                app.wrapped_run(*args, **kwargs)
+                self.current_app.status.state = AppState.DONE
+                self.logger.getChild("runner").info(f"App {app_name} finished")
+            except Exception as e:
+                self.logger.getChild("runner").error(
+                    f"An error occurred in the app {app_name}: {e}"
+                )
+                self.logger.getChild("runner").error(
+                    f"Exception details: '{app.error}'",
+                )
+                self.current_app.status.state = AppState.ERROR
+                self.current_app.status.error = str(app.error)
+
+        self.current_app = RunningApp(
+            status=AppStatus(
+                info=AppInfo(name=app_name, source_kind=SourceKind.INSTALLED),
+                state=AppState.STARTING,
+                error=None,
+            ),
+            app=app,
+            thread=Thread(target=wrapped_run),
+        )
+        self.logger.getChild("runner").info(f"Starting app {app_name}")
+        self.current_app.thread.start()
+
+        return self.current_app.status
+
+    async def stop_current_app(self, timeout: float | None = 5.0) -> None:
+        """Stop the current app."""
+        if not self.is_app_running():
+            raise RuntimeError("No app is currently running")
+
+        assert self.current_app is not None
+
+        self.current_app.status.state = AppState.STOPPING
+        self.logger.getChild("runner").info(
+            f"Stopping app {self.current_app.status.info.name}"
+        )
+        self.current_app.app.stop()
+        self.current_app.thread.join(timeout)
+
+        if self.current_app.thread.is_alive():
+            self.logger.getChild("runner").warning(
+                "The app did not stop within the timeout"
+            )
+        else:
+            self.logger.getChild("runner").info("App stopped successfully")
+
+        self.current_app = None
+
+    async def restart_current_app(self) -> AppStatus:
+        """Restart the current app."""
+        if not self.is_app_running():
+            raise RuntimeError("No app is currently running")
+
+        assert self.current_app is not None
+
+        app_info = self.current_app.status.info
+
+        await self.stop_current_app()
+        await self.start_app(app_info.name)
+
+        return self.current_app.status
+
+    async def current_app_status(self) -> Optional[AppStatus]:
+        """Get the current status of the app."""
+        if self.current_app is not None:
+            return self.current_app.status
+        return None
+
+    # Apps management interface
+    async def list_all_available_apps(self) -> list[AppInfo]:
+        """List available apps (parallel async)."""
+        results = await asyncio.gather(
+            *[self.list_available_apps(kind) for kind in SourceKind]
+        )
+        return sum(results, [])
+
+    async def list_available_apps(self, source: SourceKind) -> list[AppInfo]:
+        """List available apps for given source kind."""
+        if source == SourceKind.HF_SPACE:
+            return await hf_space.list_available_apps()
+        elif source == SourceKind.INSTALLED:
+            return await local_common_venv.list_available_apps()
+        elif source == SourceKind.LOCAL:
+            return []
+        else:
+            raise NotImplementedError(f"Unknown source kind: {source}")
+
+    async def install_new_app(self, app: AppInfo, logger: logging.Logger) -> None:
+        """Install a new app by name."""
+        success = await local_common_venv.install_package(app, logger)
+        if success != 0:
+            raise RuntimeError(f"Failed to install app '{app.name}'")
+
+    async def remove_app(self, app_name: str, logger: logging.Logger) -> None:
+        """Remove an installed app by name."""
+        success = await local_common_venv.uninstall_package(app_name, logger)
+        if success != 0:
+            raise RuntimeError(f"Failed to uninstall app '{app_name}'")

reachy_mini/apps/sources/__init__.py

@@ -0,0 +1,4 @@
+"""Specific app sources.
+
+For the moment, only huggingface spaces is implemented.
+"""

reachy_mini/apps/sources/hf_space.py

@@ -0,0 +1,25 @@
+"""Hugging Face Spaces app source."""
+
+import aiohttp
+
+from .. import AppInfo, SourceKind
+
+
+async def list_available_apps() -> list[AppInfo]:
+    """List apps available on Hugging Face Spaces."""
+    url = "https://huggingface.co/api/spaces?filter=reachy_mini&sort=likes&direction=-1&limit=50&full=true"
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            data = await response.json()
+    apps = []
+    for item in data:
+        apps.append(
+            AppInfo(
+                name=item["id"].split("/")[-1],
+                description=item["cardData"].get("short_description", ""),
+                url=f"https://huggingface.co/spaces/{item['id']}",
+                source_kind=SourceKind.HF_SPACE,
+                extra=item,
+            )
+        )
+    return apps

reachy_mini/apps/sources/local_common_venv.py

@@ -0,0 +1,44 @@
+"""Utilities for local common venv apps source."""
+
+import logging
+import sys
+from importlib.metadata import entry_points
+
+from .. import AppInfo, SourceKind
+from ..utils import running_command
+
+
+async def list_available_apps() -> list[AppInfo]:
+    """List apps available from entry points."""
+    entry_point_apps = list(entry_points(group="reachy_mini_apps"))
+    return [
+        AppInfo(name=ep.name, source_kind=SourceKind.INSTALLED)
+        for ep in entry_point_apps
+    ]
+
+
+async def install_package(app: AppInfo, logger: logging.Logger) -> int:
+    """Install a package given an AppInfo object, streaming logs."""
+    if app.source_kind == SourceKind.HF_SPACE:
+        target = f"git+{app.url}" if app.url is not None else app.name
+    elif app.source_kind == SourceKind.LOCAL:
+        target = app.extra.get("path", app.name)
+    else:
+        raise ValueError(f"Cannot install app from source kind '{app.source_kind}'")
+
+    return await running_command(
+        [sys.executable, "-m", "pip", "install", target],
+        logger=logger,
+    )
+
+
+async def uninstall_package(app_name: str, logger: logging.Logger) -> int:
+    """Uninstall a package given an app name."""
+    existing_apps = await list_available_apps()
+    if app_name not in [app.name for app in existing_apps]:
+        raise ValueError(f"Cannot uninstall app '{app_name}': it is not installed")
+
+    return await running_command(
+        [sys.executable, "-m", "pip", "uninstall", "-y", app_name],
+        logger=logger,
+    )

reachy_mini/apps/templates/README.md.j2

@@ -0,0 +1 @@
+# {{ app_name }} - A ReachyMini application

reachy_mini/apps/templates/main.py.j2

@@ -0,0 +1,46 @@
+import threading
+
+from reachy_mini import ReachyMini, ReachyMiniApp
+from reachy_mini.utils import create_head_pose
+
+
+class {{ class_name }}(ReachyMiniApp):
+    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event):
+        # Write your code here
+        # ReachyMini is already initialized and connected
+        # Check the stop_event to gracefully exit the loop
+        # Example:
+        # import time
+        # import numpy as np
+        #
+        # t0 = time.time()
+        #
+        # while not stop_event.is_set():
+        #     t = time.time() - t0
+        #
+        #     yaw = 30 * np.sin(2 * np.pi * 0.5 * t)
+        #     head_pose = create_head_pose(yaw=yaw, degrees=True) 
+        #
+        #     reachy_mini.set_target(head=head_pose)
+        #
+        #     time.sleep(0.01)
+
+        print("This is a placeholder for your app logic.")
+
+
+if __name__ == "__main__":
+    # You can run the app directly from this script
+    with ReachyMini() as mini:
+        app = {{ class_name }}()
+
+        stop = threading.Event()
+
+        try:
+            print("Running '{{ app_name }}' a ReachyMiniApp...")
+            print("Press Ctrl+C to stop the app.")
+            app.run(mini, stop)
+            print("App has stopped.")
+
+        except KeyboardInterrupt:
+            print("Stopping the app...")
+            stop.set()

reachy_mini/apps/templates/pyproject.toml.j2

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "{{ app_name }}"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "reachy-mini"
+]
+keywords = ["reachy-mini-app"]
+
+[project.entry-points."reachy_mini_apps"]
+{{ app_name }} = "{{ module_name }}.main:{{ class_name }}"

reachy_mini/apps/utils.py

@@ -0,0 +1,30 @@
+"""Utility functions for Reachy Mini apps manager."""
+
+import asyncio
+import logging
+
+
+async def running_command(command: list[str], logger: logging.Logger) -> int:
+    """Run a shell command and stream its output to the provided logger."""
+    logger.info(f"Running command: {' '.join(command)}")
+
+    proc = await asyncio.create_subprocess_exec(
+        *command, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+    )
+
+    assert proc.stdout is not None  # for mypy
+    assert proc.stderr is not None  # for mypy
+
+    # Stream output line by line
+    while True:
+        line = await proc.stdout.readline()
+        if not line:
+            break
+        logger.info(line.decode().rstrip())
+
+    # Also log any remaining stderr
+    err = await proc.stderr.read()
+    if err:
+        logger.error(err.decode().rstrip())
+
+    return await proc.wait()

reachy_mini/assets/config/hardware_config.yaml

@@ -0,0 +1,119 @@
+version: beta
+
+serial:
+  baudrate: 1000000
+
+# Limits measured on the robot (in degrees)
+# s1 
+# lower : -48° : -546
+# upper : +80° : 910
+
+# s2
+# lower: +70° : 796
+# upper: -80° : -910
+
+# s3
+# lower: -48° : -546
+# upper: +80° : 910
+
+# s4
+# lower: +48° : 546
+# upper: -80° : -910
+
+# s5
+# lower: -70° : -796
+# upper: +80° : 910
+
+# s6
+# lower : +48° : 546
+# upper : -80° : -910
+
+# s1:
+#     lower: 2048 - 546 : 1502
+#     upper: 2048 + 910 : 2958
+
+# s2: 
+#     lower: 2048 - 910 : 1138
+#     upper: 2048 + 796 : 2844
+
+# s3: 
+#     lower: 2048 - 546 : 1502
+#     upper: 2048 + 910 : 2958
+
+# s4: 
+#     lower: 2048 - 910 : 1138
+#     upper: 2048 + 546 : 2594
+
+# s5:
+#     lower: 2048 - 796 : 1252
+#     upper: 2048 + 910 : 2958
+
+# s6:
+#     lower: 2048 - 910 : 1138
+#     upper: 2048 + 546 : 2594
+
+
+motors:
+  - body_yaw:
+      id: 10
+      offset: 0
+      lower_limit: 0
+      upper_limit: 4095
+      return_delay_time: 0
+      shutdown_error: 52
+  - stewart_platform_1:
+      id: 11
+      offset: 1024
+      lower_limit: 1502
+      upper_limit: 2958
+      return_delay_time: 0
+      shutdown_error: 52
+  - stewart_platform_2:
+      id: 12
+      offset: -1024
+      lower_limit: 1138
+      upper_limit: 2844
+      return_delay_time: 0
+      shutdown_error: 52
+  - stewart_platform_3:
+      id: 13
+      offset: 1024
+      lower_limit: 1502
+      upper_limit: 2958
+      return_delay_time: 0
+      shutdown_error: 52
+  - stewart_platform_4:
+      id: 14
+      offset: -1024
+      lower_limit: 1138
+      upper_limit: 2594
+      return_delay_time: 0
+      shutdown_error: 52
+  - stewart_platform_5:
+      id: 15
+      offset: 1024
+      lower_limit: 1252
+      upper_limit: 2958
+      return_delay_time: 0
+      shutdown_error: 52
+  - stewart_platform_6:
+      id: 16
+      offset: -1024
+      lower_limit: 1138
+      upper_limit: 2594
+      return_delay_time: 0
+      shutdown_error: 52
+  - right_antenna:
+      id: 17
+      offset: 0
+      lower_limit: 0
+      upper_limit: 4095
+      return_delay_time: 0
+      shutdown_error: 52
+  - left_antenna:
+      id: 18
+      offset: 0
+      lower_limit: 0
+      upper_limit: 4095
+      return_delay_time: 0
+      shutdown_error: 52