设备管理

设备管理 API 提供设备的查询、更新、删除和分组管理功能。注意，设备只能通过 bind 接口添加到组织，不支持直接创建。

获取设备列表

获取当前组织的所有设备。

请求

http

GET /api/v2/devices/

查询参数

参数	类型	必填	说明
search	string	否	搜索设备 ID 或描述
group	string	否	按分组过滤，使用分组 ID，'none' 表示未分组

响应

json

[
    {
        "id": "device_id",
        "device_id": "设备ID",
        "info": "设备描述",
        "group": {
            "id": "group_id",
            "name": "分组名称"
        },
        "allow": true,
        "bind_time": "2024-01-08T10:00:00Z",
        "create_time": "2024-01-08T10:00:00Z"
    }
]

示例

Python

python

import requests

# 配置
API_BASE = "https://ums.holdingbyte.com/api/v2"
ACCESS_TOKEN = "your_access_token"

def list_devices(search=None, group=None):
    """获取设备列表
    
    Args:
        search: 搜索关键字
        group: 分组ID，'none' 表示未分组
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    params = {}
    if search:
        params['search'] = search
    if group:
        params['group'] = group
    
    url = f"{API_BASE}/devices/"
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# 使用示例
# 获取所有设备
devices = list_devices()
print("所有设备:", devices)

# 搜索设备
devices = list_devices(search="温度")
print("搜索结果:", devices)

# 获取指定分组的设备
devices = list_devices(group="group_1")
print("分组设备:", devices)

cURL

bash

# 获取所有设备
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/" \
     -H "Authorization: Bearer your_access_token"

# 搜索设备
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/?search=温度" \
     -H "Authorization: Bearer your_access_token"

# 获取指定分组的设备
curl -X GET "https://ums.holdingbyte.com/api/v2/devices/?group=group_1" \
     -H "Authorization: Bearer your_access_token"

获取设备详情

获取单个设备的详细信息。

请求

http

GET /api/v2/devices/{device_id}/

响应

返回单个设备信息，格式同列表项。

示例

Python

python

def get_device(device_id):
    """获取设备详情
    
    Args:
        device_id: 设备ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/"
    response = requests.get(url, headers=headers)
    return response.json()

# 使用示例
device_id = "device_1"
device = get_device(device_id)
print(f"设备详情: {device}")

cURL

bash

curl -X GET "https://ums.holdingbyte.com/api/v2/devices/device_1/" \
     -H "Authorization: Bearer your_access_token"

更新设备信息

更新设备的基本信息。

请求

http

PUT /api/v2/devices/{device_id}/

请求参数

字段	类型	必填	说明
info	string	否	设备描述
group	string	否	设备分组ID
allow	boolean	否	是否允许接入

请求示例

json

{
    "info": "新的设备描述",
    "group": "group_id",
    "allow": true
}

响应

返回更新后的设备信息，格式同列表项。

示例

Python

python

def update_device(device_id, info=None, group=None, allow=None):
    """更新设备信息
    
    Args:
        device_id: 设备ID
        info: 设备描述
        group: 分组ID
        allow: 是否允许接入
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {}
    if info is not None:
        data['info'] = info
    if group is not None:
        data['group'] = group
    if allow is not None:
        data['allow'] = allow
    
    url = f"{API_BASE}/devices/{device_id}/"
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# 使用示例
device_id = "device_1"
result = update_device(
    device_id,
    info="温度传感器 #1",
    group="group_1",
    allow=True
)
print(f"更新结果: {result}")

cURL

bash

curl -X PUT "https://ums.holdingbyte.com/api/v2/devices/device_1/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"info": "温度传感器 #1", "group": "group_1", "allow": true}'

绑定设备

将设备绑定到当前组织。

请求

http

POST /api/v2/devices/bind/

请求参数

字段	类型	必填	说明
device_id	string	是	设备ID
safe_code	string	是	设备安全码

请求示例

json

{
    "device_id": "device_id",
    "safe_code": "safe_code"
}

响应

绑定成功后返回设备信息，格式同列表项。

示例

Python

python

def bind_device(device_id, safe_code):
    """绑定设备
    
    Args:
        device_id: 设备ID
        safe_code: 设备安全码
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "device_id": device_id,
        "safe_code": safe_code
    }
    
    url = f"{API_BASE}/devices/bind/"
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 使用示例
device_id = "device_1"
safe_code = "1234567890"
result = bind_device(device_id, safe_code)
print(f"绑定结果: {result}")

cURL

bash

curl -X POST "https://ums.holdingbyte.com/api/v2/devices/bind/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"device_id": "device_1", "safe_code": "1234567890"}'

解绑设备

解除设备与当前组织的绑定关系。

请求

http

POST /api/v2/devices/{device_id}/unbind/

响应

