Android设备远程控制(dtnsbot)

dtnsbot安卓设备-无障碍服务 HTTP API 接口文档

基础信息

  • 基础URL(base_url): http://[设备IP]:58082 或 base_url (默认的设备IP为: 127.0.0.1 亦即默认的base_url为 http://127.0.0.1:58082 )
  • 所有请求方式: GET/POST
  • 端点格式要求: 【端点】务必使用完整的http-url-api调用
  • 响应格式: JSON (部分命令返回纯文本)

目录

  1. 系统控制命令
  2. 应用操作命令
  3. 坐标点击命令
  4. 手势滑动命令
  5. 截图功能命令
  6. UI信息命令
  7. 语音API命令
  8. 配置管理命令
  9. 收藏悬浮窗命令
  10. 识图机灵命令
  11. GPS定位命令
  12. 文本操作命令
  13. 命令执行器
  14. 辅助命令
  15. 错误码说明
  16. 文件上传下载
  17. poplang脚本与编程
  18. dbot-ble 平衡车控制命令

1. 系统控制命令

1.1 返回主页

  • 命令: home
  • 描述: 模拟按下Home键,返回系统桌面
  • 示例:
    GET /api/?command=home
    
  • 响应: "返回主页"

1.2 返回上一级

  • 命令: back
  • 描述: 模拟按下返回键
  • 示例:
    GET /api/?command=back
    
  • 响应: "执行返回"

1.3 显示最近任务

  • 命令: recent
  • 描述: 显示最近使用的应用列表
  • 示例:
    GET /api/?command=recent
    
  • 响应: "显示最近任务"

1.4 打开通知栏

  • 命令: notifications
  • 描述: 下拉打开通知栏
  • 示例:
    GET /api/?command=notifications
    
  • 响应: "显示通知"

1.5 电源菜单

  • 命令: power
  • 描述: 显示电源菜单(关机、重启等)
  • 示例:
    GET /api/?command=power
    
  • 响应: "电源菜单"

1.6 锁屏

  • 命令: lock
  • 描述: 锁定屏幕
  • 示例:
    GET /api/?command=lock
    
  • 响应: "锁屏"

1.7 分屏模式

  • 命令: split
  • 描述: 进入分屏模式(需要 Android 7.0+)
  • 示例:
    GET /api/?command=split
    
  • 响应: "分屏模式"

2. 应用操作命令

2.1 打开应用

  • 命令: open_[应用名]

  • 描述: 打开指定的应用

  • 参数:

    • appName: 应用名称(在URL路径中)
  • 示例:

    GET /api/?command=open_设置
    GET /api/?command=open_微信
    
  • 响应: "正在打开 微信"

2.2. 获取应用列表

获取设备上所有已安装的可启动应用列表。

请求

GET /api/?command=get_apps

或

POST /api/
Content-Type: application/x-www-form-urlencoded

command=get_apps

响应示例

{
  "status": "success",
  "count": 156,
  "apps": [
    {
      "name": "微信",
      "packageName": "com.tencent.mm",
      "activityName": "com.tencent.mm.ui.LauncherUI"
    },
    {
      "name": "设置",
      "packageName": "com.android.settings",
      "activityName": "com.android.settings.Settings"
    },
    {
      "name": "Chrome浏览器",
      "packageName": "com.android.chrome",
      "activityName": "com.google.android.apps.chrome.Main"
    }
  ]
}

响应字段说明

字段 类型 说明
status string 状态:success 或 error
count number 应用总数
apps array 应用列表数组
├─ name string 应用显示名称
├─ packageName string 应用包名
└─ activityName string 启动 Activity 完整类名

错误响应

{
  "status": "error",
  "message": "获取应用列表失败: 权限不足"
}

3. 坐标点击命令

3.1 点击坐标

  • 命令: click_at_[x],[y]
  • 描述: 在屏幕指定坐标执行点击操作
  • 参数: 坐标值在命令路径中
  • 示例:
    GET /api/?command=click_at_500,800
    
  • 响应: "坐标点击命令已发送: (500, 800)"

3.2 长按坐标

  • 命令: long_click_at_[x],[y]
  • 描述: 在屏幕指定坐标执行长按操作(1秒)
  • 示例:
    GET /api/?command=long_click_at_500,800
    
  • 响应: "长按命令已发送: (500, 800)"

3.3 测试点击

  • 命令: test_click
  • 描述: 测试点击屏幕中心点
  • 示例:
    GET /api/?command=test_click
    
  • 响应: "测试点击命令已发送"

3.4 获取屏幕信息

  • 命令: screen_info
  • 描述: 获取屏幕分辨率信息
  • 示例:
    GET /api/?command=screen_info
    
  • 响应: "屏幕分辨率: 1080x2340"

4. 手势滑动命令

4.1 左滑

  • 命令: swipe_left
  • 描述: 从屏幕中心向左滑动
  • 示例:
    GET /api/?command=swipe_left
    
  • 响应: {"status": "success", "direction": "left"}

4.2 右滑

  • 命令: swipe_right
  • 描述: 从屏幕中心向右滑动
  • 示例:
    GET /api/?command=swipe_right
    
  • 响应: {"status": "success", "direction": "right"}

4.3 上滑

  • 命令: swipe_up
  • 描述: 从屏幕中心向上滑动
  • 示例:
    GET /api/?command=swipe_up
    
  • 响应: {"status": "success", "direction": "up"}

4.4 下滑

  • 命令: swipe_down
  • 描述: 从屏幕中心向下滑动
  • 示例:
    GET /api/?command=swipe_down
    
  • 响应: {"status": "success", "direction": "down"}

4.5 自定义滑动

  • 命令: swipe_at_[startX],[startY],[endX],[endY],[duration]
  • 描述: 从起点到终点执行自定义滑动
  • 参数:
    • startX: 起始X坐标
    • startY: 起始Y坐标
    • endX: 结束X坐标
    • endY: 结束Y坐标
    • duration: 持续时间(毫秒,可选,默认500ms)
  • 示例:
    GET /api/?command=swipe_at_500,800,200,800,1000
    
  • 响应: {"status": "success", "action": "swipe"}

5. 截图功能命令

5.1 拍摄截图

  • 命令: screenshot
  • 描述: 触发截图操作
  • 示例:
    GET /api/?command=screenshot
    
  • 响应: "截图处理中..."

5.2 获取截图结果(Base64)

  • 命令: get_screenshot_result
  • 描述: 获取上次截图的Base64编码数据
  • 示例:
    GET /api/?command=get_screenshot_result
    
  • 响应 (成功):
    {
      "status": "success",
      "type": "screenshot",
      "width": 1080,
      "height": 2340,
      "format": "PNG",
      "data_size": 102400,
      "data": "base64编码的图片数据",
      "timestamp": 1647859200000
    }
    
  • 响应 (失败):
    {
      "status": "error",
      "message": "没有可用的截图,请先执行截图命令",
      "timestamp": 1647859200000
    }
    

5.3 直接获取截图

  • 命令: get_screenshot_direct
  • 描述: 直接获取当前屏幕截图(压缩为WEBP格式)
  • 参数:
    • quality: 图片质量 0-100(可选,默认30)
  • 示例:
    GET /api/?command=get_screenshot_direct&quality=60
    
  • 响应 (成功):
    {
      "status": "success",
      "type": "screenshot",
      "width": 720,
      "height": 1560,
      "screen_width": 1080,
      "screen_height": 2340,
      "original_width": 1080,
      "original_height": 2340,
      "scale": 1.5,
      "format": "WEBP",
      "data_size": 51200,
      "data": "base64编码的图片数据",
      "timestamp": 1647859200000
    }
    

5.4 获取截图OCR结果

  • 命令: get_screenshot_ocr
  • 描述: 对当前截图进行OCR文字识别

请求参数

参数名 类型 必填 描述
command string 是 固定值:get_screenshot_ocr

请求示例

GET /api/?command=get_screenshot_ocr

响应格式

返回JSON格式的数据,包含截图OCR识别的结果。

响应参数

参数名 类型 描述
status string 状态值:"success"(成功)或 "failed"(失败)
type string 固定值:"screenshot_ocr"
data object/string 成功时:OCR识别结果对象;失败时:错误信息
timestamp long Unix时间戳(毫秒)

成功响应示例

{
  "status": "success",
  "type": "screenshot_ocr",
  "data": {
    "status": "success",
    "type": "screenshot_ocr",
    "data": {
      "success": true,
      "text": "识别出的文字内容...",
      "confidence": 88,
      "processingTime": "1655ms",
      "language": "eng+chi_sim",
      "details": {
        "blocks": 1,
        "paragraphs": 1,
        "lines": 7,
        "words": 55
      },
      "hocr": "<div class='ocr_page'...>...</div>",
      "tsv": "1\t1\t0\t0\t0\t0\t0\t0\t1200\t2000\t-1\t\n...",
      "box": null
    },
    "timestamp": 1773585652996
  },
  "timestamp": 1773585652996
}

失败响应示例

{
  "status": "failed",
  "type": "screenshot_ocr",
  "data": null,
  "timestamp": 1773585652996
}

OCR结果对象字段说明

字段名 类型 描述
success boolean OCR识别是否成功
text string 识别出的完整文字内容
confidence int 识别置信度(0-100)
processingTime string 处理耗时(如"1655ms")
language string 使用的OCR语言模型
details object 识别详情(块数、段落数、行数、词数)
hocr string hOCR格式的识别结果
tsv string TSV格式的识别结果
box object 文本框坐标信息(可能为null)

功能流程

  1. 调用takeScreenshotForOCR()方法截图
  2. 调用recognizeImageWithOCRResult()方法进行OCR识别
  3. 如果主方法失败,会尝试一次重试
  4. 返回识别结果或失败信息

注意事项

  • 需要Android 7.0+系统支持截图功能
  • OCR API服务器地址通过配置项OCR_API_BASE_URL设置
  • 默认使用eng+chi_sim(中英文)语言模型
  • 截图会压缩为JPEG格式(质量80%)后上传
  • OCR API超时时间为30秒
  • 失败时会在悬浮窗显示提示信息"❌ 图片文字识别失败"

5.5 设置截图最大尺寸

  • 命令: set_screenshot_max_size
  • 描述: 设置截图的最大宽度和高度
  • 参数:
    • width: 最大宽度
    • height: 最大高度
  • 示例:
    GET /api/?command=set_screenshot_max_size&width=800&height=1200
    
  • 响应:
    {
      "status": "success",
      "message": "设置成功"
    }
    

6. UI信息命令

6.1 获取UI节点信息

  • 命令: get_uinfo
  • 描述: 获取当前窗口的UI节点信息
  • 示例:
    GET /api/?command=get_uinfo
    
  • 响应: "UI信息已获取,共 42 个节点"

