SparkFun Qwiic 3-Axis Accelerometer (ADXL313) Hookup Guide

Pages
Favorited Favorite 1

Python Package

Note: The link to the ReadtheDocs documentation for this Python package is currently broken. We are working to resolve the issue.

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 ADXL313 accelerometer. There are two methods for installing the Python package for the ADXl313.

  1. Install the all inclusive SparkFun Qwiic Python package.
  2. Independently install the SparkFun ADXL313 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):

language:bash
sudo pip3 install sparkfun-qwiic

For the current user:

language:bash
pip3 install sparkfun-qwiic

Independent Installation

You can install the sparkfun-qwiic-adxl313 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-adxl313 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):

language:bash
sudo pip3 install sparkfun-qwiic-adxl313

For the current user:

language:bash
pip3 install sparkfun-qwiic-adxl313

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):

language:bash
python3 setup.py install

To build a package for use with pip3:

language:bash
python3 setup.py sdist

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

language:bash
cd dist
pip3 install sparkfun_qwic_adxl313-<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.

Dependencies

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

language:python
import qwiic_i2c
import time

Default Variables

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

language:python
# qwiic_adxl313 GLOBAL VARIABLES
#----------------------------------------------------------------------------------------------------
# Define the device name and I2C addresses. These are set in the class defintion 
# as class variables, making them avilable without having to create a class instance.
# This allows higher level logic to rapidly create a index of qwiic devices at 
# runtine
#
# The name of this device 
_DEFAULT_NAME = "Qwiic ADXL313"

# Some devices have multiple availabele 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 = [0x53, 0x1D]

# define our valid chip IDs
_validChipIDs = [0xCB]
Note: This package is different from previous packages as the register variables are declared in the object class.
language:python
# QwiicAdxl313 CLASS VARIABLES
#----------------------------------------------------------------------------------------------------

ADXL313_TO_READ = 6      # Number of Bytes Read - Two Bytes Per Axis

#/////////////////////////////////////////
## ADXL313 Registers //
#/////////////////////////////////////////
ADXL313_DEVID_0 = 0x00
ADXL313_DEVID_1 = 0x01
ADXL313_PARTID = 0x02
ADXL313_REVID = 0x03
ADXL313_XID = 0x04
ADXL313_SOFT_RESET = 0x18
ADXL313_OFSX = 0x1E
ADXL313_OFSY = 0x1F
ADXL313_OFSZ = 0x20
ADXL313_THRESH_ACT = 0x24
ADXL313_THRESH_INACT = 0x25
ADXL313_TIME_INACT = 0x26
ADXL313_ACT_INACT_CTL = 0x27
ADXL313_BW_RATE = 0x2C
ADXL313_POWER_CTL = 0x2D
ADXL313_INT_ENABLE = 0x2E
ADXL313_INT_MAP = 0x2F
ADXL313_INT_SOURCE = 0x30
ADXL313_DATA_FORMAT = 0x31
ADXL313_DATA_X0 = 0x32
ADXL313_DATA_X1 = 0x33
ADXL313_DATA_Y0 = 0x34
ADXL313_DATA_Y1 = 0x35
ADXL313_DATA_Z0 = 0x36
ADXL313_DATA_Z1 = 0x37
ADXL313_FIFO_CTL = 0x38
ADXL313_FIFO_STATUS = 0x39

#////////////////////////////////
## ADXL313 Responses //
#////////////////////////////////
ADXL313_DEVID_0_RSP_EXPECTED = 0xAD
ADXL313_DEVID_1_RSP_EXPECTED = 0x1D
ADXL313_PARTID_RSP_EXPECTED = 0xCB

ADXL313_I2C_ADDRESS_DEFAULT = 0x1D
ADXL313_I2C_ADDRESS_ALT = 0x53
ADXL313_CS_PIN_DEFAULT = 10

#/************************** INTERRUPT PINS **************************/
ADXL313_INT1_PIN = 0x00     # INT1: 0
ADXL313_INT2_PIN = 0x01     # INT2: 1


#/********************** INTERRUPT BIT POSITION **********************/
ADXL313_INT_DATA_READY_BIT = 0x07
ADXL313_INT_ACTIVITY_BIT = 0x04
ADXL313_INT_INACTIVITY_BIT = 0x03
ADXL313_INT_WATERMARK_BIT = 0x01
ADXL313_INT_OVERRUN_BIT = 0x00

ADXL313_DATA_READY = 0x07
ADXL313_ACTIVITY = 0x04
ADXL313_INACTIVITY = 0x03
ADXL313_WATERMARK = 0x01
ADXL313_OVERRUN = 0x00

#/********************** RANGE SETTINGS OPTIONS **********************/
ADXL313_RANGE_05_G = 0x00 # 0-0.5G
ADXL313_RANGE_1_G = 0x01 # 0-1G
ADXL313_RANGE_2_G = 0x02 # 0-2G
ADXL313_RANGE_4_G = 0x03 # 0-4G

#/********************** POWER_CTL BIT POSITION **********************/
ADXL313_I2C_DISABLE_BIT = 0x06
ADXL313_LINK_BIT = 0x05
ADXL313_AUTOSLEEP_BIT = 0x04
ADXL313_MEASURE_BIT = 0x03
ADXL313_SLEEP_BIT = 0x02

#/********************** BANDWIDTH RATE CODES (HZ) *******************/
ADXL313_BW_1600 = 0xF           # 1111      IDD = 170uA
ADXL313_BW_800 = 0xE            # 1110      IDD = 115uA
ADXL313_BW_400 = 0xD            # 1101      IDD = 170uA
ADXL313_BW_200 = 0xC            # 1100      IDD = 170uA (115 low power)
ADXL313_BW_100 = 0xB            # 1011      IDD = 170uA (82 low power)
ADXL313_BW_50 = 0xA         # 1010      IDD = 170uA (64 in low power)
ADXL313_BW_25 = 0x9         # 1001      IDD = 115uA (57 in low power)
ADXL313_BW_12_5 = 0x8           # 1000      IDD = 82uA (50 in low power)
ADXL313_BW_6_25 = 0x7           # 0111      IDD = 65uA (43 in low power)
ADXL313_BW_3_125 = 0x6          # 0110      IDD = 57uA

#/********************** FIFO MODE OPTIONS ***************************/
ADXL313_FIFO_MODE_BYPASS = 0x00
ADXL313_FIFO_MODE_FIFO = 0x01
ADXL313_FIFO_MODE_STREAM = 0x02
ADXL313_FIFO_MODE_TRIGGER = 0x03

#/****************************** ERRORS ******************************/
ADXL313_OK = 1      # No Error
ADXL313_ERROR = 0       # Error Exists

ADXL313_NO_ERROR = 0        # Initial State
ADXL313_READ_ERROR = 1      # Accelerometer Reading Error
ADXL313_BAD_ARG = 2     # Bad Argument

#/********************** INTERRUPT STATUSES **************************/
ADXL313_INTSOURCE_DATAREADY = 0
ADXL313_INTSOURCE_ACTIVITY = 0
ADXL313_INTSOURCE_INACTIVITY = 0
ADXL313_INTSOURCE_WATERMARK = 0
ADXL313_INTSOURCE_OVERRUN = 0

#/***************** x,y,z variables (raw values) *********************/
x = 0
y = 0
z = 0

Class

QwiicAdxl313() or QwiicAdxl313(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.

Functions

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_ADXL313_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-adxl313 Python package, use the following command (use pip for Python 2):

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

language:bash
sudo pip3 install --upgrade sparkfun-qwiic-adxl313

For the current user:

language:bash
pip3 install --upgrade sparkfun-qwiic-adxl313