doc updates

todbot · Jul 20, 2019 · 6fbc8a8 · 6fbc8a8
1 parent 7ef97eb
commit 6fbc8a8
Show file tree

Hide file tree

Showing 3 changed files with 161 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -19,6 +19,7 @@ https://blink1.thingm.com/
    * [Servertickle watchdog](#servertickle-watchdog)
    * [Gamma correction](#gamma-correction)
    * [White point correction](#white-point-correction)
+* [API reference](#api-reference)
 * [Developer installation](#developer-installation)
 
 ## About this library
@@ -226,6 +227,157 @@ The library supports the following temperature names:
 * shade
 * blue-sky
 
+## API reference
+```
+Help on class Blink1 in blink1.blink1:
+
+blink1.blink1.Blink1 = class Blink1
+ |  Light controller class, sends messages to the blink(1) via USB HID.
+ |  
+ |  Methods defined here:
+ |  
+ |  __init__(self, serial_number=None, gamma=None, white_point=None)
+ |      :param serial_number: serial number of blink(1) to open, otherwise first found
+ |      :param gamma: Triple of gammas for each channel e.g. (2, 2, 2)
+ |  
+ |  clear_pattern(self)
+ |      Clear entire color pattern in blink(1)
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  close(self)
+ |  
+ |  fade_to_color(self, fade_milliseconds, color, ledn=0)
+ |      Fade the light to a known colour
+ |      :param fade_milliseconds: Duration of the fade in milliseconds
+ |      :param color: Named color to fade to (e.g. "#FF00FF", "red")
+ |      :param ledn: which led to control
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  fade_to_rgb(self, fade_milliseconds, red, green, blue, ledn=0)
+ |      Command blink(1) to fade to RGB color
+ |      :param fade_milliseconds: millisecs duration of fade
+ |      :param red: 0-255
+ |      :param green: 0-255
+ |      :param blue: 0-255
+ |      :param ledn: which LED to control (0=all, 1=LED A, 2=LED B)
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  fade_to_rgb_uncorrected(self, fade_milliseconds, red, green, blue, ledn=0)
+ |      Command blink(1) to fade to RGB color, no color correction applied.
+ |      :throws: Blink1ConnectionFailed if blink(1) is disconnected
+ |  
+ |  get_serial_number(self)
+ |      Get blink(1) serial number
+ |      :return blink(1) serial number as string
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  get_version(self)
+ |      Get blink(1) firmware version
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  notfound(self)
+ |  
+ |  off(self)
+ |      Switch the blink(1) off instantly
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  play(self, start_pos=0, end_pos=0, count=0)
+ |      Play internal color pattern
+ |      :param start_pos: pattern line to start from
+ |      :param end_pos: pattern line to end at
+ |      :param count: number of times to play, 0=play forever
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  play_pattern(self, pattern_str, onDevice=True)
+ |      Play a Blink1Control-style pattern string
+ |      :param pattern_str: The Blink1Control-style pattern string to play
+ |      :param onDevice: True (default) to run pattern on blink(1),
+ |                       otherwise plays in Python process
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  play_pattern_local(self, pattern_str)
+ |      Play a Blink1Control pattern string in Python process
+ |          (plays in blink1-python, so blocks)
+ |      :param pattern_str: The Blink1Control-style pattern string to play
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  read(self)
+ |      Read command result from blink(1), low-level internal use
+ |      Receive USB Feature Report 0x01 from blink(1) with 8-byte payload
+ |      Note: buf must be 8 bytes or bad things happen
+ |  
+ |  read_pattern(self)
+ |      Read the entire color pattern
+ |      :return List of pattern line tuples
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  read_pattern_line(self, pos)
+ |      Read a color pattern line at position
+ |      :param pos: pattern line to read
+ |      :return pattern line data as tuple (r,g,b, step_millis) or False on err
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  save_pattern(self)
+ |      Save internal RAM pattern to flash
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  server_tickle(self, enable, timeout_millis=0, stay_lit=False, start_pos=0, end_pos=16)
+ |      Enable/disable servertickle / serverdown watchdog
+ |      :param: enable: Set True to enable serverTickle
+ |      :param: timeout_millis: millisecs until servertickle is triggered
+ |      :param: stay_lit: Set True to keep current color of blink(1), False to turn off
+ |      :param: start_pos: Sub-pattern start position in whole color pattern
+ |      :param: end_pos: Sub-pattern end position in whole color pattern
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  set_ledn(self, ledn=0)
+ |      Set the 'current LED' value for writePatternLine
+ |      :param ledn: LED to adjust, 0=all, 1=LEDA, 2=LEDB
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  stop(self)
+ |      Stop internal color pattern playing
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  write(self, buf)
+ |      Write command to blink(1), low-level internal use
+ |      Send USB Feature Report 0x01 to blink(1) with 8-byte payload
+ |      Note: arg 'buf' must be 8 bytes or bad things happen
+ |      :return: number of bytes written or -1 if failure
+ |  
+ |  write_pattern_line(self, step_milliseconds, color, pos, ledn=0)
+ |      Write a color & step time color pattern line to RAM
+ |      :param step_milliseconds: how long for this pattern line to take
+ |      :param color: LED color
+ |      :param pos: color pattern line number (0-15)
+ |      :param ledn: LED number to adjust, 0=all, 1=LEDA, 2=LEDB
+ |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected
+ |  
+ |  ----------------------------------------------------------------------
+ |  Static methods defined here:
+ |  
+ |  color_to_rgb(color)
+ |      Convert color name or hexcode to (r,g,b) tuple
+ |      :param color: a color string, e.g. "#FF00FF" or "red"
+ |      :raises: InvalidColor: if color string is bad
+ |  
+ |  find(serial_number=None)
+ |      Find a praticular blink(1) device, or the first one
+ |      :param serial_number: serial number of blink(1) device (from Blink1.list())
+ |      :raises: Blink1ConnectionFailed: if blink(1) is not present
+ |  
+ |  list()
+ |      List blink(1) devices connected, by serial number
+ |      :return: List of blink(1) device serial numbers
+ |  
+ |  parse_pattern(pattern_str)
+ |      Parse a Blink1Control pattern string to a list of pattern lines
+ |          e.g. of the form '10,#ff00ff,0.1,0,#00ff00,0.1,0'
+ |      :param pattern_str: The Blink1Control-style pattern string to parse
+ |      :returns: an list of dicts of the parsed out pieces
+```
+
+
 ## Developer installation
 
 Having checked out the `blink1-python` library, cd to its directory and run the setup script:

diff --git a/blink1/__init__.py b/blink1/__init__.py
@@ -0,0 +1,8 @@
+""" blink1 library for python
+"""
+
+#__all__ = [
+#    'Blink1',
+#    'Blink1ConnectionFailed',
+#]
+#from .blink1 import Blink1,Blink1ConnectionFailed
diff --git a/blink1/blink1.py b/blink1/blink1.py
@@ -71,7 +71,7 @@ def __call__(self, r, g, b):
 
 
 class Blink1:
-    """Light controller class, sends messages to the blink(1) and blink(1) mk2 via USB HID.
+    """Light controller class, sends messages to the blink(1) via USB HID.
     """
     def __init__(self, serial_number=None, gamma=None, white_point=None):
         """