Library

CLI

Glow Control Library for Twinkly LEDs

Be sure to check out the book at the project website.

The glow-control-lib crate is a Rust library designed to interface with Twinkly LED devices. It provides a comprehensive set of APIs that facilitate the discovery of devices, manipulation of device modes, control of real-time lighting effects, and more. This library serves as the backbone for the glow-control CLI and can be used to build custom applications that manage Twinkly LED controllers.

This project draws inspiration from the Python libraries xled and xled_plus, and it is intended to be an open-source alternative for the Rust ecosystem.

Features

• Network-based discovery of Twinkly devices
• Easy integration with any app that can pipe output to the CLI
• High-level control interfaces for managing device modes and settings
• Real-time effect control from an external network device
• Custom LED movie uploads
• Utility functions for device authentication and communication

Library Usage

A simple example of how to use the library to set Twinkly devices to a specific mode:

use std::collections::HashSet;
use std::time::Duration;
use glow_control_lib::control_interface::{ControlInterface, DeviceMode};
use glow_control_lib::util::discovery::{DeviceIdentifier, Discovery};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Discover devices with a 5-second timeout
    let devices: HashSet<DeviceIdentifier> = Discovery::find_devices(Duration::from_secs(5)).await?;

    // Iterate over the discovered devices, print their details and set their mode
    for device in devices {
        println!("\n{} Found device {}\n{:?}\n", "=".repeat(30), "=".repeat(30), device);

        let control = ControlInterface::from_device_identifier(device).await?;
        control.set_mode(DeviceMode::Color).await?;
    }

    Ok(())
}

For more examples and detailed API documentation, run cargo doc --open after adding the library to your project.

CLI Usage

To install the CLI application, ensure you have Rust and Cargo installed, then run:

cargo install glow-control

to install from crates-io, or:

cargo install --path .

to install directly from the repository.

Preparing Your Devices

To get started, make sure your lights have been configured on your local network using the official Twinkly app, and that you have used the app to generate a 3D point cloud. This point cloud will be stored on your individual Twinkly devices by the official app, so after initial configuration, you no longer need the app to use glow-control.

Discover Feature

The glow-control CLI provides a discover subcommand that allows you to scan your network for Twinkly devices. You can use this feature to find the IP and MAC addresses of your devices, which are required for other CLI commands.

To use the discover feature, run the following command:

The discovery search time is 5000ms by default. You can adjust it if needed.

glow-control discover

IP Address    Device ID        MAC Address         Device Name   LED Count
-----------   --------------   -----------------   -----------   ---------
10.10.0.42    Twinkly_C54ABC   11:38:aa:c4:aa:55   Living Room   250
10.10.0.37    Twinkly_C5CDEF   bb:e5:7c:dd:bb:57   Kitchen       600

You can also specify the output format using the --output option. Supported formats are:

• plaintext (default)
• json
• yaml

For example, to get the results in JSON format:

glow-control discover --output json

Running the Real-Time Test Colors

To run the real-time test colors, use the real-time-test subcommand under the device-call command. This will display a rotating color pattern on Twinkly device.

glow-control device-call --ip <DEVICE_IP> --mac <DEVICE_MAC> real-time-test

<DEVICE_IP> and <DEVICE_MAC> are the IP and MAC addresses of your Twinkly device, respectively. They must be specified for all device-specific commands.

The real-time test inputs frames directly from the CLI binary. Once you terminate the program, the Twinkly device will eventually timeout and return to its previous state.

Demonstrating External App Integration

Integration with other applications is possible by piping the output of another program to the CLI. For example, to display random, changing colors on a device:

cat /dev/random| cargo run -- device-call --ip 10.10.0.37 --mac bb:e5:7c:dd:bb:57 rt-stdin --format binary --error-mode mod-invalid-address --leds-per-frame 5 --min-frame-duration 100

Other Examples

Set the device mode to 'movie':

glow-control device-call --ip <DEVICE_IP> --mac <DEVICE_MAC> set-mode movie

Show a solid color:

glow-control device-call --ip <DEVICE_IP> --mac <DEVICE_MAC> rt-effect show-color --color Red

License

This library is dual-licensed under the MIT License and the Apache License, Version 2.0, allowing you to choose the license that best fits your project's needs. The full text of the licenses can be found in the LICENSE-MIT and LICENSE-APACHE files.

Disclaimer

This project is not affiliated with, authorized by, endorsed by, or in any way officially connected with Twinkly or its affiliates. The official Twinkly website can be found at https://www.twinkly.com.

Contributions

Contributions are welcome! If you would like to contribute to this library, please feel free to open an issue or create a pull request with your improvements or suggestions.