SparkFun Photodetector (MAX30101) Hookup Guide

Favorited Favorite 0

Python Package

Note: This tutorial assumes you are using the latest version of Python 3. If this is your first time using Python or I2C hardware on a Raspberry Pi, please checkout our tutorial on Python Programming with the Raspberry Pi and the Raspberry Pi SPI and I2C Tutorial. Jetson Nano users can check out this tutorial on Working with Qwiic on a Jetson Nano through Jupyter Notebooks.

We've written a Python package to easily get setup and take readings from the button controller on the Top pHAT. There are two methods for installing the Python package for the button controller.

  1. Install the all inclusive SparkFun Qwiic Python package.
  2. Independently install the SparkFun MAX3010x Python package.

The all inclusive SparkFun Qwiic Python package, is recommended as is also installs the required I2C driver as well.

Note: Don't forget to double check that the hardware I2C connection is enabled on your single board computer.

SparkFun Qwiic Package

This repository is hosted on PyPi as the sparkfun-qwiic package. On systems that support PyPi installation via pip3 (use pip for Python 2) is simple, using the following commands:

For all users (note: the user must have sudo privileges):

sudo pip3 install sparkfun-qwiic

For the current user:

pip3 install sparkfun-qwiic

Independent Installation

You can install the sparkfun-qwiic-max3010x Python package independently, which is hosted by PyPi. However, if you prefer to manually download and install the package from the GitHub repository, you can grab them here (*Please be aware of any package dependencies. You can also check out the repository documentation page, hosted on ReadtheDocs.):

PyPi Installation

This repository is hosted on PyPi as the sparkfun-qwiic-max3010x package. On systems that support PyPi installation via pip3 (use pip for Python 2) is simple, using the following commands:

For all users (note: the user must have sudo privileges):

sudo pip3 install sparkfun-qwiic-max3010x

For the current user:

pip3 install sparkfun-qwiic-max3010x

Local Installation

To install, make sure the setuptools package is installed on the system.

Direct installation at the command line (use python for Python 2):

python3 install

To build a package for use with pip3:

python3 sdist

A package file is built and placed in a subdirectory called dist. This package file can be installed using pip3.

cd dist
pip3 install sparkfun_qwic_max3010x-<version>.tar.gz

Python Package Operation

Before we jump into getting readings, let's take a closer look at the available functions in the Python package. Below, is a description of the basic functionality of the Python package. This includes the package organization, built-in methods, and their inputs and/or outputs. For more details on how the Python package works, check out the source code and package documentation.


This Python package has a very few dependencies in the code, listed below:

from __future__ import print_function
import struct
import qwiic_i2c
import time
from smbus2 import SMBus, i2c_msg
_i2c_msg = i2c_msg

from . import heart_rate
hr = heart_rate.HeartRate()

Default Variables

The default variables, in the code, for this Python package are listed below:

# Some devices have multiple availabel addresses - this is a list of these addresses.
# NOTE: The first address in this list is considered the default I2C address for the
# device.
_AVAILABLE_I2C_ADDRESS = [0x57] # 7-bit I2C Address
# Note that MAX30102 has the same I2C address and Part ID

# Status Registers
MAX30105_INTSTAT1 =     0x00 
MAX30105_INTSTAT2 =     0x01 
MAX30105_INTENABLE1 =       0x02 
MAX30105_INTENABLE2 =       0x03 

# FIFO Registers
MAX30105_FIFOWRITEPTR =     0x04 
MAX30105_FIFOOVERFLOW =     0x05 
MAX30105_FIFOREADPTR =  0x06 
MAX30105_FIFODATA =     0x07 

# Configuration Registers
MAX30105_FIFOCONFIG =       0x08 
MAX30105_MODECONFIG =       0x09 
MAX30105_PARTICLECONFIG =   0x0A     # Note, sometimes listed as "SPO2" config in datasheet (pg. 11)
MAX30105_LED1_PULSEAMP =    0x0C 
MAX30105_LED2_PULSEAMP =    0x0D 
MAX30105_LED3_PULSEAMP =    0x0E 
MAX30105_LED_PROX_AMP =     0x10 

# Die Temperature Registers
MAX30105_DIETEMPINT =       0x1F 
MAX30105_DIETEMPFRAC =  0x20 
MAX30105_DIETEMPCONFIG =    0x21 

# Proximity Function Registers
MAX30105_PROXINTTHRESH =    0x30 

# Part ID Registers
MAX30105_REVISIONID =       0xFE 
MAX30105_PARTID =           0xFF     # Should always be 0x15. Identical to MAX30102.

# MAX30105 Commands
# Interrupt configuration (pg 13, 14)
MAX30105_INT_A_FULL_MASK =      (~0b10000000)
MAX30105_INT_A_FULL_ENABLE =    0x80 
MAX30105_INT_A_FULL_DISABLE =   0x00 

