mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
205 lines
7.3 KiB
Markdown
205 lines
7.3 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/MCP_ADC/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/MCP_ADC/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/MCP_ADC/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/MCP_ADC/releases)
|
|
|
|
|
|
# MCP_ADC
|
|
|
|
Arduino library for 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 |
|
|
|:----------|:------:|:------:|:--------|
|
|
| MCP3002 | 10 | 2 |
|
|
| MCP3004 | 10 | 4 |
|
|
| MCP3008 | 10 | 8 |
|
|
| MCP3201 | 12 | 1 | not tested yet.
|
|
| 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.
|
|
|
|
|
|
## Interface
|
|
|
|
```cpp
|
|
#include "MCP_ADC.h"
|
|
```
|
|
|
|
#### Base
|
|
|
|
If the pins are not set in the constructor, the class will automatically
|
|
use the hardware SPI, otherwise it will use software SPI.
|
|
|
|
- **MCP3002(uint8_t dataIn, uint8_t dataOut, uint8_t clock)** constructor 10 bit ADC 2 channel.
|
|
- **MCP3004(uint8_t dataIn, uint8_t dataOut, uint8_t clock)** constructor 10 bit ADC 4 channel.
|
|
- **MCP3008(uint8_t dataIn, uint8_t dataOut, uint8_t clock)** constructor 10 bit ADC 8 channel.
|
|
- **MCP3201(uint8_t dataIn, uint8_t dataOut, uint8_t clock)** constructor 12 bit ADC 1 channel.
|
|
- **MCP3202(uint8_t dataIn, uint8_t dataOut, uint8_t clock)** constructor 12 bit ADC 2 channel.
|
|
- **MCP3204(uint8_t dataIn, uint8_t dataOut, uint8_t clock)** constructor 12 bit ADC 4 channel.
|
|
- **MCP3208(uint8_t dataIn, uint8_t dataOut, uint8_t clock)** 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, e.g. 1023.
|
|
This makes it easy to calculate relative measurements.
|
|
- **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 |
|
|
|
|
|
|
### 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. needs to be called AFTER the **begin()** function.
|
|
|
|
```cpp
|
|
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.
|
|
|
|
|
|
## MCP3201 experimental
|
|
|
|
Since 0.2.0 code for the MCP3201 has been added however this 12 bit single
|
|
channel device has not been tested yet.
|
|
|
|
As the SPI transfer looked quite a bit like the MCP3202 it is expected to work
|
|
but the proof is in the hardware test.
|
|
|
|
Note that not all function calls make sense for the MCP3201 as this device only
|
|
has 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.
|
|
|