diff --git a/.gitignore b/.gitignore index 5c0e38d..06eca82 100644 --- a/.gitignore +++ b/.gitignore @@ -53,3 +53,10 @@ m4/lt~obsolete.m4 missing source/Makefile.in test-driver +docs/_build +docs/_static +docs/_templates + +# vim temp files +*~ +*.swp diff --git a/Adafruit_BBIO/Encoder.py b/Adafruit_BBIO/Encoder.py index 35fd26f..21c88c1 100644 --- a/Adafruit_BBIO/Encoder.py +++ b/Adafruit_BBIO/Encoder.py @@ -1,5 +1,72 @@ #!/usr/bin/python +"""Quadrature Encoder Pulse interface. + +This module enables access to the enhanced Quadrature Encoder Pulse (eQEP) +channels, which can be used to seamlessly interface with rotary encoder +hardware. + +The channel identifiers are available as module variables :data:`eQEP0`, +:data:`eQEP1`, :data:`eQEP2` and :data:`eQEP2b`. + +======= ======= ======= =================================================== +Channel Pin A Pin B Notes +======= ======= ======= =================================================== +eQEP0 P9.27 P9.92 +eQEP1 P8.33 P8.35 Only available with video disabled +eQEP2 P8.11 P8.12 Only available with eQEP2b unused (same channel) +eQEP2b P8.41 P8.42 Only available with video disabled and eQEP2 unused +======= ======= ======= =================================================== + +Example: + To use the module, you can connect a rotary encoder to your Beaglebone + and then simply instantiate the :class:`RotaryEncoder` class to read its + position:: + + from Adafruit_BBIO.Encoder import RotaryEncoder, eQEP2 + + # Instantiate the class to access channel eQEP2, and initialize + # that channel + myEncoder = RotaryEncoder(eQEP2) + + # Get the current position + cur_position = myEncoder.position + + # Set the current position + next_position = 15 + myEncoder.position = next_position + + # Reset position to 0 + myEncoder.zero() + + # Change mode to relative (default is absolute) + # You can use setAbsolute() to change back to absolute + # Absolute: the position starts at zero and is incremented or + # decremented by the encoder's movement + # Relative: the position is reset when the unit timer overflows. + myEncoder.setRelative() + + # Read the current mode (0: absolute, 1: relative) + # Mode can also be set as a property + mode = myEncoder.mode + + # Get the current frequency of update in Hz + freq = myEncoder.frequency + + # Set the update frequency to 1 kHz + myEncoder.frequency = 1000 + + # Disable the eQEP channel + myEncoder.disable() + + # Check if the channel is enabled + # The 'enabled' property is read-only + # Use the enable() and disable() methods to + # safely enable or disable the module + isEnabled = myEncoder.enabled + +""" + from subprocess import check_output, STDOUT, CalledProcessError import os import logging @@ -8,20 +75,28 @@ import platform (major, minor, patch) = platform.release().split("-")[0].split(".") -if not (int(major) >= 4 and int(minor) >= 4): +if not (int(major) >= 4 and int(minor) >= 4) \ + and platform.node() == 'beaglebone': raise ImportError( 'The Encoder module requires Linux kernel version >= 4.4.x.\n' 'Please upgrade your kernel to use this module.\n' 'Your Linux kernel version is {}.'.format(platform.release())) -# eQEP module channel identifiers -# eQEP 2 and 2b are the same channel, exposed on two different sets of pins, -# which are mutually exclusive eQEP0 = 0 +'''eQEP0 channel identifier, pin A-- P9.92, pin B-- P9.27 on Beaglebone +Black.''' eQEP1 = 1 +'''eQEP1 channel identifier, pin A-- P9.35, pin B-- P9.33 on Beaglebone +Black.''' eQEP2 = 2 +'''eQEP2 channel identifier, pin A-- P8.12, pin B-- P8.11 on Beaglebone Black. +Note that there is only one eQEP2 module. This is one alternative set of pins +where it is exposed, which is mutually-exclusive with eQEP2b''' eQEP2b = 3 +'''eQEP2(b) channel identifier, pin A-- P8.41, pin B-- P8.42 on Beaglebone +Black. Note that there is only one eQEP2 module. This is one alternative set of +pins where it is exposed, which is mutually-exclusive with eQEP2''' # Definitions to initialize the eQEP modules _OCP_PATH = "/sys/devices/platform/ocp" @@ -37,7 +112,7 @@ ] -class eQEP(object): +class _eQEP(object): '''Enhanced Quadrature Encoder Pulse (eQEP) module class. Abstraction for either of the three available channels (eQEP0, eQEP1, eQEP2) on the Beaglebone''' @@ -51,7 +126,7 @@ def fromdict(cls, d): return cls(**df) def __init__(self, channel, pin_A, pin_B, sys_path): - '''Initialize the eQEP module + '''Initialize the given eQEP channel Attributes: channel (str): eQEP channel name. E.g. "eQEP0", "eQEP1", etc. @@ -79,21 +154,11 @@ class RotaryEncoder(object): ''' Rotary encoder class abstraction to control a given QEP channel. - Constructor: - eqep_num: QEP object that determines which channel to control - - Properties: - position: current position of the encoder - frequency: frequency at which the encoder reports new positions - enabled: (read only) true if the module is enabled, false otherwise - mode: current mode of the encoder (absolute: 0, relative: 1) - - Methods: - enable: enable the QEP channel - disable: disable the QEP channel - setAbsolute: shortcut for setting the mode to absolute - setRelative: shortcut for setting the mode to relative - zero: shortcut for setting the position to 0 + Args: + eqep_num (int): determines which eQEP pins are set up. + Allowed values: EQEP0, EQEP1, EQEP2 or EQEP2b, + based on which pins the physical rotary encoder + is connected to. ''' def _run_cmd(self, cmd): @@ -117,15 +182,8 @@ def _config_pin(self, pin): self._run_cmd(["config-pin", pin, "qep"]) def __init__(self, eqep_num): - '''Creates an instance of the class RotaryEncoder. + '''Creates an instance of the class RotaryEncoder.''' - Arguments: - eqep_num: determines which eQEP pins are set up. - Allowed values: EQEP0, EQEP1, EQEP2 or EQEP2b, - based on which pins the physical rotary encoder - is connected to. - - ''' # nanoseconds factor to convert period to frequency and back self._NS_FACTOR = 1000000000 @@ -134,7 +192,7 @@ def __init__(self, eqep_num): self._logger.addHandler(logging.NullHandler()) # Initialize the eQEP channel structures - self._eqep = eQEP.fromdict(_eQEP_DEFS[eqep_num]) + self._eqep = _eQEP.fromdict(_eQEP_DEFS[eqep_num]) self._logger.info( "Configuring: {}, pin A: {}, pin B: {}, sys path: {}".format( self._eqep.channel, self._eqep.pin_A, self._eqep.pin_B, @@ -154,8 +212,8 @@ def __init__(self, eqep_num): def enabled(self): '''Returns the enabled status of the module: - true: module is enabled - false: module is disabled + Returns: + bool: True if the eQEP channel is enabled, False otherwise. ''' isEnabled = bool(int(self._eqep.node.enabled)) @@ -164,7 +222,11 @@ def enabled(self): def _setEnable(self, enabled): '''Turns the eQEP hardware ON or OFF - value (int): 1 represents enabled, 0 is disabled + Args: + enabled (int): enable the module with 1, disable it with 0. + + Raises: + ValueError: if the value for enabled is < 0 or > 1 ''' enabled = int(enabled) @@ -189,8 +251,11 @@ def disable(self): @property def mode(self): - '''Returns the mode the eQEP hardware is in (absolute or relative). + '''Returns the mode the eQEP hardware is in. + Returns: + int: 0 if the eQEP channel is configured in absolute mode, + 1 if configured in relative mode. ''' mode = int(self._eqep.node.mode) @@ -264,14 +329,13 @@ def position(self, position): self._logger.debug("Set position: Channel {}, position: {}".format( self._eqep.channel, position)) - @property def frequency(self): '''Sets the frequency in Hz at which the driver reports new positions. ''' - frequency = self._NS_FACTOR / int(self._eqep.node.period) + frequency = self._NS_FACTOR / int(self._eqep.node.period) self._logger.debug( "Set frequency(): Channel {}, frequency: {} Hz, " @@ -298,3 +362,4 @@ def zero(self): '''Resets the current position to 0''' self.position = 0 + diff --git a/README.md b/README.md index 2c19f81..75adddd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ -# Adafruit BeagleBone I/O Python Library (Adafruit_BBIO) +# Adafruit Beaglebone I/O Python API -* Adafruit_BBIO is a set of Python tools to allow [GPIO](README.md#gpio-setup), [PWM](README.md#pwm), [ADC](README.md#adc), [UART](README.md#uart) and [eQEP](README.md#eqep) (Quadrature Encoder) access on the BeagleBone +[![Documentation Status](https://readthedocs.org/projects/adafruit-beaglebone-io-python/badge/?version=latest)](http://adafruit-beaglebone-io-python.readthedocs.io/en/latest/?badge=latest) +[![PyPI version](https://badge.fury.io/py/Adafruit_BBIO.svg)](https://badge.fury.io/py/Adafruit_BBIO) +[![PyPI pyversions](https://img.shields.io/pypi/pyversions/Adafruit_BBIO.svg)](https://pypi.python.org/pypi/Adafruit_BBIO/) + +Adafruit BBIO is an API to enable [GPIO](README.md#gpio-setup), [PWM](README.md#pwm), [ADC](README.md#adc), [UART](README.md#uart), [SPI](README.md#spi) and [eQEP](README.md#eqep) (Quadrature Encoder) hardware access from Python applications running on the Beaglebone. * It is recommended to use an [official BeagleBoard.org Debian image](https://beagleboard.org/latest-images) * **Currently recommended image: [Debian 9.2 "Stretch" iot (2017-10-29)](https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#microSD.2FStandalone:_.28stretch-iot.29_.28All_BeagleBone_Variants_.26_PocketBeagle.29)** diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..4430e8a --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = Adafruit-BBIO +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e2b2188 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,68 @@ +# Generating API documentation + +This folder contains the required files to automatically generate the Adafruit Beaglebone I/O Python API documentation, partly from the code docstrings and partly from a reStructuredText-formatted `index.rst` file. + +``` +├── conf.py <- Sphinx configuration file +├── index.rst <- Documentation will be generated based on this +└── Makefile <- Auxiliary Makefile to build documentation +``` + +The tools used are [Sphinx](http://www.sphinx-doc.org) to extract the documentation and publish it in HTML format for online viewing, in combination with [Readthedocs](http://readthedocs.io), which automatically executes Sphinx via webhooks triggered by Github commits, and publishes the resulting docs for all tracked branches. Generally Readthedocs will be set up to track stable release branches and master. + +## Building the documentation + +The documentation can also be built on a local checkout of the project: + +First ensure you've got sphinx installed: + +``` +sudo pip install sphinx +``` + +Then you can build the HTML docs: + +``` +cd docs +make html +``` + +Once Sphinx has built the documentation, you can open the main index file with your browser: `_build/html/index.html` + +Notes: + +- The build process will create three additional temporary directories: `_build`, `_static` and `_templates` that will not be version-controlled. You can use `make clean` to remove their contents if you wish to do so. +- The html theme from files built locally is different from the online readthedocs theme. See the `docs/config.py` `html_theme` variable. The main reason is not to introduce another dependency to install the readthedocs theme, but as a side effect, it also helps visually distinguishing the locally-built documentation from the online version. + +## Readthedocs maintenance + +At every release that includes documenation (most probably 1.0.10 will be the first one), the release's branch needs to be selected in the web UI and marked as active. + +After this, documentation will automatically be generated and published for that release. It will be available at the same URL as the main documentation, and a link with the version number will be shown, where it can be accessed from. + +Optionally, the 'stable' URL slug can be pointed to that release branch. Otherwise, the 'stable' slug can also be deactivated for less maintenance overhead. + +The 'latest' URL slug will always be pointing at the repo's master branch. + +## Notes + +Ideally, all API documentation would be written in the source files as Python docstrings, and sphinx would simply extract it. This is actually the case with the `Encoder` module, which is pure Python. + +However, most of the code is written as C extensions. While they do provide docstrings once they are built, Sphinx does not natively support extracting them. There is [a workaround](https://stackoverflow.com/a/30110104/9022675) to do this, but it involves first building the extensions, installing them and hardcoding a path. While it might work for locally-built documentation, it's unlikely that readthedocs support this option. + +For the sake of keeping things simple and with less maintenance, the approach of documenting the C-generated API in the `index.rst` file has been taken. + +This has the advantage of having a definition of the API in one place, but it also poses the disadvantage of some duplication, as the C modules do define some docstrings for their objects. Then again, the API itself has hardly changed in the last few years, and the Beaglebone is a mature platform, so it's unlikely that this will pose a significant maintenance overhead. + +- The documentation in the `index.rst` file is written in [reStructuredText](http://docutils.sourceforge.net/rst.html), extended with Sphinx markup for defining the objects. +- The documentation in Python modules follows the Google readable docstring markup, which also builds upon reStructuredText and is fully supported by Sphinx. + +## Further reference + +- [Google readable docstring markup](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) +- [Google docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) +- [More Google docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) +- [Sphinx docstring markup](http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain) +- [reStructuredText primer](http://www.sphinx-doc.org/en/stable/rest.html#rst-primer) + + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..c002fc2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,178 @@ +# -*- coding: utf-8 -*- +# +# Adafruit-BBIO documentation build configuration file, created by +# sphinx-quickstart on Fri Dec 1 12:56:03 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Adafruit-BBIO' +copyright = u'2017, Adafruit Industries and contributors' +author = u'Justin Cooper and contributors' + +# 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' +# The full version, including alpha/beta/rc tags. +release = u'' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +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'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars + +# Use the readthedocs theme if the documentation is being built there +on_rtd = os.environ.get('READTHEDOCS') == 'True' +if on_rtd: + html_theme = 'default' + html_theme_options = { + 'collapse_navigation': False, + } +else: + html_theme = 'alabaster' + html_sidebars = { + '**': [ + 'searchbox.html', + 'localtoc.html' + ] + } + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Adafruit-BBIOdoc' + + +# -- 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', +} + +# 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, 'Adafruit-BBIO.tex', u'Adafruit-BBIO Documentation', + u'Justin Cooper', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'adafruit-bbio', u'Adafruit-BBIO Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Adafruit-BBIO', u'Adafruit-BBIO Documentation', + author, 'Adafruit-BBIO', 'One line description of project.', + 'Miscellaneous'), +] + +autodoc_member_order = 'groupwise' +#autoclass_content = 'both' + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..252ce6e --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,490 @@ +.. Adafruit-BBIO documentation master file, created by + sphinx-quickstart on Fri Dec 1 12:56:03 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. toctree:: + :hidden: + :maxdepth: 2 + +Adafruit Beaglebone IO Python API +================================= + +The Adafruit Beaglebone IO API enables access to the Beaglebone's GPIO, PWM, +ADC, UART and eQEP hardware modules from Python programs. + +:mod:`Encoder` --- Quadrature Encoder interface +----------------------------------------------- + +.. automodule:: Adafruit_BBIO.Encoder + :members: + +:mod:`PWM` --- Pulse Width Modulation interface +----------------------------------------------- + +Enables access to the Pulse Width Modulation (PWM) module, to easily and +accurately generate a PWM output signal of a given duty cycle and +frequency. + +.. note:: + + You need to be part of the ``pwm`` group of the OS running on the + Beaglebone to be able to run PWM code as a non-root user. The default + user created upon the Debian image installation should already be + part of the group. Otherwise, you can use + ``sudo usermod -a -G pwm userName`` to add ``userName`` to the group. + +.. module:: Adafruit_BBIO.PWM + +.. function:: start(channel, duty_cycle[, frequency=2000, polarity=0]) + + Set up and start the given PWM channel. + + :param str channel: PWM channel. It can be specified in the form + of of 'P8_10', or 'EHRPWM2A'. + :param int duty_cycle: PWM duty cycle. It must have a value from 0 to 100. + :param int frequency: PWM frequency, in Hz. It must be greater than 0. + :param int polarity: defines whether the value for ``duty_cycle`` affects the + rising edge or the falling edge of the waveform. Allowed values -- 0 + (rising edge, default) or 1 (falling edge). + +.. function:: stop(channel) + + Stop the given PWM channel. + + :param str channel: PWM channel. It can be specified in the form + of of 'P8_10', or 'EHRPWM2A'. + +.. function:: set_duty_cycle(channel, duty_cycle) + + Change the duty cycle of the given PWM channel. + + :note: You must have started the PWM channel with :func:`start()` + once, before changing the duty cycle. + + :param str channel: PWM channel. It can be specified in the form + of of 'P8_10', or 'EHRPWM2A'. + :param int duty_cycle: PWM duty cycle. It must have a value from 0 to 100. + +.. function:: set_frequency(channel, frequency) + + Change the frequency of the given PWM channel. + + :note: You must have started the PWM channel with :func:`start()` + once, before changing the frequency. + + :param str channel: PWM channel. It can be specified in the form + of of 'P8_10', or 'EHRPWM2A'. + :param int frequency: PWM frequency. It must be greater than 0. + +.. function:: cleanup() + + Clean up by resetting all GPIO channels that have been used by this + program to INPUT, with no pullup/pulldown and no event detection. + +:mod:`UART` --- UART communications interface +--------------------------------------------- + +UART functionality of a BeagleBone using Python. Generally used to set up +and grant access to a given UART device, which will then be accessed by +other software or modules (e.g. `pyserial`):: + + sudo pip install pyserial + +Example:: + + import Adafruit_BBIO.UART as UART + import serial + + UART.setup("UART1") + + ser = serial.Serial(port = "/dev/ttyO1", baudrate=9600) + ser.close() + ser.open() + if ser.isOpen(): + print "Serial is open!" + ser.write("Hello World!") + ser.close() + +.. module:: Adafruit_BBIO.UART + +.. function:: setup_uart(channel) + + Set up and start the UART channel. This function will effectively export + the given UART so that it can be accessed by other software that controls + its serial lines. + + :param str channel: UART channel to set up. One of "UART1", "UART2", + "UART4" or "UART5" + +.. function:: cleanup() + + Cleans up the UART. + +:mod:`ADC` --- A/D Converter input interface +-------------------------------------------- + +This module enables reading analog input values from the analog to digital +converter (ADC) on the Beaglebone processor. + +Example:: + + import Adafruit_BBIO.ADC as ADC + + ADC.setup() + + # The read method returns normalized values from 0 to 1.0 + value = ADC.read("P9_40") + + # The read_raw returns non-normalized values + value = ADC.read_raw("P9_40") + +.. module:: Adafruit_BBIO.ADC + +.. function:: setup_adc() + + Setup and start the ADC hardware. + +.. function:: setup_read() + + Read the normalized 0-1.0 analog value for the channel. + +.. function:: setup_read_raw() + + Read the raw analog value for the channel. + +:mod:`SPI` --- Serial Peripheral Interface +------------------------------------------ + +This module defines an object type that allows Serial Peripheral Interface +(SPI) bus transactions on hosts running the Linux kernel. The host kernel +must have SPI support and SPI device interface support. + +Because the SPI device interface is opened R/W, users of this module +usually must have root permissions or be members of a group with granted +access rights. + +Pins used for SPI0 and SPI1 ++++++++++++++++++++++++++++ + +==== ===== ===== ===== ===== +PORT CS0 DO DI SCLK +==== ===== ===== ===== ===== +SPI0 P9_17 P9_21 P9_18 P9_22 +SPI1 P9_28 P9_29 P9_30 P9_31 +==== ===== ===== ===== ===== + +Example:: + + import Adafruit_BBIO.SPI as SPI + + from Adafruit_BBIO.SPI import SPI + # spi = SPI(bus, device) #/dev/spidev. + + # /dev/spidev0.0 + spi = SPI(1, 0) + print(spi.xfer2([32, 11, 110, 22, 220])) + spi.close() + + # /dev/spidev0.1 + spi = SPI(1, 1) + print(spi.xfer2([32, 11, 110, 22, 220])) + spi.close() + + # /dev/spidev1.0 + spi = SPI(2, 0) + print(spi.xfer2([32, 11, 110, 22, 220])) + spi.close() + + # /dev/spidev1.1 + spi = SPI(2, 1) + print(spi.xfer2([32, 11, 110, 22, 220])) + spi.close() + +.. module:: Adafruit_BBIO.SPI + +.. class:: SPI(bus, client) + + :param bus: bus number. + :param client: client device number. + :returns: a new SPI object, optionally connected to the specified SPI + device interface. + :rtype: :class:`SPI` + + .. attribute:: bpw + + Bits per word. + + .. attribute:: cshigh + + Chip Select (CS or Slave Select, SS) active high. + + .. attribute:: loop + + Loopback configuration. + + .. attribute:: lsbfirst + + Least Significant Bit (LSB) first. + + .. attribute:: mode + + SPI mode as two bit pattern of Clock Polarity and Phase [CPOL|CPHA]; min-- 0b00 = 0, max-- 0b11 = 3. + + .. attribute:: msh + + Maximum speed in Hz. + + .. attribute:: threewire + + SI/SO signals are shared. + + .. method:: open(bus, device) + + Connects the object to the specified SPI device. `open(X, Y)` will open + `/dev/spidev-X.Y` + + :param int bus: bus number + :param str device: device number + + .. method:: close() + + Disconnects the object from the interface. + + .. method:: readbytes(len) + + Read the specified length of bytes from the SPI device. + + :param int len: length of bytes to read, 1024 maximum. + :returns: values read + :rtype: list[int] + + .. method:: writebytes(values) + + Write bytes to the SPI device. + + :param values: list of values to write, with a maximum length of 1024. + :type values: list[int] + + .. method:: xfer(values[,delay=0]) + + Perform an SPI transaction of values. Slave Select (SS or CS) will be + released and reactivated between blocks. + + :param values: list of values to transfer, with a maximum length of 1024. + :type values: list[int] + :param delay: delay in microseconds between blocks. + :returns: values transferred + :rtype: list[int] + + .. method:: xfer2(values) + + Perform an SPI transaction of values. Slave Select (SS or CS) will be + held active between blocks. + + :param values: list of values to transfer, with a maximum length of 1024. + :type values: list[int] + :returns: values transferred + :rtype: list[int] + +:mod:`GPIO` --- General Purpose I/O interface +--------------------------------------------- + +This module provides access and control of pins set up as General Purpose +I/O (GPIO). + +.. note:: + + You need to be part of the ``gpio`` group of the OS running on the + Beaglebone to be able to run GPIO code as a non-root user. The default + user created upon the Debian image installation should already be + part of the group. Otherwise, you can use + ``sudo usermod -a -G gpio userName`` to add ``userName`` to the group. + +.. note:: + + When coding with this module, you will be using pin names for + better readability. As such, you can specify them in the header 8 or 9 + form (e.g. "P8_16") or in pin name form (e.g. "GPIO1_14"). + For easy reference, you can use the + `Beaglebone pin names table `_ + + +Example:: + + # Use the config-pin command line tool to set a pin's function to GPIO + # Then you can control it with the GPIO module from Python + config-pin P9_14 gpio + + import Adafruit_BBIO.GPIO as GPIO + + # Set up pins as inputs or outputs + GPIO.setup("P8_13", GPIO.IN) + GPIO.setup("P8_14", GPIO.OUT) + GPIO.setup("GPIO0_26", GPIO.OUT) # Alternative: use actual pin names + + # Write a logic high or logic low + GPIO.output("P8_14", GPIO.HIGH) # You can also write '1' instead + GPIO.output("P8_14", GPIO.LOW) # You can also write '0' instead + +.. module:: Adafruit_BBIO.GPIO + +.. function:: setup(channel, direction[, pull_up_down=PUD_OFF, initial=None, delay=0]) + + Set up the given GPIO channel, its direction and (optional) pull/up down control + + :param str channel: GPIO channel to set up (e.g. "P8_16"). + :param int direction: GPIO channel direction (:data:`IN` or :data:`OUT`). + :param int pull_up_down: pull-up/pull-down resistor configuration + (:data:`PUD_OFF`, :data:`PUD_UP` or :data:`PUD_DOWN`). + :param int initial: initial value for an output channel (:data:`LOW`/:data:`HIGH`). + :param int delay: time in milliseconds to wait after exporting the GPIO pin. + +.. function:: cleanup() + + Clean up by resetting all GPIO channels that have been used by + the application to :data:`IN` with no pullup/pulldown and no event + detection. + + :note: It's recommended that you call this function upon exiting your + application. + +.. function:: output(channel, value) + + Set the given output channel to the given digital value. + + :param str channel: GPIO channel to output the value to (e.g. "P8_16"). + :param value: value to set the output to-- 0/1 or False/True + or :data:`LOW`/:data:`HIGH`. + :type value: int or bool + +.. function:: input(channel) + + Get the given input channel's digital value. + + :param str channel: GPIO channel to read the value from (e.g. "P8_16"). + :returns: Channel value–– 0 or 1. + :rtype: int + +.. function:: add_event_detect(channel, edge[, callback=None, bouncetime=0]) + + Enable edge detection events for the given GPIO channel. + + :param str channel: GPIO channel to detect events from (e.g. "P8_16"). + :param int edge: edge to detect–– :data:`RISING`, :data:`FALLING` + or :data:`BOTH` + :param func callback: a function to call once the event has been detected. + :param int bouncetime: switch bounce timeout in ms for the callback. + +.. function:: remove_event_detect(channel) + + Remove edge detection for the given GPIO channel. + + :param str channel: GPIO channel to remove event detection + from (e.g. "P8_16"). + +.. function:: event_detected(channel) + + Checks if an edge event has occured on a given GPIO. + + :note: You need to enable edge detection using :func:`add_event_detect()` first. + + :param str channel: GPIO channel to check for event detection + for (e.g. "P8_16"). + :returns: True if an edge has occured on a given GPIO, False otherwise + :rtype: bool + +.. function:: add_event_callback(channel, callback[, bouncetime=0]) + + Add a callback for an event already defined using :func:`add_event_detect()` + + :param str channel: GPIO channel to add a callback to (e.g. "P8_16"). + :param func callback: a function to call once the event has been detected. + :param int bouncetime: switch bounce timeout in ms for the callback. + +.. function:: wait_for_edge(channel, edge[, timeout=-1]) + + Wait for an edge on the given channel. + + :param str channel: GPIO channel to wait on (e.g. "P8_16"). + :param int edge: edge to detect–– :data:`RISING`, :data:`FALLING` + or :data:`BOTH` + :param int timeout: time to wait for an edge, in milliseconds. + -1 will wait forever. + +.. function:: gpio_function(channel) + + Return the current GPIO function + (:data:`IN`, :data:`IN`, :data:`ALT0`) of the given pin. + + :warning: Currently only returning the direction of the + pin (input or output) is supported. + + :param str channel: GPIO pin to query the status of. + :returns: 0 if :data:`IN`, 1 if :data:`OUT` + :rtype: int + +.. function:: setwarnings(gpio_warnings) + + Enable or disable GPIO warning messages. + + :warning: Currently enabling or disabling warnings + has no effect. + + :param int gpio_warnings: 0–– disable warnings; 1–– enable warnings + +.. attribute:: ALT0 + + Pin mode-- alternate function 0. + +.. attribute:: BOTH + + Edge detection-- detect both edges. + +.. attribute:: FALLING + + Edge detection-- detect falling edge. + +.. attribute:: HIGH + + Pin status-- logic low. + +.. attribute:: IN + + Pin mode-- input. + +.. attribute:: LOW + + Pin status-- logic low. + +.. attribute:: OUT + + Pin mode-- output. + +.. attribute:: PUD_OFF + + Pull-up/pull-down resistor type-- no pull-up/pull-down. + +.. attribute:: PUD_DOWN + + Pull-up/pull-down resistor type-- pull-down. + +.. attribute:: PUD_UP + + Pull-up/pull-down resistor type-- pull-up. + +.. attribute:: RISING + + Edge detection-- detect rising edge. + +.. attribute:: VERSION + + GPIO module version. Currently unused. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` + +