Documentation and code improvements.

Author: Gadgetoid

README.md

@@ -17,3 +17,92 @@ Latest/development library from GitHub:
 * `cd fanshim-python`
 * `sudo ./install.sh`
 
+# Reference
+
+You should first set up an instance of the `FANShim` class, eg:
+
+```
+from fanshim import FanShim
+fanshim = FanShim()
+```
+
+## Fan
+
+Turn the fan on with: `fanshim.set_fan(True)`
+
+Turn it off with: `fanshim.set_fan(False)`
+
+You can also toggle the fan with: `fanshim.toggle_fan()`
+
+## LED
+
+Fan Shim includes one RGB APA-102 LED.
+
+Set it to any colour with: `fanshim.set_light(r, g, b)`
+
+Arguments r, g and b should be numbers between 0 and 255 that describe the colour you want.
+
+For example, full red: `fanshim.set_light(255, 0, 0)`
+
+## Button
+
+Fan Shim includes a button, you can bind actions to press, release and hold events.
+
+Do something when the button is pressed:
+
+```
+@fanshim.on_press()
+def button_pressed():
+    print("The button has been pressed!")
+```
+
+Or when it has been released:
+
+```
+@fanshim.on_release()
+def button_released(was_held):
+    print("The button has been pressed!")
+```
+
+Or when it's been pressed long enough to trigger a hold:
+
+```
+fanshim.set_hold_time(2.0)
+
+@fanshim.on_hold()
+def button_held():
+    print("The button was held for 2 seconds")
+```
+
+The function you bind to `on_release()` is passed a `was_held` parameter,
+this lets you know if the button was held down for longer than the configured
+hold time. If you want to bind an action to "press" and another to "hold" you
+should check this flag and perform your action in the `on_release()` handler:
+
+```
+@fanshim.on_release()
+def button_released(was_held):
+    if was_held:
+        print("Long press!")
+    else:
+        print("Short press!")
+```
+
+To configure the amount of time the button should be held (in seconds), use:
+
+```
+fanshim.set_hold_time(number_of_seconds)
+```
+
+If you need to stop Fan Shim from polling the button, use:
+
+```
+fanshim.stop_polling()
+```
+
+You can start it again with:
+
+```
+fanshim.start_polling()
+```
+

examples/automatic.py

@@ -1,4 +1,4 @@
-from fanshim import FANShim
+from fanshim import FanShim
 import psutil
 import argparse
 import time
@@ -38,7 +38,7 @@ def set_automatic(status):
 
 args = parser.parse_args()
 
-fanshim = FANShim()
+fanshim = FanShim()
 fanshim.set_hold_time(1.0)
 fanshim.set_fan(False)
 armed = True

examples/button.py

@@ -1,5 +1,5 @@
 import signal
-from fanshim import FANShim
+from fanshim import FanShim
 
 """
 This example attaches basic pressed, released and held handlers for Fan SHIM's button.
@@ -11,7 +11,7 @@
 the "held" handler at all if you're just doing a standard short/long press action.
 """
 
-fanshim = FANShim()
+fanshim = FanShim()
 
 # Set the button hold time, in seconds
 fanshim.set_hold_time(1.0)

examples/led.py

@@ -1,8 +1,8 @@
-from fanshim import FANShim
+from fanshim import FanShim
 import time
 import colorsys
 
-fanshim = FANShim()
+fanshim = FanShim()
 fanshim.set_fan(False)
 
 try:

examples/toggle.py

@@ -1,5 +1,5 @@
 import signal
-from fanshim import FANShim
+from fanshim import FanShim
 
 """
 This example attaches basic pressed, released and held handlers for Fan SHIM's button.
@@ -11,7 +11,7 @@
 the "held" handler at all if you're just doing a standard short/long press action.
 """
 
-fanshim = FANShim()
+fanshim = FanShim()
 
 
 def update_led(state):

library/fanshim/__init__.py

@@ -7,13 +7,20 @@
 __version__ = '0.0.1'
 
 
-class FANShim():
-    def __init__(self):
-        self._pin_fancontrol = 18
-        self._pin_button = 17
+class FanShim():
+    def __init__(self, pin_fancontrol=18, pin_button=17):
+        """FAN Shim.
+
+        :param pin_fancontrol: BCM pin for fan on/off
+        :param pin_button: BCM pin for button
+
+        """
+        self._pin_fancontrol = pin_fancontrol
+        self._pin_button = pin_button
         self._button_press_handler = None
         self._button_release_handler = None
         self._button_hold_handler = None
+        self._button_hold_time = 2.0
         self._t_poll = None
 
         atexit.register(self._cleanup)
@@ -27,20 +34,23 @@ def __init__(self):
         plasma.set_light_count(1)
         plasma.set_light(0, 0, 0, 0)
 
-        self.start()
+        self.start_polling()
 
-    def start(self):
+    def start_polling(self):
+        """Start button polling."""
         if self._t_poll is None:
             self._t_poll = Thread(target=self._run)
             self._t_poll.daemon = True
             self._t_poll.start()
 
-    def stop(self):
+    def stop_polling(self):
+        """Stop button polling."""
         if self._t_poll is not None:
             self._running = False
             self._t_poll.join()
 
     def on_press(self, handler=None):
+        """Attach function to button press event."""
         def attach_handler(handler):
             self._button_press_handler = handler
 
@@ -50,6 +60,7 @@ def attach_handler(handler):
             return attach_handler
 
     def on_release(self, handler=None):
+        """Attach function to button release event."""
         def attach_handler(handler):
             self._button_release_handler = handler
 
@@ -59,6 +70,7 @@ def attach_handler(handler):
             return attach_handler
 
     def on_hold(self, handler=None):
+        """Attach function to button hold event."""
         def attach_handler(handler):
             self._button_hold_handler = handler
 
@@ -76,9 +88,11 @@ def set_hold_time(self, hold_time):
         self._button_hold_time = hold_time
 
     def get_fan(self):
+        """Get current fan state."""
         return GPIO.input(self._pin_fancontrol)
 
     def toggle_fan(self):
+        """Toggle fan state."""
         return self.set_fan(False if self.get_fan() else True)
 
     def set_fan(self, fan_state):
@@ -91,6 +105,13 @@ def set_fan(self, fan_state):
         return True if fan_state else False
 
     def set_light(self, r, g, b):
+        """Set LED.
+    
+        :param r: Red (0-255)
+        :param g: Green (0-255)
+        :param b: Blue (0-255)
+    
+        """
         plasma.set_light(0, r, g, b)
         plasma.show()