8. 扫码配置设备（Scan-to-Configure）

面向管理员

本章面向持有云账号与密钥的管理员。现场采集人员不需要阅读，可直接跳过。

把多项设备设置（采集元信息、云端上传（OSS / COS / S3 / GCS / Azure）、自动上传、码率、分辨率、Wi-Fi，以及可选的录制加密密钥）编码进一张二维码，用 App 扫码即可一键写入设备。适合批量部署：同一张二维码可复用，对每台设备各扫一次（逐台应用，并非一次配置多台）。

整个流程分两步：① 技术员用官方工具生成二维码（打印或显示在屏幕上）；② 操作员在 App 里扫码并应用到已连接的设备。

一、生成配置二维码（技术员）

生成工具：visio-settings-qr（包含在公开的 visio-schema Python 包中，需 Python 3.10 及以上）。安装：pip install "visio_schema-0.9.1.tar.gz[display,qr]"（离线源码包见「7. 工程集成与数据格式」附件），或联网安装 pip install "visio-schema[qr]"。

方式 A：从 JSON 配置文件生成

参考下方「配置示例」，改成你的配置（见下方「可配置项」），保存为例如 my.json，然后：

# 生成二维码 PNG
visio-settings-qr --config my.json --out qr.png

# 只校验配置、不生成
visio-settings-qr --config my.json --check-only

# 打印 App 实际会解析的内容（不生成图片）
visio-settings-qr --config my.json --dry-run

方式 B：交互式生成

不带 --config 直接运行，工具会先选择提示语言（或加 --lang zh），再逐段询问采集元信息 / 云端上传（含服务商选择）/ 自动上传 / 码率 / 分辨率 / Wi-Fi，最后询问是否设置录制加密密钥（见「12. 录制数据加密」）；密钥与 Wi-Fi 密码输入不回显：

visio-settings-qr --out factory7_qr.png

配置示例（JSON）

{
  "t": "visio-settings",
  "v": 1,
  "meta": { "task": "pick-and-place", "location": "Suzhou line 2", "message": "", "capturer": "operator-7" },
  "storage": {
    "endpoint_url": "https://oss-cn-hangzhou.aliyuncs.com",
    "region": "cn-hangzhou",
    "bucket": "gilabs-captures",
    "access_key_id": "LTAI5EXAMPLEKEYID",
    "secret_access_key": "EXAMPLEsecret",
    "prefix": "factory-7/"
  },
  "auto_upload": true,
  "bitrate_kbps": 8000,
  "resolution": { "width": 1920, "height": 1080 },
  "wifi": { "ssid": "FactoryNet", "passphrase": "hunter22" }
}

每个区块都可选，但至少要有一个；字段名用 snake_case。字段说明：

区块 / 字段	含义	规则
meta.task / location / message / capturer	采集元信息默认值	上限（固件 1.1.6 起）：task、capturer 各约 85 个汉字 / 255 个英文字符；location 约 170 个汉字 / 511 个英文字符；message 约 341 个汉字 / 1023 个英文字符。超长时该项不会生效；更早固件的上限约为上述的四分之一，建议先升级固件。四项整体覆盖，留空的字段会被清空
storage.endpoint_url	对象存储接入点（OSS / COS / S3 / GCS / Azure）	含 storage 时必填，须为 http(s):// 开头
storage.region	地域	OSS / COS / S3 的标准域名可自动推断；GCS 需填写（可填 auto）；Azure 不需要
storage.bucket / access_key_id	存储桶 / 访问密钥 ID	必填
storage.secret_access_key	私有密钥	可留空——保留设备已存的密钥（仅当接入点与访问密钥 ID 都与设备当前配置相同时）
storage.prefix	路径前缀	用 visio-settings-qr 生成时默认 recordings/；手写 JSON 不填时，录像直接存到存储桶根目录。结尾的 / 会自动补上
auto_upload	是否自动上传	true / false
bitrate_kbps	视频码率	整数 500–50000；重启后生效
resolution.width / height	相机分辨率	各 240–4096，且须为设备支持的分辨率；重启后生效
wifi.ssid	设备要连接的 Wi-Fi	含 wifi 时必填，≤ 32 字节
wifi.passphrase	Wi-Fi 密码	如填须 8–63 字符；留空 = 开放网络

