简介：面向 Matlab 开发者的一款游戏杆（Joystick/控制杆/摇杆）调用示例，重点解决将外部摇杆接入科学计算与仿真流程的问题，适合正在学习硬件交互与绘图、需要为实验设备添加手动输入通道的入门到中级用户。通过一个轻量 m 文件，代码集中演示了调用 joystick 读取摇杆数据、删除图形中不需要的曲线，以及利用命令修改曲线 MarkerEdgeColor 这三项核心操作，并串联起“采集输入—更新显示”的典型交互逻辑；其中涉及的句柄获取、对象删除与属性设置技巧，同样适用于动态曲线绘制和旧轨迹清空等常见绘图场景。压缩包采用 rar 格式，整体仅 393B、包含 1 个 m 文件，体积虽小但逻辑完整，无需复杂配置即可直接运行和二次开发，方便迁移至云台转动控制、figure 窗口 viewpoint 改变、无人机摇杆遥控等项目。目前已有 970 人学习/下载，示例既可作为入门教学案例，也可作为进一步封装复杂摇杆控制程序的起点，读者可按需补充滤波、映射或通信模块，形成完整的输入控制系统。整体代码风格简洁、结果反馈直观，是高性价比的 Matlab 交互式控制入门范例。
1. matlab 调用游戏杆：先弄清楚它能干什么再决定怎么用
用 MATLAB 写界面控制程序时，鼠标键盘是默认输入，可一旦涉及机器人、机械臂、无人车这类需要连续比例控制的场景，键盘的离散按键根本不够用——你没法通过按一次键告诉系统“左转 37%”的力度，这时候游戏杆就派上用场了。我最初接触 matlab 调用游戏杆是在一个模拟项目X的遥控端开发里，当时领导丢给我一支手柄，要求两天内把底盘转向和云台俯仰接进去，网上资料东一榔头西一棒子，真正跑通花了不少冤枉时间。市面上翻来覆去就那么几个老脚本，很多还是基于旧版采集函数写的，放到新版本直接报错。这篇文章把我拆这个项目时的完整思路、代码、参数设置和踩过的坑都整理出来，读者对象是那些手里有手柄、想在 MATLAB 里取轴数据和按钮状态的人，无论是做实验控制、仿真交互还是给学生演示，都能照着走通。
2. 读懂输入链路：设备接口、数据格式和回调机制
2.1 游戏杆在 MATLAB 眼中的数据形态
MATLAB 本身不是一个实时操作系统，它对游戏杆的读取本质上是周期性轮询。理解这一点非常重要：手柄插上电脑后，操作系统把它识别成 HID 设备，MATLAB 通过系统底层驱动读取其状态，然后封装成对象属性供你调用。这个过程中有两个核心数据对象：轴（Axis）和按钮（Button）。轴是模拟量输入，对应摇杆的偏转角度和扳机键的按压深度，值通常在 -1 到 1 之间浮动；按钮是数字量输入，只有 0 和 1 两个状态，对应按下与释放。
很多新手上来就找“读取函数”，但真实情况是——MATLAB 2019b 之后再没有单独的读取函数，而是直接面向对象编程。你需要先创建一个游戏杆对象，然后像访问结构体字段一样去取它当前的轴值、按钮值和按键值。我在参与某跨平台系统的研发时，曾经把一套早期版本的采集脚本搬过来用，结果发现所有函数名都变了，整个项目组都卡在那一步。
2.2 设备枚举与支持包选型
在 MATLAB 中调用游戏杆，首先需要确认你手头装的是哪个版本。2019b 之前的版本通常靠vrjoystick这个函数建立对象，它来自虚拟现实工具箱；2019b 之后官方推荐改用get.XboxController这类具体化的构造函数，全称是get.Gamepad系列支持包。在我的实践里，如果你用的是 R2020a 及以后版本，直接依赖系统自带的支持包就能识别大多数主流手柄，包括 XBox 和 PS 系列，但如果用的是老版本，则必须额外安装硬件支持包。
设备枚举这一步很多人会跳过，但它是整个链路的起点。常见做法是用gamingdevices或旧版的joyquery去列出当前已连接的设备，确认系统能看见手柄后再建对象。我一般会把这段枚举代码当成独立脚本存下来，每次接新手柄先跑一遍看 VID 和 PID，避免后面建对象时报“设备不存在”。
2.3 对象属性与回调机制的边界
当你成功创建一个游戏杆对象后，它的属性里会包含轴数、按钮数、轴值、按钮值这几类。需要注意，轴值和按钮值在你调用对象属性的瞬间才会刷新，它不会主动推送数据。这意味着如果你想实现连续控制，必须自己写循环体去反复读取，或者利用 MATLAB 的定时器对象定时触发读取回调。对于 Windows 系统，轮询周期做到 20 毫秒左右就能满足大多数控制需求，对应的采样率是 50Hz；如果做飞行器姿态仿真，建议提到 100Hz，也就是 10 毫秒读一次。
我在模拟项目X中用的是事件驱动式轮询：建立一个timer对象，每 0.02 秒读一次轴值，再调用自定义处理函数把值映射到速度指令。这种方式的好处是读数和响应逻辑解耦，坏处是回调函数里不能做耗时操作，否则定时器会乱套。
3. 初始化与实时读取：环境配置与对象建立
3.1 确认连接状态：设备枚举脚本先行
把物理连接先搞定是第一步。USB 接收器插好后，手柄开机会震动一下，然后在 Windows 控制面板的“游戏控制器”里应该能看到该设备。MATLAB 侧同样需要确认。我长期使用的设备枚举脚本如下，兼容新老两种内核：
% 枚举当前连接的游戏杆，打印设备名称和 ID % 适用于 R2019b 之后版本，老版本可尝试 vrjoystick 系列 try devices = gameroot(); % 查询游戏设备根信息（新版支持包） catch warning('gameroot 不可用，尝试 legacy 查询方式'); end % 另一种稳妥做法：直接建立所有可用控制器对象 ids = 1:4; % 常见系统最多同时挂 4 个控制器 for i = ids try joy = get.Gamepad(i); % 尝试创建第 i 号游戏杆对象 fprintf('设备 %d 连接成功，轴数 %d，按钮数 %d\n', i, joy.AxisCount, joy.ButtonCount); clear joy; catch ME fprintf('设备 %d 不可用: %s\n', i, ME.message); end end这段代码的逻辑是先走新接口，失败则降级。gameroot是查询游戏设备根信息的高层封装函数，新版本基本通用；get.Gamepad(i)则是逐号尝试创建对象，能直接探明哪些口可用。参数说明放在这里：i从 1 开始，对应系统识别到的第一个手柄，不是 USB 口编号。如果你同时插两个同型号手柄，序号可能会有变化，这也是常见的翻车点之一。
3.2 建立对象并读取第一帧数据
设备可见之后，下一步就是正式创建对象并读取第一帧。以下是完整最小工作示例，也可以看作你的“Hello Gamepad”：
% 建立游戏杆对象并读取轴值和按钮值 joy = get.XboxController(1); % 创建 1 号手柄对象，axis 和 button 属性就绪 % 读取当前轴值数组，范围约为 [-1, 1] axes_data = axis(joy); fprintf('当前轴值: [%0.3f, %0.3f, %0.3f]\n', axes_data); % 读取按钮状态数组，元素为 0 或 1 btn_data = button(joy); fprintf('按钮状态: [%d %d %d]\n', btn_data); % 读取当前按键（数字键值），比按钮数组更直观 key_code = key(joy); disp(['当前按下按键编号: ', num2str(key_code)]);这里用的axis、button、key三个函数是新版游戏杆对象的成员方法，注意它们不是工作区里的独立函数，必须通过对象调用。axis返回的行向量长度等于该手柄的物理轴数，左摇杆的 X 和 Y 分别对应前两个分量；button返回的逻辑数组下标和物理按键编号并不是一一对应，这个错位几乎没有例外。若想确认轴序是否正确，建议用手柄动一下左摇杆，同时观察数组哪个分量在变化，然后把该序号记到注释里。
3.3 定时器循环：让数据持续流动
单帧读取只能看到瞬时状态，控制场景必须做成持续读取。常见的做法是 while 循环 + 短暂停，更稳的是 timer 回调。下面给出 while 循环方案的成熟模板：
% 持续读取手柄数据，用 while 循环并以查询式延迟控制频率 joy = get.XboxController(1); run_time = 10; % 共运行 10 秒 sample_rate = 50; % 每秒 50 次读取 line_count = 0; tic; while toc < run_time axes_data = axis(joy); btn_data = button(joy); % 此处插入你自己的控制逻辑或数据记录 % 比如映射到速度值并发送给底层 vel_left = axes_data(1) * 100; % 左摇杆 X 轴映射为左轮速度 vel_right = axes_data(2) * 100; % 右摇杆 Y 轴映射为右轮速度 line_count = line_count + 1; pause(1 / sample_rate); % 控制采样节奏 end % 结束后释放对象 clear joy; fprintf('共采集 %d 帧数据，平均帧间隔约 %0.1f ms\n', line_count, run_time * 1000 / line_count);这个模板里最值得注意的参数是sample_rate和pause(1/sample_rate)。前者决定了控制指令刷新频率，后者是让出 CPU 的最小时间片方案；如果你去掉 pause，循环会以数百赫兹空转，吓到什么先不说，CPU 占用直接飙高。对于需要在 Simulink 里同步的场景，则不建议用这个模板，应该走 Simulink 的输入模块。
4. 把操控数据变成控制量：应用实战与两种联动方式
4.1 从轴值到控制量的线性映射
手柄读到的原始轴值是一个浮点数值，直接拿它去控制电机或仿真对象效果很差，必须映射到目标量纲。最常见的映射是线性映射：
% 将轴值 [-1, 1] 映射到实际物理速度 [-max_speed, max_speed] max_speed = 20; % 单位 m/s raw_axis = axis(joy); % 原始轴值 left_y = raw_axis(2); % 通常对应左摇杆 Y 轴 speed_cmd = left_y * max_speed; % 简单线性映射工程上还常加死区处理，因为摇杆物理回中后轴值不严格为零，零位漂移会让机器人自己慢慢溜车。死区我会取 0.05 或 0.08，具体值手柄型号不同差异不小，新杆取 0.05 足够，旧杆漂移大的要放宽到 0.1：
dead_zone = 0.08; if abs(left_y) < dead_zone speed_cmd = 0; else speed_cmd = left_y * max_speed; end这个死区参数是玄学，调太小会抖动，调太大会丢失细微控制，我一般先用fprintf打印原始值观察静置时的最大抖动幅度，再乘以 2 作为死区。
4.2 按钮的边沿触发与状态锁存
按钮读取最容易犯的错误是把电平状态当成按键事件。所谓电平状态，是你按住的每一帧读到的都是 1，松开就变 0，如果你在循环里判断“如果按钮为 1 就切换开关”，实际效果是按一次会连续反转很多次。正确做法是边沿触发，即只在按钮从 0 变 1 的那一帧触发一次动作。
% 边沿检测：只在按下瞬间触发一次事件 prev_btn = 0; % 记录上一帧按钮状态 while toc < run_time cur_btn = button(joy); % 检测第 1 号按钮是否刚被按下 if cur_btn(1) == 1 && prev_btn == 0 disp('按钮 1 被按下，切换运行模式'); % 在这里执行切换逻辑 end prev_btn = cur_btn(1); pause(0.02); end这段代码的关键变量是prev_btn，它保存上一帧的状态。判断条件严格限定“当前是 1 且之前是 0”，这样长按也不会反复触发。如果你的按钮数组是从button(joy)直接取的，可能某型号手柄返回的是 4×1 列向量，记得先转置或统一用(:)拉平，否则索引会出错。
4.3 联动控制：一个手柄同时驱动速度与云台
示教类应用通常需要同时控制运动平台和云台角度，这涉及多通道数据融合。左摇杆 X/Y 映射前后和转向速度，右摇杆 X/Y 映射云台俯仰和偏航，两个扳机键控制急停和模式切换，一套代码做完：
axes_data = axis(joy); btn_data = button(joy); % 左摇杆: 底盘速度控制 throttle = -axes_data(2); % 前推为负值，取反让前推为正速度 steer = axes_data(1); % 左推为负，正值代表右转 % 右摇杆: 云台姿态控制 pan = axes_data(3); % 右摇杆 X tilt = axes_data(4); % 右摇杆 Y % 映射到底盘指令 v_x = throttle * 0.8; % 最大线速度 0.8 m/s v_yaw = steer * 0.6; % 最大转向角速度 0.6 rad/s % 映射到云台角度增量 pan_target = pan * 180; % 最大 ±180 度 tilt_target = tilt * 90; % 最大 ±90 度 % 急停逻辑：同时按下按钮 1 和按钮 2 才生效 if btn_data(1) && btn_data(2) v_x = 0; v_yaw = 0; fprintf('急停触发!\n'); end这里面有个容易忽略的点：不同手柄的axis返回序号不一定一致，有的把右摇杆排在 3、4 位，有的排到 4、5 位。我拿到新手柄第一件事就是把四个方向都打到最大各停一秒钟，记录下来轴值和序号的对应关系再写进注释，这能避免大量后期调试的痛苦。
4.4 使用 Simulink 模块的联动方案
如果你的控制链路本身建模在 Simulink 里，那争取把游戏杆读取也放到模型里，而不是靠 MATLAB 脚本中转。新版支持包提供 Gamepad 输入模块，双击可配置读取的轴和按钮位，输出直接就是长度为轴数的数组，适合与控制算法模块直接相连。模块输出的采样时间建议设置为 0.01 或 0.02，过小的采样时间会加大求解器负担，过大的会丢失瞬间操作。在模型里做联动时，记得在每个摇杆通道输出后接一个饱和模块，因为轴值虽然在物理上被限制在 [-1, 1] 区间，但数学运算里混入滤波算法时可能会产生违规放大。
5. 避坑实战：这根杆子读不出来的九个常见原因
5.1 “设备未找到”但设备管理器能看到手柄
现象：get.XboxController(1)报错说设备不存在，而 Windows 游戏控制器面板里明明能识别。原因：MATLAB 的硬件支持包没有正确安装或版本不匹配，或者对象序号选错。解决：先运行 3.1 节枚举脚本打印可用序号；如果 1 号确实不对，从 1 到 4 逐个尝试。若全部失败，重新安装支持包，我遇到过一次系统从旧版本跨级升级后支持包失效的情况，重新安装恢复正常的概率非常高。
5.2 单帧读数正常，循环里一读就卡顿高延迟
现象：循环里每读一次数据，看起来要耗几十毫秒到几百毫秒，控制完全没法连续。原因：读数和显示耦合过紧，或者每次循环都调用了disp，控制台刷屏占用了大部分时间。解决：把fprintf和disp单独放到一个节流分支里，比如每 50 帧打印一次；保持循环体里只做轴值读取和逻辑运算。如果仍然卡，检查是否有多余的对象重复创建，确保get.XboxController只在循环外调用一次。
5.3 轴值回中后不为零，小车自动漂移
现象：手没碰摇杆，但输出速度始终有微小非零值，导致仿真或实体平台缓缓移动。原因：摇杆电位器老化或回中精度不够，零位漂移，这个值通常在 0.01 到 0.08 波动。解决：加死区。具体实现参考 4.1 节的代码，死区阈值要覆盖静置漂移的最大幅度。如果漂移值超过 0.1，可以考虑在初始化时记录零偏，后续所有读数都减去零偏再做死区判断。
5.4 同一套脚本换个手柄型号就反了
现象：换了另一款手柄后，左摇杆变成了右摇杆，轴序和按钮序号完全错位。原因：不同品牌的游戏杆轴序映射不同，这个没法靠设置解决，只能靠代码适配。解决：开头统一用 3.2 节测试脚本跑一遍，把手柄的轴序记录为映射表，后续控制代码全部基于映射表索引，而不是硬编码的轴号。
5.5 按钮无限触发，按下一次执行了好几次动作
现象：控制台打印显示按一次按钮，逻辑被执行了七八次。原因：把电平状态当事件用了，循环每帧都读到了 1，于是每帧都触发。解决：使用 4.2 节的边沿检测逻辑，或者改用key(joy)按下时返回非零值、释放后返回 0，从而把事件判断简化为比较前后两次的键值。
5.6 数据更新率不够，控制响应有明显延迟
现象：手柄动了，界面里的目标位置要过一两秒才跟上。原因：循环里加了pause(0.1)这类过大的间隔，或者读取过程被其他耗时代码拖住。解决：把采样周期压到 0.02 秒以内，同时将控制指令下发也放进同一个循环体。如果在 Simulink 里，确认输入模块的采样时间没有大于你的控制周期。
5.7 扳机键一直处于“半按”状态
现象：扳机键没碰，读到的值却始终停在 0.3 左右，导致某些按键判断逻辑永远成立。原因：模拟扳机的输出范围是 0 到 1，和摇杆的 -1 到 1 不同，未按下时理论应为 0，若有非零值说明传感器零漂或驱动映射问题。解决：对扳机单通道做单独标定，初始化时记录静置值，运行时减去该偏置。这个偏置在每次开机时都可能不同，所以标定代码要放在初始化阶段，而不是硬编码一个常数。
5.8 读取时 MATLAB 直接崩溃或假死
现象：运行循环读取时，MATLAB 整个窗口无响应，必须强制结束。原因：极可能是底层驱动与 MATLAB 版本兼容问题，多见于老版本 MATLAB 配合新型手柄。解决：把循环读取改成用parfeval或者定时器回调，避免在主线程里长期占用；或者升级手柄驱动到最新，并确保装了最新支持包。如果问题仍在，退回vrjoystick旧接口做验证，看是否是新接口本身的缺陷。
5.9 多手柄同时插拔后对象序号错乱
现象：两个手柄同时连接，第一次插的序号是 1，拔掉再插后序号可能变成 2，脚本里固定用 1 就失效了。原因：Windows 对游戏杆的枚举序号不是固定的物理口序号，动态插拔后顺序会重排。解决：在脚本开头强制全设备枚举，然后按设备名称匹配目标手柄，而不是按固定序号。
6. 进阶技巧：轴值滤波、按键防抖与离线回放调试
当你能稳定读取数据后，面临的下一个痛点一般是数据噪声和调试效率。先说滤波。手柄轴值在快速摆动时会有轻微噪声，直接映射到电机指令会让执行器发出滋滋声，这种噪声肉眼难察觉但实物非常明显。常见的做法是一阶低通滤波，也叫一阶惯性滤波，实现极简单：
% 一阶惯性滤波，alpha 越小越平滑，但响应也越慢 alpha = 0.3; filtered_val = 0; while toc < run_time raw_val = axis(joy); filtered_val = alpha * raw_val + (1 - alpha) * filtered_val; % 使用 filtered_val 进行控制 endalpha是滤波系数，取值在 0 到 1 之间，越大越接近原始值，越小平滑效果越强。我一般从 0.3 起步，控制出现明显延迟就调大，机器抖动厉害就调小。这里需要说明：滤波处理后的数值会产生相位滞后，如果你做的是需要快速响应的控制实验，滤波系数超过 0.5 就明显感觉到粘滞了。按键防抖则是另一种需求，机械手柄按键在按下瞬间会连续跳动多次电平，直接用边沿检测仍可能触发多次，常规方案是加入时间窗口，检测到跳变后在 20 到 30 毫秒内忽略同一位的变化。
最后聊一个我后知后觉但非常受用的调试习惯：离线回放。在调控制参数时，手柄在人手里，数据在代码里，出了问题很难复现。我的做法是每次正式实验前先录一段操控轨迹数据——轴值、按钮值、时间戳，保存成 MAT 文件，后续调参时直接回放这段数据，让系统认为自己在实时读取手柄，这样任何问题都能稳定重现。回放脚本本质上就是一个表格读取代码：
% 回放已录制的操控轨迹，用于参数调试，不依赖物理手柄 load('log_20240512.mat'); % 包含 axes_log, btn_log, ts_log for i = 1:length(ts_log) axes_data = axes_log(i, :); btn_data = btn_log(i, :); % 此处复用与实时模式相同的控制算法 % 计算控制指令并检查结果 end从那以后，我每次改控制逻辑都会先录一段真实操作，再跑回放对比新旧参数的行为差异，效果非常明显。这个习惯帮我躲过了不少只在特殊动作下才出现的逻辑问题，从那以后我每次做游戏杆控制相关项目都强制走一遍“录制—回放—调参—实机验证”的流程，希望帮到你。
本文还有配套的精品资源，点击获取
