开发者文档:用你的 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 }。

方法

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

附:组件检视悬浮窗(开发版调试)

开发者测试版内置「开发者工具箱 → 组件检视器」。启动后屏幕出现一个可拖动的「调试」气泡:

  1. 点一下气泡进入抓取模式(全屏半透明蒙层);
  2. 再点屏幕上的任意组件,弹出面板显示:类名(如 MaterialButton)、资源 ID、专属稳定编号(视图树路径 + 哈希,每次一致,便于反馈定位)、所属页面;
  3. 再点气泡退出抓取模式。
该能力仅在本 App 自身的 Activity 内生效,用于调试反馈;跨 App 命中需要系统级辅助,不在范围内。

安全与权限小结

灵逸 MB · 开发者文档  |  10Y-灵逸云科技  |  MIT License