Distinguish between aggregate & device properties

.bonsai/Bonsai.config

@@ -24,6 +24,7 @@
     <Package id="Microsoft.Web.WebView2" version="1.0.1823.32" />
     <Package id="openal.redist" version="2.0.7" />
     <Package id="OpenCV.Net" version="3.4.2" />
+    <Package id="OpenEphys.Sockets.Bonsai" version="1.0.3" />
     <Package id="OpenTK" version="3.1.0" />
     <Package id="OpenTK.GLControl" version="3.1.0" />
     <Package id="Rx-Core" version="2.2.5" />
@@ -57,6 +58,7 @@
     <AssemblyReference assemblyName="Bonsai.Vision" />
     <AssemblyReference assemblyName="Bonsai.Vision.Design" />
     <AssemblyReference assemblyName="Bonsai.Windows.Input" />
+    <AssemblyReference assemblyName="OpenEphys.Sockets.Bonsai" />
   </AssemblyReferences>
   <AssemblyLocations>
     <AssemblyLocation assemblyName="Bonsai" processorArchitecture="MSIL" location="Packages/Bonsai.2.8.5/lib/net48/Bonsai.exe" />
@@ -81,6 +83,7 @@
     <AssemblyLocation assemblyName="Microsoft.Web.WebView2.WinForms" processorArchitecture="MSIL" location="Packages/Microsoft.Web.WebView2.1.0.1823.32/lib/net45/Microsoft.Web.WebView2.WinForms.dll" />
     <AssemblyLocation assemblyName="Microsoft.Web.WebView2.Wpf" processorArchitecture="MSIL" location="Packages/Microsoft.Web.WebView2.1.0.1823.32/lib/net45/Microsoft.Web.WebView2.Wpf.dll" />
     <AssemblyLocation assemblyName="OpenCV.Net" processorArchitecture="MSIL" location="Packages/OpenCV.Net.3.4.2/lib/net462/OpenCV.Net.dll" />
+    <AssemblyLocation assemblyName="OpenEphys.Sockets.Bonsai" processorArchitecture="MSIL" location="Packages/OpenEphys.Sockets.Bonsai.1.0.3/lib/net472/OpenEphys.Sockets.Bonsai.dll" />
     <AssemblyLocation assemblyName="OpenTK" processorArchitecture="MSIL" location="Packages/OpenTK.3.1.0/lib/net20/OpenTK.dll" />
     <AssemblyLocation assemblyName="OpenTK.GLControl" processorArchitecture="MSIL" location="Packages/OpenTK.GLControl.3.1.0/lib/net20/OpenTK.GLControl.dll" />
     <AssemblyLocation assemblyName="ScintillaNET" processorArchitecture="MSIL" location="Packages/jacobslusser.ScintillaNET.3.6.3/lib/net40/ScintillaNET.dll" />

.gitmodules

@@ -1,6 +1,6 @@
 [submodule "docfx-tools"]
 	path = docfx-tools
 	url = https://github.com/bonsai-rx/docfx-tools
-[submodule "src/onix-bonsai-onix1"]
-	path = src/onix-bonsai-onix1
-	url = https://github.com/open-ephys/onix-bonsai-onix1.git
+[submodule "src/bonsai-onix1"]
+	path = src/bonsai-onix1
+	url = https://github.com/open-ephys/bonsai-onix1.git

README.md

@@ -3,7 +3,7 @@
 
 # Onix1 Bonsai Docs
 
