adafruit / adafruit_circuitpython_mcp3xxx

CircuitPython library for MCP300x SPI ADC's, may later support MCP320x as well

Introduction

CircuitPython library for the MCP3xxx series of analog-to-digital converters.

Currently supports:

• MCP3008: 8-Channel 10-Bit ADC With SPI Interface

Dependencies

This driver depends on:

• Adafruit CircuitPython
• Bus Device

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-mcp3xxx

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-mcp3xxx

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .venv
source .venv/bin/activate
pip3 install adafruit-circuitpython-mcp3xxx

Usage Example

MCP3008 Single Ended

import busio
import digitalio
import board
import adafruit_mcp3xxx.mcp3008 as MCP
from adafruit_mcp3xxx.analog_in import AnalogIn

# create the spi bus
spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)

# create the cs (chip select)
cs = digitalio.DigitalInOut(board.D5)

# create the mcp object
mcp = MCP.MCP3008(spi, cs)

# create an analog input channel on pin 0
chan = AnalogIn(mcp, MCP.P0)

print('Raw ADC Value: ', chan.value)
print('ADC Voltage: ' + str(chan.voltage) + 'V')

MCP3008 Differential

import busio
import digitalio
import board
import adafruit_mcp3xxx.mcp3008 as MCP
from adafruit_mcp3xxx.analog_in import AnalogIn

# create the spi bus
spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)

# create the cs (chip select)
cs = digitalio.DigitalInOut(board.D5)

# create the mcp object
mcp = MCP.MCP3008(spi, cs)

# create a differential ADC channel between Pin 0 and Pin 1
chan = AnalogIn(mcp, MCP.P0, MCP.P1)

print('Differential ADC Value: ', chan.value)
print('Differential ADC Voltage: ' + str(chan.voltage) + 'V')

MCP3004 Single-Ended

import busio
import digitalio
import board
import adafruit_mcp3xxx.mcp3004 as MCP
from adafruit_mcp3xxx.analog_in import AnalogIn

# create the spi bus
spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)

# create the cs (chip select)
cs = digitalio.DigitalInOut(board.D5)

# create the mcp object
mcp = MCP.MCP3004(spi, cs)

# create an analog input channel on pin 0
chan = AnalogIn(mcp, MCP.P0)

print('Raw ADC Value: ', chan.value)
print('ADC Voltage: ' + str(chan.voltage) + 'V')

MCP3004 Differential

import busio
import digitalio
import board
import adafruit_mcp3xxx.mcp3004 as MCP
from adafruit_mcp3xxx.analog_in import AnalogIn

# create the spi bus
spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)

# create the cs (chip select)
cs = digitalio.DigitalInOut(board.D5)

# create the mcp object
mcp = MCP.MCP3004(spi, cs)

# create a differential ADC channel between Pin 0 and Pin 1
chan = AnalogIn(mcp, MCP.P0, MCP.P1)

print('Differential ADC Value: ', chan.value)
print('Differential ADC Voltage: ' + str(chan.voltage) + 'V')

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

adafruit_circuitpython_mcp3xxx's Issues

RTD API Page Doesn't Render

During review of ADS1x15 PR #19, I was comparing docstrings/RTD and noticed that the API doesn't render for MCP3xxx. docs/api.rst needs to be updated to:

.. automodule:: adafruit_mcp3xxx.adafruit_mcp3xxx
   :members:

.. automodule:: adafruit_mcp3xxx.adafruit_mcp3004
   :members:

.. automodule:: adafruit_mcp3xxx.adafruit_mcp3008
   :members:

.. automodule:: adafruit_mcp3xxx.analog_in
   :members:

AnalogIn voltage with in multiple process

Does the package support multiple process, i have 3 processes, one of them run infinitely and use AnalogIn.voltage to get value, but this not as expected, program is terminated if i submit reading from analogIn.voltage...

Cookiecutter inclusions need to be updated in this lib

Needs to be recookiecuttered and the applicable files updated. This will also fix the Builds badge issue on this repo.

Old example in README, docs, PyPI

Folder examples contains this Single Ended Simpletest:

import busio
import digitalio
import board
import adafruit_mcp3xxx.mcp3008 as MCP
from adafruit_mcp3xxx.analog_in import AnalogIn

