Git Product home page Git Product logo

python-wled's Introduction

Python: WLED API Client

GitHub Release Python Versions Project Stage Project Maintenance License

Build Status Code Coverage Quality Gate Status Open in Dev Containers

Sponsor Frenck via GitHub Sponsors

Support Frenck on Patreon

Asynchronous Python client for WLED.

About

This package allows you to control and monitor an WLED device programmatically. It is mainly created to allow third-party programs to automate the behavior of WLED.

Installation

pip install wled

Usage

import asyncio

from wled import WLED


async def main() -> None:
    """Show example on controlling your WLED device."""
    async with WLED("wled-frenck.local") as led:
        device = await led.update()
        print(device.info.version)

        # Turn strip on, full brightness
        await led.master(on=True, brightness=255)


if __name__ == "__main__":
    asyncio.run(main())

Changelog & Releases

This repository keeps a change log using GitHub's releases functionality.

Releases are based on Semantic Versioning, and use the format of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented based on the following:

  • MAJOR: Incompatible or major changes.
  • MINOR: Backwards-compatible new features and enhancements.
  • PATCH: Backwards-compatible bugfixes and package updates.

Contributing

This is an active open-source project. We are always open to people who want to use the code or contribute to it.

We've set up a separate document for our contribution guidelines.

Thank you for being involved! 😍

Setting up development environment

The easiest way to start, is by opening a CodeSpace here on GitHub, or by using the Dev Container feature of Visual Studio Code.

Open in Dev Containers

This Python project is fully managed using the Poetry dependency manager. But also relies on the use of NodeJS for certain checks during development.

You need at least:

  • Python 3.11+
  • Poetry
  • NodeJS 20+ (including NPM)

To install all packages, including all development requirements:

npm install
poetry install

As this repository uses the pre-commit framework, all changes are linted and tested with each commit. You can run all checks and tests manually, using the following command:

poetry run pre-commit run --all-files

To run just the Python tests:

poetry run pytest

Authors & contributors

The original setup of this repository is by Franck Nijhof.

For a full list of all authors and contributors, check the contributor's page.

License

MIT License

Copyright (c) 2019-2024 Franck Nijhof

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

python-wled's People

Contributors

a-baturin avatar basj93 avatar deepsourcebot avatar dependabot-preview[bot] avatar dependabot[bot] avatar drinfernoo avatar frenck avatar renovate[bot] avatar sinclairpaul avatar thefork avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

python-wled's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

  • ⬆️ Update dependency node to v20.13.1
  • ⬆️ Lock file maintenance

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

Detected dependencies

devcontainer
.devcontainer/devcontainer.json
  • ghcr.io/devcontainers-contrib/features/poetry 2
  • ghcr.io/devcontainers/features/github-cli 1
  • ghcr.io/devcontainers/features/node 1
  • ghcr.io/devcontainers/features/python 1
github-actions
.github/workflows/codeql.yaml
  • actions/checkout v4.1.5
  • github/codeql-action v3.25.4
  • github/codeql-action v3.25.4
.github/workflows/labels.yaml
  • actions/checkout v4.1.5
  • micnncim/action-label-syncer v1.3.0
.github/workflows/linting.yaml
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • actions/setup-node v4.0.2
.github/workflows/lock.yaml
  • dessant/lock-threads v5.0.1
.github/workflows/pr-labels.yaml
  • jesusvasquez333/verify-pr-label-action v1.4.0
.github/workflows/release-drafter.yaml
  • release-drafter/release-drafter v6.0.0
.github/workflows/release.yaml
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • pypa/gh-action-pypi-publish v1.8.14
  • sigstore/gh-action-sigstore-python v2.1.1
.github/workflows/stale.yaml
  • actions/stale v9.0.0
.github/workflows/tests.yaml
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
  • actions/upload-artifact v4.3.3
  • actions/checkout v4.1.5
  • actions/download-artifact v4.1.7
  • actions/setup-python v5.1.0
  • codecov/codecov-action v3.1.6
  • SonarSource/sonarcloud-github-action v2.1.1
.github/workflows/typing.yaml
  • actions/checkout v4.1.5
  • actions/setup-python v5.1.0
npm
package.json
  • prettier 3.2.5
nvm
.nvmrc
  • node 20.12.2
pep621
pyproject.toml
  • poetry-core >=1.0.0
