aiy.leds

APIs to control the RGB LED in the button that connects to the Vision/Voice Bonnet, and the privacy LED with the Vision Kit.

These APIs are not compatible with the Voice HAT (V1 Voice Kit). To control the Voice HAT’s button LED, instead use aiy.board.Led.

For example, here’s how to blink the button’s red light:

import time
from aiy.leds import Leds, Color

with Leds() as leds:
    for _ in range(4):
        leds.update(Leds.rgb_on(Color.RED))
        time.sleep(1)
        leds.update(Leds.rgb_off())
        time.sleep(1)

For more examples, see leds_example.py.

These APIs are only for the RGB LED in the button and the Vision Kit’s privacy LED. To control LEDs you’ve attached to the bonnet’s GPIO pins or the LEDs named LED_1 and LED_2 on the Vision/Voice Bonnet, instead use aiy.pins.

class aiy.leds.Color

Bases: object

Defines colors as RGB tuples that can be used as color values with Leds.

BLACK = (0, 0, 0)
BLUE = (0, 0, 255)
CYAN = (0, 255, 255)
GREEN = (0, 255, 0)
PURPLE = (255, 0, 255)
RED = (255, 0, 0)
WHITE = (255, 255, 255)
YELLOW = (255, 255, 0)
static blend(color_a, color_b, alpha)

Creates a color that is a blend between two colors.

Parameters:
  • color_a – One of two colors to blend.
  • color_b – One of two colors to blend.
  • alpha – The alpha blend to apply between color_a and color_b, from 0.0 to 1.0, respectively. That is, 0.0 makes color_a transparent so only color_b is visible; 0.5 blends the two colors evenly; 1.0 makes color_b transparent so only color_a is visible.
Returns:

An RGB tuple.
class aiy.leds.Leds(reset=True)

Bases: object

Class to control the KTD LED driver chip in the button used with the Vision and Voice Bonnet.

class Channel(state, brightness)

Bases: object

Defines the configuration for each channel in the KTD LED driver.

You should not instantiate this class directly; instead create a dictionary of Channel objects with the other methods below, which you can then pass to update().

Parameters:
  • state – Either ON, OFF, or PATTERN.
  • brightness – A value between 0 and 255.
OFF = 0
ON = 1
PATTERN = 2
static installed()

Internal method to verify the Leds class is available.

pattern

Defines a blink pattern for the button’s LED. Must be set with a Pattern object. For example:

with Leds() as leds:
    leds.pattern = Pattern.blink(500)
    leds.update(Leds.rgb_pattern(Color.RED))
    time.sleep(5)
static privacy(enabled, brightness=255)

Creates a configuration for the privacy LED (channel 4).

You can instead use privacy_on() and privacy_off().

Parameters:
  • enabled – True to turn on the light; False to turn it off.
  • brightness – A value from 0 to 255.
Returns:

A dictionary with one Channel for the privacy LED (channel 4).
static privacy_off()

Creates an “off” configuration for the privacy LED (the front LED on the Vision Kit).

Returns:A dictionary with one Channel for the privacy LED (channel 4).
static privacy_on(brightness=255)

Creates an “on” configuration for the privacy LED (the front LED on the Vision Kit).

Parameters:brightness – A value from 0 to 255.
Returns:A dictionary with one Channel for the privacy LED (channel 4).
reset()

Resets the LED driver to a clean state.

static rgb(state, rgb)

Creates a configuration for the RGB channels: 1 (red), 2 (green), 3 (blue).

Generally, you should instead use convenience constructors such as rgb_on() and rgb_pattern().

Parameters:
Returns:

A dictionary of 3 Channel objects, representing red, green, and blue values.
static rgb_off()

Creates an “off” configuration for the button’s RGB LED.

Returns:A dictionary of 3 Channel objects, representing red, green, and blue values, all turned off.
static rgb_on(rgb)

Creates an “on” configuration for the button’s RGB LED.

Parameters:rgb – Either one of the Color constants or your own tuple of RGB values.
Returns:A dictionary of 3 Channel objects, representing red, green, and blue values.
static rgb_pattern(rgb)

Creates a “pattern” configuration for the button’s RGB LED, using the light pattern set with pattern and the color set here. For example:

with Leds() as leds:
    leds.pattern = Pattern.blink(500)
    leds.update(Leds.rgb_pattern(Color.RED))
    time.sleep(5)
Parameters:rgb – Either one of the Color constants or your own tuple of RGB values.
Returns:A dictionary of 3 Channel objects, representing red, green, and blue values.
update(channels)

Changes the state of an LED. Takes a dictionary of LED channel configurations, provided by various methods such as rgb_on(), rgb_off(), and rgb_pattern().

For example, turn on the red light:

with Leds() as leds:
    leds.update(Leds.rgb_on(Color.RED))
    time.sleep(2)
    leds.update(Leds.rgb_off())

Or turn on the privacy LED (Vision Kit only):

with Leds() as leds:
    leds.update(Leds.privacy_on())
    time.sleep(2)
    leds.update(Leds.privacy_off())
Parameters:channels – A dictionary of one or more Channel objects. Use the rgb_ and privacy_ methods to create a dictionary.
class aiy.leds.Pattern(period_ms, on_percent=0.5, rise_ms=0, fall_ms=0)

Bases: object

Defines an LED blinking pattern. Pass an instance of this to Leds.pattern.

Parameters:
  • period_ms – The period of time (in milliseconds) for each on/off sequence.
  • on_percent – Percent of time during the period to turn on the LED (the LED turns on at the beginning of the period).
  • rise_ms – Duration of time to fade the light on.
  • fall_ms – Duration of time to fade the light off.

The parameters behave as illustrated below.

rise_ms /----------\ fall_ms
       /            \
      /  on_percent  \
     #--------------------------------#
                  period_ms

Convenience method to create a blinking pattern.

Parameters:period_ms – The period of time (in milliseconds) for each on/off sequence.
Returns:A Pattern.
static breathe(period_ms)

Convenience method to create a breathing pattern (a blink that fades in and out).

Parameters:period_ms – The period of time (in milliseconds) for each on/off sequence.
Returns:A Pattern.
class aiy.leds.PrivacyLed(leds, brightness=32)

Bases: object

Helper class to turn Privacy LED off automatically.

When instantiated, the privacy LED turns on. It turns off whenever the code exits the scope in which this was created. For example:

# Turn the privacy LED on for 2 seconds
with PrivacyLed(Leds()):
    time.sleep(2)
Parameters:
  • leds – An instance of Leds.
  • brightness – A value between 0 and 255.
class aiy.leds.RgbLeds(leds, channels)

Bases: object

Helper class to turn RGB LEDs off automatically.

When instantiated, the privacy LED turns on. It turns off whenever the code exits the scope in which this was created. For example:

# Turn on the green LED for 2 seconds
with RgbLeds(Leds(), Leds.rgb_on(Color.GREEN)):
    time.sleep(2)
Parameters:
  • leds – An instance of Leds.
  • channels – A dictionary of one or more Channel objects. Use the Leds.rgb_ and Leds.privacy_ methods to create a dictionary.