ephys-link 1.3.3__py3-none-any.whl → 2.0.0b1__py3-none-any.whl

ephys_link/__about__.py

@@ -1 +1 @@
-__version__ = "1.3.3"
+__version__ = "2.0.0b1"

ephys_link/__main__.py

@@ -1,104 +1,42 @@
-from argparse import ArgumentParser
-from asyncio import run
-from sys import argv
+"""Ephys Link entry point.
+
+Responsible for gathering launch options, instantiating the appropriate interface, and starting the application.
 
-from ephys_link import common as com
-from ephys_link.__about__ import __version__ as version
-from ephys_link.emergency_stop import EmergencyStop
-from ephys_link.gui import GUI
-from ephys_link.server import Server
+Usage: call main() to start.
+"""
+
+from sys import argv
 
-# Setup argument parser.
-parser = ArgumentParser(
-    description="Electrophysiology Manipulator Link: a websocket interface for"
-    " manipulators in electrophysiology experiments.",
-    prog="python -m ephys-link",
-)
-parser.add_argument("-b", "--background", dest="background", action="store_true", help="Skip configuration window.")
-parser.add_argument(
-    "-i", "--ignore-updates", dest="ignore_updates", action="store_true", help="Skip (ignore) checking for updates."
-)
-parser.add_argument(
-    "-t",
-    "--type",
-    type=str,
-    dest="type",
-    default="sensapex",
-    help='Manipulator type (i.e. "sensapex", "new_scale", or "new_scale_pathfinder"). Default: "sensapex".',
-)
-parser.add_argument("-d", "--debug", dest="debug", action="store_true", help="Enable debug mode.")
-parser.add_argument("-x", "--use-proxy", dest="use_proxy", action="store_true", help="Enable proxy mode.")
-parser.add_argument(
-    "-a",
-    "--proxy-address",
-    type=str,
-    default="proxy2.virtualbrainlab.org",
-    dest="proxy_address",
-    help="Proxy IP address.",
-)
-parser.add_argument(
-    "-p",
-    "--port",
-    type=int,
-    default=8081,
-    dest="port",
-    help="TCP/IP port to use. Default: 8081 (avoids conflict with other HTTP servers).",
-)
-parser.add_argument(
-    "--pathfinder_port",
-    type=int,
-    default=8080,
-    dest="pathfinder_port",
-    help="Port New Scale Pathfinder's server is on. Default: 8080.",
-)
-parser.add_argument(
-    "-s",
-    "--serial",
-    type=str,
-    default="no-e-stop",
-    dest="serial",
-    nargs="?",
-    help="Emergency stop serial port (i.e. COM3). Default: disables emergency stop.",
-)
-parser.add_argument(
-    "-v",
-    "--version",
-    action="version",
-    version=f"Electrophysiology Manipulator Link v{version}",
-    help="Print version and exit.",
-)
+from ephys_link.back_end.platform_handler import PlatformHandler
+from ephys_link.back_end.server import Server
+from ephys_link.front_end.cli import CLI
+from ephys_link.front_end.gui import GUI
+from ephys_link.util.console import Console
 
 
 def main() -> None:
-    """Main function"""
+    """Ephys Link entry point.
 
-    # Parse arguments.
-    args = parser.parse_args()
+    1. Get options via CLI or GUI.
+    2. Instantiate the Console and make it globally accessible.
+    3. Instantiate the Platform Handler with the appropriate platform bindings.
+    4. Instantiate the Emergency Stop service.
+    5. Start the server.
+    """
 
-    # Launch GUI if there are no CLI arguments.
-    if len(argv) == 1:
-        gui = GUI()
-        gui.launch()
-        return None
+    # 1. Get options via CLI or GUI (if no CLI options are provided).
+    options = CLI().parse_args() if len(argv) > 1 else GUI().get_options()
 
-    # Otherwise, create Server from CLI.
-    server = Server()
+    # 2. Instantiate the Console and make it globally accessible.
+    console = Console(enable_debug=options.debug)
 
-    # Continue with CLI if not.
-    com.DEBUG = args.debug
+    # 3. Instantiate the Platform Handler with the appropriate platform bindings.
+    platform_handler = PlatformHandler(options.type, console)
 
-    # Setup serial port.
-    if args.serial != "no-e-stop":
-        e_stop = EmergencyStop(server, args.serial)
-        e_stop.watch()
+    # 4. Instantiate the Emergency Stop service.
 