6.2 获取UI信息结果

  • 命令: get_uiinfo_result
  • 描述: 获取上次获取的UI节点信息详情
  • 示例:
    GET /api/?command=get_uiinfo_result
    
  • 响应:
    {
      "status": "success",
      "type": "ui_info",
      "timestamp": 1647859200000,
      "data": {
        "packageName": "com.android.settings",
        "className": "android.widget.FrameLayout",
        "nodes": [...]
      }
    }
    

6.3 获取布局信息

  • 命令: dump_layout
  • 描述: 获取当前窗口的布局信息(文本格式)
  • 示例:
    GET /api/?command=dump_layout
    
  • 响应: "布局信息已获取"

6.4 获取布局信息结果

  • 命令: get_layout_result
  • 描述: 获取上次获取的布局信息详情
  • 示例:
    GET /api/?command=get_layout_result
    
  • 响应:
    {
      "status": "success",
      "type": "layout_info",
      "timestamp": 1647859200000,
      "data": "布局信息文本内容..."
    }
    

7. 语音API命令

7.1 语音识别

  • 命令: speech_recognize
  • 描述: 对上传的音频文件进行语音识别
  • 请求方式: POST
  • 参数:
    • audio: base64编码的WAV音频数据(必填)
    • language: 语言代码(可选,默认zh-CN)
      • zh-CN - 中文
      • en-US - 英文
      • ja-JP - 日语
      • ko-KR - 韩语
  • 示例 (POST):
    POST /api/
    Content-Type: multipart/form-data
    
    command=speech_recognize&audio=[base64音频数据]&language=zh-CN
    
  • 响应 (成功):
    {
      "status": "success",
      "message": "识别出的文字内容",
      "language": "zh-CN",
      "timestamp": 1647859200000
    }
    
  • 响应 (失败):
    {
      "status": "error",
      "message": "语音识别失败原因",
      "timestamp": 1647859200000
    }
    

7.2 语音合成

  • 命令: speech_synthesize
  • 描述: 将文本合成为语音
  • 参数:
    • text: 要合成的文本(必填)
    • language: 语言代码(可选,默认zh-CN)
    • voice: 语音类型(可选,默认default)
    • speed: 语速 0.5-2.0(可选,默认1.0)
  • 示例:
    GET /api/?command=speech_synthesize&text=你好世界&language=zh-CN&speed=1.0
    
  • 响应 (成功):
    {
      "status": "success",
      "audio": "base64编码的WAV音频数据",
      "text": "你好世界",
      "language": "zh-CN",
      "voice": "default",
      "speed": 1.0
    }
    
  • 响应 (失败):
    {
      "error": "语音合成失败原因"
    }
    

8. 配置管理命令

8.1 设置配置项

  • 命令: set_config
  • 描述: 设置指定的配置项
  • 参数:
    • key: 配置键名(必填)
    • value: 配置值(必填)
  • 支持的配置键:
    • IBBOT_AGENT_BASE_URL - iBBot服务器地址
    • dtnsbot_secret_key - API认证密钥
    • OCR_API_BASE_URL - OCR服务器地址
    • system_prompt - AI角色设定提示语
    • floating_button_command - 浮窗按钮指令
    • floating_button_mode - 浮窗按钮模式
  • 示例:
    GET /api/?command=set_config&key=IBBOT_AGENT_BASE_URL&value=http://192.168.1.100:8080
    
  • 响应:
    {
      "status": "success",
      "message": "配置已更新"
    }
    

8.2 获取配置项

  • 命令: get_config
  • 描述: 获取指定的配置项或所有配置
  • 参数:
    • key: 配置键名(可选,不传则获取所有)
  • 示例 (获取单个):
    GET /api/?command=get_config&key=IBBOT_AGENT_BASE_URL
    
  • 响应:
    {
      "status": "success",
      "key": "IBBOT_AGENT_BASE_URL",
      "value": "http://192.168.1.100:8080"
    }
    
  • 示例 (获取所有):
    GET /api/?command=get_config
    
  • 响应:
    {
      "status": "success",
      "config": {
        "IBBOT_AGENT_BASE_URL": "http://192.168.1.100:8080",
        "dtnsbot_secret_key": "xxxxxx",
        "system_prompt": "你是一个专业助手"
      }
    }
    

8.3 重置配置

  • 命令: reset_config
  • 描述: 重置所有配置为默认值
  • 示例:
    GET /api/?command=reset_config
    
  • 响应:
    {
      "status": "success",
      "message": "配置已重置为默认值"
    }
    

8.4 设置iBBot地址

  • 命令: set_ibbot_url
  • 描述: 快捷设置iBBot服务器地址
  • 参数:
    • url: 服务器地址(必填)
  • 示例:
    GET /api/?command=set_ibbot_url&url=http://192.168.1.100:8080
    
  • 响应:
    {
      "status": "success",
      "message": "iBBot地址已更新",
      "url": "http://192.168.1.100:8080"
    }
    

8.5 设置密钥

  • 命令: set_secret_key
  • 描述: 快捷设置API密钥
  • 参数:
    • key: 密钥值(必填)
  • 示例:
    GET /api/?command=set_secret_key&key=my_secret_key_123
    
  • 响应:
    {
      "status": "success",
      "message": "密钥已更新",
      "key": "my_se..."
    }
    

8.6 设置AI角色

  • 命令: set_system_prompt
  • 描述: 设置AI角色提示语
  • 参数:
    • prompt: 角色提示语(必填)
  • 示例:
    GET /api/?command=set_system_prompt&prompt=你是一个专业助手,请用简洁语言回答
    
  • 响应:
    {
      "status": "success",
      "message": "AI角色已设置",
      "prompt": "你是一个专业助手..."
    }
    

8.7 获取AI角色

  • 命令: get_system_prompt
  • 描述: 获取当前AI角色提示语
  • 示例:
    GET /api/?command=get_system_prompt
    
  • 响应:
    {
      "status": "success",
      "prompt": "你是一个专业助手..."
    }
    

8.8 配置帮助

  • 命令: config_help
  • 描述: 获取配置管理帮助信息
  • 示例:
    GET /api/?command=config_help
    
  • 响应: 文本形式的帮助信息

9. 收藏悬浮窗命令

9.1 显示收藏悬浮窗

  • 命令: 显示收藏
  • 描述: 显示收藏悬浮窗按钮
  • 示例:
    GET /api/?command=显示收藏
    
  • 响应: "收藏悬浮窗已显示"

9.2 隐藏收藏悬浮窗

  • 命令: 隐藏收藏
  • 描述: 隐藏收藏悬浮窗按钮
  • 示例:
    GET /api/?command=隐藏收藏
    
  • 响应: "收藏悬浮窗已隐藏"

9.3 切换收藏悬浮窗

  • 命令: 切换收藏
  • 描述: 切换收藏悬浮窗的显示状态
  • 示例:
    GET /api/?command=切换收藏
    
  • 响应: "收藏悬浮窗已切换"

9.4 设为机灵模式

  • 命令: set_smart_mode
  • 描述: 将收藏按钮设置为机灵模式
  • 示例:
    GET /api/?command=set_smart_mode
    
  • 响应:
    {
      "status": "success",
      "mode": "机灵"
    }
    

9.5 设为收藏模式

  • 命令: set_collection_mode
  • 描述: 将收藏按钮设置为收藏模式
  • 示例:
    GET /api/?command=set_collection_mode
    
  • 响应:
    {
      "status": "success",
      "mode": "收藏"
    }
    

9.6 切换模式

  • 命令: toggle_collection_mode 或 切换模式
  • 描述: 切换收藏按钮的工作模式
  • 示例:
    GET /api/?command=toggle_collection_mode
    
  • 响应:
    {
      "status": "success",
      "mode": "机灵"
    }
    

9.7 获取当前模式

  • 命令: get_collection_mode
  • 描述: 获取收藏按钮的当前模式
  • 示例:
    GET /api/?command=get_collection_mode
    
  • 响应:
    {
      "status": "success",
      "mode": "机灵"
    }
    

9.8 设置浮窗指令

  • 命令: set_floating_command
  • 描述: 设置浮窗按钮点击执行的指令
  • 参数:
    • value: 指令内容
  • 示例:
    GET /api/?command=set_floating_command&value=图片机灵
    
  • 响应:
    {
      "status": "success",
      "message": "浮窗指令已设置为: 图片机灵",
      "command": "图片机灵"
    }
    

9.9 获取浮窗指令

  • 命令: get_floating_command
  • 描述: 获取当前浮窗按钮指令
  • 示例:
    GET /api/?command=get_floating_command
    
  • 响应:
    {
      "status": "success",
      "command": "图片机灵"
    }
    

10. 识图机灵命令

10.1 识图机灵

  • 命令: image_smart 或 识图机灵
  • 描述: 截图并进行OCR识别,然后生成智能回复
  • 参数:
    • lang: OCR语言(可选,默认eng+chi_sim)
      • eng+chi_sim - 中英文
      • chi_sim - 简体中文
      • eng - 英文
      • jpn - 日文
      • kor - 韩文
  • 示例:
    GET /api/?command=识图机灵&lang=eng+chi_sim
    
  • 响应 (立即):
    {
      "status": "accepted",
      "message": "识图机灵任务已接受",
      "task_id": "img_smart_1647859200000",
      "timestamp": 1647859200000
    }
    

10.2 图片机灵

  • 命令: 图片机灵
  • 描述: 同识图机灵
  • 示例:
    GET /api/?command=图片机灵
    
  • 响应: 同上

10.3 万能机灵

  • 命令: 万能机灵
  • 描述: 跟图片机灵一样
  • 示例:
    GET /api/?command=万能机灵
    
  • 响应: 同上

10.3.2 全屏机灵

  • 命令: 全屏机灵
  • 描述: 滚动屏幕截图OCR识别并进行AI回复(即图片机灵只能截屏当前屏幕、全屏机灵可以滚动截屏)
  • 示例:
    GET /api/?command=全屏机灵
    
  • 响应: 同上

10.3.2.1 全屏机灵(参数版本)

命令格式
/api/?command=full_smart_{滚动高度},{等待时间}
参数说明
参数 类型 说明 默认值
滚动高度 整数 每次滚动距离(像素) 屏幕高度的70%
等待时间 整数 滚动后等待时间(毫秒) 5000
使用示例
示例 说明
full_smart 使用默认参数
full_smart_1000,3000 滚动1000px,等待3000ms
full_smart_500,2000 滚动500px,等待2000ms
full_smart_800,1000 滚动800px,等待1000ms
支持的别名命令
  • 全屏机灵
  • 滚动机灵
  • 长文机灵
  • full_screen_smart
  • scroll_smart
