Merge pull request #442 from open-ephys/issue-384-rhs2116

Add support for stimulus trigger events from headstage-rhs2116

Author: jonnew

OpenEphys.Onix1/ConfigureRhs2116.cs

@@ -187,6 +187,10 @@ public override IObservable<ContextTask> Process(IObservable<ContextTask> source
                         device.WriteRegister(Rhs2116.BW1, regs[3] << 6 | regs[2]);
                         device.WriteRegister(Rhs2116.FASTSETTLESAMPLES, Rhs2116Config.AnalogHighCutoffToFastSettleSamples[newValue]);
                     }),
+                    respectExternalActiveStim.SubscribeSafe(observer, newValue =>
+                    {
+                        device.WriteRegister(Rhs2116.RESPECTSTIMACTIVE, newValue ? 1u : 0u);
+                    }),
                     DeviceManager.RegisterDevice(deviceName, device, DeviceType)
                 );
             });

OpenEphys.Onix1/ConfigureRhs2116Pair.cs

@@ -149,6 +149,10 @@ static void ConfigureChip(DeviceContext device, bool enable, Rhs2116DspCutoff ds
                     // consistency
                     device.WriteRegister(Rhs2116.FORMAT, format);
                     device.WriteRegister(Rhs2116.ENABLE, enable ? 1u : 0);
+
+                    // Force each device to respect each other's stimulation state since they are being
+                    // treated, de-facto, as a single chip.
+                    device.WriteRegister(Rhs2116.RESPECTSTIMACTIVE, 1u);
                 }
 
                 ConfigureChip(rhs2116A, enable, dspCutoff);

OpenEphys.Onix1/ConfigureRhs2116Trigger.cs