-    # Launch with parsed arguments on main thread.
-    if args.use_proxy:
-        run(
-            server.launch_for_proxy(args.proxy_address, args.port, args.type, args.pathfinder_port, args.ignore_updates)
-        )
-    else:
-        server.launch(args.type, args.port, args.pathfinder_port, args.ignore_updates)
+    # 5. Start the server.
+    Server(options, platform_handler, console).launch()
 
 
 if __name__ == "__main__":

ephys_link/back_end/platform_handler.py

@@ -0,0 +1,298 @@
+# ruff: noqa: BLE001
+"""Manipulator platform handler.
+
+Responsible for performing the various manipulator commands.
+Instantiates the appropriate bindings based on the platform type and uses them to perform the commands.
+
+Usage: Instantiate PlatformHandler with the platform type and call the desired command.
+"""
+
+from uuid import uuid4
+
+from vbl_aquarium.models.ephys_link import (
+    AngularResponse,
+    BooleanStateResponse,
+    GetManipulatorsResponse,
+    PositionalResponse,
+    SetDepthRequest,
+    SetDepthResponse,
+    SetInsideBrainRequest,
+    SetPositionRequest,
+    ShankCountResponse,
+)
+from vbl_aquarium.models.proxy import PinpointIdResponse
+from vbl_aquarium.models.unity import Vector4
+
+from ephys_link.__about__ import __version__
+from ephys_link.bindings.fake_bindings import FakeBindings
+from ephys_link.bindings.ump_4_bindings import Ump4Bindings
+from ephys_link.util.base_bindings import BaseBindings
+from ephys_link.util.common import vector4_to_array
+from ephys_link.util.console import Console
+
+
+class PlatformHandler:
+    """Handler for platform commands."""
+
+    def __init__(self, platform_type: str, console: Console) -> None:
+        """Initialize platform handler.
+
+        :param platform_type: Platform type to initialize bindings from.
+        :type platform_type: str
+        """
+
+        # Store the platform type.
+        self._platform_type = platform_type
+
+        # Store the console.
+        self._console = console
+
+        # Define bindings based on platform type.
+        self._bindings = self._match_platform_type(platform_type)
+
+        # Record which IDs are inside the brain.
+        self._inside_brain: set[str] = set()
+
+        # Generate a Pinpoint ID for proxy usage.
+        self._pinpoint_id = str(uuid4())[:8]
+
+    def _match_platform_type(self, platform_type: str) -> BaseBindings:
+        """Match the platform type to the appropriate bindings.
+
+        :param platform_type: Platform type.
+        :type platform_type: str
+        :returns: Bindings for the specified platform type.
+        :rtype: :class:`ephys_link.util.base_bindings.BaseBindings`
+        """
+        match platform_type:
+            case "ump-4":
+                return Ump4Bindings()
+            case "fake":
+                return FakeBindings()
+            case _:
+                error_message = f'Platform type "{platform_type}" not recognized.'
+                self._console.labeled_error_print("PLATFORM", error_message)
+                raise ValueError(error_message)
+
+    # Ephys Link metadata.
+
+    @staticmethod
+    def get_version() -> str:
+        """Get Ephys Link's version.
+
+        :returns: Ephys Link's version.
+        :rtype: str
+        """
+        return __version__
+
+    def get_pinpoint_id(self) -> PinpointIdResponse:
+        """Get the Pinpoint ID for proxy usage.
+
+        :returns: Pinpoint ID response.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.PinpointIDResponse`
+        """
+        return PinpointIdResponse(pinpoint_id=self._pinpoint_id, is_requester=False)
+
+    def get_platform_type(self) -> str:
+        """Get the manipulator platform type connected to Ephys Link.
+
+        :returns: Platform type config identifier (see CLI options for examples).
+        :rtype: str
+        """
+        return self._platform_type
+
+    # Manipulator commands.
+
+    async def get_manipulators(self) -> GetManipulatorsResponse:
+        """Get a list of available manipulators on the current handler.
+
+        :returns: List of manipulator IDs, number of axes, dimensions of manipulators (mm), and an error message if any.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.GetManipulatorsResponse`
+        """
+        try:
+            manipulators = await self._bindings.get_manipulators()
+            num_axes = await self._bindings.get_num_axes()
+            dimensions = self._bindings.get_dimensions()
+        except Exception as e:
+            self._console.exception_error_print("Get Manipulators", e)
+            return GetManipulatorsResponse(error=self._console.pretty_exception(e))
+        else:
+            return GetManipulatorsResponse(
+                manipulators=manipulators,
+                num_axes=num_axes,
+                dimensions=dimensions,
+            )
+
+    async def get_position(self, manipulator_id: str) -> PositionalResponse:
+        """Get the current translation position of a manipulator in unified coordinates (mm).
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :returns: Current position of the manipulator and an error message if any.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.PositionalResponse`
+        """
+        try:
+            unified_position = self._bindings.platform_space_to_unified_space(
+                await self._bindings.get_position(manipulator_id)
+            )
+        except Exception as e:
+            self._console.exception_error_print("Get Position", e)
+            return PositionalResponse(error=str(e))
+        else:
+            return PositionalResponse(position=unified_position)
+
+    async def get_angles(self, manipulator_id: str) -> AngularResponse:
+        """Get the current rotation angles of a manipulator in Yaw, Pitch, Roll (degrees).
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :returns: Current angles of the manipulator and an error message if any.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.AngularResponse`
+        """
+        try:
+            angles = await self._bindings.get_angles(manipulator_id)
+        except Exception as e:
+            self._console.exception_error_print("Get Angles", e)
+            return AngularResponse(error=self._console.pretty_exception(e))
+        else:
+            return AngularResponse(angles=angles)
+
+    async def get_shank_count(self, manipulator_id: str) -> ShankCountResponse:
+        """Get the number of shanks on a manipulator.
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :returns: Number of shanks on the manipulator and an error message if any.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.ShankCountResponse`
+        """
+        try:
+            shank_count = await self._bindings.get_shank_count(manipulator_id)
+        except Exception as e:
+            self._console.exception_error_print("Get Shank Count", e)
+            return ShankCountResponse(error=self._console.pretty_exception(e))
+        else:
+            return ShankCountResponse(shank_count=shank_count)
+
+    async def set_position(self, request: SetPositionRequest) -> PositionalResponse:
+        """Move a manipulator to a specified translation position in unified coordinates (mm).
+
+        :param request: Request to move a manipulator to a specified position.
+        :type request: :class:`vbl_aquarium.models.ephys_link.GotoPositionRequest`
+        :returns: Final position of the manipulator and an error message if any.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.Position`
+        """
+        try:
+            # Disallow setting manipulator position while inside the brain.
+            if request.manipulator_id in self._inside_brain:
+                error_message = 'Can not move manipulator while inside the brain. Set the depth ("set_depth") instead.'
+                self._console.error_print(error_message)
+                return PositionalResponse(error=error_message)
+
+            # Move to the new position.
+            final_platform_position = await self._bindings.set_position(
+                manipulator_id=request.manipulator_id,
+                position=self._bindings.unified_space_to_platform_space(request.position),
+                speed=request.speed,
+            )
+            final_unified_position = self._bindings.platform_space_to_unified_space(final_platform_position)
+
+            # Return error if movement did not reach target within tolerance.
+            for index, axis in enumerate(vector4_to_array(final_unified_position - request.position)):
+                # End once index is greater than the number of axes.
+                if index >= await self._bindings.get_num_axes():
+                    break
+
+                # Check if the axis is within the movement tolerance.
+                if abs(axis) > await self._bindings.get_movement_tolerance():
+                    error_message = (
+                        f"Manipulator {request.manipulator_id} did not reach target"
+                        f" position on axis {list(Vector4.model_fields.keys())[index]}."
+                        f"Requested: {request.position}, got: {final_unified_position}."
+                    )
+                    self._console.error_print(error_message)
+                    return PositionalResponse(error=error_message)
+        except Exception as e:
+            self._console.exception_error_print("Set Position", e)
+            return PositionalResponse(error=self._console.pretty_exception(e))
+        else:
+            return PositionalResponse(position=final_unified_position)
+
+    async def set_depth(self, request: SetDepthRequest) -> SetDepthResponse:
+        """Move a manipulator's depth translation stage to a specific value (mm).
+
+        :param request: Request to move a manipulator to a specified depth.
+        :type request: :class:`vbl_aquarium.models.ephys_link.DriveToDepthRequest`
+        :returns: Final depth of the manipulator and an error message if any.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.DriveToDepthResponse`
+        """
+        try:
+            # Create a position based on the new depth.
+            current_platform_position = await self._bindings.get_position(request.manipulator_id)
+            current_unified_position = self._bindings.platform_space_to_unified_space(current_platform_position)
+            target_unified_position = current_unified_position.model_copy(update={"w": request.depth})
+            target_platform_position = self._bindings.unified_space_to_platform_space(target_unified_position)
+
+            # Move to the new depth.
+            final_platform_position = await self._bindings.set_position(
+                manipulator_id=request.manipulator_id,
+                position=target_platform_position,
+                speed=request.speed,
+            )
+            final_unified_position = self._bindings.platform_space_to_unified_space(final_platform_position)
+        except Exception as e:
+            self._console.exception_error_print("Set Depth", e)
+            return SetDepthResponse(error=self._console.pretty_exception(e))
+        else:
+            return SetDepthResponse(depth=final_unified_position.w)
+
+    async def set_inside_brain(self, request: SetInsideBrainRequest) -> BooleanStateResponse:
+        """Mark a manipulator as inside the brain or not.
+
+        This should restrict the manipulator's movement to just the depth axis.
+
+        :param request: Request to set a manipulator's inside brain state.
+        :type request: :class:`vbl_aquarium.models.ephys_link.InsideBrainRequest`
+        :returns: Inside brain state of the manipulator and an error message if any.
+        :rtype: :class:`vbl_aquarium.models.ephys_link.BooleanStateResponse`
+        """
+        try:
+            if request.inside:
+                self._inside_brain.add(request.manipulator_id)
+            else:
+                self._inside_brain.discard(request.manipulator_id)
+        except Exception as e:
+            self._console.exception_error_print("Set Inside Brain", e)
+            return BooleanStateResponse(error=self._console.pretty_exception(e))
+        else:
+            return BooleanStateResponse(state=request.inside)
+
+    async def stop(self, manipulator_id: str) -> str:
+        """Stop a manipulator.
+
+        :param manipulator_id: Manipulator ID.
+        :type manipulator_id: str
+        :returns: Error message if any.
+        :rtype: str
+        """
+        try:
+            await self._bindings.stop(manipulator_id)
+        except Exception as e:
+            self._console.exception_error_print("Stop", e)
+            return self._console.pretty_exception(e)
+        else:
+            return ""
+
+    async def stop_all(self) -> str:
+        """Stop all manipulators.
+
+        :returns: Error message if any.
+        :rtype: str
+        """
+        try:
+            for manipulator_id in await self._bindings.get_manipulators():
+                await self._bindings.stop(manipulator_id)
+        except Exception as e:
+            self._console.exception_error_print("Stop", e)
+            return self._console.pretty_exception(e)
+        else:
+            return ""

