From 05d55cbb784683468fbb11f61ea41dd24f86708c Mon Sep 17 00:00:00 2001
From: Andrey Pohilko <apc4@ya.ru>
Date: Sun, 17 Sep 2017 21:12:59 +0300
Subject: [PATCH] Working on documenting it

---
 README.md               | 41 +++++++++++++++++++++++++++++++++++------
 demo.py                 | 12 +-----------
 pylgbst/peripherals.py  |  2 +-
 setup.py                |  2 +-
 vernie/__init__.py      |  2 +-
 vernie/run_away_game.py |  5 +++--
 6 files changed, 42 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 5a47e22..a810650 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,31 @@
 # Python library to interact with LEGO Move Hub
 
-Requires `gattlib` to be installed, currently Python 2.7 only
+Best way to start is to look into [`demo.py`](demo.py) file, and run it.
 
-Best way to start is to look into [demo.py](demo.py) file, and run it.
-If you have Vernie assembled, you might look into and run [vernie.py](vernie/vernie.py) file.
+If you have Vernie assembled, you might look into and run scripts from [`vernie`](vernie/) directory.
 
 ## Features
 
 - auto-detect and connect for Bluetooth device
 - auto-detects devices connected to Hub
-- permanent Bluetooth connection server for faster debugging
 - angled and timed movement for motors
 - LED color change
-- sensor data subscribe/unsubscribe
-- battery voltage available
+- motors: angled and timed movement, rotation sensor subscription
+- push button status subscription
+- tilt sensor subscription: 2 axis, 3 axis, bump detect modes
+- color & distance sensor: several modes to measure distance, color and luminosity
+- battery voltage subscription available
+- permanent Bluetooth connection server for faster debugging
 
 ## Usage
 
+Install library like this: 
+```bash
+pip install https://github.com/undera/pylgbst/archive/0.2.tar.gz
+```
+
+Then instantiate MoveHub object and start invoking its methods. Following is example to just print peripherals detected on Hub:  
+
 ```python
 from pylgbst import MoveHub
 
@@ -26,6 +35,21 @@ for device in hub.devices:
     print(device)
 ```
 
+TODO: more usage instructions
+
+### General Information
+hub's devices detect process & fields to access them
+general subscription modes & granularity info
+
+### Motors
+### Motor Rotation Sensors
+### Tilt Sensor
+### Color & Distance Sensor
+### LED
+### Push Button
+### Power Voltage & Battery
+
+
 ## Debug Server
 
 ```
@@ -34,14 +58,19 @@ sudo python -c "from pylgbst.comms import *; import logging; logging.basicConfig
 
 ## Roadmap
 
+- handle device detach and device attach events on ports C/D
 - experiment with motor commands, find what is hidden there
 - Give nice documentation examples, don't forget to mention logging
+- document all API methods
 - make sure unit tests cover all important code
 - generalize getting device info + give constants (low priority)
 
 ## Links
 
 - https://github.com/JorgePe/BOOSTreveng - source of protocol knowledge
+- https://github.com/spezifisch/sphero-python/blob/master/BB8joyDrive.py - example with +-another approach to bluetooth libs
+
+Some things around visual programming:
 - https://github.com/RealTimeWeb/blockpy
 - https://ru.wikipedia.org/wiki/App_Inventor
 - https://en.wikipedia.org/wiki/Blockly
diff --git a/demo.py b/demo.py
index e265e2a..f7b4a8d 100644
--- a/demo.py
+++ b/demo.py
@@ -167,15 +167,5 @@ if __name__ == '__main__':
         logging.warning("Failed to use debug server: %s", traceback.format_exc())
         connection = BLEConnection().connect()
 
-
-    def cb_log(val1, val2=None, val3=None):
-        log.info("V1:%s\tV2:%s\tV3:%s", val1, val2, val3)
-
-
     hub = MoveHub(connection)
-    hub.color_distance_sensor.subscribe(cb_log, CDS_MODE_STREAM_3_VALUES, granularity=3)
-    sleep(60)
-    # hub.motor_AB.timed(10, 0.1, async=True)
-    # sleep(1)
-    # hub.motor_AB.timed(0, 0)
-    # demo_all(hub)
+    demo_all(hub)
diff --git a/pylgbst/peripherals.py b/pylgbst/peripherals.py
index 6233e74..9f3522d 100644
--- a/pylgbst/peripherals.py
+++ b/pylgbst/peripherals.py
@@ -285,7 +285,7 @@ class ColorDistanceSensor(Peripheral):
             val3 = unpack("<H", data[8:10])[0]
             self._notify_subscribers(val1, val2, val3)
         elif self._port_subscription_mode == CDS_MODE_LUMINOSITY:
-            luminosity = unpack("<H", data[4:6])[0]
+            luminosity = unpack("<H", data[4:6])[0] / 1023.0
             self._notify_subscribers(luminosity)
         else:  # TODO: support whatever we forgot
             log.debug("Unhandled data in mode %s: %s", self._port_subscription_mode, str2hex(data))
diff --git a/setup.py b/setup.py
index db07f32..02c87a9 100644
--- a/setup.py
+++ b/setup.py
@@ -2,7 +2,7 @@ from distutils.core import setup
 
 setup(name='pylgbst',
       description='Python library to interact with LEGO Move Hub (from Lego BOOST set)',
-      version='0.1',
+      version='0.2',
       author='Andrey Pokhilko',
       author_email='apc4@ya.ru',
       packages=['pylgbst'],
diff --git a/vernie/__init__.py b/vernie/__init__.py
index 16d6642..6f39e2d 100644
--- a/vernie/__init__.py
+++ b/vernie/__init__.py
@@ -153,5 +153,5 @@ class Vernie(MoveHub):
             self.say("Unknown command")
             self.say("commands help")
 
-# TODO: find and follow the lightest direction game
 # TODO: disable motors if state is not up
+# TODO: stop motors on bump?
diff --git a/vernie/run_away_game.py b/vernie/run_away_game.py
index 680fb04..336f359 100644
--- a/vernie/run_away_game.py
+++ b/vernie/run_away_game.py
@@ -12,6 +12,7 @@ def callback(color, distance):
     print("Distance is %.1f inches, I'm running back with %s%% speed!" % (distance, int(speed * 100)))
     if speed <= 1:
         robot.motor_AB.timed(secs / 1, -speed, async=True)
+        robot.say("Place your hand in front of sensor")
 
 
 def on_btn(pressed):
@@ -27,7 +28,7 @@ robot.led.set_color(COLOR_GREEN)
 while running:
     time.sleep(1)
 
-robot.led.set_color(COLOR_BLACK)
 robot.color_distance_sensor.unsubscribe(callback)
 robot.button.unsubscribe(on_btn)
-time.sleep(5)  # let color change
+robot.led.set_color(COLOR_NONE)
+time.sleep(10)  # let color change