From f1ba73318adb2cf75a942db4a0df2c38e386c2ea Mon Sep 17 00:00:00 2001 From: jonnew Date: Tue, 3 Sep 2024 10:27:46 -0400 Subject: [PATCH 1/2] Improve StartAqcuisition documentation - Add details to class description about what the operator does and what it produces without cref links to clroni - Fix typo in BitHelper --- OpenEphys.Onix1/BitHelper.cs | 2 +- OpenEphys.Onix1/StartAcquisition.cs | 65 +++++++++++++++++++++-------- 2 files changed, 49 insertions(+), 18 deletions(-) diff --git a/OpenEphys.Onix1/BitHelper.cs b/OpenEphys.Onix1/BitHelper.cs index 875712e..04ad71a 100644 --- a/OpenEphys.Onix1/BitHelper.cs +++ b/OpenEphys.Onix1/BitHelper.cs @@ -10,7 +10,7 @@ static class BitHelper /// /// The value where bits will be replaced. /// A mask defining which bits should be replaced. - /// A value containing the bits that will be assingned to the + /// A value containing the bits that will be assigned to the /// positions in . /// internal static uint Replace(uint value, uint mask, uint bits) diff --git a/OpenEphys.Onix1/StartAcquisition.cs b/OpenEphys.Onix1/StartAcquisition.cs index 1c5d2c2..fd6ee03 100644 --- a/OpenEphys.Onix1/StartAcquisition.cs +++ b/OpenEphys.Onix1/StartAcquisition.cs @@ -9,19 +9,49 @@ namespace OpenEphys.Onix1 /// /// Starts data acquisition and frame distribution on a . /// + /// + /// The open neuro interface (ONI) hardware + /// specification and API describe a general purpose acquisition system architecture and programming + /// interface for communication with a host PC. One requirement of ONI is a sequence of events that must + /// occur in order to start synchronized data acquisition. performs these + /// required actions on one or more s provided in its input sequence. Once + /// aquisition is started, devices within a particular context will start to produce data in a format + /// called an "ONI frame". The output sequence of this operator is therefore a , where + /// + /// + /// Tkey + /// + /// Is the address of a particular hardware device within a single . + /// + /// + /// + /// TElement + /// + /// Is a ONI frame produced by the device with address Tkey. + /// + /// + /// + /// These pre-sorted frame sequences can be interpreted by downstream data processing operators (e.g. or ) that convert ONI frames, which consist of + /// byte arrays with a header and data block, into data types that are are more amenable to processing + /// within Bonsai workflows. + /// [Description("Starts data acquisition and frame distribution on a ContextTask.")] public class StartAcquisition : Combinator> { /// - /// Gets or sets the number of bytes read per cycle of the 's acquisition thread. + /// Gets or sets the number of bytes read per cycle of the 's acquisition + /// thread. /// /// - /// This option allows control over a fundamental trade-off between closed-loop response time and overall bandwidth. - /// A minimal value, which is determined by , will provide the lowest response latency, - /// so long as data can be cleared from hardware memory fast enough to prevent buffering. Larger values will reduce system - /// call frequency, increase overall bandwidth, and may improve processing performance for high-bandwidth data sources. - /// The optimal value depends on the host computer and hardware configuration and must be determined via testing (e.g. - /// using ). + /// This option allows control over a fundamental trade-off between closed-loop response time and + /// overall bandwidth. A minimal value, which is determined by , will provide the lowest response latency, so long as data + /// can be cleared from hardware memory fast enough to prevent buffering. Larger values will reduce + /// system call frequency, increase overall bandwidth, and may improve processing performance for + /// high-bandwidth data sources. The optimal value depends on the host computer and hardware + /// configuration and must be determined via testing (e.g. using ). /// [Description("Number of bytes read per cycle of the acquisition thread.")] [Category(DeviceFactory.ConfigurationCategory)] @@ -31,26 +61,27 @@ public class StartAcquisition : Combinator /// - /// This value determines the amount of memory pre-allocated for calls to , - /// , and . A larger size will reduce - /// the average amount of dynamic memory allocation system calls but increase the cost of each of those calls. The minimum - /// size of this option is determined by . The effect on real-timer performance is not as - /// large as that of . + /// This value determines the amount of memory pre-allocated for calls to , , and + /// . A larger size will reduce the average amount of + /// dynamic memory allocation system calls but increase the cost of each of those calls. The minimum + /// size of this option is determined by . The effect on + /// real-timer performance is not as large as that of . /// [Description("The number of bytes that are pre-allocated for writing data to hardware.")] [Category(DeviceFactory.ConfigurationCategory)] public int WriteSize { get; set; } = 2048; /// - /// Starts data acquisition and frame distribution on a and returns - /// the sequence of all received objects, grouped by device address. + /// Starts data acquisition and frame distribution on a and returns the + /// sequence of all received objects, grouped by device address. /// /// - /// The sequence of objects on which to start data acquisition - /// and frame distribution. + /// The sequence of objects on which to start data acquisition and frame + /// distribution. /// /// - /// A sequence of objects for each , + /// A sequence of data frames produced by each in the input sequence and /// grouped by device address. /// public override IObservable> Process(IObservable source) From ed0c77ee73bdfe11cea9d2132369c99fa54279df Mon Sep 17 00:00:00 2001 From: jonnew Date: Wed, 4 Sep 2024 18:55:20 -0400 Subject: [PATCH 2/2] Address review comments --- OpenEphys.Onix1/StartAcquisition.cs | 37 +++++++++++++++++------------ 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/OpenEphys.Onix1/StartAcquisition.cs b/OpenEphys.Onix1/StartAcquisition.cs index fd6ee03..17a5f88 100644 --- a/OpenEphys.Onix1/StartAcquisition.cs +++ b/OpenEphys.Onix1/StartAcquisition.cs @@ -14,10 +14,11 @@ namespace OpenEphys.Onix1 /// specification and API describe a general purpose acquisition system architecture and programming /// interface for communication with a host PC. One requirement of ONI is a sequence of events that must /// occur in order to start synchronized data acquisition. performs these - /// required actions on one or more s provided in its input sequence. Once - /// aquisition is started, devices within a particular context will start to produce data in a format - /// called an "ONI frame". The output sequence of this operator is therefore a , where + /// required actions on one or more ContextTasks provided in its input + /// sequence. Once acquisition is started, devices managed by a particular will + /// start to produce data in a format called an ONI frame. The output + /// sequence of this operator is therefore a , where /// /// /// Tkey @@ -28,11 +29,11 @@ namespace OpenEphys.Onix1 /// /// TElement /// - /// Is a ONI frame produced by the device with address Tkey. + /// Is a ONI Frame produced by the device with address Tkey. /// /// /// - /// These pre-sorted frame sequences can be interpreted by downstream data processing operators (e.g. or ) that convert ONI frames, which consist of /// byte arrays with a header and data block, into data types that are are more amenable to processing /// within Bonsai workflows. @@ -46,12 +47,14 @@ public class StartAcquisition : Combinator /// /// This option allows control over a fundamental trade-off between closed-loop response time and - /// overall bandwidth. A minimal value, which is determined by , will provide the lowest response latency, so long as data - /// can be cleared from hardware memory fast enough to prevent buffering. Larger values will reduce - /// system call frequency, increase overall bandwidth, and may improve processing performance for - /// high-bandwidth data sources. The optimal value depends on the host computer and hardware - /// configuration and must be determined via testing (e.g. using ). + /// can be cleared from hardware memory fast enough to prevent buffering. Larger values will both + /// reduce system call frequency and reduce the number of function calls per unit time performed by + /// Bonsai, and therefore, increase available bandwidth. Larger values may improve processing + /// performance for high-bandwidth data sources. The optimal value depends on the host computer and + /// hardware configuration and must be determined via testing (e.g. using ). /// [Description("Number of bytes read per cycle of the acquisition thread.")] [Category(DeviceFactory.ConfigurationCategory)] @@ -61,12 +64,16 @@ public class StartAcquisition : Combinator /// - /// This value determines the amount of memory pre-allocated for calls to , , and - /// . A larger size will reduce the average amount of - /// dynamic memory allocation system calls but increase the cost of each of those calls. The minimum + /// . A larger size will reduce the frequency of + /// dynamic memory allocation system calls but increase the expense of each of those calls. The minimum /// size of this option is determined by . The effect on - /// real-timer performance is not as large as that of . + /// real-time performance is typically not as large as that of + /// because this parameter defines a readily-available pool of memory for the creation of output data + /// frames, but does not determine when they are written to hardware. Data is written to hardware as + /// soon as an output frame has been created. In contrast data is read from hardware whenever more than + /// bytes have accumulated in the input buffer. /// [Description("The number of bytes that are pre-allocated for writing data to hardware.")] [Category(DeviceFactory.ConfigurationCategory)]