matlab-connect-arduino

在 MATLAB 中设置 Arduino 开发板

指导 Agent 发现、配置并通过 USB 连接 Arduino 开发板，确保用户在每个步骤中都知情并掌握主动权。

何时使用

• 用户想从 MATLAB 连接 Arduino 开发板
• 用户要求发现或列出已连接的 Arduino 开发板
• 用户的任务需要先连接 Arduino（例如读取传感器、控制执行器、扫描 I2C 等）
• 用户提到 Arduino、COM 端口、串行端口或硬件设置

何时不要使用

• 为不受支持的外围设备创建自定义附加库（请参阅 matlab-create-custom-arduino-library）
• 通过 Bluetooth 或 WiFi 连接 Arduino（本文不涉及）
• Arduino IDE 或支持包安装问题
• Simulink 硬件在环工作流
• 工作区中已经有活动的 arduino 对象的任务

工作流

按顺序执行以下步骤。不要跳过步骤或猜测值。

核心原则： 切勿想当然。如果任何信息不清楚或含糊不明，务必先询问用户，再继续操作。

步骤 1：发现开发板

务必运行这两条命令——即使 arduinolist 已找到开发板，也不要跳过 serialportlist。这是硬性要求：

list = arduinolist
ports = serialportlist("available")

两次调用都必须执行。 切勿省略 serialportlist——单独使用 arduinolist 会漏掉没有支持包固件的开发板。

arduinolist 会返回一个表格，其中包含 Port、Board、Status 和 Libraries 列。不过，从 R2026a 开始，它无法列出所有已连接的开发板——即使连接了多个开发板，它也可能只显示一个。务必同时运行 serialportlist("available")，以获取所有可用端口。

如果 arduinolist 不可用（R2024a 之前的版本），请跳过它，仅使用 serialportlist("available")。

向用户展示两条命令的结果。

步骤 1b：处理“未检测到开发板”的情况

如果 arduinolist 返回空表格，且 serialportlist("available") 未显示明显的 Arduino 端口（或所有连接尝试都失败），不要对所有端口进行暴力尝试。 请改为：

1. 立即询问：“未检测到 Arduino 开发板。开发板是否已通过 USB 实际连接？”
2. **引导用户使用操作系统工具：**根据用户的操作系统提供相应指导：
   • Windows：“打开设备管理器 → 端口（COM 和 LPT）。是否看到标有‘Arduino’或‘USB-SERIAL CH340’/‘USB Serial Device’的设备？如果没有，开发板可能未连接，或者需要安装驱动程序。”
   • macOS：“在终端中运行 ls /dev/cu.usb*。Arduino 开发板通常显示为 /dev/cu.usbmodem* 或 /dev/cu.usbserial*。”
   • Linux：“插入开发板后运行 dmesg | tail -20。查找 /dev/ttyACM* 或 /dev/ttyUSB*。”
3. 建议常见的解决方法：
   • 尝试更换 USB 线缆（有些线缆只能充电，不能传输数据）
   • 尝试更换 USB 端口
   • 安装开发板的 USB 驱动程序（克隆板使用 CH340，其他开发板使用 FTDI）
   • 确保没有其他应用程序（Arduino IDE 串行监视器、PuTTY）占用该端口
   • 如果手动断开开发板时未清除 arduino 对象，请重启 MATLAB 并重新连接
   • 如需详细的故障排除信息，请参阅以下页面： https://www.mathworks.com/help/matlab/supportpkg/arduino-connection-failure.html
4. **停止并等待。**在用户回复之前，不要继续执行步骤 2 或后续步骤。如果用户确认开发板未连接，请在此处继续排查。如果已连接，请返回步骤 1 并重新发现。

步骤 2：帮助用户识别端口

仅凭串行端口名称无法判断连接的是哪种设备。请引导用户识别哪些端口连接了 Arduino 开发板：

• Windows：“查看设备管理器（端口部分），确认哪些 COM 端口对应 Arduino 开发板。”
• macOS：“查找 /dev/cu.usbmodem* 或 /dev/cu.usbserial* 条目——这些通常是 Arduino 开发板。”
• Linux：“运行 dmesg | grep tty，或查找 /dev/ttyACM* 和 /dev/ttyUSB* 设备。”

步骤 3：请用户选择板卡

列出发现的板卡/端口，并询问用户要连接哪个。 绝不能自动选择板卡。

询问：

1. 端口（必填）——要使用哪个 COM 端口 / 设备路径
2. 板卡类型（可选）——如果用户不知道，请使用 arduino('<port>') 自动检测板卡类型

对于多板卡场景，请用户按端口识别每块板卡 及其预期用途。

步骤 4：确定库

默认库为 {'I2C', 'SPI', 'Servo'}——如果未指定 Libraries 参数， MATLAB 会自动加载这些库。

库策略：

1. 从默认库开始：{'I2C', 'SPI', 'Servo'}
2. 根据以下映射，从用户的提示词中推断额外的库：

