black-ing, linting-and dox-ing

This commit is contained in:
siddacious 2020-03-20 13:13:44 -07:00
parent 98c29cee22
commit ecbcc5c9b8
8 changed files with 269 additions and 142 deletions

View file

@ -34,12 +34,6 @@ This is easily achieved by downloading
Installing from PyPI
=====================
.. note:: This library is not available on PyPI yet. Install documentation is included
as a standard element. Stay tuned for PyPI availability!
.. todo:: Remove the above note if PyPI version is/will be available at time of release.
If the library is not planned for PyPI, remove the entire 'Installing from PyPI' section.
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
PyPI <https://pypi.org/project/adafruit-circuitpython-ds1841/>`_. To install for current user:
@ -65,7 +59,51 @@ To install in a virtual environment in your current project:
Usage Example
=============
.. todo:: Add a quick, simple example. It and other examples should live in the examples folder and be included in docs/examples.rst.
.. code-block:: python
from time import sleep
import board
import busio
import adafruit_ds1841
from analogio import AnalogIn
####### NOTE ################
# this example will not work with Blinka/rasberry Pi due to the lack of analog pins.
# Blinka and Raspberry Pi users should run the "ds1841_blinka_simpletest.py" example
i2c = busio.I2C(board.SCL, board.SDA)
ds1841 = adafruit_ds1841.DS1841(i2c)
wiper_output = AnalogIn(board.A0)
while True:
ds1841.wiper = 127
print("Wiper set to %d"%ds1841.wiper)
voltage = wiper_output.value
voltage *= 3.3
voltage /= 65535
print("Wiper voltage: %.2f"%voltage)
print("")
sleep(1.0)
ds1841.wiper = 0
print("Wiper set to %d"%ds1841.wiper)
voltage = wiper_output.value
voltage *= 3.3
voltage /= 65535
print("Wiper voltage: %.2f"%voltage)
print("")
sleep(1.0)
ds1841.wiper = 63
print("Wiper set to %d"%ds1841.wiper)
voltage = wiper_output.value
voltage *= 3.3
voltage /= 65535
print("Wiper voltage: %.2f"%voltage)
print("")
sleep(1.0)
Contributing
============

View file

