# SPDX-FileCopyrightText: 2017 Tony DiCola for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
`adafruit_fxas21002c`
====================================================
CircuitPython module for the NXP FXAS21002C gyroscope. Based on the driver
from: https://github.com/adafruit/Adafruit_FXAS21002C
See examples/simpletest.py for a demo of the usage.
* Author(s): Tony DiCola
Implementation Notes
--------------------
**Hardware:**
* Adafruit `Precision NXP 9-DOF Breakout Board - FXOS8700 + FXAS21002
<https://www.adafruit.com/product/3463>`_ (Product ID: 3463)
**Software and Dependencies:**
* Adafruit CircuitPython firmware for the supported boards:
https://circuitpython.org/downloads
* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
"""
import struct
import time
try:
from typing import List, Tuple
from busio import I2C
except ImportError:
pass
__version__ = "0.0.0+auto.0"
__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_FXAS21002C.git"
import adafruit_bus_device.i2c_device as i2c_dev
from micropython import const
# Internal constants and register values:
_FXAS21002C_ADDRESS = const(0x21) # 0100001
_FXAS21002C_ID = const(0xD7) # 1101 0111
_GYRO_REGISTER_STATUS = const(0x00)
_GYRO_REGISTER_OUT_X_MSB = const(0x01)
_GYRO_REGISTER_OUT_X_LSB = const(0x02)
_GYRO_REGISTER_OUT_Y_MSB = const(0x03)
_GYRO_REGISTER_OUT_Y_LSB = const(0x04)
_GYRO_REGISTER_OUT_Z_MSB = const(0x05)
_GYRO_REGISTER_OUT_Z_LSB = const(0x06)
_GYRO_REGISTER_WHO_AM_I = const(0x0C) # 11010111 r
_GYRO_REGISTER_CTRL_REG0 = const(0x0D) # 00000000 r/w
_GYRO_REGISTER_CTRL_REG1 = const(0x13) # 00000000 r/w
_GYRO_REGISTER_CTRL_REG2 = const(0x14) # 00000000 r/w
_GYRO_SENSITIVITY_250DPS = 0.0078125 # Table 35 of datasheet
_GYRO_SENSITIVITY_500DPS = 0.015625 # ..
_GYRO_SENSITIVITY_1000DPS = 0.03125 # ..
_GYRO_SENSITIVITY_2000DPS = 0.0625 # ..
# User facing constants/module globals:
GYRO_RANGE_250DPS = 250
GYRO_RANGE_500DPS = 500
GYRO_RANGE_1000DPS = 1000
GYRO_RANGE_2000DPS = 2000
# Unit conversion:
DEGREE_TO_RAD = 3.141592653589793 / 180
[docs]
class FXAS21002C:
"""Driver for the NXP FXAS21002C gyroscope.
:param ~busio.I2C i2c: The I2C bus the device is connected to
:param int address: The I2C device address. Defaults to :const:`0x21`
:param int gyro_range: Device range. Defaults to :const:`250`.
**Quickstart: Importing and using the device**
Here is an example of using the :class:`FXAS21002C` class.
First you will need to import the libraries to use the sensor
.. code-block:: python
import board
import adafruit_fxas21002c
Once this is done you can define your `board.I2C` object and define your sensor object
.. code-block:: python
i2c = board.I2C() # uses board.SCL and board.SDA
sensor = adafruit_fxas21002c.FXAS21002C(i2c)
Now you have access to the :attr:`gyroscope` attribute
.. code-block:: python
gyro_x, gyro_y, gyro_z = sensor.gyroscope
"""
# Class-level buffer for reading and writing data with the sensor.
# This reduces memory allocations but means the code is not re-entrant or
# thread safe!
_BUFFER = bytearray(7)
def __init__(
self,
i2c: I2C,
address: int = _FXAS21002C_ADDRESS,
gyro_range: int = GYRO_RANGE_250DPS,
) -> None:
if gyro_range not in (
GYRO_RANGE_250DPS,
GYRO_RANGE_500DPS,
GYRO_RANGE_1000DPS,
GYRO_RANGE_2000DPS,
):
raise ValueError("gyro_range option selected is not a valid option")
self._gyro_range = gyro_range
self._device = i2c_dev.I2CDevice(i2c, address)
# Check for chip ID value.
if self._read_u8(_GYRO_REGISTER_WHO_AM_I) != _FXAS21002C_ID:
raise RuntimeError("Failed to find FXAS21002C, check wiring!")
ctrl_reg0 = 0x00
if gyro_range == GYRO_RANGE_250DPS:
ctrl_reg0 = 0x03
elif gyro_range == GYRO_RANGE_500DPS:
ctrl_reg0 = 0x02
elif gyro_range == GYRO_RANGE_1000DPS:
ctrl_reg0 = 0x01
elif gyro_range == GYRO_RANGE_2000DPS:
ctrl_reg0 = 0x00
# Reset then switch to active mode with 100Hz output
# Putting into standby doesn't work as the chip becomes instantly
# unresponsive. Perhaps CircuitPython is too slow to go into standby
# and send reset? Keep these two commented for now:
# self._write_u8(_GYRO_REGISTER_CTRL_REG1, 0x00) # Standby)
# self._write_u8(_GYRO_REGISTER_CTRL_REG1, (1<<6)) # Reset
self._write_u8(_GYRO_REGISTER_CTRL_REG0, ctrl_reg0) # Set sensitivity
self._write_u8(_GYRO_REGISTER_CTRL_REG1, 0x0E) # Active
time.sleep(0.1) # 60 ms + 1/ODR
def _read_u8(self, address: int) -> int:
# Read an 8-bit unsigned value from the specified 8-bit address.
with self._device as i2c:
self._BUFFER[0] = address & 0xFF
i2c.write_then_readinto(self._BUFFER, self._BUFFER, out_end=1, in_end=1)
return self._BUFFER[0]
def _write_u8(self, address: int, val: int) -> None:
# Write an 8-bit unsigned value to the specified 8-bit address.
with self._device as i2c:
self._BUFFER[0] = address & 0xFF
self._BUFFER[1] = val & 0xFF
i2c.write(self._BUFFER, end=2)
[docs]
def read_raw(self) -> Tuple[int, int, int]:
"""Read the raw gyroscope readings. Returns a 3-tuple of X, Y, Z axis
16-bit signed values. If you want the gyroscope values in friendly
units consider using the gyroscope property!
"""
# Read gyro data from the sensor.
with self._device as i2c:
self._BUFFER[0] = _GYRO_REGISTER_OUT_X_MSB
i2c.write_then_readinto(self._BUFFER, self._BUFFER, out_end=1)
# Parse out the gyroscope data as 16-bit signed data.
raw_x = struct.unpack_from(">h", self._BUFFER[0:2])[0]
raw_y = struct.unpack_from(">h", self._BUFFER[2:4])[0]
raw_z = struct.unpack_from(">h", self._BUFFER[4:6])[0]
return (raw_x, raw_y, raw_z)
# pylint is confused and incorrectly marking this function as bad return
# types. Perhaps it doesn't understand map returns an iterable value.
# Disable the warning.
@property
def gyroscope(self) -> List[float]:
"""Read the gyroscope value and return its X, Y, Z axis values as a
3-tuple in radians/second.
"""
raw = self.read_raw()
# Compensate values depending on the resolution
factor = 0
if self._gyro_range == GYRO_RANGE_250DPS:
factor = _GYRO_SENSITIVITY_250DPS
elif self._gyro_range == GYRO_RANGE_500DPS:
factor = _GYRO_SENSITIVITY_500DPS
elif self._gyro_range == GYRO_RANGE_1000DPS:
factor = _GYRO_SENSITIVITY_1000DPS
elif self._gyro_range == GYRO_RANGE_2000DPS:
factor = _GYRO_SENSITIVITY_2000DPS
factor *= DEGREE_TO_RAD
return [x * factor for x in raw]