poetry
pyproject.toml
  • aiohttp >=3.0.0
  • awesomeversion >=22.1.0
  • backoff >=2.2.0
  • cachetools >=4.0.0
  • python ^3.11
  • yarl >=1.6.0
  • aresponses 3.0.0
  • codespell 2.2.6
  • covdefaults 2.3.0
  • coverage 7.5.1
  • mypy 1.10.0
  • pre-commit 3.7.0
  • pre-commit-hooks 4.6.0
  • pylint 3.1.0
  • pytest 7.4.4
  • pytest-asyncio 0.23.6
  • pytest-cov 5.0.0
  • ruff 0.4.3
  • safety 3.2.0
  • yamllint 1.35.1

  • Check this box to trigger a request for Renovate to run again on this repository

Support leds.wv to detect if white value is required

As WLED 0.11.1 now supports a json attribute to determine if a white value is required, this could be used to determine if a white value should be sent. When the controller runs in rgbw mode with automatic white value calculation, the leds.wv flag is set to false.

To maintain backwards compatibility we can check for the existence the field, and if it does not exist assume it should be true. This should keep the current behavior for older WLED versions.

It looks like this should not be hard to implement, so I am willing to create a PR with this change if you are willing to accept it.

Need instruction to set device state and control the WLED system...

How do I set the device state?

I would like to use this library to control my WLED device, but cannot find documentation on usage.

Expected behavior

I would like to find the command (likely AWAIT) to set/command it to switch to {device.state.preset.name}, similar to how you have used:
await led.master(on=True, brightness=64)

Actual behavior

All I see in the example is how to read {device.state.preset.name}, please help! Thank you!

WLED latest version fetched on every update

Problem/Motivation

Related to: home-assistant/core#93475
Every time the state gets updated, the update sensor in HA goes unavailable. It looks like this is caused by this library as every time this

async def update(self, *, full_update: bool = False) -> Device: # noqa: PLR0912
function is called, the version is fetched from GitHub.

Expected behavior

After the versions have been fetched, cache and re-use them (unless the full_update parameter is set to True).

Actual behavior

Version gets fetched again.

Steps to reproduce

  • Use the WLED integration in HomeAssistant and toggle a the light switch
  • Watch how the firmware update sensor goes to Unkown

Add support for CCT

Problem/Motivation

WLED 0.13.0 added a new parameter in the API for changing the color temperature of the white color, for lights that support cold and warm whites. It's called "cct". See here https://kno.wled.ge/interfaces/json-api/
It will be nice to have a support for this.

Expected behavior

Providing this ability will allow us to control the temperature of the white color.

Actual behavior

I don't see any way to control the temperature of the white color.

Steps to reproduce

Check out the current API.

Proposed changes

In the segment method of the WLED class, add another "cct" argument. This argument should be translated to the "cct" parameter in the JSON that is sent to the WLED controller.

WLED Integration requires internet connection?

Since yesterday my internet connection isn’t working anymore because failure from the ISP side.
That sucks but HA works locally too for, right?

Well actually I noticed all my WLED interfaces don’t work anymore through the Home Assistant integration.

The error message the integration gives is :Invalid response from API: Timeout occurred while communicating with GitHub for WLED version

The WLED instances are reachable through the local network to their IP addresses and the WLED app with the instances is working fine. When I click on a device in the HA integration I can also click the button ‘Go to device’ which points me to the actual device on my local network.

I’ve deleted one of the lights and tried to re add is but then I get an error that it’s unable to connect, which is strange because I can actually ping the instance from both the HA cli and the server HA is running on. (Proxmox server)

Previously WLED devices did work without an internet connection. When we moved last November we didn’t had an internet connection for a couple of days but through the local network I would still be able to manage my WLED instances.

Nothing changed in my local network except that I don’t have a WAN connection at the moment.

I can’t find any specific WLED errors in the logs either so that ain’t much helpful.

I understand that some API call require an internet connection but I don’t see why the basic functionality of a WLED integration requires an internet connection. Is this a bug or did something change recently or am I overseeing something?

Preset vs Playlist selection

I am sorry, if this does not fit here, but I noticed the following.

In src/wled/wled.py there are two functions async def preset and async def playlist that both POST a request to /json/state with data={"ps": preset} or data={"ps": playlist}, respectively.

If I understand https://kno.wled.ge/interfaces/json-api/ correctly, the "ps" parameter should be used to set the preset, but since 0.11.0 "playlist" can be used to select a playlist. So I think, using data={"ps": playlist} in async def playlist is wrong, but should be something like data={"playlist": playlist}.

I have no idea what that implies about backwards compatibility.

I noticed that with homeassistant, when selecting a playlist through homeassistant's web UI the correct playlist is exececuted on the led strip, but at the same time, the hass UI displayed an error that $nameOfThePlaylist is not a valid preset option.

Test code has no method "light"

I copied the example code to a file, and ran it. It pulled the version, but bailed turning on the WLED module.
using WLED 0.13.0-b5, python 3.10.0

