iotapi — IoT Platform Management Toolkit

Setup

If iotapi MCP tools are already available, no setup is needed — just use them.

Otherwise, the user needs to configure their IoT platform connection. Direct them to set up credentials using one of these methods:

Method 1: Using Token (Recommended for Quick Start)

If the user already has a token from the web UI:

mkdir -p ~/.config/iotapi && cat > ~/.config/iotapi/credentials.json << 'EOF'
{
  "base_url": "https://iot.iwillcloud.com",
  "token": "YOUR_TOKEN_HERE"
}
EOF

Method 2: Using AppKey/AppSecret (Auto-refresh)

For long-term use with automatic token refresh:

mkdir -p ~/.config/iotapi && cat > ~/.config/iotapi/credentials.json << 'EOF'
{
  "base_url": "https://iot.iwillcloud.com",
  "app_key": "YOUR_APP_KEY",
  "app_secret": "YOUR_APP_SECRET"
}
EOF

Method 3: Environment Variables

export IOTAPI_BASE_URL="https://iot.iwillcloud.com"
export IOTAPI_TOKEN="your_token_here"
# OR
export IOTAPI_APP_KEY="your_app_key"
export IOTAPI_APP_SECRET="your_app_secret"

When to Trigger This Setup

• User asks to interact with IoT devices but no iotapi MCP tools are available and no credentials configured
• Any API call fails with 401 authentication error
• User mentions their IoT platform URL or wants to connect to their IoT system

Direct API Mode

When MCP tools are NOT available, call the API directly using curl via Bash.

Getting Credentials

Read in order, use the first one found:

1. Environment variables: IOTAPI_BASE_URL, IOTAPI_TOKEN (or IOTAPI_APP_KEY + IOTAPI_APP_SECRET)
2. Config file: ~/.config/iotapi/credentials.json (macOS/Linux) or %APPDATA%\iotapi\credentials.json (Windows)

   {
     "base_url": "https://iot.iwillcloud.com",
     "token": "...",
     "app_key": "...",
     "app_secret": "..."
   }
   

3. If neither exists, direct the user to configure credentials. Do NOT ask the user to paste credentials in chat.

Getting a Token

If only app_key and app_secret are available, obtain a token first:

curl -X POST "${IOTAPI_BASE_URL}/api/v1/oauth/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "appKey": "'"${IOTAPI_APP_KEY}"'",
    "appSecret": "'"${IOTAPI_APP_SECRET}"'"
  }'

Response:

{
  "code": 200,
  "success": true,
  "data": "77e7368a-fe49-4bb7-8755-50756ebf26f4",
  "errorMessage": ""
}

Extract the token from data field and use it in subsequent requests.

API Call Pattern

Important: This platform uses a custom token header, NOT the standard Authorization: Bearer format.

curl -X POST "${IOTAPI_BASE_URL}/api/v1/{endpoint}" \
  -H "Content-Type: application/json" \
  -H "token: ${IOTAPI_TOKEN}" \
  -d '{
    "param1": "value1",
    "param2": "value2"
  }'

All requests are POST with JSON body. Responses follow this format:

{
  "code": 200,
  "success": true,
  "data": { ... },
  "errorMessage": ""
}

• code: 200 = success, other values indicate errors
• success: boolean indicating if request succeeded
• data: response payload (structure varies by endpoint)
• errorMessage: error description (empty on success)

API Endpoints

Authentication

Get Token

Endpoint: POST /api/v1/oauth/auth

Parameters:

{
  "appKey": "string",
  "appSecret": "string"
}

Response: Token string in data field (valid for 24 hours)

Alarm APIs

Query Alarm List

Endpoint: POST /api/v1/alarm/queryAlarmListAll

Parameters:

Response: Array of alarm objects with fields:

• name: Alarm name
• category: Category (e.g., "Point")
• level: Level (e.g., "Level1")
• generateValue: Trigger value
• restoreValue: Restore value
• restoreTime: Restore timestamp
• status: Current status
• device: Device object
• createTime: Creation timestamp

Product APIs

Create Product

Endpoint: POST /api/v1/product/create

Parameters:

Query Product Details

Endpoint: POST /api/v1/product/query

Parameters: Provide one of:

• productKey: Product key
• productId: Product ID

Query All Products

Endpoint: POST /api/v1/product/queryListAll

Parameters:

Response: Array of products with fields:

• productKey: Product identifier
• productName: Product name
• authType: Authentication type
• productSecret: Product secret
• deviceNumber: Number of devices
• propertyNumber: Number of properties
• eventNumber: Number of events
• serviceNumber: Number of services

Delete Product

Endpoint: POST /api/v1/product/delete

Parameters: Provide one of:

• productKey: Product key
• productId: Product ID

Device APIs

Quick Register Device

Endpoint: POST /api/v1/quickdevice/register

Parameters:

Query Device Details

Endpoint: POST /api/v1/quickdevice/detail

Parameters: Provide one of:

• deviceName: Device code
• deviceId: Device ID

Response: Device object with fields:

• deviceId: Device unique ID
• deviceName: Device code
• nickName: Device nickname
• productKey: Product key
• productName: Product name
• deviceSecret: Device secret
• status: Device status (ONLINE, OFFLINE, UNACTIVE)
• ipAddress: IP address
• activeTime: Activation timestamp
• onlineTime: Last online timestamp
• createTime: Creation timestamp
• firmwareVersion: Firmware version (if reported)

