xlink-iot-agent（xlink 物联网 Agent）

Xlink IoT Agent

Control and query IoT devices and events on the XLink IoT platform via GatewayAppClient with signature-based authentication.

When to Use

✅ Use This Skill When

• Querying device status and statistics on XLink IoT platform
• Monitoring device alerts and events
• Batch querying device attributes (latest values or historical data)
• Remote control of IoT devices (invoking thing model services)
• Filtering device data by project/product

❌ Do Not Use This Skill For

• Other IoT platforms (AWS IoT, Azure IoT, Alibaba Cloud IoT, etc.)
• Direct local device control (not via XLink IoT platform)
• Historical weather data or severe weather alerts (use weather skill)
• Non-IoT related device management tasks

Quick Start

1. Set Environment Variables

export XLINK_BASE_URL="https://api-gw.xlink.cn"
export XLINK_APP_ID="your-app-id"
export XLINK_APP_SECRET="your-app-secret"
export XLINK_API_GROUP="your-group-id"

2. Run Commands

cd /path/to/xlink-iot-agent

# Device overview
python scripts/xlink_api.py overview

# Pending events
python scripts/xlink_api.py event-instances --status 1 --limit 20

# Alert statistics (last 24 hours)
python scripts/xlink_api.py alert-statistics

# Device control
python scripts/xlink_api.py device-control \
  --thing-id 10299402 \
  --service device_attribute_set_service \
  --input '{"PowerSwitch":true}'

Core Commands

Common Query Examples

Device Overview

python scripts/xlink_api.py overview

Output:

==================================================
📊 XLINK Device Overview
==================================================

   📱 Total Devices:    7823
   🟢 Online:           143 (1.8%)
   ✅ Activated:        6756 (86.4%)
   ⚫ Offline:          7680
   ⏸️  Not Activated:   1067

Pending Events

python scripts/xlink_api.py event-instances --status 1 --limit 20

Alert Overview

python scripts/xlink_api.py alert-overview

Device List (with Filtering)

# Filter by project
python scripts/xlink_api.py device-list \
  --query '{"logic":"AND","device":{"project_id":{"$eq":"XJA1JJAJA"}}}' \
  --limit 20

# JSON output
python scripts/xlink_api.py device-list --limit 20 --json

Device Control

# Set attributes
python scripts/xlink_api.py device-control \
  --thing-id 10299402 \
  --service device_attribute_set_service \
  --input '{"ColorTemperature": 8}'

# With command cache (10 minutes)
python scripts/xlink_api.py device-control \
  --thing-id 10299402 \
  --service device_attribute_set_service \
  --input '{"Brightness": 100}' \
  --ttl 600

Control Response Codes:

Python API

import sys
sys.path.insert(0, "scripts")
from xlink_api import XlinkIoTClient

# Initialize (reads from environment variables)
client = XlinkIoTClient()

# Device overview
overview = client.get_device_overview(project_id="ab582")

# Device list
devices = client.get_device_list(limit=50)

# Alert statistics
alerts = client.get_alert_statistics(interval="hour")

# Event instances
events = client.get_event_instances(status=[1], limit=20)

# Device control
result = client.control_device(
    thing_id="10299402",
    service="device_attribute_set_service",
    input_params={"PowerSwitch": True}
)

Detailed Documentation

Complete CLI command reference, parameter descriptions, and API documentation:

• references/cli-reference.md - Complete CLI command reference
• references/api-auth.md - Authentication mechanism and security
• references/api-doc.md - Complete API documentation
• references/response-schema.md - Response format definitions

Error Handling

Best Practices

1. Use pagination - For large datasets, use --offset and --limit
2. Filter early - Apply filters (status, device, time) to reduce data transfer
3. Cache results - Device status changes infrequently; cache for 30-60 seconds
4. Handle rate limits - Implement exponential backoff for 429 errors
5. JSON output for scripting - Use --json for programmatic parsing
6. Debug mode - Use --debug for troubleshooting