Introduction¶
An embedded library for Python to control LEDs. It uses a non-blocking approach and can control LEDs in simple (on/off) and complex (blinking, breathing and more) ways in a time-driven manner.
This is a pure Python port of my JLed C++ library.
![JLed in action](_images/jled.gif)
Features¶
non-blocking
effects: simple on/off, breathe, blink, candle, fade, user-defined
supports inverted polarity of LED
easy configuration using fluent interface
can control groups of LEDs sequentially or in parallel
supports CircuitPython and MicroPython
Usage Example¶
Test JLed interactively in a CircuitPython REPL:
Adafruit CircuitPython 7.3.3 on 2022-08-29; Raspberry Pi Pico with rp2040
>>> import board
>>> from jled import JLed
>>> led=JLed(board.LED).breathe(500).delay_after(250).repeat(5)
>>> while led.update(): pass
This creates a JLed object connected to the builtin LED (board.LED
), with a
breathe effect that is repeated 5 times. Each iteration is followed by a delay
of 250 ms, before starting again. By calling led.update()
periodically,
the LED gets physically updated. Alternatively play(led)
can be call in the
REPL as a shortcut. Once finished, call led.reset()
before playing the
effect again.
Cheat Sheet¶
![_images/jled_cheat_sheet.jpg](_images/jled_cheat_sheet.jpg)
Installation¶
On supported GNU/Linux systems like the Raspberry Pi (with Adafruit-Blinka), you can install the lib locally from PyPI. To install for current user:
pip3 install circuitpython-jled
To install system-wide (this may be required in some cases):
sudo pip3 install circuitpython-jled
To install in a virtual environment in your current project:
mkdir project-name && cd project-name
python3 -m venv .venv
source .env/bin/activate
pip3 install circuitpython-jled
Installing to a Connected CircuitPython Device with Circup¶
JLed
is available in the Circuitpython Community Bundle
and can easily installed with circup by
running:
$ circup install jled
Optionally copy also one of the example as code.py
to the root of the filesystem.
Installing on a MicroPython device¶
Create a directory called jled
on the device and copy the following files into this directory:
into this directory: jled.py
, jled_sequence.py
hal_pwm_micropython.py
, hal_time_micropython.py
, play.py
,
__init__.py`
. Optionally also copy one of the example as main.py
to the
root of the filesystem. The overall structure is:
/
├─ main.py
└─ jled
├─ __init__.[m]py
├─ hal_pwm_micropython.[m]py
├─ hal_time_micropython.[m]py
├─ jled.[m]py
├─ jled_sequence.[m]py
└─ play.[m]py
To reduce memory consumption, Python source files can be compiled to binary
mpy
format using the mpy-cross
tool. For convenience, a script to compile and copy jled to a connected device
is provided here (see scripts/install_mp.sh
).
Documentation¶
API documentation for this library can be found on here.
Rebuild the documentation with sphinx-build -E -W -b html . _build/html
in the docs
directory. Run pip install ".[optional]"
before to install
build-time dependency Sphinx
Tests¶
Unit tests (using https://docs.pytest.org) are provided, run the tests with:
$ pip install ".[optional]"
$ pytest
To run the pre-commit-hook
locally, run pre-commit run --all-files
Table of Contents¶
API Reference
- jled
JLed
JLed.blink()
JLed.breathe()
JLed.candle()
JLed.deinit()
JLed.delay_after()
JLed.delay_before()
JLed.fade()
JLed.fade_off()
JLed.fade_on()
JLed.forever()
JLed.is_forever
JLed.is_running
JLed.low_active()
JLed.max_brightness()
JLed.min_brightness()
JLed.off()
JLed.on()
JLed.repeat()
JLed.reset()
JLed.set()
JLed.stop()
JLed.update()
JLed.user_func()
JLedSequence
play()
Other Links