TinyTuya Dart #

A Dart/Flutter port of Python TinyTuya - a library to control Tuya WiFi smart devices.

Features #

• ✅ Complete Protocol Support: v3.1, v3.3, v3.4, and v3.5 (including GCM encryption)
• ✅ Device Control: Direct local network communication with Tuya devices
• ✅ Device Discovery: UDP scanner to find devices on your network
• ✅ Cloud API: Full Tuya Cloud API support for device management
• ✅ Device Types: Outlets, Bulbs (RGB/HSV), Covers, and generic devices
• ✅ Python Compatible: Byte-for-byte compatible with Python TinyTuya
• ✅ Well Tested: 56+ tests with Python comparison validation

Installation #

Add to your pubspec.yaml:

dependencies:
  tinytuya: ^0.1.0

Then run:

dart pub get
# or
flutter pub get

Quick Start #

1. Control a Device #

import 'package:tinytuya/tinytuya.dart';

void main() async {
  // Create device instance
  final device = Device(
    devId: 'your_device_id',
    address: '192.168.1.100',
    localKey: 'your_local_key',
    version: 3.3,
  );

  // Connect and get status
  try {
    final status = await device.status();
    print('Device status: $status');

    // Turn on
    await device.turnOn();

    // Set brightness (outlet devices)
    final outlet = OutletDevice(
      devId: 'your_device_id',
      address: '192.168.1.100',
      localKey: 'your_local_key',
    );
    await outlet.setDimmer(percentage: 75);

  } finally {
    device.close();
  }
}

2. Discover Devices #

import 'package:tinytuya/tinytuya.dart';

void main() async {
  print('Scanning for Tuya devices...');

  final devices = await deviceScan(scanTime: 10);

  print('Found ${devices.length} devices:');
  for (final device in devices) {
    print('  ${device.ip} - ${device.gwId} (v${device.version})');
  }
}

3. Use Cloud API #

import 'package:tinytuya/tinytuya.dart';

void main() async {
  // Create cloud client
  final cloud = Cloud(
    apiKey: 'your_api_key',
    apiSecret: 'your_api_secret',
    apiRegion: 'us', // us, eu, cn, in, sg
  );

  // Authenticate
  final success = await cloud.init();
  if (!success) {
    print('Authentication failed: ${cloud.error}');
    return;
  }

  // Get all devices
  final devices = await cloud.getDevices();
  for (final device in devices) {
    print('${device['name']}: ${device['id']}');
    print('  Local Key: ${device['local_key']}');
  }

  // Get device status
  final status = await cloud.getStatus('device_id');
  print('Status: ${status?['result']}');
}

Device Types #

Generic Device #

All devices support these methods:

final device = Device(
  devId: 'device_id',
  address: '192.168.1.100',
  localKey: 'local_key',
  version: 3.3,
);

// Control methods
await device.turnOn(switch: 1);
await device.turnOff(switch: 2);
await device.setValue(index: 1, value: 100);
await device.setTimer(numSecs: 3600);

// Query methods
final status = await device.status();
final dpsValues = await device.detectAvailableDps();

// Low-level methods
final payload = device.generatePayload(command: dpQuery);
await device.send(payload);
final response = await device.receive();

OutletDevice (Smart Plugs) #

final outlet = OutletDevice(
  devId: 'device_id',
  address: '192.168.1.100',
  localKey: 'local_key',
);

// Set dimmer/brightness
await outlet.setDimmer(percentage: 75);  // 0-100%

BulbDevice (Smart Bulbs) #

final bulb = BulbDevice(
  devId: 'device_id',
  address: '192.168.1.100',
  localKey: 'local_key',
);

// Auto-detect bulb type (A, B, or C)
bulb.detectBulb();

// Color control
await bulb.setColour(255, 0, 0);  // Red
await bulb.setHsv(0.5, 1.0, 1.0);  // HSV

// White control
await bulb.setWhite(brightness: 255, colourTemp: 128);
await bulb.setWhitePercentage(brightness: 100, colourTemp: 50);

// Brightness
await bulb.setBrightness(200);  // 0-255
await bulb.setBrightnessPercentage(80);  // 0-100%

// Color temperature
await bulb.setColourTemp(150);  // Raw value
await bulb.setColourTempPercentage(60);  // 0-100%

// Modes and scenes
await bulb.setMode('colour');  // white, colour, scene, music
await bulb.setScene(3);  // 1=nature, 3=rave, 4=rainbow

// Query color state
final rgb = bulb.colourRgb();  // [r, g, b]
final hsv = bulb.colourHsv();  // [h, s, v]
final brightness = bulb.brightness();
final temp = bulb.colourTemp();

CoverDevice (Blinds/Curtains) #

final cover = CoverDevice(
  devId: 'device_id',
  address: '192.168.1.100',
  localKey: 'local_key',
);

await cover.openCover();
await cover.closeCover();
await cover.stopCover();

Scanner #

Discover Tuya devices on your local network:

// Scan for 10 seconds (default)
final devices = await deviceScan();

// Custom scan time
final devices = await deviceScan(scanTime: 20);

// Verbose output
final devices = await deviceScan(verbose: true);

