Jackhammer mode docs (#483)

* Jackhammer test script

* Multi iteration

* Added comments

* Upgraded dependencies and started jackhammer mode documentation.

* Added jackhammer mode docs.

Author: kjy5

.idea/copilot.data.migration.agent.xml

@@ -5,17 +5,18 @@ on [GitHub](https://github.com/VirtualBrainLab/ephys-link), and we welcome contr
 
 This section describes:
 
-- [The Socket.IO server's API](socketio_api.md) and how to communicate with Ephys Link from a client application
-- How to [add a new manipulator](adding_a_manipulator.md) to Ephys Link
-- General [code organization](code_organization.md) for Ephys Link
-- Auto-generated [source code reference](../reference/SUMMARY.md) intended for developers who are maintaining Ephys Link
+- [The Socket.IO server's API](socketio_api.md) and how to communicate with Ephys Link from a client application.
+- How to [add a new manipulator](adding_a_manipulator.md) to Ephys Link.
+- General [code organization](code_organization.md) for Ephys Link.
+- Auto-generated [source code reference](../reference/SUMMARY.md) intended for developers who are maintaining Ephys Link.
+- Testing [Jackhammer Mode](jackhammer_mode.md).
 
 ## Installing for Development
 
 1. Clone the repository.
-2. Install [UV](https://docs.astral.sh/uv/#installation)
-3. Install [Hatch](https://hatch.pypa.io/latest/install/)
-4. In a terminal, navigate to the repository's root directory and run
+2. Install [UV](https://docs.astral.sh/uv/#installation).
+3. Install [Hatch](https://hatch.pypa.io/latest/install/).
+4. In a terminal, navigate to the repository's root directory and run.
 
    ```bash
    hatch shell

.idea/copilot.data.migration.edit.xml

@@ -0,0 +1,32 @@
+# Jackhammer Mode
+
+This is an internal feature for rapidly oscillating the manipulator along an axis.
+
+Jackhammer mode is not exposed in Ephys Link yet so this guide is to demonstrate how to test it in Python.
+
+## 1. Get Ephys Link
+
+Follow the instructions for [Installing for Development](index.md#installing-for-development). Or, just use a basic Python virtual environment (Python 3.13+ is required):
+
+```powershell
+python -m venv venv
+.\venv\Scripts\Activate.ps1
+pip install .
+```
+
+## 2. Change the Sensapex SDK to support Jackhammer Mode
+
+You need to replace the `libum.dll` file in the Sensapex library folder. This is located at `<virtual env>\Lib\site-packages\sensapex`. If you made a virtual environment named `venv` in the previous step, it would be `.\venv\Lib\site-packages\sensapex`.
+
+1. Download the custom SDK [here](../assets/libum.dll).
+2. (Optional) Make a backup of the old `libum.dll` in the Sensapex library folder by renaming it to `libum.dll.bck` or something like that.
+3. Copy the downloaded `libum.dll` to the Sensapex library folder.
+4. Modify `sensapex.py` in the Sensapex library folder to enable using this custom DLL. Set the `max_version` variable at line `398` to `(1, 510)`.
+
+You can (optionally) test if everything is still working by [running Ephys Link](../usage/starting_ephys_link.md) and checking to see if it can still see and control Sensapex manipulators.
+
+## 3. Use the test script
+
+There's a test script in `scripts/jackhammer.py` that makes a call to Jackhammer mode.
+
+In short, jackhammer mode enables open-loop control of the manipulators by letting you turn on and off the motors in a sequence. You can define a "first" and "second" stage to cycle between. When the "thrust length" argument is positive, the manipulator will move in the forward direction and when it is negative it will move backwards. Thrust length is not a real unit but is some percentage representing the amount of movement a step should take.

docs/assets/libum.dll

@@ -59,12 +59,12 @@ exclude = ["/.github", "/.idea", "/docs"]
 installer = "uv"
 python = "3.13"
 dependencies = [
-    "pyinstaller==6.14.2",
-    "basedpyright==1.29.5",
-    "pytest==8.4.1",
-    "pytest-cov==6.2.1",
-    "pytest-mock==3.14.1",
-    "pytest-asyncio==1.0.0"
+    "pyinstaller==6.15.0",
+    "basedpyright==1.31.4",
+    "pytest==8.4.2",
+    "pytest-cov==6.3.0",
+    "pytest-mock==3.15.0",
+    "pytest-asyncio==1.1.0"
 ]
 [tool.hatch.envs.default.scripts]
 exe = "pyinstaller.exe ephys_link.spec -y -- -d && pyinstaller.exe ephys_link.spec -y"
@@ -79,8 +79,8 @@ installer = "uv"
 python = "3.13"
 skip-install = true
 dependencies = [
-    "mkdocs-material==9.6.11",
-    "mkdocstrings-python==1.16.10",
+    "mkdocs-material==9.6.19",
+    "mkdocstrings-python==1.18.2",
     "mkdocs-gen-files==0.5.0",
     "mkdocs-literate-nav==0.6.2",
     "mkdocs-section-index==0.3.10"

docs/development/index.md

@@ -0,0 +1,29 @@
+from ctypes import c_char, c_int
+
+from sensapex import UMP
+
+# Edit these parameters:
+DEVICE_ID = 3  # Manipulator ID.
+AXIS = 3  # Axis (0=X, 1=Y, 2=Z, 3=D).
+
+NUMBER_OF_CYCLES = 20  # Number of time the first and second stage are repeated.
+
+NUMBER_OF_STEP_IN_FIRST_STAGE = 10
+FIRST_STAGE_THRUST_LENGTH = 15  # +/- 0 - 100
+
+NUMBER_OF_STEP_IN_SECOND_STAGE = 5
+SECOND_STAGE_THRUST_LENGTH = -15  # +/- 0 - 100
+
+# Do not edit below this line.
+um = UMP.get_ump()
+
+um.call(
+    "um_take_jackhammer_step",
+    c_int(DEVICE_ID),
+    c_char(AXIS),
+    c_int(NUMBER_OF_CYCLES),
+    c_int(NUMBER_OF_STEP_IN_FIRST_STAGE),
+    c_int(FIRST_STAGE_THRUST_LENGTH),
+    c_int(NUMBER_OF_STEP_IN_SECOND_STAGE),
+    c_int(SECOND_STAGE_THRUST_LENGTH),
+)