TILT sensor documented

README.md

@@ -1,6 +1,8 @@
-# Python library to interact with LEGO Move Hub
+# Python library to interact with Move Hub
 
-Best way to start is to look into [`demo.py`](demo.py) file, and run it.
+_Move Hub is central robotic controller block of [LEGO Boost](https://www.lego.com/en-us/boost) Set._
+
+Best way to start with this library is to look into [`demo.py`](demo.py) file, and run it.
 
 If you have Vernie assembled, you might look into and run scripts from [`vernie`](vernie/) directory.
 
@@ -43,17 +45,42 @@ hub's devices detect process & fields to access them
 general subscription modes & granularity info
 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
 
 ### Motor Rotation Sensors
 
 ### Tilt Sensor
 
-MoveHub's internal tilt sensor is available through filed `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 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
 
 ### 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. Only one, very last subscribe mode is in effect, with many subscriber callbacks allowed. 
+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.
 

demo.py

@@ -78,7 +78,7 @@ def demo_tilt_sensor_simple(movehub):
         demo_tilt_sensor_simple.cnt += 1
         log.info("Tilt #%s of %s: %s", demo_tilt_sensor_simple.cnt, limit, TiltSensor.TILT_STATES[param1])
 
-    movehub.tilt_sensor.subscribe(callback)
+    movehub.tilt_sensor.subscribe(callback, mode=TiltSensor.MODE_2AXIS_SIMPLE)
     while demo_tilt_sensor_simple.cnt < limit:
         time.sleep(1)
 
@@ -94,7 +94,7 @@ def demo_tilt_sensor_precise(movehub):
         demo_tilt_sensor_simple.cnt += 1
         log.info("Tilt #%s of %s: roll:%s pitch:%s yaw:%s", demo_tilt_sensor_simple.cnt, limit, pitch, roll, yaw)
 
-    movehub.tilt_sensor.subscribe(callback, mode=TiltSensor.MODE_FULL)
+    movehub.tilt_sensor.subscribe(callback, mode=TiltSensor.MODE_3AXIS_FULL)
     while demo_tilt_sensor_simple.cnt < limit:
         time.sleep(1)
 
@@ -140,7 +140,7 @@ def demo_motor_sensors(movehub):
         demo_motor_sensors.states[movehub.motor_external] = None
         movehub.motor_external.subscribe(callback_e)
 
-    while None in demo_motor_sensors.states.values():  # demo_motor_sensors.states < limit:
+    while None in demo_motor_sensors.states.values():
         time.sleep(1)
 
     movehub.motor_A.unsubscribe(callback_a)
@@ -172,4 +172,8 @@ if __name__ == '__main__':
         connection = BLEConnection().connect()
 
     hub = MoveHub(connection)
-    demo_all(hub)
+    #demo_all(hub)
+    def callback(clr):
+        log.info("HERE %s", clr)
+    hub.led.subscribe(callback)
+    demo_led_colors(hub)

pylgbst/peripherals.py

@@ -252,9 +252,9 @@ class EncodedMotor(Peripheral):
 class TiltSensor(Peripheral):
     MODE_2AXIS_FULL = 0x00
     MODE_2AXIS_SIMPLE = 0x01
-    MODE_BASIC = 0x02
+    MODE_3AXIS_SIMPLE = 0x02
-    MODE_BUMP = 0x03
+    MODE_BUMP_COUNT = 0x03
-    MODE_FULL = 0x04
+    MODE_3AXIS_FULL = 0x04
 
     HORIZONTAL = 0x00
     UP = 0x01
@@ -276,24 +276,24 @@ class TiltSensor(Peripheral):
         SOME2: "RIGHT1",
     }
 
-    def subscribe(self, callback, mode=MODE_BASIC, granularity=1, async=False):
+    def subscribe(self, callback, mode=MODE_3AXIS_SIMPLE, granularity=1, async=False):
         super(TiltSensor, self).subscribe(callback, mode, granularity)
 
     def handle_port_data(self, data):
-        if self._port_subscription_mode == self.MODE_BASIC:
+        if self._port_subscription_mode == self.MODE_3AXIS_SIMPLE:
             state = data[4]
             self._notify_subscribers(state)
         elif self._port_subscription_mode == self.MODE_2AXIS_SIMPLE:
             state = data[4]
             self._notify_subscribers(state)
-        elif self._port_subscription_mode == self.MODE_BUMP:
+        elif self._port_subscription_mode == self.MODE_BUMP_COUNT:
             bump_count = data[4]
             self._notify_subscribers(bump_count)
         elif self._port_subscription_mode == self.MODE_2AXIS_FULL:
             roll = self._byte2deg(data[4])
             pitch = self._byte2deg(data[5])
             self._notify_subscribers(roll, pitch)
-        elif self._port_subscription_mode == self.MODE_FULL:
+        elif self._port_subscription_mode == self.MODE_3AXIS_FULL:
             roll = self._byte2deg(data[4])
             pitch = self._byte2deg(data[5])
             yaw = self._byte2deg(data[6])  # did I get the order right?