7 unstable releases (3 breaking)
0.6.0 | Aug 6, 2024 |
---|---|
0.5.0 | Apr 23, 2024 |
0.4.0 | Apr 21, 2024 |
0.3.5 | Apr 12, 2024 |
0.3.3 | Nov 30, 2023 |
#50 in Hardware support
388 downloads per month
140KB
3K
SLoC
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.
Dependencies
~15–28MB
~420K SLoC