Encoder: convert get/set methods to properties, update apidoc strings

Author: dplanella

Adafruit_BBIO/Encoder.py

@@ -14,11 +14,16 @@
         'Please upgrade your kernel to use this module.\n'
         'Your Linux kernel version is {}.'.format(platform.release()))
 
+
+# eQEP module channel identifiers
+# eQEP 2 and 2b are the same channel, exposed on two different sets of pins,
+# which are mutually exclusive
 eQEP0 = 0
 eQEP1 = 1
 eQEP2 = 2
 eQEP2b = 3
 
+# Definitions to initialize the eQEP modules
 _OCP_PATH = "/sys/devices/platform/ocp"
 _eQEP_DEFS = [
    {'channel': 'eQEP0', 'pin_A': 'P9_92', 'pin_B': 'P9_27',
@@ -71,12 +76,31 @@ def __init__(self, channel, pin_A, pin_B, sys_path):
 
 
 class RotaryEncoder(object):
+    '''
+    Rotary encoder class abstraction to control a given QEP channel.
+
+    Constructor:
+        eqep_num: QEP object that determines which channel to control
+
+    Properties:
+        position: current position of the encoder
+        frequency: frequency at which the encoder reports new positions
+        enabled: (read only) true if the module is enabled, false otherwise
+        mode: current mode of the encoder (absolute: 0, relative: 1)
+
+    Methods:
+        enable: enable the QEP channel
+        disable: disable the QEP channel
+        setAbsolute: shortcut for setting the mode to absolute
+        setRelative: shortcut for setting the mode to relative
+        zero: shortcut for setting the position to 0
+    '''
 
     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.
-        '''
 
+        '''
         try:
             output = check_output(cmd, stderr=STDOUT)
             self._logger.info(
@@ -87,11 +111,8 @@ def _run_cmd(self, cmd):
                 "_run_cmd(): cmd='{}' return code={} output={}".format(
                     " ".join(cmd), e.returncode, e.output))
 
-    def config_pin(self, pin):
-        '''
-        config_pin()
-        Config pin for QEP
-        '''
+    def _config_pin(self, pin):
+        '''Configures a pin in QEP mode using the `config-pin` binary'''
 
         self._run_cmd(["config-pin", pin, "qep"])
 
@@ -103,8 +124,11 @@ def __init__(self, eqep_num):
                Allowed values: EQEP0, EQEP1, EQEP2 or EQEP2b,
                based on which pins the physical rotary encoder
                is connected to.
-            
+
         '''
+        # nanoseconds factor to convert period to frequency and back
+        self._NS_FACTOR = 1000000000
+
         # Set up logging at the module level
         self._logger = logging.getLogger(__name__)
         self._logger.addHandler(logging.NullHandler())
@@ -117,28 +141,41 @@ def __init__(self, eqep_num):
                 self._eqep.sys_path))
 
         # Configure the pins for the given channel
-        self.config_pin(self._eqep.pin_A)
-        self.config_pin(self._eqep.pin_B)
+        self._config_pin(self._eqep.pin_A)
+        self._config_pin(self._eqep.pin_B)
 
         self._logger.debug(
             "RotaryEncoder(): sys node: {0}".format(self._eqep.sys_path))
 
         # Enable the channel upon initialization
         self.enable()
 
-    def _setEnable(self, value):
+    @property
+    def enabled(self):
+        '''Returns the enabled status of the module:
+
+            true: module is enabled
+            false: module is disabled
+        '''
+        isEnabled = bool(int(self._eqep.node.enabled))
+
+        return isEnabled
+
+    def _setEnable(self, enabled):
         '''Turns the eQEP hardware ON or OFF
 
            value (int): 1 represents enabled, 0 is disabled
+
         '''
-        if value < 0 or value > 1:
+        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(value))
+                'You attempted to set it to {}.'.format(enabled))
 
-        self._eqep.node.enabled = str(int(value))
+        self._eqep.node.enabled = str(enabled)
         self._logger.info("Channel: {}, enabled: {}".format(
-            self._eqep.channel, self._eqep.node.enabled))       
+            self._eqep.channel, self._eqep.node.enabled))
 
     def enable(self):
         '''Turns the eQEP hardware ON'''
@@ -150,56 +187,59 @@ def disable(self):
 
         self._setEnable(0)
 
-    def _setMode(self, value):
+    @property
+    def mode(self):
+        '''Returns the mode the eQEP hardware is in (absolute or relative).
+
+        '''
+        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.
 
         '''
-        if value < 0 or value > 1:
+        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(value))
+                'You attempted to set it to {}.'.format(mode))
 
-        self._eqep.node.mode = str(int(value))
+        self._eqep.node.mode = str(mode)
         self._logger.debug("Mode set to: {}".format(
-            self._eqep.node.mode))  
+            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._setMode(0)
+        self.mode = 0
 
     def setRelative(self):
         '''Sets the eQEP mode as Relative:
         The position is reset when the unit timer overflows.
 
         '''
-        self._setMode(1)
-
-    def getMode(self):
-        '''Returns the mode the eQEP hardware is in (absolute or relative).
-
-        '''
+        self.mode = 1
 
-        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
-
-    def getPosition(self):
+    @property
+    def position(self):
         '''Returns the current position of the encoder.
         In absolute mode, this attribute represents the current position
         of the encoder.
@@ -209,31 +249,51 @@ def getPosition(self):
         '''
         position = self._eqep.node.position
 
-        self._logger.debug("getPosition(): Channel {}, position: {}".format(
+        self._logger.debug("Get position: Channel {}, position: {}".format(
             self._eqep.channel, position))
 
         return int(position)
 
-    def setFrequency(self, freq):
+    @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.
 
         '''
-        ns_factor = 1000000000
-        period = ns_factor/freq  # Period in nanoseconds
-        self._eqep.node.period = str(period)
+        frequency = self._eqep.node.period / self._NS_FACTOR
+
         self._logger.debug(
-            "setFrequency(): Channel {}, frequency: {} Hz, "
+            "Set frequency(): Channel {}, frequency: {} Hz, "
             "period: {} ns".format(
-                self._eqep.channel, freq, period))
+                self._eqep.channel, frequency, period))
 
-    def setPosition(self, position):
-        '''Sets the current position to a new value'''
+        return frequency
 
-        position = int(position)
-        self._eqep.node.position = str(position)
+    @frequency.setter
+    def frequency(self, frequency):
+        '''Sets the frequency in Hz at which the driver reports
+        new positions.
+
+        '''
+        period = 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'''
 
-        return self.setPosition(0)
+        self.position = 0