MAX30105_INT_DATA_RDY_MASK = (~0b01000000)

MAX30105_INT_ALC_OVF_MASK = (~0b00100000)
MAX30105_INT_ALC_OVF_ENABLE =   0x20 

MAX30105_INT_PROX_INT_MASK = (~0b00010000)

MAX30105_INT_DIE_TEMP_RDY_MASK = (~0b00000010)

MAX30105_SAMPLEAVG_MASK =   (~0b11100000)
MAX30105_SAMPLEAVG_1 =  0x00 
MAX30105_SAMPLEAVG_2 =  0x20 
MAX30105_SAMPLEAVG_4 =  0x40 
MAX30105_SAMPLEAVG_8 =  0x60 
MAX30105_SAMPLEAVG_16 =     0x80 
MAX30105_SAMPLEAVG_32 =     0xA0 


MAX30105_A_FULL_MASK =  0xF0 

# Mode configuration commands (page 19)
MAX30105_SHUTDOWN_MASK =    0x7F 
MAX30105_SHUTDOWN =         0x80 
MAX30105_WAKEUP =           0x00 

MAX30105_RESET_MASK =       0xBF 
MAX30105_RESET =            0x40 

MAX30105_MODE_MASK =        0xF8 
MAX30105_MODE_REDONLY =     0x02 
MAX30105_MODE_REDIRONLY =   0x03 
MAX30105_MODE_MULTILED =    0x07 

# Particle sensing configuration commands (pgs 19-20)
MAX30105_ADCRANGE_MASK =    0x9F 
MAX30105_ADCRANGE_2048 =    0x00 
MAX30105_ADCRANGE_4096 =    0x20 
MAX30105_ADCRANGE_8192 =    0x40 
MAX30105_ADCRANGE_16384 =   0x60 

MAX30105_SAMPLERATE_50 =    0x00 
MAX30105_SAMPLERATE_100 =   0x04 
MAX30105_SAMPLERATE_200 =   0x08 
MAX30105_SAMPLERATE_400 =   0x0C 
MAX30105_SAMPLERATE_800 =   0x10 
MAX30105_SAMPLERATE_1000 = 0x14 
MAX30105_SAMPLERATE_1600 = 0x18 
MAX30105_SAMPLERATE_3200 = 0x1C 

MAX30105_PULSEWIDTH_69 =    0x00 
MAX30105_PULSEWIDTH_118 =   0x01 
MAX30105_PULSEWIDTH_215 =   0x02 
MAX30105_PULSEWIDTH_411 =   0x03 

#Multi-LED Mode configuration (pg 22)
MAX30105_SLOT1_MASK =       0xF8 
MAX30105_SLOT2_MASK =       0x8F 
MAX30105_SLOT3_MASK =       0xF8 
MAX30105_SLOT4_MASK =       0x8F 

SLOT_NONE =                 0x00 
SLOT_RED_LED =          0x01 
SLOT_IR_LED =               0x02 
SLOT_GREEN_LED =            0x03 
SLOT_NONE_PILOT =           0x04 
SLOT_RED_PILOT =            0x05 
SLOT_IR_PILOT =             0x06 
SLOT_GREEN_PILOT =      0x07 



QwiicMax3010x() or QwiicMax3010x(address)
This Python package operates as a class object, allowing new instances of that type to be made. An __init__() constructor is used that creates a connection to an I2C device over the I2C bus using the default or specified I2C address.

The Constructor

A constructor is a special kind of method used to initialize (assign values to) the data members needed by the object when it is created.

__init__(address=None, i2c_driver=None):

Input: value
The value of the device address. If not defined, the Python package will use the default I2C address (0x71) stored under _AVAILABLE_I2C_ADDRESS variable.
Input: i2c_driver
Loads the specified I2C driver; by default the Qwiic I2C driver is used: qwiic_i2c.getI2CDriver(). Users should use the default I2C driver and leave this field blank.


A function is an attribute of the class, which defines a method for instances of that class. In simple terms, they are objects for the operations (or methods) of the class. A list of all the available functions are detailed on the API Reference page of ReadtheDocs for the Qwiic_MAX3010x_Py Python package.

Upgrading the Python Package

In the future, changes to the Python package might be made. Updating the installed packages has to be done individually for each package (i.e. sub-modules and dependencies won't update automatically and must be updated manually). For the sparkfun-qwiic-max3010x Python package, use the following command (use pip for Python 2):

For all users (note: the user must have sudo privileges):

sudo pip3 install --upgrade sparkfun-qwiic-max3010x

For the current user:

pip3 install --upgrade sparkfun-qwiic-max3010x