已发布项目

portable-remote-16a2d947

Revision 3

1.0.1 真机验证更新：支持安装后通过 USB 保存私人桥接配置，增加设备输入及传感器诊断，统一版本标识。按钮和加速度计通过设备检查；本机防火墙仍阻断真实联动。

Portable Remote · 随身遥控器

用 ESP-Mosaico 的 480 × 480 触摸屏和运动传感器，通过 Wi-Fi 遥控 Mac 的“音乐”应用，也可切换到已配置的 Home Assistant 媒体播放器。需要一台运行附件 Python 桥接程序的 Mac，无需扩展子板。

随身遥控器真机画面

操作

  • Prev / Play / Next：上一首、播放或暂停、下一首。
  • Volume − / Volume +：调整当前目标的音量。
  • 点击 Next target（切换目标） 或左右滑动，在 Mac 音乐和已配置的 Home Assistant 播放器之间切换。
  • 持续按住屏幕后，相对起始姿态倾斜设备可调节音量；摇晃可取消本次按住触发的倾斜控制，但无法撤销已经发送的指令。

Mac 控制使用固定的 AppleScript 指令操作“音乐”和系统输出音量，首次使用时 macOS 可能要求授予“自动化”权限。若需要 Home Assistant 播放器，请在桥接电脑上设置 HA_URL、私密的 HA_TOKEN 和 MOSAICO_MEDIA_PLAYER；未配置时仅支持 Mac 音乐。本版本不包含语音识别、蓝牙 HID 或演示文稿控制。

使用前配置

当前为开发预览版。固件不包含私人桥接地址或令牌，可安装后通过 USB 保存配置，无需为个人凭据重新构建。 本版本仍需电脑运行桥接程序，屏幕内没有文字输入配置页。

  1. 安装提供的 1.0.1 Iris 固件，并在 Vibe Mode 中配置 Wi-Fi；应用复用已保存的网络。
  2. 在桥接电脑上安装 Python 3.10 或以上版本，通过环境变量 MOSAICO_BRIDGE_TOKEN 设置至少 24 个字符的随机私密令牌。
  3. 运行附件中的 python3 projects/ideas_common/bridge.py --bind 0.0.0.0 --port 8765。电脑和设备应位于能互相访问的局域网；电脑防火墙须允许桥接程序接收连接。程序默认仅监听本机，局域网访问需要显式指定监听地址。
  4. 在同一开发工作区，用 python3 mosaico.py iris device-status --project projects/portable_remote --json 确认 USB 连接和 Device ID。
  5. 保持相同的 MOSAICO_BRIDGE_TOKEN 环境变量，执行 python3 projects/ideas_common/configure_device.py --project portable_remote --device-id <Device-ID> --url https://<桥接地址>:8765。设置仅保存在板上的应用 NVS 中；配置程序会检查当前运行的应用和 USB 身份，响应不会返回令牌。
  6. HTTPS 可通过 bridge.py --cert <证书> --key <私钥> 启用；证书须受设备证书包信任，证书校验不会关闭。仅在可信局域网使用明文 HTTP 时，将 URL 改为 http://... 并显式添加 --allow-http。
  7. 清除配置时运行相同的配置命令并使用 --clear。不要公开令牌、个人构建配置或私密诊断日志。旧的 menuconfig 构建配置仍可使用，但不需要嵌入私人凭据来使用公开固件。

在使用固定 ESP-IDF 的工作区根目录执行：

python3 submodule/esp-mosaico-utils/mosaico-tools/skills/idf-low-noise-build/scripts/idf_low_noise_build.py --project projects/portable_remote build
python3 projects/ideas_common/tests/check_bridge.py
python3 projects/ideas_common/tests/check_ui.py

提供的 1.0.1 Iris 包面向配备 16 MiB Flash、保留 Vibe Mode/Recovery 的 ESP32-S31，包含应用、分区表及界面数据。配置缺失、网络离线、认证失败和上游异常会显示在屏幕上；失败指令不会自动重发，出错后保留的读数会标注为上次结果。桥接服务的每个进程只保存一台遥控器的当前控制目标。

验证情况

1.0.1 已在 ESP32-S31 实机上安装，通过设备真实画面和 USB 注入触控检查所有六个按钮、请求路由、非法输入拒绝及同一启动期间的稳定性；应用崩溃计数为零。真机加速度计读取正常，重力大小检查通过。USB 配置保存、清除及输入校验已验证，公开固件仍不含私人配置。源代码逻辑检查、ESP-IDF 构建和原生模拟器检查也已通过。

真实 Home Assistant 设备联动尚未验证。Mac 桥接程序读取本机音量成功，但板端连接被本机防火墙规则阻断，真实播放及音量控制尚未完成。USB 注入触控不等同于手指操作触摸控制器的验收。详情和安装过程限制见附件中的 projects/ideas_common/DEVICE_VALIDATION.md。

源码与资源许可

附件源码包不含凭据或带有个人配置的固件。将其中的 projects/ 解压到 ESP-Mosaico Vibe 开发工作区，保持本应用与 ideas_common 目录同级；构建依赖工作区已有的框架和工具，以及固定的 ESP-IDF 提交 7b9cc1ac79f865983f59bb8ff3ff43eb74ff1dbe。

界面使用 DejaVu 字体，详见字体许可。框架依赖保留各自许可证，本页面不新增整个仓库的授权条款。