Software

This guide is no longer supported. For more information about using the MAX31855 with Python and CircuitPython, check out: https://learn.adafruit.com/thermocouple

To install and use the MAX31855 Python library follow the steps below.

Before you get started make sure your board is connected to the internet through an ethernet or wireless connection so you can download dependencies.  

You'll also want to be familiar with connecting to a Raspberry Pi or BeagleBone Black terminal with SSH.

Dependencies

First install dependencies by executing in a terminal:

Download: file
sudo apt-get update
sudo apt-get install build-essential python-dev python-pip python-smbus git

You can ignore warnings about dependencies which are already installed.

Raspberry Pi

On a Raspberry Pi execute the following to make sure the RPi.GPIO library is installed:

Download: file
sudo pip install RPi.GPIO

BeagleBone Black

On a BeagleBone Black execute the following to make sure the Adafruit_BBIO library is installed:

Download: file
sudo pip install Adafruit_BBIO

Library Install

Next download the MAX31855 Python library to your home directory and install it by executing:

Download: file
cd ~
git clone https://github.com/adafruit/Adafruit_Python_MAX31855.git
cd Adafruit_Python_MAX31855
sudo python setup.py install

That's all you need to do to install the Python library!

Usage

To learn how to use the MAX31855 Python library you can run and review an example program included with the library.  First navigate to the examples directory and open the simpletest.py script in a text editor.  Scroll down to the part of the code which configures the connection with the MAX31855 board:

Download: file
# Uncomment one of the blocks of code below to configure your Pi or BBB to use
# software or hardware SPI.

# Raspberry Pi software SPI configuration.
CLK = 25
CS  = 24
DO  = 18
sensor = MAX31855.MAX31855(CLK, CS, DO)

# Raspberry Pi hardware SPI configuration.
#SPI_PORT   = 0
#SPI_DEVICE = 0
#sensor = MAX31855.MAX31855(spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=5000000))

# BeagleBone Black software SPI configuration.
#CLK = 'P9_12'
#CS  = 'P9_15'
#DO  = 'P9_23'
#sensor = MAX31855.MAX31855(CLK, CS, DO)

# BeagleBone Black hardware SPI configuration.
#SPI_PORT   = 1
#SPI_DEVICE = 0
#sensor = MAX31855.MAX31855(spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=5000000))

By default the configuration to use a Raspberry Pi with software SPI is uncommented, however you can comment that block and uncomment a different block to use a different connection type.

If you've changed the pins which are connected to the hardware make sure to update the pin values in the in the code here!

Once the right block of configuration for your hardware is uncommented, save the file and exit the text editor.  Then run the example by executing:

Download: file
sudo python simpletest.py

If everything goes well you should see the thermocouple and internal temperature displayed every second:

Download: file
Press Ctrl-C to quit.
Thermocouple Temperature: 22.000*C / 71.600*F
    Internal Temperature: 23.312*C / 73.963*F
Thermocouple Temperature: 22.250*C / 72.050*F
    Internal Temperature: 23.375*C / 74.075*F
Thermocouple Temperature: 27.500*C / 81.500*F
    Internal Temperature: 23.312*C / 73.963*F
...
If you get the reported temperature going up when the thermocouple is cooled, and vice versa - try swapping the thermocouple red/yellow wires!

If you see an error make sure you're running the program as root with the sudo command, and that the dependencies & library were installed successfully.

To understand the usage, open simpletest.py in a text editor and follow along with the description of the code below.

Download: file
import Adafruit_MAX31855.MAX31855 as MAX31855

First the MAX31855 module is imported with a Python import statement. 

Download: file
# Uncomment one of the blocks of code below to configure your Pi or BBB to use
# software or hardware SPI.

# Raspberry Pi software SPI configuration.
CLK = 25
CS  = 24
DO  = 18
sensor = MAX31855.MAX31855(CLK, CS, DO)

# Raspberry Pi hardware SPI configuration.
#SPI_PORT   = 0
#SPI_DEVICE = 0
#sensor = MAX31855.MAX31855(spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=5000000))

# BeagleBone Black software SPI configuration.
#CLK = 'P9_12'
#CS  = 'P9_15'
#DO  = 'P9_23'
#sensor = MAX31855.MAX31855(CLK, CS, DO)

# BeagleBone Black hardware SPI configuration.
#SPI_PORT   = 1
#SPI_DEVICE = 0
#sensor = MAX31855.MAX31855(spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=5000000))

Next you see the hardware configuration which was described earlier.  It's important to note that you can configure using software SPI by passing explicit CLK, DS, and DO digital GPIO pins, or you can configure hardware SPI by passing a SpiDev hardware SPI object to the MAX31855 class initializer.

Download: file
# Loop printing measurements every second.
print 'Press Ctrl-C to quit.'
while True:
	temp = sensor.readTempC()
	internal = sensor.readInternalC()
	print 'Thermocouple Temperature: {0:0.3F}*C / {1:0.3F}*F'.format(temp, c_to_f(temp))
	print '    Internal Temperature: {0:0.3F}*C / {1:0.3F}*F'.format(internal, c_to_f(internal))
	time.sleep(1.0)

Finally the example enters a loop where it reads temperature measurements and prints them out every second.  The important thing to see are the two temperature measurement functions, readTempC() and readInternalC().  

The readTempC() function will read the temperature at the thermocouple probe.  If you aren't familiar with how thermocouples determine temperature, make sure to read the thermocouple guide.

The readInternalC() function will read the temperature internal to the MAX31855 chip.

That's all there is to use the MAX31855 Python library!  If you run into issues or wish to contribute, feel free to followup on the library's Github page.

This guide was first published on Sep 19, 2014. It was last updated on Sep 19, 2014. This page (Software) was last updated on Dec 05, 2019.