adc: Implement ADC driver interface for MCP3008 over SPI. Includes do…

…cumentation page for the driver, and inclusion of driver registration code for RP2040-based boards.

Documentation/applications/examples/adc/index.rst

@@ -1,3 +1,5 @@
+.. _adc-example:
+
 =====================
 ``adc`` Read from ADC
 =====================

Documentation/components/drivers/character/analog/adc/mcp3008/index.rst

@@ -0,0 +1,119 @@
+=======
+MCP3008
+=======
+
+Contributed by Matteo Golin
+
+The MCP3008 is a 10-bit, 8-channel ADC made by Microchip which operates over
+SPI.
+
+There is the option to operate in single-ended mode, which measures the voltage
+on each channel individually, or differential mode which measures the voltage
+difference between pairs of channels.
+
+When operating in differential mode, the channel numbers below correspond to the
+listed differential pairs:
+
+.. list-table:: Differential pair channel numbers
+   :widths: auto
+
+   * - Channel number
+     - Sources
+   * - 0                 
+     - CH0+, CH1- 
+   * - 1                 
+     - CH0-, CH1+ 
+   * - 2                 
+     - CH2+, CH3- 
+   * - 3                 
+     - CH2-, CH3+ 
+   * - 4                 
+     - CH4+, CH5- 
+   * - 5                 
+     - CH4-, CH5+ 
+   * - 6                 
+     - CH6+, CH7- 
+   * - 7                 
+     - CH6-, CH7+ 
+
+Driver Interface
+---------------------
+
+To register the MCP3008 device driver as a standard NuttX analog device on your
+board, you can use something similar to the below code for the RP2040.
+
+.. code-block:: c
+
+  #include <nuttx/analog/mcp3008.h>
+  #include <nuttx/analog/adc.h>
+
+  /* Register MCP3008 ADC */
+
+  struct spi_dev_s *spi = rp2040_spibus_initialize(0);
+  if (spi == NULL)
+    {
+      syslog(LOG_ERR, "Failed to initialize SPI bus 0\n");
+    }
+
+  struct adc_dev_s *mcp3008 = mcp3008_initialize(spi);
+  if (mcp3008 == NULL)
+  {
+    syslog(LOG_ERR, "Failed to initialize MCP3008\n");
+  }
+
+  int ret = adc_register("/dev/adc1", mcp3008);
+  if (ret < 0)
+  {
+    syslog(LOG_ERR, "Failed to register MCP3008 device driver: %d\n", ret);
+  }
+
+Once registered, this driver can be interacted with using the ADC example
+(:ref:`adc-example`). Be sure to enable the software trigger, since the MCP3008
+driver does not support hardware triggers (interrupts). You can also change the
+number of samples per group up to 8 for all 8 channels of the ADC.
+
+You may need to increase the `CONFIG_ADC_FIFOSIZE` value to something larger
+than 8 in order to be able to store all the ADC measurements after a measurement
+trigger (i.e 9).
+
+You can configure the driver in differential mode by default using the
+`CONFIG_ADC_MCP3008_DIFFERENTIAL` configuration option.
+
+You can also configure the speed of SPI communications to the MCP3008 using the
+`CONFIG_ADC_MCP3008_SPI_FREQUENCY` configuration option. This speed should be
+selected based on the supply voltage used to power the MCP3008:
+
+.. list-table:: SPI frequencies for supply voltage
+   :widths: auto
+   :header-rows: 1
+
+   * - Supply Voltage
+     - Frequency
+   * - VDD >= 4V
+     - 3.6MHz
+   * - VDD >= 3.3V
+     - 2.34MHz
+   * - VDD = 2.7V
+     - 1.35MHz
+
+If you have a measurement from the MCP3008, you can convert it into a voltage
+like so:
+
+.. code-block:: c
+
+   #define VREF (3.3) /* Whatever voltage is used on the VREF pin */
+
+   struct adc_msg_s msg;
+
+   /* Some code here to read the ADC device, you can read the ADC driver docs */
+
+   double voltage = ((double)msg.am_data * VREF) / (1023.0);
+
+There is also an additional `ioctl()` command supported for the MCP3008 that
+permits you to switch from differential to single ended mode at runtime:
+
+.. c:macro:: ANIOC_MCP3008_DIFF
+
+This command changes the mode of the MCP3008 driver. The argument passed should
+be 0 to disable differential mode (and thus use single-ended mode), and 1 to
+enable differential mode. No other values are allowed.

