Blinkenhub Python API#

Install the module and the blinkenhub command from PyPI:

pip install blinkenhub

Control library and command-line interface for the Blinkenhub Mac mini stand.

Blinkenhub is a USB-attached ring of 17 RGB LEDs. This module talks to it over a serial port using a simple framed protocol: each command is serialized to little-endian binary and followed by a CRC-8 (CCITT) checksum. ESC and ETX bytes are escaped, and the frame ends with ETX. The device answers each frame with a single A (ACK) or N (NACK) byte.

Colors are expressed in HSV: hue in degrees [0.0, 360.0], and saturation and value (brightness) in [0.0, 1.0].

Example

Show a dim rainbow and spin it clockwise:

from blinkenhub import Blinkenhub, SetPixels, Rotate, mkrainbow

bh = Blinkenhub()  # auto-detect the device
bh.send(SetPixels(mkrainbow(0.25), 0))
bh.send(Rotate(Rotate.CW, 2.0, -1))

The blinkenhub console script (see main()) exposes the same functionality from the shell; run blinkenhub --help for details.

blinkenhub.device = None#

Serial port used by stop_animations() and the CLI commands. None means auto-detect. The CLI sets it from --port / BLINKENHUB_PORT.

exception blinkenhub.TimeoutException[source]#

Bases: Exception

Raised when the Blinkenhub does not reply to a command before the serial timeout.

class blinkenhub.HSV_Color(hue, saturation, value)[source]#

Bases: object

A single pixel color in the HSV color space.

h#

Hue in degrees, [0.0, 360.0].

Type:

float

s#

Saturation, [0.0, 1.0].

Type:

float

v#

Value (brightness), [0.0, 1.0].

Type:

float

Create a color.

Parameters:

  • hue (float) – Hue in degrees, [0.0, 360.0].

  • saturation (float) – Saturation, [0.0, 1.0].

  • value (float) – Value (brightness), [0.0, 1.0].

class blinkenhub.Blinkenhub(port=None)[source]#

Bases: object

Serial connection to a Blinkenhub device.

Handles device discovery, framing, and the ACK/NACK handshake. Commands are built from BlinkenhubCmd subclasses and sent with send().

ESC#

Escape byte; precedes any ESC or ETX byte in the payload.

Type:

int

ACK#

Reply sent by the device when it accepts a command.

Type:

str

NACK#

Reply sent by the device when it rejects a command.

Type:

str

ETX#

End-of-frame byte.

Type:

int

calculator#

CRC-8 (CCITT) calculator for frame checksums.

Type:

crc.Calculator

ser#

The open serial port.

Type:

serial.Serial

Open a connection to a Blinkenhub.

Parameters:

port (str, optional) – Serial device path, such as /dev/cu.usbmodem1101. If omitted, the first USB serial port whose manufacturer is Systemix and product is Blinkenhub is used.

Raises:

  • Exception – If port is omitted and no Blinkenhub is found.

  • serial.SerialException – If the serial port cannot be opened.

prepare_buf(buf)[source]#

Frame a raw payload for transmission.

Appends a CRC-8 checksum, escapes every ESC and ETX byte by prefixing it with ESC, and terminates the frame with ETX.

Parameters:

buf (bytes) – The serialized command.

Returns:

The framed bytes, ready to write to the serial port.

Return type:

bytearray

send(item, reply=True)[source]#

Send a command to the device.

Parameters:

  • item (BlinkenhubCmd) – The command to send. Any object that supports bytes() is accepted.

  • reply (bool) – If True (the default), wait for the device’s ACK/NACK reply.

Returns:

True if the device acknowledged the command, or if reply is False. False if the device replied with anything other than ACK.

Return type:

bool

Raises:

TimeoutException – If reply is True and no reply arrives within the serial timeout (0.5 s).

class blinkenhub.BlinkenhubCmd(cmd)[source]#

Bases: object

Base class for all device commands.

Each command is sent as a 4-byte header (command ID, protocol version, and two padding bytes) followed by a command-specific payload. Subclasses must set self.buf to that payload.

VERSION#

Protocol version sent in every command header.

Type:

int

CMD_SET_PIXELS#

Command ID for SetPixels.

Type:

int

CMD_ANIMATE_HUE#

Command ID for HueAnimation.

Type:

int

CMD_ANIMATE_SATURATION#

Command ID for SaturationAnimation.

Type:

int

CMD_ANIMATE_VALUE#

Command ID for ValueAnimation.

Type:

int

CMD_ROTATE#

Command ID for Rotate.

Type:

int

CMD_SET_GAMMA#

Command ID for SetGamma.

Type:

int

cmd#

This command’s ID.

Type:

int

buf#

This command’s payload, set by the subclass.

Type:

bytes

Initialize the command header.

Parameters:

cmd (int) – One of the CMD_* command IDs.

class blinkenhub.Animation(cmd, typ, rate, top, bottom, count)[source]#

Bases: BlinkenhubCmd

Base class for commands that animate one HSV channel of every pixel.

Use one of the subclasses: HueAnimation, SaturationAnimation, or ValueAnimation.

