undera
diff --git a/‎.gitignore
Lines changed: 1 addition & 0 deletions b/‎.gitignore
Lines changed: 1 addition & 0 deletions
diff --git a/‎.travis.yml
Lines changed: 19 additions & 19 deletions b/‎.travis.yml
Lines changed: 19 additions & 19 deletions
diff --git a/‎README.md
Lines changed: 20 additions & 248 deletions b/‎README.md
Lines changed: 20 additions & 248 deletions
@@ -3,3 +3,4 @@
 *.pyc
 build
 *.avi
+test_real.py
@@ -5,33 +5,33 @@ virtualenv:
 
 matrix:
   include:
-  - os: linux
-    python: 2.7
-  - os: linux
-    python: 3.4
+    - os: linux
+      python: 2.7
+    - os: linux
+      python: 3.4
 
 addons:
   apt:
     packages:
-    - libboost-python-dev
-    - libboost-thread-dev
-    - libbluetooth-dev
+      - libboost-python-dev
+      - libboost-thread-dev
+      - libbluetooth-dev
 
-    - libglib2.0-dev
-    - libdbus-1-dev
-    - libdbus-glib-1-dev
-    - libgirepository-1.0-1
+      - libglib2.0-dev
+      - libdbus-1-dev
+      - libdbus-glib-1-dev
+      - libgirepository-1.0-1
 
-    - python-dbus
-    - python-gi
-    - python3-dbus
-    - python3-gi
+      - python-dbus
+      - python-gi
+      - python3-dbus
+      - python3-gi
 install:
-- pip install codecov nose-exclude gattlib pygatt gatt pexpect bluepy
+  - pip install codecov nose-exclude gattlib pygatt gatt pexpect bluepy
 
 
-script: coverage run --source=. `which nosetests` tests --nocapture --exclude-dir=examples
+script: coverage run --source=. -m nose tests -v --exclude-dir=examples
 
 after_success:
-- coverage report -m
-- codecov
+  - coverage report -m
+  - codecov
@@ -8,7 +8,7 @@ Best way to start is to look into [`demo.py`](examples/demo.py) file, and run it
 
 If you have Vernie assembled, you might run scripts from [`examples/vernie`](examples/vernie) directory.
 
