From cfc0a64ffeac16f52e726825e1f2c061bd4aa52d Mon Sep 17 00:00:00 2001
From: Andrey Pohilko <apc4@ya.ru>
Date: Wed, 20 Sep 2017 15:07:23 +0300
Subject: [PATCH] Documenting motors

---
 README.md              | 55 ++++++++++++++++++++++++++++++++++++++++--
 pylgbst/movehub.py     |  2 +-
 pylgbst/peripherals.py | 20 +++++++--------
 3 files changed, 64 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 7e0e5f0..8b76bd4 100644
--- a/README.md
+++ b/README.md
@@ -47,10 +47,62 @@ good practice is to unsubscribe, especially when used with `DebugServer`
 
 Only one, very last subscribe mode is in effect, with many subscriber callbacks allowed. 
 
-### Motors
+### Controlling Motors
+
+MoveHub provides motors via following fields:
+- `motor_A`
+- `motor_B`
+- `motor_AB`
+- `motor_external` - if external motor is attached to port C or D
+
+Methods to activate motors are:
+- `constant(speed_primary, speed_secondary)`
+- `timed(time, speed_primary, speed_secondary)`
+- `angled(angle, speed_primary, speed_secondary)`
+- `stop()`
+
+All these methods are synchronous by default, except `stop()`. You can pass `async` parameter to any of them to switch into asynchronous, which means command will return immediately, without waiting for rotation to complete.
+
+An example:
+```python
+from pylgbst import MoveHub
+import time
+
+hub = MoveHub()
+
+hub.motor_A.timed(0.5, 0.8)
+hub.motor_A.timed(0.5, -0.8)
+
+hub.motor_B.angled(90, 0.8)
+hub.motor_B.angled(-90, 0.8)
+
+hub.motor_AB.timed(1.5, 0.8, -0.8)
+hub.motor_AB.angled(90, 0.8, -0.8)
+
+hub.motor_external.constant(0.2)
+time.sleep(2)
+hub.motor_external.stop()
+```
+
 
 ### Motor Rotation Sensors
 
+Any motor allows to subscribe to its rotation sensor. Two sensor modes are available: rotation angle (`EncodedMotor.SENSOR_ANGLE`) and rotation speed (`EncodedMotor.SENSOR_SPEED`). Example: 
+
+```python
+from pylgbst import MoveHub, EncodedMotor
+import time
+
+def callback(angle):
+    print("Angle: %s" % angle)
+
+hub = MoveHub()
+
+hub.motor_A.subscribe(callback, mode=EncodedMotor.SENSOR_ANGLE)
+time.sleep(60) # rotate motor A
+hub.motor_A.unsubscribe(callback)
+```
+
 ### Tilt Sensor
 
 MoveHub's internal tilt sensor is available through `tilt_sensor` field. There are several modes to subscribe to sensor, providing 2-axis, 3-axis and bump detect data.
@@ -123,7 +175,6 @@ You can obtain colors are present as constants `COLOR_*` and also a map of avail
 
 Additionally, you can subscribe to LED color change events, using callback function as shown in example below.
 
-
 ```python
 from pylgbst import MoveHub, COLORS, COLOR_NONE, COLOR_RED
 import time
diff --git a/pylgbst/movehub.py b/pylgbst/movehub.py
index 969ac3c..0b3956e 100644
--- a/pylgbst/movehub.py
+++ b/pylgbst/movehub.py
@@ -43,8 +43,8 @@ class MoveHub(object):
         self.motor_A = None
         self.motor_B = None
         self.motor_AB = None
-        self.tilt_sensor = None
         self.color_distance_sensor = None
+        self.tilt_sensor = None
         self.motor_external = None
         self.port_C = None
         self.port_D = None
diff --git a/pylgbst/peripherals.py b/pylgbst/peripherals.py
index 64fc9b2..0ac341d 100644
--- a/pylgbst/peripherals.py
+++ b/pylgbst/peripherals.py
@@ -155,9 +155,9 @@ class EncodedMotor(Peripheral):
     ANGLED_GROUP = 0x0C
 
     # MOTORS
-    MOTOR_MODE_SOMETHING1 = 0x00
-    MOTOR_MODE_SPEED = 0x01
-    MOTOR_MODE_ANGLE = 0x02
+    SENSOR_SOMETHING1 = 0x00  # TODO: understand it
+    SENSOR_SPEED = 0x01
+    SENSOR_ANGLE = 0x02
 
     def _speed_abs(self, relative):
         if relative < -1:
@@ -228,24 +228,24 @@ class EncodedMotor(Peripheral):
         self._wrap_and_write(self.SOME_SINGLE, b"", speed_primary, speed_secondary)
         self._wait_sync(async)
 
-    def stop(self):
-        self.constant(0, async=True)
+    def stop(self, async=True):
+        self.constant(0, async=async)
 
     def handle_port_data(self, data):
-        if self._port_subscription_mode == self.MOTOR_MODE_ANGLE:
+        if self._port_subscription_mode == self.SENSOR_ANGLE:
             rotation = unpack("<l", data[4:8])[0]
             self._notify_subscribers(rotation)
-        elif self._port_subscription_mode == self.MOTOR_MODE_SOMETHING1:
+        elif self._port_subscription_mode == self.SENSOR_SOMETHING1:
             # TODO: understand what it means
             rotation = unpack("<B", data[4])[0]
             self._notify_subscribers(rotation)
-        elif self._port_subscription_mode == self.MOTOR_MODE_SPEED:
+        elif self._port_subscription_mode == self.SENSOR_SPEED:
             rotation = unpack("<b", data[4])[0]
             self._notify_subscribers(rotation)
         else:
             log.debug("Got motor sensor data while in unexpected mode: %s", self._port_subscription_mode)
 
-    def subscribe(self, callback, mode=MOTOR_MODE_ANGLE, granularity=1, async=False):
+    def subscribe(self, callback, mode=SENSOR_ANGLE, granularity=1, async=False):
         super(EncodedMotor, self).subscribe(callback, mode, granularity)
 
 
@@ -319,7 +319,7 @@ class ColorDistanceSensor(Peripheral):
     OFF2 = 0x07
     COLOR_DISTANCE_FLOAT = 0x08
     LUMINOSITY = 0x09
-    SOME_20BYTES = 0x0a # TODO: understand it
+    SOME_20BYTES = 0x0a  # TODO: understand it
 
     def __init__(self, parent, port):
         super(ColorDistanceSensor, self).__init__(parent, port)