diff --git a/README.md b/README.md index f03682e..d2273b8 100644 --- 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 index e69de29..4217aa0 100644 --- 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 index 38c133e..fc121c2 100644 --- 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): """