硬件设备管理接口

1573字约5分钟

2025-04-10

使用设备管理接口可以进行查询设备列表、更新设备、解绑设备。

查询设备列表

适用对象： 第三方服务端请求

请求URL： https://api.espai.fun/devices/list

请求方式： POST

请求参数：

字段名	类型	必填	描述
name	string	否	设备名称
api_key	string	否	设备的api_key，用户设备相关配置的密钥；注意：不是open_api_key
device_id	string	否	设备SM；例如：`FC:01:2C:DB:14:30`；注意非32位ID
bin_id	string	否	固件ID
version	string	否	固件版本
enable	string	否	是否启用；0：禁止（默认），1：启用
is_online	string	否	是否在线；0：离线，1：在线
type	string	否	设备类型；0：对话设备（默认），1：终端设备
page	string	否	分页查询当前页；默认当前第1页
limit	string	否	分页查询查询条数；默认查询9999条

注意：当所有参数都不传时，默认查询当前用户下的所有设备，返回设备列表。

参数示例：

{
  "name": "小琅",
  "api_key": "你自己设备对应的api_key",
  "device_id": "FC:01:2C:DB:14:30",
  "bin_id": "0",
  "version": "1.22.34",
  "enable": "1",
  "is_online": "1",
  "type": "0",
  "page": "1",
  "limit": "10"
}

返回参数：

字段名	类型	必填	描述
success	boolean	是	结果标识；true：成功，false：请求失败
totalNumber	number	是	返回的数据总数
message	string	是	返回的消息；例如：`请求成功`或其他异常信息
data	array	是	返回的数据列表

设备信息：

字段名	描述
id	设备ID
create_time	创建时间
update_time	更新时间
sort	设备排序
ext1	扩展字段
ext2	扩展字段
ext3	扩展字段
name	设备名称
user_id	绑定的用户ID
equipment_id	绑定的超体ID
api_key	设备的api_key
enable	是否启用；0：禁止（默认），1：启用
is_online	是否在线；0：离线，1：在线
device_id	设备SM

字段名	描述
wifi_ssid	设备连接wifi名称
wifi_pwd	设备连接wifi密码
net_ip	配网IP
version	固件版本
bin_id	固件ID
nation	设备所在国家
province	设备所在省
city	设备所在市
type	设备类型；0：对话设备（默认），1：终端设备
memory	凝忆晶胞
latitude	维度
longitude	经度
user_name	绑定的用户名
user_phone	绑定的用户号码

返回示例：

{
  "success": true,
  "message": "请求成功",
  "data": [
    {
      "id": "2cf661bb42b642018ee13af7150b8310",
      "create_time": 1744180142741,
      "update_time": 1744268200431,
      "sort": null,
      "ext1": null,
      "ext2": null,
      "ext3": null,
      "name": "小琅",
      "user_id": "87215a4192654cea8781a1a596d23cae",
      "equipment_id": "679f9af935e047639ddb98f35e103e8f",
      "api_key": "",
      "enable": "1",
      "is_online": "0",
      "device_id": "FC:01:2C:DB:14:30",
      "wifi_ssid": "联域科技",
      "wifi_pwd": "lykj987654321",
      "net_ip": "xxx.xxx.xxx.xxx",
      "version": "1.22.34",
      "bin_id": "0",
      "nation": "China",
      "province": "Guangdong",
      "city": "Guangzhou",
      "type": null,
      "memory": "用户问候，助手以“乌鸦哥”的身份回应，并提出可以帮助用户。",
      "latitude": "23.1181",
      "longitude": "113.2539",
      "user_name": "琳琅",
      "user_phone": 15916888888
    }
  ],
  "totalNumber": 1
}

错误示例：

{
  "success": false,
  "message": "系统错误：xxx",
  "code": 500
}

代码示例：

Nodejs

const axios = require('axios');

// 定义请求头部
const headers = {
    'authorization': 'esp_ai平台的32位open_api_key',
    'Content-Type': 'application/json'
};


// 定义要发送的数据
const data = {
    "name": "小琅",
    "api_key": "你自己设备对应的api_key",
    "device_id": "FC:01:2C:DB:14:30",
    "bin_id": "0",
    "version": "1.22.34",
    "enable": "1",
    "is_online": "1",
    "type": "0",
    "page": "1",
    "limit": "10"
};

// 发送POST请求
axios.post('https://api.espai.fun/devices/list', data, {headers})
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

更新设备

适用对象： 第三方服务端请求

请求URL： https://api.espai.fun/devices/update

请求方式： POST

请求参数：

字段名	类型	必填	描述
id	string	是	设备ID
name	string	否	设备名称
version	string	否	固件版本
enable	string	否	是否启用；0：禁止（默认），1：启用
wifi_ssid	string	否	设备连接wifi名称
wifi_pwd	string	否	设备连接wifi密码
net_ip	string	否	配网IP
bin_id	string	否	固件ID
nation	string	否	设备所在国家
province	string	否	设备所在省
city	string	否	设备所在市
longitude	string	否	经度
latitude	string	否	纬度
localData	json	否	设备本地数据

