TuyaIotLights

A Ruby gem for controlling Tuya IoT smart lights with easy color changes and white mode switching through the Tuya Cloud API.

• 🎨 Control smart light colors with simple commands
• 🤍 Switch to white mode easily
• 🌈 Pre-defined color palette with 12 colors
• 🔐 Secure credential management with encrypted storage
• 💎 Clean Ruby API for programmatic use
• 🚀 Command-line interface for quick usage
• ✅ Input validation and error handling
• 🔒 SSL certificate verification and request timeouts

Install the gem:

gem install tuya_iot_lights

Or add to your Gemfile:

gem 'tuya_iot_lights'

1. Sign up at Tuya IoT Platform
2. Create a cloud project
3. Get your Client ID, Client Secret, and Device ID

tuya_light configure

This will prompt you to enter your credentials securely. Note: Credentials are only stored for CLI usage and are saved in ~/.tuya_iot_lights/config.yml with proper file permissions (600 - owner read/write only).

For programmatic usage, credentials are passed directly to the constructor and are never stored to disk.

# Change light to blue
tuya_light blue

# Switch to white mode
tuya_light normal

# List available colors
tuya_light --colors

# Show help
tuya_light --help

The CLI provides a simple interface for controlling your lights:

tuya_light configure        # Set up your API credentials (run once)
tuya_light red              # Change light to red
tuya_light blue             # Change light to blue  
tuya_light normal           # Switch to white mode
tuya_light --colors         # List all available colors
tuya_light --help           # Show help

• red, orange, yellow, green, cyan, blue, purple, magenta
• pink, white, warm_white, cool_white
• normal (switches to white mode)

require 'tuya_iot_lights'

# Initialize controller
controller = TuyaIotLights::SmartLightController.new(
  client_id, 
  secret, 
  device_id
)

# Change color
controller.change_color('blue')

# Switch to white mode
controller.switch_to_white_mode

# Check available colors
TuyaIotLights::ColorPalette.available_colors
# => ["red", "orange", "yellow", ...]

# Get color HSV values
TuyaIotLights::ColorPalette.get_color('blue')
# => {"h"=>240, "s"=>1000, "v"=>1000}

This gem currently supports basic RGB light control only:

• ✅ Color Changes: Set lights to predefined colors (red, blue, green, etc.)
• ✅ White Mode: Switch to work_mode=white for standard white lighting
• ❌ Other Device Types: Only tested with Tuya RGB lights
• ❌ Advanced Features: No support for brightness, effects, scheduling, etc.
• ❌ Multiple Devices: Single device control only

Supported API Calls:

• colour_data_v2 - Change light color using HSV values
• work_mode - Switch between color and white modes

Want to add more features? I welcome pull requests! 🎉

Some ideas for contributions:

• Support for brightness control
• Multiple device management
• Different Tuya device types (switches, sensors, etc.)
• Advanced lighting effects
• Scheduling and automation features
• Support for other Tuya API endpoints

See the Contributing section below to get started.

• CLI Mode: Credentials are stored in ~/.tuya_iot_lights/config.yml with 600 file permissions (owner read/write only)
• Programmatic Mode: Credentials are passed directly to constructors and never stored to disk
• Safe YAML Loading: Uses YAML.safe_load to prevent code execution when reading CLI config

• Input Validation: All inputs are validated before processing
• SSL Verification: All API requests use SSL certificate verification
• Request Timeouts: HTTP requests have 30-second timeouts to prevent hanging
• Hidden Input: Secret credentials are hidden during CLI configuration (when terminal supports it)
• No Hardcoded Secrets: No default or fallback credentials in the codebase

For Ruby applications, you can use the gem programmatically. Note: When using the gem in your code, credentials are passed directly and never stored to disk:

require 'tuya_iot_lights'

# Initialize controller with credentials (not stored anywhere)
controller = TuyaIotLights::SmartLightController.new(
  'your_client_id',    # Pass directly - never stored
  'your_secret',       # Pass directly - never stored  
  'your_device_id'     # Pass directly - never stored
)

# Control the light
controller.change_color('blue')
controller.switch_to_white_mode

# You can also use environment variables for security
controller = TuyaIotLights::SmartLightController.new(
  ENV['TUYA_CLIENT_ID'],
  ENV['TUYA_SECRET'],
  ENV['TUYA_DEVICE_ID']
)

Security Note: The SmartLightController class requires credentials as constructor parameters and does not read from or write to any configuration files. This ensures your credentials remain under your application's control.

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/ksix/tuya_iot_lights! 🚀

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for your new functionality
4. Ensure all tests pass (bundle exec rake test)
5. Update documentation as needed
6. Commit your changes (git commit -am 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

API Extensions:

# Brightness control
controller.set_brightness(75)  # 0-100%

# Multiple devices
controller.add_device('device_id_2')
controller.change_all_colors('red')

# Advanced features
controller.set_effect('rainbow')
controller.schedule_color('blue', at: '20:00')

Device Support:

• Smart switches and plugs
• Temperature/humidity sensors
• Door/window sensors
• Smart curtains/blinds

• lib/tuya_iot_lights/tuya_api_client.rb - Add new API endpoints here
• lib/tuya_iot_lights/smart_light_controller.rb - Add new device control methods
• lib/tuya_iot_lights/cli.rb - Add new CLI commands
• test/ - Add comprehensive tests for new features

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the TuyaIotLights project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.