GY-63_MS5611/libraries/MCP_ADC
2023-11-30 12:21:52 +01:00
..
.github 0.1.9 MCP_ADC + github actions 2023-02-27 11:35:19 +01:00
examples 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
test 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
.arduino-ci.yml 0.1.9 MCP_ADC 2022-11-17 13:00:17 +01:00
CHANGELOG.md 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
keywords.txt 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
library.json 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
library.properties 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
LICENSE 0.1.9 MCP_ADC + github actions 2023-02-27 11:35:19 +01:00
MCP_ADC.cpp 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
MCP_ADC.h 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00
README.md 0.3.0 MCP_ADC 2023-11-30 12:21:52 +01:00

Arduino CI Arduino-lint JSON check GitHub issues

License: MIT GitHub release PlatformIO Registry

MCP_ADC

Arduino library for MCP3001 MCP3002 MCP3004 MCP3008 MCP3201 MCP3202 MCP3204 MCP3208 and compatibles.

Description

This library reads the ADC ports of the MCP ADC convertors. The chips are communicates with SPI and support both hardware SPI or optional software SPI.

type bits chan notes
MCP3001 10 1 not tested yet.
MCP3002 10 2
MCP3004 10 4
MCP3008 10 8
MCP3201 12 1 test, see #13
MCP3202 12 2
MCP3204 12 4
MCP3208 12 8

Current version allows manual override of the hardware SPI clock as the speed is not optimized per ADC type.

The MCP ADC allow single mode which compares voltage of a single channel against GND. Furthermore they allow a differential mode which compares two channels IN+ and IN- to each other. if the IN+ is equal or below IN- the ADC will return 0.

Build into the library is a delta mode which is a software enhanced differential mode. This delta mode can return negative values too.

0.3.0 Breaking change

The version 0.3.0 has breaking changes in the interface. The essence is removal of ESP32 specific code from the library. This makes it possible to support the ESP32-S3 and other processors in the future. Also it makes the library a bit simpler to maintain.

Interface

#include "MCP_ADC.h"

Constructors

  • MCP_ADC(SPIClassRP2040 * mySPI = &SPI) hardware constructor RP2040
  • MCP_ADC(SPIClass * mySPI = &SPI) hardware constructor other
  • MCP_ADC(uint8_t dataIn, uint8_t dataOut, uint8_t clock)

The derived classes have both constructors with same parameters.

  • MCP3001(...) constructor 10 bit ADC 1 channel.
  • MCP3002(...) constructor 10 bit ADC 2 channel.
  • MCP3004(...) constructor 10 bit ADC 4 channel.
  • MCP3008(...) constructor 10 bit ADC 8 channel.
  • MCP3201(...) constructor 12 bit ADC 1 channel.
  • MCP3202(...) constructor 12 bit ADC 2 channel.
  • MCP3204(...) constructor 12 bit ADC 4 channel.
  • MCP3208(...) constructor 12 bit ADC 8 channel.
  • void begin(uint8_t select) set select pin.
  • uint8_t channels() returns the number of channels.
  • int16_t maxValue() returns maxReading of ADC, typical 1023 or 4095. This makes it easy to calculate relative measurements.

Base

  • int16_t analogRead(uint8_t channel) reads the value of a single channel.
  • void analogReadMultiple(uint8_t channels[], uint8_t numChannels, int16_t readings[]) reads multiple channels in one call. See section below.
  • int16_t differentialRead(uint8_t channel) reads differential between two channels.
    Check datasheet for details.
    Note if the IN+ is equal or below IN- this function will return 0.
  • int16_t deltaRead(uint8_t channel) reads differential like above however it will return a negative value if IN+ is below IN-.
  • void setSPIspeed(uint32_t speed) sets SPI clock in Hz, please read datasheet of the ADC first to get optimal speed.
  • uint32_t getSPIspeed() gets current speed in Hz.

Differential channel table:

Channel diff IN+ diff IN- MCP
0 0 1 3x02/3x04/3x08
1 1 0 3x02/3x04/3x08
2 2 3 3x04/3x08
3 3 2 3x04/3x08
4 4 5 3x08
5 5 4 3x08
6 6 7 3x08
7 7 6 3x08

Note: the MCP3x01 are not included in this table, not investigated yet.

Debug

  • bool usesHWSPI() returns true if HW SPI is used.
  • uint32_t count() returns number of channels read since start.

ESP32 specific

  • void selectHSPI() in case hardware SPI, the ESP32 has two options HSPI and VSPI.
  • void selectVSPI() see above.
  • bool usesHSPI() returns true if HSPI is used.
  • bool usesVSPI() returns true if VSPI is used.

The selectVSPI() or the selectHSPI() needs to be called BEFORE the begin() function.

setGPIOpins() experimental

  • void setGPIOpins(uint8_t clk, uint8_t miso, uint8_t mosi, uint8_t select) overrule GPIO pins of ESP32 for hardware SPI. This function needs to be called AFTER the begin() function.

in code:

void setup()
{
  MCP.selectVSPI();
  MCP.begin(15);
  MCP.setGPIOpins(CLK, MISO, MOSI, SELECT);  // SELECT should match the parameter of begin()
}

This implementation might change in the future, e.g. leave out the select pin as it is already known in the code.

About SPI Speed

See https://github.com/RobTillaart/MCP_ADC/issues/3

The default SPI speed is reduced to 1 MHz. This is the value recommended in the datasheet for 2.7V.

In a test with an ESP32 (3.3V) the library showed stable results at 4 MHz and at 6 MHz it was almost good.

The maximum value read at 6 MHz was 1020 instead of 1023 (MCP3008) which indicates that the last 2 bits got lost probably due to signal deformation.

Board Voltage safe max
ESP32 2.7V 1 MHz 4 MHz
UNO 5.0V 2 MHz 4 MHz

For hardware SPI the ESP32 uses the VSPI pins. (see ESP examples).

analogReadMultiple()

Since version 0.2.0 the analogReadMultiple(channels[], numChannels, readings[]) is added to the interface. (See https://github.com/RobTillaart/MCP_ADC/pull/11 - Thanks to Alex Uta).

This function allows to read multiple channels in one call, which improves the performance of fetching new readings from the MCP_ADC device. The amount of gain differs per platform, so run your own performance test.

Besides fetching all ADC's in one call this function also allows to fetch the data from a specific channel multiple times, e.g. to be averaged. Other patterns are possible. These scenarios need still to be tested in practice.

Finally analogReadMultiple() can be used to read only one channel too by using numChannels = 1.

MCP3001, MCP3201 experimental

Since 0.2.0 code for the MCP3201 has been added. The first tests are done (see #13) which showed that the 0.2.0 implementation was not correct. This has been fixed in the 0.2.1 version.

Note that not all function calls make sense for the MCP3201 and MCP3001 as these devices only have one channel. So use the library carefully.

Feedback is as always welcome.

Future

Must

  • improve documentation
  • test analogReadMultiple() scenario's
  • MCP3201 buy hardware and test

Should

  • improve SWSPI for AVR (code is under test for MCP23S17)

Could

Wont

  • get / setF(float A, float B) => float readF(channel) output = A*value + B; it actually does float mapping. As it implies the same mapping for all it might not be that useful => check multiMap library.

Support

If you appreciate my libraries, you can support the development and maintenance. Improve the quality of the libraries by providing issues and Pull Requests, or donate through PayPal or GitHub sponsors.

Thank you,