jled¶

class JLed(pin=None, hal=None)[source]¶

JLed class

construct a new JLed object connected to the given pin, or using the provided hal object.

Parameters:

pin – the pin to connect the JLed object to
hal – the HAL object to use

Either pin or hal must be provided. If pin is provided, a HAL instance using JLed._DEFAULT_PWM_HAL will be created.

Unless you have special requirements, you will want to initialize your JLed object like led = JLed(board.LED).breathe(1000), i.e. by providing the pin the LED is connected to.

blink(duration_on, duration_off)[source]¶

In blink mode, the LED cycles through a given number of on-off cycles. On- and Off-cycle durations are specified independently.

Parameters:

duration_on – time in ms to turn the LED on
duration_off – time in ms to turn the LED off

Returns:

this JLed instance

breathe(duration_fade_on, duration_on=None, duration_fade_off=None)[source]¶

In breathing mode, the LED smoothly changes the brightness using PWM. The breathe method takes the period of the effect as an argument, however it is also possible to specify fade-on, on- and fade-off durations for the breathing mode to customize the effect.

Parameters:

duration_fade_on – if only this parameter is set, then duration_fade_on specifies the time in ms of a full breathe period. If also duration_on and duration_off are set, this parameter specifies the fade-on time only.
duration_on – if set, specifies time to keep effect at maximum
duration_off – if set, specifies fade-off time

Returns:

this JLed instance

candle(speed=6, jitter=15, period=65535)[source]¶

In candle mode, the random flickering of a candle or fire is simulated. The idea was taken from here

Parameters:

speed – controls the speed of the effect. 0 for fastest, increasing speed divides into halve per increment. The default value is 6.
jitter – the amount of jittering. 0 none (constant on), 255 maximum. Default value is 15.
period –
- Period of effect in ms. The default value is 65535 ms.

The default settings simulate a candle. For a fire effect for example use call the method with e.g. speed=5 and jitter=100.

Returns:: this JLed instance

deinit()[source]¶: Call deinit to free hardware resources used by this object

delay_after(time)[source]¶

Use the delay_after method to specify a delay after each repetition of an effect. The default value is 0 ms.

Parameters:: time – delay time in milliseconds
Returns:: this JLed instance

delay_before(time)[source]¶

Use the delay_before method to specify a delay before the first effect starts. The default value is 0 ms.

Parameters:: time – delay time in milliseconds
Returns:: this JLed instance

fade(start, end, period)[source]¶

The fade effect allows to fade from any start value start to any target value end with the given period. Internally it sets up a fade() or fade_off() effect and min_brightness() and max_brightness() values properly.

Parameters:

start – start brightness values
end – end brightness value
period – period of the effect

Returns:

this JLed instance

fade_off(period)[source]¶

In fade_off mode, the LED is smoothly faded off using PWM. The fade starts at 100% brightness. Internally it is implemented as a mirrored version of the fade_on() function, i.e. fade_off(t) = fade_on(period-t).

Parameters:: period – period of the effect
Returns:: this JLed instance

fade_on(period)[source]¶

In fade_on mode, the LED is smoothly faded on to 100% brightness using PWM. The fade_on method takes the period of the effect as an argument.

