Skip to content

improving_docs #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 27, 2021
Merged

improving_docs #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 121 additions & 30 deletions adafruit_lis3dh.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@

**Software and Dependencies:**

* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
https://github.com/adafruit/circuitpython/releases
* Adafruit CircuitPython firmware for the supported boards:
https://circuitpython.org/downloads
* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
"""

Expand Down Expand Up @@ -85,7 +85,14 @@


class LIS3DH:
"""Driver base for the LIS3DH accelerometer."""
"""Driver base for the LIS3DH accelerometer.

:param digitalio.DigitalInOut int1. pin on the sensor that would
act as an in interrupt
:param digitalio.DigitalInOut int2. pin on the sensor that would
act as an in interrupt

"""

def __init__(self, int1=None, int2=None):
# Check device ID.
Expand Down Expand Up @@ -115,10 +122,22 @@ def __init__(self, int1=None, int2=None):

@property
def data_rate(self):
"""The data rate of the accelerometer. Can be DATA_RATE_400_HZ, DATA_RATE_200_HZ,
DATA_RATE_100_HZ, DATA_RATE_50_HZ, DATA_RATE_25_HZ, DATA_RATE_10_HZ,
DATA_RATE_1_HZ, DATA_RATE_POWERDOWN, DATA_RATE_LOWPOWER_1K6HZ, or
DATA_RATE_LOWPOWER_5KHZ."""
"""The data rate of the accelerometer.

Could have the following values:

* DATA_RATE_400_HZ
* DATA_RATE_200_HZ
* DATA_RATE_100_HZ
* DATA_RATE_50_HZ
* DATA_RATE_25_HZ
* DATA_RATE_10_HZ
* DATA_RATE_1_HZ
* DATA_RATE_POWERDOWN
* DATA_RATE_LOWPOWER_1K6HZ
* DATA_RATE_LOWPOWER_5KHZ.

"""
ctl1 = self._read_register_byte(_REG_CTRL1)
return (ctl1 >> 4) & 0x0F

Expand All @@ -131,8 +150,16 @@ def data_rate(self, rate):

@property
def range(self):
"""The range of the accelerometer. Can be RANGE_2_G, RANGE_4_G, RANGE_8_G, or
RANGE_16_G."""
"""The range of the accelerometer.

Could have the following values:

* RANGE_2_G
* RANGE_4_G
* RANGE_8_G
* RANGE_16_G.

"""
ctl4 = self._read_register_byte(_REG_CTRL4)
return (ctl4 >> 4) & 0x03

Expand All @@ -145,7 +172,8 @@ def range(self, range_value):

@property
def acceleration(self):
"""The x, y, z acceleration values returned in a 3-tuple and are in m / s ^ 2."""
"""The x, y, z acceleration values returned
in a 3-tuple and are in :math:`m / s ^ 2`"""
divider = 1
accel_range = self.range
if accel_range == RANGE_16_G:
Expand All @@ -167,21 +195,23 @@ def acceleration(self):
return AccelerationTuple(x, y, z)

def shake(self, shake_threshold=30, avg_count=10, total_delay=0.1):
"""
Detect when the accelerometer is shaken. Optional parameters:
"""Detect when the accelerometer is shaken. Optional parameters:

:param int shake_threshold: Increase or decrease to change shake sensitivity.
This requires a minimum value of 10.
10 is the total acceleration if the board is not
moving, therefore anything less than
10 will erroneously report a constant shake detected.
Defaults to :const:`30`

:param shake_threshold: Increase or decrease to change shake sensitivity. This
requires a minimum value of 10. 10 is the total
acceleration if the board is not moving, therefore
anything less than 10 will erroneously report a constant
shake detected. (Default 30)
:param int avg_count: The number of readings taken and used for the average
acceleration. Default to :const:`10`

:param avg_count: The number of readings taken and used for the average
acceleration. (Default 10)
:param float total_delay: The total time in seconds it takes to obtain avg_count
readings from acceleration. Defaults to :const:`0.1`

:param total_delay: The total time in seconds it takes to obtain avg_count
readings from acceleration. (Default 0.1)
"""

