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 <https://github.com/jandelgado/jled>`_
C++ library.
.. image:: https://cdn.jsdelivr.net/gh/jandelgado/jled-circuitpython@1.0.5/.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:: https://cdn.jsdelivr.net/gh/jandelgado/jled-circuitpython@1.0.5/.images/jled_cheat_sheet.jpg
Installation
=============
On supported GNU/Linux systems like the Raspberry Pi (with `Adafruit-Blinka
<https://pypi.org/project/Adafruit-Blinka/>`_), you can install the lib
locally `from PyPI <https://pypi.org/project/circuitpython-jled/>`_. 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 <https://github.com/adafruit/CircuitPython_Community_Bundle>`_
and can easily installed with `circup <https://pypi.org/project/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
<https://pypi.org/project/mpremote/>`_ 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 <https://pypi.org/project/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
<https://jandelgado.github.io/jled-circuitpython/>`_.
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 <https://www.sphinx-doc.org/>`_
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 <https://docs.astral.sh/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
Raw data
{
"_id": null,
"home_page": null,
"name": "circuitpython-jled",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "adafruit, blinka, circuitpython, micropython, jled",
"author": null,
"author_email": "Jan Delgado <jdelgado@gmx.net>",
"download_url": "https://files.pythonhosted.org/packages/ba/44/c12692939c2952e65618afec0a619caf3d3e8063df29cf48e949e236f61f/circuitpython_jled-1.0.5.tar.gz",
"platform": null,
"description": "Introduction\n============\n\n.. image:: https://github.com/jandelgado/jled-circuitpython/workflows/Build%20CI/badge.svg\n :target: https://github.com/jandelgado/jled-circuitpython/actions\n :alt: Build Status\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code Style: Black\n\n.. image:: https://img.shields.io/badge/-API%20documentation-brightgreen\n :target: https://jandelgado.github.io/jled-circuitpython\n :alt: API Documentation\n\nAn embedded library for Python to control LEDs. It uses a **non-blocking**\napproach and can control LEDs in simple (**on**/**off**) and complex\n(**blinking**, **breathing** and more) ways in a **time-driven** manner.\n\nThis is a pure Python port of my `JLed <https://github.com/jandelgado/jled>`_\nC++ library.\n\n.. image:: https://cdn.jsdelivr.net/gh/jandelgado/jled-circuitpython@1.0.5/.images/jled.gif\n :alt: JLed in action\n\nFeatures\n========\n\n- non-blocking\n- effects: simple on/off, breathe, blink, candle, fade, user-defined\n- supports inverted polarity of LED\n- easy configuration using fluent interface\n- can control groups of LEDs sequentially or in parallel\n- supports CircuitPython and MicroPython\n\nUsage Example\n=============\n\nTest JLed interactively in a CircuitPython REPL:\n\n.. code-block::\n\n Adafruit CircuitPython 7.3.3 on 2022-08-29; Raspberry Pi Pico with rp2040\n >>> import board\n >>> from jled import JLed\n >>> led=JLed(board.LED).breathe(500).delay_after(250).repeat(5)\n >>> while led.update(): pass\n\nThis creates a JLed object connected to the builtin LED (``board.LED``), with a\nbreathe effect that is repeated 5 times. Each iteration is followed by a delay\nof 250 ms, before starting again. By calling ``led.update()`` periodically,\nthe LED gets physically updated. Alternatively ``play(led)`` can be call in the\nREPL as a shortcut. Once finished, call ``led.reset()`` before playing the\neffect again.\n\nCheat Sheet\n===========\n\n.. image:: https://cdn.jsdelivr.net/gh/jandelgado/jled-circuitpython@1.0.5/.images/jled_cheat_sheet.jpg\n\nInstallation\n=============\n\nOn supported GNU/Linux systems like the Raspberry Pi (with `Adafruit-Blinka\n<https://pypi.org/project/Adafruit-Blinka/>`_), you can install the lib\nlocally `from PyPI <https://pypi.org/project/circuitpython-jled/>`_. To\ninstall for current user:\n\n.. code-block:: shell\n\n pip3 install circuitpython-jled\n\nTo install system-wide (this may be required in some cases):\n\n.. code-block:: shell\n\n sudo pip3 install circuitpython-jled\n\nTo install in a virtual environment in your current project:\n\n.. code-block:: shell\n\n mkdir project-name && cd project-name\n python3 -m venv .venv\n source .env/bin/activate\n pip3 install circuitpython-jled\n\nInstalling to a Connected CircuitPython Device with Circup\n----------------------------------------------------------\n\n``JLed`` is available in the `Circuitpython Community Bundle <https://github.com/adafruit/CircuitPython_Community_Bundle>`_\nand can easily installed with `circup <https://pypi.org/project/circup/>`_ by\nrunning::\n\n $ circup install jled\n\nOptionally copy also one of the example as ``code.py`` to the root of the filesystem.\n\nInstalling on a MicroPython device\n----------------------------------\n\nCreate a directory called ``jled`` on the device and `copy\n<https://pypi.org/project/mpremote/>`_ the following files into this directory:\n``jled.py``, ``jled_sequence.py`` ``hal_pwm_micropython.py``,\n``hal_time_micropython.py``, ``play.py``, ``__init__.py```. Optionally also copy\none of the example as ``main.py`` to the root of the filesystem. The overall\nstructure is:\n\n.. code-block::\n\n /\n \u251c\u2500 main.py\n \u2514\u2500 jled\n \u00a0\u00a0 \u251c\u2500 __init__.[m]py\n \u00a0\u00a0 \u251c\u2500 hal_pwm_micropython.[m]py\n \u00a0\u00a0 \u251c\u2500 hal_time_micropython.[m]py\n \u00a0\u00a0 \u251c\u2500 jled.[m]py\n \u00a0\u00a0 \u251c\u2500 jled_sequence.[m]py\n \u00a0\u00a0 \u2514\u2500 play.[m]py\n\nTo reduce memory consumption, Python source files can be compiled to binary\n``mpy`` format using the `mpy-cross <https://pypi.org/project/mpy-cross/>`_\ntool. For convenience, a script to compile and copy jled to a connected device\nis provided here (see ``scripts/install_mp.sh``).\n\nDocumentation\n=============\n\n`API documentation for this library can be found on here\n<https://jandelgado.github.io/jled-circuitpython/>`_.\n\nRebuild the documentation with ``sphinx-build -E -W -b html . _build/html``\nin the ``docs`` directory. Run ``pip install \".[optional]\"`` before to install\nbuild-time dependency `Sphinx <https://www.sphinx-doc.org/>`_\n\nTests\n=====\n\nUnit tests (using https://docs.pytest.org) are provided, run the tests with:\n\n.. code-block::\n\n $ pip install \".[optional]\"\n $ pytest\n\nTo run the ``pre-commit-hook`` locally, run ``pre-commit run --all-files``\n\nTip\n===\n\nInstead of installing the various tools like ``circup``, ``mp-remote``,\n``mpy-cross`` etc. you can easily run the tools using `uv <https://docs.astral.sh/uv/>`_:\n\n- ``uv tool run circup list``, ``uv tool run circup update --all``\n- ``uv tool run mpremote`` to start a REPL on the micro controller\n- ``uv tool run --with pytest-cov pytest`` to run the unit tests\n- ``uv tool run --from sphinx sphinx-build -E -W -b html . build/html`` to build\n the documentation using sphinx (run inside ``docs/``)\n\n\nAuthor & Copyright\n==================\n\nCopyright \u00a9 2022-2023 by Jan Delgado, License: MIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Non-blocking LED controlling library",
"version": "1.0.5",
"project_urls": {
"Homepage": "https://github.com/jandelgado/jled-circuitpython"
},
"split_keywords": [
"adafruit",
" blinka",
" circuitpython",
" micropython",
" jled"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0314f75cdaed3eb2e3d0a847a923250b30246c8b685503f23813153e0eef3468",
"md5": "70be5da52bb17768baaab19208181c37",
"sha256": "a1d23ab435f7b1ff92da257489c0f20763c9becb7d38c39d5579dd6433d0d7fa"
},
"downloads": -1,
"filename": "circuitpython_jled-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70be5da52bb17768baaab19208181c37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16590,
"upload_time": "2025-08-01T17:40:54",
"upload_time_iso_8601": "2025-08-01T17:40:54.103621Z",
"url": "https://files.pythonhosted.org/packages/03/14/f75cdaed3eb2e3d0a847a923250b30246c8b685503f23813153e0eef3468/circuitpython_jled-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ba44c12692939c2952e65618afec0a619caf3d3e8063df29cf48e949e236f61f",
"md5": "7495f83e0412edfcb94a2e647fa2b805",
"sha256": "77135974ef1468a0eac031edb3bed4c33424c45a303a6d985a1d446fd1881cb6"
},
"downloads": -1,
"filename": "circuitpython_jled-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "7495f83e0412edfcb94a2e647fa2b805",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1014046,
"upload_time": "2025-08-01T17:40:55",
"upload_time_iso_8601": "2025-08-01T17:40:55.417339Z",
"url": "https://files.pythonhosted.org/packages/ba/44/c12692939c2952e65618afec0a619caf3d3e8063df29cf48e949e236f61f/circuitpython_jled-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 17:40:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jandelgado",
"github_project": "jled-circuitpython",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "circuitpython-jled"
}
JSON