@@ -10,17 +10,20 @@
 namespace OpenEphys.Onix1
 {
     /// <summary>
-    /// Configures an ONIX RHS 2116 Trigger device.
+    /// Configures an Rhs2116 trigger device.
     /// </summary>
     /// <remarks>
-    /// The RHS2116 Trigger device generates triggers for Intan RHS2116 bioamplifier and stimulator chip(s)
-    /// either from a remote source via external SYNC pin or locally via GPIO or TRIGGER register. This 
-    /// device can be used to synchronize stimulus application and recovery across chips.
+    /// The Rhs2116 Trigger device generates triggers for Intan Rhs2116 bioamplifier and stimulator chip(s)
+    /// either from a remote source via external SYNC pin or locally via GPIO or TRIGGER register. This device
+    /// can be used to synchronize stimulus application and recovery across chips. This configuration operator
+    /// can be linked to a data IO operator, such as <see cref="Rhs2116TriggerData"/>, using a shared
+    /// <c>DeviceName</c>.
     /// </remarks>
     [Editor("OpenEphys.Onix1.Design.Rhs2116StimulusSequenceEditor, OpenEphys.Onix1.Design", typeof(ComponentEditor))]
     public class ConfigureRhs2116Trigger : SingleDeviceFactory
     {
         readonly BehaviorSubject<Rhs2116StimulusSequencePair> stimulusSequence = new(new Rhs2116StimulusSequencePair());
+        readonly BehaviorSubject<bool> triggerArmed = new(true);
 
         /// <summary>
         /// Initializes a new instance of the <see cref="ConfigureRhs2116Trigger"/> class.
@@ -30,6 +33,19 @@ public ConfigureRhs2116Trigger()
         {
         }
 
+        /// <summary>
+        /// Gets or sets the device enable state.
+        /// </summary>
+        /// <remarks>
+        /// If set to true, a <see cref="Rhs2116TriggerData"/> instance that is linked to this configuration
+        /// will produce data. If set to false, it will not produce data. Note that this does not affect the
+        /// ability of the device to trigger stimuli, but only affects if trigger event information is
+        /// streamed back from the device. To disable the trigger see the <see cref="Armed"/> property.
+        /// </remarks>
+        [Category(ConfigurationCategory)]
+        [Description("Specifies whether the stimulus trigger device will stream stimulus delivery information.")]
+        public bool Enable { get; set; } = true;
+
         /// <summary>
         /// Gets or sets the trigger source.
         /// </summary>
@@ -52,6 +68,21 @@ public ConfigureRhs2116Trigger()
         [Description("Defines the channel configuration")]
         public Rhs2116ProbeGroup ProbeGroup { get; set; } = new();
 
+        /// <summary>
+        /// Gets or sets if trigger is armed.
+        /// </summary>
+        /// <remarks>
+        /// If true, this device will respect triggers from the selected <see cref="TriggerSource"/>.
+        /// Otherwise, triggers will be ignored. 
+        /// </remarks>
+        [Category(AcquisitionCategory)]
+        [Description("If true, respect triggers. Otherwise, triggers will not be applied.")]
+        public bool Armed
+        {
+            get => triggerArmed.Value;
+            set => triggerArmed.OnNext(value);
+        }
+
         /// <summary>
         /// Gets or sets a string defining the <see cref="ProbeGroup"/> in Base64.
         /// </summary>
@@ -88,7 +119,7 @@ public Rhs2116StimulusSequencePair StimulusSequence
         }
 
         /// <summary>
-        /// Configures an RHS2116 Trigger device.
+        /// Configures an Rhs2116 Trigger device.
         /// </summary>
         /// <remarks>
         /// This will schedule configuration actions to be applied by a <see cref="StartAcquisition"/> node
@@ -97,10 +128,11 @@ public Rhs2116StimulusSequencePair StimulusSequence
         /// <param name="source">A sequence of <see cref="ContextTask"/> that holds all configuration actions.</param>
         /// <returns>
         /// The original sequence with the side effect of an additional configuration action to configure
-        /// aN RHS2116 Trigger device.
+        /// aN Rhs2116 Trigger device.
         /// </returns>
         public override IObservable<ContextTask> Process(IObservable<ContextTask> source)
         {
+            var enable = Enable;
             var triggerSource = TriggerSource;
             var deviceName = DeviceName;
             var deviceAddress = DeviceAddress;
@@ -113,6 +145,7 @@ public override IObservable<ContextTask> Process(IObservable<ContextTask> source
                 var rhs2116B = context.GetDeviceContext(rhs2116BAddress, typeof(Rhs2116));
 
                 var device = context.GetDeviceContext(deviceAddress, DeviceType);
+                device.WriteRegister(Rhs2116Trigger.ENABLE, enable ? 1u : 0u);
                 device.WriteRegister(Rhs2116Trigger.TRIGGERSOURCE, (uint)triggerSource);
 
                 static void WriteStimulusSequence(DeviceContext device, Rhs2116StimulusSequence sequence)
@@ -164,6 +197,10 @@ static void WriteStimulusSequence(DeviceContext device, Rhs2116StimulusSequence
                         WriteStimulusSequence(rhs2116A, newValue.StimulusSequenceA);
                         WriteStimulusSequence(rhs2116B, newValue.StimulusSequenceB);
                     }),
+                    triggerArmed.SubscribeSafe(observer, newValue =>
+                    {
+                        device.WriteRegister(Rhs2116Trigger.TRIGGERARMED, newValue ? 1u : 0u);
+                    }),
                     DeviceManager.RegisterDevice(deviceName, device, DeviceType));
             });
         }
@@ -174,9 +211,11 @@ static class Rhs2116Trigger
         public const int ID = 32;
 
         // managed registers
-        public const uint ENABLE = 0; // Writes and reads to ENABLE are ignored without error
+        public const uint ENABLE = 0; // Enable or disable the trigger event datastream
         public const uint TRIGGERSOURCE = 1; // The LSB is used to determine the trigger source
         public const uint TRIGGER = 2; // Writing 0x1 to this register will trigger a stimulation sequence if the TRIGGERSOURCE is set to 0.
