https://github.com/jandelgado/jled-circuitpython
Non-blocking LED controlling library for CirctuitPython and MicroPython.
https://github.com/jandelgado/jled-circuitpython
circuitpython jled micropython
Last synced: 3 months ago
JSON representation
Non-blocking LED controlling library for CirctuitPython and MicroPython.
- Host: GitHub
- URL: https://github.com/jandelgado/jled-circuitpython
- Owner: jandelgado
- License: mit
- Created: 2022-10-02T19:42:19.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-06-29T20:00:51.000Z (over 2 years ago)
- Last Synced: 2025-02-02T05:31:29.059Z (12 months ago)
- Topics: circuitpython, jled, micropython
- Language: Python
- Homepage: https://jandelgado.github.io/jled-circuitpython
- Size: 5.63 MB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
Introduction
============
.. image:: https://github.com/jandelgado/jled-circuitpython/workflows/Build%20CI/badge.svg
:target: https://github.com/jandelgado/jled-circuitpython/actions
:alt: Build Status
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code Style: Black
.. image:: https://img.shields.io/badge/-API%20documentation-brightgreen
:target: https://jandelgado.github.io/jled-circuitpython
:alt: API Documentation
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.
.. image:: .images/jled.gif
:alt: JLed in action
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:
.. code-block::
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
===========
.. image:: .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:
.. code-block:: shell
pip3 install circuitpython-jled
To install system-wide (this may be required in some cases):
.. code-block:: shell
sudo pip3 install circuitpython-jled
To install in a virtual environment in your current project:
.. code-block:: shell
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:
``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:
.. code-block::
/
├─ 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:
.. code-block::
$ pip install ".[optional]"
$ pytest
To run the ``pre-commit-hook`` locally, run ``pre-commit run --all-files``
Tip
===
Instead of installing the various tools like ``circup``, ``mp-remote``,
``mpy-cross`` etc. you can easily run the tools using `uv `_:
- ``uv tool run circup list``, ``uv tool run circup update --all``
- ``uv tool run mpremote`` to start a REPL on the micro controller
- ``uv tool run --with pytest-cov pytest`` to run the unit tests
- ``uv tool run --from sphinx sphinx-build -E -W -b html . build/html`` to build
the documentation using sphinx (run inside ``docs/``)
Author & Copyright
==================
Copyright © 2022-2023 by Jan Delgado, License: MIT