Menu
设备交互智能体——扫描、连接、操纵物理开发板与嵌入式Linux板卡
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | device-connect |
| description | 设备交互智能体——扫描、连接、操纵物理开发板与嵌入式Linux板卡 |
| metadata | {"type":"skill"} |
用户执行以下任一操作时触发：
Linux 下的 USB 设备枚举：
# 列举所有 USB 设备（VID:PID:厂商:产品）
lsusb
# 列举 USB 转串口设备（真实开发板通常出现在这些节点）
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
ls -l /dev/serial/by-id/ 2>/dev/null # 稳定设备路径（推荐使用）
ls -l /dev/serial/by-path/ 2>/dev/null # 按物理端口路径
# 平台串口（ttyS*/ttyAMA*）通常是主板或 SoC 片上 UART，不一定是外接设备
# 仅当上述 USB 路径无结果时才作为备选检查
ls /dev/ttyS* /dev/ttyAMA* 2>/dev/null
# 获取 USB 设备详细信息
udevadm info --query=all --name=/dev/ttyUSB0
# 获取串口属性
stty -F /dev/ttyUSB0 -a
常见 USB 转串口芯片 VID:PID 对照表：
| 芯片 | VID:PID | 常见用途 |
|---|---|---|
| FT232R | 0403:6001 | 经典 USB-UART 转换器 |
| CH340/CH341 | 1A86:7523 | 低成本 Arduino 及国产开发板常用 |
| CP210x | 10C4:EA60 | Silicon Labs 方案，ESP32 开发板常见 |
| PL2303 | 067B:2303 | 老旧方案，Linux 下需注意驱动版本 |
设备描述输出格式：
[1] /dev/ttyUSB0 — FT232R (0403:6001) — 物理路径: bus-1.2
[2] /dev/ttyACM0 — STM32 Virtual COM Port (0483:5740) — 物理路径: bus-1.3
[3] /dev/serial/by-id/usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge_Controller_XXXXXXXX-00
适用场景：通过 JSONL 协议与机载 Linux 板卡（如 Jetson、Raspberry Pi）通信，代理执行 Shell 命令和外设操作。
协议规范：
请求帧（一行 JSON）:
{"id": 1, "method": "shell.exec", "params": {"cmd": "ls /dev/i2c*", "timeout_ms": 5000}}
响应帧:
{"id": 1, "ok": true, "data": {"stdout": "/dev/i2c-0\n/dev/i2c-1\n", "stderr": "", "exit_code": 0}}
支持的方法：
| Method | 功能 | 参数 | 安全限制 |
|---|---|---|---|
shell.exec | 执行 Shell 命令 | cmd: 命令字符串, timeout_ms: 超时 | 禁止 rm -rf, dd of=, mkfs, fdisk 等破坏性命令；禁止 `curl |
shell.exec_safe | 安全白名单命令 | cmd: 命令 | 仅允许：ls, cat, echo, uname, dmesg, i2cdetect, gpioinfo, i2cget, i2cset 等只读/低风险操作 |
gpio.read | 读取 GPIO 电平 | pin: 引脚号或名称 | 仅读取 |
gpio.write | 设置 GPIO 输出 | pin, value: 0/1 | 禁止设置为输入的 UART TX/RX 引脚、SWD 引脚等 |
i2c.scan | I2C 总线扫描 | bus: 总线号 | 无限制 |
i2c.read | I2C 寄存器读 | bus, addr, reg, len | 每次最大读取 256 字节 |
i2c.write | I2C 寄存器写 | bus, addr, reg, data[] | 禁止写电源管理/看门狗配置寄存器（需确认） |
spi.transfer | SPI 收发 | bus, cs, speed, tx_data[] | 每次最大传输 4096 字节 |
sensor.read | 传感器数据读取 | sensor_type, params | 每次最多返回 100 条数据点 |
连接流程：
1. 探测端口：尝试对候选 IP:port 发送 {"id": 0, "method": "ping"}
等待响应 {"id": 0, "ok": true, "data": {"version": "1.0", "hostname": "jetson-nx", "platform": "aarch64"}}
2. 能力协商：{"id": 1, "method": "capabilities"}
3. 执行操作
4. 优雅关闭：{"id": -1, "method": "disconnect"}
支持的传感器及读取方法：
| 传感器型号 | 接口 | 关键寄存器/指令 | 数据转换公式 |
|---|---|---|---|
| MPU6050 (6轴 IMU) | I2C 0x68 | ACCEL_XOUT_H (0x3B), GYRO_XOUT_H (0x43) | accel = raw / LSB_sensitivity (g), gyro = raw / 65.5 (deg/s, ±500dps) |
| MPU9250 (9轴 IMU) | I2C 0x68 | 同 MPU6050 + AK8963 磁力计 (I2C 0x0C) | mag = raw × mag_sensitivity_adj × 0.15 (μT) |
| VL53L0X (ToF 测距) | I2C 0x29 | RESULT_RANGE_STATUS (0x14+0x0096) | distance_mm = raw / 4 (若 unit=1) |
| BME280 (温湿压) | I2C 0x76/0x77 | 补偿参数从 0x88-0xA1 和 0xE1-0xF0 | 使用 Bosch 补偿公式（整型运算版本，无浮点） |
| SHT3x (温湿度) | I2C 0x44/0x45 | 单次测量命令 0x2C06 + 读数 6 字节 | T(°C) = -45 + 175 × ST / (2^16-1), RH(%) = 100 × SRH / (2^16-1) |
| ADS1115 (16位 ADC) | I2C 0x48/0x49/0x4A/0x4B | 转换寄存器 0x00, 配置寄存器 0x01 | voltage = raw × FS / 32768 (FS=4.096/2.048/1.024/0.512/6.144V 取决于 PGA) |
| AS5600 (磁编码器) | I2C 0x36 | RAW_ANGLE (0x0C) | angle_deg = raw × 360 / 4096 |
数据输出格式：
时间戳(ms) | 传感器 | 温度(°C) | 湿度(%) | 压力(hPa)
001234 | BME280 | 25.3 | 48.7 | 1013.25
001364 | BME280 | 25.4 | 48.9 | 1013.28
...
对于周期性采样，输出 ASCII 时序图（终端文本画图）。
操作规范：
# 导出 GPIO（sysfs 方式，Linux 4.x 及之前）
echo 17 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio17/direction
echo 1 > /sys/class/gpio/gpio17/value
# GPIO 字符设备方式（Linux 4.8+ 推荐）
gpioset gpiochip0 17=1 # 设置输出高
gpioget gpiochip0 18 # 读取输入
# libgpiod 工具集
gpiodetect # 列出所有 gpiochip
gpioinfo # 列出所有 GPIO 线的状态
gpioset --mode=time -s 2 gpiochip0 17=1 # 持续 2 秒的高脉冲（用于 LED 闪烁）
gpioset --mode=exit gpiochip0 17=0 # 设置后退出（维持电平）
安全约束：
完整流程参见 embedded-fullstack skill 的第 5 节。本 skill 侧重烧录前的连接准备和启动模式控制：
STM32 启动模式控制：
| BOOT0 | BOOT1 | 启动源 |
|---|---|---|
| 0 | x | Main Flash（正常运行模式） |
| 1 | 0 | System Memory（内置 bootloader，用于串口/USB DFU 烧录） |
| 1 | 1 | SRAM（调试用） |
ESP32 启动模式控制：
| GPIO0 | 模式 |
|---|---|
| 低（按住 BOOT 键） | 下载模式（等待 esptool 连接） |
| 高（默认） | Flash 启动（正常运行） |
诊断决策树：
连接失败
├─ 物理层
│ ├─ lsusb 能看到设备吗？→ 否 → 换 USB 线、换端口、检查设备上电
│ ├─ dmesg | grep tty 有设备挂载日志吗？→ 否 → 驱动缺失（linux-firmware 更新）
│ ├─ 设备挂载但有 "device descriptor read/64 error -71"？→ USB 供电不足或线缆质量问题
│ └─ /dev/ttyUSB0 存在但无法打开？→ 权限问题（用户需加入 dialout 组）
├─ 网络层（SSH/TCP 设备）
│ ├─ ping 通吗？→ 否 → 检查 IP、子网掩码、路由
│ ├─ 端口开放吗？→ nc -zv IP PORT → 否 → 防火墙或服务未启动
│ └─ SSH 连接被拒 → 检查 sshd 是否运行、用户名是否正确、密钥是否已授权
├─ 协议层（JSONL-RPC）
│ ├─ 能 TCP 连接但无响应？→ 检查 JSONL 格式（每行一个 JSON）
│ ├─ 返回 {"ok": false, "error": "..."} → 按错误信息调试
│ └─ 返回乱码 → 波特率或编码不匹配
└─ 应用层（MCU 下载模式）
├─ STM32CubeProgrammer 连接失败 → BOOT0 是否拉高？RESET 后是否过快尝试连接？
├─ OpenOCD 无法连接 SWD → 检查 SWCLK/SWDIO/GND 三线是否正确；目标板是否上电；ST-Link 固件版本
└─ esptool 连接超时 → 进入下载模式后再执行 esptool；检查 EN/GPIO0 时序
lsusb, udevadm, stty, picocom, screendmesg（查看设备挂载日志）ping, nc, ssh, curlgpiodetect, gpioinfo, gpioset, gpioget（libgpiod 套件）i2cdetect, i2cdump, i2cget, i2cset（i2c-tools 套件）STM32_Programmer_CLI, openocd, esptool.py## 设备清单
[扫描结果，按端口排列]
## 连接状态
设备 [名称] @ [端口] — [✓ 已连接 / ✗ 连接失败: 原因]
## 操作结果
[命令输出 / 传感器数据表格 / GPIO 状态]
## 异常与建议
[连接失败时的诊断建议]
板卡管理器——管理板卡配置、端口别名、外设清单与踩坑记录
嵌入式全流程开发助手——从MCU选型到固件烧录的全链路支持
硬件调试专家——串口监听、波形分析、故障定位与寄存器级调试
知识库检索引擎——查询芯片手册、通信协议、传感器参数与错误码诊断
技能提炼器——从调试会话中提取可复用技能，整合记忆并自我优化