Add workflow and page for MemoryUsageDevice (#51)

- Added three new files: workflow, workflow svg, and page for workflow - Block read size set low in workflow to allow buffer to accumulate data - Labels added to reference parts of memory monitor datasheet and OniContext node - "Read Block Size" -> "Block Read Size" & "Write Block Size" -> "Block Write Size" to reflect the OniContext node's configuration table
open-ephys · Apr 22, 2024 · 110fc00 · 110fc00
1 parent e2b3dd6
commit 110fc00
Show file tree

Hide file tree

Showing 6 changed files with 178 additions and 2 deletions.
diff --git a/source/Hardware Guide/Datasheets/memory-usage.rst b/source/Hardware Guide/Datasheets/memory-usage.rst
@@ -74,6 +74,8 @@ Register Programming
       - None
       - Number of 32-bit words stored in memory, same value as what the frames generate
 
+.. _onidatasheet_memory-usage_d2h:
+
 Device To Host Data Frames
 ******************************************
 Each frame transmitted to the host is structured as follows:

diff --git a/source/Software Guide/Bonsai.ONIX/Nodes/MemoryUsageDevice.rst b/source/Software Guide/Bonsai.ONIX/Nodes/MemoryUsageDevice.rst
@@ -0,0 +1,52 @@
+
+
+#################
+MemoryUsageDevice
+#################
+
+
+A `Bonsai source <https://bonsai-rx.org/docs/editor/#toolbox>`__ that wraps a
+:ref:`onidatasheet_memory-usage` device.
+
+:Inputs:  None
+:Outputs: A single ``MemoryUsageDataFrame`` that is produced periodically by
+          hardware containing information about data buffer memory status.
+          This type is a wrapper around the :ref:`Device To Host Data Frame <onidatasheet_memory-usage_d2h>` specified 
+          on the :ref:`onidatasheet_memory-usage` datasheet. To calculate the percentage of memory that is occupied, 
+          divide the number of 32-bit memory words used by the hardware's total memory and multiply that quotient by 100. 
+
+..  attention:: 
+    The :ref:`Block Read Size <bonsai_onicontext_configuration>` property in the :ref:`bonsai_onicontext` node is set intentionally low so that the buffer accumulates data for demonstration purposes.
+
+.. raw:: html
+
+    {% with static_path = '../../../_static', name = 'MemoryMonitor' %}
+        {% include 'workflow.html' %}
+    {% endwith %}
+
+*************
+Configuration
+*************
+
+Configuration is performed using its property pane which contains the following
+options.
+
+.. list-table::
+    :widths: auto
+    :header-rows: 1
+
+    * - Name
+      - Type
+      - Description
+
+    * - EnableStream
+      - boolean
+      - Enable the device data stream
+
+    * - UpdateHz
+      - uint
+      - Rate at which the hardware memory usage is polled in Hz.
+
+    * - MemorySize
+      - uint
+      - Hardware buffer size in 32-bit words.
diff --git a/source/Software Guide/Bonsai.ONIX/Nodes/ONIContext.rst b/source/Software Guide/Bonsai.ONIX/Nodes/ONIContext.rst
@@ -64,6 +64,8 @@ to use it.
     present in a single computer, then each will need its own
     :ref:`bonsai_onicontext` to manage it.
 
+.. _bonsai_onicontext_configuration:
+
 Configuration GUI
 --------------------------
 :ref:`bonsai_onicontext` configuration is performed using a GUI provided in the
@@ -80,10 +82,10 @@ using the **Properties Pane** on the right side of the form.
 #. **Settings**: Drop down menu that provides several hardware configuration options
 #. **Driver**: The device driver used to control the host hardware.
 #. **Slot**: The physical slot of the Host hardware in the computer.
-#. **Read Block Size**: The number of bytes read per call to the kernel driver.
+#. **Block Read Size**: The number of bytes read per call to the kernel driver.
    Larger numbers *will generally* increase overall bandwidth and decrease
    response latency.
-#. **Write Block Size**: The number of bytes pre-allocated to make output for output
+#. **Block Write Size**: The number of bytes pre-allocated to make output for output
    data frames. Larger numbers *may* increase overall bandwidth and decrease
    response latency.
 #. |refresh_icon| **<status>**: Shows the current host hardware connection status.

diff --git a/source/Software Guide/Bonsai.ONIX/Nodes/index.rst b/source/Software Guide/Bonsai.ONIX/Nodes/index.rst
@@ -17,6 +17,7 @@ Nodes
 
     ONIContext
     HeartbeatDevice
+    MemoryUsageDevice
     AnalogIODevice
     DigitalIODevice
     ClockOutputDevice

diff --git a/source/_static/bonsai/workflows/MemoryMonitor.bonsai b/source/_static/bonsai/workflows/MemoryMonitor.bonsai
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="utf-8"?>
+<WorkflowBuilder Version="2.8.1"
+                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                 xmlns:p1="clr-namespace:Bonsai.ONIX;assembly=Bonsai.ONIX"
+                 xmlns:dsp="clr-namespace:Bonsai.Dsp;assembly=Bonsai.Dsp"
+                 xmlns:io="clr-namespace:Bonsai.IO;assembly=Bonsai.System"
+                 xmlns="https://bonsai-rx.org/2018/workflow">
+  <Workflow>
+    <Nodes>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="p1:ONIContext">
+          <p1:ContextConfiguration>
+            <p1:Slot>
+              <p1:Driver>riffa</p1:Driver>
+              <p1:Index>0</p1:Index>
+            </p1:Slot>
+            <p1:ReadSize>48</p1:ReadSize>
+            <p1:WriteSize>8192</p1:WriteSize>
+          </p1:ContextConfiguration>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="p1:AnalogIODevice">
+          <p1:DeviceAddress>
+            <p1:HardwareSlot>
+              <p1:Driver>riffa</p1:Driver>
+              <p1:Index>0</p1:Index>
+            </p1:HardwareSlot>
+            <p1:Address>6</p1:Address>
+          </p1:DeviceAddress>
+          <p1:BlockSize>100</p1:BlockSize>
+          <p1:DataType>Volts</p1:DataType>
+          <p1:EnableStream>true</p1:EnableStream>
+          <p1:InputRange00>TenVolts</p1:InputRange00>
+          <p1:InputRange01>TenVolts</p1:InputRange01>
+          <p1:InputRange02>TenVolts</p1:InputRange02>
+          <p1:InputRange03>TenVolts</p1:InputRange03>
+          <p1:InputRange04>TenVolts</p1:InputRange04>
+          <p1:InputRange05>TenVolts</p1:InputRange05>
+          <p1:InputRange06>TenVolts</p1:InputRange06>
+          <p1:InputRange07>TenVolts</p1:InputRange07>
+          <p1:InputRange08>TenVolts</p1:InputRange08>
+          <p1:InputRange09>TenVolts</p1:InputRange09>
+          <p1:InputRange10>TenVolts</p1:InputRange10>
+          <p1:InputRange11>TenVolts</p1:InputRange11>
+          <p1:Direction00>Input</p1:Direction00>
+          <p1:Direction01>Input</p1:Direction01>
+          <p1:Direction02>Input</p1:Direction02>
+          <p1:Direction03>Input</p1:Direction03>
+          <p1:Direction04>Input</p1:Direction04>
+          <p1:Direction05>Input</p1:Direction05>
+          <p1:Direction06>Input</p1:Direction06>
+          <p1:Direction07>Input</p1:Direction07>
+          <p1:Direction08>Input</p1:Direction08>
+          <p1:Direction09>Input</p1:Direction09>
+          <p1:Direction10>Input</p1:Direction10>
+          <p1:Direction11>Input</p1:Direction11>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="MemberSelector">
+        <Selector>Data</Selector>
+      </Expression>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="dsp:MatrixWriter">
+          <dsp:Path>analog-data_.raw</dsp:Path>
+          <dsp:Suffix>Timestamp</dsp:Suffix>
+          <dsp:Overwrite>false</dsp:Overwrite>
+          <dsp:Layout>ColumnMajor</dsp:Layout>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="MemberSelector">
+        <Selector>Clock</Selector>
+      </Expression>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="dsp:MatrixWriter">
+          <dsp:Path>analog-clock_.raw</dsp:Path>
+          <dsp:Suffix>Timestamp</dsp:Suffix>
+          <dsp:Overwrite>false</dsp:Overwrite>
+          <dsp:Layout>ColumnMajor</dsp:Layout>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="p1:MemoryUsageDevice">
+          <p1:DeviceAddress>
+            <p1:HardwareSlot>
+              <p1:Driver>riffa</p1:Driver>
+              <p1:Index>0</p1:Index>
+            </p1:HardwareSlot>
+            <p1:Address>10</p1:Address>
+          </p1:DeviceAddress>
+          <p1:EnableStream>true</p1:EnableStream>
+          <p1:UpdateHz>100</p1:UpdateHz>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="io:CsvWriter">
+        <io:FileName>memory-use_.csv</io:FileName>
+        <io:Append>false</io:Append>
+        <io:Overwrite>false</io:Overwrite>
+        <io:Suffix>Timestamp</io:Suffix>
+        <io:IncludeHeader>false</io:IncludeHeader>
+        <io:Selector>Clock,MemoryUsageBytes,MemoryUsagePercentage</io:Selector>
+      </Expression>
+      <Expression xsi:type="MemberSelector">
+        <Selector>MemoryUsagePercentage</Selector>
+      </Expression>
+    </Nodes>
+    <Edges>
+      <Edge From="1" To="2" Label="Source1" />
+      <Edge From="1" To="4" Label="Source1" />
+      <Edge From="2" To="3" Label="Source1" />
+      <Edge From="4" To="5" Label="Source1" />
+      <Edge From="6" To="7" Label="Source1" />
+      <Edge From="7" To="8" Label="Source1" />
+    </Edges>
+  </Workflow>
+</WorkflowBuilder>
diff --git a/source/_static/bonsai/workflows/MemoryMonitor.svg b/source/_static/bonsai/workflows/MemoryMonitor.svg