diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 6344b2f..2916315 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,47 +1,13 @@ -Thank you for opening an issue on an Adafruit Python library repository. To -improve the speed of resolution please review the following guidelines and -common troubleshooting steps below before creating the issue: +Thank you for opening an issue on the Adafruit BeagleBone Python library repository. -- **Do not use GitHub issues for troubleshooting projects and issues.** Instead use - the forums at http://forums.adafruit.com to ask questions and troubleshoot why - something isn't working as expected. In many cases the problem is a common issue - that you will more quickly receive help from the forum community. GitHub issues - are meant for known defects in the code. If you don't know if there is a defect - in the code then start with troubleshooting on the forum first. -- **If following a tutorial or guide be sure you didn't miss a step.** Carefully - check all of the steps and commands to run have been followed. Consult the - forum if you're unsure or have questions about steps in a guide/tutorial. +In order to understand your system configuration better, please run: +``` +sudo /opt/scripts/tools/version.sh +``` -- **For Python/Raspberry Pi projects check these very common issues to ensure they don't apply**: +and paste the output in a reply. - - If you are receiving an **ImportError: No module named...** error then a - library the code depends on is not installed. Check the tutorial/guide or - README to ensure you have installed the necessary libraries. Usually the - missing library can be installed with the `pip` tool, but check the tutorial/guide - for the exact command. +This script should be present for any image downloaded from: +https://beagleboard.org/ or https://rcn-ee.com/ - - **Be sure you are supplying adequate power to the board.** Check the specs of - your board and power in an external power supply. In many cases just - plugging a board into your computer is not enough to power it and other - peripherals. - - - **Double check all soldering joints and connections.** Flakey connections - cause many mysterious problems. See the [guide to excellent soldering](https://learn.adafruit.com/adafruit-guide-excellent-soldering/tools) for examples of good solder joints. - -If you're sure this issue is a defect in the code and checked the steps above -please fill in the following fields to provide enough troubleshooting information. -You may delete the guideline and text above to just leave the following details: - -- Platform/operating system (i.e. Raspberry Pi with Raspbian operating system, - Windows 32-bit, Windows 64-bit, Mac OSX 64-bit, etc.): **INSERT PLATFORM/OPERATING - SYSTEM HERE** - -- Python version (run `python -version` or `python3 -version`): **INSERT PYTHON - VERSION HERE** - -- Error message you are receiving, including any Python exception traces: **INSERT - ERROR MESAGE/EXCEPTION TRACES HERE*** - -- List the steps to reproduce the problem below (if possible attach code or commands - to run): **LIST REPRO STEPS BELOW** 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/.travis.yml b/.travis.yml index df3bb3e..f515d75 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,4 +1,6 @@ language: python +python: + - "3.6" install: - pip install tox script: diff --git a/Adafruit_BBIO/Encoder.py b/Adafruit_BBIO/Encoder.py index 9f73675..84ca5f6 100644 --- a/Adafruit_BBIO/Encoder.py +++ b/Adafruit_BBIO/Encoder.py @@ -1,313 +1,366 @@ #!/usr/bin/python -# =========================================================================== -# Adafruit_BBIO.Encoder Class -# =========================================================================== -# refers to graycatlabs/PyBBIO/bbio/libraries/RotaryEncoder/rotary_encoder.py - -# BeagleBone must boot with cape-universal enabled -# and load the cape-universala overlay in order to -# use all the eQEP pins -# -# Install the latest Device Tree overlays: -# ======================================== -# sudo apt-get upgrade bb-cape-overlays -# -# File: /boot/uEnv.txt -# ==================== -# uname_r=4.4.62-ti-r99 -# cmdline=coherent_pool=1M quiet cape_universal=enable -# cape_enable=bone_capemgr.enable_partno=cape-universala -# -# File: /sys/devices/platform/bone_capemgr/slots -# ============================================== -# 0: PF---- -1 -# 1: PF---- -1 -# 2: PF---- -1 -# 3: PF---- -1 -# 4: P-O-L- 0 Override Board Name,00A0,Override Manuf,cape-universala -# -# eqep0: P9_27, P9_92 -# =================== -# config-pin P9_27 qep -# config-pin P9_92 qep # alias for P9_42.1 -# cat /sys/devices/platform/ocp/48300000.epwmss/48300180.eqep/position -# -# eqep1: P8.33, P8.35 -# =================== -# config-pin P8.33 qep -# config-pin P8.35 qep -# cat /sys/devices/platform/ocp/48302000.epwmss/48302180.eqep/position -# -# eqep2: P8.11, P8.12 -# =================== -# config-pin P8.11 qep -# config-pin P8.12 qep -# cat /sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position -# -# alternate pins for eqep2 (mutually exclusive) -# eqep2b: P8.41, P8.42 -# ==================== -# config-pin P8.41 qep -# config-pin P8.42 qep -# cat /sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position - -from subprocess import call -import os +"""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 -class QEP : - - def __init__(self, channel=1, debug=False): - self.channel = channel - self.debug = debug - - def errMsg(self): - print("Error accessing 0x%02X: Check your QEP channel" % self.address) - return -1 - -# example method from Adafruit_I2C -# TODO: delete this -# def write8(self, reg, value): -# "Writes an 8-bit value to the specified register/address" -# try: -# self.bus.write_byte_data(self.address, reg, value) -# if self.debug: -# print("Rotary: Wrote 0x%02X to register 0x%02X" % (value, reg)) -# except IOError as err: -# return self.errMsg() -# -# -#if __name__ == '__main__': -# try: -# qep = Adafruit_BBIO.Encoder.QEP() -# print("Default QEP channel is accessible") -# except: -# print("Error accessing default Rotary bus") + # 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 +import itertools +from .sysfs import Node +import platform + +(major, minor, patch) = platform.release().split("-")[0].split(".") +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())) + + +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" +_eQEP_DEFS = [ + {'channel': 'eQEP0', 'pin_A': 'P9_92', 'pin_B': 'P9_27', + 'sys_path': os.path.join(_OCP_PATH, '48300000.epwmss/48300180.eqep')}, + {'channel': 'eQEP1', 'pin_A': 'P8_35', 'pin_B': 'P8_33', + 'sys_path': os.path.join(_OCP_PATH, '48302000.epwmss/48302180.eqep')}, + {'channel': 'eQEP2', 'pin_A': 'P8_12', 'pin_B': 'P8_11', + 'sys_path': os.path.join(_OCP_PATH, '48304000.epwmss/48304180.eqep')}, + {'channel': 'eQEP2b', 'pin_A': 'P8_41', 'pin_B': 'P8_42', + 'sys_path': os.path.join(_OCP_PATH, '48304000.epwmss/48304180.eqep')} +] + + +class _eQEP(object): + '''Enhanced Quadrature Encoder Pulse (eQEP) module class. Abstraction + for either of the three available channels (eQEP0, eQEP1, eQEP2) on + the Beaglebone''' + + @classmethod + def fromdict(cls, d): + '''Creates a class instance from a dictionary''' + + allowed = ('channel', 'pin_A', 'pin_B', 'sys_path') + df = {k: v for k, v in d.items() if k in allowed} + return cls(**df) + + def __init__(self, channel, pin_A, pin_B, sys_path): + '''Initialize the given eQEP channel + + Attributes: + channel (str): eQEP channel name. E.g. "eQEP0", "eQEP1", etc. + Note that "eQEP2" and "eQEP2b" are channel aliases for the + same module, but on different (mutually-exclusive) sets of + pins + pin_A (str): physical input pin for the A signal of the + rotary encoder + pin_B (str): physical input pin for the B signal of the + rotary encoder + sys_path (str): sys filesystem path to access the attributes + of this eQEP module + node (str): sys filesystem device node that contains the + readable or writable attributes to control the QEP channel + + ''' + self.channel = channel + self.pin_A = pin_A + self.pin_B = pin_B + self.sys_path = sys_path + self.node = Node(sys_path) class RotaryEncoder(object): - # TODO: check that kernel 4.1+ - # TODO: use config-pin to set qep mode - OCP_PATH = "/sys/devices/platform/ocp" - _eqep_dirs = [ - '%s/48300000.epwmss/48300180.eqep' % OCP_PATH, - '%s/48302000.epwmss/48302180.eqep' % OCP_PATH, - '%s/48304000.epwmss/48304180.eqep' % OCP_PATH - ] - - EQEP0 = 0 - EQEP1 = 1 - EQEP2 = 2 - EQEP2b = 3 - - def config_pin(self, pin): ''' - config_pin() - Config pin for QEP - ''' - result = call(["config-pin", pin, "qep"]) - print("config_pin> pin={0} result={1}".format(pin, result)) - return result - - def cat_file(self, path): - ''' - cat_file() - Print contents of file - ''' - result = call(["cat", path]) - print("cat_file> path={0} result={1}".format(path, result)) - return result - - def __init__(self, eqep_num): - ''' - RotaryEncoder(eqep_num) - Creates an instance of the class RotaryEncoder. - eqep_num determines which eQEP pins are set up. - eqep_num can be: EQEP0, EQEP1, EQEP2 or EQEP2b based on which pins \ - the rotary encoder is connected to. + Rotary encoder class abstraction to control a given QEP channel. + + 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. ''' - print(">>>>>>>> TEST CALL BEGIN") - ################################### - print(">>>>>> eqep0: P9_27, P9_92") - pin = "P9_27" - self.config_pin(pin) + def _run_cmd(self, cmd): + '''Runs a command. If not successful (i.e. error code different than + zero), print the stderr output as a warning. - pin = "P9_92" - self.config_pin(pin) + ''' + try: + output = check_output(cmd, stderr=STDOUT) + self._logger.info( + "_run_cmd(): cmd='{}' return code={} output={}".format( + " ".join(cmd), 0, output)) + except CalledProcessError as e: + self._logger.warning( + "_run_cmd(): cmd='{}' return code={} output={}".format( + " ".join(cmd), e.returncode, e.output)) - path = "/sys/devices/platform/ocp/48300000.epwmss/48300180.eqep/position" - self.cat_file(path); + def _config_pin(self, pin): + '''Configures a pin in QEP mode using the `config-pin` binary''' - ################################### - print(">>>>>>> eqep1: P8.33, P8.35") + self._run_cmd(["config-pin", pin, "qep"]) - pin = "P8.33" - self.config_pin(pin) + def __init__(self, eqep_num): + '''Creates an instance of the class RotaryEncoder.''' - pin = "P8.35" - self.config_pin(pin) + # nanoseconds factor to convert period to frequency and back + self._NS_FACTOR = 1000000000 - path = "/sys/devices/platform/ocp/48302000.epwmss/48302180.eqep/position" - self.cat_file(path); + # Set up logging at the module level + self._logger = logging.getLogger(__name__) + self._logger.addHandler(logging.NullHandler()) - ################################### - print(">>>>>>> eqep2: P8.11, P8.12") + # Initialize the eQEP channel structures + 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, + self._eqep.sys_path)) - pin = "P8.11" - self.config_pin(pin) + # Configure the pins for the given channel + self._config_pin(self._eqep.pin_A) + self._config_pin(self._eqep.pin_B) - pin = "P8.12" - self.config_pin(pin) + self._logger.debug( + "RotaryEncoder(): sys node: {0}".format(self._eqep.sys_path)) - path = "/sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position" - self.cat_file(path); + # Enable the channel upon initialization + self.enable() + + @property + def enabled(self): + '''Returns the enabled status of the module: + + Returns: + bool: True if the eQEP channel is enabled, False otherwise. + ''' + isEnabled = bool(int(self._eqep.node.enabled)) - ################################### - print(">>>>>>> eqep2b: P8.41, P8.42") + return isEnabled - pin = "P8.41" - self.config_pin(pin) + def _setEnable(self, enabled): + '''Turns the eQEP hardware ON or OFF - pin = "P8.42" - self.config_pin(pin) + Args: + enabled (int): enable the module with 1, disable it with 0. - path = "/sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position" - self.cat_file(path); + Raises: + ValueError: if the value for enabled is < 0 or > 1 - ################################### - print(">>>>>>>> TEST CALL END") + ''' + enabled = int(enabled) + if enabled < 0 or enabled > 1: + raise ValueError( + 'The "enabled" attribute can only be set to 0 or 1. ' + 'You attempted to set it to {}.'.format(enabled)) - print("RotaryEncoder(): eqep_num: {0}".format(eqep_num)) - print("RotaryEncoder(): self._eqep_dirs[0]: {0}".format(self._eqep_dirs[0])) - print("RotaryEncoder(): self._eqep_dirs[1]: {0}".format(self._eqep_dirs[1])) - print("RotaryEncoder(): self._eqep_dirs[2]: {0}".format(self._eqep_dirs[2])) - print("RotaryEncoder(): self._eqep_dirs[eqep_num: {0}]: {1}".format(eqep_num, self._eqep_dirs[eqep_num])) - assert 0 <= eqep_num <= 3 , "eqep_num must be between 0 and 3" - self.base_dir = self._eqep_dirs[eqep_num] - print("RotaryEncoder(): self.base_dir: {0}".format(self.base_dir)) - self.enable() + self._eqep.node.enabled = str(enabled) + self._logger.info("Channel: {}, enabled: {}".format( + self._eqep.channel, self._eqep.node.enabled)) - def enable(self): - ''' - enable() - Turns the eQEP hardware ON - ''' - enable_file = "%s/enabled" % self.base_dir - print("enable(): enable_file: {0}".format(enable_file)) - print("enable(): TODO: write 1 to enable_file") - #return sysfs.kernelFileIO(enable_file, '1') - - def disable(self): - ''' - disable() - Turns the eQEP hardware OFF - ''' - enable_file = "%s/enabled" % self.base_dir - print("disable(): enable_file: {0}".format(enable_file)) - print("disable(): TODO: write 0 to enable_file") - #return sysfs.kernelFileIO(enable_file, '0') + def enable(self): + '''Turns the eQEP hardware ON''' - def setAbsolute(self): - ''' - setAbsolute() - Set mode as Absolute - The position starts at zero and is incremented or - decremented by the encoder's movement - ''' - mode_file = "%s/mode" % self.base_dir - print("setAbsolute(): mode_file: {0}".format(mode_file)) - print("setAbsolute(): TODO: write 0 to mode_file") - #return sysfs.kernelFileIO(mode_file, '0') - - def setRelative(self): - ''' - setRelative() - Set mode as Relative - The position is reset when the unit timer overflows. - ''' - mode_file = "%s/mode" % self.base_dir - print("setRelative(): mode_file: {0}".format(mode_file)) - print("setRelative(): TODO: write 1 to mode_file") - #return sysfs.kernelFileIO(mode_file, '1') - - def getMode(self): - ''' - getMode() - Returns the mode the eQEP hardware is in. - ''' - mode_file = "%s/mode" % self.base_dir - print("getMode(): mode_file: {0}".format(mode_file)) - print("getMode(): TODO: read mode_file") - #return sysfs.kernelFileIO(mode_file) + self._setEnable(1) + + def disable(self): + '''Turns the eQEP hardware OFF''' + + self._setEnable(0) + + @property + def mode(self): + '''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) + + if mode == 0: + mode_name = "absolute" + elif mode == 1: + mode_name = "relative" + else: + mode_name = "invalid" + + self._logger.debug("getMode(): Channel {}, mode: {} ({})".format( + self._eqep.channel, mode, mode_name)) + + return mode + + @mode.setter + def mode(self, mode): + '''Sets the eQEP mode as absolute (0) or relative (1). + See the setAbsolute() and setRelative() methods for + more information. + + ''' + mode = int(mode) + if mode < 0 or mode > 1: + raise ValueError( + 'The "mode" attribute can only be set to 0 or 1. ' + 'You attempted to set it to {}.'.format(mode)) + + self._eqep.node.mode = str(mode) + self._logger.debug("Mode set to: {}".format( + self._eqep.node.mode)) + + def setAbsolute(self): + '''Sets the eQEP mode as Absolute: + The position starts at zero and is incremented or + decremented by the encoder's movement + + ''' + self.mode = 0 + + def setRelative(self): + '''Sets the eQEP mode as Relative: + The position is reset when the unit timer overflows. + + ''' + self.mode = 1 + + @property + def position(self): + '''Returns the current position of the encoder. + In absolute mode, this attribute represents the current position + of the encoder. + In relative mode, this attribute represents the position of the + encoder at the last unit timer overflow. + + ''' + position = self._eqep.node.position + + self._logger.debug("Get position: Channel {}, position: {}".format( + self._eqep.channel, position)) + + return int(position) + + @position.setter + def position(self, position): + '''Sets the current position to a new value''' + + position = int(position) + self._eqep.node.position = str(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) + + self._logger.debug( + "Set frequency(): Channel {}, frequency: {} Hz, " + "period: {} ns".format( + self._eqep.channel, frequency, + self._eqep.node.period)) + + return frequency + + @frequency.setter + def frequency(self, frequency): + '''Sets the frequency in Hz at which the driver reports + new positions. + + ''' + # github issue #299: force period to be an integer + period = int(self._NS_FACTOR / frequency) # Period in nanoseconds + self._eqep.node.period = str(period) + self._logger.debug( + "Set frequency(): Channel {}, frequency: {} Hz, " + "period: {} ns".format( + self._eqep.channel, frequency, period)) + + def zero(self): + '''Resets the current position to 0''' + + self.position = 0 - def getPosition(self): - ''' - getPosition() - Get the current position of the encoder. - In absolute mode, this attribute represents the current position - of the encoder. - In relative mode, this attribute represents the position of the - encoder at the last unit timer overflow. - ''' - position_file = "%s/position" % self.base_dir - print("getPosition(): position_file: {0}".format(position_file)) - position_handle = open(position_file, 'r') - print("getPosition(): position_handle: {0}".format(position_handle)) - position = position_handle.read() - print("getPosition(): position: {0}".format(position)) - #return sysfs.kernelFileIO(position_file) - return position - - def setFrequency(self,freq): - ''' - setFrequency(freq) - Set the frequency in Hz at which the driver reports new positions. - ''' - period_file = "%s/period" % self.base_dir - print("setFrequency(): period_file: {0}".format(period_file)) - print("setFrequency(): freq: {0}".format(period_file)) - print("setFrequency(): freq: {0}".format(freq)) - print("setFrequency(): 1000000000/freq: {0}".format(1000000000/freq)) - print("setFrequency(): str(1000000000/freq)): {0}".format(str(1000000000/freq))) - print("setFrequency(): TODO: set period_file: {0}".format(str(1000000000/freq))) - #return sysfs.kernelFileIO(period_file, str(1000000000/freq)) - - def setPosition(self,val): - ''' - setPosition(value) - Give a new value to the current position - ''' - position_file = "%s/position" % self.base_dir - #return sysfs.kernelFileIO(position_file, str(val)) - - def zero(self): - ''' - zero()s - Set the current position to 0 - ''' - return self.setPosition(0) - - -#""" -# encoder_test.py -# Rekha Seethamraju -# An example to demonstrate the use of the eQEP library -# for PyBBIO. -# This example program is in the public domain. -#""" -#from bbio import * -#from bbio.libraries.RotaryEncoder import RotaryEncoder -# -#encoder = RotaryEncoder(RotaryEncoder.EQEP2b) -# -#def setup(): -# encoder.setAbsolute() -# encoder.zero() -# -#def loop(): -# print("encoder position : "+encoder.getPosition()) -# delay(1000) -# -#run(setup, loop) diff --git a/Adafruit_BBIO/README.md b/Adafruit_BBIO/README.md new file mode 100644 index 0000000..58cbfd7 --- /dev/null +++ b/Adafruit_BBIO/README.md @@ -0,0 +1,179 @@ +# Adafruit_BBIO.Encoder + +This module enables access to the Beaglebone Black enhanced Quadrature Encoder Pulse (eQEP) modules: eQEP0, eQEP1 and eQEP2/eQEP2b. + +## Usage + +On a recent Beaglebone Debian image, access to the eQEP0 and eQEP2 channels should work out of the box, at least as root user. To ensure you can run the code as a regular user, read on the prerequisites section below. + +```python +from Adafruit_BBIO.Encoder import RotaryEncoder, eQEP2 + +''' +Each channel can be accessed and initialized using its corresponding +channel name constants: + + eQEP0 + eQEP1 # Pins only available when video is disabled + eQEP2 + eQEP2b # Pins only available when video is disabled +''' + +# Instantiate the class to access channel eQEP2, and only initialize +# that channel +myEncoder = RotaryEncoder(eQEP2) + +# Get the current position +cur_position = myEncoder.position + +# Position can also be set as a property +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 + +# Read the current frequency of update +# Returned value is in Hz +# If you want to set the frequency, specify it also in Hz +freq = myEncoder.frequency + +# Disable your 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 + +``` + +If you need to use further channels, read on the prerequisites in the following section. + +## Prerequisites + +### Kernel and packages + +These instructions are based on: + +- Linux kernel: 4.4.x or later +- `bb-cape-overlays` package: version 4.4.20171120.0-0rcnee1~stretch+20171120 or later +- `bb-customizations` package: version 1.20171123-0rcnee0~stretch+20171123 or later + +It's recommended to run the following commands to ensure you have the latest required packages: + +``` +sudo apt update +sudo apt upgrade bb-cape-overlays bb-customizations +``` + +### User permissions + +In order to be able to run code that accesses the eQEP modules as a regular user, as opposed to root, that user must be part of the `eqep` group. + +To check which users are part of the `eqep` group: + +``` +cat /etc/group | grep eqep +``` + +To add user `userName` to the `eqep` group (run this command as root): +``` +usermod -a -G eqep userName +``` + +Note: you will need to log out and log back in for the group membership change to take effect. + +### Capes + +In order to use all eQEP pins the BeagleBone must boot with the [cape-universal](https://github.com/beagleboard/bb.org-overlays/tree/master/tools/beaglebone-universal-io) enabled, and load the `cape-universal` overlay. + +This is the default, thus **no further steps are initially required to use eQEP0 and eQEP2**. Simply double-check that the following line is present and not commented out on your `/boot/uEnv.txt` file: + +``` +enable_uboot_cape_universal=1 +``` + +Note: Some older documentation recommends using the `cmdline` and `cape_enable` options instead. They are meant to load deprecated kernel-based overlays and it's not recommended to use them. Use the new way of [loading overlays via uboot](https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#U-Boot_Overlays) instead, as instructed above. + +#### Enabling additional eQEP modules + +The `cape-universal` overlay will enable access to the eQEP0 and eQEP2 modules. As it does not expose pins that are shared with the HDMI interface, eQEP1 and eQEP2b will **not** be available. + +To disable the HDMI interface and gain access to the pins and peripherals that share its pins, comment out the following line on the `/boot/uEnv.txt` file and reboot: + +``` +disable_uboot_overlay_video=1 +``` + +## eQEP configuraton + +Notes: + +- If either eQEP1 or eQEP2b are used on the Beaglebone Black, video must be disabled, as their pins are shared with the LCD_DATAx lines of the HDMI interface. +- eQEP2 and eQEP2b are the same module, but with the alternative of accessing it via two sets of pins. These are mutually exclusive. + +### eQEP0 + +Pins: `P9_27`, `P9_92` + +``` +$ config-pin P9_27 qep +$ config-pin P9_92 qep # alias for P9_42.1 +$ cat /sys/devices/platform/ocp/48300000.epwmss/48300180.eqep/position +``` + +### eQEP1 + +Pins: `P8.33`, `P8.35` + +``` +$ config-pin P8.33 qep +$ config-pin P8.35 qep +$ cat /sys/devices/platform/ocp/48302000.epwmss/48302180.eqep/position +``` + +### eQEP2 + +#### eQEP2 + +Pins: `P8.11`, `P8.12` + +``` +$ config-pin P8.11 qep +$ config-pin P8.12 qep +$ cat /sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position +``` + +#### eQEP2b + +Note: alternate pins for eQEP2 (mutually exclusive) + +Pins: `P8.41`, `P8.42` + +``` +$ config-pin P8.41 qep +$ config-pin P8.42 qep +$ cat /sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position +``` + +## Credits + +Initially based on the [PyBBIO](https://github.com/graycatlabs/PyBBIO/bbio/libraries/RotaryEncoder/rotary_encoder.py) rotary encoder code. + +## Further reading + +1. [Beaglebone encoder inputs](https://github.com/Teknoman117/beaglebot/tree/master/encoders) +1. [Beaglebone eQEP overlays](https://github.com/Teknoman117/beaglebot/tree/master/encoders/dts) diff --git a/Adafruit_BBIO/sysfs.py b/Adafruit_BBIO/sysfs.py new file mode 100644 index 0000000..f2273a1 --- /dev/null +++ b/Adafruit_BBIO/sysfs.py @@ -0,0 +1,118 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright (c) 2014 MIT OpenCourseWare +# Copyright (c) 2017 Adafruit Industries +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. +# +# Code originally published at http://stackoverflow.com/questions/4648792/ and +# subsequently forked at https://github.com/ponycloud/python-sysfs +# +# Original author: Benedikt Reinartz +# Contributors: +# - Jan Dvořák +# - Jonathon Reinhart https://github.com/JonathonReinhart +# - Ondřej Koch +# - David Planella + +""" +Simplistic Python SysFS interface. It enables access to the sys filesystem device +nodes and to get and set their exposed attributes. + +Usage examples:: + from sysfs import sys + + # Print all block devices in /sys, with their sizes + for block_dev in sys.block: + print(block_dev, str(int(block_dev.size) / 1048576) + ' M') + + >>> import sysfs + >>> # Read/write Beaglebone Black's eQEP module attributes + >>> eqep0 = sysfs.Node("/sys/devices/platform/ocp/48300000.epwmss/48300180.eqep") + >>> # Read eqep attributes + >>> eqep0.enabled + '1' + >>> eqep0.mode + '0' + >>> eqep0.period + '1000000000' + >>> eqep0.position + '0' + >>> # Write eqep attributes. They should be strings. + >>> eqep0.position = str(2) + >>> eqep0.position + '2' +""" + +from os import listdir +from os.path import isdir, isfile, join, realpath, basename + +__all__ = ['sys', 'Node'] + + +class Node(object): + __slots__ = ['_path_', '__dict__'] + + def __init__(self, path='/sys'): + self._path_ = realpath(path) + if not self._path_.startswith('/sys/') and not '/sys' == self._path_: + raise RuntimeError('Using this on non-sysfs files is dangerous!') + + self.__dict__.update(dict.fromkeys(listdir(self._path_))) + + def __repr__(self): + return '' % self._path_ + + def __str__(self): + return basename(self._path_) + + def __setattr__(self, name, val): + if name.startswith('_'): + return object.__setattr__(self, name, val) + + path = realpath(join(self._path_, name)) + if isfile(path): + with open(path, 'w') as fp: + fp.write(val) + else: + raise RuntimeError('Cannot write to non-files.') + + def __getattribute__(self, name): + if name.startswith('_'): + return object.__getattribute__(self, name) + + path = realpath(join(self._path_, name)) + if isfile(path): + with open(path, 'r') as fp: + return fp.read().strip() + elif isdir(path): + return Node(path) + + def __setitem__(self, name, val): + return setattr(self, name, val) + + def __getitem__(self, name): + return getattr(self, name) + + def __iter__(self): + return iter(getattr(self, name) for name in listdir(self._path_)) + + +sys = Node() diff --git a/Adafruit_I2C.py b/Adafruit_I2C.py index 742e59e..6a7a3bc 100644 --- a/Adafruit_I2C.py +++ b/Adafruit_I2C.py @@ -1,123 +1,13 @@ #!/usr/bin/python -import smbus - -# =========================================================================== -# Adafruit_I2C Class -# Adafruit_I2C.py is essentially a fork of the Adafruit Raspberry Pi I2C module. -# Any pull requests for this module should be directed to the following, and I -# can pull them. I'd rather not deviate from the original: -# https://github.com/adafruit/Adafruit-Raspberry-Pi-Python-Code/tree/master/Adafruit_I2C -# =========================================================================== +# WARNING: THIS MODULE IS DEPRECATED! +# use Adafruit_GPIO.I2C instead: +# https://github.com/adafruit/Adafruit_Python_GPIO/blob/master/Adafruit_GPIO/I2C.py class Adafruit_I2C : def __init__(self, address, busnum=-1, debug=False): - self.address = address - self.bus = smbus.SMBus(busnum if busnum >= 0 else 1) - self.debug = debug - - def reverseByteOrder(self, data): - "Reverses the byte order of an int (16-bit) or long (32-bit) value" - # Courtesy Vishal Sapre - byteCount = len(hex(data)[2:].replace('L','')[::2]) - val = 0 - for i in range(byteCount): - val = (val << 8) | (data & 0xff) - data >>= 8 - return val - - def errMsg(self): - print("Error accessing 0x%02X: Check your I2C address" % self.address) - return -1 - - def write8(self, reg, value): - "Writes an 8-bit value to the specified register/address" - try: - self.bus.write_byte_data(self.address, reg, value) - if self.debug: - print("I2C: Wrote 0x%02X to register 0x%02X" % (value, reg)) - except IOError as err: - return self.errMsg() - - def write16(self, reg, value): - "Writes a 16-bit value to the specified register/address pair" - try: - self.bus.write_word_data(self.address, reg, value) - if self.debug: - print("I2C: Wrote 0x%02X to register pair 0x%02X,0x%02X" % - (value, reg, reg+1)) - except IOError as err: - return self.errMsg() - - def writeList(self, reg, list): - "Writes an array of bytes using I2C format" - try: - if self.debug: - print("I2C: Writing list to register 0x%02X:" % reg) - print(list) - self.bus.write_i2c_block_data(self.address, reg, list) - except IOError as err: - return self.errMsg() - - def readList(self, reg, length): - "Read a list of bytes from the I2C device" - try: - results = self.bus.read_i2c_block_data(self.address, reg, length) - if self.debug: - print("I2C: Device 0x%02X returned the following from reg 0x%02X" % - (self.address, reg)) - print(results) - return results - except IOError as err: - return self.errMsg() - - def readU8(self, reg): - "Read an unsigned byte from the I2C device" - try: - result = self.bus.read_byte_data(self.address, reg) - if self.debug: - print("I2C: Device 0x%02X returned 0x%02X from reg 0x%02X" % - (self.address, result & 0xFF, reg)) - return result - except IOError as err: - return self.errMsg() - - def readS8(self, reg): - "Reads a signed byte from the I2C device" - try: - result = self.bus.read_byte_data(self.address, reg) - if result > 127: result -= 256 - if self.debug: - print("I2C: Device 0x%02X returned 0x%02X from reg 0x%02X" % - (self.address, result & 0xFF, reg)) - return result - except IOError as err: - return self.errMsg() - - def readU16(self, reg): - "Reads an unsigned 16-bit value from the I2C device" - try: - result = self.bus.read_word_data(self.address,reg) - if (self.debug): - print("I2C: Device 0x%02X returned 0x%04X from reg 0x%02X" % (self.address, result & 0xFFFF, reg)) - return result - except IOError as err: - return self.errMsg() - - def readS16(self, reg): - "Reads a signed 16-bit value from the I2C device" - try: - result = self.bus.read_word_data(self.address,reg) - if (self.debug): - print("I2C: Device 0x%02X returned 0x%04X from reg 0x%02X" % (self.address, result & 0xFFFF, reg)) - return result - except IOError as err: - return self.errMsg() + print("WARNING: THIS MODULE IS DEPRECATED. Use Adafruit_GPIO.I2C instead.\n"); if __name__ == '__main__': - try: - bus = Adafruit_I2C(address=0) - print("Default I2C bus is accessible") - except: - print("Error accessing default I2C bus") + print("WARNING: THIS MODULE IS DEPRECATED. Use Adafruit_GPIO.I2C instead.\n"); diff --git a/CHANGELOG.md b/CHANGELOG.md index b3cdcd6..4f9325e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,249 @@ +1.1.2 +--- +Daniel Nguyen (2): + Update common.c + Update common.c + +Drew Fustini (28): + upload to PyPI againt to resolve #293 + do not set pinmux on the beaglebone blue + remove deug output + Fix dead link to bone.js #296 + force Encoder period to be an integer #299 + Ignore new compiler warnings in gcc 8.2.0 + Update setup.py + do not set pin mode for built-in USRn LEDs + Change name of P1_3 to match bone.js + Fix warning about casting incompatible function types #308 + Fix warning print format strings being truncated #308 + Fix warning about casting incompatible function types #308 + Fix warnings on format truncation and sizeof in strncpy #308 + Fix warning about casting incompatible function types #308 + Update travis config to specify Python 3.6 + Update tox.ini to Python 3.6 + Merge pull request #321 from adafruit/issue308 + Update ISSUE_TEMPLATE.md + Update README.md + Update README.md + Merge pull request #327 from zer0cod3r/master + Merge pull request #337 from SamPovilus/docfix + Update README.md + Update README.md + Update README.md + remove -Werror from CFLAGS + Remove suppression of gcc warnings in CFLAGS #336 + Update version in setup.py to v1.2 + +Sam Povilus (1): + fixing document locaiton and version as current location dosn't load + +1.1.1 +--- +Attempt upload to PyPI again to avoid +error reported in issue #293 + +1.1.0 +--- +Aaron Marburg (1): + * Added usleep after successfully enabling PWM via udev. + +Drew Fustini (16): + * Merge pull request #233 from zsserg/fixed_segfault_in_event_detection + * Merge pull request #257 from zsserg/develop + * Merge pull request #251 from amarburg/master + * Merge pull request #271 from fcooper/documentation-updates + * Update ADC.rst + * Update Encoder.rst + * Update ADC.rst + * Add UART entries for the PocketBeagle (issue #242) + * update install and test shell scripts + * update UART section in README + * Merge pull request #282 from erikwelsh/master + * do not load overlays for the beaglebone blue #283 + * Merge pull request #284 from sam-bristow/py3-docs + * Merge pull request #285 from sam-bristow/bugfix/uart-error-reporting + * fix pwm on pocketbeagle and beaglebone blue #286 + * remove debug logging + +Erik Welsh (1): + * Fixed GPIO export problem; Leaves GPIO in bad state on latest BeagleBone image on PocketBeagle + +Franklin S Cooper Jr (3): + * docs/SPI.rst: Fix bus numbering in examples + * docs/GPIO.rst: Add information on blinking led + * docs/GPIO.rst Make documentation a bit newbie friendly + +Sam Bristow (3): + * Use print() function in all code and docs + * Use new python-serial API + * Return error-code for failing interface + +zserg (5): + * Fixed SEGFAULT when calling remove_event_detect() inside python callback function. + * Fixed SEGFAULT when calling remove_event_detect() inside python callback function. + * Fixed SEGFAULT in event_gpio,c run_callbacks() * Added more elaborate epoll() error logging + * Minor style fixes + +1.0.10 +---- +**features** +* automatically set pin modes for UART (PR #158) +* Encoder: README.md: added note about eqep group change (PR #214) +* deprecate out of date Adafruit_I2C.py (PR #215) +* Add Encoder module info to main README.md (PR #217) +* Add automatic API documentation generation (PR #219) +* Separate API docs into modules (PR #221) + +**shortlog** +* David Planella (46): + * Encoder: README.md: added note about eqep group change + * Add Encoder module info to main README.md + * Added docstrings using Google syntax and Sphinx support to generate the API documentation for the Encoder and PWM modules for now. + * Made kernel version check to happen only if running on a beaglebone. The readthedocs builders that import the Encoder module have an old 3.3 kernel and the autodoc build fails + * Use the default readthedocs theme + * Use readthedocs theme if building docs there, remove redundand search link + * Readthedocs theme tweaks + * Removed redundant TOC, added global description + * Added UART documentation + * Added documentation badge + * Added ADC API docs, fixed UART module definition + * API docs: added SPI module + * Added SPI module attribute docs + * Added Python badges to README file + * Added SPI pins table and first shot at GPIO module. Functions still need to be documented + * Merge branch 'readthedocs' of https://github.com/dplanella/adafruit-beaglebone-io-python into readthedocs + * Documented the API docs build process + * Added docstrings using Google syntax and Sphinx support to generate the API documentation for the Encoder and PWM modules for now. + * Made kernel version check to happen only if running on a beaglebone. The readthedocs builders that import the Encoder module have an old 3.3 kernel and the autodoc build fails + * Use the default readthedocs theme + * Use readthedocs theme if building docs there, remove redundand search link + * Readthedocs theme tweaks + * Removed redundant TOC, added global description + * Added UART documentation + * Added documentation badge + * Added ADC API docs, fixed UART module definition + * API docs: added SPI module + * Added SPI module attribute docs + * Added Python badges to README file + * Added SPI pins table and first shot at GPIO module. Functions still need to be documented + * Documented the API docs build process + * Merge branch 'readthedocs' of https://github.com/dplanella/adafruit-beaglebone-io-python into readthedocs + * Update README.md + * Added some more API doc content + * Sync from upstream master + * Minor documentation and configuration improvements + * Finished documenting GPIO + * rST fixes + * Update README.md + * Minor API doc improvements + * Merge branch 'readthedocs' of https://github.com/dplanella/adafruit-beaglebone-io-python into readthedocs + * Generate the API documentation from a master index and a separate file for each module + * Sync from upstream master + * Improvements to the API docs output config + * Update docs generation description to reflect new separate modules + * Updated ADC API docs + +* Drew Fustini (10): + * use set_pin_mode() to set uart pinmux (#158) + * Add SPI instructions to README (#158) + * Update README.md + * Fix spidev path mismatch (#216) + * Merge pull request #217 from dplanella/patch-2 + * Merge pull request #214 from dplanella/patch-1 + * Deprecate Adafruit_BBIO.I2C in favor of Adafruit_GPIO.I2C (#215) + * Merge pull request #219 from dplanella/readthedocs + * relocate doc dir to avoid confusion (#218) + * Merge pull request #221 from dplanella/readthedocs + + +1.0.9 +---- +**Features:** +* Issue #194: Encoder position cannot be set +* PR #205: Encoder: add support for reading/writing sysfs attributes + +**Fixes:** +* Issue #198: use https for DEFAULT_URL in distribute_setup.py +* Issue #197: Fix leak of pwm enable file descriptor +* Issue #189: Fix seg fault of PWM in Python 3.6 +* Issue #180: Clarify there is no 0 prefix for pin lables +* PR #201: Encoder: do kernel check, PEP8 cleanup +* PR #202: Encoder: corrected kernel check logic +* PR #207: Encoder: improved usage documentation +* PR #210: Encoder: fix sysfs import, make code Python 3 compatible +* PR #212: Encoder: fix Python 3 compatibility +* PR #213: Encoder: fix frequency calculation from period + +**shortlog:** +* David Planella (18): + * Encoder: initialize only the given channel + * Sync from master + * Encoder: do kernel check, PEP8 cleanup + * Encoder: added sysfs module + * Encoder: use sysfs to write QEP attributes + * Encoder: corrected kernel check logic + * Merge pull request #2 from adafruit/master + * Encoder: convert get/set methods to properties, update apidoc strings + * Encoder: updated README + * Encoder: add README apt install clarification + * Encoder: copyright assignment note, updated comments + * Encoder: added usage notes + * Encoder: improved usage documentation + * Encoder: minor fix to usage example + * Encoder: added a note about permissions + * Encoder: switched sysfs to be a relative import compatible with Python 2 and 3 + * Encoder: use items() instead of iteritems() to be Python 3 compatible + * Encoder: fix frequency getter + +* Drew Fustini (18): + * use https for DEFAULT_URL in distribute_setup.py (#198) + * fix except syntax for Python 3 + * use dict.items() instead of dict.iteritems() for Python 3 + * fix error in set_brightness() + * close enable_fd when stopping PWM output (#197) + * Merge pull request #199 from dplanella/patch-1 + * Fix leak of pwm enable file descriptor (#197) + * Merge pull request #201 from dplanella/encoder-cleanup + * remove test_rotary.py as not valid for pytest + * Fix seg fault of PWM in Python 3.6 (#189) + * Merge pull request #202 from dplanella/patch-2 + * Clarify there is no 0 prefix for pin lables (#180) + * Merge pull request #205 from dplanella/encoder-sysfs + * assign copyright for new file to Adafruit Industries + * Add bash scripts to help install and test + * Merge pull request #212 from dplanella/patch-4 + * Merge pull request #207 from dplanella/patch-3 + * Merge pull request #213 from dplanella/fix-encoder-frequency + +1.0.8 +---- +**Fixes:** +* Issue #196: cache board type to avoid poor performance +* Issue #192: fix PocketBeagle PWM pin typo +* Issue #191: turn off RotaryEncoder's debug output by default +* Issue #188: GPIO is extremely slow (20ms to toggle) +* Issue #186: problems with UART + +**shortlog:** +* David Planella (12): + * Copy Encoder module comments to README.md + * Formatted Encoder README in markdown + * Fixed Encoder README formatting + * Removed QEP instructions from Encoder module + * Fixes to Encoder README + * Updated Encoder README + * Encoder README: added info on dedicated overlays + * Encoder README: updated info on pre-requisites + * Encoder README update + * Encoder README update + * Add logging support, turn off unconditional debug output + * Encoder: remove unused logging code + +* Drew Fustini (3): + * Merge pull request #195 from dplanella/master + * Fix PocketBeagle PWM pin typo (#192) + * cache board type to avoid poor performance (#196) + 1.0.7 ---- **Fixes:** diff --git a/README.md b/README.md index 32da985..fba6863 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,65 @@ -# 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) and [UART](README.md#uart) 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)** - * Install [Linux kernel](https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#Kernel_Options) [4.14.x](https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#Mainline_.284.14.x_lts.29) to enable [non-root control of GPIO](https://github.com/rcn-ee/repos/blob/master/bb-customizations/suite/stretch/debian/80-gpio-noroot.rules) and [PWM](https://github.com/rcn-ee/repos/blob/master/bb-customizations/suite/stretch/debian/81-pwm-noroot.rules) [_(commit)_](https://github.com/adafruit/adafruit-beaglebone-io-python/commit/b65cbf8e41b444bad7c4ef6cfd4f88a30210fd78) + * **Currently recommended image: [Debian 10.3 "Buster" IoT (2020-04-06)](http://beagleboard.org/latest-images)** _(default kernel is 4.19.x-ti)_ -* Adafruit_BBIO supports Linux kernels 3.8 through 4.14 +* Adafruit_BBIO supports Linux kernels 3.8 through 4.19 * New versions of Adafruit_BBIO may break backwards compatibility. Please read the [changelog](CHANGELOG.md). +* It is recommended to use Python 3 + ## Installation on Debian -Easiest: +Note: Follow the instructions on BeagleBoard.org to [get connected to the Internet](https://beagleboard.org/upgrade#connect) + +**Easiest:** ``` -sudo ntpdate pool.ntp.org sudo apt-get update -sudo apt-get install build-essential python-dev python-pip -y -sudo pip install Adafruit_BBIO +sudo apt-get install build-essential python3-dev python3-pip -y +sudo pip3 install Adafruit_BBIO ``` -Manual: +**Manual:** ``` -sudo ntpdate pool.ntp.org sudo apt-get update -sudo apt-get install build-essential python-dev python-pip -y +sudo apt-get install build-essential python3-dev python3-pip -y git clone git://github.com/adafruit/adafruit-beaglebone-io-python.git cd adafruit-beaglebone-io-python -sudo python setup.py install +sudo python3 setup.py install ``` Upgrade Adafruit_BBIO to latest version on [PyPI](https://pypi.python.org/pypi/Adafruit_BBIO): ``` -sudo pip install --upgrade Adafruit_BBIO +sudo pip3 install --upgrade Adafruit_BBIO ``` ## Usage Using the library is very similar to the excellent RPi.GPIO library used on the Raspberry Pi. Below are some examples. +### Pin Numbers + +Please note that there is no '0' prefix for the pin numbers. For example, pin 7 on header P8 is `P8_7`. + +**Correct:** +``` +GPIO.setup("P8_7", OUT ) +``` + +**INCORRECT:** +``` +GPIO.setup("P8_07", OUT ) +``` + +Refer to `pins_t table[]` in [common.c](https://github.com/adafruit/adafruit-beaglebone-io-python/blob/master/source/common.c#L73) all the pin labels. + ### config-pin [config-pin](https://github.com/beagleboard/bb.org-overlays/tree/master/tools/beaglebone-universal-io) is now used on the official BeagleBoard.org Debian Jessie and Stretch images to control pin mode (e.g. pin mux). @@ -130,7 +151,7 @@ Detecting events: #your amazing code here #detect wherever: if GPIO.event_detected("P9_12"): - print "event detected!" + print("event detected!") ### PWM **The PWM Duty Cycle range was reversed in 0.0.15 from 100(off)-0(on) to 0(off)-100(on). Please update your code accordingly.** @@ -178,27 +199,92 @@ 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() +with serial.Serial(port = "/dev/ttyO1", baudrate=9600) as ser: + print("Serial is open!") + ser.write(b"Hello World!") + ``` +* Available UART names on BeagleBone + * `UART1`: /dev/ttyO1, Rx: P9_26, Tx: P9_24 + * `UART2`: /dev/ttyO2, Rx: P9_22, Tx: P9_21 + * `UART4`: /dev/ttyO4, Rx: P9_11, Tx: P9_13 + * `UART5`: /dev/ttyO5, Rx: P8_38, Tx: P8_37 + * note: `UART5` requires `disable_uboot_overlay_video=1` in `/boot/uEnv.txt` +* Available UART names on PocketBeagle + * `PB-UART0`: /dev/ttyO0, Rx: P1_30, Tx: P1_32 + * `PB-UART1`: /dev/ttyO1, Rx: P2_11, Tx: P2_09 + * `PB-UART2`: /dev/ttyO2, Rx: P1_08, Tx: P1_10 * [Loopback test with UART1 and UART2](https://learn.adafruit.com/setting-up-io-python-library-on-beaglebone-black/uart#testing-and-using-the-uart) + +### [SPI](https://learn.adafruit.com/setting-up-io-python-library-on-beaglebone-black/spi) +* Use [`config-pin` to set pin mode](https://github.com/beagleboard/bb.org-overlays/tree/master/tools/beaglebone-universal-io) for [SPI pins](http://beagleboard.org/static/images/cape-headers-spi.png) + * SPI0 + * SPI0_CS0: `config-pin p9.17 spi_cs` + * SPI0_D0: `config-pin p9.21 spi` + * SPI0_D1: `config-pin p9.18 spi` + * SPI0_SCLK: `config-pin p9.22 spi_sclk` + * SPI1 + * SPI1_CS0: `config-pin p9.20 spi_cs` + * SPI1_CS0: `config-pin p9.28 spi_cs` + * SPI1_CS1: `config-pin p9.19 spi_cs` + * SPI1_CS1: `config-pin p9.42 spi_cs` + * SPI1_D0: `config-pin p9.29 spi` + * SPI1_D1: `config-pin p9.30 spi` + * SPI1_SCLK: `config-pin p9.31 spi_sclk` +* Example: +``` +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() +``` + +### eQEP + +To use the enhanced Quadrature Encoder Pulse (eQEP) module, please refer to the [`Encoder` module's documentation](https://github.com/adafruit/adafruit-beaglebone-io-python/tree/master/Adafruit_BBIO#usage). + ## Running tests Install py.test to run the tests. You'll also need the python compiler package for pytest: ``` -sudo pip install pytest +sudo pip3 install pytest ``` Execute the following in the root of the project: ``` -sudo pytest +pytest ``` -NOTE: `sudo` should not be required when running [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) with [Linux kernel](https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#Kernel_Options) [4.14.x](https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#Mainline_.284.14.x_lts.29) as udev configures group ownership and permission for [GPIO](https://github.com/rcn-ee/repos/blob/master/bb-customizations/suite/stretch/debian/80-gpio-noroot.rules) and [PWM](https://github.com/rcn-ee/repos/blob/master/bb-customizations/suite/stretch/debian/81-pwm-noroot.rules) +NOTE: `sudo` should not be required as udev configures group ownership and permission for [GPIO](https://github.com/rcn-ee/repos/blob/master/bb-customizations/suite/stretch/debian/80-gpio-noroot.rules) and [PWM](https://github.com/rcn-ee/repos/blob/master/bb-customizations/suite/stretch/debian/81-pwm-noroot.rules) + +## Reporting issues + +When reporting issues, plesae run the following script which will print the system configuration: +``` +sudo /opt/scripts/tools/version.sh +``` +and paste the output in a reply. + +This script should be present for any Debian or Ubunut image downloaded from: +https://beagleboard.org/ or https://rcn-ee.com/ + ## Credits diff --git a/distribute_setup.py b/distribute_setup.py index c67b752..5b31634 100644 --- a/distribute_setup.py +++ b/distribute_setup.py @@ -50,7 +50,7 @@ def quote(arg): return os.spawnl(os.P_WAIT, sys.executable, *args) == 0 DEFAULT_VERSION = "0.6.45" -DEFAULT_URL = "http://pypi.python.org/packages/source/d/distribute/" +DEFAULT_URL = "https://pypi.python.org/packages/source/d/distribute/" SETUPTOOLS_FAKED_VERSION = "0.6c11" SETUPTOOLS_PKG_INFO = """\ diff --git a/docs/ADC.rst b/docs/ADC.rst new file mode 100644 index 0000000..dc9c64c --- /dev/null +++ b/docs/ADC.rst @@ -0,0 +1,45 @@ +:mod:`ADC` --- A/D Converter input interface +-------------------------------------------- + +This module enables reading analog input values from the analog to digital +converter (ADC) on the TI AM3358 SoC on the BeagleBone. + +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 from 0 to 4095 + value = ADC.read_raw("P9_40") + +.. module:: Adafruit_BBIO.ADC + +.. function:: setup_adc() + + Setup and start the ADC hardware. + +.. function:: setup_read(channel) + + Read the normalized analog value for the channel. + + :param str channel: GPIO channel to read the value from (e.g. "P8_16"). + :returns: normalized value reading from 0.0 to 1.0 + :rtype: float + + +.. function:: setup_read_raw(channel) + + Read the raw analog value for the channel. + + :note: Kernels older than 4.1.x returned a raw value range 0 - 1800 + based on the reference voltage of 1.8 V. + + :param str channel: GPIO channel to read the value from (e.g. "P8_16"). + :returns: raw value reading from 0 to 4095 (12 bits). + :rtype: float + + diff --git a/docs/Encoder.rst b/docs/Encoder.rst new file mode 100644 index 0000000..364eee3 --- /dev/null +++ b/docs/Encoder.rst @@ -0,0 +1,5 @@ +:mod:`Encoder` --- Quadrature Encoder interface (eQEP) +----------------------------------------------- + +.. automodule:: Adafruit_BBIO.Encoder + :members: diff --git a/docs/GPIO.rst b/docs/GPIO.rst new file mode 100644 index 0000000..70be0a1 --- /dev/null +++ b/docs/GPIO.rst @@ -0,0 +1,221 @@ +: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 `_ + + +.. note:: + + On-board LEDs (USR0-USR3) are handled by LED class driver rather than the GPIO pin driver. + + They have a different path in the /sys/ filesystem. + + Setup the pin for output and write GPIO.HIGH or GPIO.LOW + +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 + + + # Blinking onboard led example + import Adafruit_BBIO.GPIO as GPIO + import time + + for i in range(4): + GPIO.setup("USR%d" % i, GPIO.OUT) + + while True: + for i in range(4): + GPIO.output("USR%d" % i, GPIO.HIGH) + time.sleep(1) + for i in range(4): + GPIO.output("USR%d" % i, GPIO.LOW) + time.sleep(1) + + +.. module:: Adafruit_BBIO.GPIO + +.. function:: setup(channel, direction[, pull_up_down=GPIO.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:`GPIO.IN` or :data:`GPIO.OUT`). + :param int pull_up_down: pull-up/pull-down resistor configuration + (:data:`GPIO.PUD_OFF`, :data:`GPIO.PUD_UP` or :data:`GPIO.PUD_DOWN`). + :param int initial: initial value for an output channel + (:data:`GPIO.LOW`/:data:`GPIO.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:`GPIO.LOW`/:data:`GPIO.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:`GPIO.RISING`, :data:`GPIO.FALLING` + or :data:`GPIO.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:`GPIO.RISING`, :data:`GPIO.FALLING` + or :data:`GPIO.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. + 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/PWM.rst b/docs/PWM.rst new file mode 100644 index 0000000..95d428a --- /dev/null +++ b/docs/PWM.rst @@ -0,0 +1,62 @@ +: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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..828f2c3 --- /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 files in reStructuredText format. + +``` +├── conf.py <- Sphinx configuration file +├── index.rst <- Documentation will be generated based on the master index +└── 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). Readthedocs automatically executes Sphinx via webhooks triggered by Github commits, and publishes the resulting docs for all tracked branches or tags. Generally Readthedocs will be set up to track stable release tags and the master branch. + +## 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 or tag 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 separate `.rst` files (one for each Python module) 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 add a significant maintenance overhead. + +- The documentation in the `.rst` files 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/SPI.rst b/docs/SPI.rst new file mode 100644 index 0000000..fcf4bf6 --- /dev/null +++ b/docs/SPI.rst @@ -0,0 +1,134 @@ +: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(0, 0) + print(spi.xfer2([32, 11, 110, 22, 220])) + spi.close() + + # /dev/spidev0.1 + spi = SPI(0, 1) + print(spi.xfer2([32, 11, 110, 22, 220])) + spi.close() + + # /dev/spidev1.0 + spi = SPI(1, 0) + print(spi.xfer2([32, 11, 110, 22, 220])) + spi.close() + + # /dev/spidev1.1 + spi = SPI(1, 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] + diff --git a/docs/UART.rst b/docs/UART.rst new file mode 100644 index 0000000..c3d238d --- /dev/null +++ b/docs/UART.rst @@ -0,0 +1,35 @@ +: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") + + with serial.Serial(port = "/dev/ttyO1", baudrate=9600) as ser: + print("Serial is open!") + ser.write(b"Hello World!") + +.. 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. + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..6dfd6ad --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,190 @@ +# -*- 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, or +# use a Sphinx theme if the documentation is being built locally +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' + ] + } + # If you want to use the same theme as readthedocs, uncomment the lines + # below and install the readthedocs theme (pip install sphinx_rtd_theme) + # before doing a new build: + #html_theme = 'sphinx_rtd_theme' + #html_theme_options = { + # 'collapse_navigation': False, + #} + +# Do not show the "View source" link that shows the .rst files +html_copy_source = False +html_show_sourcelink = False + +# -- 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..a663628 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,29 @@ +.. 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. + +Adafruit Beaglebone IO Python API +================================= + +The Adafruit Beaglebone IO API enables access to the Beaglebone's GPIO, PWM, +ADC, UART, SPI and eQEP hardware modules from Python programs. + +.. toctree:: + :maxdepth: 4 + :caption: Contents + + ADC + Encoder + GPIO + PWM + SPI + UART + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` + + diff --git a/install_all_python_versions.sh b/install_all_python_versions.sh new file mode 100755 index 0000000..cc19011 --- /dev/null +++ b/install_all_python_versions.sh @@ -0,0 +1,7 @@ +#!/bin/bash +# useful for testing changes against all versions of python +make clean +echo "Install Python 2" +python2 ./setup.py install +echo "Install Python 3" +python3 ./setup.py install diff --git a/pytest_all_versions.sh b/pytest_all_versions.sh new file mode 100755 index 0000000..76d46e6 --- /dev/null +++ b/pytest_all_versions.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# useful for testing changes against all versions of python + +cd test +echo "Testing Python 2" +python2 -mpytest +echo "Testing Python 3" +python3 -mpytest +cd .. diff --git a/setup.py b/setup.py index 3e9b78b..a6f5891 100644 --- a/setup.py +++ b/setup.py @@ -21,7 +21,7 @@ else: kernel41 = None -CFLAGS = ['-Wall', '-Werror', '-Wextra', '-Wno-missing-field-initializers', '-Wno-strict-aliasing' ] +CFLAGS = ['-Wall'] classifiers = ['Development Status :: 3 - Alpha', 'Operating System :: POSIX :: Linux', @@ -40,11 +40,12 @@ } setup(name = 'Adafruit_BBIO', - version = '1.0.7', + version = '1.2.0', author = 'Justin Cooper', author_email = 'justin@adafruit.com', description = 'A module to control BeagleBone IO channels', long_description = open_as_utf8('README.md').read() + open_as_utf8('CHANGELOG.md').read(), + long_description_content_type = 'text/markdown', license = 'MIT', keywords = 'Adafruit BeagleBone IO GPIO PWM ADC', url = 'https://github.com/adafruit/adafruit-beaglebone-io-python/', @@ -54,6 +55,6 @@ ext_modules = [Extension('Adafruit_BBIO.GPIO', ['source/py_gpio.c', 'source/event_gpio.c', 'source/c_pinmux.c', 'source/constants.c', 'source/common.c'], **extension_args), Extension('Adafruit_BBIO.PWM', ['source/py_pwm.c', 'source/c_pwm.c', 'source/c_pinmux.c', 'source/constants.c', 'source/common.c'], **extension_args), Extension('Adafruit_BBIO.ADC', ['source/py_adc.c', 'source/c_adc.c', 'source/constants.c', 'source/common.c'], **extension_args), - Extension('Adafruit_BBIO.SPI', ['source/spimodule.c', 'source/constants.c', 'source/common.c'], **extension_args), - Extension('Adafruit_BBIO.UART', ['source/py_uart.c', 'source/c_uart.c', 'source/constants.c', 'source/common.c'], **extension_args)] ) + Extension('Adafruit_BBIO.SPI', ['source/spimodule.c', 'source/c_pinmux.c', 'source/constants.c', 'source/common.c'], **extension_args), + Extension('Adafruit_BBIO.UART', ['source/py_uart.c', 'source/c_pinmux.c', 'source/c_uart.c', 'source/constants.c', 'source/common.c'], **extension_args)] ) diff --git a/source/c_adc.c b/source/c_adc.c index 21ad284..d496366 100644 --- a/source/c_adc.c +++ b/source/c_adc.c @@ -41,9 +41,9 @@ int adc_initialized = 0; BBIO_err initialize_adc(void) { #ifdef BBBVERSION41 - char test_path[49]; + char test_path[149]; #else - char test_path[40]; + char test_path[140]; #endif FILE *fh; BBIO_err err; @@ -94,10 +94,10 @@ BBIO_err read_value(unsigned int ain, float *value) { FILE * fh; #ifdef BBBVERSION41 - char ain_path[49]; + char ain_path[149]; snprintf(ain_path, sizeof(ain_path), "%s%d_raw", adc_prefix_dir, ain); #else - char ain_path[40]; + char ain_path[140]; snprintf(ain_path, sizeof(ain_path), "%s%d", adc_prefix_dir, ain); #endif diff --git a/source/c_pinmux.c b/source/c_pinmux.c index 6932ec6..23f1030 100644 --- a/source/c_pinmux.c +++ b/source/c_pinmux.c @@ -9,11 +9,16 @@ BBIO_err set_pin_mode(const char *key, const char *mode) { // char ocp_dir[] defined in common.h - char path[60]; // "/sys/devices/platform/ocp/ocp:P#_##_pinmux/state" + char path[100]; // "/sys/devices/platform/ocp/ocp:P#_##_pinmux/state" char pinmux_dir[20]; // "ocp:P#_##_pinmux" char pin[6]; //"P#_##" FILE *f = NULL; - + + // pin mode can not be set for the built-in USRn LEDs + if (strncmp(key, "USR", 3) == 0) { + return BBIO_OK; + } + if (strlen(key) == 4) // Key P#_# format, must inject '0' to be P#_0# snprintf(pin, sizeof(pin), "%.3s0%c", key,key[3]); else //copy string @@ -32,6 +37,14 @@ BBIO_err set_pin_mode(const char *key, const char *mode) snprintf(pinmux_dir, sizeof(pinmux_dir), "ocp:%s_pinmux", pin); snprintf(path, sizeof(path), "%s/%s/state", ocp_dir, pinmux_dir); + /* beaglebone blue has complete dtb file and does not need overlays */ + if(beaglebone_blue()) { + fprintf(stderr, "DEBUG: Adafruit_BBIO: set_pin_mode() :: Pinmux file: %s, mode: %s", path, mode); + fprintf(stderr, "DEBUG: Adafruit_BBIO: set_pin_mode(): beaglebone_blue() is TRUE; return BBIO_OK\n"); + return BBIO_OK; + } + + f = fopen(path, "w"); if (NULL == f) { return BBIO_ACCESS; diff --git a/source/c_pwm.c b/source/c_pwm.c index 55afd09..a5ef5ec 100644 --- a/source/c_pwm.c +++ b/source/c_pwm.c @@ -94,6 +94,14 @@ void export_pwm(struct pwm_exp *new_pwm) } } +int is_dmtimer_pin(pwm_t *p) { + char temp[6]; + strncpy(temp, p->module, 5); + temp[5] = '\0'; + + return (strcmp(temp, "timer") == 0); +} + BBIO_err initialize_pwm(void) { #ifdef BBBVERSION41 // don't load overlay in 4.1+ @@ -119,7 +127,7 @@ BBIO_err initialize_pwm(void) BBIO_err pwm_set_frequency(const char *key, float freq) { int len; - char buffer[20]; + char buffer[100]; unsigned long period_ns; struct pwm_exp *pwm; @@ -195,7 +203,7 @@ BBIO_err pwm_set_frequency(const char *key, float freq) { // Only works before chip is enabled BBIO_err pwm_set_polarity(const char *key, int polarity) { int len; - char buffer[9]; /* allow room for trailing NUL byte */ + char buffer[100]; /* allow room for trailing NUL byte */ struct pwm_exp *pwm; #ifdef BBBVERSION41 int enabled; /* Maintain original state */ @@ -275,7 +283,7 @@ BBIO_err pwm_set_polarity(const char *key, int polarity) { BBIO_err pwm_set_duty_cycle(const char *key, float duty) { int len; - char buffer[20]; + char buffer[100]; struct pwm_exp *pwm; if (duty < 0.0 || duty > 100.0) @@ -309,17 +317,17 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri struct pwm_exp *new_pwm; #ifdef BBBVERSION41 - char pwm_dev_path[45]; // "/sys/devices/platform/ocp/48300000.epwmss" - char pwm_addr_path[60]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm" - char pwm_chip_path[75]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0" - char pwm_export_path[80]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/export" - char pwm_path[85]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/pwm1" - char pwm_path_udev[85]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/pwm-0:1" - char ecap_path_udev[85];// "/sys/devices/platform/ocp/48300000.epwmss/48300100.ecap/pwm/pwmchip0/pwm-0:0/" - char duty_path[95]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/pwm1/duty_cycle" - char period_path[95]; - char polarity_path[95]; - char enable_path[90]; + char pwm_dev_path[100]; // "/sys/devices/platform/ocp/48300000.epwmss" + char pwm_addr_path[150]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm" + char pwm_chip_path[200]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0" + char pwm_export_path[250]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/export" + char pwm_path[250]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/pwm2" + char pwm_path_udev[250]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/pwm-0:2" + char ecap_path_udev[300]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ecap/pwm/pwmchip0/pwm-0:0/" + char duty_path[300]; // "/sys/devices/platform/ocp/48300000.epwmss/48300200.ehrpwm/pwm/pwmchip0/pwm2/duty_cycle" + char period_path[300]; + char polarity_path[300]; + char enable_path[300]; char pin_mode[PIN_MODE_LEN]; // "pwm" or "pwm2" int e; @@ -338,6 +346,10 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri // Make sure that one of the universal capes is loaded if( !uboot_overlay_enabled() // only check kernel overlays if u-boot overlays are not being used + && + !beaglebone_blue() // beaglebone blue has complete dtb file and does not need overlays + && + !pocketbeagle() // pocketbeagle has complete dtb file and does not need overlays && !( device_tree_loaded("cape-univ-audio") // from cdsteinkuehler/beaglebone-universal-io || device_tree_loaded("cape-univ-emmc") // "" @@ -371,16 +383,27 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri return err; } - err = build_path(ocp_dir, p->chip, pwm_dev_path, sizeof(pwm_dev_path)); - if (err != BBIO_OK) { - syslog(LOG_ERR, "Adafruit_BBIO: pwm_setup: %s couldn't build pwm_dev_path: %i", key, err); - return err; - } + int dmtimer_pin = is_dmtimer_pin(p); - err = build_path(pwm_dev_path, p->addr, pwm_addr_path, sizeof(pwm_addr_path)); - if (err != BBIO_OK) { - syslog(LOG_ERR, "Adafruit_BBIO: pwm_setup: %s couldn't build pwm_addr_path: %i", key, err); - return err; + if(!dmtimer_pin) { + err = build_path(ocp_dir, p->chip, pwm_dev_path, sizeof(pwm_dev_path)); + if (err != BBIO_OK) { + syslog(LOG_ERR, "Adafruit_BBIO: pwm_setup: %s couldn't build pwm_dev_path: %i", key, err); + return err; + } + + err = build_path(pwm_dev_path, p->addr, pwm_addr_path, sizeof(pwm_addr_path)); + if (err != BBIO_OK) { + syslog(LOG_ERR, "Adafruit_BBIO: pwm_setup: %s couldn't build pwm_addr_path: %i", key, err); + return err; + } + } + else { + err = build_path("/sys/devices/platform", p->addr, pwm_addr_path, sizeof(pwm_addr_path)); + if (err != BBIO_OK) { + syslog(LOG_ERR, "Adafruit_BBIO: pwm_setup: %s couldn't build pwm_addr_path, are you sure you've loaded the correct dmtimer device tree overlay?: %i", key, err); + return err; + } } err = build_path(pwm_addr_path, "pwm/pwmchip", pwm_chip_path, sizeof(pwm_chip_path)); @@ -393,10 +416,10 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri syslog(LOG_DEBUG, "Adafruit_BBIO: pwm_start: key: %s, pwm_path: %s", key, pwm_path); //pwm with udev patch - snprintf(pwm_path_udev, sizeof(pwm_path_udev), "%s/pwm-%c:%d", pwm_chip_path, pwm_path[66], p->index); + snprintf(pwm_path_udev, sizeof(pwm_path_udev), "%s/pwm-%c:%d", pwm_chip_path, dmtimer_pin ? pwm_path[47] : pwm_path[66], p->index); syslog(LOG_DEBUG, "Adafruit_BBIO: pwm_start: key: %s, pwm_path_udev: %s", key, pwm_path_udev); //ecap output with udev patch - snprintf(ecap_path_udev, sizeof(ecap_path_udev), "%s/pwm-%c:%d", pwm_chip_path, pwm_path[67], p->index); + snprintf(ecap_path_udev, sizeof(ecap_path_udev), "%s/pwm-%c:%d", pwm_chip_path, dmtimer_pin ? pwm_path[47] : pwm_path[67], p->index); syslog(LOG_DEBUG, "Adafruit_BBIO: pwm_start: key: %s, ecap_path_udev: %s", key, ecap_path_udev); // Export PWM if hasn't already been @@ -452,11 +475,12 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri return BBIO_GEN; } } else { - strncpy(pwm_path, ecap_path_udev, sizeof(ecap_path_udev)); + strncpy(pwm_path, ecap_path_udev, sizeof(pwm_path)); } } } else { - strncpy(pwm_path, pwm_path_udev, sizeof(pwm_path_udev)); + strncpy(pwm_path, pwm_path_udev, sizeof(pwm_path)); + usleep(100*1000); } } } @@ -465,12 +489,12 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri snprintf(duty_path, sizeof(duty_path), "%s/duty_cycle", pwm_path); snprintf(enable_path, sizeof(enable_path), "%s/enable", pwm_path); #else - char fragment[18]; - char pwm_fragment[20]; - char pwm_path[45]; - char duty_path[56]; - char period_path[50]; - char polarity_path[55]; + char fragment[100]; + char pwm_fragment[100]; + char pwm_path[100]; + char duty_path[200]; + char period_path[100]; + char polarity_path[100]; int period_fd, duty_fd, polarity_fd; if (!pwm_initialized) { @@ -553,6 +577,9 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri close(period_fd); close(duty_fd); close(polarity_fd); +#ifdef BBBVERSION41 + close(enable_fd); +#endif syslog(LOG_ERR, "Adafruit_BBIO: pwm_setup: %s couldn't malloc pwm_exp: %i-%s", key, errno, strerror(errno)); return BBIO_MEM; // out of memory @@ -579,9 +606,10 @@ BBIO_err pwm_setup(const char *key, __attribute__ ((unused)) float duty, __attri BBIO_err pwm_start(const char *key, float duty, float freq, int polarity) { syslog(LOG_DEBUG, "Adafruit_BBIO: pwm_start: %s, %f, %f, %i", key, duty, freq, polarity); + //fprintf(stderr, "Adafruit_BBIO: pwm_start: %s, %f, %f, %i\n", key, duty, freq, polarity); BBIO_err err; - char buffer[20]; + char buffer[100]; ssize_t len; struct pwm_exp *pwm = lookup_exported_pwm(key); @@ -685,7 +713,7 @@ BBIO_err pwm_disable(const char *key) #ifndef BBBVERSION41 BBIO_err err; - char fragment[18]; + char fragment[100]; snprintf(fragment, sizeof(fragment), "bone_pwm_%s", key); err = unload_device_tree(fragment); if (err != BBIO_OK) @@ -700,7 +728,7 @@ BBIO_err pwm_disable(const char *key) { #ifdef BBBVERSION41 - char buffer[2]; + char buffer[100]; size_t len; // Disable the PWM @@ -717,6 +745,9 @@ BBIO_err pwm_disable(const char *key) #endif //close the fd +#ifdef BBBVERSION41 + close(pwm->enable_fd); +#endif close(pwm->period_fd); close(pwm->duty_fd); close(pwm->polarity_fd); diff --git a/source/c_uart.c b/source/c_uart.c index 211c54e..471c2a9 100644 --- a/source/c_uart.c +++ b/source/c_uart.c @@ -46,13 +46,13 @@ BBIO_err uart_cleanup(void) if (e1 != BBIO_OK) return e1; if (e2 != BBIO_OK) - return e1; + return e2; if (e3 != BBIO_OK) - return e1; + return e3; if (e4 != BBIO_OK) - return e1; + return e4; if (e5 != BBIO_OK) - return e1; + return e5; return BBIO_OK; } diff --git a/source/common.c b/source/common.c index 1a9cf31..f911d49 100644 --- a/source/common.c +++ b/source/common.c @@ -69,7 +69,7 @@ typedef struct pins_t { int ain; } pins_t; -//Table generated based on https://raw.github.com/jadonk/bonescript/master/node_modules/bonescript/bone.js +//Table generated based on https://github.com/jadonk/bonescript/blob/master/src/bone.js pins_t table[] = { { "USR0", "USR0", 53, -1, -1}, { "USR1", "USR1", 54, -1, -1}, @@ -81,10 +81,10 @@ pins_t table[] = { { "GPIO1_7", "P8_4", 39, -1, -1}, { "GPIO1_2", "P8_5", 34, -1, -1}, { "GPIO1_3", "P8_6", 35, -1, -1}, - { "TIMER4", "P8_7", 66, -1, -1}, - { "TIMER7", "P8_8", 67, -1, -1}, - { "TIMER5", "P8_9", 69, -1, -1}, - { "TIMER6", "P8_10", 68, -1, -1}, + { "TIMER4", "P8_7", 66, 2, -1}, + { "TIMER7", "P8_8", 67, 2, -1}, + { "TIMER5", "P8_9", 69, 2, -1}, + { "TIMER6", "P8_10", 68, 2, -1}, { "GPIO1_13", "P8_11", 45, -1, -1}, { "GPIO1_12", "P8_12", 44, -1, -1}, { "EHRPWM2B", "P8_13", 23, 4, -1}, @@ -189,7 +189,7 @@ pins_t table[] = { // These are for the PocketBeagle { "VIN_AC", "P1_1", 0, -1, -1}, { "GPIO2_23", "P1_2", 87, -1, -1}, - { "USB1_VBUS_OUT", "P1_3", 0, -1, -1}, + { "USB1_DRVVBUS", "P1_3", 0, -1, -1}, { "GPIO2_25", "P1_4", 89, -1, -1}, { "USB1_VBUS_IN", "P1_5", 0, -1, -1}, { "SPI0_CS0", "P1_6", 5, -1, -1}, @@ -206,15 +206,15 @@ pins_t table[] = { { "VREFN", "P1_17", 0, -1, -1}, { "VREFP", "P1_18", 0, -1, -1}, { "AIN0", "P1_19", 0, -1, 0}, - { "GPIO0_20", "P1_20", 20, -1, -1}, + { "GPIO0_20", "P1_20", 20, 4, -1}, { "AIN1", "P1_21", 0, -1, 1}, { "GND", "P1_22", 0, -1, -1}, { "AIN2", "P1_23", 0, -1, 2}, { "VOUT-5V", "P1_24", 0, -1, -1}, { "AIN3", "P1_25", 0, -1, 3}, - { "I2C2_SDA", "P1_26", 12, -1, -1}, + { "I2C2_SDA", "P1_26", 12, 1, -1}, { "AIN4", "P1_27", 0, -1, 4}, - { "I2C2_SCL", "P1_28", 13, -1, -1}, + { "I2C2_SCL", "P1_28", 13, 1, -1}, { "GPIO3_21", "P1_29", 117, -1, -1}, { "UART0_TXD", "P1_30", 43, -1, -1}, { "GPIO3_18", "P1_31", 114, -1, -1}, @@ -249,11 +249,11 @@ pins_t table[] = { { "GPIO1_12", "P2_24", 44, -1, -1}, { "SPI1_CS0", "P2_25", 41, -1, -1}, { "RESET#", "P2_26", 0, -1, -1}, - { "SPI1_D0", "P2_27", 40, -1, -1}, + { "SPI1_D0", "P2_27", 40, 5, -1}, { "GPIO3_20", "P2_28", 116, -1, -1}, { "SPI1_SCLK", "P2_29", 7, -1, -1}, { "GPIO3_17", "P2_30", 113, -1, -1}, - { "SPI1_CS1", "P2_31", 19, -1, -1}, + { "SPI1_CS1", "P2_31", 19, 2, -1}, { "GPIO3_16", "P2_32", 112, -1, -1}, { "GPIO1_13", "P2_33", 45, -1, -1}, { "GPIO3_19", "P2_34", 115, -1, -1}, @@ -263,13 +263,16 @@ pins_t table[] = { { NULL, NULL, 0, 0, 0 } }; -typedef struct uart_t { - const char *name; - const char *path; - const char *dt; - const char *rx; - const char *tx; -} uart_t; +// Issue #243: UART setup not working for pocket beagle pins +// Add UART entries for the PocketBeagle: +// P1_30 uart0_txd +// P1_32 uart0_rxd +// P2_11 uart1_rxd +// P2_09 uart1_txd +// P1_08 uart2_rxd +// P1_10 uart2_txd +// P2_05 uart4_rxd +// P2_07 uart4_txd uart_t uart_table[] = { { "UART1", "/dev/ttyO1", "ADAFRUIT-UART1", "P9_26", "P9_24"}, @@ -277,12 +280,16 @@ uart_t uart_table[] = { { "UART3", "/dev/ttyO3", "ADAFRUIT-UART3", "P9_42", ""}, { "UART4", "/dev/ttyO4", "ADAFRUIT-UART4", "P9_11", "P9_13"}, { "UART5", "/dev/ttyO5", "ADAFRUIT-UART5", "P8_38", "P8_37"}, + { "PB-UART0", "/dev/ttyO0", "ADAFRUIT-UART0", "P1_30", "P1_32"}, + { "PB-UART1", "/dev/ttyO1", "ADAFRUIT-UART1", "P2_11", "P2_09"}, + { "PB-UART2", "/dev/ttyO2", "ADAFRUIT-UART2", "P1_08", "P1_10"}, + { "PB-UART4", "/dev/ttyO4", "ADAFRUIT-UART4", "P2_05", "P2_07"}, { NULL, NULL, 0, 0, 0 } }; // Copied from https://github.com/jadonk/bonescript/blob/master/src/bone.js // See am335x technical manual, p. 183, for more info: -// http://www.ti.com/lit/ug/spruh73n/spruh73n.pdf +// https://www.ti.com/lit/ug/spruh73q/spruh73q.pdf pwm_t pwm_table[] = { { "ehrpwm2", 6, 1, 4, "ehrpwm.2:1", "EHRPWM2B", "48304000", "48304200", "P8_13"}, { "ehrpwm2", 5, 0, 4, "ehrpwm.2:0", "EHRPWM2A", "48304000", "48304200", "P8_19"}, @@ -298,12 +305,21 @@ pwm_t pwm_table[] = { { "ehrpwm0", 1, 1, 1, "ehrpwm.0:1", "EHRPWM0B", "48300000", "48300200", "P9_29"}, { "ehrpwm0", 0, 0, 1, "ehrpwm.0:0", "EHRPWM0A", "48300000", "48300200", "P9_31"}, { "ecap0", 2, 0, 0, "ecap.0", "ECAPPWM0", "48300000", "48300100", "P9_42"}, + { "timer4", 0, 0, 2, "", "", "", "dmtimer-pwm-4", "P8_7" }, + { "timer7", 0, 0, 2, "", "", "", "dmtimer-pwm-7", "P8_8" }, + { "timer5", 0, 0, 2, "", "", "", "dmtimer-pwm-5", "P8_9" }, + { "timer6", 0, 0, 2, "", "", "", "dmtimer-pwm-6", "P8_10" }, { "ehrpwm0", 0, 0, 1, "ehrpwm.0:0", "EHRPWM0A", "48300000", "48300200", "P1_8"}, { "ehrpwm0", 0, 0, 1, "ehrpwm.0:0", "EHRPWM0A", "48300000", "48300200", "P1_36"}, { "ehrpwm0", 1, 1, 1, "ehrpwm.0:1", "EHRPWM0B", "48300000", "48300200", "P1_10"}, - { "ehrpwm0", 1, 1, 1, "ehrpwm.0:1", "EHRPWM0B", "48300000", "48300200", "P1_13"}, + { "ehrpwm0", 1, 1, 1, "ehrpwm.0:1", "EHRPWM0B", "48300000", "48300200", "P1_33"}, { "ehrpwm1", 3, 0, 6, "ehrpwm.1:0", "EHRPWM1A", "48302000", "48302200", "P2_1"}, { "ehrpwm2", 6, 1, 3, "ehrpwm.2:1", "EHRPWM2B", "48304000", "48304200", "P2_3"}, + { "timer7", 0, 0, 4, "", "", "", "dmtimer-pwm-7", "P1_20" }, + { "timer6", 0, 0, 1, "", "", "", "dmtimer-pwm-6", "P1_26" }, + { "timer5", 0, 0, 1, "", "", "", "dmtimer-pwm-5", "P1_28" }, + { "timer7", 0, 0, 5, "", "", "", "dmtimer-pwm-7", "P2_27" }, + { "timer4", 0, 0, 2, "", "", "", "dmtimer-pwm-4", "P2_31" }, { NULL, 0, 0, 0, NULL, NULL, NULL, NULL, NULL } }; @@ -601,23 +617,30 @@ int pocketbeagle(void) { */ int beaglebone_blue(void) { const char *cmd = "/bin/grep -c 'TI AM335x BeagleBone Blue' /proc/device-tree/model"; - char blue; + // cache the value to avoid poor performance + // in functions that are called frequently like + // gpio_set_value() in source/event_gpio.c + static int initialized = 0; + static int retval = 0; FILE *file = NULL; - file = popen(cmd, "r"); - if (file == NULL) { - fprintf(stderr, "error: beaglebone_blue() failed to run cmd=%s\n", cmd); - syslog(LOG_ERR, "Adafruit_BBIO: error: beaglebone_blue() failed to run cmd=%s\n", cmd); - return -1; + //fprintf(stderr, "beaglebone_blue(): initialized=[%d] retval=[%d]\n", initialized, retval); + if(!initialized) { + initialized = 1; + //fprintf(stderr, "beaglebone_blue(): not initialized\n"); + file = popen(cmd, "r"); + if (file == NULL) { + fprintf(stderr, "Adafruit_BBIO: error in beaglebone_blue(): failed to run cmd=%s\n", cmd); + syslog(LOG_ERR, "Adafruit_BBIO: error in beaglebone_blue(): failed to run cmd=%s\n", cmd); + return -1; + } + if( fgetc(file) == '1' ) { + retval = 1; + } + pclose(file); } - blue = fgetc(file); - pclose(file); - if(blue == '1') { - return 1; - } else { - return 0; - } + return retval; } @@ -625,12 +648,10 @@ BBIO_err load_device_tree(const char *name) { char line[256]; FILE *file = NULL; - + char slots[100]; #ifdef BBBVERSION41 - char slots[41]; snprintf(ctrl_dir, sizeof(ctrl_dir), "/sys/devices/platform/bone_capemgr"); #else - char slots[40]; build_path("/sys/devices", "bone_capemgr", ctrl_dir, sizeof(ctrl_dir)); #endif @@ -642,7 +663,15 @@ BBIO_err load_device_tree(const char *name) return BBIO_OK; } + /* beaglebone blue has complete dtb file and does not need overlays */ + if(beaglebone_blue()) { + //fprintf(stderr, "common.c: load_device_tree(): beaglebone_blue(): TRUE\n"); + return BBIO_OK; + } + + /* pocketbeagle has complete dtb file and does not need overlays */ if(pocketbeagle()) { + //fprintf(stderr, "common.c: load_device_tree(): pocketbeagle(): TRUE\n"); return BBIO_OK; } @@ -679,11 +708,10 @@ BBIO_err load_device_tree(const char *name) int device_tree_loaded(const char *name) { FILE *file = NULL; + char slots[100]; #ifdef BBBVERSION41 - char slots[41]; snprintf(ctrl_dir, sizeof(ctrl_dir), "/sys/devices/platform/bone_capemgr"); #else - char slots[40]; build_path("/sys/devices", "bone_capemgr", ctrl_dir, sizeof(ctrl_dir)); #endif char line[256]; @@ -696,7 +724,15 @@ int device_tree_loaded(const char *name) return 1; } + /* beaglebone blue has complete dtb file and does not need overlays */ + if(beaglebone_blue()) { + //fprintf(stderr, "common.c: device_tree_loaded(): beaglebone_blue(): TRUE\n"); + return BBIO_OK; + } + + /* pocketbeagle has complete dtb file and does not need overlays */ if(pocketbeagle()) { + //fprintf(stderr, "common.c: device_tree_loaded(): pocketbeagle(): TRUE\n"); return BBIO_OK; } @@ -728,16 +764,27 @@ int device_tree_loaded(const char *name) BBIO_err unload_device_tree(const char *name) { FILE *file = NULL; + char slots[100]; #ifdef BBBVERSION41 - char slots[41]; snprintf(ctrl_dir, sizeof(ctrl_dir), "/sys/devices/platform/bone_capemgr"); #else - char slots[40]; build_path("/sys/devices", "bone_capemgr", ctrl_dir, sizeof(ctrl_dir)); #endif char line[256]; char *slot_line; + /* beaglebone blue has complete dtb file and does not need overlays */ + if(beaglebone_blue()) { + //fprintf(stderr, "common.c: unload_device_tree(): beaglebone_blue(): TRUE\n"); + return BBIO_OK; + } + + /* pocketbeagle has complete dtb file and does not need overlays */ + if(pocketbeagle()) { + //fprintf(stderr, "common.c: unload_device_tree(): pocketbeagle(): TRUE\n"); + return BBIO_OK; + } + snprintf(slots, sizeof(slots), "%s/slots", ctrl_dir); file = fopen(slots, "r+"); if (!file) { diff --git a/source/common.h b/source/common.h index 1e2d307..7d60c1f 100644 --- a/source/common.h +++ b/source/common.h @@ -64,6 +64,17 @@ typedef struct pwm_t { const char *key; // Pin name eg P9_21 } pwm_t; + +typedef struct uart_t { + const char *name; + const char *path; + const char *dt; + const char *rx; + const char *tx; +} uart_t; + +extern uart_t uart_table[]; + extern int gpio_mode; extern int gpio_direction[120]; diff --git a/source/constants.c b/source/constants.c index 5e284c8..23753c6 100644 --- a/source/constants.c +++ b/source/constants.c @@ -35,39 +35,41 @@ SOFTWARE. void define_constants(PyObject *module) { - high = Py_BuildValue("i", HIGH); - PyModule_AddObject(module, "HIGH", high); + PyObject *object; - low = Py_BuildValue("i", LOW); - PyModule_AddObject(module, "LOW", low); + object = Py_BuildValue("i", HIGH); + PyModule_AddObject(module, "HIGH", object); - output = Py_BuildValue("i", OUTPUT); - PyModule_AddObject(module, "OUT", output); + object = Py_BuildValue("i", LOW); + PyModule_AddObject(module, "LOW", object); - input = Py_BuildValue("i", INPUT); - PyModule_AddObject(module, "IN", input); + object = Py_BuildValue("i", OUTPUT); + PyModule_AddObject(module, "OUT", object); - alt0 = Py_BuildValue("i", ALT0); - PyModule_AddObject(module, "ALT0", alt0); + object = Py_BuildValue("i", INPUT); + PyModule_AddObject(module, "IN", object); - pud_off = Py_BuildValue("i", PUD_OFF); - PyModule_AddObject(module, "PUD_OFF", pud_off); + object = Py_BuildValue("i", ALT0); + PyModule_AddObject(module, "ALT0", object); - pud_up = Py_BuildValue("i", PUD_UP); - PyModule_AddObject(module, "PUD_UP", pud_up); + object = Py_BuildValue("i", PUD_OFF); + PyModule_AddObject(module, "PUD_OFF", object); - pud_down = Py_BuildValue("i", PUD_DOWN); - PyModule_AddObject(module, "PUD_DOWN", pud_down); + object = Py_BuildValue("i", PUD_UP); + PyModule_AddObject(module, "PUD_UP", object); + + object = Py_BuildValue("i", PUD_DOWN); + PyModule_AddObject(module, "PUD_DOWN", object); - rising_edge = Py_BuildValue("i", RISING_EDGE); - PyModule_AddObject(module, "RISING", rising_edge); + object = Py_BuildValue("i", RISING_EDGE); + PyModule_AddObject(module, "RISING", object); - falling_edge = Py_BuildValue("i", FALLING_EDGE); - PyModule_AddObject(module, "FALLING", falling_edge); + object = Py_BuildValue("i", FALLING_EDGE); + PyModule_AddObject(module, "FALLING", object); - both_edge = Py_BuildValue("i", BOTH_EDGE); - PyModule_AddObject(module, "BOTH", both_edge); + object = Py_BuildValue("i", BOTH_EDGE); + PyModule_AddObject(module, "BOTH", object); - version = Py_BuildValue("s", "0.0.20"); - PyModule_AddObject(module, "VERSION", version); + object = Py_BuildValue("s", "0.0.20"); + PyModule_AddObject(module, "VERSION", object); } diff --git a/source/constants.h b/source/constants.h index 0f6fdf5..82ebe5e 100644 --- a/source/constants.h +++ b/source/constants.h @@ -1,19 +1,6 @@ #ifndef CONSTANTS_H #define CONSTANTS_H -PyObject *high; -PyObject *low; -PyObject *input; -PyObject *output; -PyObject *alt0; -PyObject *pud_off; -PyObject *pud_up; -PyObject *pud_down; -PyObject *rising_edge; -PyObject *falling_edge; -PyObject *both_edge; -PyObject *version; - void define_constants(PyObject *module); #endif diff --git a/source/event_gpio.c b/source/event_gpio.c index 08bcec1..9f5acd6 100644 --- a/source/event_gpio.c +++ b/source/event_gpio.c @@ -80,18 +80,39 @@ BBIO_err gpio_export(unsigned int gpio) // already exported by us? if (exported_gpios[gpio] != GPIO_NOT_EXPORTED) { - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_export: %u already exported", gpio); + syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_export(): %u already exported before", gpio); ret = BBIO_OK; goto exit; } + // Is GPIO an LED? + if ( ((gpio >= USR_LED_GPIO_MIN) && (gpio <= USR_LED_GPIO_MAX)) + || + ( beaglebone_blue() + && + ( + (gpio == USR_LED_RED) + || (gpio == USR_LED_GREEN) + || (gpio == BAT25) + || (gpio == BAT50) + || (gpio == BAT75) + || (gpio == BAT100) + || (gpio == WIFI) + ) + ) + ) + { + syslog(LOG_WARNING, "Adafruit_BBIO: gpio_export: %u not applicable to built-in LEDs", gpio); + return BBIO_OK; // export is not applicable to the USR LED pins + } + // already exported by someone else? char gpio_path[64]; snprintf(gpio_path, sizeof(gpio_path), "/sys/class/gpio/gpio%d", gpio); if (access(gpio_path, R_OK|W_OK|X_OK) != -1) { exported_gpios[gpio] = GPIO_ALREADY_EXPORTED; - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_export: %u already exported", gpio); + syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_export(): %u already exported externally", gpio); ret = BBIO_OK; goto exit; } @@ -99,7 +120,7 @@ BBIO_err gpio_export(unsigned int gpio) const char gpio_export[] = "/sys/class/gpio/export"; if ((fd = open(gpio_export, O_WRONLY)) < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_export: %u couldn't open \"%s\": %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_export(): %u couldn't open \"%s\": %i-%s", gpio, gpio_export, errno, strerror(errno)); ret = BBIO_SYSFS; goto exit; @@ -116,19 +137,19 @@ BBIO_err gpio_export(unsigned int gpio) // add to list exported_gpios[gpio] = GPIO_EXPORTED; - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_export: %u OK", gpio); + syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_export(): %u OK", gpio); ret = BBIO_OK; exit: if(fd && (ret = close(fd))) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_export: %u couldn't close \"%s\": %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_export(): %u couldn't close \"%s\": %i-%s", gpio, gpio_export, errno, strerror(errno)); ret = BBIO_SYSFS; } usleep(200000); // Hack to wait for newly exported pins to get correct ownership return ret; } - +// Closes fd corresponding to specified GPIO pin and removes it from fdx list void close_value_fd(unsigned int gpio) { struct fdx *f = fd_list; @@ -140,10 +161,12 @@ void close_value_fd(unsigned int gpio) if (f->gpio == gpio) { close(f->fd); + syslog(LOG_DEBUG, "Adafruit_BBIO: close_value_fd(): closed file descriptor %d", f->fd); if (prev == NULL) fd_list = f->next; else prev->next = f->next; + syslog(LOG_DEBUG, "Adafruit_BBIO: close_value_fd(): removing file descriptor %d for pin %u from opened descriptors list",f->fd, f->gpio); temp = f; f = f->next; free(temp); @@ -153,7 +176,7 @@ void close_value_fd(unsigned int gpio) } } } - +// Returns file descriptor corresponding to specified GPIO pin int fd_lookup(unsigned int gpio) { struct fdx *f = fd_list; @@ -165,7 +188,7 @@ int fd_lookup(unsigned int gpio) } return 0; } - +// Adds GPIO file descriptor to fdx list int add_fd_list(unsigned int gpio, int fd) { struct fdx *new_fd; @@ -184,6 +207,7 @@ int add_fd_list(unsigned int gpio, int fd) new_fd->next = fd_list; } fd_list = new_fd; + syslog(LOG_DEBUG, "Adafruit_BBIO: add_fd_list(): registered file descriptor %d for pin %u.",fd, gpio); return 0; } @@ -196,7 +220,7 @@ int open_value_file(unsigned int gpio) if ((gpio >= USR_LED_GPIO_MIN) && (gpio <= USR_LED_GPIO_MAX)) { snprintf(filename, sizeof(filename), "/sys/class/leds/beaglebone:green:usr%d/brightness", gpio - USR_LED_GPIO_MIN); } else if (beaglebone_blue()) { - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio open_value_file: beaglebone_blue() is true\n"); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio open_value_file: beaglebone_blue() is true\n"); switch(gpio) { case USR_LED_RED: snprintf(filename, sizeof(filename), "/sys/class/leds/red/brightness"); @@ -224,10 +248,10 @@ int open_value_file(unsigned int gpio) break; } } else { - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio open_value_file: default gpio path\n"); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio open_value_file: default gpio path\n"); snprintf(filename, sizeof(filename), "/sys/class/gpio/gpio%d/value", gpio); } - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio open_value_file: filename=%s\n", filename); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio open_value_file: filename=%s\n", filename); // if(gpio == USR_LED_RED) { // red LED // snprintf(filename, sizeof(filename), "/sys/class/leds/red/brightness"); @@ -242,6 +266,7 @@ int open_value_file(unsigned int gpio) gpio, filename, errno, strerror(errno)); return -1; } + syslog(LOG_DEBUG, "Adafruit_BBIO: open_value_file(): opened file descriptor %d for pin %u.",fd, gpio); add_fd_list(gpio, fd); return fd; } @@ -251,15 +276,16 @@ BBIO_err gpio_unexport(unsigned int gpio) int fd, len; char str_gpio[10]; + //If gpio is not exported by us - no need to do anything if (exported_gpios[gpio] != GPIO_EXPORTED) return 0; - + //close gpio pin file descriptor close_value_fd(gpio); #define GPIO_UNEXPORT "/sys/class/gpio/unexport" if ((fd = open(GPIO_UNEXPORT, O_WRONLY)) < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_unexport: %u couldn't open '"GPIO_UNEXPORT"': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_unexport(): %u couldn't open '"GPIO_UNEXPORT"': %i-%s", gpio, errno, strerror(errno)); return BBIO_SYSFS; } @@ -268,7 +294,7 @@ BBIO_err gpio_unexport(unsigned int gpio) int ret = write(fd, str_gpio, len); close(fd); if (ret < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_unexport: %u couldn't write '"GPIO_UNEXPORT"': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_unexport(): %u couldn't write '"GPIO_UNEXPORT"': %i-%s", gpio, errno, strerror(errno)); return BBIO_SYSFS; } @@ -276,7 +302,7 @@ BBIO_err gpio_unexport(unsigned int gpio) // remove from list exported_gpios[gpio] = GPIO_NOT_EXPORTED; - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_unexport: %u OK", gpio); + syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_unexport(): %u OK", gpio); return BBIO_OK; } @@ -308,7 +334,7 @@ BBIO_err gpio_set_direction(unsigned int gpio, unsigned int in_flag) snprintf(filename, sizeof(filename), "/sys/class/gpio/gpio%d/direction", gpio); if ((fd = open(filename, O_WRONLY)) < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_direction: %u couldn't open '%s': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_direction(): %u couldn't open '%s': %i-%s", gpio, filename, errno, strerror(errno)); return BBIO_SYSFS; } @@ -322,12 +348,12 @@ BBIO_err gpio_set_direction(unsigned int gpio, unsigned int in_flag) int ret = write(fd, direction, strlen(direction)); close(fd); if (ret < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_direction: %u couldn't write '%s': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_direction(): %u couldn't write '%s': %i-%s", gpio, filename, errno, strerror(errno)); return BBIO_SYSFS; } - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_direction: %u OK", gpio); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_direction: %u OK", gpio); return BBIO_OK; } @@ -339,7 +365,7 @@ BBIO_err gpio_get_direction(unsigned int gpio, unsigned int *value) snprintf(filename, sizeof(filename), "/sys/class/gpio/gpio%d/direction", gpio); if ((fd = open(filename, O_RDONLY | O_NONBLOCK)) < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_get_direction: %u couldn't open '%s': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_get_direction(): %u couldn't open '%s': %i-%s", gpio, filename, errno, strerror(errno)); return BBIO_SYSFS; } @@ -348,7 +374,7 @@ BBIO_err gpio_get_direction(unsigned int gpio, unsigned int *value) int ret = read(fd, &direction, sizeof(direction) - 1); close(fd); if (ret < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_get_direction: %u couldn't read '%s': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_get_direction(): %u couldn't read '%s': %i-%s", gpio, filename, errno, strerror(errno)); return BBIO_SYSFS; } @@ -359,7 +385,7 @@ BBIO_err gpio_get_direction(unsigned int gpio, unsigned int *value) *value = INPUT; } - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_get_direction: %u OK", gpio); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_get_direction: %u OK", gpio); return BBIO_OK; } @@ -396,14 +422,14 @@ BBIO_err gpio_set_value(unsigned int gpio, unsigned int value) char *usr_led_trigger[] = { "heartbeat", "mmc0", "cpu0", "mmc1" }; int led = gpio - USR_LED_GPIO_MIN; - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: USR LED path\n"); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: USR LED path\n"); snprintf(filename, sizeof(filename), "/sys/class/leds/beaglebone:green:usr%d/brightness", led); if (access(filename, W_OK) < 0) { snprintf(filename, sizeof(filename), "/sys/class/leds/beaglebone:green:%s/brightness", usr_led_trigger[led]); } } else if (beaglebone_blue()) { - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: beaglebone_blue() is true\n"); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: beaglebone_blue() is true\n"); switch(gpio) { case USR_LED_RED: snprintf(filename, sizeof(filename), "/sys/class/leds/red/brightness"); @@ -431,14 +457,14 @@ BBIO_err gpio_set_value(unsigned int gpio, unsigned int value) break; } } else { - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: default gpio path\n"); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: default gpio path\n"); snprintf(filename, sizeof(filename), "/sys/class/gpio/gpio%d/value", gpio); } - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: filename=%s\n", filename); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: filename=%s\n", filename); fd = open(filename, O_WRONLY); if (fd < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value: %u couldn't open '%s': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value(): %u couldn't open '%s': %i-%s", gpio, filename, errno, strerror(errno)); return BBIO_SYSFS; } @@ -452,12 +478,12 @@ BBIO_err gpio_set_value(unsigned int gpio, unsigned int value) int ret = write(fd, vstr, strlen(vstr)); close(fd); if (ret < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value: %u couldn't write '%s': %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value(): %u couldn't write '%s': %i-%s", gpio, filename, errno, strerror(errno)); return BBIO_SYSFS; } - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: %u %u OK", gpio, value); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_set_value: %u %u OK", gpio, value); return BBIO_OK; } @@ -469,7 +495,7 @@ BBIO_err gpio_get_value(unsigned int gpio, unsigned int *value) if (!fd) { if ((fd = open_value_file(gpio)) == -1) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value: %u couldn't open value file: %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value(): %u couldn't open value file: %i-%s", gpio, errno, strerror(errno)); return BBIO_SYSFS; } @@ -478,7 +504,7 @@ BBIO_err gpio_get_value(unsigned int gpio, unsigned int *value) lseek(fd, 0, SEEK_SET); int ret = read(fd, &ch, sizeof(ch)); if (ret < 0) { - syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value: %u couldn't read value file: %i-%s", + syslog(LOG_ERR, "Adafruit_BBIO: gpio_set_value(): %u couldn't read value file: %i-%s", gpio, errno, strerror(errno)); return BBIO_SYSFS; } @@ -489,7 +515,7 @@ BBIO_err gpio_get_value(unsigned int gpio, unsigned int *value) *value = 0; } - syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_get_value: %u OK", gpio); + //syslog(LOG_DEBUG, "Adafruit_BBIO: gpio_get_value: %u OK", gpio); return BBIO_OK; } @@ -511,7 +537,7 @@ int gpio_set_edge(unsigned int gpio, unsigned int edge) return 0; } - +//Returns gpio number corresponding to fd file descriptor unsigned int gpio_lookup(int fd) { struct fdx *f = fd_list; @@ -554,17 +580,32 @@ int add_edge_callback(unsigned int gpio, void (*func)(unsigned int gpio)) cb = cb->next; cb->next = new_cb; } + syslog(LOG_DEBUG, "Adafruit_BBIO: add_edge_callback(): added callback to %p for pin %u", new_cb->func, gpio); return 0; } void run_callbacks(unsigned int gpio) { struct callback *cb = callbacks; + //Memory cookie + unsigned char cookie[2] = {0}; while (cb != NULL) { - if (cb->gpio == gpio) + //Store memory contents of the first byte of current callback structure as a "magic cookie" + memcpy(&cookie[0], cb, 1); + syslog(LOG_DEBUG, "Adafruit_BBIO: run_callbacks(): running callback %p for pin %u", cb->func, gpio); + if (cb->gpio == gpio) cb->func(cb->gpio); - cb = cb->next; + + //Check the first byte of callback structure after executing callback function body + memcpy(&cookie[1], cb, 1); + + // Current callback pointer might have changed _only_ if linked list structure has been altered from within the callback function, which should happen _only_ in remove_event_detect() call + // If that happened, cb* pointer will be now addressing different memory location with different data. + if (cookie[0] != cookie[1]) break; + + if (cb != NULL) + cb = cb->next; } } @@ -578,6 +619,7 @@ void remove_callbacks(unsigned int gpio) { if (cb->gpio == gpio) { + syslog(LOG_DEBUG, "Adafruit_BBIO: remove_callbacks(): removing callback to %p for pin %u", cb->func, cb->gpio); if (prev == NULL) callbacks = cb->next; else @@ -591,7 +633,7 @@ void remove_callbacks(unsigned int gpio) } } } - +// Resets flag for the corresponding gpio void set_initial_false(unsigned int gpio) { struct fdx *f = fd_list; @@ -603,7 +645,7 @@ void set_initial_false(unsigned int gpio) f = f->next; } } - +// Checks if flag is set for the corresponding gpio int gpio_initial(unsigned int gpio) { struct fdx *f = fd_list; @@ -627,28 +669,38 @@ void *poll_thread(__attribute__ ((unused)) void *threadarg) thread_running = 1; while (thread_running) { + // epoll_wait() returns -1 on error/timeout if ((n = epoll_wait(epfd, &events, 1, -1)) == -1) { thread_running = 0; + syslog(LOG_ERR, "Adafruit_BBIO: poll_thread(): exiting due to error/timeout returned by epoll_wait()"); pthread_exit(NULL); } + // otherwise it returns number of file descriptors ready if (n > 0) { + // Set read/write offset to the beginning of the file lseek(events.data.fd, 0, SEEK_SET); + // Try to check if there's new data available on fd by reading from it, i.e. no error ocurred if (read(events.data.fd, &buf, 1) != 1) { thread_running = 0; + syslog(LOG_ERR, "Adafruit_BBIO: poll_thread(): exiting due to no data available to read"); pthread_exit(NULL); } + // Find out gpio number corresponding to fd on which event has happened gpio = gpio_lookup(events.data.fd); if (gpio_initial(gpio)) { // ignore first epoll trigger + syslog(LOG_DEBUG, "Adafruit_BBIO: poll_thread(): discarding first epoll() event for pin %u",gpio); set_initial_false(gpio); } else { event_occurred[gpio] = 1; + syslog(LOG_DEBUG, "Adafruit_BBIO: poll_thread(): running callbacks for pin %u",gpio); run_callbacks(gpio); } } } thread_running = 0; + syslog(LOG_DEBUG, "Adafruit_BBIO: poll_thread(): normal exit"); pthread_exit(NULL); } @@ -690,6 +742,7 @@ int gpio_event_remove(unsigned int gpio) if (f->gpio == gpio) { f->is_evented = 0; + f->initial = 1; return 0; } f = f->next; @@ -700,17 +753,17 @@ int gpio_event_remove(unsigned int gpio) int add_edge_detect(unsigned int gpio, unsigned int edge) // return values: // 0 - Success -// 1 - Edge detection already added -// 2 - Other error +// -1 - Even detection already enabled for that GPIO +// Other error codes are system-wide { int fd = fd_lookup(gpio); pthread_t threads; struct epoll_event ev; long t = 0; - // check to see if this gpio has been added already + // check to see if this gpio has been added already to the list of gpios with event detection enabled if (gpio_event_add(gpio) != 0) - return 1; + return -1; // export /sys/class/gpio interface gpio_export(gpio); @@ -720,24 +773,37 @@ int add_edge_detect(unsigned int gpio, unsigned int edge) if (!fd) { if ((fd = open_value_file(gpio)) == -1) - return 2; + { + syslog(LOG_ERR, "Adafruit_BBIO: add_edge_detect(): open_value_file() error %i-%s", errno, strerror(errno)); + return errno; + } } // create epfd if not already open if ((epfd == -1) && ((epfd = epoll_create(1)) == -1)) - return 2; + { + syslog(LOG_ERR, "Adafruit_BBIO: add_edge_detect(): epoll_create() error %i-%s", errno, strerror(errno)); + return errno; + } + // add to epoll fd ev.events = EPOLLIN | EPOLLET | EPOLLPRI; ev.data.fd = fd; if (epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &ev) == -1) - return 2; + { + syslog(LOG_ERR, "Adafruit_BBIO: add_edge_detect(): epoll_ctl() error %i-%s", errno, strerror(errno)); + return errno; + } // start poll thread if it is not already running if (!thread_running) { if (pthread_create(&threads, NULL, poll_thread, (void *)t) != 0) - return 2; + { + syslog(LOG_ERR, "Adafruit_BBIO: add_edge_detect(): pthread_create() error %i-%s", errno, strerror(errno)); + return errno; + } } return 0; @@ -751,17 +817,21 @@ void remove_edge_detect(unsigned int gpio) // delete callbacks for gpio remove_callbacks(gpio); - // delete epoll of fd + // delete fd from epoll epoll_ctl(epfd, EPOLL_CTL_DEL, fd, &ev); // set edge to none gpio_set_edge(gpio, NO_EDGE); - // unexport gpio + //clear event gpio_event_remove(gpio); + // clear detected flag event_occurred[gpio] = 0; + + syslog(LOG_DEBUG, "Adafruit_BBIO: remove_edge_detect(): event detection disabled for pin %u",gpio); + } int event_detected(unsigned int gpio) diff --git a/source/event_gpio.h b/source/event_gpio.h index 78092ab..e06f344 100644 --- a/source/event_gpio.h +++ b/source/event_gpio.h @@ -72,6 +72,7 @@ int add_edge_detect(unsigned int gpio, unsigned int edge); void remove_edge_detect(unsigned int gpio); int add_edge_callback(unsigned int gpio, void (*func)(unsigned int gpio)); int event_detected(unsigned int gpio); +int gpio_initial(unsigned int gpio); int gpio_event_add(unsigned int gpio); int gpio_event_remove(unsigned int gpio); int gpio_is_evented(unsigned int gpio); diff --git a/source/examples/python/i2ctmp101.py b/source/examples/python/i2ctmp101.py index 923c0f9..ab916c0 100755 --- a/source/examples/python/i2ctmp101.py +++ b/source/examples/python/i2ctmp101.py @@ -8,5 +8,5 @@ while True: temp = bus.read_byte_data(address, 0) - print (temp, end="\r") + print(temp, end="\r") time.sleep(0.25) diff --git a/source/py_gpio.c b/source/py_gpio.c index 385a060..99cb0e7 100644 --- a/source/py_gpio.c +++ b/source/py_gpio.c @@ -218,6 +218,7 @@ static void run_py_callbacks(unsigned int gpio) PyObject *result; PyGILState_STATE gstate; struct py_callback *cb = py_callbacks; + unsigned char cookie[2] = {0}; struct timeval tv_timenow; unsigned long long timenow; @@ -225,28 +226,40 @@ static void run_py_callbacks(unsigned int gpio) { if (cb->gpio == gpio) { - gettimeofday(&tv_timenow, NULL); - timenow = tv_timenow.tv_sec*1E6 + tv_timenow.tv_usec; - if (cb->bouncetime == 0 || timenow - cb->lastcall > cb->bouncetime*1000 || cb->lastcall == 0 || cb->lastcall > timenow) { - - // save lastcall before calling func to prevent reentrant bounce + //Store memory contents of the first byte of current callback structure as a "magic cookie" + memcpy(&cookie[0], cb, 1); + gettimeofday(&tv_timenow, NULL); + timenow = tv_timenow.tv_sec*1E6 + tv_timenow.tv_usec; + if (cb->bouncetime == 0 || timenow - cb->lastcall > cb->bouncetime*1000 || cb->lastcall == 0 || cb->lastcall > timenow) { + + // save lastcall before calling func to prevent reentrant bounce + cb->lastcall = timenow; + + // run callback + gstate = PyGILState_Ensure(); + result = PyObject_CallFunction(cb->py_cb, "s", cb->channel); + //Check the first byte of callback structure after executing callback function body + memcpy(&cookie[1], cb, 1); + + if (result == NULL && PyErr_Occurred()) + { + PyErr_Print(); + PyErr_Clear(); + } + Py_XDECREF(result); + PyGILState_Release(gstate); + } + + // Current callback pointer might have changed _only_ if linked list structure has been altered from within the callback function, which should happen _only_ in remove_event_detect() call + // If that happened, cb* pointer will be now addressing different memory location with different data. + if (cookie[0] != cookie[1]) break; + + if (cb != NULL) cb->lastcall = timenow; - - // run callback - gstate = PyGILState_Ensure(); - result = PyObject_CallFunction(cb->py_cb, "s", cb->channel); - - if (result == NULL && PyErr_Occurred()) - { - PyErr_Print(); - PyErr_Clear(); - } - Py_XDECREF(result); - PyGILState_Release(gstate); - } - cb->lastcall = timenow; } - cb = cb->next; + // If callback just executed was the only one in chain and it was removed inside cb->py_cb() body, cb->next will be pointing to NULL now + if (cb != NULL) + cb = cb->next; } } @@ -364,12 +377,12 @@ static PyObject *py_add_event_detect(__attribute__ ((unused)) PyObject *self, Py if ((result = add_edge_detect(gpio, edge)) != 0) // starts a thread { - if (result == 1) + if (result == -1) { - PyErr_SetString(PyExc_RuntimeError, "Edge detection already enabled for this GPIO channel"); + PyErr_SetString(PyExc_KeyError, "Edge detection already enabled for this GPIO channel"); return NULL; } else { - PyErr_SetString(PyExc_RuntimeError, "Failed to add edge detection"); + PyErr_SetFromErrno(PyExc_RuntimeError); return NULL; } } @@ -411,7 +424,9 @@ static PyObject *py_remove_event_detect(__attribute__ ((unused)) PyObject *self, temp = cb; cb = cb->next; free(temp); - } else { + } + else + { prev = cb; cb = cb->next; } @@ -540,14 +555,14 @@ static PyObject *py_setwarnings(__attribute__ ((unused)) PyObject *self, __attri static const char moduledocstring[] = "GPIO functionality of a BeagleBone using Python"; PyMethodDef gpio_methods[] = { - {"setup", (PyCFunction)py_setup_channel, METH_VARARGS | METH_KEYWORDS, "Set up the GPIO channel, direction and (optional) pull/up down control\nchannel - Either: RPi board pin number (not BCM GPIO 00..nn number). Pins start from 1\n or : BCM GPIO number\ndirection - INPUT or OUTPUT\n[pull_up_down] - PUD_OFF (default), PUD_UP or PUD_DOWN\n[initial] - Initial value for an output channel\n[delay] - Time in milliseconds to wait after exporting gpio pin"}, + {"setup", (PyCFunction)(void *)py_setup_channel, METH_VARARGS | METH_KEYWORDS, "Set up the GPIO channel, direction and (optional) pull/up down control\nchannel - Either: RPi board pin number (not BCM GPIO 00..nn number). Pins start from 1\n or : BCM GPIO number\ndirection - INPUT or OUTPUT\n[pull_up_down] - PUD_OFF (default), PUD_UP or PUD_DOWN\n[initial] - Initial value for an output channel\n[delay] - Time in milliseconds to wait after exporting gpio pin"}, {"cleanup", py_cleanup, METH_VARARGS, "Clean up by resetting all GPIO channels that have been used by this program to INPUT with no pullup/pulldown and no event detection"}, {"output", py_output_gpio, METH_VARARGS, "Output to a GPIO channel\ngpio - gpio channel\nvalue - 0/1 or False/True or LOW/HIGH"}, {"input", py_input_gpio, METH_VARARGS, "Input from a GPIO channel. Returns HIGH=1=True or LOW=0=False\ngpio - gpio channel"}, - {"add_event_detect", (PyCFunction)py_add_event_detect, METH_VARARGS | METH_KEYWORDS, "Enable edge detection events for a particular GPIO channel.\nchannel - either board pin number or BCM number depending on which mode is set.\nedge - RISING, FALLING or BOTH\n[callback] - A callback function for the event (optional)\n[bouncetime] - Switch bounce timeout in ms for callback"}, + {"add_event_detect", (PyCFunction)(void *)py_add_event_detect, METH_VARARGS | METH_KEYWORDS, "Enable edge detection events for a particular GPIO channel.\nchannel - either board pin number or BCM number depending on which mode is set.\nedge - RISING, FALLING or BOTH\n[callback] - A callback function for the event (optional)\n[bouncetime] - Switch bounce timeout in ms for callback"}, {"remove_event_detect", py_remove_event_detect, METH_VARARGS, "Remove edge detection for a particular GPIO channel\ngpio - gpio channel"}, {"event_detected", py_event_detected, METH_VARARGS, "Returns True if an edge has occured on a given GPIO. You need to enable edge detection using add_event_detect() first.\ngpio - gpio channel"}, - {"add_event_callback", (PyCFunction)py_add_event_callback, METH_VARARGS | METH_KEYWORDS, "Add a callback for an event already defined using add_event_detect()\ngpio - gpio channel\ncallback - a callback function\n[bouncetime] - Switch bounce timeout in ms"}, + {"add_event_callback", (PyCFunction)(void *)py_add_event_callback, METH_VARARGS | METH_KEYWORDS, "Add a callback for an event already defined using add_event_detect()\ngpio - gpio channel\ncallback - a callback function\n[bouncetime] - Switch bounce timeout in ms"}, {"wait_for_edge", py_wait_for_edge, METH_VARARGS, "Wait for an edge.\ngpio - gpio channel\nedge - RISING, FALLING or BOTH\ntimeout (optional) - time to wait in miliseconds. -1 will wait forever (default)"}, {"gpio_function", py_gpio_function, METH_VARARGS, "Return the current GPIO function (IN, OUT, ALT0)\ngpio - gpio channel"}, {"setwarnings", py_setwarnings, METH_VARARGS, "Enable or disable warning messages"}, @@ -584,8 +599,10 @@ PyMODINIT_FUNC initGPIO(void) initlog(LOG_INFO, NULL, BBIO_LOG_OPTION); +#if PY_VERSION_HEX < 0x03090000 if (!PyEval_ThreadsInitialized()) PyEval_InitThreads(); +#endif if (Py_AtExit(event_cleanup) != 0) { diff --git a/source/py_pwm.c b/source/py_pwm.c index 49c539b..e5f10f8 100644 --- a/source/py_pwm.c +++ b/source/py_pwm.c @@ -215,10 +215,10 @@ static PyObject *py_set_frequency(__attribute__ ((unused)) PyObject *self, PyObj static const char moduledocstring[] = "PWM functionality of a BeagleBone using Python"; PyMethodDef pwm_methods[] = { - {"start", (PyCFunction)py_start_channel, METH_VARARGS | METH_KEYWORDS, "Set up and start the PWM channel. channel can be in the form of 'P8_10', or 'EHRPWM2A'"}, - {"stop", (PyCFunction)py_stop_channel, METH_VARARGS | METH_KEYWORDS, "Stop the PWM channel. channel can be in the form of 'P8_10', or 'EHRPWM2A'"}, - { "set_duty_cycle", (PyCFunction)py_set_duty_cycle, METH_VARARGS, "Change the duty cycle\ndutycycle - between 0.0 and 100.0" }, - { "set_frequency", (PyCFunction)py_set_frequency, METH_VARARGS, "Change the frequency\nfrequency - frequency in Hz (freq > 0.0)" }, + {"start", (PyCFunction)(void *)py_start_channel, METH_VARARGS | METH_KEYWORDS, "Set up and start the PWM channel. channel can be in the form of 'P8_10', or 'EHRPWM2A'"}, + {"stop", (PyCFunction)(void *)py_stop_channel, METH_VARARGS | METH_KEYWORDS, "Stop the PWM channel. channel can be in the form of 'P8_10', or 'EHRPWM2A'"}, + { "set_duty_cycle", (PyCFunction)(void *)py_set_duty_cycle, METH_VARARGS | METH_KEYWORDS, "Change the duty cycle\ndutycycle - between 0.0 and 100.0" }, + { "set_frequency", (PyCFunction)(void *)py_set_frequency, METH_VARARGS | METH_KEYWORDS, "Change the frequency\nfrequency - frequency in Hz (freq > 0.0)" }, {"cleanup", py_cleanup, METH_VARARGS, "Clean up by resetting all GPIO channels that have been used by this program to INPUT with no pullup/pulldown and no event detection"}, //{"setwarnings", py_setwarnings, METH_VARARGS, "Enable or disable warning messages"}, {NULL, NULL, 0, NULL} diff --git a/source/py_uart.c b/source/py_uart.c index 78b2535..c70d327 100644 --- a/source/py_uart.c +++ b/source/py_uart.c @@ -25,6 +25,7 @@ SOFTWARE. #include "constants.h" #include "common.h" #include "c_uart.h" +#include "c_pinmux.h" const char *valid_uarts[4] = {"UART1", "UART2", "UART4", "UART5"}; @@ -61,6 +62,29 @@ static PyObject *py_setup_uart(__attribute__ ((unused)) PyObject *self, PyObject return NULL; } +#ifdef BBBVERSION41 + uart_t *p; + for (p = uart_table; p->name != NULL; ++p) { + if (strcmp(p->name, channel) == 0) { + err = set_pin_mode(p->rx, "uart"); + //Check if set_pin_mode() returned no error + if (err != BBIO_OK) { + fprintf(stderr, "py_setup_uart(%s): set_pin_mode() failed for pin=%s", channel, p->rx); + PyErr_SetString(PyExc_ValueError, "Set pin mode failed for uart channel."); + return NULL; + } + + err = set_pin_mode(p->tx, "uart"); + //Check if set_pin_mode() returned no error + if (err != BBIO_OK) { + fprintf(stderr, "py_setup_uart(%s): set_pin_mode() failed for pin=%s", channel, p->tx); + PyErr_SetString(PyExc_ValueError, "Set pin mode failed for uart channel."); + return NULL; + } + } + } +#endif + Py_RETURN_NONE; } diff --git a/source/spimodule.c b/source/spimodule.c index 5b1f6ad..7e438bd 100644 --- a/source/spimodule.c +++ b/source/spimodule.c @@ -703,7 +703,6 @@ static PyObject * SPI_open(SPI *self, PyObject *args, PyObject *kwds) { int bus, device; - int bus_path; int max_dt_length = 15; char device_tree_name[max_dt_length]; char path[MAXPATH]; @@ -722,14 +721,7 @@ SPI_open(SPI *self, PyObject *args, PyObject *kwds) return NULL; } - bus_path = get_spi_bus_path_number(bus); - if (bus_path == -1) { - PyErr_SetString(PyExc_OverflowError, - "Unable to find loaded spi bus path."); - return NULL; - } - - if (snprintf(path, MAXPATH, "/dev/spidev%d.%d", bus_path, device) >= MAXPATH) { + if (snprintf(path, MAXPATH, "/dev/spidev%d.%d", bus, device) >= MAXPATH) { PyErr_SetString(PyExc_OverflowError, "Bus and/or device number is invalid."); return NULL; @@ -785,17 +777,17 @@ PyDoc_STRVAR(SPI_type_doc, "specified SPI device interface.\n"); static PyMethodDef SPI_methods[] = { - {"open", (PyCFunction)SPI_open, METH_VARARGS | METH_KEYWORDS, + {"open", (PyCFunction)(void *)SPI_open, METH_VARARGS | METH_KEYWORDS, SPI_open_doc}, - {"close", (PyCFunction)SPI_close, METH_NOARGS, + {"close", (PyCFunction)(void *)SPI_close, METH_NOARGS, SPI_close_doc}, - {"readbytes", (PyCFunction)SPI_readbytes, METH_VARARGS, + {"readbytes", (PyCFunction)(void *)SPI_readbytes, METH_VARARGS, SPI_read_doc}, - {"writebytes", (PyCFunction)SPI_writebytes, METH_VARARGS, + {"writebytes", (PyCFunction)(void *)SPI_writebytes, METH_VARARGS, SPI_write_doc}, - {"xfer", (PyCFunction)SPI_xfer, METH_VARARGS, + {"xfer", (PyCFunction)(void *)SPI_xfer, METH_VARARGS, SPI_xfer_doc}, - {"xfer2", (PyCFunction)SPI_xfer2, METH_VARARGS, + {"xfer2", (PyCFunction)(void *)SPI_xfer2, METH_VARARGS, SPI_xfer2_doc}, {NULL}, }; diff --git a/doc/rotary-encoder-eqep-test.md b/test/notes/rotary-encoder-eqep-test.md similarity index 100% rename from doc/rotary-encoder-eqep-test.md rename to test/notes/rotary-encoder-eqep-test.md diff --git a/doc/run_config-pin_during_startup.md b/test/notes/run_config-pin_during_startup.md similarity index 100% rename from doc/run_config-pin_during_startup.md rename to test/notes/run_config-pin_during_startup.md diff --git a/doc/spi_loopback_test.md b/test/notes/spi_loopback_test.md similarity index 97% rename from doc/spi_loopback_test.md rename to test/notes/spi_loopback_test.md index 0f93d0c..7041852 100644 --- a/doc/spi_loopback_test.md +++ b/test/notes/spi_loopback_test.md @@ -46,7 +46,7 @@ from Adafruit_BBIO.SPI import SPI #spi = SPI(1,1) #/dev/spidev2.1 spi = SPI(0,0) -print spi.xfer2([32, 11, 110, 22, 220]) +print(spi.xfer2([32, 11, 110, 22, 220])) spi.close() ``` diff --git a/doc/test_read_write_all_gpio_pins.md b/test/notes/test_read_write_all_gpio_pins.md similarity index 100% rename from doc/test_read_write_all_gpio_pins.md rename to test/notes/test_read_write_all_gpio_pins.md diff --git a/test/start_all_pwm.py b/test/start_all_pwm.py index 58d02f5..f19ef97 100644 --- a/test/start_all_pwm.py +++ b/test/start_all_pwm.py @@ -20,7 +20,7 @@ # /sys/devices/platform/ocp/48304000.epwmss/48304100.ecap/pwm/pwmchip5/pwm-5:0/duty_cycle for pin in pins: - print pin + print(pin) PWM.start(pin, 50, 2000, 1) PWM.stop(pin) PWM.cleanup() diff --git a/test/test_led.py b/test/test_led.py index fa197a2..97dca13 100644 --- a/test/test_led.py +++ b/test/test_led.py @@ -14,7 +14,7 @@ def set_brightness(self, state, led, name): prefix = "/sys/class/leds/beaglebone:green:{0}/brightness" path = prefix.format(led.lower()) value = self.read_led_file(path) - if value < 0: + if value == "": path = prefix.format(name) value = self.read_led_file(path) if state == 1: @@ -25,16 +25,16 @@ def set_brightness(self, state, led, name): def read_led_file(self, path): try: return open(path).read() - except IOError, e: + except (IOError, e): if e.errno == errno.ENOENT: - return -1 + return "" def set_all_leds(self, state): test_leds = { "USR0": "heartbeat", \ "USR1": "mmc0", \ "USR2": "cpu0", \ "USR3": "mmc1" } - for led, name in test_leds.iteritems(): + for led, name in test_leds.items(): self.set_brightness(state, led, name) GPIO.cleanup() diff --git a/test/test_rotary.py b/test/test_rotary.py deleted file mode 100755 index 2292cd0..0000000 --- a/test/test_rotary.py +++ /dev/null @@ -1,74 +0,0 @@ -#!/usr/bin/python -# -# BeagleBone must boot with cape-universal enabled -# and load the cape-universala overlay in order to -# use all the eQEP pins -# -# Install the latest Device Tree overlays: -# ======================================== -# sudo apt-get upgrade bb-cape-overlays -# -# File: /boot/uEnv.txt -# ==================== -# uname_r=4.4.62-ti-r99 -# cmdline=coherent_pool=1M quiet cape_universal=enable -# cape_enable=bone_capemgr.enable_partno=cape-universala -# -# File: /sys/devices/platform/bone_capemgr/slots -# ============================================== -# 0: PF---- -1 -# 1: PF---- -1 -# 2: PF---- -1 -# 3: PF---- -1 -# 4: P-O-L- 0 Override Board Name,00A0,Override Manuf,cape-universala -# -# eqep0: P9_27, P9_92 -# =================== -# config-pin P9_27 qep -# config-pin P9_92 qep # alias for P9_42.1 -# cat /sys/devices/platform/ocp/48300000.epwmss/48300180.eqep/position -# -# eqep1: P8.33, P8.35 -# =================== -# config-pin P8.33 qep -# config-pin P8.35 qep -# cat /sys/devices/platform/ocp/48302000.epwmss/48302180.eqep/position -# -# eqep2: P8.11, P8.12 -# =================== -# config-pin P8.11 qep -# config-pin P8.12 qep -# cat /sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position -# -# alternate pins for eqep2 (mutually exclusive) -# eqep2b: P8.41, P8.42 -# ==================== -# config-pin P8.41 qep -# config-pin P8.42 qep -# cat /sys/devices/platform/ocp/48304000.epwmss/48304180.eqep/position -# -# -# How To Run This Test: -# debian@beaglebone:~/ssh/adafruit-beaglebone-io-python$ sudo python ./setup.py install &> /dev/null && sudo python ./test/test_rotary.py -# -# - -import Adafruit_BBIO.Encoder as Encoder - -qep = Encoder.RotaryEncoder(0) -print("qep.getPosition(): {0}".format(qep.getPosition())) - -qep = Encoder.RotaryEncoder(1) -print("qep.getPosition(): {0}".format(qep.getPosition())) - -qep = Encoder.RotaryEncoder(2) -print("qep.getPosition(): {0}".format(qep.getPosition())) - - -#qep.getMode() -#qep.setAbsolute() -#qep.setRelative() -#qep.setFrequency(5000) -#qep.setPosition(100) -#qep.disable() -#print("qep.enable(): {0}".format(qep.enable())) diff --git a/test/test_uart.py b/test/test_uart.py index 4fd4ac3..38f3ba7 100644 --- a/test/test_uart.py +++ b/test/test_uart.py @@ -1,4 +1,5 @@ import pytest +import serial import platform import Adafruit_BBIO.UART as UART @@ -11,7 +12,7 @@ def teardown_module(module): # ADC.cleanup() -class TestAdc: +class TestUart: def test_setup_uart_wrong_name(self): if kernel >= '4.1.0': pass @@ -25,9 +26,39 @@ def test_setup_adc(self): else: UART.setup("UART1") - def test_setup_adc_multiple(self): + def test_setup_uart_multiple(self): if kernel >= '4.1.0': pass else: UART.setup("UART1") UART.setup("UART1") + + # test UART entries for the PocketBeagle (issue #243) + def test_pocketbeagle(self): + if kernel < '4.1.0': + pass + value = open('/proc/device-tree/model').read() + if(value.startswith("TI AM335x PocketBeagle")): + uarts = { + 'PB-UART0': '/dev/ttyO0', + 'PB-UART1': '/dev/ttyO1', + 'PB-UART2': '/dev/ttyO2', + } + else: + uarts = { + 'UART1': '/dev/ttyO1', + 'UART2': '/dev/ttyO2', + 'UART4': '/dev/ttyO4' + # note: UART5 requires + # "disable_uboot_overlay_video=1" in /boot/uEnv.txt + #'UART5': '/dev/ttyO5' + } + + for name, device in sorted(uarts.items()): + UART.setup(name) + uart = serial.Serial(port = device, baudrate=9600) + uart.close() + uart.open() + if uart.isOpen(): + uart.write("hello world".encode("utf-8")) + uart.close() diff --git a/tox.ini b/tox.ini index abaae1f..084648a 100644 --- a/tox.ini +++ b/tox.ini @@ -4,7 +4,7 @@ # and then run "tox" from this directory. [tox] -envlist = py27, py34 +envlist = py27, py36 [testenv] commands = echo "run pytest on beaglebone" pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy