{"id":20995287,"url":"https://github.com/todbot/blink1-python","last_synced_at":"2025-04-10T00:16:45.622Z","repository":{"id":45707604,"uuid":"113372879","full_name":"todbot/blink1-python","owner":"todbot","description":"Official Python library for blink(1) USB RGB LED notification device","archived":false,"fork":false,"pushed_at":"2025-03-22T15:04:02.000Z","size":75,"stargazers_count":37,"open_issues_count":7,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-10T00:16:40.589Z","etag":null,"topics":["blink1","hid","rgb-led","usb"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/todbot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-06T22:15:22.000Z","updated_at":"2025-04-04T10:13:44.000Z","dependencies_parsed_at":"2022-09-26T17:41:07.493Z","dependency_job_id":null,"html_url":"https://github.com/todbot/blink1-python","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/todbot%2Fblink1-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/todbot%2Fblink1-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/todbot%2Fblink1-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/todbot%2Fblink1-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/todbot","download_url":"https://codeload.github.com/todbot/blink1-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131318,"owners_count":21052820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blink1","hid","rgb-led","usb"],"created_at":"2024-11-19T07:22:51.592Z","updated_at":"2025-04-10T00:16:45.612Z","avatar_url":"https://github.com/todbot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\nPython Blink(1) library\n========================\n\nOfficial Python library for blink(1) USB RGB LED notification devices\nhttps://blink1.thingm.com/\n\n* [About this library](#about-this-library)\n* [Installation](#installation)\n* [Example Code and Installed scripts](#example-code-and-installed-scripts)\n* [OS-specific notes](#os-specific-notes)\n   * [Linux:](#linux)\n   * [Mac OS X:](#mac-os-x)\n   * [Windows:](#windows)\n* [Use](#use)\n   * [Colors](#colors)\n   * [Pattern playing](#pattern-playing)\n   * [Servertickle watchdog](#servertickle-watchdog)\n   * [Gamma correction](#gamma-correction)\n   * [White point correction](#white-point-correction)\n* [API reference](#api-reference)\n* [Developer installation](#developer-installation)\n\n## About this library\n\nFeatures of this library:\n\n* Test coverage on all library components\n* Python 3.x compatible\n* Automatic installation via Python Package Index\n* High level control over the blink(1)\n* Single implementation with `cython-hidapi` USB HID API (PyUSB cannot access HID devices on all OSes)\n\nThis library lives at https://github.com/todbot/blink1-python\n\nOriginally written by @salimfadhley, at https://github.com/salimfadhley/blink1/tree/master/python/pypi.\nMoved to this repository and rewritten for `cython-hidapi` by @todbot.\n\n## Installation\n\nUse the `pip` utility to fetch the latest release of this package and any\nadditional components required in a single step:\n```\n  pip install blink1\n```\n\n## Example Code and Installed scripts\nTwo command-line scripts `blink1-shine` and `blink1-flash` are installed when this library is installed.\n* `blink1-shine` – Tell the blink(1) to be specifc steady color\n* `blink1-flash` – Flash the blink(1) two different colors at a specific rate\n\nFor examples, see the [`blink1_demo`](./blink1_demo/) directory for several examples on how to use this library.\n\n## OS-specific notes\nThe `blink1-python` library relies on [cython-hidapi](https://github.com/trezor/cython-hidapi) for USB HID access.  This package may require a C compiler and attendant utilities to be installed before installing this library.\n\n### Linux:\nThe following extra packages must be installed:\n```\n  sudo apt-get install python-dev libusb-1.0-0-dev libudev-dev\n```\nAnd udev rules for non-root user access to blink(1) devices:\n```\n  echo 'SUBSYSTEM==\"usb\", ATTRS{idVendor}==\"27b8\", ATTRS{idProduct}==\"01ed\", MODE:=\"666\", GROUP=\"plugdev\"' | sudo tee /etc/udev/rules.d/51-blink1.rules\n  sudo udevadm control --reload\n  sudo udevadm trigger\n```\n\n### Mac OS X:\nInstall [Xcode](https://developer.apple.com/xcode/) with command-line tools.\n\n### Windows:\nYou may need [Microsoft Visual C++ Compiler for Python 2.7](http://aka.ms/vcpython27)\n\n## Use\n\nThe simplest way to use this library is via a context manager.\n```\n  import time\n  from blink1.blink1 import blink1\n\n  with blink1() as b1:\n    b1.fade_to_color(100, 'navy')\n    time.sleep(10)\n```\n\nWhen the blink1() block exits the light is automatically switched off.\nIt is also possible to access the exact same set of functions without the context manager:\n```\n  import time\n  from blink1.blink1 import Blink1\n\n  b1 = Blink1()\n  b1.fade_to_rgb(1000, 64, 64, 64)\n  time.sleep(3)\n  b1.fade_to_rgb(1000, 255, 255, 255)\n```\n\nUnlike the context manager, this demo will leave the blink(1) open at the end of execution.\nTo close it, use the `b1.close()` method.\n\nTo list all connected blink(1) devices:\n```\n  from blink1.blink1 import Blink1\n  blink1_serials = Blink1.list()\n  print(\"blink(1) devices found: \" + ','.join(blink1_serials))\n```\n\nTo open a particular blink(1) device by serial number, pass in its serial number as a Unicode string:\n```\n  from blink1.blink1 import blink1\n  blink1 = Blink1(serial_number=u'20002345')\n  blink1.fade_to_rgb(1000, 255,0,255)\n  blink1.close()\n```\n\n### Colors\n\nThere are a number of ways to specify colors in this library:\n```\n  blink1.fade_to_color(1000, '#ffffff') # Hexdecimal RGB as a string\n  blink1.fade_to_color(1000, 'green') # Named color - any color name understood by css3\n  blink1.fade_to_color(1000, (22,33,44) # RGB as a tuple. Luminance values are 0 \u003c= lum \u003c= 255\n```\nAttempting to select a color outside the plausible range will generate an InvalidColor exception.\n\n\n### Pattern playing\n\nThe blink(1) device has a 16-line non-volatile color pattern memory.\nThis color pattern plays automatically if power is applied but not connected to a computer.\nYou can also trigger this pattern (or sub-patterns) over USB,\nleaving your application free to do other things besides blink lights.\n\nEach line in the color pattern consists of an R,G,B triplet and a fade time to reach that color.\n\nTo play the pattern in blink(1) or sub-patterns:\n```\nblink1.play()  # play entire color pattern, infinitely looped\nblink1.stop()  # stop a color pattern playing (if playing)\n\nblink1.play(2,3, count=7)  # play color pattern lines 2,3 in a loop 7 times\n```\n\nTo alter the lines of the pattern memory:\n```\n# write 100msec fades to green then yellow then black at lines 3,4,5\nblink1.write_pattern_line( 100, 'green',  3)\nblink1.write_pattern_line( 100, 'yellow', 4)\nblink1.write_pattern_line( 100, 'black',  5)\n\nblink1.play( 3,5, 4)  # play that sub-loop 4 times\n```\n\nTo save the pattern to non-volatile memory (overwriting the factory pattern):\n```\nblink1.save_pattern()\n```\n\nTo quickly play a pattern in Blink1Control-style string format:\n```\n# play purple on LED1 in 300ms, green on LED2 in 100ms, then swap, for 10 times\npattern_str = '10, #ff00ff,0.3,1, #00ff00,0.1,2,  #ff00ff,0.3,2, #00ff00,0.1,1'\nblink1.play_pattern(pattern_str)\n# wait 5 seconds while the pattern plays on the blink1\n# (or go do something more useful)\ntime.sleep(5.0)\n# flash red-off 5 times fast on all LEDs\nblink1.play_pattern('5, #FF0000,0.2,0,#000000,0.2,0')\n```\n\n### Servertickle watchdog\nblink(1) also has a \"watchdog\" of sorts called \"servertickle\".\nWhen enabled, you must periodically send it to the blink(1) or it will\ntrigger, playing the stored color pattern.  This is useful to announce\na computer that has crashed.  The blink(1) will flash on its own until\ntold otherwise.\n\nTo use, enable severtickle with a timeout value (max timeout 62 seconds):\n```\nblink1.server_tickle(enable=True, timeout_millis=2000)\n```\n\n\n### Gamma correction\n\nThe context manager supports a ''gamma'' argument which allows you to supply a per-channel gamma correction value.\n```\n  from blink1.blink1 import blink1\n\n  with blink1(gamma=(2, 2, 2)) as b1:\n    b1.fade_to_color(100, 'pink')\n    time.sleep(10)\n```\nThis example provides a gamma correction of 2 to each of the three colour channels.\n\nHigher values of gamma make the blink(1) appear more colorful but decrease the brightness of colours.\n\n### White point correction\n\nThe human eye's perception of color can be influenced by ambient lighting. In some circumstances it may be desirable\nto apply a small color correction in order to make colors appear more accurate. For example, if we were operating\nthe blink(1) in a room lit predominantly by candle-light:\n```\n  with blink1(white_point='candle', switch_off) as b1:\n    b1.fade_to_color(100, 'white')\n```\nViewed in daylight this would make the Blink(1) appear yellowish, however in a candle-lit room this would be perceived\nas a more natural white. If we did not apply this kind of color correction the Blink(1) would appear blueish.\n\nThe following values are acceptable white-points:\n\n* Any triple of (r,g,b). Each 0 \u003c= luminance \u003c= 255\n* Any color_temperature expressed as an integer or float in Kelvin\n* A color temperature name.\n\nThe library supports the following temperature names:\n\n* candle\n* sunrise\n* incandescent\n* tungsten\n* halogen\n* sunlight\n* overcast\n* shade\n* blue-sky\n\n## API reference\n```\nHelp on class Blink1 in blink1.blink1:\n\nblink1.blink1.Blink1 = class Blink1\n |  Light controller class, sends messages to the blink(1) via USB HID.\n |  \n |  Methods defined here:\n |  \n |  __init__(self, serial_number=None, gamma=None, white_point=None)\n |      :param serial_number: serial number of blink(1) to open, otherwise first found\n |      :param gamma: Triple of gammas for each channel e.g. (2, 2, 2)\n |  \n |  clear_pattern(self)\n |      Clear entire color pattern in blink(1)\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  close(self)\n |  \n |  fade_to_color(self, fade_milliseconds, color, ledn=0)\n |      Fade the light to a known colour\n |      :param fade_milliseconds: Duration of the fade in milliseconds\n |      :param color: Named color to fade to (e.g. \"#FF00FF\", \"red\")\n |      :param ledn: which led to control\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  fade_to_rgb(self, fade_milliseconds, red, green, blue, ledn=0)\n |      Command blink(1) to fade to RGB color\n |      :param fade_milliseconds: millisecs duration of fade\n |      :param red: 0-255\n |      :param green: 0-255\n |      :param blue: 0-255\n |      :param ledn: which LED to control (0=all, 1=LED A, 2=LED B)\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  fade_to_rgb_uncorrected(self, fade_milliseconds, red, green, blue, ledn=0)\n |      Command blink(1) to fade to RGB color, no color correction applied.\n |      :raises: Blink1ConnectionFailed if blink(1) is disconnected\n |  \n |  get_serial_number(self)\n |      Get blink(1) serial number\n |      :return blink(1) serial number as string\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  get_version(self)\n |      Get blink(1) firmware version\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  notfound(self)\n |  \n |  off(self)\n |      Switch the blink(1) off instantly\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  play(self, start_pos=0, end_pos=0, count=0)\n |      Play internal color pattern\n |      :param start_pos: pattern line to start from\n |      :param end_pos: pattern line to end at\n |      :param count: number of times to play, 0=play forever\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  play_pattern(self, pattern_str, onDevice=True)\n |      Play a Blink1Control-style pattern string\n |      :param pattern_str: The Blink1Control-style pattern string to play\n |      :param onDevice: True (default) to run pattern on blink(1),\n |                       otherwise plays in Python process\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  play_pattern_local(self, pattern_str)\n |      Play a Blink1Control pattern string in Python process\n |          (plays in blink1-python, so blocks)\n |      :param pattern_str: The Blink1Control-style pattern string to play\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  read(self)\n |      Read command result from blink(1), low-level internal use\n |      Receive USB Feature Report 0x01 from blink(1) with 8-byte payload\n |      Note: buf must be 8 bytes or bad things happen\n |  \n |  read_pattern(self)\n |      Read the entire color pattern\n |      :return List of pattern line tuples\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  read_pattern_line(self, pos)\n |      Read a color pattern line at position\n |      :param pos: pattern line to read\n |      :return pattern line data as tuple (r,g,b, step_millis) or False on err\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  save_pattern(self)\n |      Save internal RAM pattern to flash\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  server_tickle(self, enable, timeout_millis=0, stay_lit=False, start_pos=0, end_pos=16)\n |      Enable/disable servertickle / serverdown watchdog\n |      :param: enable: Set True to enable serverTickle\n |      :param: timeout_millis: millisecs until servertickle is triggered\n |      :param: stay_lit: Set True to keep current color of blink(1), False to turn off\n |      :param: start_pos: Sub-pattern start position in whole color pattern\n |      :param: end_pos: Sub-pattern end position in whole color pattern\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  set_ledn(self, ledn=0)\n |      Set the 'current LED' value for writePatternLine\n |      :param ledn: LED to adjust, 0=all, 1=LEDA, 2=LEDB\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  stop(self)\n |      Stop internal color pattern playing\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  write(self, buf)\n |      Write command to blink(1), low-level internal use\n |      Send USB Feature Report 0x01 to blink(1) with 8-byte payload\n |      Note: arg 'buf' must be 8 bytes or bad things happen\n |      :raises: Blink1ConnectionFailed if blink(1) is disconnected\n |  \n |  write_pattern_line(self, step_milliseconds, color, pos, ledn=0)\n |      Write a color \u0026 step time color pattern line to RAM\n |      :param step_milliseconds: how long for this pattern line to take\n |      :param color: LED color\n |      :param pos: color pattern line number (0-15)\n |      :param ledn: LED number to adjust, 0=all, 1=LEDA, 2=LEDB\n |      :raises: Blink1ConnectionFailed: if blink(1) is disconnected\n |  \n |  ----------------------------------------------------------------------\n |  Static methods defined here:\n |  \n |  color_to_rgb(color)\n |      Convert color name or hexcode to (r,g,b) tuple\n |      :param color: a color string, e.g. \"#FF00FF\" or \"red\"\n |      :raises: InvalidColor: if color string is bad\n |  \n |  find(serial_number=None)\n |      Find a praticular blink(1) device, or the first one\n |      :param serial_number: serial number of blink(1) device (from Blink1.list())\n |      :raises: Blink1ConnectionFailed: if blink(1) is not present\n |  \n |  list()\n |      List blink(1) devices connected, by serial number\n |      :return: List of blink(1) device serial numbers\n |  \n |  parse_pattern(pattern_str)\n |      Parse a Blink1Control pattern string to a list of pattern lines\n |          e.g. of the form '10,#ff00ff,0.1,0,#00ff00,0.1,0'\n |      :param pattern_str: The Blink1Control-style pattern string to parse\n |      :returns: an list of dicts of the parsed out pieces\n```\n\n\n## Developer installation\n\nHaving checked out the `blink1-python` library, cd to its directory and run the setup script:\n```\n  git clone https://github.com/todbot/blink1-python\n  cd blink1-python\n  pip3 install --editable .\n  python3 ./blink1_demo/demo1.py\n```\nYou can now use the `blink1` package on your system and edit it.\n\nTo get internal blink1 library debug, messages set the environment variable `DEBUGBLINK1`:\n```\nDEBUGBLINK1=1 python3 ./blink1_demo/demo_logging.py\n```\n\nTo uninstall the development version:\n```\n  pip3 uninstall blink1\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftodbot%2Fblink1-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftodbot%2Fblink1-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftodbot%2Fblink1-python/lists"}