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 (部分命令返回纯文本)
目录
- 系统控制命令
- 应用操作命令
- 坐标点击命令
- 手势滑动命令
- 截图功能命令
- UI信息命令
- 语音API命令
- 配置管理命令
- 收藏悬浮窗命令
- 识图机灵命令
- GPS定位命令
- 文本操作命令
- 命令执行器
- 辅助命令
- 错误码说明
- 文件上传下载
- poplang脚本与编程
- 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) |
功能流程
- 调用
takeScreenshotForOCR()方法截图 - 调用
recognizeImageWithOCRResult()方法进行OCR识别 - 如果主方法失败,会尝试一次重试
- 返回识别结果或失败信息
注意事项
- 需要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_smartscroll_smart
响应示例
{
"status": "accepted",
"message": "全屏机灵任务已接受,滚动高度: 1000px,等待时间: 3000ms",
"task_id": "full_smart_1734567890123"
}
完整请求示例
http://192.168.1.49:58082/api/?command=full_smart_1000,3000
注意事项
- 任务异步执行,完成后结果自动复制到剪贴板
- 滚动高度建议范围:100-2000px
- 等待时间建议范围:500-10000ms
- 执行时会显示进度悬浮窗
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 对象或数组,则原样返回。
注意事项
POP 脚本语法:POP 脚本基于 JavaScript 语法,支持
op(context, opcode, ...)调用预定义的操作码,也支持['opcode', 参数...]数组形式。具体操作码可参考pop_runtime2.js中的binderAddOpcode定义。内置操作码扩展:该服务额外注册了
show-toast和dtnsbot操作码:show-toast: 显示 Toast 消息,例:show-toast msgdtnsbot: 调用原有控制命令,例:dtnsbot click_at_500,800
URL 编码:当脚本中包含特殊字符(如空格、引号、换行)时,必须进行 URL 编码。建议使用 POST 方式传递长脚本。
执行超时:POP 脚本和 JS 代码默认执行超时时间为 30 秒,超时后会返回
{"error": "执行超时"}。安全限制:
- POP 引擎初始化时
safeFlag = false,禁用了 Node.js 的vm模块和文件操作,但基本运算和自定义操作码可用。 - JavaScript 引擎运行在独立的 WebView 中,无法直接访问文件系统,但可以通过
PopAndroid接口调用部分服务功能。
- POP 引擎初始化时
响应结构:
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 格式"
}
注意事项
日志文件位置
- 优先写入公共目录:
/sdcard/dtnsbot/logs/ - 若无存储权限,则回退到应用私有目录:
/storage/emulated/0/Android/data/com.example.dtnsbot/files/../dtnsbot/logs/ - 实际路径以响应中的
file_path为准。
- 优先写入公共目录:
权限要求
- 访问公共目录需要
READ_EXTERNAL_STORAGE权限(Android 10 及以下)或MANAGE_EXTERNAL_STORAGE(Android 11+)。若无权限,请引导用户到设置中授予「存储权限」。 - 应用私有目录不需要额外权限。
- 访问公共目录需要
日志轮转
- 每天生成一个独立的日志文件,文件名格式为
YYYY-MM-DD.log。 - 当日志写入时自动创建,跨日时关闭旧文件并创建新文件。
- 每天生成一个独立的日志文件,文件名格式为
内容安全
- 日志可能包含敏感信息(如脚本内容、屏幕坐标等),仅在可信网络环境下调用该接口。
扩展用法
配合 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
注意事项
- 所有坐标参数请确保在屏幕分辨率范围内
- 截图功能需要 Android 7.0+(API 24+)
- 系统截图API需要 Android 11+(API 30+)
- 语音识别需要上传WAV格式音频
- 配置修改后立即生效,无需重启服务
- 异步任务可以通过
task_id查询处理状态
WebRTC RPC 命令 API 文档(补充)
本文档描述 dtnsbot 安卓设备通过 WebRTC RPC 通道暴露的命令接口,与 HTTP /api/?command=... 接口功能完全等价。
目录
- 概述
- 信令与连接
- 命令通道
/command - 文件通道
/file/get/file/put/file/list - Android 端 WebRTC 管理命令
- Android 作为客户端
- 浏览器/Node 端调用示例
- 与 HTTP API 的对应关系
- 常见问题
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 保存路径策略
上传时,路径按优先级选择:
params.savePath— 完整路径params.path+params.filename— 目录 + 指定文件名params.path+ 原始文件名- 默认目录 + 原始文件名
默认目录:
- 优先
/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¶ms={"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¶ms={"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¶ms=%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¶ms=%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 端上传文件保存到哪里
默认:
- 优先
/sdcard/Download/<原名>(需MANAGE_EXTERNAL_STORAGE) - 回退
/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 慢
常见原因:
maxMessageSize小(Android WebView 通常 64KB,Nodewrtc通常 256KB)- JS → Java 桥接(每次 write 都跨界 + Base64 编解码)
- 手机 CPU 降频 + WebView 主线程
9.4 无法连接到 Android
排查:
- 信令服务器是否可达:
curl http://dev.dtns.top - 房间号是否匹配:Android 端
webrtc_set_server_room配的 room,客户端要用同一个 - TURN 服务器是否可达:
turn:static.dtns.top:3478 - Android WebView 是否加载成功:看 logcat 里
JS ENV探针 - 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 |
浏览器客户端示例 |
本文档结束。