小蜜陪护机器人 - 通用设备管理指南

akinggw

391人浏览 · 2026-07-20 21:36:54

akinggw · 2026-07-20 21:36:54 发布

通用设备管理指南

概述

小蜜陪护机器人支持通过 TCP 协议连接和管理各种智能设备，如空调、灯光、窗帘、传感器等。本文以"客厅空调"为例，详细说明如何配置和管理通用设备。

系统架构

通用设备管理模块

系统通过 GenericDeviceManager 模块实现通用设备的管理，主要功能包括：

TCP 服务器监听，接收设备连接
设备上线/离线状态管理
命令发送与响应处理
心跳检测与超时管理
脚本事件分发

通信协议

设备与服务器之间采用二进制协议通信，数据格式如下：

[DEV][srcDataLen(4字节大端序)][comDataLen(4字节大端序)][压缩数据]

消息类型：

消息类型	说明	方向
`device_online`	设备上线，携带设备信息和支持的命令列表	设备→服务器
`device_message`	设备消息/响应	设备→服务器
`device_offline`	设备离线通知	设备→服务器
`device_command`	服务器下发的控制命令	服务器→设备

配置步骤

步骤一：准备模拟设备

项目提供了 test/sim_air_conditioner.py 脚本用于模拟空调设备。

配置模拟器参数

SERVER_HOST = "127.0.0.1"    # 小蜜服务器地址
SERVER_PORT = 9090           # 通用设备服务器端口
DEVICE_NAME = "客厅空调"      # 设备名称
RECONNECT_INTERVAL = 5       # 断线重连间隔（秒）

启动模拟器

cd d:\kunbao_agent\agent_test
python test/sim_air_conditioner.py

启动成功后输出：

连接通用设备服务器 127.0.0.1:9090 ...
已连接! 发送上线消息...
设备已上线 (Ctrl+C退出)

步骤二：配置小蜜服务器端口

在小蜜陪护机器人中配置通用设备服务器端口：

打开"系统设置"
在"设备设置"中找到"通用设备服务器端口"
设置端口为 9090（与模拟器配置一致）
重启小蜜陪护机器人使配置生效

步骤三：验证设备在线

启动模拟器后，在小蜜的"设备管理"界面查看：

设备列表中应显示"客厅空调"
设备状态显示为"在线"
可查看设备支持的命令列表

设备命令说明

空调支持的命令

命令	说明	参数	示例
`power_on`	开机	无	`{"cmd":"power_on"}`
`power_off`	关机	无	`{"cmd":"power_off"}`
`set_temp`	设置温度	`temp`: 目标温度(整数)	`{"cmd":"set_temp","temp":26}`
`set_mode`	设置模式	`mode`: 制冷/制热/除湿/送风	`{"cmd":"set_mode","mode":"制冷"}`
`get_status`	查询状态	无	`{"cmd":"get_status"}`

查询设备状态

发送 get_status 命令后，设备返回当前状态：

{
    "success": true,
    "result": {
        "power": true,
        "target_temp": 26,
        "current_temp": 25.8,
        "mode": "制冷",
        "fan_speed": "自动"
    }
}

通过语音控制设备

小蜜陪护机器人支持通过语音指令控制通用设备，例如：

"打开客厅空调" → 发送 power_on 命令
"关闭客厅空调" → 发送 power_off 命令
"把空调温度调到25度" → 发送 set_temp 命令
"空调改成制热模式" → 发送 set_mode 命令

语音控制流程

用户语音输入 → ASR 转写为文本
Agent 识别意图和设备名称
调用"通用设备控制"工具
工具通过 GenericDeviceManager 发送命令
设备执行命令并返回结果
TTS 语音播报执行结果

通过 Agent 工具控制

通用设备控制工具

系统提供了"通用设备控制"工具，可通过脚本或 Agent 调用：

工具配置（agentconfigs/tools/通用设备控制.tool）：

{
    "name": "通用设备控制",
    "description": "控制智能设备，如空调、灯光等",
    "params": [
        {"type": "string", "name": "device_name", "description": "设备名称"},
        {"type": "string", "name": "command", "description": "命令JSON字符串"}
    ],
    "script_content": "..."
}