响应示例
{
    "status": "accepted",
    "message": "全屏机灵任务已接受,滚动高度: 1000px,等待时间: 3000ms",
    "task_id": "full_smart_1734567890123"
}
完整请求示例
http://192.168.1.49:58082/api/?command=full_smart_1000,3000
注意事项
  1. 任务异步执行,完成后结果自动复制到剪贴板
  2. 滚动高度建议范围:100-2000px
  3. 等待时间建议范围:500-10000ms
  4. 执行时会显示进度悬浮窗

10.4 获取任务状态

  • 命令: get_task_status
  • 描述: 获取异步任务的处理状态
  • 参数:
    • task_id: 任务ID
  • 示例:
    GET /api/?command=get_task_status&task_id=img_smart_1647859200000
    
  • 响应:
    {
      "status": "completed",
      "task_id": "img_smart_1647859200000",
      "message": "任务处理完成",
      "timestamp": 1647859200000
    }
    

11. GPS定位命令

11.1 获取当前位置

  • 命令: get_gps
  • 描述: 获取当前GPS位置信息
  • 示例:
    GET /api/?command=get_gps
    
  • 响应:
    {
      "latitude": 31.2304,
      "longitude": 121.4737,
      "accuracy": 10.5,
      "time": 1647859200000,
      "provider": "gps",
      "address": "上海市浦东新区..."
    }
    

11.2 开始定位

  • 命令: start_gps
  • 描述: 开始持续定位
  • 示例:
    GET /api/?command=start_gps
    
  • 响应:
    {
      "status": "started",
      "message": "位置服务已启动,正在获取位置..."
    }
    

11.3 停止定位

  • 命令: stop_gps
  • 描述: 停止定位服务
  • 示例:
    GET /api/?command=stop_gps
    
  • 响应:
    {
      "status": "stopped",
      "message": "位置服务已停止"
    }
    

11.4 获取定位状态

  • 命令: gps_status
  • 描述: 获取当前定位服务状态
  • 示例:
    GET /api/?command=gps_status
    
  • 响应:
    {
      "status": "running",
      "location_service": "已开启",
      "formatted_location": "纬度: 31.2304, 经度: 121.4737",
      "location_data": {...}
    }
    

12. 文本操作命令

12.1 输入文本

  • 命令: input_[文本]
  • 描述: 在当前焦点输入框中输入文本
  • 参数: 文本内容在命令路径中
  • 示例:
    GET /api/?command=input_hello%20world
    
  • 响应: "正在输入: hello world"

12.2 点击文本

  • 命令: click_[文本]
  • 描述: 点击包含指定文本的UI元素
  • 参数: 文本内容在命令路径中
  • 示例:
    GET /api/?command=click_确定
    
  • 响应: "正在点击: 确定"

12.3 复制到剪贴板

  • 命令: paste_[文本]
  • 描述: 将文本复制到剪贴板
  • 参数: 文本内容在命令路径中
  • 示例:
    GET /api/?command=paste_要复制的文本
    
  • 响应: "正在粘贴: 要复制的文本"

12.4 获取剪贴板内容

  • 命令: get_clipboard_text
  • 描述: 获取剪贴板中的文本内容
  • 示例:
    GET /api/?command=get_clipboard_text
    
  • 响应:
    {
      "status": "success",
      "type": "screenshot_ocr",
      "data": "剪贴板中的文本内容",
      "timestamp": 1647859200000
    }
    

12.2 输入法功能

输入法发送ime_send 命令支持以下多种格式:

1. 下划线格式(与 click_at 风格一致)

# 发送文本
/api/?command=ime_send_你好世界

# 清空后发送
/api/?command=ime_send_&clear=true你好世界

# 发送并按回车
/api/?command=ime_send_&enter=true你好世界

# 逐字输入(文本_延迟)
/api/?command=ime_send_delayed_你好世界_100

2. 空格分隔格式

/api/?command=ime_send 你好世界

/api/?command=ime_send_delayed 你好世界 100

3. 参数格式

/api/?command=ime_send&text=你好世界&clear=true&enter=true

/api/?command=ime_send_delayed&text=你好世界&delay=100

4. 中文命令格式

/api/?command=输入文本 你好世界

/api/?command=逐字输入 你好世界 100

其他输入法命令使用方法:

5. 获取当前输入框内容

curl "http://设备IP:58082/api/?command=ime_get_text"

6. 清空输入框

curl "http://设备IP:58082/api/?command=ime_clear"

7. 逐字输入(模拟真人)

curl "http://设备IP:58082/api/?command=ime_send_delayed&text=你好世界&delay=100"


13. 命令执行器

13.1 执行命令

  • 命令: exec
  • 描述: 在设备上执行系统命令(需要Node.js服务)
  • 参数:
    • cmd: 要执行的命令
    • timeout: 超时时间(毫秒,可选)
    • cwd: 工作目录(可选)
  • 示例:
    GET /api/?command=exec&cmd=ls -la&cwd=/sdcard
    
  • 响应:
    {
      "ret": true,
      "msg": "success",
      "data": {
        "command": "ls -la",
        "exitCode": 0,
        "stdout": "文件列表...",
        "stderr": "",
        "executionTime": 123,
        "cwd": "/sdcard"
      }
    }
    

13.2 异步执行命令

  • 命令: exec_async
  • 描述: 异步执行系统命令
  • 参数:
    • cmd: 要执行的命令
    • timeout: 超时时间(可选)
    • cwd: 工作目录(可选)
  • 示例:
    GET /api/?command=exec_async&cmd=ping 8.8.8.8
    
  • 响应:
    {
      "status": "accepted",
      "message": "命令已接受,正在异步执行",
      "task_id": "exec_1647859200000",
      "command": "ping 8.8.8.8",
      "cwd": "默认目录",
      "timestamp": 1647859200000
    }
    

13.3 执行系统命令(简化版)

  • 命令: system 或 sh
  • 描述: 执行系统命令的简化版本
  • 参数:
    • cmd: 要执行的命令
    • cwd: 工作目录(可选)
  • 示例:
    GET /api/?command=system&cmd=ls&cwd=/sdcard
    
  • 响应:
    {
      "status": "success",
      "exitCode": 0,
      "stdout": "文件列表...",
      "stderr": "",
      "cwd": "/sdcard",
      "timestamp": 1647859200000
    }
    

13.4 检查执行服务状态

  • 命令: check_exec_service
  • 描述: 检查命令执行服务是否正常运行
  • 示例:
    GET /api/?command=check_exec_service
    
  • 响应:
    {
      "status": "online",
      "message": "执行服务正常运行",
      "port": 58083,
      "timestamp": 1647859200000
    }
    

14. 辅助命令

14.1 帮助信息

  • 命令: help
  • 描述: 获取所有可用命令的帮助信息
  • 示例:
    GET /api/?command=help
    
  • 响应: 文本形式的帮助信息

14.2 iBBot处理

  • 命令: ibbot_process
  • 描述: 调用iBBot处理API处理命令
  • 参数:
    • command: 要处理的命令
  • 示例:
    GET /api/?command=ibbot_process&command=今天天气怎么样
    
  • 响应:
    {
      "status": "success",
      "message": "已复制到剪贴板",
      "result": "iBBot处理结果"
    }
    

14.3 iBBot智能回复

  • 命令: ibbot_smart_reply
  • 描述: 调用iBBot智能回复API
  • 参数:
    • context: 上下文信息(可选)
  • 示例:
    GET /api/?command=ibbot_smart_reply&context=用户询问天气
    
  • 响应:
    {
      "status": "success",
      "message": "已复制到剪贴板",
      "reply": "智能回复内容"
    }
    

14.4 收藏文章

  • 命令: 收藏
  • 描述: 收藏当前文章或内容
  • 示例:
    GET /api/?command=收藏
    
  • 响应: "文章收藏请求已发送"

14.5 智能回复

  • 命令: 机灵 或 智能回复
  • 描述: 基于当前界面生成智能回复
  • 示例:
    GET /api/?command=机灵
    
  • 响应: "正在生成智能回复..."

15. 错误码说明

15.1 HTTP状态码

状态码 说明
200 请求成功
400 请求参数错误
404 命令不存在
500 服务器内部错误

15.2 通用错误响应格式

{
  "status": "error",
  "message": "错误描述信息",
  "timestamp": 1647859200000
}

15.3 常见错误消息

错误消息 说明
"没有可用的截图,请先执行截图命令" 截图缓存为空
"图片压缩失败" 图片处理失败
"坐标格式错误" 坐标参数格式不正确
"截图功能需要 Android 7.0+" 系统版本不支持
"缺少音频数据参数: audio" 语音识别缺少音频数据
"缺少文本参数: text" 语音合成缺少文本
"配置项不存在: [key]" 配置键不存在
"命令执行失败: [原因]" 系统命令执行失败

16. 文件上传下载

1. 文件上传

方式:Base64 上传

GET /api/?command=file_upload&filename=test.txt&file_data=[base64编码文件]&path=/storage/emulated/0/Download/

参数说明

参数 必填 说明
command 是 固定值: file_upload
filename 否 文件名,不填则自动生成
file_data 是* Base64编码的文件数据
path 否 目标路径,默认: /storage/emulated/0/Download/

*注:使用Base64方式时必须提供file_data;使用multipart方式时需通过表单上传文件

成功响应示例

{
  "status": "success",
  "message": "文件上传成功",
  "file_name": "test.txt",
  "file_path": "/storage/emulated/0/Download/test.txt",
  "file_size": 1024,
  "timestamp": 1678901234567
}

失败响应示例

{
  "status": "error",
  "message": "文件上传失败: 磁盘空间不足",
  "timestamp": 1678901234567
}

2. 文件下载

GET /api/?command=file_download&path=/storage/emulated/0/Download/test.txt

参数说明

参数 必填 说明
command 是 固定值: file_download
path 是 要下载的文件完整路径

响应

  • 成功: 返回文件二进制流,Content-Type: application/octet-stream
  • 失败: 返回JSON格式错误信息

失败响应示例

{
  "status": "error",
  "message": "文件不存在或无法读取",
  "timestamp": 1678901234567
}

3. 文件列表

GET /api/?command=file_list&path=/storage/emulated/0/Download/&recursive=false

参数说明

参数 必填 说明
command 是 固定值: file_list
path 否 目录路径,默认: /storage/emulated/0/
recursive 否 是否递归列出,默认: false

成功响应示例

{
  "status": "success",
  "path": "/storage/emulated/0/Download/",
  "parent_path": "/storage/emulated/0",
  "file_count": 5,
  "directory_count": 2,
  "files": [
    {
      "name": "文档",
      "path": "/storage/emulated/0/Download/文档",
      "is_directory": true,
      "is_file": false,
      "last_modified": 1678901234000,
      "can_read": true,
      "can_write": true,
      "hidden": false,
      "file_count": 3
    },
    {
      "name": "test.txt",
      "path": "/storage/emulated/0/Download/test.txt",
      "is_directory": false,
      "is_file": true,
      "size": 1024,
      "size_formatted": "1.00 KB",
      "extension": "txt",
      "last_modified": 1678901234000,
      "can_read": true,
      "can_write": true,
      "hidden": false
    }
  ],
  "storage": {
    "total_space": 12884901888,
    "free_space": 5242880000,
    "usable_space": 5242880000,
    "total_formatted": "12.00 GB",
    "free_formatted": "4.88 GB",
    "usable_formatted": "4.88 GB"
  },
  "timestamp": 1678901234567
}