The brightness function uses an approximation of this function (example with period 1000.

Parameters:: period – period of the effect
Returns:: this JLed instance

forever()[source]¶

Set effect to run forever.

Returns:: this JLed instance

property is_forever¶

Returns:: True if effect is set to run forever, otherwise False.

property is_running¶

Returns:: True if the effect is running, otherwise False.

low_active(val=True)[source]¶: Use the low_active method when the connected LED is low active. All output will be inverted by JLed (i.e. instead of x, the value of 255-x will be set).

max_brightness(level)[source]¶

The max_brightness method is used to set the maximum brightness level of the LED. A level of 255 (the default) is full brightness, while 0 effectively turns the LED off. In the same way, the min_brightness method sets the minimum brightness level. The default minimum level is 0. If minimum or maximum brightness levels are set, the output value is scaled to be within the interval defined by [minimum brightness, maximum brightness]: a value of 0 will be mapped to the minimum brightness level, a value of 255 will be mapped to the maximum brightness level.

Returns:: this JLed instance

min_brightness(level)[source]¶

See max_brightness()

Returns:: this JLed instance

off(period=1)[source]¶

The off method works like on(), except that it turns the LED off, i.e. it sets the brightness to 0.

Parameters:: period – period of the effect. Period will be relevant when multiple JLed objects are controlled by a JLedSequence
Returns:: this JLed instance

on(period=1)[source]¶

Calling on turns the LED on. To immediately turn a LED on, remember to also call update() like in JLed(board.LED).on().update(). The period is optional and defaults to 1ms. on basically calls set() with brightness set to 255.

Parameters:: period – period of the effect. Period will be relevant when multiple JLed objects are controlled by a JLedSequence
Returns:: this JLed instance

repeat(num)[source]¶

Use the repeat method to specify the number of repetitions. The default value is 1 repetition. The forever() method sets to repeat the effect forever. Each repetition includes a full period of the effect and the time specified by delay_after() method.

Parameters:: num – number of repetitions
Returns:: this JLed instance

reset()[source]¶: A call to reset brings the JLed object to its initial state. Use it when you want to start-over an effect.

set(brightness, period=1)[source]¶

Use the set method to set the brightness to the given value.

Parameters:

brightness – brightness (0..255) to set
period – period of the effect. Period will be relevant when multiple JLed objects are controlled by a JLedSequence

Returns:

this JLed instance

stop()[source]¶

Call stop to immediately turn the LED off and stop any running effects. Further calls to update() will have no effect unless the reset() method is called or a new effect is activated.

Returns:: this JLed instance

update()[source]¶

Call update periodically to update the LED.

Returns:: True if the effect is active, otherwise False, when finished.

user_func(user_eval)[source]¶

It is also possible to provide a user defined brightness evaluator. The class must implement two methods:

eval(t) - the brightness evaluation function that calculates a brightness for the given time t. The brightness must be returned as an unsigned byte , where 0 means LED off and 255 means full brightness. period() - returns the period of the effect.

The unit of time is milliseconds.

# SPDX-FileCopyrightText: Copyright (c) 2022 Jan Delgado
# SPDX-License-Identifier: MIT
"""
JLed User defined effect example
"""

import board
from jled import JLed


class UserEffect:
    def __init__(self, period):
        self._period = period

    def eval(self, t):
        """this function returns changes between 0 and 255 and
        vice versa every period/2 ms"""
        return 255 * ((t // (self._period >> 1)) & 1)

    def period(self):
        return self._period


led = JLed(board.LED).user_func(UserEffect(1000)).forever()

while True:
    led.update()

Returns:: this JLed instance

class JLedSequence(mode, leds)[source]¶

The JLedSequence class allows controlling a group of effects either in parallel or sequentially. An effect is either a JLed object or a JLedSequence.

Example:

from jled import JLed, JLedSequence

led1 = JLed(board.LED).blink(500, 250).repeat(5)
led2 = JLed(board.GP2).breathe(1000).repeat(5)

seq = JLedSequence(JLedSequence.SEQUENTIAL, [led1, led2])

Construct a JLedSequence for the given list of effects. An effect can be either a JLed object, or another JLedSequence.

For convenience, two additional functions are provided: parallel() and sequential()

Parameters:

mode – one of JLedSequence.PARALLEL or JLedSequence.SEQUENTIAL
leds – list of effects to control

forever()[source]¶

Set this JLedSequence to run forever.

Returns:: this JLedSequence object

property is_forever¶

Returns:: True if this JLedSequence is set to run forever(), otherwise False

property is_running¶

Returns:: True if JLedSequence is running, otherwise False.

static parallel(leds)[source]¶

Initialize a JLedSequence to play given effects in parallel. This is a convenience method for calling JLedSequence(JLedSequence.PARALLEL, leds).

Parameters:: leds – list of effects to play
Returns:: a new JLedSequence object

repeat(num)[source]¶

Use the repeat method to specify the number of repetitions. The default value is 1 repetition.

Parameters:: num – number of repetitions
Returns:: this JLedSequence object

reset()[source]¶

Reset all LEDs controlled by this JLedSequence and the JLedSequence itself. Calling update afterwards will start all all LEDs over.

Returns:: this JLedSequence object

static sequential(leds)[source]¶

Initialize a JLedSequence to play given effects sequentially. This is a convenience method for calling JLedSequence(JLedSequence.SEQUENTIAL, leds).

Parameters:: leds – list of effects to play
Returns:: a new JLedSequence object

stop()[source]¶

Turns off all objects controlled by this JLedSequence and stops the sequence. Further calls to update() will have no effect.

Returns:: this JLedSequence object

update()[source]¶

Call update periodically to play the effects/LEDs.

Returns:: True if the effect is still running, otherwise False

play(*leds, seq=False)[source]¶

play puts the given list of objects in a JLedSequence and runs the effects, until the last effect finished. This function is intended to be used when interactively exploring JLed in the Python REPL.

Example:

from jled import JLed, play

led1 = JLed(board.LED).blink(500, 250).repeat(5)
led2 = JLed(board.GP2).breathe(1000).repeat(5)

play(led1, led2)

Parameters:

leds – list of effects to “play”
seq – set to True to play effects sequentially. When False (default), effects will be played in parallel.