shake_accel = (0, 0, 0)
for _ in range(avg_count):
# shake_accel creates a list of tuples from acceleration data.
Expand All @@ -198,7 +228,7 @@ def shake(self, shake_threshold=30, avg_count=10, total_delay=0.1):
return total_accel > shake_threshold

def read_adc_raw(self, adc):
"""Retrieve the raw analog to digital converter value. ADC must be a
"""Retrieve the raw analog to digital converter value. ADC must be a
value 1, 2, or 3.
"""
if adc < 1 or adc > 3:
Expand Down Expand Up @@ -230,18 +260,19 @@ def read_adc_mV(self, adc): # pylint: disable=invalid-name
def tapped(self):
"""
True if a tap was detected recently. Whether its a single tap or double tap is
determined by the tap param on ``set_tap``. ``tapped`` may be True over
determined by the tap param on :attr:`set_tap`. :attr:`tapped` may be True over
multiple reads even if only a single tap or single double tap occurred if the
interrupt (int) pin is not specified.

The following example uses ``i2c`` and specifies the interrupt pin:
The following example uses `board.I2C` and specifies the interrupt pin:

.. code-block:: python

import adafruit_lis3dh
import digitalio
import board

i2c = busio.I2C(board.SCL, board.SDA)
i2c = board.I2C() # uses board.SCL and board.SDA
int1 = digitalio.DigitalInOut(board.D11) # pin connected to interrupt
lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, int1=int1)
lis3dh.range = adafruit_lis3dh.RANGE_8_G
Expand Down Expand Up @@ -275,10 +306,11 @@ def set_tap(
the accelerometer range. Good values are 5-10 for 16G,
10-20 for 8G, 20-40 for 4G, and 40-80 for 2G.

:param int time_limit: TIME_LIMIT register value (default 10).
:param int time_latency: TIME_LATENCY register value (default 20).
:param int time_window: TIME_WINDOW register value (default 255).
:param int time_limit: TIME_LIMIT register value. Defaults to :const:`10`
:param int time_latency: TIME_LATENCY register value. Defaults to :const:`20`
:param int time_window: TIME_WINDOW register value. Defaults to :const:`255`
:param int click_cfg: CLICK_CFG register value.

"""
if (tap < 0 or tap > 2) and click_cfg is None:
raise ValueError(
Expand Down Expand Up @@ -324,7 +356,37 @@ def _write_register_byte(self, register, value):


class LIS3DH_I2C(LIS3DH):
"""Driver for the LIS3DH accelerometer connected over I2C."""
"""Driver for the LIS3DH accelerometer connected over I2C.

:param ~busio.I2C i2c: The I2C bus the LIS3DH is connected to.
:param address: The I2C device address. Defaults to :const:`0x18`


**Quickstart: Importing and using the device**

Here is an example of using the :class:`LIS3DH_I2C` class.
First you will need to import the libraries to use the sensor

.. code-block:: python

import board
import adafruit_lis3dh

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
lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c)

Now you have access to the :attr:`acceleration` attribute

.. code-block:: python

acc_x, acc_y, acc_z = lis3dh.acceleration


"""

def __init__(self, i2c, *, address=0x18, int1=None, int2=None):
import adafruit_bus_device.i2c_device as i2c_device # pylint: disable=import-outside-toplevel
Expand All @@ -348,7 +410,36 @@ def _write_register_byte(self, register, value):


class LIS3DH_SPI(LIS3DH):
"""Driver for the LIS3DH accelerometer connected over SPI."""
"""Driver for the LIS3DH accelerometer connected over SPI.

:param ~busio.I2C i2c: The I2C bus the LIS3DH is connected to.
:param address: The I2C device address. Defaults to :const:`0x18`


**Quickstart: Importing and using the device**

Here is an example of using the :class:`LIS3DH_SPI` class.
First you will need to import the libraries to use the sensor

