7. 工程集成与数据格式
面向需要用 Python 直接对接数据流 / 解析录制的工程师。本页会用到命令行与 Python。
数据流概览
Ego 数据以标准 MCAP 格式录制（Foxglove 原生、自带消息 schema、自描述），可用开源的 visio-schema Python 包解析。同一份数据可通过多种通道获取：
| 通道 | 形式 | 用途 |
|---|---|---|
| USB 串口 | Windows 为 COMx，Linux 为 /dev/ttyACM0 | 直连、低延迟 |
| TCP（设备热点） | 设备热点下的 192.168.4.1:50001 | 经设备热点连接 |
| TCP（同一 Wi-Fi） | GILABS-XXXXXXXX.local:50001 | 设备已连接 Wi-Fi 时，电脑接入同一网络即可连接 |
| USB 网络 | USB 连接电脑后出现的有线网卡，地址 GILABS-XXXXXXXX.local:50001（固件 1.1.6 起） | 免 Wi-Fi 的高速连接 |
| 文件（MCAP） | SD 卡上的 .mcap 文件 | 离线分析 |
| USB 存储（MTP） | USB 连接电脑后出现「Visio Storage」便携设备 | 免取卡拷贝 / 删除 SD 卡上的录制 |
录制中的频道（channels）
| Topic | Schema | 内容 |
|---|---|---|
| /ego/camera/0 | foxglove.CompressedVideo | 右目 H.265（cam0 = 右目 = 坐标锚点） |
| /ego/camera/1 | foxglove.CompressedVideo | 左目 H.265 |
| /ego/camera/0/intrinsics | foxglove.CameraCalibration | 右目内参 |
| /ego/camera/1/intrinsics | foxglove.CameraCalibration | 左目内参 |
| /ego/camera/1/extrinsics | foxglove.FrameTransform | 左目相对右目位姿（cam0 为锚点） |
| /ego/camera/0/frame_info /ego/camera/1/frame_info | visio_schema…sensor.CameraFrameInfo | 每帧曝光信息（曝光时长、曝光中点偏移、增益、逐行读出时序），时间戳与同目视频帧相同（固件 1.1.6 起）。Foxglove 可直接查看；用 Python 解析需比 0.9.1 更新的 visio-schema |
| /ego/imu/0/raw | visio_schema…sensor.ImuRaw | IMU 原始样本（成束） |
| /ego/imu/0/quat | visio_schema…ros.geometry_msgs.Quaternion | 融合姿态四元数 |
| /ego/imu/0/extrinsics | foxglove.FrameTransform | IMU 相对右目（cam0）位姿 |
| /ego/audio/0 | foxglove.RawAudio | 立体声音频（PCM S16，仅 EGO1GS） |
| /ego/system_health | visio_schema…sensor.SystemHealth | CPU / 温度 / 磁盘 / 客户端数等设备状态 |
说明：以 cam0（右目）为坐标锚点，其余相机 / IMU 的外参均相对 cam0 给出。EGO1GS 额外包含一路立体声音频频道；开启手部识别时还有 /ego/camera/0/annotations（foxglove.ImageAnnotations，手部方框，见「13. 手部识别」）。录制中另有 /ego/imu/0/info（IMU 信息）以及 /ego/command_result、/ego/diag_log 等内部频道，解析时请按 topic 过滤。
安装 visio-schema
使用随手册附带的离线源码包安装（当前版本 0.9.1，需要 Python 3.10 及以上）：
pip install "visio_schema-0.9.1.tar.gz[display,qr]"
安装请务必带上 [display] extra——visio-display 的 Rerun 可视化、H.265 解码与 --serve 控制台所需依赖都在其中；[qr] 用于生成设置二维码图片。安装后可用命令：visio-display、visio-settings-qr、visio-decrypt。
visio-display 命令行
一个数据源 + 至少一个输出：
# 实时串口 → MCAP 录制（无界面）
visio-display --serial /dev/ttyACM0 --out capture.mcap
# 实时 TCP（设备 50001 端口）→ 录制
visio-display --tcp 192.168.4.1:50001 --out capture.mcap
# 回放一个 MCAP 到 Rerun 可视化
visio-display --mcap-in capture.mcap --rerun
# 实时流 → Foxglove WebSocket 桥
visio-display --tcp 192.168.4.1:50001 --foxglove
常用参数：--serial PORT / --tcp HOST[:PORT] / --mcap-in FILE / --serve（源，四选一；--serve 为图形化本地控制台，可发现设备、回放录制、设置加密）；--out FILE.mcap / --foxglove [--port 8765] / --rerun（输出；--mcap-in 只支持 --out / --rerun）；加密录制加 --key-file（见「12. 录制数据加密」）。TCP 端口为 50001，连接时请显式写 :50001。
在 Foxglove Studio 看实时流
Visio Launcher（visio-display）：发现设备并在 Foxglove 打开
Foxglove Studio 不能直接连设备，需要先用 visio-display 起一个 Foxglove WebSocket 桥：
visio-display --tcp 192.168.4.1:50001 --foxglove
# 输出：Foxglove WebSocket server on ws://localhost:8765
然后在 Foxglove Studio 中 Open connection → Foxglove WebSocket → ws://localhost:8765。查看已录制文件则不需要桥，直接 File ▸ Open local file 打开 .mcap（加密录制需先用 visio-decrypt 生成明文副本，见「12. 录制数据加密」）。
用 Python 读取数据
from visio_schema import read_mcap, read_serial, message_class
# 读取录制：msg.payload 是原始字节，用 message_class 按 schema 解码
for msg, channel in read_mcap("capture.mcap"):
if channel.topic == "/ego/imu/0/quat":
quat = message_class(channel.schema_name)()
quat.ParseFromString(msg.payload)
print(quat)
# 或实时读串口（同样是 (msg, channel)，payload 为字节，需解码）
for msg, channel in read_serial("/dev/ttyACM0"):
...
更多稳定 API：serial_endpoint(path)（双向，可下发命令）、McapWriter(path)、ChannelRegistry、message_class(schema_name) 等。
若录制已加密，read_mcap 会自动从本机钥匙串 ~/.config/visio/recording-keys.json 或环境变量 VISIO_RECORDING_KEY_FILE 获取密钥。
网络与端口速查
| 名称 | 值 |
|---|---|
| 设备热点 SSID | GILABS-XXXXXXXX（开放，无需密码） |
| 热点网关 IP | 192.168.4.1 |
| 网页预览（热点） | http://192.168.4.1 |
| 网页预览（同 Wi-Fi） | http://GILABS-XXXXXXXX.local |
| Wi-Fi 信道 | 自动选择：优先 5 GHz（36–48 / 149–165），无可用 5 GHz 时为 2.4 GHz 信道 6；设备已连接 Wi-Fi 时与该 Wi-Fi 同信道 |
| 数据端口 | TCP 50001 |
| Foxglove 桥端口 | ws://localhost:8765（由 visio-display --foxglove 提供） |
术语
- Egocentric（自我中心）采集：从佩戴者第一视角采集。
- MCAP：Foxglove 原生录制容器格式，自带消息 schema。
- IMU：惯性测量单元，本机用于头部姿态。
- MTP：媒体传输协议，USB 连接电脑时用于访问 SD 卡上的录制文件。
附件下载
最新安装包与各平台 visio-display 打包程序（Windows / macOS / Linux）均可从 GitHub Release 获取：visio-schema releases。
以下文件由团队提供 / 随手册附件：
- 手机 App —— Visio Companion（iOS 见 App Store，HarmonyOS 见华为应用市场，Android .apk 见 App 版本更新说明）
- Foxglove 布局文件 —— Ego Foxglove Layout（.json，在 Foxglove 中 Layouts ▸ Import from file 导入）
- visio-schema Python 包（离线源码包）—— visio_schema-0.9.1.tar.gz
📎 Ego-Foxglove-Layout.json (3.0 KB)
📎 visio_schema-0.9.1.tar.gz (641.5 KB)
深入了解
子章节
- 7.1 visio-display 命令行——全部参数、本地控制台（
--serve）、软件解码。 - 7.2 时间戳与 Unix 时间——单调时钟与 Unix 时间的换算。
- 7.3 标定数据——录制自带哪些标定、哪些没有标定、SLAM 管线怎么用。
- 7.4 频道与网络速查——完整的 topic 与端口表。
- 7.5 手部识别数据——
/ego/camera/0/annotations的内容与读取。 - 7.6 读取加密录制——有密钥时怎么打开加密的
.mcap。
自固件 1.0.4 起支持 USB 录制
固件 1.0.4 及更新版本完整支持经 USB 录制与通信；更旧的固件上 USB 只供电。请经 固件升级（OTA）升级。