FeiYang Smart Control API Documentation - ESP32 Smart Home Control System

Yang Yang Programming included in Technical Documentation Smart Hardware

2024-06-01 919 words 5 minutes views

Contents

🔌 The FeiYang Smart Control Cloud Platform offers comprehensive open API capabilities, enabling secure communication with smart gateway devices through standardized HTTPS protocols. This document elaborates on interface protocol specifications, API definitions, and typical application scenarios, helping developers quickly integrate FeiYang smart home solutions.

📋 Interface List

👤 User Interfaces

Interface Name	Request Method	Path	Description
Get Gateway Device List	GET	`/mcp/user/gateway/devices`	Retrieve user’s gateway device list
Device Control	POST	`/mcp/user/device/control`	Control devices to execute specific commands
TTS Service	POST	`/mcp/user/device/tts`	Text-to-speech or audio playback

📝 Interface Detailed Descriptions

1️⃣ Get Gateway Device List

Interface Path: GET /mcp/user/gateway/devices

Request Parameters:

Parameter	Type	Required	Location	Description
auth	String	Yes	Query	Gateway device key

Response Data:

        
        
        
    
{
  "code": 0,
  "message": "Successfully retrieved device response",
  "data": {
    "homelist": [
      {
        "id": "224001002695",
        "name": "My Home",
        "address": "East District",
        "roomlist": [
          {
            "id": "224001002696",
            "name": "Living Room",
            "dids": [
              {
                "did": "1",
                "name": "Living Room Lamp",
                "model": "mi.switch",
                "isOnline": true
              }
            ]
          }
        ]
      }
    ]
  }
}

Error Codes:

0: Successfully retrieved device response
40000: System error/Failed to get device list

2️⃣ Device Control

Interface Path: POST /mcp/user/device/control

Request Body:

        
{
  "auth": "Gateway device key",
  "command": "Control command",
  "silence": false
}

Request Parameters:

Parameter	Type	Required	Description
auth	String	Yes	Gateway device key
command	String	Yes	Control command
silence	Boolean	No	Silent mode, default is false

Response Data:

        
        
        
    
{
  "code": 0,
  "message": "Device control successful",
  "data": {
    "requestId": "app_ios_abc123def456",
    "response": {
      "cmd": "902",
      "status": "success",
      "result": {...}
    },
    "timestamp": 1719834567,
    "cmd": "902"
  }
}

Error Codes:

0: Device control successful
10002: Control command cannot be empty
40000: Device control failed

3️⃣ TTS Service

Interface Path: POST /mcp/user/device/tts

Request Body:

        
        
        
    
{
  "auth": "Gateway device key",
  "text": "Hello XiaoAi",
  "audio_url": "https://oneapi.sooncore.com/ota/tts/audio/test_xiaoai_tts.mp3",
  "volume": 5,
  "silence": false,
  "execute": false
}

Request Parameters:

Parameter	Type	Required	Description
auth	String	Yes	Gateway device key
text	String	No*	Text to convert to speech
audio_url	String	No*	Audio URL
volume	Integer	No	Volume level, default is 5
silence	Boolean	No	Silent mode, default is false
execute	Boolean	No	Execute flag, default is false

*Note: Either text or audio_url must be provided

Response Data:

        
        
        
    
{
  "code": 0,
  "message": "TTS execution successful",
  "data": {
    "requestId": "app_ios_abc123def456",
    "response": {
      "cmd": "902",
      "status": "success",
      "result": {...}
    },
    "timestamp": 1719834567,
    "cmd": "902"
  }
}

Error Codes:

0: TTS execution successful
10002: Text or audio URL cannot both be empty
40000: TTS execution failed
40001: Must provide either text or audio URL

📡 Communication Protocol Description

The FeiYang Smart Control platform uses standard HTTPS protocol for secure communication with smart gateway devices. In the implementation architecture, the system supports two core message types:

Control Messages: Command data sent from the cloud platform to smart gateways
Status Messages: Device status updates sent back from smart gateways to the cloud platform

📝 Note: All communication data uses JSON format, supporting encrypted transmission and comprehensive error handling mechanisms

🧪 Example Code

📋 Multi-language Examples

cURL Examples

        
        
        
    
# Get Device List
curl -X GET "https://oneapi.sooncore.com/weilaiapi/mcp/user/gateway/devices?auth=YOUR_DEVICE_KEY"

