Tuya Electric Vehicle Status & Safety Skill

Basic Information

• Authentication: Via Header Authorization: Bearer {Api-key}
• Credentials: Read from environment variable TUYA_API_KEY. The base URL is auto-detected from the API key prefix (e.g. sk-AY... → China, sk-EU... → Europe). You can override by setting TUYA_BASE_URL.
• API Reference: See individual files under references/
• Python SDK: See scripts/tuya_api.py, which provides a TuyaAPI class for calling all APIs directly

Environment Variable Configuration

Set the following environment variable before use:

export TUYA_API_KEY="your-tuya-api-key"
# TUYA_BASE_URL is optional — auto-detected from API key prefix

API Key Prefix → Data Center Mapping

How to obtain an API key:

• China Mainland users: Get from https://tuyasmart.com/
• International users: Get from https://tuya.ai/

The skill will not load if the TUYA_API_KEY environment variable is missing.

Usage

Via Python SDK (Recommended)

import sys
sys.path.insert(0, "{baseDir}/scripts")
from tuya_api import TuyaAPI

api = TuyaAPI()

# List all devices, then filter for electric vehicles
devices = api.get_all_devices()

# Get vehicle detail (battery, signal, location, online status)
detail = api.get_device_detail("your_device_id")

# Query weather at vehicle location
weather = api.get_weather(lat="30.27", lon="120.15")

Via Command Line

python3 {baseDir}/scripts/tuya_api.py devices
python3 {baseDir}/scripts/tuya_api.py device_detail <device_id>
python3 {baseDir}/scripts/tuya_api.py weather <lat> <lon>

Feature Overview

Scope

This skill focuses exclusively on read-only monitoring of electric vehicles. It does NOT support:

• Remotely locking/unlocking the vehicle
• Sending control commands to the vehicle
• Device pairing or removal
• Firmware upgrades
• Video/camera operations

If the user requests any of these, inform them that this skill is for status monitoring only and suggest using the Tuya App for control operations.

Core Workflows

Workflow 1: Find the User's Electric Vehicle

When the user asks about their electric vehicle (e.g. "check my e-bike", "how's my scooter doing"):

1. List all devices — Call the "List All Devices" API
2. Filter for electric vehicles — Electric vehicle / e-bike devices typically have category codes like ddc (electric vehicle), cldc (e-bike tracker), or similar mobility-related categories. Match by category or category_name containing keywords related to electric vehicles, motorcycles, scooters, or trackers
3. Handle ambiguity:
   • If only one EV device is found, use it directly
   • If multiple EV devices are found, list them and ask the user to choose
   • If no EV device is found, show all devices and ask the user to identify which one is their vehicle

Workflow 2: Query Vehicle Status

When the user asks about battery, signal, online status, or location (e.g. "what's my e-bike's battery?", "is my scooter online?", "where is my electric vehicle?"):

1. Locate the vehicle — Use Workflow 1 to find the target device and get its device_id
2. Get device detail — Call GET /v1.0/end-user/devices/{device_id}/detail
3. Extract status from properties — The properties field contains the vehicle's real-time state. Common property codes for electric vehicles include:

Since property codes vary across manufacturers, use the Thing Model API (GET /v1.0/end-user/devices/{device_id}/model) to discover the actual property codes and their meanings if the common codes above don't match.

4. Present the status — Summarize the vehicle's status in natural language. For example:

   Your electric vehicle "My E-bike" is currently online.

   • Battery: 78%
   • Signal strength: Good (85)
   • Last reported location: 30.2741°N, 120.1551°E
   • Last update: 2 minutes ago

Workflow 3: Query Weather at Vehicle Location

When the user asks about weather conditions at their vehicle's location (e.g. "what's the weather where my e-bike is parked?", "is it raining at my scooter's location?"):

1. Get vehicle location — Follow Workflow 2 to get the vehicle's latitude and longitude from the device properties

2. Query weather — Call the Weather API with the vehicle's coordinates:

   GET /v1.0/end-user/services/weather/recent?codes=["w.temp","w.humidity","w.condition","w.realFeel","w.windLevel","w.hour.7"]&lat={lat}&lon={lon}
   

3. Present weather info — Translate the response into a user-friendly summary:

   Weather at your vehicle's location (30.27°N, 120.15°E):

   • Temperature: 12°C (feels like 9°C)
   • Humidity: 65%
   • Condition: Partly Cloudy
   • Wind: Level 3

   If the vehicle has no GPS data, ask the user for a city or coordinates to query weather manually.

Workflow 4: Comprehensive Status Check

When the user says something general like "check my e-bike" or "how's my vehicle doing", combine Workflows 2 and 3 to give a full status report:

1. Get the vehicle detail (battery, signal, online status, location)
2. If GPS coordinates are available, also query weather at that location
3. Present everything in one clear summary

API Calling Convention

Request Format

All APIs use the configured Base URL concatenated with the path:

GET {base_url}/v1.0/end-user/devices/all
GET {base_url}/v1.0/end-user/devices/{device_id}/detail
GET {base_url}/v1.0/end-user/devices/{device_id}/model
GET {base_url}/v1.0/end-user/services/weather/recent

Response Format

Success:

{
  "success": true,
  "t": 1710234567890,
  "result": { ... }
}

Error:

{
  "success": false,
  "code": 1108,
  "msg": "uri path invalid"
}

Error Handling

Important Notes

1. Electric vehicle category codes vary by manufacturer — always check category and category_name to identify the right device, and be flexible with fuzzy matching
2. Property codes (like battery_percentage, signal_strength, latitude) are not standardized across all EV products. When in doubt, query the Thing Model to discover the actual codes
3. GPS coordinates in device properties may use different formats (decimal degrees, or scaled integers). Check the Thing Model's typeSpec for the scale field to convert correctly
4. The weather API requires latitude and longitude as strings
5. This skill is read-only — it monitors status but does not send control commands to the vehicle