# create the spi bus
spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)

# create the cs (chip select)
cs = digitalio.DigitalInOut(board.D5)

# create the mcp object
mcp = MCP.MCP3008(spi, cs)

# create an analog input channel on pin 0
chan = AnalogIn(mcp, MCP.P0)

print('Raw ADC Value: ', chan.value)
print('ADC Voltage: ' + str(chan.voltage) + 'V')

However, PyPI, README and circuitpython.readthedocs.io all contain this (I assume outdated) example:

import busio
import digitalio
import board
from adafruit_mcp3xxx.mcp3008 import MCP3008
from adafruit_mcp3xxx.analog_in import AnalogIn

# create the spi bus
spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)

# create the cs (chip select)
cs = digitalio.DigitalInOut(board.D5)

# create the mcp object from MCP3008 class
mcp = MCP3008(spi, cs)

# create an analog input channel on pin 0
chan = AnalogIn(mcp, MCP3008.pin_0)

print('Raw ADC Value: ', chan.value)
print('ADC Voltage: ' + str(chan.voltage) + 'V')

Possible solution

Update the examples.

gpio 8 being selected as CS (chip select) alongside programmed pin

I noticed that independently of which GPIO pin I select to be the CS(chip select) it will also activate GPIO pin 8. Is this the intended behaviour?

Add Support for MCP3002

Support for the MCP3002: 2.7V Dual Channel 10-Bit A/D Converter with SPI Serial Interface

Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21294E.pdf

Reading differential value for Pin 7 throws an error

According to the MCP3008 datasheet, a proper way to calculate the differential value of Pin 7 should be Pin 7 value - Pin 6 value. (Table 5-2, page 19 in https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf ).

Running this code snippet below throws an exception:

import time
import busio
import digitalio
import board
import adafruit_mcp3xxx.mcp3008 as MCP
from adafruit_mcp3xxx.analog_in import AnalogIn

spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)
cs = digitalio.DigitalInOut(board.D5)
mcp = MCP.MCP3008(spi, cs)

diff7 = AnalogIn(mcp, MCP.P7, MCP.P6)
print('Diff7: {}'.format(diff7.value)) 

Traceback (most recent call last):
  File "mcp3xxx-test2.py", line 13, in <module>
      print('Diff7: {}'.format(diff7.value))
  File "/usr/local/lib/python3.5/dist-packages/adafruit_mcp3xxx/analog_in.py", line 61, in value
    return self._mcp.read(self._pin_setting, is_differential=self.is_differential) << 6
  File "/usr/local/lib/python3.5/dist-packages/adafruit_mcp3xxx/mcp3xxx.py", line 86, in read
    command |= pin << 3
TypeError: unsupported operand type(s) for <<: 'str' and 'int'