-Demonstrational videos:
+## Demonstrational Videos
 
 [![Vernie Programmed](http://img.youtube.com/vi/oqsmgZlVE8I/0.jpg)](http://www.youtube.com/watch?v=oqsmgZlVE8I)
 [![Laser Engraver](http://img.youtube.com/vi/ZbKmqVBBMhM/0.jpg)](https://youtu.be/ZbKmqVBBMhM)
@@ -18,16 +18,17 @@ Demonstrational videos:
 
 ## Features
 
-- auto-detect and connect to Move Hub device
-- auto-detects peripheral devices connected to Hub
-- constant, angled and timed movement for motors, rotation sensor subscription
-- color & distance sensor: several modes to measure distance, color and luminosity
-- tilt sensor subscription: 2 axis, 3 axis, bump detect modes
-- LED color change
-- push button status subscription
-- battery voltage subscription available
+- auto-detect and connect to [Move Hub](docs/MoveHub.md) device
+- auto-detects [peripheral devices](docs/Peripherals.md) connected to Hub
+- constant, angled and timed movement for [motors](docs/Motor.md), rotation sensor subscription
+- [vision sensor](docs/VisionSensor.md): several modes to measure distance, color and luminosity
+- [tilt sensor](docs/TiltSensor.md) subscription: 2 axis, 3 axis, bump detect modes
+- [RGB LED](docs/LED.md) color change
+- [push button](docs/MoveHub.md#push-button) status subscription
+- [battery voltage and current](docs/VoltageCurrent.md) subscription available
 - permanent Bluetooth connection server for faster debugging
 
+
 ## Usage
 
 _Please note that this library requires one of Bluetooth backend libraries to be installed, please read section [here](#bluetooth-backend-prerequisites) for details._
@@ -40,217 +41,17 @@ pip install https://github.com/undera/pylgbst/archive/1.0.tar.gz
 Then instantiate MoveHub object and start invoking its methods. Following is example to just print peripherals detected on Hub:  
 
 ```python
-from pylgbst.movehub import MoveHub
+from pylgbst.hub import MoveHub
 
 hub = MoveHub()
 
-for device in hub.devices:
+for device in hub.peripherals:
     print(device)
 ```
 
-### Controlling Motors
-
-MoveHub provides motors via following fields:
-- `motor_A` - port A
-- `motor_B` - port B
-- `motor_AB` - motor group of A+B manipulated together
-- `motor_external` - external motor attached to port C or D
-
-Methods to activate motors are:
-- `constant(speed_primary, speed_secondary)` - enables motor with specified speed forever 
-- `timed(time, speed_primary, speed_secondary)` - enables motor with specified speed for `time` seconds, float values accepted
-- `angled(angle, speed_primary, speed_secondary)` - makes motor to rotate to specified angle, `angle` value is integer degrees, can be negative and can be more than 360 for several rounds
-- `stop()` - stops motor at once, it is equivalent for `constant(0)`
-
-Parameter `speed_secondary` is used when it is motor group of `motor_AB` running together. By default, `speed_secondary` equals `speed_primary`. Speed values range is `-1.0` to `1.0`, float values. _Note: In group angled mode, total rotation angle is distributed across 2 motors according to motor speeds ratio._
-
-All these methods are synchronous by default, means method does not return untill it gets confirmation from Hub that command has completed. You can pass `async=True` parameter to any of methods to switch into asynchronous, which means command will return immediately, without waiting for rotation to complete. Be careful with asynchronous calls, as they make Hub to stop reporting synchronizing statuses.
-
-An example:
-```python
-from pylgbst.movehub 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.movehub 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.
-
-An example:
-
-```python
-from pylgbst.movehub import MoveHub, TiltSensor
-import time
-
-def callback(pitch, roll, yaw):
-    print("Pitch: %s / Roll: %s / Yaw: %s" % (pitch, roll, yaw))
-
-hub = MoveHub()
-
-hub.tilt_sensor.subscribe(callback, mode=TiltSensor.MODE_3AXIS_FULL)
-time.sleep(60) # turn MoveHub block in different ways
-hub.tilt_sensor.unsubscribe(callback)
-```
-
-`TiltSensor` sensor mode constants:
-- `MODE_2AXIS_SIMPLE` - use `callback(state)` for 2-axis simple state detect
-- `MODE_2AXIS_FULL` - use `callback(roll, pitch)` for 2-axis roll&pitch degree values
-- `MODE_3AXIS_SIMPLE` - use `callback(state)` for 3-axis simple state detect
-- `MODE_3AXIS_FULL` - use `callback(roll, pitch)` for 2-axis roll&pitch degree values
-- `MODE_BUMP_COUNT` - use `callback(count)` to detect bumps
-
-There are tilt sensor constants for "simple" states, for 2-axis mode their names are also available through `TiltSensor.DUO_STATES`:
-- `DUO_HORIZ` - "HORIZONTAL"
-- `DUO_DOWN` - "DOWN"
-- `DUO_LEFT` - "LEFT"
-- `DUO_RIGHT` - "RIGHT"
-- `DUO_UP` - "UP"
-  
-For 3-axis simple mode map name is `TiltSensor.TRI_STATES` with values:
-- `TRI_BACK` - "BACK"
-- `TRI_UP` - "UP"
-- `TRI_DOWN` - "DOWN"
-- `TRI_LEFT` - "LEFT"
-- `TRI_RIGHT` - "RIGHT"
-- `TRI_FRONT` - "FRONT"
-
-
-### Color & Distance Sensor
-
-Field named `color_distance_sensor` holds instance of `ColorDistanceSensor`, if one is attached to MoveHub. Sensor has number of different modes to subscribe. 
-
-Colors that are detected are part of `COLORS` map (see [LED](#led) section). Only several colors are possible to detect: `BLACK`, `BLUE`, `CYAN`, `YELLOW`, `RED`, `WHITE`. Sensor does its best to detect best color, but only works when sample is very close to sensor.
-
-Distance works in range of 0-10 inches, with ability to measure last inch in higher detail.
-
-Simple example of subscribing to sensor:
-
-```python
-from pylgbst.movehub import MoveHub, ColorDistanceSensor
-import time
-
-def callback(clr, distance):
-    print("Color: %s / Distance: %s" % (clr, distance))
-
-hub = MoveHub()
-
-hub.color_distance_sensor.subscribe(callback, mode=ColorDistanceSensor.COLOR_DISTANCE_FLOAT)
-time.sleep(60) # play with sensor while it waits   
-hub.color_distance_sensor.unsubscribe(callback)
-```
-
-Subscription mode constants in class `ColorDistanceSensor` are:
-- `COLOR_DISTANCE_FLOAT` - default mode, use `callback(color, distance)` where `distance` is float value in inches
-- `COLOR_ONLY` - use `callback(color)`
-- `DISTANCE_INCHES` - use `callback(color)` measures distance in integer inches count
-- `COUNT_2INCH` - use `callback(count)` - it counts crossing distance ~2 inches in front of sensor
-- `DISTANCE_HOW_CLOSE` - use `callback(value)` - value of 0 to 255 for 30 inches, larger with closer distance
-- `DISTANCE_SUBINCH_HOW_CLOSE` - use `callback(value)` - value of 0 to 255 for 1 inch, larger with closer distance
-- `LUMINOSITY` - use `callback(luminosity)` where `luminosity` is float value from 0 to 1
-- `OFF1` and `OFF2` - seems to turn sensor LED and notifications off
-- `STREAM_3_VALUES` - use `callback(val1, val2, val3)`, sends some values correlating to distance, not well understood at the moment
-
-Tip: laser pointer pointing to sensor makes it to trigger distance sensor
-
-### LED
-
-`MoveHub` class has field `led` to access color LED near push button. To change its color, use `set_color(color)` method. 
-
-You can obtain colors are present as constants `COLOR_*` and also a map of available color-to-name as `COLORS`. There are 12 color values, including `COLOR_BLACK` and `COLOR_NONE` which turn LED off.
-
-Additionally, you can subscribe to LED color change events, using callback function as shown in example below.
-
-```python
-from pylgbst.movehub import MoveHub, COLORS, COLOR_NONE, COLOR_RED
-import time
+Each peripheral kind has own methods to do actions and/or get sensor data. See [features](#features) list for individual doc pages.
 
-def callback(clr):
-    print("Color has changed: %s" % clr)
-
-hub = MoveHub()
-hub.led.subscribe(callback)
-
-hub.led.set_color(COLOR_RED)
-for color in COLORS:
-    hub.led.set_color(color)
-    time.sleep(0.5)
-    
-hub.led.set_color(COLOR_NONE)
-hub.led.unsubscribe(callback)
-```
-
-Tip: blinking orange color of LED means battery is low.
-
-### Push Button
-
-`MoveHub` class has field `button` to subscribe to button press and release events.
-
-Note that `Button` class is not real `Peripheral`, as it has no port and not listed in `devices` field of Hub. Still, subscribing to button is done usual way: 
-
-```python
-from pylgbst.movehub import MoveHub
-
-def callback(is_pressed):
-    print("Btn pressed: %s" % is_pressed)
-
-hub = MoveHub()
-hub.button.subscribe(callback)
-```
-
-### Power Voltage & Battery
-
-`MoveHub` class has field `voltage` to subscribe to battery voltage status. Callback accepts single parameter with current value. The range of values is float between `0` and `1.0`. Every time data is received, value is also written into `last_value` field of `Voltage` object. Values less than `0.2` are known as lowest values, when unit turns off.
-
-```python
-from pylgbst.movehub import MoveHub
-import time
-
-def callback(value):
-    print("Voltage: %s" % value)
-
-hub = MoveHub()
-hub.voltage.subscribe(callback)
-time.sleep(1)
-print ("Value: " % hub.voltage.last_value)
-```
-
-## General Notes
-
-### Bluetooth Backend Prerequisites
+## Bluetooth Backend Prerequisites
 
 You have following options to install as Bluetooth backend:
 
@@ -278,43 +79,17 @@ There is optional parameter for `MoveHub` class constructor, accepting instance
 
 All the functions above have optional arguments to specify adapter name and MoveHub mac address. Please look function source code for details.
 
-If you want to specify name for Bluetooth interface to use on local computer, you can passthat to class or function of getting a connection. Then pass connection object to `MoveHub` constructor. Like this:
+If you want to specify name for Bluetooth interface to use on local computer, you can pass that to class or function of getting a connection. Then pass connection object to `MoveHub` constructor. Like this:
 ```python
-from pylgbst.movehub import MoveHub
+from pylgbst.hub import MoveHub
 from pylgbst.comms.cgatt import GattConnection
 
 conn = GattConnection("hci1")
-conn.connect()  # you can pass MoveHub mac address as parameter here, like 'AA:BB:CC:DD:EE:FF'
+conn.connect()  # you can pass Hub mac address as parameter here, like 'AA:BB:CC:DD:EE:FF'
 
 hub = MoveHub(conn)
 ```
 
-### Use Disconnect in `finally`
-
-It is recommended to make sure `disconnect()` method is called on connection object after you have finished your program. This ensures Bluetooth subsystem is cleared and avoids problems for subsequent re-connects of MoveHub. The best way to do that in Python is to use `try ... finally` clause:
-
-```python
-from pylgbst import get_connection_auto
-from pylgbst.movehub import MoveHub
-
-conn=get_connection_auto()  # ! don't put this into `try` block
-try:
-    hub = MoveHub(conn)
-finally:
-    conn.disconnect()
-```
-
-### Devices Detecting
-As part of instantiating process, `MoveHub` waits up to 1 minute for all builtin devices to appear, such as motors on ports A and B, tilt sensor, button and battery. This not guarantees that external motor and/or color sensor will be present right after `MoveHub` instantiated. Usually, sleeping for couple of seconds gives it enough time to detect everything.
-
-### Subscribing to Sensors
-Each sensor usually has several different "subscription modes", differing with callback parameters and value semantics. 
-
-There is optional `granularity` parameter for each subscription call, by default it is `1`. This parameter tells Hub when to issue sensor data notification. Value of notification has to change greater or equals to `granularity` to issue notification. This means that specifying `0` will cause it to constantly send notifications, and specifying `5` will cause less frequent notifications, only when values change for more than `5` (inclusive).
-
-It is possible to subscribe with multiple times for the same sensor. Only one, very last subscribe mode is in effect, with many subscriber callbacks allowed to receive notifications. 
-
-Good practice for any program is to unsubscribe from all sensor subscriptions before ending, especially when used with `DebugServer`.
 
 ## Debug Server
 Running debug server opens permanent BLE connection to Hub and listening on TCP port for communications. This avoids the need to re-start Hub all the time. 
@@ -331,18 +106,15 @@ Then push green button on MoveHub, so permanent BLE connection will be establish
 
 ## Roadmap & TODO
 
+- validate operations with other Hub types (train, PUP etc)
+- make connections to detect hub by UUID instead of name
 - document all API methods
-- make sure unit tests cover all important code
 - make debug server to re-establish BLE connection on loss
 
 ## Links
 
 - https://github.com/LEGO/lego-ble-wireless-protocol-docs - true docs for LEGO BLE protocol
 - https://github.com/JorgePe/BOOSTreveng - initial source of protocol knowledge
+- https://github.com/nathankellenicki/node-poweredup - JavaScript version of library
 - 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
-
-Original file line number
+Diff line change
 *.pyc
 build
 *.avi
 +test_real.py