调用示例：

// 打开空调
var result = 通用设备控制("客厅空调", '{"cmd":"power_on"}');

// 设置温度
var result = 通用设备控制("客厅空调", '{"cmd":"set_temp","temp":26}');

自定义设备开发

设备协议规范

开发自定义设备时，需遵循以下协议规范：

连接流程

设备连接到服务器的 TCP 端口
设备发送 device_online 消息，包含设备信息和命令列表
服务器记录设备状态，通知 UI 和脚本
设备定时发送心跳消息（device_message + data_type: heartbeat）
设备接收并处理服务器下发的命令
设备发送响应消息（device_message）

device_online 消息格式

{
    "msgtype": "device_online",
    "device_name": "客厅空调",
    "device_type": "air_conditioner",
    "commands": [
        {"name": "power_on", "description": "开机", "example": "{\"cmd\":\"power_on\"}"},
        {"name": "set_temp", "description": "设温度", "params": {"temp": "整数"}, "example": "{\"cmd\":\"set_temp\",\"temp\":26}"}
    ]
}

device_command 消息格式

{
    "msgtype": "device_command",
    "cmd": "set_temp",
    "temp": 26
}

device_message 响应格式

{
    "msgtype": "device_message",
    "device_name": "客厅空调",
    "success": true,
    "result": "目标温度已设为26度"
}

设备模拟器开发模板

参考 test/sim_air_conditioner.py，开发自定义设备模拟器：

import socket
import struct
import zlib
import json

def build_packet(json_obj):
    json_bytes = json.dumps(json_obj, ensure_ascii=False).encode("utf-8")
    compressed = zlib.compress(json_bytes)
    header = b"DEV" + struct.pack(">II", len(json_bytes), len(compressed))
    return header + compressed

def send_online(sock):
    send_msg(sock, {
        "msgtype": "device_online",
        "device_name": "自定义设备",
        "device_type": "custom",
        "commands": [
            {"name": "command1", "description": "命令说明"}
        ]
    })

def main():
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.connect(("127.0.0.1", 9090))
    send_online(sock)
    # 接收和处理命令...

常见问题

设备连接失败

问题：模拟器提示"连接失败: Connection refused"

解决方案：

确认小蜜陪护机器人已启动
确认通用设备服务器端口配置正确（默认 9090）
确认防火墙未阻止端口访问

设备在线但无响应

问题：设备显示在线，但发送命令无响应

解决方案：

检查设备是否定期发送心跳（默认每10秒一次）
检查网络连接是否正常
查看小蜜日志（bin/logs/）中的错误信息

设备频繁离线

问题：设备频繁显示离线/在线状态切换

解决方案：

检查网络稳定性
调整心跳间隔（建议 5-15 秒）
调整服务器超时时间（默认 45 秒）

命令格式错误

问题：设备返回"未知命令"或参数错误

解决方案：

检查命令格式是否正确
参考设备的 commands 列表获取正确的命令和参数
使用 get_status 命令验证设备通信正常

注意事项

端口冲突：确保通用设备服务器端口（默认 9090）未被其他程序占用
设备名称：设备名称需唯一，不能与其他设备重名
网络安全：建议在局域网内使用，避免直接暴露在公网
心跳机制：设备需定期发送心跳消息，否则会被标记为离线
断线重连：设备应实现自动重连机制，确保网络恢复后自动上线

扩展功能

添加新设备类型

开发设备模拟器或真实设备固件
在设备上线消息中声明支持的命令
通过 Agent 工具调用新设备的命令
在场景脚本中使用设备数据

设备联动

通过场景脚本实现设备联动，例如：

function onDeviceOnline(deviceId, deviceInfo, clientInfo) {
    var deviceName = JSON.parse(deviceInfo).device_name;
    if (deviceName === "客厅空调") {
        // 空调上线时自动同步状态
        var status = 通用设备控制("客厅空调", '{"cmd":"get_status"}');
        // 更新场景状态...
    }
}

通过以上步骤，您可以完成通用设备的配置和管理。如需添加更多设备类型，只需按照协议规范开发相应的设备模拟器或固件即可。