ESP-AI

简体中文

English

简体中文

English

外观

设备管理接口

1432字约5分钟

2025-04-10

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

查询设备列表

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

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

请求方式： POST

请求参数：

字段名类型必填描述
namestring否设备名称
api_keystring否设备的api_key，用户设备相关配置的密钥；注意：不是open_api_key
device_idstring否设备SM；例如：FC:01:2C:DB:14:30；注意非32位ID
bin_idstring否固件ID
versionstring否固件版本
enablestring否是否启用；0：禁止（默认），1：启用
is_onlinestring否是否在线；0：离线，1：在线
typestring否设备类型；0：对话设备（默认），1：终端设备
pagestring否分页查询当前页；默认当前第1页
limitstring否分页查询查询条数；默认查询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"
}

返回参数：

字段名类型必填描述
successboolean是结果标识；true：成功，false：请求失败
totalNumbernumber是返回的数据总数
messagestring是返回的消息；例如：请求成功或其他异常信息
dataarray是返回的数据列表

设备信息：

字段名描述
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

请求参数：

字段名类型必填描述
idstring是设备ID
namestring否设备名称
versionstring否固件版本
enablestring否是否启用；0：禁止（默认），1：启用
wifi_ssidstring否设备连接wifi名称
wifi_pwdstring否设备连接wifi密码
net_ipstring否配网IP
bin_idstring否固件ID
nationstring否设备所在国家
provincestring否设备所在省
citystring否设备所在市
longitudestring否经度
latitudestring否纬度
localDatajson否设备本地数据

参数示例：

{
  "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"
  }
}

返回参数：

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

返回示例：

{
  "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);
    });

解绑设备

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

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

请求方式： POST

请求参数：

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

参数示例：

[
  {
    "id": "b93ec353967441ada8d31b4910a3032d"
  }
]

返回参数：

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

返回示例：

{
  "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);
    });
Powered by VuePress & vuepress-theme-plume
Apache 2.0 Licensed | Copyright © ESP-AI 地址：深圳市福田区汉国中心1206

🎉 ESP-AI 公告 🎉


📢 2025 年 6 月 2 日

近期，ESP-AI 服务器及开源仓库遭受大规模恶意攻击。

我们始终坚持将自主研发的代码完全开源，这一行动虽触及部分群体利益，但我们始终坚信技术价值高于一切。

开源不仅是代码的共享，更是极客精神的践行 —— 我们以技术为信仰，以开放为武器，直面行业沉疴。

我们是一群笃信技术力量的极客。 我们确信，唯有通过真正的技术创新与实力角逐，才能打破 “闭源垄断 + 手段竞争” 的行业怪圈。那些企图以非技术手段维系优势的落后模式，终将在开放协作的浪潮中被颠覆。

技术的战场，从不应由 “围墙” 决定胜负。我们将继续以开源为旗，让代码质量与创新能力成为唯一的竞争标准。

极客不死，开源不止。



📢 2025/6/1 公告

ESP-AI 新版已发布：升级日志

open api提供音乐生成接口：OPEN API

open api天气查询接口：OPEN API



QQ qr_code

QQ 交流群： 952051286

您在使用过程中遇到任何问题，欢迎通过 issue 反馈。
也欢迎加入我们的 QQ 交流群一起讨论。