Skip to content

Commit

Permalink
Minor edits across Rhs2116 docs
Browse files Browse the repository at this point in the history
- wrap to 100 instead of 120
- Remove some superfluous formatting
- Clarity edits
  • Loading branch information
cjsha committed Jan 2, 2025
1 parent 57dd398 commit db1a01f
Show file tree
Hide file tree
Showing 9 changed files with 224 additions and 171 deletions.
19 changes: 10 additions & 9 deletions articles/hardware/rhs2116/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,17 @@ workflowLocation: overview

## Configuring the Breakout Board and Headstage Rhs2116

The `ConfigureBreakoutBoard` operator configures the Onix Breakout Board. In the Headstage Rhs2116 example tutorial, it is
configured to enable digital inputs to serve as a trigger for the Headstage Rhs2116's electrical and optical stimulation
and to enable monitoring of the percentage of memory occupied. This is accomplished by leaving all of the
`ConfigureBreakoutBoard` properties set to their default values except its `Memory Monitor` `Enable` property is set to
`True`.
The `ConfigureBreakoutBoard` operator configures the Onix Breakout Board. In the Headstage Rhs2116
example tutorial, it is configured to enable digital inputs to serve as a trigger for the Headstage
Rhs2116's electrical and optical stimulation and to enable monitoring of the percentage of memory
occupied. This is accomplished by leaving all of the `ConfigureBreakoutBoard` properties set to
their default values except its Memory Monitor Enable property is set to "True".

The `ConfigureHeadstageRhs2116` operator is used to configure the Headstage Rhs2116. In the Headstage Rhs2116 example
tutorial, it is configured to enable streaming of electrophysiology data from a Rhs2116 amplifier, orientation data from
the on-board Bno055 IMU, and position data from the Ts4231. This is accomplished in the Headstage Rhs2116 example
workflow by leaving all of the `ConfigureHeadstageRhs2116` properties set to their default values.
The `ConfigureHeadstageRhs2116` operator is used to configure the Headstage Rhs2116. In the
Headstage Rhs2116 example tutorial, it is configured to enable streaming of electrophysiology data
from a Rhs2116 amplifier, orientation data from the on-board Bno055 IMU, and position data from the
Ts4231. This is accomplished in the Headstage Rhs2116 example workflow by leaving all of the
`ConfigureHeadstageRhs2116` properties set to their default values.

[!INCLUDE [timestamp-info](../../../includes/configuration-timestamp.md)]

Expand Down
91 changes: 45 additions & 46 deletions articles/hardware/rhs2116/gui.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,59 +12,60 @@ downloaded. For more information on how to install that library, check out the
The GUI for `Rhs2116Headstage` allows for an easy way to change settings, as well as the ability to
set waveform parameters and visualize the effect. From the GUI, you can:

