Changes from API design (#1)

README.md

@@ -4,7 +4,7 @@
 
 -----
 
-# Welcome to the .NET **nanoFramework** nanoFramework.GiantGecko.Adc repository
+# Welcome to the .NET **nanoFramework** GiantGecko.Adc repository
 
 ## Build status
 
@@ -14,7 +14,6 @@
 
 ## Usage
 
-
 ## Feedback and documentation
 
 For documentation, providing feedback, issues and finding out how to contribute please refer to the [Home repo](https://github.com/nanoframework/Home).

nanoFramework.GiantGecko.Adc/AdcChannel.cs

@@ -30,19 +30,21 @@ public class AdcChannel : AdcChannelBase, IDisposable
 #pragma warning restore IDE0052 // Remove unread private members
 
         /// <summary>
-        /// Initialization configuration for <see cref="AdcChannel"/>.
+        /// The initialized configuration for this <see cref="AdcChannel"/>. Any changes made
+        /// to properties in this object will be ignored: <see cref="AdcChannelConfiguration"/> 
+        /// properties must be defined before calling <see cref="AdcController.OpenChannel(int, AdcChannelConfiguration)"/>.
         /// </summary>
         public AdcChannelConfiguration AdcChannelConfiguration => _adcChannelConfiguration;
 
-        internal AdcChannel(
-            AdcController controller,
-            int channelNumber)
+        /// <summary>
+        /// The last value read in continuous sample mode started via <see cref="AdcController.StartContinuousSampling"/>() or, if averaged sampling continuous mode is currently in use via <see cref="AdcController.StartAveragedContinuousSampling"/>(), the latest averaged value.
+        /// It is an error to read this property if the channel is not currently in continuous mode.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">When reading from this property when the is not currently in continuous mode.</exception>
+        public extern int LastContinuousValue
         {
-            _adcController = controller;
-            _channelNumber = channelNumber;
-            _adcChannelConfiguration = default;
-
-            _syncLock = new object();
+            [MethodImpl(MethodImplOptions.InternalCall)]
+            get;
         }
 
         internal AdcChannel(

nanoFramework.GiantGecko.Adc/AdcChannelConfiguration.cs

@@ -21,9 +21,6 @@ public class AdcChannelConfiguration
         /// <summary>
         /// Peripheral reflex system trigger selection.
         /// </summary>
-        /// <remarks>
-        /// Only applicable if prsEnable is enabled.
-        /// </remarks>
         public PrsSampleTrigger PrsSampleTrigger { get => _prsSampleTrigger; set => _prsSampleTrigger = value; }
 
         /// <summary>
@@ -45,15 +42,12 @@ public class AdcChannelConfiguration
         public SampleResolution SampleResolution { get => _sampleResolution; set => _sampleResolution = value; }
 
         /// <summary>
-        /// Gets or sets the channel mode for the <see cref="AdcChannel"/>.
+        /// Channel mode: single ended or differential.
         /// </summary>
-        /// <value>
-        /// The mode for the <see cref="AdcChannel"/>.
-        /// </value>
         public AdcChannelMode ChannelMode { get => _channelMode; set => _channelMode = value; }
 
         /// <summary>
-        /// Peripheral reflex system trigger enable.
+        /// Returns whether the peripheral reflex system trigger is enable, based on the <see cref="PrsSampleTrigger"/> setting.
         /// </summary>
         public bool IsPrsEnabled => _prsSampleTrigger > PrsSampleTrigger.Disabled;
     }

nanoFramework.GiantGecko.Adc/AdcChannelMode.cs

@@ -14,6 +14,7 @@ public enum AdcChannelMode
         /// Simple value of a particular pin.
         /// </summary>
         SingleEnded = 0,
+
         /// <summary>
         /// Difference between two pins.
         /// </summary>

nanoFramework.GiantGecko.Adc/AdcConfiguration.cs

@@ -6,7 +6,7 @@
 namespace nanoFramework.GiantGecko.Adc
 {
     /// <summary>
-    /// ADC configuration, common for single conversion and scan sequence.
+    /// ADC global configuration, common for single conversion and scan sequence.
     /// </summary>
     public class AdcConfiguration
     {
@@ -21,7 +21,8 @@ public class AdcConfiguration
         /// Oversampling rate select.
         /// </summary>
         /// <remarks>
-        /// To have any effect, oversampling must be enabled for single/scan mode.
+        /// To have any effect, oversampling must be enabled for single/scan mode when the
+        /// channel was opened/configred via <see cref="AdcChannelConfiguration.SampleResolution"/>.
         /// </remarks>
         public OversampleRate OversampleRate { get => _oversampleRate; set => _oversampleRate = value; }
 

nanoFramework.GiantGecko.Adc/AdcController.cs

@@ -13,7 +13,7 @@ namespace nanoFramework.GiantGecko.Adc
     /// Represents an <see cref="AdcController"/> on the system.
     /// </summary>
     /// <remarks>
-    /// This class implements specifics of the Silabs Giant Gecko ADC.
+    /// This class implements specifics of the Silabs Giant Gecko EFM32 ADC.
     /// It's meant to be used instead of the standard System.Adc.
     /// </remarks>
     public class AdcController : AdcControllerBase
@@ -24,7 +24,7 @@ public class AdcController : AdcControllerBase
         private readonly object _syncLock;
         private AdcChannel[] _scanChannels;
         private int _averageCount;
-        private bool _continuousConvertionstarted;
+        private bool _continuousSamplingStarted;
 
         private readonly AdcConfiguration _acdConfiguration;
 
@@ -38,14 +38,7 @@ public override int ChannelCount
         }
 
         /// <inheritdoc/>
-        public override AdcChannelMode ChannelMode
-        {
-            get => throw new PlatformNotSupportedException();
-            set => throw new PlatformNotSupportedException();
-        }
-
-        /// <inheritdoc/>
-        public override SampleResolution SupportedResolutionsInBits
+        public override SampleResolution[] SupportedResolutionsInBits
         {
             get
             {
@@ -59,48 +52,43 @@ public override SampleResolution SupportedResolutionsInBits
         public AdcConfiguration AcdConfiguration => _acdConfiguration;
 
         /// <summary>
-        /// Gets an array with the last conversions from an ongoing scan operation.
+        /// Gets an array with the last samples from an ongoing scan operation.
         /// </summary>
-        /// <exception cref="InvalidOperationException">The ADC is not performing a scan operation. This as to be started with a call to <see cref="StartContinuousConversion"/> or <see cref="StartAveragedContinuousConversion"/>.</exception>
-        /// <remarks>The values are either the last conversion or the average of the last conversion count, if the averaged continuous scan was started with <see cref="StartAveragedContinuousConversion"/>.</remarks>
-        public int[] LastConversion
+        /// <exception cref="InvalidOperationException">The ADC is not performing a scan operation. This has to be started with a call to <see cref="StartContinuousSampling"/> or <see cref="StartAveragedContinuousSampling"/>.</exception>
+        /// <remarks>
+        /// <para>
+        /// The values are either the last sample value (if started with <see cref="StartContinuousSampling"/>) or the average of the last samples count (if the averaged continuous scan was started with <see cref="StartAveragedContinuousSampling"/>). 
+        /// The array is indexed by the position of the channel in the array passed to <see cref="StartContinuousSampling"/> or <see cref="StartAveragedContinuousSampling"/>. For example, if <see cref="StartContinuousSampling"/>([channel_idda, channel_idd3_3]) was called, then <see cref="LastContinuousSamples">[0]</see> would have value for channel_idda and <see cref="LastContinuousSamples"/>[1] would have value for channel_idd3_3. The last continuous sample for a channel may also be retrieved from <see cref="AdcChannel.LastContinuousValue"/>.
+        /// </para>
+        /// <para>
+        /// Please see remarks on <see cref="StartContinuousSampling"/> and <see cref="StartAveragedContinuousSampling"/> for more information on continuous sampling.
+        /// </para>
+        /// </remarks>
+        public int[] LastContinuousSamples
         {
-            [MethodImpl(MethodImplOptions.InternalCall)]
-            get;
-        }
+            get
+            {
+                CheckIfContinuousSamplingIsStarted();
 
-        /// <inheritdoc/>
-        public override SampleResolution ResolutionInBits
-        {
-            get => throw new PlatformNotSupportedException();
-            set => throw new PlatformNotSupportedException();
+                return NativeGetLastContinuousSamples();
+            }
         }
 
+        /// <summary>
+        /// Returns <see langword="true"/> if the ADC is currently running in scan mode, started via <see cref="StartContinuousSampling"/> or <see cref="StartAveragedContinuousSampling"/>. <see langword="false"/> otherwise.
+        /// </summary>
+        public bool IsContinuousSamplingRunning => _continuousSamplingStarted;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="AdcController"/> class. 
+        /// A default <see cref="AdcConfiguration"/> is used.
         /// </summary>
         /// <returns>
         /// The <see cref="AdcController"/> for the system.
         /// </returns>
         /// <exception cref="InvalidOperationException">If the <see cref="AdcController"/> has already been instantiated.</exception>
-        public AdcController()
+        public AdcController() : this(new AdcConfiguration())
         {
-            // check if this device is already opened
-            if (_syncLock == null)
-            {
-                _acdConfiguration = new AdcConfiguration();
-
-                // call native init to allow HAL/PAL inits related with ADC hardware
-                // this is also used to check if the requested ADC actually exists
-                NativeInit();
-
-                _syncLock = new object();
-            }
-            else
-            {
-                // this controller already exists: throw an exception
-                throw new InvalidOperationException();
-            }
         }
 
         /// <summary>
@@ -131,9 +119,7 @@ public AdcController(AdcConfiguration acdInitialization)
         /// <inheritdoc/>   
         public override AdcChannel OpenChannel(int channelNumber)
         {
-            NativeOpenChannel(channelNumber);
-
-            return new AdcChannel(this, channelNumber);
+            return OpenChannel(channelNumber, new AdcChannelConfiguration());
         }
 
         /// <inheritdoc/>
@@ -147,67 +133,69 @@ public override AdcChannel OpenChannel(
         }
 
         /// <summary>
-        /// Starts continuous conversions on the specified channels.
+        /// Starts continuous sampling on the specified channels.
         /// </summary>
-        /// <param name="channels">Array of channels to scan performing continuous conversions.</param>
+        /// <param name="channels">Array of channels to scan performing continuous sampling.</param>
         /// <returns><see langword="true"/> if the operation was successful. <see langword="false"/> otherwise.</returns>
-        /// <exception cref="InvalidOperationException">If a previous continuous conversion operation has been started previously without being stopped.</exception>
-        public bool StartContinuousConversion(AdcChannel[] channels)
+        /// <exception cref="InvalidOperationException">If a previous continuous sampling operation has been started previously without being stopped.</exception>
+        public bool StartContinuousSampling(AdcChannel[] channels)
         {
-            if (_continuousConvertionstarted)
-            {
-                throw new InvalidOperationException();
-            }
+            CheckIfContinuousSamplingIsStarted();
 
             _scanChannels = channels;
             // set average count to 1 for single sample
             _averageCount = 1;
 
             // update flag
-            _continuousConvertionstarted = NativeStartContinuousConversion();
+            _continuousSamplingStarted = NativeStartContinuousConversion();
 
-            return _continuousConvertionstarted;
+            return _continuousSamplingStarted;
         }
 
         /// <summary>
-        /// Starts continuous conversions and average the digital representation of <paramref name="count"/> analog values read from the ADC.
+        /// Starts continuous sampling and average the digital representation of <paramref name="count"/> analog values read from the ADC.
         /// </summary>
-        /// <param name="channels">Array of channels to scan performing continuous conversions.</param>
+        /// <remarks>
+        /// In this mode, the last count samples are averaged and made available in LastScanConversion[0].
+        /// </remarks>
+        /// <param name="channels">Array of channels to scan performing continuous sampling.</param>
         /// <param name="count">Number of samples to take for averaging.</param>
-        /// <returns></returns>
+        /// <returns><see langword="true"/> if the continuous sampling was successfully started. <see langword="false"/> otherwise.</returns>
         /// <exception cref="InvalidOperationException"></exception>
-        public bool StartAveragedContinuousConversion(AdcChannel[] channels, int count)
+        public bool StartAveragedContinuousSampling(AdcChannel[] channels, int count)
         {
-            if (_continuousConvertionstarted)
-            {
-                throw new InvalidOperationException();
-            }
+            CheckIfContinuousSamplingIsStarted();
 
             _scanChannels = channels;
             _averageCount = count;
 
             // update flag
-            _continuousConvertionstarted = NativeStartContinuousConversion();
+            _continuousSamplingStarted = NativeStartContinuousConversion();
 
-            return _continuousConvertionstarted;
+            return _continuousSamplingStarted;
         }
 
         /// <summary>
-        /// Stops an ongoing continuous conversion scan operation.
+        /// Stops an ongoing continuous sampling operation.
         /// </summary>
-        /// <exception cref="InvalidOperationException">If there is no ongoing continuous conversion operation.</exception>
-        public void StoptContinuousConversion()
+        /// <exception cref="InvalidOperationException">If there is no ongoing continuous sampling operation.</exception>
+        public void StopContinuousSampling()
         {
-            if (!_continuousConvertionstarted)
-            {
-                throw new InvalidOperationException();
-            }
+            CheckIfContinuousSamplingIsStarted(true);
 
             NativeStoptContinuousConversion();
 
             // update flag
-            _continuousConvertionstarted = false;
+            _continuousSamplingStarted = false;
+
+        }
 
+        private void CheckIfContinuousSamplingIsStarted(bool invertCheck = false)
+        {
+            if (invertCheck ? !_continuousSamplingStarted : _continuousSamplingStarted)
+            {
+                throw new InvalidOperationException();
+            }
         }
 
         #region Native Calls
@@ -225,14 +213,20 @@ public void StoptContinuousConversion()
         private extern bool NativeIsChannelModeSupported(int mode);
 
         [MethodImpl(MethodImplOptions.InternalCall)]
-        private extern SampleResolution NativeGetSupportedResolutionsInBits();
+        private extern SampleResolution[] NativeGetSupportedResolutionsInBits();
 
         [MethodImpl(MethodImplOptions.InternalCall)]
         private extern bool NativeStartContinuousConversion();
 
         [MethodImpl(MethodImplOptions.InternalCall)]
         private extern bool NativeStoptContinuousConversion();
 
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        private extern int[] NativeGetLastContinuousSamples();
+
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        private extern int NativeGetLastScanSampleForChannel(int channel);
+
         #endregion
     }
 }

nanoFramework.GiantGecko.Adc/AdcControllerBase.cs

@@ -29,6 +29,7 @@ public abstract class AdcControllerBase
         /// <param name="channelNumber">
         /// The channel to connect to.
         /// </param>
+        /// <param name="configuration">Initial configuration for ADC channel.</param>
         /// <returns>
         /// The ADC channel.
         /// </returns>
@@ -42,30 +43,12 @@ public abstract class AdcControllerBase
         /// </value>
         public abstract int ChannelCount { get; }
 
-        /// <summary>
-        /// Gets or sets the channel mode for the <see cref="AdcController"/>.
-        /// </summary>
-        /// <value>
-        /// The mode for the <see cref="AdcChannel"/>.
-        /// </value>
-        /// <exception cref="PlatformNotSupportedException">If the platform doesn't have this configuration available.</exception>
-        public abstract AdcChannelMode ChannelMode { get; set; }
-
         /// <summary>
         /// Gets the resolution(s) of the controller as number of bits it has. For example, if we have a 10-bit ADC, that means it can detect 1024 (2^10) discrete levels.
         /// </summary>
         /// <value>
-        /// The number of bits the <see cref="AdcController"/> has support for.
-        /// </value>
-        public abstract SampleResolution SupportedResolutionsInBits { get; }
-
-        /// <summary>
-        /// Gets or sets the resolution of the controller as number of bits it has.
-        /// </summary>
-        /// <value>
-        /// The number of bits the <see cref="AdcController"/> will use to perform conversions.
+        /// Array with the resolution(s) that the ADC has support for.
         /// </value>
-        /// <exception cref="InvalidOperationException">If trying to change the resolution when a continuous conversion operation has been started.</exception>
-        public abstract SampleResolution ResolutionInBits { get; set; }
+        public abstract SampleResolution[] SupportedResolutionsInBits { get; }
     }
 }