import asyncio

from wled import WLED


async def main():
    """Show example on controlling your WLED device."""
    async with WLED("10.0.0.47") as led:
        device = await led.update()
        print(device.info.version)

        # Turn strip on, full brightness
        await led.light(on=True, brightness=255)


if __name__ == "__main__":
    asyncio.run(main())
PS C:\Users\nicko\OneDrive\Documents\Repos\nellson\nellson> python .\wled-test.py
0.13.0-b5
Traceback (most recent call last):
  File "C:\Users\nicko\OneDrive\Documents\Repos\nellson\nellson\wled-test.py", line 17, in <module>
    asyncio.run(main())
  File "C:\Users\nicko\AppData\Local\Programs\Python\Python310\lib\asyncio\runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "C:\Users\nicko\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 641, in run_until_complete
    return future.result()
  File "C:\Users\nicko\OneDrive\Documents\Repos\nellson\nellson\wled-test.py", line 13, in main
    await led.light(on=True, brightness=255)
AttributeError: 'WLED' object has no attribute 'light'
Exception ignored in: <function _ProactorBasePipeTransport.__del__ at 0x00000214AF0672E0>
Traceback (most recent call last):
  File "C:\Users\nicko\AppData\Local\Programs\Python\Python310\lib\asyncio\proactor_events.py", line 116, in __del__
    self.close()
  File "C:\Users\nicko\AppData\Local\Programs\Python\Python310\lib\asyncio\proactor_events.py", line 108, in close
    self._loop.call_soon(self._call_connection_lost, None)
  File "C:\Users\nicko\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 745, in call_soon
    self._check_closed()
  File "C:\Users\nicko\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 510, in _check_closed
    raise RuntimeError('Event loop is closed')
RuntimeError: Event loop is closed
PS C:\Users\nicko\OneDrive\Documents\Repos\nellson\nellson>

⚪ Missing CCT support

With popular strip chips like FW1906 hitting the market with RGBCCT leds support and with WLED properly supporting CCT channel from version 0.15 we really need CCT support in python-wled as well.

This would allow adding those kind of strip to home assistant as well, because as for now it's not possible to add them (if cct strip is detected the config flow is being stopped) Aircoookie/WLED#3298 (comment) and home-assistant/core#101029 (comment)

This was already asked here: #977

Moreover, a PULL request was already made (I was going to implement basically the same before checking for existing PRs): #1137

It was closed by bot for stale, but please consider merging it to allow me opening a PR to home assistant adding support for CCT strips, thank you.

Add support for upgrading new ESP32 board types

What needs to be done to add upgrade support for the new ESP32 board types, like ESP32-C3? With https://github.com/Aircoookie/WLED/releases/tag/v0.14.0, there's "-S2/-C3/-S3" (initial) support.

Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/components/wled/helpers.py", line 28, in handler
    await func(self, *args, **kwargs)
  File "/usr/src/homeassistant/homeassistant/components/wled/update.py", line 88, in async_install
    await self.coordinator.wled.upgrade(version=version)
  File "/usr/local/lib/python3.11/site-packages/wled/wled.py", line 661, in upgrade
    raise WLEDUpgradeError(msg)
wled.exceptions.WLEDUpgradeError: Upgrade is only supported on ESP01, ESP02, ESP32 and ESP8266 devices

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/components/websocket_api/commands.py", line 226, in handle_call_service
    await hass.services.async_call(
  File "/usr/src/homeassistant/homeassistant/core.py", line 2012, in async_call
    response_data = await coro
                    ^^^^^^^^^^
  File "/usr/src/homeassistant/homeassistant/core.py", line 2049, in _execute_service
    return await target(service_call)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/src/homeassistant/homeassistant/helpers/entity_component.py", line 235, in handle_service
    return await service.entity_service_call(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/src/homeassistant/homeassistant/helpers/service.py", line 876, in entity_service_call
    response_data = await _handle_entity_call(
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/src/homeassistant/homeassistant/helpers/service.py", line 948, in _handle_entity_call
    result = await task
             ^^^^^^^^^^
  File "/usr/src/homeassistant/homeassistant/components/update/__init__.py", line 157, in async_install
    await entity.async_install_with_progress(version, backup)
  File "/usr/src/homeassistant/homeassistant/components/update/__init__.py", line 432, in async_install_with_progress
    await self.async_install(version, backup)
  File "/usr/src/homeassistant/homeassistant/components/wled/helpers.py", line 37, in handler
    raise HomeAssistantError("Invalid response from WLED API") from error
homeassistant.exceptions.HomeAssistantError: Invalid response from WLED API

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.