- Modify stimulus parameters for all 32 channels simultaneously
- Visualize waveforms across all channels
- Select specific channels using a ProbeInterface representation of the hardware
- Remove or add stimulus waveform parameters to one or more channels at a time
- Modify stimulus parameters for all 32 channels
- Visualize waveforms across all channels
- Select specific channels using a ProbeInterface representation of the hardware
- Remove or add stimulus waveform parameters to one or more channels at a time
- Save and load channel configuration
- Change filter settings for recording data
- See the <xref:rhs2116_configuration> page for more information on filter settings
- See <xref:OpenEphys.Onix1.ConfigureHeadstageRhs2116> or the
[Rhs2116 datasheet](https://intantech.com/files/Intan_RHS2116_datasheet.pdf) for more
information on filter settings

This configuration GUI can be accessed by double-clicking on the `ConfigureHeadstageRhs2116`
operator. The remainder of this page will describe the functionality of the window that opens,
allowing for easy configuring of the hardware.
operator.

<p align="center">
<img src="../../../images/rhs2116-gui-tut/bonsai-where-to-click.png">
</p>

### Stimulus parameters

All of the parameters are applied in real-world units that the user will be familiar with (i.e.,
milliseconds and microamps). On the backend, the GUI will take these units and convert them into raw
samples which is how they will be written to the hardware. Since the conversion between real units
and samples is not always exact, there might be some discrepancies between the value that the user
initially inputs and the value that is automatically updated. Values will be automatically updated
whenever the focus moves away from the current text box (i.e., the user presses <kbd>Tab</kbd> or
clicks somewhere outside of the text box).
The GUI accepts values for stimulation waveform parameters in metric units (e.g., milliseconds and
microamps). In the backend, the GUI converts metric units into units that can be written to the
hardware. Because the conversion between metric values and converted values is not always exact, the
GUI might automatically update the metric value initially input by the user to a metric value that
more accurately represents the converted value that will be written to hardware. This update is
visually displayed in the same text box where the user initially input their values and happens when
the focus moves away from the active text box (e.g., the user presses <kbd>Tab</kbd> or clicks
somewhere outside of the text box).

Below is a table listing the various parameters that can be applied to each channel, as well as the
resolution and any other relevant limits for each parameter.
Below is a table describing the various stimulus parameters that can be applied to each channel
including the resolution and limits for each parameter.

| Parameter Name | Minimum Value | Maximum Value | Resolution | Remarks |
| ----- | ---- | ---- | ---- | ---- |
| `Biphasic Symmetric` | Unchecked | Checked | n/a | If checked, the positive and negative segments of each pulse will be symmetric |
| `Anodic First` | Unchecked | Checked | n/a | If checked, the anodic (positive) segment will be delivered first for every pulse |
| `Delay` | 0 ms | n/a | 0.03312 ms | Time between a trigger being received and the first pulse is delivered |
| `Inter-Pulse` | 0 ms | n/a | 0.03312 ms | Time between positive-to-negative (or negative-to-positive) stimulation for a single pulse |
| `Amplitude` | 0 µA | 2550 µA | Dependent on the step size | Type in the requested amplitude, and underneath is the actual value that will be applied on hardware based on the current step size |
| `Step Size` | 0.01 µA | 25 µA | [Step Size](xref:OpenEphys.Onix1.Rhs2116StepSize) | Automatically calculated to optimize difference between requested and actual amplitude |
| `Pulse Width` | 0.03312 ms | n/a | 0.03312 ms | Width of each positive or negative portion of the stimulus |
| `Amplitude` | 0 µA | 2550 µA | Dependent on the step size | Enter the requested amplitude, and the actual value that will be applied on hardware based on the current step size is displayed underneath in the `Step Size` text box |
| `Step Size` | 0.01 µA | 25 µA | [Step Size](xref:OpenEphys.Onix1.Rhs2116StepSize) | Automatically calculated to optimize difference between requested and actually possible amplitude |
| `Pulse Width` | 0.03312 ms | n/a | 0.03312 ms | Time between each pulse's rising edge and falling edge (or vice-versa) |
| `Inter-Stimulus` | 0.03312 ms | n/a | 0.03312 ms | Time between successive pulses. Can be 0 if there is only one pulse |
| `Number of Pulses` | 1 | n/a | 1 | Number of pulses that are sent per trigger received |

### ProbeInterface

The `Rhs2116Headstage` GUI uses
[ProbeInterface](https://probeinterface.readthedocs.io/en/main/index.html) as the format to draw the
probes and electrodes visually. For more information on ProbeInterface and the resulting JSON file,
check out their [format
specifications](https://probeinterface.readthedocs.io/en/main/format_spec.html) page.
The `Rhs2116Headstage` GUI uses the
[ProbeInterface](https://probeinterface.readthedocs.io/en/main/index.html) format to draw the probes
and electrodes visually. For more information on the ProbeInterface JSON format, check out their
[format specifications](https://probeinterface.readthedocs.io/en/main/format_spec.html) page.

When opening the GUI, there is a default probe configuration that is loaded and drawn, which can be
saved to a [JSON file](#save-probeinterface-file). Conversely, an existing JSON file can be
[loaded](#load-probeinterface-file) to update the current channel configuration. If for any reason
the default configuration is needed, it can be [loaded again](#load-default-configuration) at any
time.
When opening the GUI, there is a default probe configuration that is loaded and drawn which can be
saved to a [JSON file](#save-probeinterface-file). Conversely, an existing ProbeInterface JSON file
can be [loaded](#load-probeinterface-file) to update the current channel configuration. If the
default configuration is needed, it can be [loaded again](#load-default-configuration) at any time.

## Using the Channel Selection Window

Expand All @@ -86,11 +87,11 @@ are the controls used to navigate within this panel to view and choose electrode
- Mouse wheel zooms in/out towards the cursor
- Left-click and drag will select electrodes within the drawn rectangle
- Left-click on an electrode will toggle selection for that electrode
- Left-click in empty space will clear the selected electrodes
- Left-click on empty space will clear the electrode selection
- Middle-click and drag will pan the electrodes

When channels are selected, they will be highlighted by a green circle around the contact number,
and the appropriate waveform will continue to be plotted in the main window; any channels that are
and the corresponding waveforms will be plotted in the main window; any channels that are
not selected will not be plotted.

### Zoom and pan limits
Expand All @@ -104,10 +105,9 @@ is always in view. This is handled each time the probe is zoomed or panned.

## Define Stimuli

The following sections will define how to apply parameters, read existing parameters, and clear
parameters from channels. A description of what the parameters refer to will be given, as well as
tables to define some of the error codes that can appear in the status strip to better troubleshoot
issues.
The following sections define how to apply parameters, read existing parameters, and clear parameters from channels.
They also provide example stimulus parameters and descriptions of error codes that can appear in the status strip to
facilitate troubleshooting.

### Applying parameters

Expand All @@ -121,13 +121,12 @@ are selected.
<img src="../../../images/rhs2116-gui-tut/channel-selection-7-8-23-24.png">
</p>

Next, type in / check the [stimulus parameters](#stimulus-parameters) that are to be
applied to the currently selected channel(s). The section above will give some insight into what
each parameter is controlling, as well as the possible resolutions and maximum/minimum values that
can be applied. Note that each time the cursor leaves a text box it will automatically update the
values inside the text box to reflect the actual value that will be written, based on the
resolutions listed above. In the example below, we can see that the table listed below as well shows
the typed values compared to the actual values list.
Enter the [stimulus parameters](#stimulus-parameters) that you want to apply to the currently
selected channel(s). Note that the value initially input by the user might update when the focus
moves away from the current text box (e.g., the user presses <kbd>Tab</kbd> or clicks somewhere
outside of the text box) to reflect the actual value that will be written based on the resolutions
listed above. In the example below, we can see that the table listed below as well shows the typed
values compared to the actual values list.

| Parameter | Requested Value | Listed Value |
| --- | --- | --- |
Expand Down Expand Up @@ -178,8 +177,8 @@ parameter fields will be populated with zeroes as shown in the image below:
<img src="../../../images/rhs2116-gui-tut/define-stimuli-read-defaults.png">
</p>

Any channel that has been configured can also be selected before pressing <kbd>Read</kbd> to pull
out the current parameters. For example, if one of the channels that was configured in the [Applying
Now select a channel that has been configured and press <kbd>Read</kbd> to read that channel's
current parameters. For example, if one of the channels that was configured in the [Applying
parameters](#applying-parameters) section above is selected, the image below shows the result of the
operation:

Expand Down Expand Up @@ -239,8 +238,8 @@ configuration, such as filter settings and all stimulus waveform parameters.
> [!NOTE]
> The hardware is not actually configured until the workflow starts.
If the window is closed any other way (such as by pressing `Cancel`, or pressing the <kbd>X</kbd> to
close the window), then any changes made *will not* be saved. If the current settings are considered
If the window is closed any other way (such as by pressing `Cancel` or pressing the <kbd>X</kbd> to
close the window), any changes made *will not* be saved. If the current settings are considered
invalid (see [the table above](#reasons-for-invalid-sequence-status) for specific reasons why some
settings are invalid), they also *will not* be saved even if <kbd>Ok</kbd> is pressed. A message box
will pop up warning that the settings will not be saved, giving the opportunity to continue editing
Expand Down
28 changes: 14 additions & 14 deletions articles/hardware/rhs2116/rhs2116-record.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,26 @@ uid: rhs2116_record
title: Rhs2116 Recording
---

The following excerpt from the HeadstageRhs2116 [example workflow](xref:rhs2116) demonstrates the Rhs2116
recording functionality by streaming and saving data from the Rhs2116 device.
The following excerpt from the HeadstageRhs2116 [example workflow](xref:rhs2116) demonstrates the
Rhs2116 recording functionality by streaming and saving data from the Rhs2116 device.

::: workflow
![/workflows/hardware/rhs2116/rhs2116-record.bonsai workflow](../../../workflows/hardware/rhs2116/rhs2116-record.bonsai)
:::

The <xref:OpenEphys.Onix1.Rhs2116Data> operator generates a sequence of <xref:OpenEphys.Onix1.Rhs2116DataFrame>s using
the following settings:
- `BufferSize` is set to 30. Each `Rhs2116DataFrame` will contain a [1 x 30 sample] `Clock` vector, a [32 channel x 30
sample] `AmplifierData` matrix, and a [3 channel x 30 sample] `AuxData` matrix. This corresponds to 1.2 ms of data per
data frame.
- `DeviceName` is set to "HeadstageRhs2116/Rhs2116". This links the `Rhs2116Data`
operator to the corresponding configuration operator.
The <xref:OpenEphys.Onix1.Rhs2116Data> operator generates a sequence of
<xref:OpenEphys.Onix1.Rhs2116DataFrame>s using the following settings:
- The BufferSize property is set to 30. Each `Rhs2116DataFrame` will contain a [1 x 30 sample] Clock
vector, a [32 channel x 30 sample] AmplifierData matrix, and a [32 channel x 30 sample] DcData
matrix. This corresponds to 1 ms of data per data frame.
- The DeviceName property is set to "HeadstageRhs2116/Rhs2116". This links `Rhs2116Data` to the
Rhs2116s on the Headstage Rhs2116.

The relevant properties are extracted from the `Rhs2116DataFrame` by right-clicking the `Rhs2116Data` operator, and
choosing the following Output members: `Clock`, `AmplifierData`, and `DcData`. The
<xref:Bonsai.Dsp.MatrixWriter> operators saves the selected members to
files with the following format: `rhs2116pair-clock_<filecount>.raw`, `rhs2116pair-dc_<filecount>.raw`, and
`rhs2116pair-ac_<filecount>.raw`, respectively.
The relevant properties are extracted from the `Rhs2116DataFrame` by right-clicking the
`Rhs2116Data` operator, and choosing the following Output members: Clock, AmplifierData, and DcData.
The <xref:Bonsai.Dsp.MatrixWriter>s save the selected members to files with the following
formats: `rhs2116pair-clock_<filecount>.raw`, `rhs2116pair-ac_<filecount>.raw`, and
`rhs2116pair-dc_<filecount>.raw`, respectively.

> [!TIP]
> For more details about configuring the Rhs2116 and its data, read the
Expand Down
32 changes: 18 additions & 14 deletions articles/hardware/rhs2116/rhs2116-stimulate.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,26 @@ stimulation functionality by streaming and saving data from the Rhs2116 device.
![/workflows/hardware/rhs2116/rhs2116-stimulate.bonsai workflow](../../../workflows/hardware/rhs2116/rhs2116-stimulate.bonsai)
:::

The <xref:OpenEphys.Onix1.DigitalInput> operator generates a sequence of <xref:OpenEphys.Onix1.DigitalInputDataFrame>s.
Although the digital inputs are sampled at 4 Mhz, these data frames are only emitted when the port status changes (i.e.,
when a pin, button, or switch is toggled). In the Breakout Board example workflow, the `DigitalInput`'s `DeviceName`
property is set to "BreakoutBoard/DigitalInput". This links the `DigitalInput` operator to the corresponding
configuration operator.
The <xref:OpenEphys.Onix1.DigitalInput> operator generates a sequence of
<xref:OpenEphys.Onix1.DigitalInputDataFrame>s. Although the digital inputs are sampled at 4 Mhz,
these data frames are only emitted when the port status changes (i.e., when a pin, button, or switch
is toggled). In the Breakout Board example workflow, the `DigitalInput`'s DeviceName property is
set to "BreakoutBoard/DigitalInput". This links the `DigitalInput` operator to the Breakout Board's
digital inputs.

<xref:OpenEphys.Onix1.BreakoutButtonState> is selected from the `DigitalInputDataFrame`. It is an enumerator with values
that correspond to bit positions of the breakout board's digital port. `Buttons` connects to `Condition` which is
inspectable with the <kbd>F12</kbd> hotkey. `Condition` contains a `HasFlags` operator. Because `HasFlags`'s `Value` is
set to "Triangle", its output is "True" when the selected `BreakoutButtonState` bit field contains the "Triangle" flag.
Therefore, the conditional statement evaluates as true whenever the "Triangle" button is pressed in which case the
upstream `BreakoutButtonState` element emitted by `Condition` to `Double`, which emits a value of type <xref:System.Double>
to <xref:OpenEphys.Onix1.Rhs2116StimulusTrigger> anytime it receives an item in its upstream sequence.
<xref:OpenEphys.Onix1.BreakoutButtonState> is selected from the `DigitalInputDataFrame`. It is an
enumerator with values that correspond to bit positions of the breakout board's digital port.
`Buttons` connects to `Condition` which is inspectable with the <kbd>F12</kbd> hotkey. `Condition`
contains a `HasFlags` operator. Because `HasFlags`'s Value property is set to "Triangle", it outputs
"True" when the △ button is pressed. `Condition` passes `BreakoutButtonState` to `Double`
when the its internal conditional statement is evaluated is true. `Double` emits a value of type
<xref:System.Double> to <xref:OpenEphys.Onix1.Rhs2116StimulusTrigger> anytime it receives an item in
its upstream sequence.

When `Rhs2116StimulusTrigger` receives a double from the upstream sequence, a stimulus waveform is triggered. The
waveform can be modified by `Rhs2116StimulusTrigger`'s properties.
When `Rhs2116StimulusTrigger` receives a double from the upstream sequence, a stimulus waveform is
triggered. Its DeviceName property is set to "HeadstageRhs2116/StimulusTrigger" to link this
operator to the Rhs2116s on the Headstage Rhs2116. [Open the Headstage RHS2116
GUI](xref:rhs2116_gui) to edit the stimulus waveform.

> [!TIP]
> For more details about configuring the Rhs2116 and its stimulation capabilities, read the
Expand Down
12 changes: 5 additions & 7 deletions includes/configuration-timestamp.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
When the workflow is started, the current time (based on
[Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time))
is saved, along with global hardware parameters governing data acquisition. This is
accomplished using a [TimeStamp](https://bonsai-rx.org/docs/api/Bonsai.Reactive.Timestamp.html) operator
to capture the computer's wall clock time. This
`Timestamp` is saved along with `ContextTask`'s properties (e.g.,
`AcquisitionClockHz`, `BlockReadSize`, `BlockWriteSize`) to a csv
file (`start-time_<filecount>.csv`) when the the workflow is started.
[Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time)) is saved, along with global
hardware parameters governing data acquisition. This is accomplished using a
[TimeStamp](https://bonsai-rx.org/docs/api/Bonsai.Reactive.Timestamp.html) operator to capture the computer's wall clock
time. The timestamp is saved along with `ContextTask`'s properties (e.g. AcquisitionClockHz, BlockReadSize,
BlockWriteSize) to a csv file (`start-time_<filecount>.csv`) when the workflow is started.
Loading

0 comments on commit db1a01f

Please sign in to comment.