API Reference

MCP3xxx

CircuitPython Library for MCP3xxx ADCs with SPI

  • Author(s): ladyada, Brent Rubell, Kevin J. Walters

Implementation Notes

Hardware:

Software and Dependencies:

Note

The ADC chips’ input pins (AKA “channels”) are aliased in this library as integer variables whose names start with “P” (eg MCP3008.P0 is channel 0 on the MCP3008 chip). Each module that contains a driver class for a particular ADC chip has these aliases predefined accordingly. This is done for code readability and prevention of erroneous SPI commands.

Important

The differential reads (comparisons done by the ADC chip) are limited to certain pairs of channels. These predefined pairs are referenced in this documentation as differential channel mappings. Please refer to the driver class of your ADC chip (MCP3008, MCP3004, MCP3002) for a list of available differential channel mappings.

class adafruit_mcp3xxx.mcp3xxx.MCP3xxx(spi_bus: busio.SPI, cs: DigitalInOut, ref_voltage: float = 3.3, baudrate: int = 100000)

This abstract base class is meant to be inherited by MCP3008, MCP3004, or MCP3002 child classes.

Parameters:

  • spi_bus (SPIDevice) – SPI bus the ADC is connected to.

  • cs (DigitalInOut) – Chip Select Pin.

  • ref_voltage (float) – Voltage into (Vin) the ADC.

  • baudrate (int) – the clock speed for communication to this SPI device. Defaults to 100k.

read(pin: int, is_differential: bool = False) → int

SPI Interface for MCP3xxx-based ADCs reads. Due to 10-bit accuracy, the returned value ranges [0, 1023].

Parameters:

  • pin (int) – individual or differential pin.

  • is_differential (bool) – single-ended or differential read.

Note

This library offers a helper class called AnalogIn for both single-ended and differential reads. If you opt to not implement AnalogIn during differential reads, then the pin parameter should be the first of the two pins associated with the desired differential channel mapping.

property reference_voltage: float

Returns the MCP3xxx’s reference voltage. (read-only)

AnalogIn

AnalogIn for single-ended and differential ADC readings.

  • Author(s): Brent Rubell, Kevin J. Walters

Warning

The ADC chips supported by this library do not use negative numbers. If the resulting differential read is less than 0, then the returned integer value (and voltage value) is 0. If for some reason the voltage on a channel is greater than the reference voltage or less than 0, then the returned integer value is 65535 or 0 respectively.

class adafruit_mcp3xxx.analog_in.AnalogIn(mcp: MCP3xxx, positive_pin: int, negative_pin: int | None = None)

AnalogIn Mock Implementation for ADC Reads.

Parameters:

  • mcp (MCP3002,MCP3004,MCP3008) – The mcp object.

  • positive_pin (int) – Required pin for single-ended.

  • negative_pin (int) – Optional pin for differential reads.

property value: int

Returns the value of an ADC pin as an integer in the range [0, 65535].

property voltage: float

Returns the voltage from the ADC pin as a floating point value. Returned value ranges from 0 to reference_voltage.

MCP3008

MCP3008 8-channel, 10-bit, analog-to-digital converter instance.

  • Author(s): Brent Rubell, Kevin J. Walters

For proper wiring, please refer to the Package Types diagram and Pin Description section of the MCP3004/MCP3008 datasheet.

class adafruit_mcp3xxx.mcp3008.MCP3008(spi_bus: busio.SPI, cs: DigitalInOut, ref_voltage: float = 3.3, baudrate: int = 100000)

Bases: MCP3xxx

MCP3008 Differential channel mapping. The following list of available differential readings takes the form (positive_pin, negative_pin) = (channel A) - (channel B).

  • (P0, P1) = CH0 - CH1

  • (P1, P0) = CH1 - CH0

  • (P2, P3) = CH2 - CH3

  • (P3, P2) = CH3 - CH2

  • (P4, P5) = CH4 - CH5

  • (P5, P4) = CH5 - CH4

  • (P6, P7) = CH6 - CH7

  • (P7, P6) = CH7 - CH6

See also the warning in the AnalogIn class API.

read(pin: int, is_differential: bool = False) → int

SPI Interface for MCP3xxx-based ADCs reads. Due to 10-bit accuracy, the returned value ranges [0, 1023].

Parameters:

  • pin (int) – individual or differential pin.

  • is_differential (bool) – single-ended or differential read.

Note

This library offers a helper class called AnalogIn for both single-ended and differential reads. If you opt to not implement AnalogIn during differential reads, then the pin parameter should be the first of the two pins associated with the desired differential channel mapping.

MCP3004

MCP3004 4-channel, 10-bit, analog-to-digital converter instance.

  • Author(s): Brent Rubell, Kevin J. Walters

For proper wiring, please refer to Package Types diagram and Pin Description section of the MCP3004/MCP3008 datasheet.

class adafruit_mcp3xxx.mcp3004.MCP3004(spi_bus: busio.SPI, cs: DigitalInOut, ref_voltage: float = 3.3, baudrate: int = 100000)

Bases: MCP3xxx

MCP3004 Differential channel mapping. The following list of available differential readings takes the form (positive_pin, negative_pin) = (channel A) - (channel B).

  • (P0, P1) = CH0 - CH1

  • (P1, P0) = CH1 - CH0

  • (P2, P3) = CH2 - CH3

  • (P3, P2) = CH3 - CH2

See also the warning in the AnalogIn class API.

read(pin: int, is_differential: bool = False) → int

SPI Interface for MCP3xxx-based ADCs reads. Due to 10-bit accuracy, the returned value ranges [0, 1023].

Parameters:

  • pin (int) – individual or differential pin.

  • is_differential (bool) – single-ended or differential read.

Note

This library offers a helper class called AnalogIn for both single-ended and differential reads. If you opt to not implement AnalogIn during differential reads, then the pin parameter should be the first of the two pins associated with the desired differential channel mapping.

MCP3002

MCP3002 2-channel, 10-bit, analog-to-digital converter instance.

  • Author(s): Brent Rubell, Brendan Doherty, Kevin J. Walters

For proper wiring, please refer to Package Type diagram and Pin Description section of the MCP3002 datasheet.

class adafruit_mcp3xxx.mcp3002.MCP3002(spi_bus: busio.SPI, cs: DigitalInOut, ref_voltage: float = 3.3, baudrate: int = 100000)

Bases: MCP3xxx

MCP3002 Differential channel mapping. The following list of available differential readings takes the form (positive_pin, negative_pin) = (channel A) - (channel B).

  • (P0, P1) = CH0 - CH1

  • (P1, P0) = CH1 - CH0

See also the warning in the AnalogIn class API.