Adding Mcp3xxx (#48)

Author: Ellerbach

devices/Mcp3xxx/Mcp3001.cs

@@ -0,0 +1,29 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3001 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3001 : Mcp3Base
+    {
+        /// <summary>
+        /// Constructs Mcp3008 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3001(SpiDevice spiDevice)
+            : base(spiDevice)
+        {
+        }
+
+        /// <summary>
+        /// Reads a 10-bit (0..1023) value from the device
+        /// </summary>
+        /// <returns>10-bit value corresponding to relative voltage level on specified device channel</returns>
+        // Read the data from the device. As the 10 bits of data start at bit 3 then read 13 bits and shift right by 3.
+        public int Read() => ReadInternal(adcRequest: 0, adcResolutionBits: 10 + 3, delayBits: 0) >> 3;
+    }
+}

devices/Mcp3xxx/Mcp3002.cs

@@ -0,0 +1,22 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3002 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3002 : Mcp3xxx
+    {
+        /// <summary>
+        /// Constructs Mcp3002 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3002(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 2, adcResolutionBits: 10)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp3004.cs

@@ -0,0 +1,22 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3004 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3004 : Mcp3xxx
+    {
+        /// <summary>
+        /// Constructs Mcp3004 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3004(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 4, adcResolutionBits: 10)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp3008.cs

@@ -0,0 +1,22 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3008 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3008 : Mcp3xxx
+    {
+        /// <summary>
+        /// Constructs Mcp3008 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3008(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 8, adcResolutionBits: 10)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp3201.cs

@@ -0,0 +1,29 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP32001 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3201 : Mcp3Base
+    {
+        /// <summary>
+        /// Constructs Mcp3201 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3201(SpiDevice spiDevice)
+            : base(spiDevice)
+        {
+        }
+
+        /// <summary>
+        /// Reads a 12-bit (0..4096) value from the device
+        /// </summary>
+        /// <returns>12-bit value corresponding to relative voltage level on specified device channel</returns>
+        // Read the data from the device. As the 12 bits of data start at bit 1 then read 13 bits and shift right by 1.
+        public int Read() => ReadInternal(adcRequest: 0, adcResolutionBits: 12 + 1, delayBits: 0) >> 1;
+    }
+}

devices/Mcp3xxx/Mcp3202.cs

@@ -0,0 +1,22 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3202 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3202 : Mcp3xxx
+    {
+        /// <summary>
+        /// Constructs Mcp3202 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3202(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 2, adcResolutionBits: 12)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp3204.cs

@@ -0,0 +1,22 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3204 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3204 : Mcp3xxx
+    {
+        /// <summary>
+        /// Constructs Mcp3204 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3204(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 4, adcResolutionBits: 12)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp3208.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3208 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3208 : Mcp3xxx
+    {
+        /// <summary>
+        /// Constructs Mcp3208 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3208(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 8, adcResolutionBits: 12)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp3301.cs

@@ -0,0 +1,34 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3301 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3301 : Mcp3Base
+    {
+        /// <summary>
+        /// Constructs Mcp3301 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3301(SpiDevice spiDevice)
+            : base(spiDevice)
+        {
+        }
+
+        /// <summary>
+        /// Reads a 13 bit signed value from the device using differential inputs
+        /// </summary>
+        /// <returns>A 13 bit signed value corresponding to relative voltage level on specified device channels</returns>
+        public int ReadDifferential()
+        {
+            int signedResult = ReadInternal(adcRequest: 0, adcResolutionBits: 13, delayBits: 0);
+
+            // convert 13 bit signed to 32 bit signed
+            return Mcp33xx.SignExtend(signedValue: signedResult, signingBit: 12);
+        }
+    }
+}

devices/Mcp3xxx/Mcp3302.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3302 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3302 : Mcp33xx
+    {
+        /// <summary>
+        /// Constructs Mcp3302 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3302(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 4, adcResolutionBits: 13)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp3304.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP3304 Analog to Digital Converter (ADC)
+    /// </summary>
+    public class Mcp3304 : Mcp33xx
+    {
+        /// <summary>
+        /// Constructs Mcp3304 instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        public Mcp3304(SpiDevice spiDevice)
+            : base(spiDevice, channelCount: 8, adcResolutionBits: 13)
+        {
+        }
+    }
+}

devices/Mcp3xxx/Mcp33xx.cs

@@ -0,0 +1,83 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Device.Spi;
+
+namespace Iot.Device.Adc
+{
+    /// <summary>
+    /// MCP33XX family of Analog to Digital Converters
+    /// </summary>
+    public abstract class Mcp33xx : Mcp3xxx
+    {
+        /// <summary>
+        /// Constructs Mcp33xx instance
+        /// </summary>
+        /// <param name="spiDevice">Device used for SPI communication</param>
+        /// <param name="channelCount">Value representing the number of single ended input channels on the device.</param>
+        /// <param name="adcResolutionBits">The number of bits of resolution for the ADC.</param>
+        public Mcp33xx(SpiDevice spiDevice, byte channelCount, byte adcResolutionBits)
+            : base(spiDevice, channelCount, adcResolutionBits)
+        {
+        }
+
+        /// <summary>
+        /// Convert a signed value with a sign bit at a particular location to an int.
+        /// </summary>
+        /// <param name="signedValue">Signed value with a sign bit at a particular location</param>
+        /// <param name="signingBit">Bit number that contains the sign bit</param>
+        /// <returns>A value corresponding to the signed value sign extended into an int</returns>
+        // if the sign bit is set then extend the signing bit to create a signed integer
+        public static int SignExtend(int signedValue, int signingBit) => (signedValue >> signingBit) == 0 ? signedValue : signedValue - (2 << signingBit);
+
+        /// <summary>
+        /// Reads a  value from the device using pseudo-differential inputs
+        /// </summary>
+        /// <param name="valueChannel">Channel which represents the signal (valid values: 0 to channelcount - 1).</param>
+        /// <param name="referenceChannel">Channel which represents the signal ground (valid values: 0 to channelcount - 1).</param>
+        /// <returns>A value corresponding to relative voltage level on specified device channels</returns>
+        public override int ReadPseudoDifferential(int valueChannel, int referenceChannel) => throw new NotSupportedException($"Mcp33xx device does not support {nameof(ReadPseudoDifferential)}.");
+
+        /// <summary>
+        /// Reads a 13 bit signed value from the device using differential inputs
+        /// </summary>
+        /// <remarks>
+        /// The value that is read respresents the difference between the voltage on the value channel and the voltage on the reference channel (valueChannel Reading - referenceChannel Reading).
+        /// If the valueChannel and the referenceChannel are part of the same channel pairing then the ADC converter will internally subtract the two values. If not then the subtraction is
+        /// performed in software which may mean that errors are introduced with rapidly changing signals.
+        /// </remarks>
+        /// <param name="valueChannel">Channel which represents the signal driving the value in a positive direction (valid values: 0 to channelcount - 1).</param>
+        /// <param name="referenceChannel">Channel which represents the signal driving the value in a negative direction (valid values: 0 to channelcount - 1).</param>
+        /// <returns>A 13 bit signed value corresponding to relative voltage level on specified device channels</returns>
+        public override int ReadDifferential(int valueChannel, int referenceChannel)
+        {
+            int retval;
+
+            CheckChannelRange(valueChannel, ChannelCount);
+            CheckChannelRange(referenceChannel, ChannelCount);
+
+            if (valueChannel == referenceChannel)
+            {
+                throw new ArgumentException(nameof(valueChannel), $"ADC differential channels must be different. {nameof(valueChannel)}: {valueChannel}; {nameof(referenceChannel)}: {referenceChannel}.");
+            }
+
+            // check if it is possible to use hardware differential because both input channels are in the same differential channel pairing
+            if (valueChannel / 2 == referenceChannel / 2)
+            {
+                // read a value from the ADC where the channel is the channel pairing
+                retval = ReadInternal(channel: valueChannel / 2, valueChannel > referenceChannel ? InputType.InvertedDifferential : InputType.Differential, adcResolutionBits: 13);
+
+                // convert 13 bit signed to 32 bit signed
+                retval = SignExtend(signedValue: retval, signingBit: 12);
+            }
+            else // otherwise just subtract two readings
+            {
+                retval = ReadInternal(valueChannel, InputType.SingleEnded, adcResolutionBits: 12) -
+                         ReadInternal(referenceChannel, InputType.SingleEnded, adcResolutionBits: 12);
+            }
+
+            return retval;
+        }
+    }
+}