# Control Device
curl -X POST "https://oneapi.sooncore.com/weilaiapi/mcp/user/device/control" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "YOUR_DEVICE_KEY",
    "command": "Control command",
    "silence": false
  }'

# TTS Service
curl -X POST "https://oneapi.sooncore.com/weilaiapi/mcp/user/device/tts" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "YOUR_DEVICE_KEY",
    "text": "Hello XiaoAi",
    "audio_url": "https://oneapi.sooncore.com/ota/tts/audio/test_xiaoai_tts.mp3",
    "volume": 5,
    "silence": false,
    "execute": false
  }'

JavaScript (Fetch API)

        
        
        
    
// Get devices example
async function getDevices(authKey) {
  try {
    const response = await fetch(
      `https://oneapi.sooncore.com/weilaiapi/mcp/user/gateway/devices?auth=${authKey}`,
      { method: 'GET' }
    );
    const data = await response.json();
    console.log('Device List:', data);
    return data;
  } catch (error) {
    console.error('Failed to get devices:', error);
  }
}

// Control device example
async function controlDevice(authKey, command) {
  try {
    const response = await fetch(
      'https://oneapi.sooncore.com/weilaiapi/mcp/user/device/control',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          auth: authKey,
          command: command,
          silence: false
        })
      }
    );
    const result = await response.json();
    console.log('Control Result:', result);
    return result;
  } catch (error) {
    console.error('Failed to control device:', error);
  }
}

Python Example

        
        
        
    
import requests

# Set basic parameters
BASE_URL = "https://oneapi.sooncore.com/weilaiapi"
AUTH_KEY = "YOUR_DEVICE_KEY"

# Get device list
def get_devices():
    url = f"{BASE_URL}/mcp/user/gateway/devices"
    params = {"auth": AUTH_KEY}
    
    response = requests.get(url, params=params)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Failed to get devices: {response.status_code}")
        return None

# Control device
def control_device(command):
    url = f"{BASE_URL}/mcp/user/device/control"
    payload = {
        "auth": AUTH_KEY,
        "command": command,
        "silence": False
    }
    
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Failed to control device: {response.status_code}")
        return None

# Use TTS service
def tts_service(text=None, audio_url=None):
    url = f"{BASE_URL}/mcp/user/device/tts"
    payload = {
        "auth": AUTH_KEY,
        "volume": 5,
        "silence": False,
        "execute": False
    }
    
    # Either text or audio_url must be provided
    if text:
        payload["text"] = text
    if audio_url:
        payload["audio_url"] = audio_url
        
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"TTS service call failed: {response.status_code}")
        return None

# Usage example
if __name__ == "__main__":
    # Get device list
    devices = get_devices()
    print("Device List:", devices)
    
    # Control device
    result = control_device("Turn on living room light")
    print("Control Result:", result)

⚠️ Error Code Reference

Error Code	Description
0	Success
10002	Parameter error
40000	System error/Operation failed
40001	Parameter validation failed
40002	Network connection failed
40003	Device response timeout

🔐 Security Considerations

API Authentication: All interfaces require a gateway device key (auth parameter) for identity verification
HTTPS Encryption: TLS 1.2+ protocol ensures transport layer data security
Timeout Protection: Server-side 30-second request timeout effectively prevents resource exhaustion
Access Control: Granular permission controls based on device IDs and keys
Audit Logging: Complete access logs for all API calls, supporting security audits

📦 Project Repository: https://gitee.com/panzuji/ha-esp32
📚 Complete Technical Documentation: https://bxk64web49.feishu.cn/docx/XAVJdha5FoI5bjxKELqcz3rJnwg
💾 Firmware Download: https://gitee.com/panzuji/ha-esp32/releases

Contents

FeiYang Smart Control API Documentation - ESP32 Smart Home Control System

📋 Interface List

👤 User Interfaces

📝 Interface Detailed Descriptions

1️⃣ Get Gateway Device List

Request Parameters:

Response Data:

Error Codes:

2️⃣ Device Control

Request Body:

Request Parameters:

Response Data:

Error Codes:

3️⃣ TTS Service

Request Body:

Request Parameters:

Response Data:

Error Codes:

📡 Communication Protocol Description

🧪 Example Code

📋 Multi-language Examples

cURL Examples

JavaScript (Fetch API)

Python Example

⚠️ Error Code Reference

🔐 Security Considerations

🔄 Related Resources