ephys_link/back_end/server.py

@@ -0,0 +1,200 @@
+from asyncio import get_event_loop, run
+from collections.abc import Callable, Coroutine
+from json import JSONDecodeError, dumps, loads
+from typing import Any
+
+from aiohttp.web import Application, run_app
+from pydantic import ValidationError
+from socketio import AsyncClient, AsyncServer
+from vbl_aquarium.models.ephys_link import (
+    EphysLinkOptions,
+    SetDepthRequest,
+    SetInsideBrainRequest,
+    SetPositionRequest,
+)
+from vbl_aquarium.models.generic import VBLBaseModel
+
+from ephys_link.back_end.platform_handler import PlatformHandler
+from ephys_link.util.common import PORT, check_for_updates, server_preamble
+from ephys_link.util.console import Console
+
+
+class Server:
+    def __init__(self, options: EphysLinkOptions, platform_handler: PlatformHandler, console: Console) -> None:
+        """Initialize server fields based on options and platform handler."""
+
+        # Save fields.
+        self._options = options
+        self._platform_handler = platform_handler
+        self._console = console
+
+        # Initialize based on proxy usage.
+        self._sio: AsyncServer | AsyncClient = AsyncClient() if self._options.use_proxy else AsyncServer()
+        if not self._options.use_proxy:
+            self._app = Application()
+            self._sio.attach(self._app)
+
+            # Bind connection events.
+            self._sio.on("connect", self.connect)
+            self._sio.on("disconnect", self.disconnect)
+
+        # Store connected client.
+        self._client_sid: str = ""
+
+        # Bind events.
+        self._sio.on("*", self.platform_event_handler)
+
+    # Server launch.
+    def launch(self) -> None:
+        # Preamble.
+        server_preamble()
+
+        # Check for updates.
+        check_for_updates()
+
+        # List platform and available manipulators.
+        self._console.info_print("PLATFORM", self._platform_handler.get_platform_type())
+        self._console.info_print(
+            "MANIPULATORS",
+            str(get_event_loop().run_until_complete(self._platform_handler.get_manipulators()).manipulators),
+        )
+
+        # Launch server
+        if self._options.use_proxy:
+            self._console.info_print("PINPOINT ID", self._platform_handler.get_pinpoint_id().pinpoint_id)
+
+            async def connect_proxy() -> None:
+                # noinspection HttpUrlsUsage
+                await self._sio.connect(f"http://{self._options.proxy_address}:{PORT}")
+                await self._sio.wait()
+
+            run(connect_proxy())
+        else:
+            run_app(self._app, port=PORT)
+
+    # Helper functions.
+    def _malformed_request_response(self, request: str, data: tuple[tuple[Any], ...]) -> str:
+        """Return a response for a malformed request."""
+        self._console.labeled_error_print("MALFORMED REQUEST", f"{request}: {data}")
+        return dumps({"error": "Malformed request."})
+
+    async def _run_if_data_available(
+        self, function: Callable[[str], Coroutine[Any, Any, VBLBaseModel]], event: str, data: tuple[tuple[Any], ...]
+    ) -> str:
+        """Run a function if data is available."""
+        request_data = data[1]
+        if request_data:
+            return str((await function(str(request_data))).to_json_string())
+        return self._malformed_request_response(event, request_data)
+
+    async def _run_if_data_parses(
+        self,
+        function: Callable[[VBLBaseModel], Coroutine[Any, Any, VBLBaseModel]],
+        data_type: type[VBLBaseModel],
+        event: str,
+        data: tuple[tuple[Any], ...],
+    ) -> str:
+        """Run a function if data parses."""
+        request_data = data[1]
+        if request_data:
+            try:
+                parsed_data = data_type(**loads(str(request_data)))
+            except JSONDecodeError:
+                return self._malformed_request_response(event, request_data)
+            except ValidationError as e:
+                self._console.exception_error_print(event, e)
+                return self._malformed_request_response(event, request_data)
+            else:
+                return str((await function(parsed_data)).to_json_string())
+        return self._malformed_request_response(event, request_data)
+
+    # Event Handlers.
+
+    async def connect(self, sid: str, _: str) -> bool:
+        """Handle connections to the server
+
+        :param sid: Socket session ID.
+        :type sid: str
+        :param _: Extra connection data (unused).
+        :type _: str
+        :returns: False on error to refuse connection, True otherwise.
+        :rtype: bool
+        """
+        self._console.info_print("CONNECTION REQUEST", sid)
+
+        if self._client_sid == "":
+            self._client_sid = sid
+            self._console.info_print("CONNECTION GRANTED", sid)
+            return True
+
+        self._console.error_print(f"CONNECTION REFUSED to {sid}. Client {self._client_sid} already connected.")
+        return False
+
+    async def disconnect(self, sid: str) -> None:
+        """Handle disconnections from the server
+
+        :param sid: Socket session ID.
+        :type sid: str
+        """
+        self._console.info_print("DISCONNECTED", sid)
+
+        # Reset client SID if it matches.
+        if self._client_sid == sid:
+            self._client_sid = ""
+        else:
+            self._console.error_print(f"Client {sid} disconnected without being connected.")
+
+    # noinspection PyTypeChecker
+    async def platform_event_handler(self, event: str, *args: tuple[Any]) -> str:
+        """Handle events from the server
+
+        :param event: Event name.
+        :type event: str
+        :param args: Event arguments.
+        :type args: tuple[Any]
+        :returns: Response data.
+        :rtype: str
+        """
+
+        # Log event.
+        self._console.debug_print("EVENT", event)
+
+        # Handle event.
+        match event:
+            # Server metadata.
+            case "get_version":
+                return self._platform_handler.get_version()
+            case "get_pinpoint_id":
+                return str(self._platform_handler.get_pinpoint_id().to_json_string())
+            case "get_platform_type":
+                return self._platform_handler.get_platform_type()
+
+            # Manipulator commands.
+            case "get_manipulators":
+                return str((await self._platform_handler.get_manipulators()).to_json_string())
+            case "get_position":
+                return await self._run_if_data_available(self._platform_handler.get_position, event, args)
+            case "get_angles":
+                return await self._run_if_data_available(self._platform_handler.get_angles, event, args)
+            case "get_shank_count":
+                return await self._run_if_data_available(self._platform_handler.get_shank_count, event, args)
+            case "set_position":
+                return await self._run_if_data_parses(
+                    self._platform_handler.set_position, SetPositionRequest, event, args
+                )
+            case "set_depth":
+                return await self._run_if_data_parses(self._platform_handler.set_depth, SetDepthRequest, event, args)
+            case "set_inside_brain":
+                return await self._run_if_data_parses(
+                    self._platform_handler.set_inside_brain, SetInsideBrainRequest, event, args
+                )
+            case "stop":
+                request_data = args[1]
+                if request_data:
+                    return await self._platform_handler.stop(str(request_data))
+                return self._malformed_request_response(event, request_data)
+            case "stop_all":
+                return await self._platform_handler.stop_all()
+            case _:
+                self._console.error_print(f"Unknown event: {event}.")
+                return dumps({"error": "Unknown event."})