SPI stands for Serial Peripheral Interface and is a mechanism allowing compatible devices to communicate with the Pi. SPI is a four-wire protocol meaning it usually requires four pins to operate:
The gpiozero library provides two SPI implementations:
When constructing an SPI device there are two schemes for specifying which pins it is connected to:
You cannot mix these two schemes, i.e. attempting to specify port and clock_pin will result in SPIBadArgs being raised. However, you can omit any arguments from either scheme. The defaults are:
Hence the following constructors are all equiavlent:
from gpiozero import MCP3008
MCP3008(channel=0)
MCP3008(channel=0, device=0)
MCP3008(channel=0, port=0, device=0)
MCP3008(channel=0, select_pin=8)
MCP3008(channel=0, clock_pin=11, mosi_pin=10, miso_pin=9, select_pin=8)
Note that the defaults describe equivalent sets of pins and that these pins are compatible with the hardware implementation. Regardless of which scheme you use, gpiozero will attempt to use the hardware implementation if it is available and if the selected pins are compatible, falling back to the software implementation if not.
The MCP3001 is a 10-bit analog to digital converter with 1 channel
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3002 is a 10-bit analog to digital converter with 2 channels (0-1).
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3004 is a 10-bit analog to digital converter with 4 channels (0-3).
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3008 is a 10-bit analog to digital converter with 8 channels (0-7).
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3201 is a 12-bit analog to digital converter with 1 channel
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3202 is a 12-bit analog to digital converter with 2 channels (0-1).
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3204 is a 12-bit analog to digital converter with 4 channels (0-3).
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3208 is a 12-bit analog to digital converter with 8 channels (0-7).
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3301 is a signed 13-bit analog to digital converter. Please note that the MCP3301 always operates in differential mode between its two channels and the output value is scaled from -1 to +1.
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3302 is a 12/13-bit analog to digital converter with 4 channels (0-3). When operated in differential mode, the device outputs a signed 13-bit value which is scaled from -1 to +1. When operated in single-ended mode (the default), the device outputs an unsigned 12-bit value scaled from 0 to 1.
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The MCP3304 is a 12/13-bit analog to digital converter with 8 channels (0-7). When operated in differential mode, the device outputs a signed 13-bit value which is scaled from -1 to +1. When operated in single-ended mode (the default), the device outputs an unsigned 12-bit value scaled from 0 to 1.
The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.
If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).
Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
The classes in the sections above are derived from a series of base classes, some of which are effectively abstract. The classes form the (partial) hierarchy displayed in the graph below:
The following sections document these base classes for advanced users that wish to construct classes for their own devices.
Represents an analog input device connected to SPI (serial interface).
Typical analog input devices are analog to digital converters (ADCs). Several classes are provided for specific ADC chips, including MCP3004, MCP3008, MCP3204, and MCP3208.
The following code demonstrates reading the first channel of an MCP3008 chip attached to the Pi’s SPI pins:
from gpiozero import MCP3008
pot = MCP3008(0)
print(pot.value)
The value attribute is normalized such that its value is always between 0.0 and 1.0 (or in special cases, such as differential sampling, -1 to +1). Hence, you can use an analog input to control the brightness of a PWMLED like so:
from gpiozero import MCP3008, PWMLED
pot = MCP3008(0)
led = PWMLED(17)
led.source = pot.values
The bit-resolution of the device/channel.
The raw value as read from the device.
The current value read from the device, scaled to a value between 0 and 1 (or -1 to +1 for devices operating in differential mode).
Extends Device. Represents a device that communicates via the SPI protocol.
See SPI keyword args for information on the keyword arguments that can be specified with the constructor.
Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.
This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.
You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.
For example, if you have a breadboard with a buzzer connected to pin 16, but then wish to attach an LED instead:
>>> from gpiozero import *
>>> bz = Buzzer(16)
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED(16)
>>> led.blink()
Device descendents can also be used as context managers using the with statement. For example:
>>> from gpiozero import *
>>> with Buzzer(16) as bz:
... bz.on()
...
>>> with LED(16) as led:
... led.on()
...