[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"article:portable-remote-16a2d947":3},{"article":4,"revisions":15},{"id":5,"author_id":6,"firmware_project_id":7,"slug":8,"published_revision_id":9,"visibility":10,"moderation_lock_reason":11,"version":12,"created_at":13,"updated_at":14},"ebcfde1d-ce03-4580-9cd8-120d6c85cb19","b0b979c8-0f4e-425f-ba4c-2fbc494aa122","16a2d947-e3dd-4751-8101-ed32175057da","portable-remote-16a2d947","21524853-5e4e-406f-b111-e6c88b3b6baf","public",null,17,"2026-10-03T05:30:42.131Z","2026-10-05T02:40:29.539Z",[16],{"id":9,"article_id":5,"revision_no":17,"state":18,"source_revision_id":19,"change_summary":20,"version":21,"submitted_at":22,"reviewed_at":23,"published_at":14,"created_at":24,"description":25,"rendered_description":26,"content":27},3,"published","b320d8f7-62ba-4a61-9747-c264d47b9cfc","1.0.1 真机验证更新：支持安装后通过 USB 保存私人桥接配置，增加设备输入及传感器诊断，统一版本标识。按钮和加速度计通过设备检查；本机防火墙仍阻断真实联动。",7,"2026-10-03T14:48:23.682Z","2026-10-05T02:40:29.520Z","2026-10-03T14:38:16.852Z","# Portable Remote · 随身遥控器\n\n用 ESP-Mosaico 的 480 × 480 触摸屏和运动传感器，通过 Wi-Fi 遥控 Mac 的“音乐”应用，也可切换到已配置的 Home Assistant 媒体播放器。需要一台运行附件 Python 桥接程序的 Mac，无需扩展子板。\n\n![随身遥控器真机画面](\u002Fapi\u002Fv1\u002Ffiles\u002Faus_072bae599a8e2b43a8548330e6694f7ba5c0ee3fae1a34a083a73bc1b49b3b92.webp)\n\n## 操作\n\n- **Prev \u002F Play \u002F Next**：上一首、播放或暂停、下一首。\n- **Volume − \u002F Volume +**：调整当前目标的音量。\n- 点击 **Next target（切换目标）** 或左右滑动，在 Mac 音乐和已配置的 Home Assistant 播放器之间切换。\n- 持续按住屏幕后，相对起始姿态倾斜设备可调节音量；摇晃可取消本次按住触发的倾斜控制，但无法撤销已经发送的指令。\n\nMac 控制使用固定的 AppleScript 指令操作“音乐”和系统输出音量，首次使用时 macOS 可能要求授予“自动化”权限。若需要 Home Assistant 播放器，请在桥接电脑上设置 `HA_URL`、私密的 `HA_TOKEN` 和 `MOSAICO_MEDIA_PLAYER`；未配置时仅支持 Mac 音乐。本版本不包含语音识别、蓝牙 HID 或演示文稿控制。\n\n## 使用前配置\n\n**当前为开发预览版。固件不包含私人桥接地址或令牌，可安装后通过 USB 保存配置，无需为个人凭据重新构建。** 本版本仍需电脑运行桥接程序，屏幕内没有文字输入配置页。\n\n1. 安装提供的 1.0.1 Iris 固件，并在 Vibe Mode 中配置 Wi-Fi；应用复用已保存的网络。\n2. 在桥接电脑上安装 Python 3.10 或以上版本，通过环境变量 `MOSAICO_BRIDGE_TOKEN` 设置至少 24 个字符的随机私密令牌。\n3. 运行附件中的 `python3 projects\u002Fideas_common\u002Fbridge.py --bind 0.0.0.0 --port 8765`。电脑和设备应位于能互相访问的局域网；电脑防火墙须允许桥接程序接收连接。程序默认仅监听本机，局域网访问需要显式指定监听地址。\n4. 在同一开发工作区，用 `python3 mosaico.py iris device-status --project projects\u002Fportable_remote --json` 确认 USB 连接和 Device ID。\n5. 保持相同的 `MOSAICO_BRIDGE_TOKEN` 环境变量，执行 `python3 projects\u002Fideas_common\u002Fconfigure_device.py --project portable_remote --device-id \u003CDevice-ID> --url https:\u002F\u002F\u003C桥接地址>:8765`。设置仅保存在板上的应用 NVS 中；配置程序会检查当前运行的应用和 USB 身份，响应不会返回令牌。\n6. HTTPS 可通过 `bridge.py --cert \u003C证书> --key \u003C私钥>` 启用；证书须受设备证书包信任，证书校验不会关闭。仅在可信局域网使用明文 HTTP 时，将 URL 改为 `http:\u002F\u002F...` 并显式添加 `--allow-http`。\n7. 清除配置时运行相同的配置命令并使用 `--clear`。不要公开令牌、个人构建配置或私密诊断日志。旧的 menuconfig 构建配置仍可使用，但不需要嵌入私人凭据来使用公开固件。\n\n在使用固定 ESP-IDF 的工作区根目录执行：\n\n```sh\npython3 submodule\u002Fesp-mosaico-utils\u002Fmosaico-tools\u002Fskills\u002Fidf-low-noise-build\u002Fscripts\u002Fidf_low_noise_build.py --project projects\u002Fportable_remote build\npython3 projects\u002Fideas_common\u002Ftests\u002Fcheck_bridge.py\npython3 projects\u002Fideas_common\u002Ftests\u002Fcheck_ui.py\n```\n\n提供的 1.0.1 Iris 包面向配备 16 MiB Flash、保留 Vibe Mode\u002FRecovery 的 ESP32-S31，包含应用、分区表及界面数据。配置缺失、网络离线、认证失败和上游异常会显示在屏幕上；失败指令不会自动重发，出错后保留的读数会标注为上次结果。桥接服务的每个进程只保存一台遥控器的当前控制目标。\n\n## 验证情况\n\n1.0.1 已在 ESP32-S31 实机上安装，通过设备真实画面和 USB 注入触控检查所有六个按钮、请求路由、非法输入拒绝及同一启动期间的稳定性；应用崩溃计数为零。真机加速度计读取正常，重力大小检查通过。USB 配置保存、清除及输入校验已验证，公开固件仍不含私人配置。源代码逻辑检查、ESP-IDF 构建和原生模拟器检查也已通过。\n\n真实 Home Assistant 设备联动尚未验证。Mac 桥接程序读取本机音量成功，但板端连接被本机防火墙规则阻断，真实播放及音量控制尚未完成。USB 注入触控不等同于手指操作触摸控制器的验收。详情和安装过程限制见附件中的 `projects\u002Fideas_common\u002FDEVICE_VALIDATION.md`。\n\n## 源码与资源许可\n\n附件源码包不含凭据或带有个人配置的固件。将其中的 `projects\u002F` 解压到 ESP-Mosaico Vibe 开发工作区，保持本应用与 `ideas_common` 目录同级；构建依赖工作区已有的框架和工具，以及固定的 ESP-IDF 提交 `7b9cc1ac79f865983f59bb8ff3ff43eb74ff1dbe`。\n\n界面使用 DejaVu 字体，详见[字体许可](\u002Fapi\u002Fv1\u002Ffiles\u002Faus_ce4c4683277f71a1de67b757dbdab25e38873a506143b5ad009bbae56d18c616.bin)。框架依赖保留各自许可证，本页面不新增整个仓库的授权条款。\n","\u003Ch1>Portable Remote · 随身遥控器\u003C\u002Fh1>\n\u003Cp>用 ESP-Mosaico 的 480 × 480 触摸屏和运动传感器，通过 Wi-Fi 遥控 Mac 的“音乐”应用，也可切换到已配置的 Home Assistant 媒体播放器。需要一台运行附件 Python 桥接程序的 Mac，无需扩展子板。\u003C\u002Fp>\n\u003Cp>\u003Cimg src=\"\u002Fapi\u002Fv1\u002Ffiles\u002Faus_072bae599a8e2b43a8548330e6694f7ba5c0ee3fae1a34a083a73bc1b49b3b92.webp\" alt=\"随身遥控器真机画面\" \u002F>\u003C\u002Fp>\n\u003Ch2>操作\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Cstrong>Prev \u002F Play \u002F Next\u003C\u002Fstrong>：上一首、播放或暂停、下一首。\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Volume − \u002F Volume +\u003C\u002Fstrong>：调整当前目标的音量。\u003C\u002Fli>\n\u003Cli>点击 \u003Cstrong>Next target（切换目标）\u003C\u002Fstrong> 或左右滑动，在 Mac 音乐和已配置的 Home Assistant 播放器之间切换。\u003C\u002Fli>\n\u003Cli>持续按住屏幕后，相对起始姿态倾斜设备可调节音量；摇晃可取消本次按住触发的倾斜控制，但无法撤销已经发送的指令。\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Mac 控制使用固定的 AppleScript 指令操作“音乐”和系统输出音量，首次使用时 macOS 可能要求授予“自动化”权限。若需要 Home Assistant 播放器，请在桥接电脑上设置 \u003Ccode>HA_URL\u003C\u002Fcode>、私密的 \u003Ccode>HA_TOKEN\u003C\u002Fcode> 和 \u003Ccode>MOSAICO_MEDIA_PLAYER\u003C\u002Fcode>；未配置时仅支持 Mac 音乐。本版本不包含语音识别、蓝牙 HID 或演示文稿控制。\u003C\u002Fp>\n\u003Ch2>使用前配置\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>当前为开发预览版。固件不包含私人桥接地址或令牌，可安装后通过 USB 保存配置，无需为个人凭据重新构建。\u003C\u002Fstrong> 本版本仍需电脑运行桥接程序，屏幕内没有文字输入配置页。\u003C\u002Fp>\n\u003Col>\n\u003Cli>安装提供的 1.0.1 Iris 固件，并在 Vibe Mode 中配置 Wi-Fi；应用复用已保存的网络。\u003C\u002Fli>\n\u003Cli>在桥接电脑上安装 Python 3.10 或以上版本，通过环境变量 \u003Ccode>MOSAICO_BRIDGE_TOKEN\u003C\u002Fcode> 设置至少 24 个字符的随机私密令牌。\u003C\u002Fli>\n\u003Cli>运行附件中的 \u003Ccode>python3 projects\u002Fideas_common\u002Fbridge.py --bind 0.0.0.0 --port 8765\u003C\u002Fcode>。电脑和设备应位于能互相访问的局域网；电脑防火墙须允许桥接程序接收连接。程序默认仅监听本机，局域网访问需要显式指定监听地址。\u003C\u002Fli>\n\u003Cli>在同一开发工作区，用 \u003Ccode>python3 mosaico.py iris device-status --project projects\u002Fportable_remote --json\u003C\u002Fcode> 确认 USB 连接和 Device ID。\u003C\u002Fli>\n\u003Cli>保持相同的 \u003Ccode>MOSAICO_BRIDGE_TOKEN\u003C\u002Fcode> 环境变量，执行 \u003Ccode>python3 projects\u002Fideas_common\u002Fconfigure_device.py --project portable_remote --device-id <Device-ID> --url https:\u002F\u002F<桥接地址>:8765\u003C\u002Fcode>。设置仅保存在板上的应用 NVS 中；配置程序会检查当前运行的应用和 USB 身份，响应不会返回令牌。\u003C\u002Fli>\n\u003Cli>HTTPS 可通过 \u003Ccode>bridge.py --cert <证书> --key <私钥>\u003C\u002Fcode> 启用；证书须受设备证书包信任，证书校验不会关闭。仅在可信局域网使用明文 HTTP 时，将 URL 改为 \u003Ccode>http:\u002F\u002F...\u003C\u002Fcode> 并显式添加 \u003Ccode>--allow-http\u003C\u002Fcode>。\u003C\u002Fli>\n\u003Cli>清除配置时运行相同的配置命令并使用 \u003Ccode>--clear\u003C\u002Fcode>。不要公开令牌、个人构建配置或私密诊断日志。旧的 menuconfig 构建配置仍可使用，但不需要嵌入私人凭据来使用公开固件。\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>在使用固定 ESP-IDF 的工作区根目录执行：\u003C\u002Fp>\n\u003Cpre>\u003Ccode>python3 submodule\u002Fesp-mosaico-utils\u002Fmosaico-tools\u002Fskills\u002Fidf-low-noise-build\u002Fscripts\u002Fidf_low_noise_build.py --project projects\u002Fportable_remote build\npython3 projects\u002Fideas_common\u002Ftests\u002Fcheck_bridge.py\npython3 projects\u002Fideas_common\u002Ftests\u002Fcheck_ui.py\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>提供的 1.0.1 Iris 包面向配备 16 MiB Flash、保留 Vibe Mode\u002FRecovery 的 ESP32-S31，包含应用、分区表及界面数据。配置缺失、网络离线、认证失败和上游异常会显示在屏幕上；失败指令不会自动重发，出错后保留的读数会标注为上次结果。桥接服务的每个进程只保存一台遥控器的当前控制目标。\u003C\u002Fp>\n\u003Ch2>验证情况\u003C\u002Fh2>\n\u003Cp>1.0.1 已在 ESP32-S31 实机上安装，通过设备真实画面和 USB 注入触控检查所有六个按钮、请求路由、非法输入拒绝及同一启动期间的稳定性；应用崩溃计数为零。真机加速度计读取正常，重力大小检查通过。USB 配置保存、清除及输入校验已验证，公开固件仍不含私人配置。源代码逻辑检查、ESP-IDF 构建和原生模拟器检查也已通过。\u003C\u002Fp>\n\u003Cp>真实 Home Assistant 设备联动尚未验证。Mac 桥接程序读取本机音量成功，但板端连接被本机防火墙规则阻断，真实播放及音量控制尚未完成。USB 注入触控不等同于手指操作触摸控制器的验收。详情和安装过程限制见附件中的 \u003Ccode>projects\u002Fideas_common\u002FDEVICE_VALIDATION.md\u003C\u002Fcode>。\u003C\u002Fp>\n\u003Ch2>源码与资源许可\u003C\u002Fh2>\n\u003Cp>附件源码包不含凭据或带有个人配置的固件。将其中的 \u003Ccode>projects\u002F\u003C\u002Fcode> 解压到 ESP-Mosaico Vibe 开发工作区，保持本应用与 \u003Ccode>ideas_common\u003C\u002Fcode> 目录同级；构建依赖工作区已有的框架和工具，以及固定的 ESP-IDF 提交 \u003Ccode>7b9cc1ac79f865983f59bb8ff3ff43eb74ff1dbe\u003C\u002Fcode>。\u003C\u002Fp>\n\u003Cp>界面使用 DejaVu 字体，详见\u003Ca href=\"\u002Fapi\u002Fv1\u002Ffiles\u002Faus_ce4c4683277f71a1de67b757dbdab25e38873a506143b5ad009bbae56d18c616.bin\" rel=\"nofollow noopener noreferrer\">字体许可\u003C\u002Fa>。框架依赖保留各自许可证，本页面不新增整个仓库的授权条款。\u003C\u002Fp>\n",{"title":28,"categories":29,"boards":33,"tags":34,"cover_images":35,"external_links":37,"attachments":38,"current_version":44,"license":45,"firmware_variants":46},"Portable Remote",[30,31,32],"communication","audio","display",[],[],[36],"\u002Fapi\u002Fv1\u002Ffiles\u002Faus_072bae599a8e2b43a8548330e6694f7ba5c0ee3fae1a34a083a73bc1b49b3b92.webp",[],[39],{"id":40,"name":41,"size":42,"media_type":43,"upload_id":40},"aus_8efda1227c2e0dcdb243a45fa10d61324214647b6f46de18809b4cb6dc9c9217.zip","portable_remote-source.zip",782753,"application\u002Foctet-stream","1.0.1","",[47],{"type":48,"partitions":49,"iris":50},"iris",[],{"bundle_asset_id":51},"aus_76a0b450e8b5e1c80c555389b23f88c0955fff73c9241298fda65684e73a45f3.irisfw"]