+        public const uint TRIGGERARMED = 3; // 0x0: Ignore all trigger inputs regardless of TRIGGERSOURCE.
+                                            // 0x1: Respect the trigger input specified by TRIGGERSOURCE
 
         internal class NameConverter : DeviceNameConverter
         {

OpenEphys.Onix1/Rhs2116Data.cs

@@ -50,6 +50,7 @@ public unsafe override IObservable<Rhs2116DataFrame> Generate()
                     var device = deviceInfo.GetDeviceContext(typeof(Rhs2116));
                     var amplifierBuffer = new short[Rhs2116.AmplifierChannelCount * bufferSize];
                     var dcBuffer = new short[Rhs2116.AmplifierChannelCount * bufferSize];
+                    var recovery = new ushort[bufferSize];
                     var hubClockBuffer = new ulong[bufferSize];
                     var clockBuffer = new ulong[bufferSize];
 
@@ -61,12 +62,14 @@ public unsafe override IObservable<Rhs2116DataFrame> Generate()
                             Marshal.Copy(new IntPtr(payload->DCData), dcBuffer, sampleIndex * Rhs2116.AmplifierChannelCount, Rhs2116.AmplifierChannelCount);
                             hubClockBuffer[sampleIndex] = payload->HubClock;
                             clockBuffer[sampleIndex] = frame.Clock;
+                            recovery[sampleIndex] = payload->Recovery;
                             if (++sampleIndex >= bufferSize)
                             {
                                 var amplifierData = BufferHelper.CopyTranspose(amplifierBuffer, bufferSize, Rhs2116.AmplifierChannelCount, Depth.U16);
                                 var dcData = BufferHelper.CopyTranspose(dcBuffer, bufferSize, Rhs2116.AmplifierChannelCount, Depth.U16);
-                                observer.OnNext(new Rhs2116DataFrame(clockBuffer, hubClockBuffer, amplifierData, dcData));
+                                observer.OnNext(new Rhs2116DataFrame(clockBuffer, hubClockBuffer, amplifierData, dcData, recovery));
                                 hubClockBuffer = new ulong[bufferSize];
+                                recovery = new ushort[bufferSize];
                                 clockBuffer = new ulong[bufferSize];
                                 sampleIndex = 0;
                             }

OpenEphys.Onix1/Rhs2116DataFrame.cs

@@ -1,10 +1,14 @@
-using System.Runtime.InteropServices;
+using System;
+using System.Collections;
+using System.Collections.Specialized;
+using System.Numerics;
+using System.Runtime.InteropServices;
 using OpenCV.Net;
 
 namespace OpenEphys.Onix1
 {
     /// <summary>
-    /// Buffered data from one or more Rhs2116 devices.
+    /// Buffered data from a Rhs2116 device.
     /// </summary>
     public class Rhs2116DataFrame : BufferedDataFrame
     {
@@ -15,19 +19,21 @@ public class Rhs2116DataFrame : BufferedDataFrame
         /// <param name="hubClock">An array of hub clock counter values.</param>
         /// <param name="amplifierData">An array of multi-channel amplifier data.</param>
         /// <param name="dcData">An array of multi-channel DC data.</param>
-        public Rhs2116DataFrame(ulong[] clock, ulong[] hubClock, Mat amplifierData, Mat dcData)
+        /// <param name="recoveryMask">An array of stimulus artifact recovery mask values.</param>
+        public Rhs2116DataFrame(ulong[] clock, ulong[] hubClock, Mat amplifierData, Mat dcData, ushort[] recoveryMask)
             : base(clock, hubClock)
         {
             AmplifierData = amplifierData;
             DCData = dcData;
+            RecoveryMask = recoveryMask;
         }
 
         /// <summary>
         /// Gets the high-gain electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// Electrophysiology samples are organized in MxN matrix with M rows representing electrophysiology
-        /// channel number and N columns representing sample index. Each column is a M-channel vector of ADC
+        /// Electrophysiology samples are organized in a 16xN matrix with 16 rows representing electrophysiology
+        /// channel and N columns representing sample index. Each column is a 16-channel vector of ADC
         /// samples whose acquisition time is indicated by the corresponding elements in <see
         /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is an 16-bit,
         /// offset binary value encoded as a <see cref="ushort"/>. The following equation can be used to
@@ -42,8 +48,8 @@ public Rhs2116DataFrame(ulong[] clock, ulong[] hubClock, Mat amplifierData, Mat
         /// Gets the DC-coupled, low-gain amplifier data array for monitoring stimulation waveforms.
         /// </summary>
         /// <remarks>
-        /// DC-coupled samples are organized in MxN matrix with M rows representing electrophysiology
-        /// channel number and N columns representing sample index. Each column is a M-channel vector of ADC
+        /// DC-coupled samples are organized in 16xN matrix with 16 rows representing electrophysiology
+        /// channel and N columns representing sample index. Each column is a 16-channel vector of ADC
         /// samples whose acquisition time is indicated by the corresponding elements in <see
         /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is an 10-bit,
         /// offset binary value encoded as a <see cref="ushort"/>. The following equation can be used to
@@ -53,6 +59,20 @@ public Rhs2116DataFrame(ulong[] clock, ulong[] hubClock, Mat amplifierData, Mat
         /// </code>
         /// </remarks>
         public Mat DCData { get; }
+
+        /// <summary>
+        /// Gets the stimulus artifact recovery mask array.
+        /// </summary>
+        /// <remarks>
+        /// During and following stimulus pulses, electrophysiology amplifiers can enter an artifact recovery
+        /// mode which discharges the electrode and applies an aggressive high-pass filter to prevent
+        /// amplifier saturation (see <see cref="ConfigureRhs2116.AnalogLowCutoffRecovery"/>). This 1xN vector
+        /// provides a per-sample bit mask indicating if artifact recovery mode is active on each of the 16
+        /// electrophysiology channels. The bit position in each value indicates the channel number and the
+        /// logical state indicates if recovery is active. For instance a value of 0x0011 would indicate that
+        /// channels 0 and 4 were in artifact recovery mode and all other channels were in normal operation.
+        /// </remarks>
+        public ushort[] RecoveryMask { get; }
     }
 
     [StructLayout(LayoutKind.Sequential, Pack = 1)]
@@ -61,6 +81,6 @@ unsafe struct Rhs2116Payload
         public ulong HubClock;
         public fixed ushort AmplifierData[Rhs2116.AmplifierChannelCount];
         public fixed ushort DCData[Rhs2116.AmplifierChannelCount];
-        public short Pad;
+        public ushort Recovery;
     }
 }

OpenEphys.Onix1/Rhs2116PairData.cs

@@ -10,15 +10,15 @@
 namespace OpenEphys.Onix1
 {
     /// <summary>
-    /// Produces a sequence of <see cref="Rhs2116DataFrame"/> objects from a synchronized pair of Intan
+    /// Produces a sequence of <see cref="Rhs2116PairDataFrame"/> objects from a synchronized pair of Intan
     /// Rhs2116 bidirectional bioacquisition chips.
     /// chips.
     /// </summary>
     /// <remarks>
     /// This data IO operator must be linked to an appropriate configuration, such as a <see
     /// cref="ConfigureRhs2116Pair"/>, using a shared <c>DeviceName</c>.
     /// </remarks>
-    public class Rhs2116PairData : Source<Rhs2116DataFrame>
+    public class Rhs2116PairData : Source<Rhs2116PairDataFrame>
     {
         /// <inheritdoc cref = "SingleDeviceFactory.DeviceName"/>
         [TypeConverter(typeof(Rhs2116Pair.NameConverter))]
@@ -31,27 +31,28 @@ public class Rhs2116PairData : Source<Rhs2116DataFrame>
         /// This property determines the number of samples that are collected from each of the 32
         /// electrophysiology channels before data is propagated. For instance, if this value is set to 30,
         /// then 32x30 samples, along with 30 corresponding clock values, will be collected and packed into
-        /// each <see cref="Rhs2116DataFrame"/>. Because channels are sampled at ~30 kHz, this is equivalent
+        /// each <see cref="Rhs2116PairDataFrame"/>. Because channels are sampled at ~30 kHz, this is equivalent
         /// to ~1 millisecond of data from each channel.
         /// </remarks>
         public int BufferSize { get; set; } = 30;
 
         /// <summary>
-        /// Generates a sequence of <see cref="Rhs2116DataFrame"/>s.
+        /// Generates a sequence of <see cref="Rhs2116PairDataFrame"/>s.
         /// </summary>
-        /// <returns>A sequence of <see cref="Rhs2116DataFrame"/>s.</returns>
-        public unsafe override IObservable<Rhs2116DataFrame> Generate()
+        /// <returns>A sequence of <see cref="Rhs2116PairDataFrame"/>s.</returns>
+        public unsafe override IObservable<Rhs2116PairDataFrame> Generate()
         {
             var bufferSize = BufferSize;
             return DeviceManager.GetDevice(DeviceName).SelectMany(
-                deviceInfo => Observable.Create<Rhs2116DataFrame>(observer =>
+                deviceInfo => Observable.Create<Rhs2116PairDataFrame>(observer =>
                 {
                     var sampleIndex = 0;
                     var dualInfo = (Rhs2116PairDeviceInfo)deviceInfo;
                     var rhs2116A = dualInfo.Rhs2116A;
                     var rhs2116B = dualInfo.Rhs2116B;
                     var amplifierBuffer = new short[Rhs2116Pair.TotalChannels * bufferSize];
                     var dcBuffer = new short[Rhs2116Pair.TotalChannels * bufferSize];
+                    var recovery = new uint[bufferSize];
                     var hubClockBuffer = new ulong[bufferSize];
                     var clockBuffer = new ulong[bufferSize];
 
@@ -64,24 +65,27 @@ public unsafe override IObservable<Rhs2116DataFrame> Generate()
                                 var payload = (Rhs2116Payload*)frame.Data.ToPointer();
                                 Marshal.Copy(new IntPtr(payload->AmplifierData), amplifierBuffer, offset, Rhs2116.AmplifierChannelCount);
                                 Marshal.Copy(new IntPtr(payload->DCData), dcBuffer, offset, Rhs2116.AmplifierChannelCount);
+                                recovery[sampleIndex] |= payload->Recovery;
 
                                 if (++sampleIndex >= bufferSize)
                                 {
                                     var amplifierData = BufferHelper.CopyTranspose(amplifierBuffer, bufferSize, Rhs2116Pair.TotalChannels, Depth.U16);
                                     var dcData = BufferHelper.CopyTranspose(dcBuffer, bufferSize, Rhs2116Pair.TotalChannels, Depth.U16);
-                                    observer.OnNext(new Rhs2116DataFrame(clockBuffer, hubClockBuffer, amplifierData, dcData));
+                                    observer.OnNext(new Rhs2116PairDataFrame(clockBuffer, hubClockBuffer, amplifierData, dcData, recovery));
                                     hubClockBuffer = new ulong[bufferSize];
+                                    recovery = new uint[bufferSize];
                                     clockBuffer = new ulong[bufferSize];
                                     sampleIndex = 0;
                                 }
 
-                            } else
+                            } else // Chip B
                             {
                                 var offset = sampleIndex * Rhs2116Pair.TotalChannels + Rhs2116Pair.ChannelsPerChip;
                                 var payload = (Rhs2116Payload*)frame.Data.ToPointer();
                                 Marshal.Copy(new IntPtr(payload->AmplifierData), amplifierBuffer, offset, Rhs2116.AmplifierChannelCount);
                                 Marshal.Copy(new IntPtr(payload->DCData), dcBuffer, offset, Rhs2116.AmplifierChannelCount);
                                 hubClockBuffer[sampleIndex] = payload->HubClock;
+                                recovery[sampleIndex] |= (uint)payload->Recovery << 16;
                                 clockBuffer[sampleIndex] = frame.Clock;
                             }