xlink-iot-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

```bash
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

```bash
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

| Command | Function | Example |
|------|------|------|
| `overview` | Device overview statistics | `python scripts/xlink_api.py overview` |
| `device-list` | Device list query | `python scripts/xlink_api.py device-list --limit 20` |
| `device-trend` | Device statistics trend | `python scripts/xlink_api.py device-trend --start-time "2026-03-17T00:00" --end-time "2026-03-24T23:59"` |
| `device-history` | Device attribute history snapshots | `python scripts/xlink_api.py device-history --device-ids 300513220,501548135` |
| `device-latest` | Device latest attributes | `python scripts/xlink_api.py device-latest --device-ids 300513220,501548135` |
| `device-control` | Device control | `python scripts/xlink_api.py device-control --thing-id 10299402 --service device_attribute_set_service --input '{"PowerSwitch":true}'` |
| `alert-overview` | Alert overview | `python scripts/xlink_api.py alert-overview` |
| `alert-statistics` | Alert time-series statistics | `python scripts/xlink_api.py alert-statistics --interval hour` |
| `event-instances` | Event instance query | `python scripts/xlink_api.py event-instances --status 1 --limit 20` |

---

## Common Query Examples

### Device Overview

```bash
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

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

### Alert Overview

```bash
python scripts/xlink_api.py alert-overview
```

### Device List (with Filtering)

```bash
# 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

```bash
# 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:**
| Code | Description |
|------|-------------|
| `200` | ✅ Success - device responded |
| `202` | ⏸️ Device offline - command not sent |
| `408` | ⚠️ Connection closed - device sleeping |
| `503` | ❌ Control failed |

---

## Python API

```python
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`](references/cli-reference.md) - Complete CLI command reference
- [`references/api-auth.md`](references/api-auth.md) - Authentication mechanism and security
- [`references/api-doc.md`](references/api-doc.md) - Complete API documentation
- [`references/response-schema.md`](references/response-schema.md) - Response format definitions

---

## Error Handling

| Status | Description | Solution |
|------|------|----------|
| `401 Unauthorized` | Invalid credentials | Check App ID/Secret |
| `403 Forbidden` | Access denied | Verify Group ID and permissions |
| `404 Not Found` | Resource not found | Check endpoint path or resource ID |
| `429 Too Many Requests` | Rate limited | Implement exponential backoff retry |
| `500 Server Error` | Server error | Retry later |

---

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