成功解绑返回 204 状态码，无响应内容。

示例

Python

python

def unbind_device(device_id):
    """解绑设备
    
    Args:
        device_id: 设备ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/unbind/"
    response = requests.post(url, headers=headers)
    return response.status_code == 204

# 使用示例
device_id = "device_1"
success = unbind_device(device_id)
print(f"解绑{'成功' if success else '失败'}")

cURL

bash

curl -X POST "https://ums.holdingbyte.com/api/v2/devices/device_1/unbind/" \
     -H "Authorization: Bearer your_access_token"

重启设备

向设备发送重启命令。只有设备在线时才能执行此操作。

请求

http

POST /api/v2/devices/{device_id}/reboot/

响应

json

{
    "message": "重启命令已发送",
    "token": "命令令牌"
}

错误响应

状态码	说明
401	未认证
404	设备不存在
503	设备离线或无法重启

示例

Python

python

def reboot_device(device_id):
    """重启设备
    
    Args:
        device_id: 设备ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    url = f"{API_BASE}/devices/{device_id}/reboot/"
    response = requests.post(url, headers=headers)
    return response.json()

# 使用示例
device_id = "device_1"
result = reboot_device(device_id)
print(f"重启结果: {result}")

cURL

bash

curl -X POST "https://ums.holdingbyte.com/api/v2/devices/device_1/reboot/" \
     -H "Authorization: Bearer your_access_token"

设置串口参数

设置设备的串口通信参数，包括波特率、数据位、停止位、校验位和流控制。只有设备在线时才能执行此操作。

请求

http

POST /api/v2/devices/{device_id}/set-serial/

请求参数

字段	类型	必填	默认值	说明
baud_rate	integer	否	9600	波特率，支持：1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
data_bits	integer	否	8	数据位，支持：7, 8
stop_bits	integer	否	1	停止位，支持：1(1位), 15(1.5位), 2(2位)
parity	integer	否	0	校验位，0:无校验, 1:奇校验, 2:偶校验, 3:标记, 4:空格

请求示例

json

{
    "baud_rate": 115200,
    "data_bits": 8,
    "stop_bits": 1,
    "parity": 0
}

响应

json

{
    "message": "串口参数设置命令已发送",
    "token": "命令令牌"
}

错误响应

状态码	说明
400	参数错误
401	未认证
404	设备不存在
503	设备离线或无法设置

示例

Python

python

def set_serial_params(device_id, baud_rate=9600, data_bits=8, stop_bits=1, parity=0):
    """设置设备串口参数
    
    Args:
        device_id: 设备ID
        baud_rate: 波特率
        data_bits: 数据位
        stop_bits: 停止位
        parity: 校验位
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "baud_rate": baud_rate,
        "data_bits": data_bits,
        "stop_bits": stop_bits,
        "parity": parity
    }
    
    url = f"{API_BASE}/devices/{device_id}/set-serial/"
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 使用示例
device_id = "device_1"
# 设置串口参数为：115200, 8N1, 无流控
result = set_serial_params(
    device_id,
    baud_rate=115200,
    data_bits=8,
    stop_bits=1,
    parity=0
)
print(f"设置结果: {result}")

cURL

bash

curl -X POST "https://ums.holdingbyte.com/api/v2/devices/device_1/set-serial/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{
         "baud_rate": 115200,
         "data_bits": 8,
         "stop_bits": 1,
         "parity": 0
     }'

设备管理 ​

获取设备列表 ​

请求 ​

查询参数 ​

响应 ​

示例 ​

Python ​

cURL ​

获取设备详情 ​

请求 ​

响应 ​

示例 ​

Python ​

cURL ​

更新设备信息 ​

请求 ​

请求参数 ​

请求示例 ​

响应 ​

示例 ​

Python ​

cURL ​

绑定设备 ​

请求 ​

请求参数 ​

请求示例 ​

响应 ​

示例 ​

Python ​

cURL ​

解绑设备 ​

请求 ​

响应 ​

示例 ​

Python ​

cURL ​

重启设备 ​

请求 ​

响应 ​

错误响应 ​

示例 ​

Python ​

cURL ​

设置串口参数 ​

请求 ​

请求参数 ​

请求示例 ​

响应 ​

错误响应 ​

示例 ​

Python ​

cURL ​

设备管理

获取设备列表

请求

查询参数

响应

示例

Python

cURL

获取设备详情

请求

响应

示例

Python

cURL

更新设备信息

请求

请求参数

请求示例

响应

示例

Python

cURL

绑定设备

请求

请求参数

请求示例

响应

示例

Python

cURL

解绑设备

请求

响应

示例

Python

cURL

重启设备

请求

响应

错误响应

示例

Python

cURL

设置串口参数

请求

请求参数

请求示例

响应

错误响应

示例

Python

cURL