.. code-block:: python

import board
import adafruit_lis3dh

Once this is done you can define your `board.SPI` object and define your sensor object

.. code-block:: python

i2c = board.SPI()
lis3dh = adafruit_lis3dh.LIS3DH_SPI(spi)

Now you have access to the :attr:`acceleration` attribute

.. code-block:: python

acc_x, acc_y, acc_z = lis3dh.acceleration

"""

def __init__(self, spi, cs, *, baudrate=100000, int1=None, int2=None):
import adafruit_bus_device.spi_device as spi_device # pylint: disable=import-outside-toplevel
Expand Down
27 changes: 26 additions & 1 deletion docs/examples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,41 @@ Ensure your device works with this simple test.
:caption: examples/lis3dh_simpletest.py
:linenos:

Here are some additional examples:

Tap test
------------

Illustrates tap different capabilities

.. literalinclude:: ../examples/lis3dh_tap.py
:caption: examples/lis3dh_tap.py
:linenos:

ADC test
------------

Get the voltage readings

.. literalinclude:: ../examples/lis3dh_adc.py
:caption: examples/lis3dh_adc.py
:linenos:


Spinner Example
---------------

Creates a spinner

.. literalinclude:: ../examples/lis3dh_spinner.py
:caption: examples/lis3dh_spinner.py
:linenos:


Advanced Spinner Example
------------------------

Creates a spinner with colors and animations

.. literalinclude:: ../examples/lis3dh_spinner.py
:caption: examples/lis3dh_spinner.py
:linenos:
2 changes: 2 additions & 0 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ Table of Contents
.. toctree::
:caption: Tutorials

Adafruit LIS3DH Triple-Axis Accelerometer Breakout Learning Guide <https://learn.adafruit.com/adafruit-lis3dh-triple-axis-accelerometer-breakout>

.. toctree::
:caption: Related Products

Expand Down
6 changes: 3 additions & 3 deletions examples/lis3dh_adc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,16 @@
i2c = busio.I2C(board.ACCELEROMETER_SCL, board.ACCELEROMETER_SDA)
lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, address=0x19)
else:
i2c = busio.I2C(board.SCL, board.SDA)
i2c = board.I2C() # uses board.SCL and board.SDA
lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c)

# Hardware SPI setup:
# spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
# spi = board.SPI()
# cs = digitalio.DigitalInOut(board.D5) # Set to correct CS pin!
# lis3dh = adafruit_lis3dh.LIS3DH_SPI(spi, cs)

# PyGamer I2C Setup:
# i2c = busio.I2C(board.SCL, board.SDA)
# i2c = board.I2C(A)
# lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, address=0x19)


Expand Down
6 changes: 3 additions & 3 deletions examples/lis3dh_simpletest.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,16 @@
i2c = busio.I2C(board.ACCELEROMETER_SCL, board.ACCELEROMETER_SDA)
lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, address=0x19)
else:
i2c = busio.I2C(board.SCL, board.SDA)
i2c = board.I2C() # uses board.SCL and board.SDA
lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c)

# Hardware SPI setup:
# spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
# spi = board.SPI()
# cs = digitalio.DigitalInOut(board.D5) # Set to correct CS pin!
# lis3dh = adafruit_lis3dh.LIS3DH_SPI(spi, cs)

# PyGamer or MatrixPortal I2C Setup:
# i2c = busio.I2C(board.SCL, board.SDA)
# i2c = board.I2C() # uses board.SCL and board.SDA
# lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, address=0x19)


Expand Down
2 changes: 1 addition & 1 deletion examples/lis3dh_tap.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
int1 = digitalio.DigitalInOut(board.ACCELEROMETER_INTERRUPT)
lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, address=0x19, int1=int1)
else:
i2c = busio.I2C(board.SCL, board.SDA)
i2c = board.I2C() # uses board.SCL and board.SDA
int1 = digitalio.DigitalInOut(
board.D9
) # Set this to the correct pin for the interrupt!
Expand Down