# Ephys Link
[](https://badge.fury.io/py/ephys-link)
[](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/codeql-analysis.yml)
[](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/dependency-review.yml)
[](https://github.com/pypa/hatch)
[](https://github.com/astral-sh/ruff)
The [Electrophysiology Manipulator Link](https://github.com/VirtualBrainLab/ephys-link)
(or Ephys Link for short) is a
Python [Socket.IO](https://socket.io/docs/v4/#what-socketio-is) server that
allows any
Socket.IO-compliant application (such
as [Pinpoint](https://github.com/VirtualBrainLab/Pinpoint))
to communicate with manipulators used in electrophysiology experiments.
**Supported Manipulators:**
| Manufacturer | Model |
|--------------|-------------------------------------------------------------------------|
| Sensapex | |
| New Scale | - Pathfinder MPM Control v2.8+
- M3-USB-3:1-EP
|
Ephys Link is an open and extensible platform. It is designed to easily support
integration with other manipulators.
For more information regarding the server's implementation and how the code is
organized, see
the [package's development documentation](https://virtualbrainlab.org/ephys_link/development.html).
For detailed descriptions of the server's API, see
the [API reference](https://virtualbrainlab.org/api_reference_ephys_link.html).
## Installation
### Prerequisites
1. An **x86 Windows PC is required** to run the server.
2. For Sensapex devices, the controller unit must be connected via an ethernet
cable and powered. A USB-to-ethernet adapter is acceptable. For New Scale
manipulators, the controller unit must be connected via USB and be powered by
a 6V power supply.
3. To use the emergency stop feature, ensure an Arduino with
the [StopSignal](https://github.com/VirtualBrainLab/StopSignal) sketch is
connected to the computer. Follow the instructions on that repo for how to
set up the Arduino.
**NOTE:** Ephys Link is an HTTP server without cross-origin support. The server
is currently designed to interface with local/desktop instances of Pinpoint. It
will not work with the web browser versions of Pinpoint at this time.
### Launch from Pinpoint (Recommended)
Pinpoint comes bundled with the correct version of Ephys Link. If you are using
Pinpoint on the same computer your manipulators are connected to, you can launch
the server from within Pinpoint. Follow the instructions in
the [Pinpoint documentation](https://virtualbrainlab.org/pinpoint/tutorials/tutorial_ephys_link.html#configure-and-launch-ephys-link).
### Install as Standalone Executable
1. Download the latest executable from
the [releases page](https://github.com/VirtualBrainLab/ephys-link/releases/latest).
2. Double-click the executable file to launch the configuration window.
1. Take note of the IP address and port. **Copy this information into
Pinpoint to connect**.
3. Select the desired configuration and click "Launch Server".
The configuration window will close and the server will launch. Your
configurations will be saved for future use.
To connect to the server from Pinpoint, provide the IP address and port. For
example, if the server is running on the
same computer that Pinpoint is, use
- Server: `localhost`
- Port: `8081`
If the server is running on a different (local) computer, use the IP address of
that computer as shown in the startup
window instead of `localhost`.
### Install as a Python package
```bash
pip install ephys-link
```
Import the modules you need and launch the server.
```python
from ephys_link.server import Server
server = Server()
server.launch("sensapex", 8081)
```
### Install for Development
1. Clone the repository.
2. Install [Hatch](https://hatch.pypa.io/latest/install/)
3. Install the latest Microsoft Visual C++ (MSVC v143+ x86/64) and the Windows
SDK (10/11)
via [Visual Studio Build Tools Installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
4. In a terminal, navigate to the repository's root directory and run
```bash
hatch shell
```
This will create a virtual environment, install Python 12 (if not found), and
install the package in editable mode.
## CLI Usage
Ephys Link can be launched from the command line directly without the
configuration window. This is useful for computers
or servers without graphical user interfaces.
With the standalone executable downloaded, invoking the executable from the
command line:
```bash
EphysLink-vX.X.X.exe -b
```
Use the actual name of the executable you downloaded. The `-b` or `--background`
flag will launch the server without the
configuration window and read configuration from CLI arguments.
Run the following commands in a terminal to start the server for the desired
manipulator platform without the startup
window (replace `EphysLink.exe` with the actual name of the executable you
downloaded):
| Manipulator Platform | Command |
|------------------------------------------|--------------------------------------------|
| Sensapex uMp-4 | `EphysLink.exe -b` |
| Sensapex uMp-3 | `EphysLink.exe -b -t ump3` |
| New Scale Pathfinder MPM Control v2.8.8+ | `EphysLink.exe -b -t new_scale_pathfinder` |
| New Scale M3-USB-3:1-EP | `EphysLink.exe -b -t new_scale` |
More options can be viewed by running `EphysLink.exe -h`.
### "New Scale Pathfinder MPM Control" vs "New Scale M3-USB-3:1-EP"
New Scale manipulators have two methods of connection. The first method is
through the Pathfinder MPM Control software (`-t new_scale_pathfinder`) and the
second is via a direct hardware
connection (`-t new_scale`). The first method is only available if Pathfinder is
running on the same computer
as Ephys Link. New Scale manipulators should be connected to the Pathfinder
software first and the Pathfinder HTTP server should be running.