Looks differential channel mapping in MCP3008 class has a typo, (https://github.com/adafruit/Adafruit_CircuitPython_MCP3xxx/blob/master/adafruit_mcp3xxx/mcp3xxx.py)

MCP3008_DIFF_PINS = {
(0, 1) : P0,
(1, 0) : P1,
(2, 3) : P2,
(3, 2) : P3,
(4, 5) : P4,
(5, 4) : P5,
(6, 7) : P6,
(6, 6) : P7
}

but somehow I was able to read the data on Pin 7 using AnalogIn(MCP.P6, MCP.P6).value .

Using 2 x MCP3008 chips

Hi, I'm trying to connect 2 x MCP3008 to a Raspberry Pi 4 but I'm only getting readings from the first chip. I'm using the same pins for CLK, MISO, MOSI and one MCP3008 connected to CS0 and the other one to CS1 on the Raspberry Pi. How can I read data from the second sensor?

How can i read measurements from pH sensor?

I am using mcp3008 to read analog input from the E-201C pH sensor. I am trying to interpret pH values from voltage measurements. But, wherever I search, the results are like converting mv readings obtained from pH sensor to pH readings.
chan = AnalogIn(mcp, MCP.P0);print(chan.voltage)
Does the above code produce mV readings or V readings? Is there anything you can help me to measure pH sensor reading through mcp3008 to the raspberry pi?

Examples should be renamed to match lib name

Currently the examples begin with mcp3004_ and mcp3008_. They should begin with mcp3xxx_ to follow CircuitPython library standards. These examples should be renamed to begin with mcp3xxx_mcp3004_ and mcp3xxx_mcp3008_. It's longer, but it will better identify which library these examples are associated with in the library example bundle.

The lines including this file name in the docs/examples.rst file must also be updated to reflect the name change, e.g.:

.. literalinclude:: ../examples/current_file_name.py
    :caption: examples/current_file_name.py
    :linenos:

would be updated to:

.. literalinclude:: ../examples/current_file_name_changed.py
    :caption: examples/current_file_name_changed.py
    :linenos:

Incorrect voltage calculation

I think the final line of analog_in.py is wrong. Even when I drive 3.3 volts to an input, the value returned is 3.29682...

return (self.value * self._mcp.reference_voltage) / 65535

When it should be:

return (self.value * self._mcp.reference_voltage) / 65472

The highest level I'm getting from the MCP3008 is 65,472, not 65,535. This makes sense, as the MCP3008 outputs 0 to 1,023 (for a total of 1,024 values). 1,023 * 64 = 65,472

Am I looking at this right?

Values from pins return 16 bits, instead of 10 bits

I am expecting the digital values read from MCP3008 to be between 0 and 1024.

The MCP3008 is a low cost 8-channel 10-bit analog to digital converter.

Digital Output Code = (1024 * V_in) / V_ref
(Equation 4-2, page 17, https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf)

I realized even in the example in the official document, MCP3008 throws values between 0 and 65535, which is 16 bits, not 10 bits.

(https://learn.adafruit.com/mcp3008-spi-adc/python-circuitpython)

In order to retrieve correct values, I manually had to shift 6 bits down channel.value >> 6 but shouldn't it be handled in the library, returning values in 10 bits?

AttributeError: module 'board' has no attribute 'SCK'

As follow-up to the issue #26:

Side note: The upgraded code has started to work for me with one FSR sensor, but the the printed voltage (result) was less sophisticated compared to one generated by the old code.
The real issue is that after the installation of few additional pyhton packages, the new code has stopped working:

spi = busio.SPI(clock=board.SCK, MISO=board.MISO, MOSI=board.MOSI)
AttributeError: module 'board' has no attribute 'SCK'

I have not find any similar like that recorded, but I hope you can advise! Thank you in advance!

No output on this version of library

Hello,

I have an MCP3008 connected to RaspberryPI 3 B+ and this version of the library doesn't output me the value of the voltage when I ran python3 mcp3008_single_ended_simpletest.py
Output it's empty:

Raw ADC Value:  0
ADC Voltage: 0.0V

However this old, deprecated library - https://github.com/adafruit/Adafruit_Python_MCP3008output me correctly the sensor value ; PIN 0

python3 simpletest.py
Reading MCP3008 values, press Ctrl-C to quit...
|    0 |    1 |    2 |    3 |    4 |    5 |    6 |    7 |
---------------------------------------------------------
|   76 |  325 |  307 |  219 |  151 |   58 |    0 |    0 |
|   76 |   38 |   14 |    0 |    0 |   12 |    0 |    0 |
|   77 |   10 |    0 |   37 |  286 |  493 |  353 |  360 |
|   76 |   64 |    7 |    0 |    0 |    0 |    6 |    0 |
|   77 |  138 |  274 |  361 |  359 |  189 |    0 |    0 |

Any ideea? What I should check?

Thank you for all your work!

spi1 instead of spi0

Sorry that i write this in the Issues but i have a question.
I want to use your code to read analog inputs with a raspi with the MCP3008. But not with the spi0 but with the spi1, is this possible and how can i change this? For example in the code of mcp3xxx_mcp3008_single_ended_simpletest.py.
Thank you for your help.

ReadTheDocs webhook out of sync

I hate to be that guy, but RTD doesn't seem to be automatically triggering docs builds. I can't help fix this through a PR. This is on whoever is in charge of the RTD project for this library

conceptual questions

Question #1: By printing out digital (FSR) sensor data (using MCP3008) together with statement "datetime.datetime.now()", what do I really see? Does the signal reflect the status at the moment of SENSING or that at the moment of RECORDING (moment of sensing is earlier than moment of recording)?

Question #2: In connection to the question above and additionally using the statement "time.sleep(0.1)", the sampling rate is ~10/second and the results are displayed very quickly on the display. However with statement "time.sleep(0.0)", the sampling rate is ~230/second and the results are displayed ~1 second later (once I pressed the sensor pad) on the monitor. If I would like to precisely map the FSR sensor data to other time-series using "datetime" unique key, should I shift the result by ~1 second earlier to reflect the reality, or actually the sensor data and associated "datetime" are linked correctly (irrespective of the sampling rate) but the 1 second delay is only visible in real-time display mode?

Thank you for your help!

Missing Type Annotations

There are missing type annotations for some functions in this library.

The typing module does not exist on CircuitPython devices so the import needs to be wrapped in try/except to catch the error for missing import. There is an example of how that is done here:

try:
    from typing import List, Tuple
except ImportError:
    pass

Once imported the typing annotations for the argument type(s), and return type(s) can be added to the function signature. Here is an example of a function that has had this done already:

def wrap_text_to_pixels(
    string: str, max_width: int, font=None, indent0: str = "", indent1: str = ""
) -> List[str]:

If you are new to Git or Github we have a guide about contributing to our projects here: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

There is also a guide that covers our CI utilities and how to run them locally to ensure they will pass in Github Actions here: https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/check-your-code In particular the pages: Sharing docs on ReadTheDocs and Check your code with pre-commit contain the tools to install and commands to run locally to run the checks.

If you are attempting to resolve this issue and need help, you can post a comment on this issue and tag both @FoamyGuy and @kattni or reach out to us on Discord: https://adafru.it/discord in the #circuitpython-dev channel.

The following locations are reported by mypy to be missing type annotations:

• adafruit_mcp3xxx/mcp3xxx.py:56
• adafruit_mcp3xxx/mcp3xxx.py:67
• adafruit_mcp3xxx/mcp3008.py:60
• adafruit_mcp3xxx/mcp3004.py:43
• adafruit_mcp3xxx/mcp3002.py:39
• adafruit_mcp3xxx/analog_in.py:32

Please add MCP3208 support.

"may later support MCP320x as well"

So, Eben Upton and co has made 10.000.000 RP2040, that needs external ADC's to be useful beyond 8 bit.
https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf#errata-e11

I found this library, but ideally want to use MCP3208 to get the resolution I think I need.
The application is a simple 2-joystick(4 pots) + 4 pots MIDI device for sending analog values as 14-bit MIDI CC MSB/LSB messages.

So please, If you have the time, update this to include MCP3208 support.

Kind regards
Jens Peter Nielsen

adafruit_mcp3xxx.Analogin - correct ADC scaling to 16-bit range to match analogio.AnalogIn

The change in adafruit/circuitpython#4794 (raised by @PaintYourDragon) which appeared in CircuitPython 8 scales values to the full 16 bit range for analogio.AnalogIn.

The current implementation of adafruit_mcp3xxx.AnalogIn has the old behaviour of zero padding to unsigned 16bit for the 10bit values. This is well documented as ranging from 0 to 65472 and has been previously discussed in #12

This is part of the same ecosystem, should this be brought into line with the aforementioned full-scaling change?

Same issue raised in adafruit/Adafruit_CircuitPython_ADS1x15#92

Library uses short argument names

pylint suggests using argument names with at least 3 letters. This library uses argument names of shorter length, and while these warnings have been disabled for now, they should be considered for renaming. This may require the rework of Learn Guides and other references to code snippets.

differential python code with 2 sensors

import time
import Adafruit_GPIO.SPI as SPI
import Adafruit_MCP3008
SPI_PORT = 0
SPI_DEVICE = 0
mcp = Adafruit_MCP3008.MCP3008(spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE))
print('Press Ctrl-C to quit...')
while True:
value = mcp.read_adc_difference(0)
print(format(value))
time.sleep(0.0)

I would like to kindly ask your help!
I would like to setup a circuit with 2 FSR sensors. The code above is perfectly working with one FSR, but I have difficulties adjusting the code to read also the signal of the 2nd FSR sensor. Could you give me your advice!? Thank you!

Use GPIO7 (CE1)

How can I use CE1 (GPIO7) instead of CE0 (GPIO8)?