DOCSEARCHbyAlgolia
Submit Docs

XLED

repository·develop·Indexed 42 days ago

https://github.com/scrool/xled

An unofficial Python library and CLI tool for local control of Twinkly smart decoration LED lights, bypassing manufacturer servers. Officially supported on Linux (Fedora, Ubuntu) and compatible with Python 2.7 and 3.7 through 3.11. Features include device discovery, power and mode management, timer scheduling, movie uploads, and firmware updates.

Tokens
2.1K
Snippets
11
Records
15
Agent score
54%

What's inside XLED

  1. Use the XLED CLI to control devices

    develop

    The XLED CLI provides a high-level interface to query and control Twinkly smart decoration LED lights.

    Key Behaviors:

    • Statelessness: The tool does not maintain a configuration file. It performs device discovery before every operation.
    • Device Selection: By default, the CLI controls the first device that responds during discovery. You can specify a particular device to control instead of using the default.
    • Discovery: Every command triggers a discovery process to find available devices on the network.

  2. Check operating system compatibility for XLED

    develop

    XLED is primarily designed for Linux. Both the Command Line Interface (CLI) and the Python library are officially supported only on Linux platforms.

    • Recommended distributions: Fedora (where code is most frequently tested) and Ubuntu (used in CI).
    • Other platforms: While the library might function on other operating systems where Python is available, there is no guarantee of stability or support, and no platform-specific compatibility code will be added for non-Linux systems.

  3. Install XLED

    develop

    XLED is supported on Linux (primarily Fedora). Follow these steps to install the library and CLI tool:

    1. Install pip and wheel: Ensure you have python3-pip and python3-wheel installed.
    2. Create a virtual environment (recommended): Create and activate a dedicated environment to avoid dependency conflicts.
    3. Install via PyPI: Use pip to install or upgrade the xled package.

    If you use a virtual environment, remember to activate it before using the xled command or importing the library.

    # 1. Install dependencies (Fedora example)
$ sudo dnf install python3-pip python3-wheel

# 2. Create and activate virtual environment
$ mkdir -p ~/.virtualenvs
$ python3 -m venv ~/.virtualenvs/xled
$ source ~/.virtualenvs/xled/bin/activate

# 3. Install xled
$ python3 -m pip install --upgrade xled

  5. Use the XLED Python library

    develop

    You can control Twinkly devices programmatically using the xled Python library. The workflow involves discovering a device on the network and then using a ControlInterface to interact with it.

    1. Discover devices: Use xled.discover.discover() to find available Twinkly hardware.
    2. Initialize control: Create a xled.ControlInterface using the discovered device's ip_address and hw_address.
    3. Control the device: Use methods like set_mode(), get_mode(), and get_device_info() to manipulate settings and retrieve hardware information.
    import xled

# Discover a device
discovered_device = xled.discover.discover()
print(f"Device ID: {discovered_device.id}")

# Initialize the control interface
control = xled.ControlInterface(discovered_device.ip_address, discovered_device.hw_address)

# Set the device mode (e.g., 'movie')
control.set_mode('movie')

# Get current mode
current_mode = control.get_mode()['mode']

# Get device information
device_info = control.get_device_info()
print(f"Number of LEDs: {device_info['number_of_led']}")

  6. Use global CLI options to target a device

    develop

    When running any xled command, you must specify which device to operate on using either --name or --hostname. These options are mutually exclusive.

    • --name DEVICE_NAME: Targets a device by its assigned name.
    • --hostname ADDRESS: Targets a device by its network address (IP or hostname).

    Example usage:

    xled --name "MyLights" on
xled --hostname 192.168.1.50 off
    xled --name DEVICE_NAME <command>
xled --hostname ADDRESS <command>

  7. Check supported Python versions for XLED

    develop

    XLED (both the CLI and the library) is written in Python. The project supports the following versions:

    Python 2

    • 2.7: Supported as long as underlying dependencies remain available and compatible with Python 3.

    Python 3

    • 3.7
    • 3.8
    • 3.9
    • 3.10
    • 3.11

    Support for Python 3 follows the official Python lifecycle. As upstream Python versions reach end-of-life, support for those versions in XLED will gradually fade.

  9. Use the XLED CLI

    develop

    The XLED CLI provides a simple way to control your lights from the terminal.

    To turn on your lights, run the xled on command. The tool will automatically search for available devices on your network and attempt to activate them.

    For a full list of available commands and options, use the --help flag.

    # Turn on the discovered Twinkly device
$ xled on

# See all available commands
$ xled --help

  10. Configure CLI verbosity levels

    develop

    You can control the logging output for different modules of the xled tool using specific verbosity flags. Supported levels for all flags are CRITICAL, ERROR, WARNING, INFO, or DEBUG.

    Available verbosity flags:

    • --verbosity-cli: Sets verbosity of the main CLI.
    • --verbosity-discover: Sets verbosity of the discovery module.
    • --verbosity-control: Sets verbosity of the control module.
    • --verbosity-auth: Sets verbosity of the authentication module.
    --verbosity-cli
--verbosity-discover
--verbosity-control
--verbosity-auth

  11. Manage device timers

    develop

    The xled CLI allows you to schedule when the device turns on and off using a timer. Time arguments must be provided in HH:MM format.

    • get-timer: Displays current timer settings, including the current time and scheduled on/off times.
    • set-timer <time-on> <time-off>: Sets the scheduled on and off times. Example: set-timer 18:00 23:30.
    • disable-timer: Disables any active timer.
    xled set-timer 18:00 23:30
xled get-timer
xled disable-timer

  12. Update device firmware

    develop

    To update the device firmware, you must provide two stage files as arguments:

    • update-firmware <stage0_file> <stage1_file>: Performs the firmware update process using the provided binary files.
    xled update-firmware stage0.bin stage1.bin