sanworks · ogeesan · Jul 12, 2025 · Jul 12, 2025 · Jul 12, 2025
diff --git a/docs/function-reference/liquid-calibration.md b/docs/function-reference/liquid-calibration.md
@@ -28,3 +28,32 @@ ValveTimes = GetValveTimes(20, [1 3]);
 LeftValveTime = ValveTimes(1); 
 RightValveTime = ValveTimes(2);
 ```
+
+### `BpodLiquidCalibration()`
+**Description**
+
+Command Window function to allow users to interact with the liquid calibration.
+Allows users to initialise calibration of the [Port Array Module](../serial-interfaces/port-array-module-serial-interface.md).
+
+**Syntax**
+```matlab
+BpodLiquidCalibration(operation, _)
+```
+
+**Parameters**
+
+- operation: what action to perform
+    - 'calibrate': launch a calibrator, optionally specify 'portarray' after 'calibrate' to launch port array calibrator.
+    - 'getvalvetimes': equivalent to [`GetValveTimes()`](#getvalvetimes)
+
+**Returns**
+
+ValveTimes_s if operation was 'getvalvetimes'.
+
+**Examples**
+
+```matlab
+% Initialise calibration of liquid calibration user interface
+% for Port Array Module
+BpodLiquidCalibration calibrate portarray
+```
diff --git a/docs/serial-interfaces/port-array-module-serial-interface.md b/docs/serial-interfaces/port-array-module-serial-interface.md
@@ -21,7 +21,7 @@ The state machine command interface consists of bytes sent from the Bpod state m
         - state (1 byte; range = 0-1) Note: 0 = closed, 1 = open
 - '**B**' (ASCII 66): **Set the state of all valves at once, using bits of a byte**
     - Following 'B', the module expects 1 byte:
-        - valveState (1 byte; range = 0-15) Note: 0 = all cosed, 15 = all open
+        - valveState (1 byte; range = 0-15) Note: 0 = all closed, 15 = all open
 - '**P**' (ASCII 80): **Set port LED intensity (pulse width modulated)**.
     - Following 'P', the module expects 2 bytes:
         - port# (1 byte; range = 0-3)

diff --git a/docs/user-guide/bpod-gui.md b/docs/user-guide/bpod-gui.md
@@ -116,7 +116,10 @@ If the Bpod software can not connect to a Bpod device, it can be run in Emulator
 - Currently, only the state machine's onboard channels are supported. If your protocol depends on Bpod modules or other external hardware, you will have to run your protocol with the hardware present.
 
 ## Liquid calibration
-Solenoid valves connected to each behavior port (we recommend [these](http://www.google.com/url?q=http%3A%2F%2Fwww.theleeco.com%2Felectro-fluidic-systems%2Fsolenoid-valves%2Flhd%2Fsoft-tube-ported-style.cfm&sa=D&sntz=1&usg=AOvVaw1w0EV-e7R4MRGhzhhuY39h) for their fast action) can gate the gravity flow of liquid reward from an elevated reservoir to the test subject below. When writing your protocol, you might want to deliver a 5µl of liquid reward to a mouse - but how long should you open the valve to achieve this? The `GetValveTimes()` function will solve this for you, by reading from a calibration curve you create. Here's how to create and manage calibration curves:
+Solenoid valves connected to each behavior port (we recommend [these](http://www.google.com/url?q=http%3A%2F%2Fwww.theleeco.com%2Felectro-fluidic-systems%2Fsolenoid-valves%2Flhd%2Fsoft-tube-ported-style.cfm&sa=D&sntz=1&usg=AOvVaw1w0EV-e7R4MRGhzhhuY39h) for their fast action) can gate the gravity flow of liquid reward from an elevated reservoir to the test subject below.
+When writing your protocol, you might want to deliver a 5µl of liquid reward to a mouse - but how long should you open the valve to achieve this?
+The `GetValveTimes()` function will solve this for you, by reading from a calibration curve you create.
+Here's how to create and manage calibration curves:
 
 <!-- ### Step 1. Launch the calibration manager -->
 <!-- Original wiki has no step 2 heading -->
@@ -125,6 +128,9 @@ Solenoid valves connected to each behavior port (we recommend [these](http://www
 
 <img src="../../images/console-settings-menu.png" alt="drawing" width="300"/><br><br>
 
+!!! note
+    You can also use [`BpodLiquidCalibration()`](../function-reference/liquid-calibration.md#bpodliquidcalibration) to start liquid calibration, including for the [Port Array Module](../serial-interfaces/port-array-module-serial-interface.md).
+
 - Next, click "Liquid reward calibration" (the faucet icon on the far left)
 - You should now see the calibration manager:
 
@@ -147,15 +153,39 @@ Solenoid valves connected to each behavior port (we recommend [these](http://www
 
 ## Bpod files
 
-
-```
-Bpod Local/ # Contains user-specific files like protcols, calibrations, saved data
-    Calibration files/
-    Data/
-    Protocols/
-    Settings/    # Bpod saves
-Bpod_Gen2/    # Contains files required for Bpod to run
-```
+=== "Standard configuration layout"
+
+    ```
+    Bpod_Gen2/
+    Bpod Local/
+    ├─ Data/
+    ├─ Protocols/
+    ├─ Config/
+    │  ├─ LiquidCalibration.json
+    │  ├─ SoundCalibration.mat
+    │  ├─ BpodSettings.mat
+    │  ├─ InputConfig.mat
+    │  ├─ ModuleUSBConfig.mat
+    │  ├─ SyncConfig.mat
+    ```
+
+=== "Legacy configuration layout"
+
+    Default layout in <=1.8.1
+    ```
+    Bpod_Gen2/
+    Bpod Local/
+    ├─ Data/
+    ├─ Protocols/
+    ├─ Calibration Files/
+    │  ├─ LiquidCalibration.json
+    │  ├─ SoundCalibration.mat
+    ├─ Settings/
+    │  ├─ BpodSettings.mat
+    │  ├─ InputConfig.mat
+    │  ├─ ModuleUSBConfig.mat
+    │  ├─ SyncConfig.mat
+    ```
 
 !!! note
     The default location for the 'Bpod Local' folder is in same folder where 'Bpod_Gen2' is located.
diff --git a/docs/user-guide/multi-setup.md b/docs/user-guide/multi-setup.md
@@ -0,0 +1,104 @@
+# Multiple Bpods on one computer
+!!! warning "Experimental feature"
+
+    This feature is in development. Features and functions may change in the future.
+
+Multiple state machines can be run a single computer simultaneously by using multiple MATLAB instances, allowing users to run multiple Bpod sessions simultaneously.
+
+## Enabling multi-setup
+Once `Bpod` has been run you must run these two commands (only when initially enabling up multi-setup support):
+
+1. `#!matlab BpodSetup updatesettings`
+    - Updates legacy (<=1.8.1) Bpod Local structure to Config/ structure.
+    - Updates liquid calibration file to new format.
+2. `#!matlab BpodSetup multisetup`
+    - Places all files in Config/ into COM-specific folder
+
+This will modify your configuration data, making each state machine have its own unique configuration data (calibration files, input and sync configuration etc.) while sharing protocols and session data access.
+
+=== "Legacy configuration layout"
+
+    Default layout in <=1.8.1
+    ```
+    Bpod Local/
+    ├─ Data/
+    ├─ Protocols/
+    ├─ Calibration Files/
+    │  ├─ LiquidCalibration.json    
+    │  ├─ SoundCalibration.mat
+    ├─ Settings/
+    │  ├─ BpodSettings.mat
+    │  ├─ InputConfig.mat
+    │  ├─ ModuleUSBConfig.mat
+    │  ├─ SyncConfig.mat
+    ```
+
+=== "Standard configuration layout"
+
+    Standard layout following fresh installation or created from legacy structure with `#!matlab BpodSetup updatesettings`
+    ```
+    Bpod Local/
+    ├─ Data/
+    ├─ Protocols/
+    ├─ Config/
+    │  ├─ LiquidCalibration.json
+    │  ├─ SoundCalibration.mat
+    │  ├─ BpodSettings.mat
+    │  ├─ InputConfig.mat
+    │  ├─ ModuleUSBConfig.mat
+    │  ├─ SyncConfig.mat
+    ```
+
+=== "Multi-setup configuration layout"
+
+    Layout following `#!matlab BpodSetup multisetup`
+    ```
+    Bpod Local/
+    ├─ Data/
+    ├─ Protocols/
+    ├─ Config/
+    │  ├─ Machine-COM5
+    │  │  ├─ LiquidCalibration.json
+    │  │  ├─ SoundCalibration.mat
+    │  │  ├─ BpodSettings.mat
+    │  │  ├─ InputConfig.mat
+    │  │  ├─ ModuleUSBConfig.mat
+    │  │  ├─ SyncConfig.mat
+    │  ├─ Machine-COM13/
+    │  │  ├─ [same structure as Machine-COM5/]
+    ```
+
+## Using multiple setups
+Once enabled, users can run two or more instances of MATLAB to control two or more state machines in parallel.
+Calling `Bpod` in one instance of MATLAB and connecting to one state machine, and then calling `Bpod` in a separate instance of MATLAB to connect to a different state machine will result in two Bpod Consoles.
+Users are encouraged to keep the consoles in separate parts of the screen to minimise confusion as to which console belongs to which state machine.
+
+- The Bpod Local folder is shared between all Bpod installations, which means that:
+    - The Protocols folder is by default shared between setups
+    - The Data folder is by default shared between setups
+- Each state machine will access its own subfolder within Config/, which means that:
+    - Settings are specific to machine
+        - Protocols and Data folder can be specified per-machine if required
+    - Calibration files are specific to machine
+
+## Limitations and considerations
+A key consideration for whether your setup is suited for multi-setup support is if your behaviour requires the CPU, GPU, or other processing systems of the computer.
+For example, if your behaviour uses Psychtoolbox to generate stimuli then multiple sessions running in parallel may experience some lag.
+However, if the stimuli are generated using external hardware (such as sound through the Bpod HiFi Module) then the increased CPU load will not affect the task because the external hardware is unaffected.
+
+## Suggested knowledge of state machine connectivity
+Multi-machine support is enabled by makings settings specific to the COM port of the state machine.
+A COM (communication) port is a communication protocol which can use USB plugs.
+The state machine and the modules use COM ports to communicate with the computer via their USB connections.
+The computer gives each COM device a unique number, meaning a State Machine that receives the number 3 when it is first plugged in will be recognised as "COM3" regardless of where it is plugged into the computer later on.
+Each additional State Machine then receives its own COM port identifier, allowing the configuration for each to be kept separate.
+
+!!! danger "COM ports are not 100% stable"
+    Occasionally the COM number for devices may change, which seems to be a Windows problem or may be related to low-quality USB dongles.
+    If this occurs then the Bpod software will be unable to determine which configuration data belongs to which State Machine. Users will have to use one of the following options:
+
+    1. Rename the folders within `Bpod Local/Config/` that refer to state machine COMs.
+    2. [Manually change the COM number](https://support.arduino.cc/hc/en-us/articles/360016420140-COM-port-number-changes-when-connecting-board-on-different-ports-or-in-bootloader-mode) to match the previous number.
+
+    Users have reported COMs changing on Windows computers once or twice a year.
+    This means that if users choose to use multi-setups then there may be one or two days a year when, at startup, Bpod reports that a fresh multi-setup was created.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -49,6 +49,7 @@ nav:
     - Operation:
       - user-guide/state-machine-concept.md
       - user-guide/bpod-gui.md
+      - user-guide/multi-setup.md
     - Programming:
       - user-guide/protocol-development.md
       - Function Reference: # IMPORTANT NOTE: New functions are not automatically added to the function-reference/index.md page!
@@ -148,12 +149,15 @@ markdown_extensions:
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
+  - pymdownx.details
   - pymdownx.snippets
   - pymdownx.superfences:
       custom_fences:
             - name: mermaid
               class: mermaid
               format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg