Python & CircuitPython

It's easy to use the LSM303 sensor with CircuitPython and the Adafruit CircuitPython LSM303 module.  This module allows you to easily write Python code that reads the accelerometer and magentometer from the sensor.

You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.

CircuitPython Microcontroller Wiring

First wire up a LSM303 to your board exactly as shown on the previous pages for Arduino using an I2C connection.  Here's an example of wiring a Feather M0 to the sensor with I2C:

  • Board 3V to sensor VIN
  • Board GND to sensor GND
  • Board SCL to sensor SCL
  • Board SDA to sensor SDA

Python Computer Wiring

Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported

Here's the Raspberry Pi wired with I2C:

  • Pi 3V3 to sensor VIN
  • Pi GND to sensor GND
  • Pi SCL to sensor SCL
  • Pi SDA to sensor SDA

CircuitPython Installation of LSM303 Library

Next you'll need to install the Adafruit CircuitPython LSM303 library on your CircuitPython board.  

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle.  Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.

Remember for non-express boards like the, you'll need to manually install the necessary libraries from the bundle:

  • adafruit_lsm303.mpy
  • adafruit_bus_device

Before continuing make sure your board's lib folder or root filesystem has the adafruit_lsm303.mpy, and adafruit_bus_device files and folders copied over.

Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.

CircuitPython & Python Usage

To demonstrate the usage of the sensor we'll initialize it and read the accelerometer and compass/magnetometer from the board's Python REPL.

Run the following code to import the necessary modules and initialize the I2C connection with the sensor:

Download: file
import board
import busio
import adafruit_lsm303
i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_lsm303.LSM303(i2c)

Now you're ready to read values from the sensor using any of these properties:

  • acceleration - A 3-tuple of X, Y, Z acceleration values in meters per second per second (m/s^2).
  • raw_acceleration - A 3-tuple of X, Y, Z acceleration values in the raw 16-bit unsigned values returned by the sensor.  This is handy for doing the most accurate math yourself, but in practice you probably want to use the acceleration attribute above instead!
  • magnetic - A 3-tuple of the X, Y, Z magnetometer readings in micro-Teslas.
Download: file
print('Acceleration (m/s^2): X={0:0.3f} Y={1:0.3f} Z={2:0.3f}'.format(*sensor.acceleration))
print('Magnetometer (micro-Teslas): X={0:0.3f} Y={1:0.3f} Z={2:0.3f}'.format(*sensor.magnetic))

In addition you can read and write a few properties to adjust the magnetometer:

  • mag_gain - The gain of the magnetometer, should be a value of:
    • adafruit_lsm303.MAGGAIN_1_3 - 1.3x (the default)
    • adafruit_lsm303.MAGGAIN_1_9 - 1.9x
    • adafruit_lsm303.MAGGAIN_2_5 - 2.5x
    • adafruit_lsm303.MAGGAIN_4_0 - 4.0x
    • adafruit_lsm303.MAGGAIN_4_7 - 4.7x
    • adafruit_lsm303.MAGGAIN_5_6 - 5.6x
    • adafruit_lsm303.MAGGAIN_8_1 - 8.1x
  • mag_rate - The rate at which the magnetometer is sampled, should be a value of:
    • adafruit_lsm303.MAGRATE_0_7 - 0.75 hz (the default)
    • adafruit_lsm303.MAGRATE_1_5 - 1.5 hz
    • adafruit_lsm303.MAGRATE_3_0 - 3 hz
    • adafruit_lsm303.MAGRATE_7_5 - 7.5 hz
    • adafruit_lsm303.MAGRATE_15 - 15 hz
    • adafruit_lsm303.MAGRATE_30 - 30 hz
    • adafruit_lsm303.MAGRATE_75 - 75 hz
    • adafruit_lsm303.MAGRATE_220 - 220 hz
Download: file
sensor.mag_gain = adafruit_lsm303.MAGGAIN_8_1
sensor.mag_rate = adafruit_lsm303.MAGRATE_220

That's all there is to using the LSM303 with CircuitPython!

Below is a complete example of reading the sensor and printing its values every second.  Save this as on your board and open the REPL to see the output.

Full Example Code

""" Display both accelerometer and magnetometer data once per second """

import time
import board
import busio
import adafruit_lsm303

i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_lsm303.LSM303(i2c)

while True:
    acc_x, acc_y, acc_z = sensor.acceleration
    mag_x, mag_y, mag_z = sensor.magnetic

    print('Acceleration (m/s^2): ({0:10.3f}, {1:10.3f}, {2:10.3f})'.format(acc_x, acc_y, acc_z))
    print('Magnetometer (gauss): ({0:10.3f}, {1:10.3f}, {2:10.3f})'.format(mag_x, mag_y, mag_z))
This guide was first published on Mar 10, 2013. It was last updated on Mar 10, 2013. This page (Python & CircuitPython) was last updated on Sep 16, 2019.