{"id":22145031,"url":"https://github.com/st235/MicroLED","last_synced_at":"2025-07-26T02:31:01.910Z","repository":{"id":265958166,"uuid":"896586226","full_name":"st235/MicroLED","owner":"st235","description":"MicroLED: A Lightweight Python Library for Animating LED Grids, Strips, and Rings 🎄","archived":false,"fork":false,"pushed_at":"2024-12-04T21:58:11.000Z","size":9035,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T10:41:06.548Z","etag":null,"topics":["led","micropython","python","raspberry-pi","raspberry-pi-pico","rp2040","rp2350"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/st235.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-30T18:57:15.000Z","updated_at":"2025-04-09T00:58:11.000Z","dependencies_parsed_at":"2025-03-27T01:51:55.527Z","dependency_job_id":null,"html_url":"https://github.com/st235/MicroLED","commit_stats":null,"previous_names":["st235/ledanimation","st235/microled"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/st235/MicroLED","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st235%2FMicroLED","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st235%2FMicroLED/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st235%2FMicroLED/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st235%2FMicroLED/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/st235","download_url":"https://codeload.github.com/st235/MicroLED/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st235%2FMicroLED/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267107543,"owners_count":24037276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["led","micropython","python","raspberry-pi","raspberry-pi-pico","rp2040","rp2350"],"created_at":"2024-12-01T22:38:35.202Z","updated_at":"2025-07-26T02:31:01.900Z","avatar_url":"https://github.com/st235.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MicroLed\n\n![Cover](assets/images/micro_led.jpeg)\n\n**MicroLed** is a lightweight and efficient library designed for MicroPython, enabling smooth animations for LED grids, \nstrips, rings, and more. Perfect for makers and developers, it offers easy-to-use APIs tailored for resource-constrained environments 🎄\n\n## Installation\n\nMicrocontrollers don’t come with a package manager, so to use this library, you’ll need to fork it manually.\nHere's an overview of the modules included:\n\n- **animation:** This is the core module of the library — its heart and soul. It provides the basic abstractions you'll likely need,\nthough you might not require the entire module. For example, the **effects** submodule can be selectively included:\n    - **effects:** Contains logic for specific animations. Since you probably won’t need all of them, you can save memory on your microcontroller by copying only\nthe effects you’ll use.\n- **zoo:** A collection of predefined color palettes and effects (basically timing and color configurations).\nWhile not essential, it’s a great source of inspiration for your projects.\n- **example** and **tests**: These aren’t - technically - Python modules at all. \nThey’re included for demonstration purposes, along with **main.py** and **ws2812_led_strip_mapper.py**.\n- You can completely ignore **assets** folder as this is infrastructural files for this repository.\n\n## Minimal working example\n\nBelow is a minimal working example.\n\n```python\n# Initialises hardware.\nstrip = plasma.WS2812(50, 0, 0, plasma2040.DAT, color_order=plasma.COLOR_ORDER_BGR)\nstrip.start()\n\n# Controls the animation.\nplayer = AnimationPlayer()\n\n# Adds animation to play.\nplayer.add_animation(\n    animation=SolidColor(\n        color=CANDLE,\n    ),\n    device_mapper=WS2818ColorStripMapper(\n        strip=strip,\n        mapped_indexes=[i for i in range(50)]\n    ),\n)\n\n# It is necessary to initialise the player prior advancing the animation loop\n# as it sets up the inner animations state, required to work properly.\nplayer.start()\n\nwhile True:\n    # Advances animation cycle one step forward.\n    player.advance_one_step()\n```\n\n## API\n\n### Animation\n\nThe Animation class is the core component for defining the logic behind LED interactions.\n\n![Animation UML](./assets/images/animation_uml.png)\n\nThis is essentially a template class for all animations in the codebase.\nThe Animation class functions as a state machine that updates periodically.\nYou can specify either a single update interval or multiple intervals (with the animation looping over the values)\nusing the `update_intervals_ms` parameter in the constructor.\n\nMoreover, it offers a few useful methods that can be customized:\n- **Optional `_on_start`:** Gives you a chance to initialize your animation.\n- **`_on_update`:** Called each time the animation loop advances, after enough time specified in the `update_intervals_ms` have elapsed.\n\n### Predefined animations\n\nThere are several predefined animations available in the `animation.effects` module:\n\n- **`Blink`**: Alternates between the specified color and a disabled LED pixel.\n- **`ColorCycle`**: Loops through the provided set of colors.\n- **`Fade`**: Alternates between a disabled LED pixel and the specified color, gradually transitioning between the two states using simple linear interpolation.\n- **`GradientCycle`**: Similar to `Fade`, but alternates between the provided colors.\n- **`Progress`**: Fills the device pixel by pixel.\n- **`Snake`**: Moves a snake of a given size along the LED device.\n- **`SolidColor`**: Displays a single color for the entire duration.\n- **`Sparkle`**: Creates a sparkling effect by randomly highlighting one of the device pixels and blending it with the background color.\n\n### Color Context\n\nThe color context acts as your virtual memory for animations.\nEssentially, it’s a multidimensional array that can represent LED devices of any complexity: a 1D strip, a 2D grid, a 3D cube, \nor even more unconventional configurations. It holds pixel values between `start` and `update` operations, \nreflecting the current state of your LED setup before being sent to the physical device for display.\n\n![Color Context UML](./assets/images/color_context_uml.png)\n\nThe context can accept either a single integer or a list of dimensions, representing the addressing structure of your LED device.\n\nHere’s a minimal example:  \n\n```python\n  color_context = ColorContext(dimensions=[5, 2])\n  color_context[[0, 1]] = ColorContextTest.TEST_COLOR_A\n```\n\n\nAdditionally, to ensure determinism when creating animations, `ColorContext` allows its data to be accessed as a contiguous \nin-memory chunk through the `__len__`, `__setitem__`, and `__getitem__` methods.  \n\n\u003e [!NOTE]\n\u003e Take a look at [`color_context_test.py`](./tests/color_context_test.py) for more usage examples.\n\n### LED mapper\n\nThe device mapper serves as an abstraction layer between the animation and the physical device.\nThink of it as a virtual device that can represent an entire LED setup or just a portion of it.\n\n![LED Device Mapper UML](./assets/images/led_device_mapper_uml.png)\n\nTo correctly map your device, simply override the `present` method to display the state of the `ColorContext`.  \n\n\u003e [!NOTE]  \n\u003e That’s right—you can map just a portion of your device!  \n\u003e All you need is an index mapping between the virtual `ColorContext` indices and the real device indices.  \n\u003e Check out [`ws2812_led_strip_mapper.py`](./ws2812_led_strip_mapper.py) for an example of how to implement this mapping.  \n\n### Animation Player\n\n\nThe Animation Player manages all parallel animations,\ndevices (or their portions — remember?), and their current states, represented by `ColorContext`.\n\n![Animation Player UML](./assets/images/animation_player_uml.png)\n\nRather than implementing a `loop` that blocks the thread while the animation is running,\nthe `Player` provides the `advance_one_step` method. This approach offers greater flexibility,\nallowing the animation to be used with various technologies such as simple loops, generators,\nframeworks like `asyncio`, or multithreaded APIs.\n\n## Zoo: collection of predefined colors and effects\n\n### Colors\n\nBelow is a list of all the available predefined colors in the palette.\n\n![Palette](assets/images/palette.png)\n\n### Effects\n\nA predefined effect consists of several components: the animation (i.e., the logic of the effect), colors, and timings.  \n\nAll predefined effects are designed for an entire LED matrix or strip. While they can be played on a portion\nof the device (see [`LED device mapper`](./animation/led_device_mapper.py)),\nthis has not been tested for partial device use.\n\nThe list of effects is:\n\n- POLICE_CAR_1\n- POLICE_CAR_2\n- EMERGENCY_CAR_1\n- FIRE_CAR_1\n- LIGHTNING\n- RAINBOW\n- TV\n- CANDLE\n- BROKEN_BULB\n- PULSE\n- SNOWFLAKES\n- SPARKLES\n\n## A few more photos of the project\n\n| Red Solid Color                            | Blue Solid Color                              |\n|--------------------------------------------|-----------------------------------------------|\n| ![Red Star](./assets/images/red_star.jpeg) | ![Blue Star](./assets/images/blue_star.jpeg)  |\n\n\u003e [!NOTE]\n\u003e See more examples at [`MicroLED` Youtube Playlist](https://www.youtube.com/playlist?list=PLucKuGqiOAE_1GyYPRy1i3J4XSmMSZjE9).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fst235%2FMicroLED","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fst235%2FMicroLED","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fst235%2FMicroLED/lists"}