@ -46,26 +46,30 @@ __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_DS1841.git"
from time import sleep
import adafruit_bus_device.i2c_device as i2c_device
from adafruit_register.i2c_struct import UnaryStruct, ROUnaryStruct
from adafruit_register.i2c_struct import UnaryStruct
from adafruit_register.i2c_struct_array import StructArray
from adafruit_register.i2c_bit import RWBit, ROBit
from adafruit_register.i2c_bits import RWBits, ROBits
from adafruit_register.i2c_bit import RWBit
_DS1841_IVR = 0x00
_DS1841_CR0 = 0x02
_DS1841_CR1 = 0x03
_DS1841_LUTAR = 0x08
_DS1841_WR = 0x09
_DS1841_CR2 = 0x0A
_DS1841_TEMP = 0x0C
_DS1841_VOLTAGE = 0x0E
_DS1841_LUT = 0x80 # to C7h
_DS1841_IVR = 0x00
_DS1841_CR0 = 0x02
_DS1841_CR1 = 0x03
_DS1841_LUTAR = 0x08
_DS1841_WR = 0x09
_DS1841_CR2 = 0x0A
_DS1841_TEMP = 0x0C
_DS1841_VOLTAGE = 0x0E
_DS1841_LUT = 0x80 # to C7h
_DS1841_VCC_LSB = 25.6
_DS1841_DEFAULT_ADDRESS = 0x28 # up to 0x2B
_DS1841_DEFAULT_ADDRESS = 0x28 # up to 0x2B
class DS1841:
"""Driver for the DS3502 I2C Digital Potentiometer.
:param ~busio.I2C i2c_bus: The I2C bus the DS3502 is connected to.
:param address: The I2C device address for the sensor. Default is ``0x28``.
"""
_lut_address = UnaryStruct(_DS1841_LUTAR, ">B")
_wiper_register = UnaryStruct(_DS1841_WR, ">B")
@ -88,17 +92,20 @@ class DS1841:
def __init__(self, i2c_bus, address=_DS1841_DEFAULT_ADDRESS):
self.i2c_device = i2c_device.I2CDevice(i2c_bus, address)
self._disable_save_to_eeprom = True # turn off eeprom updates to IV and CR0
self._adder_mode_bit = False # Don't add IV to WR
self._disable_save_to_eeprom = True # turn off eeprom updates to IV and CR0
self._adder_mode_bit = False # Don't add IV to WR
# UPDATE MODE MUST BE FALSE FOR WIPER TO SHADOW IV
self._manual_lut_address = True #
self._manual_wiper_value = True # update WR by I2C
self._manual_lut_address = True #
self._manual_wiper_value = True # update WR by I2C
self._lut_mode_enabled = False
self._update_mode = True
@property
@property
def wiper(self):
"""The value of the potentionmeter's wiper.
:param wiper_value: The value from 0-127 to set the wiper to.
"""
return self._wiper_register
@wiper.setter
@ -108,11 +115,15 @@ class DS1841:
self._wiper_register = value
@property
def initial_value(self):
def wiper_default(self):
"""Sets the wiper's default value and current value to the given value
:param new_default: The value from 0-127 to set as the wiper's default.
"""
return self._initial_value_register
@initial_value.setter
def initial_value(self, value):
@wiper_default.setter
def wiper_default(self, value):
if value > 127:
raise AttributeError("initial_value must be from 0-127")
self._disable_save_to_eeprom = False
@ -126,17 +137,24 @@ class DS1841:
# Turn update mode back on so temp and voltage update
# and LUT usage works
self._update_mode = True
@property
def temperature(self):
"""The current temperature in degrees celcius"""
return self._temperature_register
@property
def voltage(self):
"""The current voltage between VCC and GND"""
return self._voltage_register * _DS1841_VCC_LSB
######## LUTS on LUTS on LUTS
@property
def lut_mode_enabled(self):
"""Enables LUT mode. LUT mode takes sets the value of the Wiper based on the entry in a
72-entry Look Up Table. The LUT entry is selected using the `lut_selection`
property to set an index from 0-71
"""
return self._lut_mode_enabled
@lut_mode_enabled.setter
@ -147,6 +165,11 @@ class DS1841:
self._lut_mode_enabled = value
def set_lut(self, index, value):
"""Set the value of an entry in the Look Up Table.
:param index: The index of the entry to set, from 0-71.
:param value: The value to set at the given index. The `wiper` will be set to this
value when the LUT entry is selected using `lut_selection`
"""
if value > 127:
raise IndexError("set_lut value must be from 0-127")
lut_value_byte = bytearray([value])
@ -154,15 +177,19 @@ class DS1841:
sleep(0.020)
@property
def look_up(self):
def lut_selection(self):
"""Choose the entry in the Look Up Table to use to set the wiper.
:param index: The index of the entry to use, from 0-71.
"""
if not self._lut_mode_enabled:
raise RuntimeError("lut_mode_enabled must be equal to True to use look_up")
return (self._lut_address-_DS1841_LUT)
raise RuntimeError(
"lut_mode_enabled must be equal to True to use lut_selection"
)
return self._lut_address - _DS1841_LUT
@look_up.setter
def look_up(self, value):
@lut_selection.setter
def lut_selection(self, value):
if value > 71 or value < 0:
raise IndexError("look_up value must be from 0-71")
self._lut_address = value+_DS1841_LUT
raise IndexError("lut_selection value must be from 0-71")
self._lut_address = value + _DS1841_LUT
sleep(0.020)

View file

