Merge pull request adafruit#207 from dplanella/patch-3

Encoder: improved usage documentation

Author: pdp7

Adafruit_BBIO/README.md

@@ -4,30 +4,68 @@ This module enables access to the Beaglebone Black enhanced Quadrature Encoder P
 
 ## Usage
 
-On a recent Beaglebone Debian image, access to the eQEP0 and eQEP2 channels should work out of the box:
+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
-import Adafruit_BBIO.Encoder as Encoder
+from Adafruit_BBIO.Encoder import RotaryEncoder, eQEP2
 
 '''
 Each channel can be accessed and initialized using its corresponding
 channel name constants:
 
- Encoder.eQEP0
- Encoder.eQEP1 # Pins only available when video is disabled
- Encoder.eQEP2
- Encoder.eQEP2b # Pins only available when video is disabled
+ 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 = Encoder.RotaryEncoder(Encoder.eQEP2)
+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
@@ -41,6 +79,23 @@ 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
+```
+
+### 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:
@@ -51,7 +106,7 @@ 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
+#### 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.