安全提示：默认生成的二维码会把存储私有密钥与录制密钥加密封装，只有设备固件能解开（确认页显示「已封装在二维码内」）；但 Wi-Fi 密码仍是明文。用 --plaintext 生成的旧版二维码中密钥也是明文。含 Wi-Fi 密码的二维码请当作写下来的密码妥善保管，用完及时销毁。

二、在 App 扫码并应用（操作员）

先确保要配置的设备已在 App 中连接 / 在线（扫码本身可离线，但应用设置需要与设备的实时连接）。

1. 打开设备详情页 → 点右上角的扫码图标（标签「扫码设置 / Scan settings」，在齿轮设置图标旁；仅设备已连接时显示）。
2. 扫码：将相机对准二维码（提示语「将相机对准 Visio 设置二维码」）。首次使用请允许相机权限；HarmonyOS 会调用系统「扫一扫」。Android / iOS 也可点「从相册选择」识别已保存的二维码图片。
3. 确认：App 逐项列出将写入的设置（密钥 / 密码已打码），提示「设备将被设置为以下值。点击“应用”前不会发送任何内容。」核对无误后点 「应用到设备 / Apply to device」。
4. 应用：各项按 录制加密（如有）→ 采集元信息 → 云端上传 → 自动上传 → 码率 → 分辨率 → Wi-Fi（最后） 依次下发，每项显示 转圈 →（绿勾 / 红叉）。
5. 完成：查看结果汇总，点「完成」。

Wi-Fi 最后应用、可能断开：若二维码含 Wi-Fi，设备会切换网络、App 可能短暂断开——之后 App 会尝试跟随到新网络；如未自动重连，请把手机接入设备的新 Wi-Fi 后重新发现设备。码率 / 分辨率需重启设备后生效（完成页会提示）。录制加密一项失败时，其余各项不再下发；其他单项失败不影响后续项。

三、常见提示与排查

提示	含义 / 处理
这不是 Visio 设置二维码	扫到的不是本功能的二维码；用 visio-settings-qr 重新生成。
此设置二维码需要更新版本的应用	二维码版本比 App 新；升级 App 后再扫。
设置二维码包含无效字段	某字段超出范围（如码率不在 500–50000）；修正配置后重新生成。
无法加入 Wi-Fi（设备无法加入“…”，已返回其热点）	Wi-Fi 名称或密码有误；修正二维码中的 wifi 配置后重新生成。
要配置多台设备	用同一张二维码对每台设备各扫一次（逐台应用）。

配置二维码的内容格式见上方示例。默认的加密二维码需用 visio-settings-qr 生成；如可接受密钥明文，也可把上述 JSON（"v": 1）用任意二维码工具编码（纠错级别 M 即可）。

深入了解

一张码可携带的区块

区块	设置的内容
采集元信息	任务、地点、备注、采集者
云端上传	端点、区域、存储桶、访问密钥 ID、私有密钥、前缀
自动上传	开或关
视频码率	500–50000 kbps；重启后生效
相机分辨率	宽与高；重启后生效
设备 Wi-Fi	网络名与密码

私有密钥可以省略，仅当端点与访问密钥 ID 都未改变时，设备保留已有的密钥——适合在不重印凭据的情况下给整批设备换 Wi-Fi。Wi-Fi 最后应用，因为设备此时切换网络、手机可能失去联系；App 会尽量跟随设备到新网络。

加密的设置二维码

自 App 1.1.3 起，App 可以读取新版（加密）的设置二维码，旧版明文二维码继续支持。录制密钥只会以加密二维码分发：码里的密钥是封装过的，只有设备固件能解开；若要限制为指定设备，必须显式加 --device，见 12. 录制数据加密。

把站点配置纳入版本控制

用 JSON 文件生成二维码，可以把每个站点的配置放进版本库，做到可复现：--check-only 只校验不生成，--dry-run 打印 App 实际解析的负载。密钥不要提交到版本库——在文件里留空、让设备保留已有密钥，或在生成时用隐藏输入。