参数示例：

{
  "id": "2cf661bb42b642018ee13af7150b8310",
  "name": "小琅",
  "version": "1.22.34",
  "enable": "1",
  "wifi_ssid": "联域科技",
  "wifi_pwd": "lykj987654321",
  "net_ip": "192.168.3.71",
  "bin_id": "0",
  "nation": "China",
  "province": "Guangdong",
  "city": "Guangzhou",
  "longitude": "113.2539",
  "latitude": "23.1181",
  "localData": {
    "wifi_ssid": "联域科技",
    "wifi_pwd": "lykj987654321"
  }
}

返回参数：

字段名	类型	必填	描述
success	boolean	是	结果标识；true：成功，false：请求失败
message	string	是	返回的消息；例如：`修改成功`或其他异常信息
data	json	是	返回的已变更的数据，参考`设备信息`

返回示例：

{
  "success": true,
  "message": "修改成功",
  "data": {
    "version": "1.22.34",
    "name": "小琅",
    "enable": "1",
    "wifi_ssid": "联域科技",
    "wifi_pwd": "lykj987654321",
    "net_ip": "192.168.3.71",
    "bin_id": "0",
    "nation": "China",
    "province": "Guangdong",
    "city": "Guangzhou",
    "latitude": "23.1181",
    "longitude": "113.2539",
    "update_time": 1744274870626
  }
}

错误示例：

{
  "success": false,
  "message": "系统错误：xxx",
  "code": 500
}

{
  "success": false,
  "message": "缺失参数：id",
  "code": 401
}

代码示例：

Nodejs

const axios = require('axios');

// 定义请求头部
const headers = {
    'authorization': 'esp_ai平台的32位open_api_key',
    'Content-Type': 'application/json'
};


// 定义要发送的数据
const data = {
    "id": "2cf661bb42b642018ee13af7150b8310",
    "name": "小琅",
    "version": "1.22.34",
    "enable": "1",
    "wifi_ssid": "联域科技",
    "wifi_pwd": "lykj987654321",
    "net_ip": "192.168.3.71",
    "bin_id": "0",
    "nation": "China",
    "province": "Guangdong",
    "city": "Guangzhou",
    "longitude": "113.2539",
    "latitude": "23.1181",
    "localData": {"wifi_ssid": "联域科技", "wifi_pwd": "lykj987654321"}
};

// 发送POST请求
axios.post('https://api.espai.fun/devices/update', data, {headers})
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

解绑设备(基于ID)

适用对象： 第三方服务端请求

请求URL： https://api.espai.fun/devices/del

请求方式： POST

请求参数：

字段名	类型	必填	描述
id	string	是	设备ID

参数示例：

[
  {
    "id": "b93ec353967441ada8d31b4910a3032d"
  }
]

返回参数：

字段名	类型	必填	描述
success	boolean	是	结果标识；true：成功，false：请求失败
message	string	是	返回的消息；例如：`解绑成功`或其他异常信息

返回示例：

{
  "success": true,
  "message": "解绑成功"
}

错误示例：

{
  "success": false,
  "message": "系统错误：xxx",
  "code": 500
}

{
  "success": false,
  "message": "解绑失败，请传入需要解绑的数据"
}

{
  "success": false,
  "message": "设备未找到，请检查！"
}

代码示例：

Nodejs

const axios = require('axios');

// 定义请求头部
const headers = {
    'authorization': 'esp_ai平台的32位open_api_key',
    'Content-Type': 'application/json'
};


// 定义要发送的数据
const data = [{"id": "b93ec353967441ada8d31b4910a3032d"}];

// 发送POST请求
axios.post('https://api.espai.fun/devices/del', data, {headers})
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

解绑设备(基于设备MAC地址)

适用对象： 第三方服务端请求

请求URL： https://api.espai.fun/devices/unbind

请求方式： POST

请求参数：

字段名	类型	必填	描述
api_key	string	是	超体秘钥
device_id	string	是	设备MAC地址

参数示例：

 {
    "api_key": "xxx", 
    "device_id": "XX:XX:XX:XX:XX:XX"
  }

返回参数：

字段名	类型	必填	描述
success	boolean	是	结果标识；true：成功，false：请求失败
message	string	是	返回的消息；例如：`解绑成功`或其他异常信息

返回示例：

{
  "success": true,
  "message": "解绑成功"
}

硬件设备管理接口

查询设备列表

更新设备

解绑设备(基于ID)

解绑设备(基于设备MAC地址)

🎉 ESP-AI 公告 🎉

📢 2025 年 7 月 14 日

1. 一大波文档修改，比如客户端代码中增加设备绑定说明。

2. ESP-AI-C3固件和PCB发布：去看看

📢 2025 年 6 月 27 日

ESP-AI-Studio 发布，每个人都可以在线编辑自己的固件啦！去看看