开发者文档:用你的 App 控制用户的 micro:bit
灵逸 MB 开放了对外开发者接口。你的 App 无需自己处理蓝牙 / 串口,只要把「意图指令」(如
SCROLL:hello)交给灵逸 MB,由它转成串口数据下发给用户已连接的 micro:bit V2。
⚠️ 安全前提:所有外部调用都受「设置 → 允许外部应用控制开发板」开关保护。该开关默认关闭(开发者测试版默认开启)。未开启时任何调用都返回失败、不会触碰开发板。
第一步:开启接口
在灵逸 MB 内:设置 → 允许外部应用控制开发板,打开开关。之后同机任意 App 都可以通过下面两种方式调用。
三种版本的 authority(包名后缀不同):
稳定版:com.lingyi.mbos.external 预览版:com.lingyi.mbos.preview.external 开发版:com.lingyi.mbos.dev.external
方式一:ContentProvider(推荐,零权限)
灵逸 MB 导出了一个 exported 的 ContentProvider,authority 为 <包名>.external。任意 App 无需声明任何权限即可调用。返回 Bundle{ ok, reason, sent }。
方法
call("status", null, null)—— 查询连接状态。call("send", "SCROLL:hello", null)—— 转发一条指令(参数即指令文本)。
Kotlin 示例
val auth = "com.lingyi.mbos.external" // 按版本替换包名
val uri = Uri.parse("content://$auth")
val r = contentResolver.call(uri, "send", "SCROLL:hello", null)
val ok = r?.getBoolean("ok") ?: false
val reason = r?.getString("reason")
println("发送结果:ok=$ok, $reason")
Java 示例
String auth = "com.lingyi.mbos.external"; // 按版本替换包名
Uri uri = Uri.parse("content://" + auth);
Bundle r = getContentResolver().call(uri, "send", "SCROLL:hello", null);
boolean ok = r != null && r.getBoolean("ok");
String reason = r == null ? "无返回" : r.getString("reason");
System.out.println("发送结果:ok=" + ok + ", " + reason);
也可用 URI 形式
// content://<包名>.external/send?cmd=SCROLL:hello
val r = contentResolver.call(uri, "send", "SCROLL:hello", null)
方式二:本地 HTTP 接口(curl / 任意语言)
开发者测试版内置一个仅监听 127.0.0.1 的本地 HTTP 服务(端口 8765),外部网络不可达。在「开发者工具箱 → 本地 HTTP 接口」里启动。
GET /send?cmd=SCROLL:hello —— 转发指令
GET /status —— 查询连接状态
curl 示例
# 发送一条滚动文字指令
curl "http://127.0.0.1:8765/send?cmd=SCROLL:hello"
# 查询是否已连接开发板
curl "http://127.0.0.1:8765/status"
Python 示例
import urllib.request, json
def mb_send(cmd):
url = "http://127.0.0.1:8765/send?cmd=" + urllib.parse.quote(cmd)
with urllib.request.urlopen(url) as r:
return json.loads(r.read())
print(mb_send("SCROLL:hello"))
返回格式(JSON)
// 成功
{"ok":true,"sent":"SCROLL:hello"}
// 失败(接口未开启 / 未连接)
{"ok":false,"reason":"外部接口未开启"}
协议指令参考
指令均为「命令 + 冒号 + 参数」,以换行结尾(调用方传 SCROLL:hello 即可,本 App 自动补换行)。
| 指令 | 含义 | 示例 |
|---|---|---|
SCROLL | 滚动文字 | SCROLL:hello |
SHOW | 显示 5×5 图案 | SHOW:♥ |
PLOT | 点亮 / 熄灭某点 (x,y,0/1) | PLOT:2,2,1 |
TONE | 音调 (频率Hz,时长ms) | TONE:440,500 |
NUMBER | 显示数字 | NUMBER:2026 |
BRIGHT | 亮度 (0–9) | BRIGHT:5 |
MELODY | 播放旋律 | MELODY:ODE |
COMPASS | 启动指南针 | COMPASS |
READ | 读取传感器 | READ |
INFO | 读取固件信息 | INFO |
CLEAR | 清空屏幕 | CLEAR |
附:组件检视悬浮窗(开发版调试)
开发者测试版内置「开发者工具箱 → 组件检视器」。启动后屏幕出现一个可拖动的「调试」气泡:
- 点一下气泡进入抓取模式(全屏半透明蒙层);
- 再点屏幕上的任意组件,弹出面板显示:类名(如 MaterialButton)、资源 ID、专属稳定编号(视图树路径 + 哈希,每次一致,便于反馈定位)、所属页面;
- 再点气泡退出抓取模式。
该能力仅在本 App 自身的 Activity 内生效,用于调试反馈;跨 App 命中需要系统级辅助,不在范围内。
安全与权限小结
- ContentProvider 以
exported=true导出,但所有指令都受应用内开关拦截,默认不生效。 - HTTP 接口仅绑定
127.0.0.1,外部网络无法访问。 - 无论哪种方式,都必须先在本 App 内开启开关,且用户已连接 micro:bit。
- 开发者测试版供调试使用,请勿用于生产日常场景。
灵逸 MB · 开发者文档 | 10Y-灵逸云科技 | MIT License