-Documentation for the [Onix1 Bonsai package](https://github.com/open-ephys/onix-bonsai-onix1).
+Documentation for the [Onix1 Bonsai package](https://github.com/open-ephys/bonsai-onix1).
 
 These docs are built using [docfx](https://dotnet.github.io/docfx/index.html).
 
@@ -20,33 +20,31 @@ Download and install [git](https://git-scm.com/downloads) if it is not installed
 > It often appears to hang because it does not output any status information.
 > Usually, the command will eventually return.
 
-1. Clone the documentation repository:
+1. Using Windows PowerShell or a Git Bash terminal, clone the documentation repository:
     ``` console
-    git clone https://github.com/open-ephys/onix1-bonsai-docs
-    cd onix1-bonsai-docs
+    git clone https://github.com/open-ephys/bonsai-onix1-docs
+    cd bonsai-onix1-docs
     ```
 1. Pull in the latest files from the submodules according to the commit that the submodules point to:
     ``` console
     git submodule update --recursive --init
     ```
     In particular, the source code is available in this repo as a submodule. This will update the source code to the latest commit on main.
-1. Configure the docfx version and restore docfx companion tools such as [DocLinkChecker](https://github.com/Ellerbach/docfx-companion-tools/tree/main/src/DocLinkChecker).
-    ``` console
-    dotnet tool restore --configfile ./.bonsai/NuGet.config
-    ```
-1. To make the `docfx` command available after restoring the config file from the previous step, run:
+1. Configure the docfx version and restore docfx companion tools such as [DocLinkChecker](https://github.com/Ellerbach/docfx-companion-tools/tree/main/src/DocLinkChecker). You need to be in the same root folder where you cloned the repository for this to work. Run:
     ``` console
     dotnet tool restore
     ```
+    to make the `docfx` command available.
+
     If the above command yields the following error:
     ``` console
     It was not possible to find any installed .NET Core SDKs
     ```
     even after installing .NET as described previously in the readme, refer to [this comment](https://github.com/dotnet/core/issues/6095#issuecomment-809006602) for a potential fix. If you follow the instructions described in the comment, make sure you proceed in a terminal or command prompt opened after changing the environment variables.
-1. Set up a local Bonsai environment for automatically exporting SVGs, run: 
+1. Set up a local Bonsai environment for automatically exporting SVGs, run Setup.ps1 in PowerShell (or, if not using PowerShell, run Setup.Cmd): 
     ``` console
     ./.bonsai/Setup.ps1
-    ```
+    ```    
     If the above command yields the following error:
     ``` console
     ./Setup.ps1 : File C:\Users\User\...\bonsai-onix1-docs\Setup.ps1 cannot be loaded because running scripts is      
@@ -66,6 +64,8 @@ To build the docs and serve locally, run in PowerShell:
 ./build.ps1 --serve
 ```
 
+If this doesn't run, see comment in section above.
+
 If SVGs are already exported and do not need to be updated, they don't need to be re-exported. In that case, to build the docs and serve locally more quickly, run:
 
 ``` console
@@ -96,7 +96,7 @@ The above set of commands can also be run using the `docfx-utils.ps1` Powershell
 To run the next command, install [Lychee](https://github.com/lycheeverse/lychee?tab=readme-ov-file) by following [these instructions](https://github.com/lycheeverse/lychee?tab=readme-ov-file#installation). If you are use Windows and download a Lychee executable, amend the below command according to the location and version of your Lychee executable, and run it.
 
 ``` console
-<lychee/installation/directory>/lychee-v<x.xx.x>-windows-x86_64.exe --verbose --no-progress --base _site --exclude ^https://github\.com.*merge.* --exclude ^https://github\.com.*apiSpec.* '_site/**/*.html'
+<lychee/installation/directory>/lychee-v<x.xx.x>-windows-x86_64.exe --no-progress --base _site --exclude ^https://github\.com.*merge.* --exclude ^https://github\.com.*apiSpec.* --exclude ^https://github\.com/open-ephys/onix1-bonsai-docs/blob/.*/#L1 '_site/**/*.html' --max-retries 0 --max-concurrency 32 --cache --max-cache-age 1d
 ```
 
 If you use a different operating systems and a different methods of installation, the above command might require additional amendments. 
@@ -187,4 +187,4 @@ If there are discrepancies between local and remote builds:
 
 ## Style Guide
 
-Refer to the [Style Guide](style-guide.md).
+Refer to the [Style Guide](style-guide.md).

api/configure.md

@@ -1,9 +1,15 @@
 ---
 uid: configure
-title: Configuration Operators
+title: Device Group Configuration Operators
 ---
 
-Aggregate configuration operators belong in a top-level chain of operators between
-[`CreateContext`](xref:OpenEphys.Onix1.CreateContext) and [`StartAcquisition`](xref:OpenEphys.Onix1.StartAcquisition) to
-configure ONIX hardware hubs. These are known as aggregate configuration operators because they configure an aggregation
-of devices (also referred to as a hub) on a given headstage, miniscope, breakout board, etc..
+Device Group configuration operators belong in a top-level configuration chain between
+[CreateContext](xref:OpenEphys.Onix1.CreateContext) and
+[StartAcquisition](xref:OpenEphys.Onix1.StartAcquisition) to configure ONIX hardware. These are
+known as Device Group configuration operators because they configure a group of devices on a given
+headstage, miniscope, breakout board, etc. [!INCLUDE [device description](<./../includes/device-description.md>)]
+
+Device Group configuration operators are simply referred to as "Configuration Operators" in the
+[Reference](xref:OpenEphys.Onix1) table of contents for concision and simplicity as they are
+the recommended starting-point operators for configuring Open Ephys ONIX hardware. There are also
+<xref:device-configure>. 

api/device-configure.md

@@ -4,8 +4,12 @@ title: Device Configuration Operators
 ---
 
 > [!TIP]
->  Device configuration operators are not recommended for using off-the-shelf Open Ephys hardware. Use aggregate [configuration operators](xref:configure) instead. Aggregate [configuration operators](xref:configure) confer the following benefits:
-> - The `address` and `name` properties of aggregate configuration operators undergo automatic configuration which reduces the risk of erroneous configuration.
-> - The workflow is less cluttered with configuration operators as one aggregate configuration operator corresponds to multiple device operators. This improves workflow legibility and expedites the workflow scripting process.
+>  Device configuration operators are not recommended for using off-the-shelf Open Ephys hardware.
+>  Use [Device Group configuration operators](xref:configure) instead. They confer the following benefits:
+> - The `address` and `name` properties of Device Group configuration operators undergo automatic configuration which reduces the risk of erroneous configuration.
+> - The workflow is less cluttered with configuration operators as one Device Group configuration operator corresponds to multiple device operators. This improves workflow legibility and expedites the workflow scripting process.
 
-Device configuration operators belong in a top-level chain of operators between [`CreateContext`](xref:OpenEphys.Onix1.CreateContext) and [`StartAcquisition`](xref:OpenEphys.Onix1.StartAcquisition) to configure devices contained by ONIX hardware hubs.
+Device configuration operators belong in a top-level configuration chain between
+[CreateContext](xref:OpenEphys.Onix1.CreateContext) and
+[StartAcquisition](xref:OpenEphys.Onix1.StartAcquisition) to configure devices that can be found
+on ONIX hardware. [!INCLUDE [device description](<./../includes/device-description.md>)]

api/overview.md

@@ -3,7 +3,54 @@ uid: OpenEphys.Onix1
 title: OpenEphys.Onix1
 ---
 
-`OpenEphys.Onix1` is a Bonsai package containing interfaces for data acquisition and control of ONIX hardware. This section
-of the docs is dedicated to facilitate construction of workflows using the OpenEphys.Onix1 package.
+> [!TIP]
+> Quickly access these pages in Bonsai by pressing <kbd>F1</kbd> while an OpenEphys.Onix1 operator
+> is selected in the workflow or Toolbox. 
 
-In Bonsai, press <kbd>F1</kbd> while an OpenEphys.Onix1 node is selected in the workflow editor to quickly open this reference.
+OpenEphys.Onix1 is a Bonsai package for control of and data acquisition from 
+ONIX hardware. This section of the docs is dedicated to facilitate construction 
+of workflows using OpenEphys.Onix1. It contains helpful information about 
+OpenEphys.Onix1 operators and the data elements they produce such as in-depth 
+descriptions of their properties and their input/output data types. The data
+elements produced by OpenEphys.Onix1 operators contain information to interpret
+data such as equations for converting electrophysiology signals from the ADC 
+step-size to volts. The <xref:OpenEphys.Onix1.Rhs2116DataFrame> page exemplifies 
+this.
+
+## Property Categories
+
+In the OpenEphys.Onix1 package, properties belong to specific categories that
+define when the property effects the hardware. 
+
+- <span class="badge oe-badge-border oe-badge-yellow"
+id="configuration">Configuration</span> properties have an effect on hardware
+when a workflow is started and are used to initialize the hardware state. If
+they are changed while a workflow is running, they will not have an effect until
+the workflow is restarted. For example, CreateContext's
+<xref:OpenEphys.Onix1.CreateContext.Index> Configuration property is used to 
+specify the hardware prior to starting a recording, and editing this property 
+has no effect until the workflow is started or restarted.
+- <span class="badge oe-badge-border oe-badge-blue"
+id="acquisition">Acquisition</span> properties have an immediate effect on
+hardware when the workflow is running. For example, 
+Headstage64ElectricalStimulatorTrigger's Acquisition properties (e.g. 
+<xref:OpenEphys.Onix1.Headstage64ElectricalStimulatorTrigger.InterPulseInterval>)
+allow dynamically configuring stimulus patterns in real-time while a workflow 
+is running.
+
+Properties are additionally grouped by whether they effect a group of devices
+or a single device:
+
+- <span class="badge oe-badge-border oe-badge-green" id="device-group">Device
+Group</span> properties are only available through [Device Group configuration
+operators](xref:configure) that are used for configuring groups of devices. 
+For example, ConfigureNeuropixelsV2eHeadstage's 
+<xref:OpenEphys.Onix1.ConfigureNeuropixelsV2eHeadstage.Port> property sets the
+port name for all devices on the NeuropixelsV2e Headstage (which in turn 
+automatically configures each device's address). 
+- <span class="badge oe-badge-border oe-badge-purple" id="device">Device</span>
+properties are available through [Device configuration
+operators](xref:device-configure) and Device Group configuration operators which
+combine multiple individual devices. They are used to configure a single device. 
+For example, ConfigureBreakoutBoard's <xref:OpenEphys.Onix1.ConfigureBreakoutBoard.AnalogIO> 
+device properties can be used to configure Breakout Board's Analog I/O device.

articles/getting-started/bonsai-workflows.md

@@ -0,0 +1,34 @@
+---
+uid: bonsai-workflows
+title: Bonsai Workflows
+---
+
+Scripts in Bonsai are known as **workflows**. A workflow comprises of "operators" that are represented
+by nodes which connect to form a data processing graph. Each connection indicates that the
+downstream operator on the right takes the sequence of data from the upstream operator on the left
+as input. The behavior of an operator depends on its type. For example:
+
+- A `source` operator produces its own sequence of data.
+- A `transform` operator transforms data in its input sequence.
+- A `sink` operator produces a side effect (such as writing data or outputting an external signal
+like a noise through your computer's speaker or a digital output toggle through your ONIX breakout
+board).
+- A `combinator` operator controls the flow of downstream sequences.
+
+The workflow editor represents these operators using different colors and a grey arc. The [official
+Bonsai docs](https://bonsai-rx.org/docs/articles/operators.html) provides a nice description of operators
+and the various types with pictures.
+
+Below is an example workflow which configures ONIX hardware.
+
+::: workflow
+![/workflows/getting-started/start-acquisition.bonsai workflow](../../workflows/getting-started/start-acquisition.bonsai)
+:::
+
+> [!TIP]
+> This workflow, and others like it in these docs, can be copied and pasted into
+> the Bonsai editor using the clipboard icon that appears when you hover your
+> mouse over the image.
+
+We'll take a closer look at how this workflow is created and what it's used for
+in the following pages.

articles/getting-started/index.md

@@ -3,11 +3,12 @@ uid: getting-started
 title: Getting Started
 ---
 
-Welcome to the user guide! The next few pages are for users to learn how to use ONIX hardware using the OpenEphys.Onix1
-Bonsai package. Browse the articles in the table of contents to learn more.
+Welcome to the user guide! These pages are for users to learn how to use ONIX hardware through
+the OpenEphys.Onix1 Bonsai package. Browse the articles in the table of contents to learn more.
 
-This software documentation is intended to be used hand-in-hand with the 
-[Hardware documentation](https://open-ephys.github.io/onix-docs/index.html) to learn about and start using their ONIX hardware. 
+This software documentation is intended to be used hand-in-hand with the [Hardware
+documentation](https://open-ephys.github.io/onix-docs/index.html) to learn about and start using
+ONIX hardware. 
 
-For those who are looking for user guides and example workflows for using a particular device or headstage in Bonsai, visit
-the <xref:hardware>.
+For those who are looking for user guides and example workflows for using a particular device or
+headstage in Bonsai, visit the <xref:hardware>.