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 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:

Run the official interactive reverse-extraction terminal utility:
```
npx @tuyapi/cli wizard
```
Enter the standard application User ID code from your mobile Smart Life or Tuya Smart application profile.
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)

Register a trial workspace on the Tuya Developer Portal.
Navigate to Cloud -> Link Tuya App and scan the link vector with your mobile app.
Head to Cloud -> API Explorer -> Smart Home Device System -> Device Management -> Query Device Details.
Provide your hardware tracking strings to retrieve your permanent, matching 16-character local_key.

💻 Installation

Add this line to your project's Gemfile:

gem 'woox'

And then execute:

\$ 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:

# 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.

woox

Development