@ -2,7 +2,8 @@
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath(".."))
# -- General configuration ------------------------------------------------
@ -10,42 +11,53 @@ sys.path.insert(0, os.path.abspath('..'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.napoleon',
'sphinx.ext.todo',
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.todo",
]
# TODO: Please Read!
# Uncomment the below if you use native CircuitPython modules such as
# digitalio, micropython and busio. List the modules you use. Without it, the
# autodoc module docs will fail to generate with a warning.
# autodoc_mock_imports = ["digitalio", "busio"]
autodoc_mock_imports = ["adafruit_bus_device", "adafruit_register"]
intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'BusDevice': ('https://circuitpython.readthedocs.io/projects/busdevice/en/latest/', None),'Register': ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
intersphinx_mapping = {
"python": ("https://docs.python.org/3.4", None),
"BusDevice": (
"https://circuitpython.readthedocs.io/projects/busdevice/en/latest/",
None,
),
"Register": (
"https://circuitpython.readthedocs.io/projects/register/en/latest/",
None,
),
"CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None),
}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
templates_path = ["_templates"]
source_suffix = '.rst'
source_suffix = ".rst"
# The master toctree document.
master_doc = 'index'
master_doc = "index"
# General information about the project.
project = u'Adafruit DS1841 Library'
copyright = u'2020 Bryan Siepert'
author = u'Bryan Siepert'
project = "Adafruit DS1841 Library"
copyright = "2020 Bryan Siepert"
author = "Bryan Siepert"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'1.0'
version = "1.0"
# The full version, including alpha/beta/rc tags.
release = u'1.0'
release = "1.0"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -57,7 +69,7 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".env", "CODE_OF_CONDUCT.md"]
# The reST default role (used for this markup: `text`) to use for all
# documents.
@ -69,7 +81,7 @@ default_role = "any"
add_function_parentheses = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
pygments_style = "sphinx"
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
@ -84,59 +96,62 @@ napoleon_numpy_docstring = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
on_rtd = os.environ.get("READTHEDOCS", None) == "True"
if not on_rtd: # only import and set the theme if we're building docs locally
try:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."]
except:
html_theme = 'default'
html_theme_path = ['.']
html_theme = "default"
html_theme_path = ["."]
else:
html_theme_path = ['.']
html_theme_path = ["."]
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_static_path = ["_static"]
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
html_favicon = '_static/favicon.ico'
html_favicon = "_static/favicon.ico"
# Output file base name for HTML help builder.
htmlhelp_basename = 'AdafruitDs1841Librarydoc'
htmlhelp_basename = "AdafruitDs1841Librarydoc"
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'AdafruitDS1841Library.tex', u'AdafruitDS1841 Library Documentation',
author, 'manual'),
(
master_doc,
"AdafruitDS1841Library.tex",
"AdafruitDS1841 Library Documentation",
author,
"manual",
),
]
# -- Options for manual page output ---------------------------------------
@ -144,8 +159,13 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'AdafruitDS1841library', u'Adafruit DS1841 Library Documentation',
[author], 1)
(
master_doc,
"AdafruitDS1841library",
"Adafruit DS1841 Library Documentation",
[author],
1,
)
]
# -- Options for Texinfo output -------------------------------------------
@ -154,7 +174,13 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'AdafruitDS1841Library', u'Adafruit DS1841 Library Documentation',
author, 'AdafruitDS1841Library', 'One line description of project.',
'Miscellaneous'),
(
master_doc,
"AdafruitDS1841Library",
"Adafruit DS1841 Library Documentation",
author,
"AdafruitDS1841Library",
"One line description of project.",
"Miscellaneous",
),
]

View file

@ -23,14 +23,13 @@ Table of Contents
.. toctree::
:caption: Tutorials
.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave
the toctree above for use later.
Learn Guide <https://learn.adafruit.com/ds1841-i2c-potentiometer>
.. toctree::
:caption: Related Products
.. todo:: Add any product links here. If there are none, then simply delete this todo and leave
the toctree above for use later.
`Adafruit DS1841 <https://www.adafruit.com/product/4286>`_
.. toctree::
:caption: Other Links

View file

@ -0,0 +1,21 @@
from time import sleep
import board
import adafruit_ds3502
i2c = board.I2C()
ds3502 = adafruit_ds3502.DS3502(i2c)
# As this code runs, measure the voltage between ground and the RW (wiper) pin
# with a multimeter. You should see the voltage change with each print statement.
while True:
ds3502.wiper = 127
print("Wiper value set to 127")
sleep(5.0)
ds3502.wiper = 0
print("Wiper value set to 0")
sleep(5.0)
ds3502.wiper = 63
print("Wiper value set to 63")
sleep(5.0)

View file

@ -1,25 +1,46 @@
import time
from time import sleep
import board
import busio
from analogio import AnalogIn
import adafruit_ds1841
import adafruit_debug_i2c
####### NOTE ################
# this example will not work with Blinka/rasberry Pi due to the lack of analog pins.
# Blinka and Raspberry Pi users should run the "ds1841_blinka_simpletest.py" example
# setup of the i2c bus giving the SCL (clock) and SDA (data) pins from the board
i2c = busio.I2C(board.SCL, board.SDA)
i2c = adafruit_debug_i2c.DebugI2C(i2c)
ds = adafruit_ds1841.DS1841(i2c)
while True:
print("Temperature = %.2f *C"%ds.temperature)
print("voltage:", ds.voltage, "mV")
# create the ds1841 instance giving the I2C bus we just set up
ds1841 = adafruit_ds1841.DS1841(i2c)
ds.initial_value = 0
time.sleep(1.0)
print("\t\tWiper 1 = %d"%ds.wiper)
# set up an analog input, selecting the A0 pin
wiper_output = AnalogIn(board.A0)
while True:
# set th
ds1841.wiper = 127
print("Wiper set to %d" % ds1841.wiper)
voltage = wiper_output.value
voltage *= 3.3
voltage /= 65535
print("Wiper voltage: %.2f V" % voltage)
print("")
print("\t\tInitial Value 1: = %d"%ds.initial_value)
sleep(1.0)
ds1841.wiper = 0
print("Wiper set to %d" % ds1841.wiper)
voltage = wiper_output.value
voltage *= 3.3
voltage /= 65535
print("Wiper voltage: %.2f V" % voltage)
print("")
ds.initial_value = 69
time.sleep(1.0)
print("\t\t\tWiper 2 = %d"%ds.wiper)
sleep(1.0)
ds1841.wiper = 63
print("Wiper set to %d" % ds1841.wiper)
voltage = wiper_output.value
voltage *= 3.3
voltage /= 65535
print("Wiper voltage: %.2f V" % voltage)
print("")
print("\t\t\tInitial Value 2: = %d"%ds.initial_value)
print("")
sleep(1.0)