Query Device Status

Endpoint: POST /api/v1/quickdevice/status

Parameters: Provide one of:

• deviceName: Device code
• deviceId: Device ID

Response: Status string (ONLINE, OFFLINE, UNACTIVE)

Batch Query Device State

Endpoint: POST /api/v1/quickdevice/batchGetDeviceState

Parameters: Provide one of (max 100 devices):

• deviceName: Array of device codes
• deviceId: Array of device IDs

Response: Array of device state objects

Batch Query Device Details

Endpoint: POST /api/v1/quickdevice/batchQueryDeviceDetail

Parameters:

Query Devices by Product

Endpoint: POST /api/v1/quickdevice/queryDevice

Parameters:

Response: Array of all devices under the product

Thing Model APIs

Query Thing Model

Endpoint: POST /api/v1/thing/queryThingModel

Parameters:

Response: Thing model definition with properties, events, and services

Set Device Property

Endpoint: POST /api/v1/thing/setDevicesProperty

Parameters:

Batch Set Device Properties

Endpoint: POST /api/v1/thing/setBatchDevicesProperty

Parameters:

Invoke Device Service

Endpoint: POST /api/v1/thing/invokeThingsService

Parameters:

Batch Invoke Device Service

Endpoint: POST /api/v1/thing/invokeBatchThingsService

Parameters:

Query Device Property Data

Endpoint: POST /api/v1/thing/queryDevicePropertyData

Parameters:

Batch Query Device Properties Data

Endpoint: POST /api/v1/thing/queryDevicePropertiesData

Parameters:

Query Device Event Data

Endpoint: POST /api/v1/thing/queryDeviceEventData

Parameters:

Query Device Service Data

Endpoint: POST /api/v1/thing/queryDeviceServiceData

Parameters:

Response: Array of service call records with fields:

• send: Sent content
• receive: Response content
• receiveTime: Response timestamp
• result: Result
• resultTime: Result timestamp
• servicePoint: Service point info

Custom Topic APIs

For devices that don't use thing model, the platform supports custom topics for transparent message passing.

Topics:

• Subscribe (device receives): /{productKey}/{deviceName}/user/get
• Publish (device sends): /{productKey}/{deviceName}/user/update
• Error: /{productKey}/{deviceName}/user/update/error

Send Custom Message to Device

Endpoint: POST /api/v1/device/down/record/add/custom

Parameters:

Example: To send binary Modbus command 01 03 00 00 00 01 84 0A:

# Convert to Base64: AQMAAAABhAo=
curl -X POST "${IOTAPI_BASE_URL}/api/v1/device/down/record/add/custom" \
  -H "Content-Type: application/json" \
  -H "token: ${IOTAPI_TOKEN}" \
  -d '{
    "deviceName": "Wk9kOa5NLX",
    "messageContent": "AQMAAAABhAo="
  }'

RRPC (Synchronous MQTT Communication)

RRPC enables synchronous request-response communication with devices over MQTT.

Device subscribes to: /sys/${productKey}/${deviceName}/rrpc/request/+ Device responds to: /sys/${productKey}/${deviceName}/rrpc/response/${requestId}

Send RRPC Request

Endpoint: POST /api/v1/device/rrpc

Parameters:

Response:

{
  "code": 200,
  "success": true,
  "data": {
    "rrpcCode": "SUCCESS",  // or "TIMEOUT", "OFFLINE"
    "payloadBase64Byte": "base64_encoded_response"
  }
}

RRPC Codes:

• SUCCESS: Device responded successfully
• TIMEOUT: No response within timeout period
• OFFLINE: Device is offline

Note: Platform automatically handles Base64 encoding/decoding. Device receives raw bytes and should respond with raw bytes.

Error Handling

Best Practices

Workflow Patterns

1. Device Management Flow:

Query products → Select product → Query devices → Get device details/status

2. Device Control Flow:

Query thing model → Identify properties/services → Set property or invoke service

3. Data Query Flow:

Get device list → Query property/event/service data for time range

Performance Tips

• Use batch APIs when operating on multiple devices (max 100 per request)
• Query thing model once and cache the structure
• Use parallel requests for independent operations
• For real-time control, prefer RRPC over async property setting
• Use custom topics for devices with proprietary protocols

Common Patterns

Check device online status before control:

# 1. Check status
curl -X POST "${IOTAPI_BASE_URL}/api/v1/quickdevice/status" \
  -H "Content-Type: application/json" \
  -H "token: ${IOTAPI_TOKEN}" \
  -d '{"deviceName": "sensor_001"}'

# 2. If online, set property
curl -X POST "${IOTAPI_BASE_URL}/api/v1/thing/setDevicesProperty" \
  -H "Content-Type: application/json" \
  -H "token: ${IOTAPI_TOKEN}" \
  -d '{
    "deviceName": "sensor_001",
    "pointList": [{"identifier": "temperature_threshold", "value": "25"}]
  }'

Query historical data with time range:

curl -X POST "${IOTAPI_BASE_URL}/api/v1/thing/queryDevicePropertyData" \
  -H "Content-Type: application/json" \
  -H "token: ${IOTAPI_TOKEN}" \
  -d '{
    "deviceName": "sensor_001",
    "identifier": "temperature",
    "startTime": "2025-01-01T00:00:00.000Z",
    "endTime": "2025-01-31T23:59:59.999Z",
    "downSampling": "1h"
  }'

Data Limitations