boards/arm/rp2040/common/src/rp2040_common_bringup.c

@@ -87,6 +87,12 @@
 #include "rp2040_adc.h"
 #endif
 
+#if defined(CONFIG_ADC) && defined(CONFIG_ADC_MCP3008)
+#include <nuttx/analog/mcp3008.h>
+#include <nuttx/analog/adc.h>
+#include "rp2040_spi.h"
+#endif
+
 #if defined(CONFIG_RP2040_BOARD_HAS_WS2812) && defined(CONFIG_WS2812)
 #include "rp2040_ws2812.h"
 #endif
@@ -446,6 +452,28 @@ int rp2040_common_bringup(void)
     }
 #endif
 
+#ifdef CONFIG_ADC_MCP3008
+  /* Register MCP3008 ADC. */
+
+  struct spi_dev_s *spi = rp2040_spibus_initialize(0);
+  if (spi == NULL)
+    {
+      syslog(LOG_ERR, "Failed to initialize SPI bus 0\n");
+    }
+
+  struct adc_dev_s *mcp3008 = mcp3008_initialize(spi);
+  if (mcp3008 == NULL)
+    {
+      syslog(LOG_ERR, "Failed to initialize MCP3008\n");
+    }
+
+  ret = adc_register("/dev/adc1", mcp3008);
+  if (ret < 0)
+    {
+      syslog(LOG_ERR, "Failed to register MCP3008 device driver: %d\n", ret);
+    }
+#endif
+
 #ifdef CONFIG_FS_PROCFS
   /* Mount the procfs file system */
 

drivers/analog/CMakeLists.txt

@@ -95,6 +95,10 @@ if(CONFIG_ADC)
   if(CONFIG_ADC_HX711)
     list(APPEND SRCS hx711.c)
   endif()
+
+  if(CONFIG_ADC_MCP3008)
+    list(APPEND SRCS mcp3008.c)
+  endif()
 endif()
 
 if(CONFIG_LMP92001)

drivers/analog/Kconfig

@@ -229,6 +229,34 @@ config ADC_HA711_ADD_DELAY
 
 endif # ADC_HX711
 
+config ADC_MCP3008
+	bool "MCP3008 support"
+	default n
+	select SPI
+	---help---
+        Enable driver support for the Microchip MCP3008 8-channel, 10-bit ADC.
+
+if ADC_MCP3008
+
+config ADC_MCP3008_SPI_FREQUENCY
+    int "Frequency in Hz"
+    default 2340000
+    range 0 3600000
+    ---help---
+        The frequency of SPI communications to the MCP3008, which also has an
+        effect on sample frequency. 3.6MHz is recommended for VDD >= 4V, 2.34MHz
+        for VDD >= 3.3V and 1.35MHz for VDD = 2.7V.
+
+config ADC_MCP3008_DIFFERENTIAL
+    bool "Differential mode"
+    default n
+    ---help---
+        If yes, MCP3008 will be used in differential mode, which uses channel pairs
+        to measure differential signals. Otherwise, single-ended mode is used which
+        measures the voltage on each channel individually.
+
+endif # ADC_MCP3008
+
 endif # ADC
 
 config COMP

drivers/analog/Make.defs

@@ -107,6 +107,10 @@ endif
 ifeq ($(CONFIG_ADC_HX711),y)
   CSRCS += hx711.c
 endif
+
+ifeq ($(CONFIG_ADC_MCP3008),y)
+  CSRCS += mcp3008.c
+endif
 endif
 
 ifeq ($(CONFIG_LMP92001),y)