ANIMATE_NONE#

No animation.

Type:

int

ANIMATE_UP#

Ramp from bottom to top.

Type:

int

ANIMATE_DOWN#

Ramp from top to bottom.

Type:

int

ANIMATE_UPDOWN#

Oscillate between bottom and top.

Type:

int

Build an animation command.

Parameters:

  • cmd (int) – The CMD_ANIMATE_* command ID.

  • typ (int) – One of the ANIMATE_* constants.

  • rate (float) – Speed in cycles per second.

  • top (float) – Upper limit of the animated channel.

  • bottom (float) – Lower limit of the animated channel.

  • count (int) – Number of cycles to run; -1 runs forever.

class blinkenhub.SetGamma(gamma)[source]#

Bases: BlinkenhubCmd

Set the gamma correction the device applies to pixel brightness.

Build a set-gamma command.

Parameters:

gamma (float) – Gamma exponent; 1.0 means no correction.

class blinkenhub.SetPixels(colors, fade_time)[source]#

Bases: BlinkenhubCmd

Set the color of each pixel, with an optional fade.

LEN_LIMIT#

Maximum number of pixels (the ring has 17).

Type:

int

Build a set-pixels command.

Parameters:

  • colors (list[HSV_Color]) – One color per pixel, starting at pixel 0.

  • fade_time (float) – Seconds to fade from the current colors to the new ones; 0 changes them at once.

Raises:

Exception – If colors has more than LEN_LIMIT entries.

class blinkenhub.HueAnimation(typ=0, rate=0.5, top=1, bottom=0.1, count=-1)[source]#

Bases: Animation

Animate the hue of every pixel.

Build a hue animation command.

Parameters:

  • typ (int) – One of the Animation.ANIMATE_* constants.

  • rate (float) – Speed in cycles per second.

  • top (float) – Upper hue limit in degrees, [0.0, 360.0].

  • bottom (float) – Lower hue limit in degrees, [0.0, 360.0].

  • count (int) – Number of cycles to run; -1 runs forever.

class blinkenhub.SaturationAnimation(typ=0, rate=0.5, top=1, bottom=0.1, count=-1)[source]#

Bases: Animation

Animate the saturation of every pixel.

Build a saturation animation command.

Parameters:

  • typ (int) – One of the Animation.ANIMATE_* constants.

  • rate (float) – Speed in cycles per second.

  • top (float) – Upper saturation limit, [0.0, 1.0].

  • bottom (float) – Lower saturation limit, [0.0, 1.0].

  • count (int) – Number of cycles to run; -1 runs forever.

class blinkenhub.ValueAnimation(typ=0, rate=0.5, top=1, bottom=0.1, count=-1)[source]#

Bases: Animation

Animate the value (brightness) of every pixel.

Build a value (brightness) animation command.

Parameters:

  • typ (int) – One of the Animation.ANIMATE_* constants.

  • rate (float) – Speed in cycles per second.

  • top (float) – Upper brightness limit, [0.0, 1.0].

  • bottom (float) – Lower brightness limit, [0.0, 1.0].

  • count (int) – Number of cycles to run; -1 runs forever.

class blinkenhub.Rotate(typ, rate, limit)[source]#

Bases: BlinkenhubCmd

Rotate the current pixel pattern around the ring.

NONE#

Stop rotating.

Type:

int

CW#

Rotate clockwise.

Type:

int

CCW#

Rotate counterclockwise.

Type:

int

CYLON#

Sweep back and forth over limit pixels.

Type:

int

Build a rotate command.

Parameters:

  • typ (int) – One of NONE, CW, CCW, or CYLON.

  • rate (float) – Speed in pixels per second.

  • limit (int) – In CYLON mode, the number of pixels to sweep across. The other modes pass -1.

blinkenhub.mkrainbow(value)[source]#

Build a rainbow that spans the full hue circle across the ring.

Parameters:

value (float) – Brightness of every pixel, [0.0, 1.0].

Returns:

17 fully saturated colors with evenly spaced hues.

Return type:

list[HSV_Color]

blinkenhub.stop_animations()[source]#

Stop any rotation and channel animations running on the device.

Connects to the port in the module-level device variable, which the CLI sets from --port.

blinkenhub.mk_random_colors(value)[source]#

Build a random pattern in which about half the pixels are lit.

Parameters:

value (float) – Brightness of the lit pixels, [0.0, 1.0].

Returns:

17 colors. Each is either off or a fully saturated random hue.

Return type:

list[HSV_Color]

blinkenhub.are_we_awake(cg)[source]#

Report whether any active display on this Mac is awake (macOS only).

Parameters:

cg (ctypes.CDLL) – The loaded CoreGraphics framework, with restype set to ctypes.c_int for CGDisplayIsAsleep and CGGetActiveDisplayList.

Returns:

True if at least one active display is awake, otherwise False.

Return type:

bool

blinkenhub.main()[source]#

Entry point for the blinkenhub command-line tool.

Builds the Click command group and runs it. The serial port can be given with --port or the BLINKENHUB_PORT environment variable; otherwise the device is detected automatically.