用户提及	添加库
超声波、距离传感器、HC-SR04	'Ultrasonic'
移位寄存器、74HC595	'ShiftRegister'
旋转编码器、正交编码器	'RotaryEncoder'
电机扩展板、Adafruit 电机	'Adafruit/MotorShieldV2'
电机载板、MKR 电机	'MotorCarrier'
CAN 总线	'CAN'
串行设备、UART	'Serial'
APDS9960、手势、颜色传感器	'APDS9960'

仅当匹配明确且无歧义时，才根据上表推断。 如果不确定，请询问用户，而不是猜测库。

3. 告知用户要包含哪些库以及原因
4. 询问用户是否还需要其他库
5. 如果用户询问有哪些库可用，请运行 listArduinoLibraries 并 显示完整列表

步骤 5：连接

根据收集的信息构建 arduino() 调用：

% TEMPLATE — not executable
% With board type known + custom libraries:
a = arduino('<port>', '<board>', 'Libraries', {'I2C', 'SPI', 'Servo', ...});

% With board type known, default libraries only:
a = arduino('<port>', '<board>');

% Auto-detect board type (uses libraries already flashed on board):
a = arduino('<port>');

**重要：**指定 'Libraries' 时，必须同时指定板卡类型。如果用户不知道板卡类型但需要额外的库，请先运行 arduino('<port>') 自动检测，然后读取 a.Board，再使用指定的板卡类型和库重新连接。

如果连接失败：

1. 立即停止——不要自动重试
2. 向用户报告准确的错误消息
3. 根据错误提供 1–2 个有针对性的解决方法
4. 除非用户明确要求，否则不要使用不同的端口或板卡类型重试

常见问题：

• 端口正被占用（其他应用程序已打开该端口）
• “设备正在使用”——工作区中已存在 arduino 对象；用户必须先 clear，然后才能重新连接
• 指定了错误的板卡类型
• 板卡需要重置固件（双击复位按钮）

步骤 6：确认并移交

连接成功后：

1. 向用户确认：“已通过 [Port] 端口连接到 [Board]，使用的库：[list]。”
2. 如果用户的提示词包含连接以外的任务（例如， “闪烁 LED”“读取超声波传感器”），请告知：“现在开始执行 [task]……”并继续后续工作流。

主要函数

函数	用途	起始版本
arduinolist	发现已连接的 Arduino 板卡（表格输出）	R2024a
serialportlist("available")	列出所有可用的串行端口	R2019b
arduino(port)	使用自动检测的板卡类型和默认库进行连接	R2014b
arduino(port, board)	使用指定的板卡和默认库进行连接	R2014b
arduino(port, board, 'Libraries', libs)	使用指定的板卡和自定义库进行连接	R2014b
listArduinoLibraries	列出所有可用的附加库	R2014b

用法模式

单板卡连接

% TEMPLATE — not executable
% Step 1: Discover
list = arduinolist;
ports = serialportlist("available");

% Step 3-5: Connect (after user selects port and board is known)
a = arduino('COM8', 'Nano33BLE', 'Libraries', {'I2C', 'SPI', 'Servo', 'Ultrasonic'});

多板卡连接

% TEMPLATE — not executable
% Connect to each board with its own variable and libraries
a1 = arduino('COM8', 'Nano33BLE', 'Libraries', {'I2C', 'SPI', 'Servo'});
a2 = arduino('COM52', 'Uno', 'Libraries', {'I2C', 'SPI', 'Servo', 'Ultrasonic'});

常见错误

错误	错误原因	正确做法
不带参数使用 arduino()	未经用户同意便连接到任意开发板	务必先发现设备，再让用户选择
猜测 COM 端口或开发板类型	在错误的端口上浪费时间，或给错误的开发板重新刷写固件	询问用户，或仅指定端口并使用自动检测
只加载需要的库	稍后重新连接并加载更多库会耗时 30 秒以上	加载默认库 {'I2C','SPI','Servo'}，以及推断出的其他库
未指定开发板便使用 arduino(port, 'Libraries', libs)	错误：必须先指定端口和开发板，再指定名称-值对	使用 arduino(port, board, 'Libraries', libs)，或使用 arduino(port) 自动检测并加载默认库
arduinolist 成功后跳过 serialportlist	会漏掉没有支持包固件的开发板或 R2024a 之前的开发板	始终同时运行两者——即使 arduinolist 返回了结果，serialportlist 仍是必需步骤
通过结束进程来释放端口	未经用户同意便执行破坏性操作	报告端口冲突，并请用户关闭其他应用程序

约定

• 每个发现步骤都必须同时运行 arduinolist 和 serialportlist("available")——即使 arduinolist 已找到开发板。serialportlist 可以发现 arduinolist 无法识别的开发板。
• 执行操作前，始终先向用户展示发现的信息
• 开发板类型为可选项——用户不知道时，让 MATLAB 自动检测
• 始终包含默认库 {'I2C', 'SPI', 'Servo'}
• 未经询问，绝不执行破坏性操作（结束进程、清空工作区）
• 明确区分连接步骤和后续任务执行
• Arduino 硬件不可共享——同一时间只能有一个 MATLAB 会话连接到指定开发板。不要运行多个并行 Agent，让它们分别尝试连接 Arduino 硬件。Arduino 工作流必须按顺序运行。

---

版权所有 2026 The MathWorks, Inc.

---