// Each device contains:
print(device.ip);           // IP address
print(device.gwId);         // Gateway ID (device ID)
print(device.version);      // Protocol version
print(device.productKey);   // Product key
print(device.rawData);      // Full JSON data

The scanner listens on multiple UDP ports (6666, 6667, 7000) and decrypts UDP broadcast packets from all protocol versions (v3.1-v3.5).

Cloud API #

The Cloud API provides access to the Tuya IoT Platform for device management and control:

final cloud = Cloud(
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret',
  apiRegion: 'us',  // or 'eu', 'cn', 'in', 'sg'
);

// Initialize (get access token)
await cloud.init();

// Get all devices with local keys
final devices = await cloud.getDevices();

// Get device status
final status = await cloud.getStatus('device_id');

// Send command
await cloud.sendCommand('device_id', {
  'commands': [
    {'code': 'switch_1', 'value': true}
  ]
});

// Get device specifications
final specs = await cloud.getDps('device_id');
final functions = await cloud.getFunctions('device_id');
final properties = await cloud.getProperties('device_id');

// Generic cloud request
final response = await cloud.cloudRequest(
  '/v1.0/devices/device_id/logs',
  action: 'GET',
);

Getting Cloud Credentials #

1. Sign up at Tuya IoT Platform
2. Create a Cloud Project
3. Link your devices to the project
4. Get your API Key and Secret from the project overview

Configuration #

Finding Device Parameters #

You need three pieces of information to control a device:

1. Device ID (devId): Found in the Tuya/Smart Life app
2. Local Key: Obtained via Cloud API or tinytuya wizard
3. IP Address: Use the scanner or check your router

Protocol Versions #

• v3.1: Older devices, basic encryption
• v3.3: Most common, improved security
• v3.4: Additional HMAC validation
• v3.5: Latest, uses AES-GCM encryption

The library automatically handles all protocol versions.

Socket Persistence #

The persist parameter controls socket connection behavior:

// persist=false (default) - Socket closes after each operation
// Matches Python TinyTuya's socketPersistent=False
final device = Device(
  deviceId: 'your_device_id',
  address: '192.168.1.100',
  localKey: 'your_local_key',
  version: 3.3,
  persist: false,  // Default - socket closes after each operation
);

// persist=true - Socket stays open between operations
// Better for frequent operations, but connection may timeout after ~1 minute idle
final devicePersistent = Device(
  deviceId: 'your_device_id',
  address: '192.168.1.100',
  localKey: 'your_local_key',
  version: 3.3,
  persist: true,  // Keep socket open
);

Recommendations:

• Use persist=false (default) for reliability - socket closes/reopens for each operation
• Use persist=true for performance when making many rapid consecutive operations
• The library automatically handles session timeout and reconnection in both modes

Examples #

See the example/ directory for complete examples:

• device_control_example.dart - Basic device control
• bulb_example.dart - Smart bulb control
• scanner_example.dart - Device discovery
• cloud_example.dart - Cloud API usage

Testing #

The library includes comprehensive tests with Python comparison validation:

# Run all tests
dart test

# Run specific test suite
dart test test/bulb_color_conversion_test.dart

# Run scanner comparison (requires devices on network)
./example/compare_scanners.sh

Tests include:

• AES encryption (ECB and GCM)
• Message packing/unpacking
• Payload generation
• Device helper methods
• Bulb color conversion
• Cloud API signatures
• Scanner functionality

All tests compare output byte-for-byte with Python TinyTuya to ensure compatibility.

Troubleshooting #

Device Connection Issues #

Problem: Cannot connect to device

Solutions:

• Verify device is on same network
• Check firewall settings
• Ensure correct protocol version
• Verify local key is correct

Problem: "Invalid JSON" errors

Solutions:

• Try different protocol versions (3.1, 3.3, 3.4, 3.5)
• Some devices require protocol auto-detection

Cloud API Issues #

Problem: Authentication fails

Solutions:

• Verify API key and secret
• Check API region matches your account
• Ensure devices are linked to your cloud project

Problem: "Device not found"

Solutions:

• Link device to cloud project in Tuya IoT Platform
• Wait a few minutes after linking for propagation

Comparison with Python TinyTuya #

This Dart port maintains full compatibility with Python TinyTuya:

All cryptographic operations and message formats are validated against Python TinyTuya to ensure interoperability.

Why Not PointyCastle? #

This port uses the cryptography package instead of PointyCastle because:

• PointyCastle has known issues with GCM counter mode
• IV/nonce and tag size handling problems in cross-language scenarios
• The cryptography package provides proper AES-GCM implementation
• Better cross-platform support and performance

Contributing #

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: dart test
5. Submit a pull request

Credits #

This is a port of Python TinyTuya by Jason Cox.

Original Python TinyTuya credits:

• TuyaAPI by codetheweb and blackrozes - Protocol reverse engineering
• PyTuya by clach04 - Original Python implementation
• LocalTuya by rospogrigio - Device ID support improvements

License #

MIT License - see LICENSE file for details.

Resources #

• Python TinyTuya
• Tuya IoT Platform
• Tuya Developer Documentation
• Getting Local Keys Guide