woox 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 17c9cdba29244d47abb7332e08eeb06f001683195407f00e943035a66fbc3e60
+  data.tar.gz: 165c578c0f8883a141bf406cb43d44c67bb3509505dcb98d9e2aabd2f001a784
+SHA512:
+  metadata.gz: 65889379e745a0732c13c621ac17c93e87a68ae7a59ddd443d703b0590ae9705171cb247d84e5fa01f69a72f05d7cbe3edc90326226a950dc0a9b9168a924cdb
+  data.tar.gz: 6b7a4b98fe2867ce99c66783a4b76915d3a56e1de585283f459a97576f21cdc855e7b08674eb8427843e6bc63a29b19d213cef95f345e89c1d4608528ade21f0

data/README.md

@@ -0,0 +1,52 @@
+# Woox
+
+A low-overhead, highly optimized local area network (LAN) library for communicating directly with Woox Smart Home hardware (Plugs, Bulbs, and Strips) using Tuya v3.3 socket engines. Carefully structured to enforce zero-object-allocation cipher cycles, maximizing execution performance on lower-end embedded microprocessors.
+
+## 🤝 Project Origin & Credits
+This library was authored by Jan Svoboda (`escpos`) in collaboration with an interactive physical hardware logging sandbox loop and a Google AI assistant. This engineering process isolated and resolved the strict 16-byte cryptographic resetting quirks of the Tuya protocol.
+
+## 🔑 How to Retrieve Your Device ID and Local Key
+
+### Method A: The QR Code Script Approach (Easiest / No Developer Account)
+You can completely skip creating cloud developer projects by using public reverse-engineered client tools:
+1. Run the official interactive reverse-extraction terminal utility:
+   ```bash
+   npx @tuyapi/cli wizard
+   ```
+2. Enter the standard application User ID code from your mobile **Smart Life** or **Tuya Smart** application profile.
+3. Scan the terminal's generated QR code with your mobile app's scanner. It will immediately dump every connected hardware `Device ID` and `Local Key` string.
+
+### Method B: The Tuya Cloud Explorer Approach (Official Manual Route)
+1. Register a trial workspace on the [Tuya Developer Portal](https://tuya.com).
+2. Navigate to **Cloud -> Link Tuya App** and scan the link vector with your mobile app.
+3. Head to **Cloud -> API Explorer -> Smart Home Device System -> Device Management -> Query Device Details**.
+4. Provide your hardware tracking strings to retrieve your permanent, matching 16-character `local_key`.
+
+## 💻 Installation
+Add this line to your project's `Gemfile`:
+```ruby
+gem 'woox'
+```
+
+And then execute:
+```bash
+\$ bundle install
+```
+
+## 🛠 Command Line Interface (CLI) Use
+Once installed, use the global shell hook to toggle state values or parse metrics straight from your terminal terminal:
+
+```bash
+# General Syntax: woox <plug|bulb> <ip> <device_id> <local_key> <action> [value]
+
+# Controlling a Smart Plug:
+\$ woox plug 192.168.1.50 <device_id> <local_key> on
+\$ woox plug 192.168.1.50 <device_id> <local_key> status
+
+# Controlling a Smart Bulb/LED Strip:
+\$ woox bulb 192.168.1.60 <device_id> <local_key> brightness 300
+\$ woox bulb 192.168.1.60 <device_id> <local_key> color green
+```
+
+## 🔴 Comprehensive Programming Examples
+For an exhaustive, runnable breakdown of all available capabilities (including dimming loops and sequential multi-DP unbundled tracking controls), see the `examples/all_use_cases.rb` script inside the repository directory.

data/bin/woox

@@ -0,0 +1,247 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Robust path interception: pulls from local lib tree if testing locally
+local_lib = File.expand_path("../lib", __dir__)
+if File.directory?(local_lib)
+  $LOAD_PATH.unshift(local_lib)
+end
+
+begin
+  require "woox"
+rescue LoadError => e
+  puts "Error: Cannot load the Woox library module framework."
+  puts e.message
+  exit 1
+end
+
+require "io/console"
+require "json"
+
+# FIXED: Re-engineered using string definitions to prevent markdown rendering bugs from stripping the array values
+COLOR_PRESETS = {
+  "red"     => "255,0,0".split(",").map(&:to_i),
+  "green"   => "0,255,0".split(",").map(&:to_i),
+  "blue"    => "0,0,255".split(",").map(&:to_i),
+  "yellow"  => "255,255,0".split(",").map(&:to_i),
+  "magenta" => "255,0,255".split(",").map(&:to_i),
+  "cyan"    => "0,255,255".split(",").map(&:to_i),
+  "orange"  => "255,165,0".split(",").map(&:to_i),
+  "purple"  => "128,0,128".split(",").map(&:to_i),
+  "pink"    => "255,192,203".split(",").map(&:to_i),
+  "white"   => "255,255,255".split(",").map(&:to_i)
+}
+
+# Helper method to transform standard RGB representations into Tuya v3.3 12-character HHHHSSSSVVVV profiles
+def convert_rgb_to_tuya_hex(r, g, b, targeted_brightness = nil)
+  r_n = r / 255.0
+  g_n = g / 255.0
+  b_n = b / 255.0
+
+  max_val = [r_n, g_n, b_n].max
+  min_val = [r_n, g_n, b_n].min
+  delta   = max_val - min_val
+
+  # Calculate Hue (Scaled 0-360)
+  h = 0
+  if delta > 0
+    if max_val == r_n
+      h = (60 * ((g_n - b_n) / delta) + 360) % 360
+    elsif max_val == g_n
+      h = (60 * ((b_n - r_n) / delta) + 120) % 360
+    elsif max_val == b_n
+      h = (60 * ((r_n - g_n) / delta) + 240) % 360
+    end
+  end
+
+  # Calculate Saturation (Scaled 0-1000)
+  s = max_val == 0 ? 0 : (delta / max_val) * 1000
+
+  # If a specific brightness level is provided, use that instead of maximizing to 1000 based on RGB layout
+  v = targeted_brightness ? targeted_brightness : (max_val * 1000)
+
+  # Convert safely to hex strings padded precisely to 4 characters
+  sprintf("%04x%04x%04x", h.round, s.round, v.round)
+end
+
+# Utility to break down flexible input formats (presets, comma structures, or hex values) into raw RGB values
+def parse_color_input(input)
+  cleaned = input.to_s.strip.downcase
+  
+  if COLOR_PRESETS.has_key?(cleaned)
+    return COLOR_PRESETS[cleaned]
+  end
+
+  if cleaned.include?(",")
+    parts = cleaned.split(",").map { |p| p.to_i }
+    return parts if parts.length == 3
+  end
+
+  hex_match = cleaned.gsub("#", "")
+  if hex_match.length == 6 && hex_match =~ /\A[0-9a-f]{6}\z/
+    r = hex_match[0..1].to_i(16)
+    g = hex_match[2..3].to_i(16)
+    b = hex_match[4..5].to_i(16)
+    return [r, g, b]
+  end
+
+  nil
+end
+
+# Enforce a strict 16-byte length boundary safety check for cryptographic keys
+def sanitize_key(raw_key)
+  cleaned = raw_key.to_s.strip
+  if cleaned.bytesize > 16
+    cleaned[0...16]
+  elsif cleaned.bytesize < 16
+    cleaned.ljust(16, "\x00")
+  else
+    cleaned
+  end
+end
+
+# Executed when running the interactive CLI interface
+def run_interactive_menu(device, type)
+  loop do
+    puts "\n--- Woox Interactive Controller (#{(type == 'bulb' ? 'Smart Bulb' : 'Smart Plug')}) ---"
+    puts "  Power Relay ON"
+    puts "  Power Relay OFF"
+    puts "  [s] Query Telemetry Status Matrix"
+    if type == "bulb"
+      puts "  [b] Set White Brightness Level (10-1000)"
+      puts "  [c] Modify Chromatic RGB Color Space"
+    end
+    puts "  [q] Quit CLI Interface"
+    print "Select action: "
+    choice = IO.console.gets.strip.downcase
+
+    case choice
+    when "1", "on"
+      puts device.turn_on ? "✅ Success: Device turned ON" : "❌ Error: Command failed"
+    when "2", "off"
+      puts device.turn_off ? "✅ Success: Device turned OFF" : "❌ Error: Command failed"
+    when "s", "status"
+      status = device.get_status
+      if status
+        puts "✅ Current Data Points (dps): #{status['dps']}"
+      else
+        puts "❌ Error: Failed to retrieve status payload."
+      end
+    when "b", "brightness"
+      if type == "bulb"
+        print "Enter brightness level (10-1000): "
+        val = IO.console.gets.strip.to_i
+        puts device.set_brightness(val) ? "✅ Brightness adjusted" : "❌ Command failed"
+      end
+    when "c", "color"
+      if type == "bulb"
+        print "Enter color (e.g., 'red', 'ff0000', or '0,255,0'): "
+        input = IO.console.gets.strip
+        rgb = parse_color_input(input)
+        if rgb
+          # Read the current status to preserve the active brightness level
+          status = device.get_status
+          active_brightness = nil
+          
+          if status && status["dps"]
+            if status["dps"]["21"] == "colour" && status["dps"]["24"]
+              # Extract the last 4 hex characters (VVVV) from the existing color code
+              active_brightness = status["dps"]["24"][-4..-1].to_i(16)
+            elsif status["dps"]["22"]
+              # Fallback to white mode brightness if switching from white to color
+              active_brightness = status["dps"]["22"].to_i
+            end
+          end
+
+          tuya_hex = convert_rgb_to_tuya_hex(rgb[0], rgb[1], rgb[2], active_brightness)
+          puts device.set_dps("21" => "colour", "24" => tuya_hex) ? "✅ Color shifted to RGB #{rgb.inspect}" : "❌ Command failed"
+        else
+          puts "❌ Error: Unknown color pattern entry."
+        end
+      end
+    when "q", "quit"
+      puts "Exiting script runner."
+      break
+    else
+      puts "❌ Error: Invalid selection menu choice."
+    end
+  end
+end
+
+# ==============================================================================
+# MAIN ROUTING BLOCK
+# ==============================================================================
+
+if ARGV.empty? || ARGV == ["-i"] || ARGV == ["--interactive"]
+  puts "Woox Local Engine Configuration Setup Wizard"
+  puts "============================================="
+  print "Device Target Type (plug/bulb): "; type = IO.console.gets.strip.downcase
+  print "Device LAN Network IP Address : "; ip = IO.console.gets.strip
+  print "Alphanumeric Hardware Device ID: "; device_id = IO.console.gets.strip
+  print "Permanent 16-Character Key    : "; raw_key = IO.console.gets.strip
+
+  key = sanitize_key(raw_key)
+  device = (type == "bulb") ? Woox::LocalBulb.new(ip, device_id, key) : Woox::LocalPlug.new(ip, device_id, key)
+  run_interactive_menu(device, type)
+  exit 0
+end
+
+if ARGV.length < 5
+  puts "Usage (Automation Mode): woox <plug|bulb> <ip> <device_id> <local_key> <action> [value]"
+  puts "Usage (Interactive Mode): woox --interactive"
+  exit 1
+end
+
+type, ip, device_id, local_key, action, value = ARGV[0..5]
+key = sanitize_key(local_key)
+device = (type == "bulb") ? Woox::LocalBulb.new(ip, device_id, key) : Woox::LocalPlug.new(ip, device_id, key)
+
+case action.to_s.downcase
+when "1", "on"
+  exit(device.turn_on ? 0 : 1)
+when "2", "off"
+  exit(device.turn_off ? 0 : 1)
+when "s", "status"
+  status = device.get_status
+  if status
+    puts status["dps"].to_json
+    exit 0
+  else
+    puts "Error"
+    exit 1
+  end
+when "brightness", "bright"
+  if type == "bulb"
+    exit(device.set_brightness(value.to_i) ? 0 : 1)
+  else
+    puts "Error: Brightness parameter adjustments are only supported on bulb hardware profiles."
+    exit 1
+  end
+when "color", "colour"
+  if type == "bulb"
+    rgb = parse_color_input(value)
+    if rgb
+      status = device.get_status
+      active_brightness = nil
+      if status && status["dps"]
+        if status["dps"]["21"] == "colour" && status["dps"]["24"]
+          active_brightness = status["dps"]["24"][-4..-1].to_i(16)
+        elsif status["dps"]["22"]
+          active_brightness = status["dps"]["22"].to_i
+        end
+      end
+
+      tuya_hex = convert_rgb_to_tuya_hex(rgb[0], rgb[1], rgb[2], active_brightness)
+      exit(device.set_dps("21" => "colour", "24" => tuya_hex) ? 0 : 1)
+    else
+      puts "Error: Unknown color matrix format."
+      exit 1
+    end
+  else
+    puts "Error: Color parameters are only supported on bulb hardware profiles."
+    exit 1
+  end
+else
+  puts "Unknown action: #{action}"
+  exit 1
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: woox
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jan Svoboda
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-09-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Engineered via an exhaustive human-AI hardware testing session, this
+  gem provides direct local Tuya v3.3 socket communication configurations for Woox
+  smart plugs, avoiding all external cloud routing bottlenecks.
+email:
+- jan@mluv.cz
+executables:
+- woox
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/woox
+homepage: https://github.com/svoboda-jan/woox
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/svoboda-jan/woox
+  source_code_uri: https://github.com/svoboda-jan/woox
+  cooperation_credits: Developed via interactive runtime pair-programming between
+    a human engineer running active physical test benches and a Google AI assistant.
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: A lightweight local network Ruby driver for Woox Smart Home devices.
+test_files: []