documenting peripherals

README.md

@@ -41,20 +41,56 @@ TODO: more usage instructions
 connection params
 hub's devices detect process & fields to access them
 general subscription modes & granularity info
-
+good practice is to unsubscribe, especially when used with `DebugServer`
 ### Motors
 ### Motor Rotation Sensors
 ### Tilt Sensor
 ### Color & Distance Sensor
 Tip: laser pointer pointing to sensor makes it trigger distance sensor
 ### LED
+
 ### Push Button
+
+Hub object has field `button` to subscribe to button press and release events. Note that `Button` class is not real `Peripheral`, we just mimic it. Subscribing to button uses internal mechanics which is slightly different from other peripherals.
+
+Still, subscribing to button is done usual way: 
+
+```python
+from pylgbst import MoveHub
+
+def callback(is_pressed):
+    print("Btn pressed: %s" % is_pressed)
+
+hub = MoveHub()
+hub.button.subscribe(callback)
+```
+
 ### Power Voltage & Battery
 
+Hub object has field `battery` to subscribe to battery voltage status. Callback accepts single parameter with current value. The range of values is unknown, it's 2-byte integer. Every time data is received, value is also written into `last_value` field of Battery object.
+
+```python
+from pylgbst import MoveHub
+import time
+
+def callback(value):
+    print("Voltage: %s" % value)
+
+hub = MoveHub()
+hub.battery.subscribe(callback)
+time.sleep(1)
+print ("Value: " % hub.battery.last_value)
+```
+
+TODO: investigate `mode` parameter for battery
 
 ## 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. 
 
-```
+There is `DebugServerConnection` class that you can use with it, instead of `BLEConnection`. 
+
+Starting debug server is done like this:
+```bash
 sudo python -c "from pylgbst.comms import *; \
     import logging; logging.basicConfig(level=logging.DEBUG); \
     DebugServer(BLEConnection().connect()).start()"
@@ -62,13 +98,11 @@ sudo python -c "from pylgbst.comms import *; \
 
 ## TODO
 
-- 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
+- handle device detach and device attach events on ports C/D
 - generalize getting device info + give constants (low priority)
-- can we subscribe to LED?
 - organize requesting and printing device info on startup - firmware version at least
 - make debug server to re-establish BLE connection on loss
 

pylgbst/peripherals.py

@@ -380,7 +380,7 @@ class Battery(Peripheral):
     # good 7.5v ~= 3892
     # liion 5v ~= 2100
     def handle_port_data(self, data):
-        self.last_value = unpack("<h", data[4:6])[0]
+        self.last_value = unpack("<H", data[4:6])[0]
         log.warning("Battery: %s"), self.last_value
         self._notify_subscribers(self.last_value)
 
@@ -391,7 +391,7 @@ class Button(Peripheral):
     """
 
     def __init__(self, parent):
-        super(Button, self).__init__(parent, 0)
+        super(Button, self).__init__(parent, 0)  # fake port 0
 
     def subscribe(self, callback, mode=None, granularity=1, async=False):
         cmd = pack("<B", PACKET_VER) + pack("<B", MSG_DEVICE_INFO) + b'\x02\x02'