🕹️

Phone Controller

Connectivity

PhoneController 是一个信号源方块，可将任意智能手机变为无线遥控手柄（包含虚拟摇杆及独立的偏航滚轮）。当该方块被拖拽到画布上时，会生成配对二维码；用手机扫描后即可打开控制页面，展示一个大尺寸屏幕触摸摇杆以及下方的水平偏航滑动条。手机通过与 RemoteSensor 方块相同的 WebRTC 点对点（P2P）信道，以约 30 Hz 的频率将归一化的 X/Y/Yaw 控制量 (−1…+1) 实时推送到仿真环境中 — 全程无需线缆，也无需安装任何 App。

手机端摇杆控制面板支持两种操作模式（下方的偏航滑动条在两种模式下功能完全相同）：

Touch（触摸，默认）：用拇指直接在屏幕虚拟摇杆上拖动，松开时自动回弹复位至中心。
Tilt（体感倾斜）：使用手机的内置姿态传感器（DeviceOrientation）。左右倾斜控制 X 轴，前后倾斜控制 Y 轴。开启该模式时会自动校准当前零位；轻触屏幕可随时重新校准居中。

偏航滑动条位于虚拟摇杆下方的水平控制条 — 左右滑动控制偏航，松手自动归零。无论处于触摸还是倾斜模式，偏航控制始终处于激活状态。

适用于鼠标交互不便的实时动态演示场景：例如操控仿真无人机飞行、控制车辆转向模型，或在控制回路中通过手势实时给定设定值。其 X/Y 输出端口命名与 Joystick2D 完全一致，可作为任何已连线画布摇杆的即插即用无线替代品 — 包括 Fly the Quadcopter (Phone) 示例模板。

输入与输出

Direction	ID	Label	类型	Status
← Out	`x`	X	number	Output
← Out	`y`	Y	number	Output
← Out	`yaw`	Yaw	number	Output

参数

参数	Label	类型	默认值	描述
`playoutDelay`	Playout Delay (ms)	number	`80`	Network jitter buffer. Lower = more responsive control, higher = smoother signal on flaky connections.
`interpolation`	Interpolation	select	`linear`	How to reconstruct the control signal between received joystick packets.
`outputLabels`	Output Labels	vector	`x,y,yaw`

使用示例

手机摇杆 — 姿态控制演示

加载内置的 Phone Joystick — Attitude Demo 示例（方块示例菜单）。您的拇指可以直接控制仿真四轴飞行器的空间姿态：X 轴映射为滚转角设定值，Y 轴映射为俯仰角设定值，各自经过二阶姿态动力学模型处理后渲染在 3D 云台（Gimbal3D）上：

PhoneController ──► [X] ──► Gain(30) ──► 2nd Order System ──► Gimbal3D [roll]
                ──► [Y] ──► Gain(30) ──► 2nd Order System ──► Gimbal3D [pitch]

扫描二维码，点击 Grab Control，启动仿真 — 虚拟无人机将跟随您的拇指灵敏感应。

无线操控完整四轴飞行器模板

在 Fly the Quadcopter (Phone) 模板中（示例菜单 → 控制系统），三路输出均已连线 — x/y 通过增益（Gain）接入滚转与俯仰 PID 回路，yaw 直接接入偏航 PID 回路 — 驱动完整的三轴 PID、电机混控器及 3D 云台。画布上无需再放置任何滑块。

为 PID 控制回路提供手动设定值

PhoneController ──► [Y] ──► Gain ──► (setpoint) Subtraction ──► PIDController → plant

说明与最佳实践

信号源方块：三个通道全部为右侧的输出端口。X 向右为正，Y 向前/向上为正（向上推摇杆输出 +1），Yaw 在滑动条向右为正。
恒定 30 Hz 数据流：即使摇杆居中静止，手机也会持续发送心跳数据，以保持播放缓冲区处于激活状态并稳定延迟估计。
死区设置：手机端内置轻微的死区处理（±0.02），确保手离开摇杆时输出绝对稳定的 0。
仿真等待配对：与所有外部实时硬件方块相同，仿真的启动会被挂起，直到手机成功配对并接收到首批数据包。
需要 WebRTC：手机与电脑均需访问网络以完成 PeerJS 握手。支持使用与 RemoteSensor 相同的 localStorage 键配置自建 PeerJS 握手信令服务器（blockwerk_peer_host / blockwerk_peer_port / blockwerk_peer_path / blockwerk_peer_secure）。
每个框图单个控制器：X/Y/Yaw 通道为全局唯一（remote:joy.x / remote:joy.y / remote:joy.z）；若在同一画布放置两个 PhoneController 方块，两者将接收完全相同的数据。
未连接状态下的输出：在手机连接并开始发送数据前，所有三个端口均保持为 0。