View file

@ -9,8 +9,9 @@ from analogio import AnalogIn
# * Wire connecting VCC to RH to make a voltage divider
# * Wire connecting RW to A0
def wiper_voltage(wiper_pin):
raw_value = wiper_pin.value
return (raw_value/(2**16-1) * wiper_pin.reference_voltage)
raw_value = wiper_pin.value
return raw_value / (2 ** 16 - 1) * wiper_pin.reference_voltage
i2c = busio.I2C(board.SCL, board.SDA)
ds = adafruit_ds1841.DS1841(i2c)
@ -28,12 +29,14 @@ ds.lut_mode_enabled = True
# ds.set_lut(i, new_lut_val)
while True:
for i in range(0, LUT_MAX_INDEX+1):
for i in range(0, LUT_MAX_INDEX + 1):
ds.look_up = i
# for printing to serial terminal:
print("\tLUTAR: %s"%hex(ds.look_up),
"\tWiper = %d"%ds.wiper,
"\tWiper Voltage: %f"%wiper_voltage(wiper_pin) )
print(
"\tLUTAR: %s" % hex(ds.look_up),
"\tWiper = %d" % ds.wiper,
"\tWiper Voltage: %f" % wiper_voltage(wiper_pin),
)
time.sleep(0.5)
# uncomment this and comment out the above to print out a mu plotter friendly format (tuple)

View file

@ -6,6 +6,7 @@ https://github.com/pypa/sampleproject
"""
from setuptools import setup, find_packages
# To use a consistent encoding
from codecs import open
from os import path
@ -13,53 +14,44 @@ from os import path
here = path.abspath(path.dirname(__file__))
# Get the long description from the README file
with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
with open(path.join(here, "README.rst"), encoding="utf-8") as f:
long_description = f.read()
setup(
name='adafruit-circuitpython-ds1841',
name="adafruit-circuitpython-ds1841",
use_scm_version=True,
setup_requires=['setuptools_scm'],
description='I2C Logarithmic Resistor',
setup_requires=["setuptools_scm"],
description="I2C Logarithmic Resistor",
long_description=long_description,
long_description_content_type='text/x-rst',
long_description_content_type="text/x-rst",
# The project's main homepage.
url='https://github.com/adafruit/Adafruit_CircuitPython_DS1841',
url="https://github.com/adafruit/Adafruit_CircuitPython_DS1841",
# Author details
author='Adafruit Industries',
author_email='circuitpython@adafruit.com',
author="Adafruit Industries",
author_email="circuitpython@adafruit.com",
install_requires=[
'Adafruit-Blinka',
'adafruit-circuitpython-busdevice',
'adafruit-circuitpython-register'
"Adafruit-Blinka",
"adafruit-circuitpython-busdevice",
"adafruit-circuitpython-register",
],
# Choose your license
license='MIT',
license="MIT",
# See https://pypi.python.org/pypi?%3Aaction=list_classifiers
classifiers=[
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers',
'Topic :: Software Development :: Libraries',
'Topic :: System :: Hardware',
'License :: OSI Approved :: MIT License',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.4',
'Programming Language :: Python :: 3.5',
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"Topic :: Software Development :: Libraries",
"Topic :: System :: Hardware",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.4",
"Programming Language :: Python :: 3.5",
],
# What does your project relate to?
keywords='adafruit blinka circuitpython micropython ds1841 Log Potentiometer pot bias',
keywords="adafruit blinka circuitpython micropython ds1841 Log Potentiometer pot bias",
# You can just specify the packages manually here if your project is
# simple. Or you can use find_packages().
# TODO: IF LIBRARY FILES ARE A PACKAGE FOLDER,
# CHANGE `py_modules=['...']` TO `packages=['...']`
py_modules=['adafruit_ds1841'],
py_modules=["adafruit_ds1841"],
)