失败响应示例

{
  "status": "error",
  "message": "路径不存在或不是目录: /invalid/path",
  "timestamp": 1678901234567
}

17 poplang脚本与编程

POP 语言与 JavaScript 执行 API 文档

1. 执行 POP 脚本 pop_eval

同步执行一段 POP 语言脚本。POP 脚本可以是多行命令,也可以是一个操作数组。

命令别名: pop_eval、执行pop

参数:

参数名 类型 必填 说明
script string 是 POP 脚本内容(支持多行,需 URL 编码)
code string 备选 与 script 等价,二选一即可

示例请求:

# 简单 Toast 测试
curl "http://192.168.1.100:58082/api/?command=pop_eval&script=show-toast%20msg"

**示例响应**:

```json
{"status": "success", "message": "Toast已触发"}

2. 从文件执行 POP 脚本 pop_run

从设备内部存储读取一个 POP 脚本文件并执行。

参数:

参数名 类型 必填 说明
file string 是 脚本文件的绝对路径(例如 /sdcard/script.pop)

示例请求:

curl "http://192.168.1.100:58082/api/?command=pop_run&file=/sdcard/test.pop"

示例响应:

{
  "ret": true,
  "msg": "success",
  "results": [...]
}

3. 测试 Toast 命令

test_toast

快速测试 POP 的 show-toast 指令,使用默认方式显示一条消息。

参数:

参数名 类型 必填 说明
msg string 否 要显示的消息,默认 "Hello from POP"

示例请求:

curl "http://192.168.1.100:58082/api/?command=test_toast&msg=测试消息"

示例响应:

{
  "status": "success",
  "message": "Toast已触发"
}

该命令会调用 popEngine.executeScript 自动生成 ['show-toast','','','消息'] 数组并执行。


4. 执行任意 JavaScript 代码

js_eval / eval / jseval

在 WebView 中直接执行 JavaScript 代码,并返回执行结果。支持调用 PopAndroid 对象(如 PopAndroid.showToast)进行交互。

命令别名: js_eval、eval、jseval

参数:

参数名 类型 必填 说明
code string 是 要执行的 JavaScript 代码
script string 备选 与 code 等价

示例请求:

# 简单计算
curl "http://192.168.1.100:58082/api/?command=js_eval&code=1%2B2"

# 获取当前页面标题(如果 WebView 加载了页面)
curl "http://192.168.1.100:58082/api/?command=js_eval&code=document.title"

# 调用 Android Toast
curl "http://192.168.1.100:58082/api/?command=js_eval&code=PopAndroid.showToast('Hello%20from%20JS')"

示例响应:

{
  "result": 3
}

对于非 JSON 返回值,会自动包装为 {"result": 值};如果返回的是 JSON 对象或数组,则原样返回。


注意事项

  1. POP 脚本语法:POP 脚本基于 JavaScript 语法,支持 op(context, opcode, ...) 调用预定义的操作码,也支持 ['opcode', 参数...] 数组形式。具体操作码可参考 pop_runtime2.js 中的 binderAddOpcode 定义。

  2. 内置操作码扩展:该服务额外注册了 show-toast 和 dtnsbot 操作码:

    • show-toast: 显示 Toast 消息,例:show-toast msg
    • dtnsbot: 调用原有控制命令,例:dtnsbot click_at_500,800
  3. URL 编码:当脚本中包含特殊字符(如空格、引号、换行)时,必须进行 URL 编码。建议使用 POST 方式传递长脚本。

  4. 执行超时:POP 脚本和 JS 代码默认执行超时时间为 30 秒,超时后会返回 {"error": "执行超时"}。

  5. 安全限制:

    • POP 引擎初始化时 safeFlag = false,禁用了 Node.js 的 vm 模块和文件操作,但基本运算和自定义操作码可用。
    • JavaScript 引擎运行在独立的 WebView 中,无法直接访问文件系统,但可以通过 PopAndroid 接口调用部分服务功能。
  6. 响应结构:pop_eval 返回的是 opbatch 执行结果,通常包含 ret, msg, results 字段;js_eval 返回的是 JS 代码的直接返回值。


扩展建议

  • 结合 dtnsbot 操作码,可以在 POP 脚本中无缝调用所有无障碍命令(如点击、滑动、打开应用等)。
  • 利用 js_eval 可动态计算表达式或操作 WebView 内加载的页面内容。
  • 两种执行方式互补:POP 语言适合编写结构化自动化流程,JS 适合快速调试或简单计算。

poplang示例(调用dtnsbot命令)

根据您的要求和 POP 语言的实际语法,dtnsbot 操作码支持直接传递参数字符串(无需用 set 定义变量)。以下是通过 pop_eval 调用 dtnsbot 的示例,均使用简洁的 dtnsbot 命令 参数 格式。

基本示例

# 点击坐标
dtnsbot click_at_500,800

# 返回主页
dtnsbot home

# 截图
dtnsbot screenshot

# 打开设置
dtnsbot open_settings

# 滑动屏幕(起点、终点、持续时间)
dtnsbot swipe_at_100,800,100,200,300

# 输入文本
dtnsbot input_你好世界

# 获取GPS位置
dtnsbot get_gps

使用变量和循环

# 定义循环变量
set i 0
set max 10
set flag true

# 循环点击不同坐标
pop.func.define click_loop
    set x 100
    set y 100
    + x i x
    + y i y
    set coord **500,800
    dtnsbot click_at coord
    + i 1 i
    < i max flag
pop.func.end

pop.do.while flag click_loop

结合条件判断与 OCR 识图

# 截图并识别文字
dtnsbot screenshot
set screenshot_ok true
pop.ifelse screenshot_ok do_ocr skip_ocr

pop.func.define do_ocr
    dtnsbot 识图机灵
pop.func.end

pop.func.define skip_ocr
    dtnsbot show-toast 未截图成功
pop.func.end

# 注意:识图机灵是异步命令,实际执行时可能需等待

17.2 获取webview日志

HTTP API 文档:获取 WebView 日志

基本信息

属性 值
命令 get_today_log / get_log
方法 GET 或 POST
路径 /api/
描述 获取当天 WebView 控制台日志文件的内容(用于调试 POP 或 JS 脚本)

参数

参数名 类型 必填 说明
command string 是 固定值 get_today_log 或 get_log
date string 否 指定日期,格式 YYYY-MM-DD(例如 2025-01-15)。不提供时返回当天日志。

请求示例

# 获取今天的日志
curl "http://192.168.1.100:58082/api/?command=get_today_log"

# 获取指定日期的日志(扩展支持)
curl "http://192.168.1.100:58082/api/?command=get_log&date=2025-01-14"

响应格式

成功响应(日志文件存在且可读)

{
  "status": "success",
  "date": "2025-01-15",
  "file_path": "/sdcard/dtnsbot/logs/2025-01-15.log",
  "file_size": 12345,
  "content": "[10:47:23.205] [LOG] oplines:[[\"set\",\"msg\",\"测试消息\"],[\"show-toast\",\"msg\"]] (:904)\n[10:47:23.205] [ERROR] SyntaxError: Unexpected token '测', \"测试消息\" is not valid JSON (:953)",
  "timestamp": 1705312345678
}
字段 类型 说明
status string 固定为 "success"
date string 日志日期
file_path string 日志文件的绝对路径
file_size number 文件大小(字节)
content string 完整日志内容
timestamp number 服务器响应时间戳(毫秒)

错误响应

1. 日志文件不存在
{
  "status": "error",
  "message": "日志文件不存在或不可读",
  "date": "2025-01-15",
  "expected_path": "/sdcard/dtnsbot/logs/2025-01-15.log",
  "hint": "请确保已执行过脚本产生了日志,且应用有读取权限"
}
2. 读取失败(权限问题)
{
  "status": "error",
  "message": "读取日志文件失败: java.io.FileNotFoundException: /sdcard/dtnsbot/logs/2025-01-15.log (Permission denied)",
  "date": "2025-01-15",
  "file_path": "/sdcard/dtnsbot/logs/2025-01-15.log"
}
3. 日期格式错误(如果手动指定了 date)
{
  "status": "error",
  "message": "日期格式错误,请使用 YYYY-MM-DD 格式"
}

注意事项

  1. 日志文件位置

    • 优先写入公共目录:/sdcard/dtnsbot/logs/
    • 若无存储权限,则回退到应用私有目录:/storage/emulated/0/Android/data/com.example.dtnsbot/files/../dtnsbot/logs/
    • 实际路径以响应中的 file_path 为准。
  2. 权限要求

    • 访问公共目录需要 READ_EXTERNAL_STORAGE 权限(Android 10 及以下)或 MANAGE_EXTERNAL_STORAGE(Android 11+)。若无权限,请引导用户到设置中授予「存储权限」。
    • 应用私有目录不需要额外权限。
  3. 日志轮转

    • 每天生成一个独立的日志文件,文件名格式为 YYYY-MM-DD.log。
    • 当日志写入时自动创建,跨日时关闭旧文件并创建新文件。
  4. 内容安全

    • 日志可能包含敏感信息(如脚本内容、屏幕坐标等),仅在可信网络环境下调用该接口。

扩展用法

配合 dtnsbot_poplang.html 工具,可以在 JavaScript 模式下快速查看日志:

// 在 JS 模式编辑器中执行
fetch('/api/?command=get_today_log')
  .then(res => res.json())
  .then(data => {
    if (data.status === 'success') {
      console.log(data.content);
    } else {
      console.error('获取日志失败:', data.message);
    }
  });

错误码说明

HTTP状态码 说明
200 成功
400 请求参数错误
404 文件/目录不存在
500 服务器内部错误

18. dbot-ble 平衡车控制命令

本章节描述通过 dtnsbot 安卓设备远程控制 FOTBOT 平衡车(BLE 设备,能力代号 dbot-ble)的接口。

  • 传输方式:BLE GATT(安卓端主动扫描并连接平衡车)
  • 远程调用方式:HTTP API(/api/?command=ble_xxx)或 WebRTC RPC(call('/command', {command:'ble_xxx'}))
  • 无需额外网关:安卓手机本身即作为 BLE 网关
  • 兼容性:与 BleCommandClient(ESP32-Dtnsbot)互不干扰,按广播名区分设备

18.0 网页控制面板

  • 访问地址:http://[设备IP]:58082/dbot.html 或 http://dtnsbot.{deviceid}.html.dtns.top/dbot.html
  • 描述:360° 摇杆 + 速度/转向滑块 + 快捷按钮 + 状态面板 + 日志
  • 实时视频(新增):页面顶部 300×400 视频区,object-fit:contain 不裁切;按流比例自适应高度
  • 双向语音(新增):
    • 🎤 我的麦克风:浏览器麦克风 → 手机扬声器(关闭时 replaceTrack(null) 真正停采集)
    • 🔊 对方麦克风:手机麦克风 → 浏览器(对应 webrtc_video_audio)
    • 🔇 全部静音 / 🔊 恢复声音:两端一键同开/同关
  • 视频按钮:📹 开启视频 / ⏹️ 关闭视频 / 🔄 切换前后
  • 房间号:页面从域名 dtnsbot.{clientId}.html.dtns.top 解析 clientId 作为 WebRTC roomid

18.1 平衡车状态

  • 命令: ble_status(别名:平衡车状态)
  • 描述: 查询平衡车连接状态和遥测数据
  • 示例:
    GET /api/?command=ble_status
    
  • 响应:
    {
      "connected": true,
      "linkHealthy": true,
      "connecting": false,
      "name": "BLE_FOTBOT",
      "addr": "ec:c5:7f:f6:86:ff",
      "connectedForMs": 12345,
      "rxAgeMs": 120,
      "power": 35,
      "steerPower": 100,
      "angleDeadZone": 35,
      "mirrorY": false,
      "mirrorX": false,
      "direction": { "y": 127, "x": 127 },
      "moving": false,
      "leaseLeftMs": 0,
      "stopLockLeftMs": 0,
      "leaseMs": 800,
      "stopHoldMs": 800,
      "tickMs": 100,
      "linkTimeoutMs": 30000,
      "tx": 100,
      "rx": 50,
      "battery": "电量 97%",
      "speed": "速度 0.00",
      "temp": "温度 42.2°C",
      "voltage": "电池电压 55.00V",
      "mileage": "里程 0.021",
      "bar": "摇杆电压 2.14V",
      "angle": "俯仰角 11.55°",
      "init": "限速8 运动105 尾灯3(蓝) 灵敏127 大灯开 静止角42 定位127",
      "firmware": "固件版本 181",
      "ageMs": {
        "init": 1200,
        "firmware": 5000,
        "voltage": null,
        "charge": 800,
        "speed": 100
      },
      "lastError": null,
      "lastRx": { "op": "0x22", "text": "电量 97%" }
    }
    

18.2 平衡车日志

  • 命令: ble_log
  • 描述: 查询最近的 BLE 日志(最多 200 条,先进先出)
  • 示例:
    GET /api/?command=ble_log
    
  • 响应:
    {
      "log": [
        "14:23:01  已连接。写特征 6eb675ab-8bd1-1b9a-7444-621e52ec6423",
        "14:23:01  <<< 0x06 固件版本 181",
        "14:23:02  <<< 0x22 电量 97%",
        "14:23:05  >> 方向 Y=67 X=127",
        "14:23:06  >> 回中"
      ]
    }
    

18.3 启动/停止 BLE 连接

  • 命令: ble_start / ble_stop_ble
  • 描述: 启动或停止 BLE 连接(一般无需手动调用,服务启动时已自动 start)
  • 示例:
    GET /api/?command=ble_start
    GET /api/?command=ble_stop_ble
    
  • 响应:
    { "ok": true, "message": "ble started" }
    { "ok": true, "message": "ble stopped" }
    

18.4 方向控制

  • 命令: ble_fwd / ble_back / ble_left / ble_right
  • 描述: 前进 / 后退 / 左转 / 右转,每条指令带租约,到点自动回中
  • 参数:
    • ms: 运动持续时间,60..5000(可选,默认 600)
  • 示例:
    GET /api/?command=ble_fwd&ms=600
    GET /api/?command=ble_back&ms=600
    GET /api/?command=ble_left&ms=600
    GET /api/?command=ble_right&ms=600
    
  • 响应:
    {
      "ok": true,
      "cmd": "fwd",
      "y": 67,
      "x": 127,
      "ms": 600,
      "leaseUntil": 1712345678901,
      "changed": true,
      "status": { ...ble_status 完整对象... }
    }
    
  • 注意: 要持续运动必须周期性重发(推荐 250ms 一次),松手后必须主动发 ble_stop

18.5 急停

  • 命令: ble_stop(别名:ble_stop_car)
  • 描述: 立即把方向回中并锁定 stopHoldMs(默认 800ms),锁定期间忽略任何方向指令
  • 示例:
    GET /api/?command=ble_stop
    
  • 响应:
    {
      "ok": true,
      "y": 127,
      "x": 127,
      "stopped": true,
      "stopLockUntil": 1712345679701,
      "status": { ...ble_status 完整对象... }
    }
    

18.6 原始摇杆

  • 命令: ble_move
  • 描述: 直接指定 Y/X 轴值
  • 参数:
    • y: 前后轴 0..254,127 中位(必填)
    • x: 左右轴 0..254,127 中位(必填,有 ±100 死区)
    • ms: 租约毫秒(可选,默认 600)
  • 示例:
    GET /api/?command=ble_move&y=100&x=127&ms=500
    
  • 注意: X ∈ [30, 224] 时车体忽略 X 的转向语义,转向时必须把 X 推到接近 0 或接近 254

18.7 极坐标摇杆

  • 命令: ble_vector

  • 描述: 极坐标映射到 Y/X,内部已做 X 轴死区强制修正

  • 参数:

    • r: 力度 0..1(必填)
    • t: 角度 0..360,0=上(前进),顺时针(必填)
    • ms: 租约毫秒(可选,默认 600)
  • 示例:

    GET /api/?command=ble_vector&r=0.8&t=45&ms=500
    
  • 方向映射表:

    θ 行为 Y X
    0° 前进 0 127
    45° 前进+右转 37 227
    90° 右转 127 254
    135° 后退+右转 217 227
    180° 后退 254 127
    225° 后退+左转 217 27
    270° 左转 127 0
    315° 前进+左转 37 27

18.8 设置 Y 轴运动幅度

  • 命令: ble_power
  • 参数:
    • pct: 1..100(必填)
  • 示例:
    GET /api/?command=ble_power&pct=40
    
  • 响应:
    { "ok": true, "power": 40, "deltaY": 51 }
    

18.9 设置 X 轴转向幅度

  • 命令: ble_steer
  • 参数:
    • pct: 1..100(必填)
  • 示例:
    GET /api/?command=ble_steer&pct=100
    
  • 响应:
    { "ok": true, "steerPower": 100, "deltaX": 127 }
    
  • 说明: deltaX = max(100, round(127 * pct / 100)),强制 ≥ 100 以越过 X 轴死区

18.10 镜像开关

  • 命令: ble_mirror
  • 参数:
    • y: 1=开启前后镜像,0=关闭(可选)
    • x: 1=开启左右镜像,0=关闭(可选)
  • 描述:
    • 前后镜像:摇杆"上"=车后退,"下"=车前进
    • 左右镜像:摇杆"左"=车右转,"右"=车左转
    • 用于摄像头反装时对齐用户操作直觉
  • 示例:
    GET /api/?command=ble_mirror&y=1&x=1
    
  • 响应:
    { "ok": true, "mirrorY": true, "mirrorX": false }
    

18.11 设置限速

  • 命令: ble_limit
  • 参数:
    • kmh: 8 / 12 / 16 / 18(必填)
  • 示例:
    GET /api/?command=ble_limit&kmh=12
    
  • 响应(异步立即返回):
    { "ok": true, "pending": true, "limit": 12 }
    
  • 说明: 实际结果通过 ble_log 或下一次 ble_status 里的 init 字段观察。固件 181 可能只接受 8/12/16 三档

18.12 设置尾灯颜色

  • 命令: ble_light
  • 参数:
    • c: 0=关,1=黄,2=紫,3=蓝,4=绿(必填)
  • 示例:
    GET /api/?command=ble_light&c=3
    
  • 响应(异步立即返回):
    { "ok": true, "pending": true, "color": 3 }
    
  • 说明: 实际结果通过 ble_status 里的 init 字段观察

18.13 蜂鸣器

  • 命令: ble_beep
  • 示例:
    GET /api/?command=ble_beep
    
  • 响应(异步立即返回):
    { "ok": true, "pending": true }
    

18.14 查询平衡车初始配置

  • 命令: ble_init
  • 示例:
    GET /api/?command=ble_init
    
  • 响应(异步立即返回):
    { "ok": true, "pending": true }
    
  • 说明: 实际结果通过 ble_status 里的 init 字段观察

18.15 发送原始字节

  • 命令: ble_raw
  • 参数:
    • hex: 十六进制字符串,长度必须偶数(必填)
    • expect: 期望收到的响应 opcode(十六进制,可选,异步重试 4 次)
  • 示例:
    GET /api/?command=ble_raw&hex=4E
    GET /api/?command=ble_raw&hex=01507F
    GET /api/?command=ble_raw&hex=4E&expect=4F
    
  • 响应(无 expect):
    { "ok": true, "sent": "4E" }
    
  • 响应(带 expect):
    { "ok": true, "pending": true, "sent": "4E", "expect": "0x4f" }
    

18.16 使用示例

curl 示例

# 状态
curl "http://127.0.0.1:58082/api/?command=ble_status"

# 前进 600ms
curl "http://127.0.0.1:58082/api/?command=ble_fwd&ms=600"

# 按住前进(每 250ms 重发,持续 2 秒)
for i in $(seq 1 8); do
  curl -s "http://127.0.0.1:58082/api/?command=ble_fwd&ms=700" > /dev/null
  sleep 0.25
done
curl "http://127.0.0.1:58082/api/?command=ble_stop"

# 极坐标摇杆:前进+右转
curl "http://127.0.0.1:58082/api/?command=ble_vector&r=0.8&t=45&ms=500"

# 尾灯蓝色
curl "http://127.0.0.1:58082/api/?command=ble_light&c=3"

# 鸣笛
curl "http://127.0.0.1:58082/api/?command=ble_beep"

Python 示例

import requests
import time

BASE = "http://127.0.0.1:58082/api/"

def cmd(name, **params):
    r = requests.get(BASE, params={"command": name, **params}, timeout=5)
    return r.json()

print(cmd("ble_status"))
for _ in range(4):
    cmd("ble_fwd", ms=700)
    time.sleep(0.25)
cmd("ble_stop")
cmd("ble_vector", r=0.8, t=45, ms=500)

JavaScript 示例

const BASE = 'http://127.0.0.1:58082/api/';

async function cmd(name, params = {}) {
  const url = new URL(BASE);
  url.searchParams.set('command', name);
  for (const [k, v] of Object.entries(params)) {
    url.searchParams.set(k, v);
  }
  const res = await fetch(url);
  return res.json();
}

console.log(await cmd('ble_status'));
const timer = setInterval(() => cmd('ble_fwd', { ms: 700 }), 250);
setTimeout(() => { clearInterval(timer); cmd('ble_stop'); }, 2000);
await cmd('ble_vector', { r: 0.8, t: 45, ms: 500 });

18.17 安全策略(三层保护)

层 位置 实现
客户端层 远程端 每条运动指令带 ms,到点自动回中
网关层 安卓端 100ms 心跳持续发送当前方向或中位
指令层 安卓端 setDir 里 leaseUntil = now + ms,过期自动回中

远程端崩溃时:网关侧的 lease 到期后自动发中位,车停。

18.18 协议细节(供参考)

项 值
写特征 UUID 6eb675ab-8bd1-1b9a-7444-621e52ec6423
通知特征 UUID 15005991-b131-3396-014c-664c9867d917
主服务 UUID edfec62e-9910-0bac-5241-d8bda6932a2a
广播名 BLE_FOTBOT
方向帧 [0x01, Y, X],Y/X ∈ [0,254],127 = 中位
X 轴死区 ±100(X ∈ [30, 224] 被忽略)
方向心跳周期 100ms
运动租约 默认 800ms
急停锁定 默认 800ms
写类型 方向包 WRITE_TYPE_NO_RESPONSE,配置指令 WRITE_TYPE_DEFAULT
连接优先级 CONNECTION_PRIORITY_HIGH

18.19 常见问题

Q1: 车不动或反应慢?

  • 检查 ble_status 里 connected 是否为 true
  • 检查 rxAgeMs 是否 > 30 秒(链路判死)
  • 确认远程端是否在持续重发(单发一条只动 ms 毫秒)
  • 检查 X 轴是否落在死区 [30, 224]

Q2: ble_limit / ble_light / ble_beep 返回 pending:true?

  • 异步设计,避免阻塞 HTTP 线程
  • 实际结果通过 ble_log 或下一次 ble_status 观察
  • 不是错误

Q3: 远程访问 /dbot.html 打不开?

  • 检查 HttpCommandServer 的 /dbot.html 路由
  • 检查 assets/fotbot-page.html 是否存在
  • 用 curl http://127.0.0.1:58082/dbot.html 本机验证

Q4: BLE_FOTBOT 找不到?

  • 平衡车是否上电
  • 是否被官方 App 占用连接
  • 先 ble_stop_ble 再 ble_start
  • 看 ble_log 是否有扫描日志

18.20 与 ESP32-Dtnsbot 的区别

dtnsbot 安卓应用里同时存在两套 BLE 客户端:

维度 BleCommandClient(ESP32-Dtnsbot) DbotBleController(dbot-ble)
目标设备 ESP32-Dtnsbot BLE_FOTBOT
服务 UUID 0000ffe0-... edfec62e-...
命令格式 JSON 文本 二进制帧
上行格式 JSON 事件 二进制遥测
用途 通用 ESP32 外设 平衡车差速控制
命令前缀 无 ble_

两者互不干扰:按广播名区分扫描目标,UUID 不同,连接独立。

18.21 命令速查表

# 状态与日志
GET /api/?command=ble_status
GET /api/?command=ble_log

# 连接管理
GET /api/?command=ble_start
GET /api/?command=ble_stop_ble

# 方向
GET /api/?command=ble_fwd&ms=600
GET /api/?command=ble_back&ms=600
GET /api/?command=ble_left&ms=600
GET /api/?command=ble_right&ms=600
GET /api/?command=ble_stop
GET /api/?command=ble_move&y=100&x=127&ms=500
GET /api/?command=ble_vector&r=0.8&t=45&ms=500

# 参数
GET /api/?command=ble_power&pct=40
GET /api/?command=ble_steer&pct=100
GET /api/?command=ble_mirror&y=1&x=0

# 一次性指令
GET /api/?command=ble_limit&kmh=12
GET /api/?command=ble_light&c=3
GET /api/?command=ble_beep
GET /api/?command=ble_init
GET /api/?command=ble_raw&hex=4E
GET /api/?command=ble_raw&hex=4E&expect=4F

# 页面
GET /dbot.html
GET /api/?command=ble_page

# 视频(新增)
GET /api/?command=webrtc_video_start&facing=user&width=640&height=480&fps=15&audio=true
GET /api/?command=webrtc_video_stop
GET /api/?command=webrtc_video_switch
GET /api/?command=webrtc_video_status

# 双向语音(新增)
GET /api/?command=webrtc_video_audio&enabled=1     # 手机麦克风 → 浏览器
GET /api/?command=webrtc_video_audio&enabled=0
GET /api/?command=webrtc_speaker&enabled=1         # 浏览器 → 手机扬声器
GET /api/?command=webrtc_speaker&enabled=0

# clientId(新增)
GET /api/?command=restart_proxy&proxy_id=your_client_id   # 设置并持久化(示例值,勿写真实 ID)
GET /api/?command=set_config&key=http_proxy_id&value=   # 清空,下次启动重新生成

附录

Web界面访问

  • 控制面板: http://[设备IP]:58082/control
  • 配置管理: http://[设备IP]:58082/config
  • 截图功能: http://[设备IP]:58082/screenshot
  • UI信息: http://[设备IP]:58082/uiinfo
  • 语音API: http://[设备IP]:58082/speech
  • 使用帮助: http://[设备IP]:58082/help
  • 平衡车控制: http://[设备IP]:58082/dbot.html

注意事项

  1. 所有坐标参数请确保在屏幕分辨率范围内
  2. 截图功能需要 Android 7.0+(API 24+)
  3. 系统截图API需要 Android 11+(API 30+)
  4. 语音识别需要上传WAV格式音频
  5. 配置修改后立即生效,无需重启服务
  6. 异步任务可以通过 task_id 查询处理状态

WebRTC RPC 命令 API 文档(补充)

本文档描述 dtnsbot 安卓设备通过 WebRTC RPC 通道暴露的命令接口,与 HTTP /api/?command=... 接口功能完全等价。


目录

  1. 概述
  2. 信令与连接
  3. 命令通道 /command
  4. 文件通道 /file/get /file/put /file/list
  5. Android 端 WebRTC 管理命令
  6. Android 作为客户端
  7. 浏览器/Node 端调用示例
  8. 与 HTTP API 的对应关系
  9. 常见问题

1. 概述

1.1 与 HTTP API 的关系

维度 HTTP API WebRTC RPC
传输 HTTP/TCP WebRTC/DataChannel (SCTP)
端口 58082 无需端口(P2P 或 TURN)
命令 /api/?command=xxx client.call('/command', {command, params})
文件 /api/?command=file_upload/file_download /file/get /file/put /file/list
大文件 受 HTTP body 限制(base64) 二进制分片 + 断点续传
NAT 穿透 需公网 IP / 端口映射 天然穿透

关键:/command handler 最终调用同一个 onCommandReceived,所有 HTTP 命令自动可用,包括新增的 ble_* 系列。

1.2 角色

┌──────────────────┐                    ┌──────────────────┐
│  Android 设备     │  ←── WebRTC ──→   │  浏览器/Node 端   │
│  (Server 角色)   │                    │  (Client 角色)   │
└──────────────────┘                    └──────────────────┘
        ↕                                        ↕
   NanoHTTPD :58082                       HTTP API 也可用

┌──────────────────┐                    ┌──────────────────┐
│  Android 设备     │  ←── WebRTC ──→   │  其他 Android     │
│  (Client 角色)   │                    │  (Server 角色)   │
└──────────────────┘                    └──────────────────┘

Android 设备可以同时是 Server 和 Client。


2. 信令与连接

2.1 信令服务器

所有 WebRTC 连接通过一个 Socket.IO 信令服务器建立。

项 值
协议 http:// 或 https://
默认地址 http://dev.dtns.top
传输 websocket
ICE 服务器 turn:static.dtns.top:3478

2.2 房间号(Room ID)

用途 默认值
Android 作为 Server room-android-server
Android 作为 Client room-clean-demo

规则:

  • Server 房间号:其他设备连接到这个房间
  • Client 房间号:Android 主动连接的房间

clientId 与房间号(新增):

  • http-proxy 启动时,会把 clientId 同时写成 WebRTC Server 房间号(配置键 webrtc_server_room),并自动启动 WebRTC Server。
  • clientId 持久化在配置键 http_proxy_id:人为设置一次后,重启/重装都沿用;只有配置为空时才重新生成。
  • 浏览器端用 dtnsbot.{clientId}.html.dtns.top 打开页面时,会从域名里解析出 clientId 作为房间号,与安卓端自动对齐。

2.3 角色与信令流

Client 端                     信令服务器                   Android (Server)
   |                              |                            |
   |--- discover(room) ---------> |                            |
   |<-- {peers, hostid} --------- |                            |
   |--- connect(hostid) -------> |                            |
   |                              |--- request ------------->  |
   |                              |<-- accept ---------------- |
   |<======== WebRTC DataChannel ============================>|
   |                                                            |

Android 作为 Server 时,信令服务器上会注册 roomid::host,其他设备 discover(roomid) 就能拿到 hostid。


3. 命令通道 /command

3.1 基本调用

RPC 接口:

rpc.call('/command', {
    command: '<HTTP命令名>',    // 必填
    params: { ... }              // 可选
})

与 HTTP 的等价关系:

HTTP WebRTC RPC
GET /api/?command=home call('/command', { command: 'home' })
GET /api/?command=click_at_500,800 call('/command', { command: 'click_at_500,800' })
GET /api/?command=screen_info call('/command', { command: 'screen_info' })
GET /api/?command=ble_fwd&ms=600 call('/command', { command: 'ble_fwd', params: { ms: '600' } })
GET /api/?command=ble_vector&r=0.8&t=45 call('/command', { command: 'ble_vector', params: { r: '0.8', t: '45' } })

3.2 返回格式

统一返回 JSON:

{
    "status": "success",
    "result": "..."       // 原始 HTTP 返回
}

或直接是 HTTP 命令的原始 JSON 返回(如果 handler 返回的是 JSON 对象)。

3.3 支持的命令

所有 HTTP 命令都可以通过 /command 调用:

分类 命令示例
系统控制 home back recent notifications power lock split
应用操作 open_设置 open_微信 get_apps
坐标点击 click_at_500,800 long_click_at_500,800 test_click
手势滑动 swipe_left swipe_right swipe_up swipe_down swipe_at_500,800,200,800,1000
截图 screenshot get_screenshot_result get_screenshot_direct&quality=60 get_screenshot_ocr
UI 信息 get_uinfo get_uiinfo_result dump_layout get_layout_result
语音 speech_recognize speech_synthesize
配置 set_config get_config set_system_prompt
收藏悬浮窗 显示收藏 隐藏收藏 set_smart_mode set_collection_mode
识图机灵 识图机灵 图片机灵 万能机灵 全屏机灵 full_smart_1000,3000
GPS get_gps start_gps stop_gps gps_status
文本 input_文本 click_文本 paste_文本 get_clipboard_text
输入法 ime_send&text=xxx ime_get_text ime_clear ime_send_delayed
命令执行 exec&cmd=ls exec_async system check_exec_service
POP/JS pop_eval&script=... pop_run&file=... js_eval&code=...
文件 file_upload file_download file_list
辅助 help ibbot_process ibbot_smart_reply 收藏 机灵
日志 get_today_log get_log
dbot-ble ble_status ble_fwd ble_back ble_left ble_right ble_stop ble_move ble_vector ble_power ble_steer ble_mirror ble_limit ble_light ble_beep ble_init ble_raw

3.4 参数传递

params 会被拼接为 query 参数,由 Android 侧解析:

// 等价于 HTTP: /api/?command=set_config&key=xxx&value=yyy
await client.call('/command', {
    command: 'set_config',
    params: { key: 'xxx', value: 'yyy' }
});

注意:params 里的所有键值都会被传为 String,与 HTTP query 一致。

3.5 错误返回

{
    "error": "具体错误信息"
}

或

{
    "status": "error",
    "message": "具体错误信息"
}

4. 文件通道

4.1 /file/get — 下载文件

客户端调用:

const result = await client.download(
    '/file/get',
    {
        path: '/sdcard/Download/test.png',
        name: 'test.png',
        size: 12345
    },
    sink,
    (got, total) => { /* 进度 */ }
);

// result: { name: 'test.png', size: 12345, url: 'blob:...' }

Android 侧 handler:

androidServer.on('/file/get', async ({ params }) => {
    const path = params.path;
    const size = AndroidBridge.getFileSize(path);
    const name = params.name || path.split('/').pop();
    return {
        name,
        size,
        path,
        async read(offset, length) {
            const b64 = AndroidBridge.readFileChunk(path, offset, length);
            return base64ToUint8(b64);
        },
    };
});

参数:

参数 必填 说明
path 是 Android 上的绝对路径
name 否 覆盖保存的文件名(默认用 path 的 basename)
size 否 文件大小(不传则 Android 侧查)

返回:

{
    "name": "test.png",
    "size": 12345,
    "path": "/sdcard/Download/test.png",
    "data": "Uint8Array(如果 sink 用 MemoryDownloadSink)",
    "url": "blob:http://... (如果 sink 用 OpfsDownloadSink)"
}

4.2 /file/put — 上传文件

客户端调用:

const result = await client.upload(
    file,
    '/file/put',
    {
        path: '/sdcard/Download/',
        filename: file.name,
    },
    (acked, total) => { /* 进度 */ }
);

// result: { ok: true, name: 'test.png', size: 12345, path: '/sdcard/Download/test.png' }

参数:

参数 必填 说明
path 否 目标目录,默认 /sdcard/Download/
filename 否 目标文件名,默认用上传源的文件名
savePath 否 完整保存路径(优先级最高)

返回:

{
    "ok": true,
    "name": "test.png",
    "size": 12345,
    "path": "/sdcard/Download/test.png"
}

4.3 /file/list — 列出文件

客户端调用:

const result = await client.call('/file/list', {
    path: '/sdcard/Download',
    recursive: false
});

// result.files: [{ name, path, isDir, size }, ...]

参数:

参数 必填 说明
path 否 目录路径,默认 /sdcard/
recursive 否 是否递归,默认 false

返回:

{
    "files": [
        {
            "name": "test.png",
            "path": "/sdcard/Download/test.png",
            "isDir": false,
            "size": 12345
        },
        {
            "name": "子目录",
            "path": "/sdcard/Download/子目录",
            "isDir": true,
            "size": 0
        }
    ]
}

4.4 保存路径策略

上传时,路径按优先级选择:

  1. params.savePath — 完整路径
  2. params.path + params.filename — 目录 + 指定文件名
  3. params.path + 原始文件名
  4. 默认目录 + 原始文件名

默认目录:

  • 优先 /sdcard/Download/(需要 MANAGE_EXTERNAL_STORAGE 权限)
  • 回退 /storage/emulated/0/Android/data/com.example.dtnsbot/files/downloads/(无需权限)

5. Android 端 WebRTC 管理命令

这些命令通过 HTTP API 调用,用于控制 Android 的 WebRTC 行为。

5.1 启动 WebRTC Server

GET /api/?command=webrtc_server_start

响应:

{
    "status": "accepted",
    "message": "RPC Server 启动中"
}

5.2 停止 WebRTC Server

GET /api/?command=webrtc_server_stop

5.3 启动 WebRTC Client

GET /api/?command=webrtc_client_start

5.4 停止 WebRTC Client

GET /api/?command=webrtc_client_stop

5.5 设置信令 URL

GET /api/?command=webrtc_set_signal&url=http://dev.dtns.top

5.6 设置 Server 房间号

GET /api/?command=webrtc_set_server_room&room=room-android-server

5.7 设置 Client 房间号

GET /api/?command=webrtc_set_client_room&room=room-clean-demo

5.8 查询 WebRTC 状态

GET /api/?command=webrtc_status

5.9 通过 Android Client 远程调用

GET /api/?command=webrtc_rpc_call&url=/command&params={"command":"home"}

5.10 通过 Android Client 远程上传

GET /api/?command=webrtc_rpc_upload&url=/file/put&path=/sdcard/xxx.png&extra={}

5.11 通过 Android Client 远程下载

GET /api/?command=webrtc_rpc_download&url=/file/get&params={"path":"/remote/xxx.png"}&save=/sdcard/xxx.png

5.12 开启视频(摄像头 → 浏览器)

GET /api/?command=webrtc_video_start&facing=user&width=640&height=480&fps=15&audio=true
参数 类型 默认 说明
facing string user user 前置 / environment 后置
width / height int 640 / 480 建议 4:3(640×480),用满传感器、不裁视野
fps int 15 帧率
audio bool true 是否同时采集手机麦克风
lens string auto auto 自动挑超广角(label 含 ultra/0.5x/超广角);default 按 facing 取默认镜头

响应:

{
  "ok": true,
  "facing": "user",
  "width": 480,
  "height": 640,
  "fps": 15,
  "audio": true,
  "deviceId": "07db930b...",
  "videoTracks": 1,
  "audioTracks": 1
}

行为说明:

  • 调用前会自动 startServer,保证 WebRTC Server 在跑。
  • 安卓是 answerer,addTrack 不能新增 m-line:必须复用浏览器 offer 里已有 mid 的 transceiver(replaceTrack)。
  • 音频 transceiver 方向是 sendrecv(双向语音),视频是 sendonly。
  • 开启后会自动把 zoom 拉到最小值(最广视野)并尝试连续对焦(机型支持时)。

5.13 关闭视频

GET /api/?command=webrtc_video_stop

释放摄像头/麦克风,并从所有 peer 上移除轨道。

5.14 切换前后摄像头

GET /api/?command=webrtc_video_switch

响应:

{ "ok": true, "facing": "environment" }

注意:实现是「先停旧摄像头,再开新摄像头」——很多机型/WebView 不允许同时打开两颗摄像头,否则会报 Could not start video source。失败会自动回滚到原摄像头。

5.15 开关手机麦克风(上行:手机 → 浏览器)

GET /api/?command=webrtc_video_audio&enabled=1
GET /api/?command=webrtc_video_audio&enabled=0

对应网页上的「对方麦克风」按钮。

5.16 开关手机播放远端语音(下行:浏览器 → 手机扬声器)

GET /api/?command=webrtc_speaker&enabled=1
GET /api/?command=webrtc_speaker&enabled=0

别名:webrtc_remote_audio。参数缺省视为 1(开)。

响应:

{ "ok": true, "enabled": false }

说明:默认开启。关闭后安卓端 <audio> 被静音(muted=true),但 WebRTC 连接与音轨保留,随时可再打开。

5.17 查询视频/语音状态

GET /api/?command=webrtc_video_status

响应(result 字段内是 JSON 字符串):

{
  "ok": true,
  "active": true,
  "facing": "user",
  "width": 480,
  "height": 640,
  "fps": 15,
  "audio": true,
  "deviceId": "07db930b...",
  "zoom": null,
  "focusMode": ["manual"],
  "remoteAudio": {
    "enabled": true,
    "playing": true,
    "hasTrack": true
  },
  "videoTracks": 1,
  "audioTracks": 1
}
字段 说明
zoom 摄像头支持的变焦范围;null 表示该机型 WebView 未暴露
focusMode 支持的对焦模式
remoteAudio.enabled 是否允许播放远端语音
remoteAudio.playing 当前是否真的在播放
remoteAudio.hasTrack 是否已收到浏览器音轨

5.18 网页控制面板 /dbot.html

GET https://dtnsbot.{clientId}.html.dtns.top/dbot.html
按钮 作用
📹 开启视频 / ⏹️ 关闭视频 起停推流
🔄 切换前后 调用 webrtc_video_switch
🎤 我的麦克风 浏览器本地麦克风上/下行(关闭时 replaceTrack(null) 真正停止采集)
🔊 对方麦克风 调 webrtc_video_audio 开关手机麦克风
🔇 全部静音 / 🔊 恢复声音 两端麦克风一起关/开

页面停留时自动订阅 peer 事件;接收端同时监听 stream、track 和原生 ontrack,并按 getReceivers() 合并所有轨道(避免只挂到音频轨导致黑屏)。

5.19 常见问题(视频/语音)

现象 原因 处理
连接 connected 但黑屏 SDP 里没有 m=video,或对端 addTrack 新建了无 mid 的 transceiver 浏览器先 addTransceiver('video', {direction:'sendrecv'})(视频用 sendrecv 才可复用),安卓用 replaceTrack 复用已有 mid
点「切换前后」报 Could not start video source 新旧摄像头同时打开 已内置「先 stop 再开 + 失败回滚」
有声音但画面 0×0 srcObject 只挂了 audio 轨 从 pc.getReceivers() 重建 MediaStream
啸叫/回声 手机扬声器播放电脑麦克风,同一房间形成声学回环 电脑端戴耳机,或用 webrtc_speaker&enabled=0 关闭下行

5.20 修改 / 持久化 clientId

GET /api/?command=restart_proxy&proxy_id=your_client_id

重启 http-proxy 并把新 clientId 写入配置(http_proxy_id),之后重启 App 一直沿用;WebRTC 房间号同步改成新 ID 并重启 Server。

清空(下次启动重新生成):

GET /api/?command=set_config&key=http_proxy_id&value=

⚠️ 隐私提醒:proxy_id 就是设备 clientId,等同于这台设备的控制入口。文档、截图、聊天记录里都不要出现真实值,示例统一写 your_client_id;也不要把它写进公开仓库。


6. Android 作为客户端

6.1 整体流程

1. HTTP: webrtc_set_signal  → 配置信令
2. HTTP: webrtc_set_client_room → 配置目标房间
3. HTTP: webrtc_client_start → 建立连接
4. HTTP: webrtc_rpc_call → 调用远端命令
5. HTTP: webrtc_rpc_upload → 上传文件到远端
6. HTTP: webrtc_rpc_download → 下载远端文件到本地

6.2 完整示例

curl "http://127.0.0.1:58082/api/?command=webrtc_set_signal&url=http://dev.dtns.top"
curl "http://127.0.0.1:58082/api/?command=webrtc_set_client_room&room=room-clean-demo"
curl "http://127.0.0.1:58082/api/?command=webrtc_client_start"
sleep 5
curl "http://127.0.0.1:58082/api/?command=webrtc_rpc_call&url=/command&params=%7B%22command%22%3A%22screen_info%22%7D"
curl "http://127.0.0.1:58082/api/?command=webrtc_rpc_upload&url=/file/put&path=/sdcard/test.png"
curl "http://127.0.0.1:58082/api/?command=webrtc_rpc_download&url=/file/get&params=%7B%22path%22%3A%22/remote/test.png%22%7D&save=/sdcard/test.png"

7. 浏览器/Node 端调用示例

7.1 浏览器:加载依赖

<script src="socket.io.min.js"></script>
<script src="simple-signal-client.min.js"></script>
<script src="jszip.min.js"></script>
<script src="rpc-protocol.js"></script>
<script src="rpc-core.js"></script>
<script src="opfs-utils.js"></script>
<script src="storage-browser.js"></script>

7.2 连接 Android Server

const SSC = window.SimpleSignalClient || window.SimpleSignal;

const client = new RPCCore.RPCClient(
    'room-android-server',
    'http://dev.dtns.top',
    {},
    {
        socketIo: io,
        SimpleSignalClient: SSC,
        rtcOptions: {
            iceServers: [
                { urls: 'turn:static.dtns.top:3478' },
                { urls: 'stun:stun.l.google.com:19302' },
            ],
        },
        createDownloadSink: () => new BrowserStorage.OpfsDownloadSink({ dir: 'downloads' }),
        wrapUploadSource: (src) => src instanceof Blob
            ? new BrowserStorage.FileUploadSource(src)
            : src,
    }
);

client.addEventListener('ready', () => console.log('connected'));
await client.connect();

7.3 调用命令(含 ble_* 示例)

// 系统控制
await client.call('/command', { command: 'home' });
await client.call('/command', { command: 'back' });

// 坐标点击
await client.call('/command', { command: 'click_at_500,800' });

// 截图
await client.call('/command', { command: 'screenshot' });

// 配置
await client.call('/command', {
    command: 'set_config',
    params: { key: 'IBBOT_AGENT_BASE_URL', value: 'http://192.168.1.100:8080' }
});

// 输入法
await client.call('/command', {
    command: 'ime_send',
    params: { text: '你好世界', clear: 'true', enter: 'true' }
});

// POP 脚本
await client.call('/command', {
    command: 'pop_eval',
    params: { script: 'dtnsbot home' }
});

// ============ dbot-ble 平衡车(新增) ============
await client.call('/command', { command: 'ble_status' });
await client.call('/command', { command: 'ble_fwd', params: { ms: '600' } });
await client.call('/command', { command: 'ble_vector', params: { r: '0.8', t: '45', ms: '500' } });
await client.call('/command', { command: 'ble_stop' });
await client.call('/command', { command: 'ble_light', params: { c: '3' } });
await client.call('/command', { command: 'ble_beep' });
// =================================================

7.4 下载文件

const result = await client.download(
    '/file/get',
    { path: '/sdcard/Download/test.png', name: 'test.png' },
    null,
    (got, total) => {
        console.log(`download ${got}/${total}`);
    }
);

const a = document.createElement('a');
a.href = result.url;
a.download = result.name;
a.click();

7.5 上传文件

const fileInput = document.querySelector('#file');
const file = fileInput.files[0];

const result = await client.upload(
    file,
    '/file/put',
    {
        path: '/sdcard/Download/',
        filename: file.name,
    },
    (acked, total) => {
        console.log(`upload ${acked}/${total}`);
    }
);

console.log('uploaded to:', result.path);

7.6 列出文件

const result = await client.call('/file/list', { path: '/sdcard/Download' });
console.log('files:', result.files);

7.7 Node.js 端

const io = require('socket.io-client');
const SimpleSignalClient = require('simple-signal-client');
const wrtc = require('wrtc');

const { RPCClient } = require('./rpc-core.js');
const { FsDownloadSink, FsUploadSource } = require('./storage-node.js');

const client = new RPCClient('room-android-server', 'http://dev.dtns.top', {}, {
    socketIo: io,
    SimpleSignalClient,
    rtcOptions: {
        wrtc,
        iceServers: [{ urls: 'turn:static.dtns.top:3478' }],
    },
});

await client.connect();

console.log(await client.call('/command', { command: 'screen_info' }));
console.log(await client.call('/command', { command: 'ble_status' })); // 新增

await client.download(
    '/file/get',
    { path: '/sdcard/Download/test.png' },
    new FsDownloadSink({ savePath: './test.png' })
);

await client.upload(
    new FsUploadSource('./test.png'),
    '/file/put',
    { path: '/sdcard/Download/' }
);

console.log(await client.call('/file/list', { path: '/sdcard/Download' }));

8. 与 HTTP API 的对应关系

8.1 命令通道对照

HTTP WebRTC RPC
GET /api/?command=home call('/command', { command: 'home' })
GET /api/?command=click_at_500,800 call('/command', { command: 'click_at_500,800' })
GET /api/?command=set_config&key=k&value=v call('/command', { command: 'set_config', params: { key: 'k', value: 'v' } })
GET /api/?command=exec&cmd=ls call('/command', { command: 'exec', params: { cmd: 'ls' } })
GET /api/?command=get_screenshot_direct&quality=60 call('/command', { command: 'get_screenshot_direct', params: { quality: '60' } })
GET /api/?command=ble_fwd&ms=600 call('/command', { command: 'ble_fwd', params: { ms: '600' } })
GET /api/?command=ble_move&y=100&x=127 call('/command', { command: 'ble_move', params: { y: '100', x: '127' } })
GET /api/?command=ble_light&c=3 call('/command', { command: 'ble_light', params: { c: '3' } })

8.2 文件通道对照

HTTP WebRTC RPC
file_upload (Base64) /file/put (二进制流)
file_download (binary) /file/get (二进制流)
file_list /file/list
无大小限制(受 HTTP body 限制) 支持 GB 级文件
无进度 带进度回调
无断点续传 协议层支持

8.3 WebRTC 独有

功能 说明
NAT 穿透 无需公网 IP / 端口映射
P2P 直连 局域网/同城直连,速度快
断点续传 streamId 持久化,网络抖动自动恢复
服务端驱动重发 STREAM_RETRY,精确重传丢包
动态切片 32KB → 512KB 自适应网络
gzip 压缩 大 JSON 自动压缩,带宽省 90%

9. 常见问题

9.1 Android 端上传文件保存到哪里

默认:

  1. 优先 /sdcard/Download/<原名>(需 MANAGE_EXTERNAL_STORAGE)
  2. 回退 /storage/emulated/0/Android/data/com.example.dtnsbot/files/downloads/<原名>(无需权限)

通过 params.path 指定目录:

client.upload(file, '/file/put', {
    path: '/sdcard/Download/子目录/',
    filename: '自定义名.png',
});

9.2 下载文件到 Android 端保存到哪里

通过 savePath 指定:

client.download('/file/get', {
    path: '/remote/test.png',
    name: 'test.png',
}, new AndroidDownloadSink({ savePath: '/sdcard/Download/test.png' }));

默认:走 getDefaultDownloadDir() → App 私有目录。

9.3 为什么 WebRTC 比 HTTP 慢

常见原因:

  1. maxMessageSize 小(Android WebView 通常 64KB,Node wrtc 通常 256KB)
  2. JS → Java 桥接(每次 write 都跨界 + Base64 编解码)
  3. 手机 CPU 降频 + WebView 主线程

9.4 无法连接到 Android

排查:

  1. 信令服务器是否可达:curl http://dev.dtns.top
  2. 房间号是否匹配:Android 端 webrtc_set_server_room 配的 room,客户端要用同一个
  3. TURN 服务器是否可达:turn:static.dtns.top:3478
  4. Android WebView 是否加载成功:看 logcat 里 JS ENV 探针
  5. Android 端是否启动了 Server:webrtc_status 查询

9.5 /command 返回空

可能原因:

  • Android 侧 dispatchCommand 抛异常(看 logcat)
  • 命令名拼写错误(大小写敏感)
  • 参数没传对(params 是 String 类型)

9.6 大文件上传/下载中断

检查:

  • 网络是否稳定
  • 是否超时(默认 1 小时)
  • Android 端 openFileForWrite 是否失败(看 logcat)
  • 是否触碰 MANAGE_EXTERNAL_STORAGE 权限问题

9.7 POP 脚本通过 WebRTC 调用

await client.call('/command', {
    command: 'pop_eval',
    params: {
        script: `
            set i 0
            set max 5
            pop.func.define loop
                dtnsbot click_at_${i * 100},${i * 100}
                + i 1 i
                < i max flag
            pop.func.end
            pop.do.while flag loop
        `
    }
});

附录 A:错误响应格式

{
    "error": "错误描述"
}

或

{
    "status": "error",
    "message": "错误描述",
    "timestamp": 1234567890
}

附录 B:WebRTC 命令快速参考

命令 用途
webrtc_server_start 启动 Server
webrtc_server_stop 停止 Server
webrtc_client_start 启动 Client
webrtc_client_stop 停止 Client
webrtc_set_signal 设置信令 URL
webrtc_set_server_room 设置 Server 房间
webrtc_set_client_room 设置 Client 房间
webrtc_status 查询状态
webrtc_rpc_call 远程调用
webrtc_rpc_upload 远程上传
webrtc_rpc_download 远程下载

附录 C:相关文件

文件 作用
rpc-protocol.js 协议层(pack/unpack)
rpc-core.js 协议核心(Pusher/Receiver/Client/Server)
storage-android.js Android 专用 sink/source
storage-browser.js 浏览器专用 sink/source
storage-node.js Node 专用 sink/source
opfs-utils.js OPFS 工具(浏览器)
rpc-bridge.html Android WebView 宿主
WebrtcRpcManager.kt Kotlin 桥接管理
dtnsbot-rpc-client.html 浏览器客户端示例

本文档结束。