Profile 与多设备模拟

Profile 描述桌面窗口中的设备显示与输入语义。同一个桌面 App 包可以分别放到横屏、竖屏、圆角屏和圆屏中检查布局，无需为每种屏幕重新烧录固件。

1. 当前有哪些 Profile

工作区 Profile 位于 simulator/profiles/<名称>.toml。以下数值来自当前仓库：

四种配置当前都选择 dark 主题并启用标准 UI 手势。屏幕边距排列为上、右、下、左。

tools/simulator.sh ui --profile generic
tools/simulator.sh ui --profile pai-touch
tools/simulator.sh ui --profile sensecap-watcher
tools/simulator.sh ui --profile esp32s31-korvo-1

逐条启动，关闭窗口后再尝试下一种即可比较系统 UI。若 hello 已登记到 catalog，直接运行真实应用：

tools/dev.sh sim hello --profile sensecap-watcher --watch

工作区的 TOML Profile 名称与底层独立程序的内置 compact、phone、round 不是同一套入口。使用工作区脚本时传 TOML 文件名去掉扩展名后的名称。

屏幕实拍：四种 Profile

以下是桌面模拟器的原始帧截图，展示同一组应用目录在不同尺寸、语言和安全区下的启动器布局。09:41 和 86% 电量是截图时设置的模拟状态。图标表示目录中的应用，实际运行仍需要先构建并安装对应桌面包。

pai-touch · 296×240 · 中文 · 圆角半径 58，小屏需要检查标题截断与触控空间。 点击图片查看原图。

generic · 390×844 · 英文，观察长屏下的布局与中英文标题差异。 点击图片查看原图。

sensecap-watcher · 412×412 · 中文 · 四边安全区各 60 像素，重点检查圆形边缘。 点击图片查看原图。

esp32s31-korvo-1 · 800×480 · 中文，观察更宽的应用网格与留白。 点击图片查看原图。

2. 完整 Profile 示例

新建 simulator/profiles/watch-240.toml，内容如下。不要覆盖现有板子的配置：

[desktop]
width = 240
height = 240
round = true
safe_insets = [36, 36, 36, 36]
shape_background = "black"
locale = "zh-CN"
theme = "dark"
gestures = true

这是一块用于布局测试的虚拟圆屏，安全边距是示例值，应按实际产品的有效显示区与交互要求调整。运行：

tools/simulator.sh ui --profile watch-240
tools/dev.sh sim hello --profile watch-240 --watch

Profile 名称只使用小写字母、数字和连字符；传入 watch-240，不是完整文件路径，也不带 .toml。新建 Profile 不需要创建同名 BSP，App 开发可以继续使用默认 --board pai-touch。

3. 字段参考

脚本没有通用的 scale、dpi、rotation 或 GPIO 配置字段；不要凭直觉在 TOML 中加入这些键并期待生效。横竖屏布局测试通过合适的宽高与安全区表达，真实面板旋转和触控变换仍在 BSP 中实现。

当前 product 路径转发尺寸、形状、安全区、背景和语言参数，不直接转发 TOML 的 theme 与 gestures 开关。主题联调应在标准 UI 与实际系统主题通路中验证，不能假定每个运行模式对所有字段都有相同效果。

4. 理解安全区与圆角

safe_insets = [8,10,8,10] 表示顶部 8、右侧 10、底部 8、左侧 10 像素，不是 CSS 的任意简写格式。以 296×240 屏幕为例，减去这些边距的参考区域为 276×224；系统栏或应用布局可能再占据部分区域。

边距是提供给系统和应用的布局信息，不应假设它会自动挪动所有硬编码坐标。按钮、文字和关键提示要明确落在可见安全区；背景或装饰可以延伸到圆角边缘。

shape_background 只影响主机窗口中圆形或圆角面板外部的颜色。PNG 截图的形状外像素保留为透明，不能靠它改变应用实际背景。

5. 同一个包切换不同设备外形

只改变显示形态时，可以构建一次桌面包，然后分别运行：

tools/app.sh build hello --target simulator

tools/simulator.sh product --profile pai-touch \
  --package local/app-output/pai-touch/pxa-hello

tools/simulator.sh product --profile sensecap-watcher \
  --package local/app-output/pai-touch/pxa-hello

命令默认用开发夹具公钥；如果包使用自己的私钥签名，追加 --publisher-key local/keys/publisher-public.der。这里包路径仍在 pai-touch 输出目录，并不妨碍用 Watcher 外形运行；桌面制品 target 仍是 linux-x86_64。

修改 Profile 后重新启动窗口。App watch 只观察 App 目录，不会因你保存 TOML 就重新配置窗口。

6. 中英文、主题与测试矩阵

复制现有 Profile 为 pai-touch-en.toml，把 locale 改为 en-US；再复制一个用于标准 UI 的 pai-touch-light.toml，把 theme 改为 light。为有意义的差异建立小规模矩阵：

语言变化后文本没有变化，先确认应用资源是否提供该语言、是否处理语言事件，以及字体是否包含所需字符。屏幕尺寸变化后不应该仅依靠截图缩放来“通过测试”。

7. 多实例隔离

同一个 Profile 默认共享安装状态。如果要比较两个版本、两个账号状态或首次启动行为，用不同实例名。先构建稳定的桌面包，再启动两个服务：

tools/simulator.sh service start --profile pai-touch --instance demo-a
tools/simulator.sh service start --profile pai-touch --instance demo-b

pxadb package install local/app-output/pai-touch/pxa-hello.pxa --simulator pai-touch@demo-a
pxadb package install local/app-output/pai-touch/pxa-hello.pxa --simulator pai-touch@demo-b
pxadb devices

分别在两个终端打开窗口：

# 终端 A
tools/simulator.sh product --profile pai-touch --instance demo-a --installed pxa-hello

# 终端 B
tools/simulator.sh product --profile pai-touch --instance demo-b --installed pxa-hello

两个运行命令分别占用各自终端，以下截图命令在第三个终端执行。也可以选择用标准 UI 窗口进入已安装应用，但不要让同一实例的两个可见运行器同时争用控制通道。

各实例通过自己的安装目录、socket 与控制通道运行；同一 Profile 的构建目录仍共享，不应同时修改公共构建配置。

pxadb screenshot hello-a.png --simulator pai-touch@demo-a
pxadb screenshot hello-b.png --simulator pai-touch@demo-b

tools/dev.sh 当前没有 --instance，不能把这里的参数直接加到 dev 命令。需要隔离测试时使用上述显式 build → service → install → run 流程。

8. 文件位置与关闭

--state-root 可以覆盖状态目录，PXA_SIMULATOR_SOCKET_ROOT 可以覆盖 socket 父目录；入门阶段使用默认布局更容易与 PXADB 自动发现保持一致。

关闭相关窗口后，停止显式启动的服务：

tools/simulator.sh service stop --profile pai-touch --instance demo-a
tools/simulator.sh service stop --profile pai-touch --instance demo-b

测试干净安装时优先新建实例，不要随意删除正在运行实例的数据目录。

9. 常见问题

Profile 不模拟触控 IC、电源电路、PSRAM 性能和 LCD DMA 时序。完成屏幕适配后，继续板子调试验证真实硬件。