0x23/MicroManipulatorStepper
GitHub: 0x23/MicroManipulatorStepper
一款低成本开源的亚微米级XYZ精密运动控制平台，支持G-Code和Python API控制，适用于光学对准和显微镜操作等场景。
Stars: 1475 | Forks: 194
# 开源微型机械臂
本项目包含一个开源低成本、易于构建的电动 **XYZ 微型机械臂** 运动控制平台，可实现亚微米级精度。
它专为光学对准、电子元器件探针检测和显微镜等应用而设计。
请查看 YouTube 视频以获取有关该设备及其构建方式的更多信息：
[一款开源电动 XYZ 微型机械臂 - 经济实惠的亚微米级运动控制](https://youtu.be/MgQbPdiuUTw)
得益于其并联运动结构和微型球头关节，它实现了良好的机械刚度和较大的运动范围。
电机是现成的步进电机，由 30 kHz 闭环控制器和非常精确的 PWM 信号驱动。
一种“磁齿轮”方法将低成本磁性旋转编码器的分辨率提高了 30 倍，从而允许低至 50nm 的步进
（**请注意分辨率和精度之间的区别**。绝对精度要差得多。
该设备可通过 USB 串行接口使用简单的 G-Code 命令进行控制，因此易于集成到其他项目中。
固件实现了一个完整的运动规划堆栈，具有前瞻功能，可实现平滑且精确的路径跟随能力。
## 开始使用
如果您想复刻该项目，以下是可以遵循的高级步骤列表。
如果您在构建过程中遇到问题，或者只是想讨论与项目相关的话题，
请加入项目社区 [Discord 服务器](https://discord.gg/maRvMVpa2Q)。
1. 阅读本文档并观看链接的视频
2. 获取 [物料清单](documentation/bom/bom.md) 中列出的零件
3. 组装设备和电子元件
4. 根据您的构建修改硬件配置 [hw_config.h](firmware/MotionControllerRP/src/hw_config.h)
5. 使用带有 PlatformIO 插件的 VSCode 上传固件
6. 校准轴
## ✨新消息：硬件版本 4.0
新版本的硬件已发布，修复了先前设计的几个问题：
- 修复了归零过程中的自碰撞问题。
- 仅用螺丝连接球头关节块约束不佳，可能会轻微旋转。
- 没有可靠的方法来确保连杆长度的一致性
- 不必要的球头关节摩擦
- 准确的球头位置很大程度上取决于打印质量和尖角圆润度
- 橡皮筋一旦粘上就无法更换或移除。
关于改进的球头关节和连杆制造过程的视频可以在 YT 上找到：[开源微型机械臂的更好球头关节](https://www.youtube.com/watch?v=NM2KXvRGmpg)
此外，FreeCAD 模型已重构和改进，现在包括所有销钉和紧固件。它现在为所有必需的机械零件提供了参考。
警告：BOM 尚未更新...
## 开源微型机械臂 GUI
为了使开源微型机械臂的测试和使用变得简单方便，此处提供了一个带有图形用户界面的 Python 控制程序：[开源微型机械臂 GUI](https://github.com/0x23/OpenMicroManipulatorGUI)。
它具有移动设备的简单控件，同时还显示实时摄像头画面（例如来自显微镜摄像头）。其他功能包括简单的 g-code 运行器和实时鼠标控制（例如用于生物学应用）。
## 🐍 Python-API
轻量级 Python API 处理所有串行通信，并提供便捷的命令执行和调试消息打印。
该接口包括归零、移动和校准设备的功能，以及查询设备信息的功能。
只需将 [open_micro_stage_api.py](software/PythonAPI/open_micro_stage_api.py) 文件复制到您的项目中（同时安装 requirements.txt 中的依赖项），您就可以开始了。
## 使用示例
```
from open_micro_stage_api import OpenMicroStageInterface
# 创建接口并连接
oms = OpenMicroStageInterface(show_communication=True, show_log_messages=True)
oms.connect('/dev/ttyACM0')
# 运行此命令一次以校准关节
# for i in range(3): oms.calibrate_joint(i, save_result=True)
# 归零设备
oms.home()
# 移动到多个 x,y,z 位置 [mm]
oms.move_to(0.0, 0.0, 0.0, f=10)
oms.move_to(3.1, 4.1, 5.9, f=26)
oms.move_to(0.0001, 0.0, 0.0, f=10)
# 等待移动完成
oms.wait_for_stop()
```
## API 函数（仅列出最相关的函数）
```
connect(port, baud_rate=921600)
disconnect()
set_workspace_transform(transform)
get_workspace_transform()
home(axis_list=None)
calibrate_joint(joint_index, save_result)
move_to(x, y, z, f, move_immediately, blocking, timeout)
set_pose(x, y, z)
dwell(time_s, blocking, timeout)
enable_motors(enable)
wait_for_stop(polling_interval_ms, disable_callbacks)
set_max_acceleration(linear_accel, angular_accel)
set_servo_parameter(pos_kp, pos_ki, vel_kp, vel_ki, vel_filter_tc)
```
## ✨ 固件 v1.0.1
此更新改进了校准、归零、日志记录，并添加了几个新的 G-Code 命令。
### 改进
- **归零**：支持并行归零，重复性更高，几何参考更准确
- **关节校准**：改进的流程，持久化 Flash 存储（重启后无需重新校准）
- **日志记录**：更清晰、更详细的输出
### 新 G-Code 命令
- `G28` — 关节归零（支持多轴同时归零以加快启动速度）
- `G24` — 设置位姿命令（直接设置舵机目标，绕过运动控制器）
- `M17/M18` — 启用/禁用电机（启用时从编码器恢复位姿）
- `M51` — 读取编码器值
- `M55` — 设置舵机环路参数
- `M56` — 关节校准（带有保存到 Flash 的选项）
- `M57` — 读取有关设备状态的各种信息
- `M58` — 读取固件版本
## ⚙ CAD 文件
所有 CAD 模型均使用 **FreeCAD** 制作，以便每个人都可以查看和修改设计，而无需订阅或付费购买专有的 CAD 解决方案。
请注意，大多数组件的设计目标 already 是使其易于在三轴 CNC 铣床上加工。
您也可以 3D 打印这些零件，但必须承受热漂移（碳纤维填充耗材可以减少此问题）。
CAD 文件可以在这里找到：[CAD 模型](construction)。 请注意，使用的是 FreeCAD 版本 **1.2.0dev**，文件可能无法在旧版本上运行。 用于打印的 STL 文件可以在这里找到：[STL 文件](construction/STL_3D_Printing/) ## ⚙ 运动学模型 运动学模型定义在此处：[kinematic_model_delta3d.cpp](firmware/MotionControllerRP/src/kinemtaic_models/kinematic_model_delta3d.cpp)。 请根据构造函数中设置的值检查您构建的尺寸。特别是，确保臂长匹配。 ## ⚙ 电子元件 重要提示：如果您制作的是 PCB 版本 v1.2（请参阅板上的版本标签），您需要钻掉二极管 D1 上一个错位的过孔，该过孔将 5V 轨短路到地（参见 [修复图像](electronics/pcb_v1.2_fix.jpg)）。此问题已在 v1.3 中修复。 电子元件设计使用 **KiCAD**，仅使用通用的常用模块（电机驱动器和 MCU 板）并通过简单的 PCB 连接。填充电路板不需要 SMD 焊接，这使得构建格外容易上手。 对于电机的通常绕组电阻，设备应由 $${\color{lightgreen} 5V-6V }$$ (2A) 供电，以将电流和发热保持在合理水平。
该存储库现在还包含可直接上传给 PCB 制造商的制造文件。
## ⚙ 固件
固件使用 C++ 编写，并从 'SimpleFOC' 项目中汲取了一些灵感。它旨在精简且易读，没有任何多余的繁琐内容，专注于本项目使用的硬件。
它实现了带前瞻功能的路径规划，与许多其他运动控制器项目不同，它支持真正的 6DOF-位姿插值和规划，使其准备好驱动六足运动平台；这可能是也可能不是本项目的下一步。
您可以在 [hw_config.h](firmware/MotionControllerRP/src/hw_config.h) 中找到引脚编号、电机类型和其他参数的配置。请在上传固件前检查它们。
### 构建和烧录固件
建议使用 Visual Studio Code（可在 Windows 和 Linux 上免费使用）来构建和烧录固件。
安装 PlatformIO 插件并打开固件文件夹。您现在可以像任何其他 PlatformIO 项目一样构建和烧录固件。
## ⚙ G-Code 接口
固件仅支持下面列出的 G-Code 命令的一小部分。
每个命令都会收到 **`ok`** 或 **`error`** 响应进行确认。
如果命令提供附加信息（例如 *获取位置* 命令），则该信息在 `ok` 消息 **之前** 返回。
客户端必须等待上一条命令的确认后再发送下一条命令——否则，行为未定义。
| 命令 | 描述 |
|-------------------|-----------------------------------------------------------------------------|
| `G0 X Y Z F` | 将末端执行器沿直线移动到指定位置。
• `X`, `Y`, `Z`：目标位置
• `F`：进给速率 | | `G1 X Y Z F` | 同 `G0`。 | | `G4 S/P` | 停留/暂停指定时间。
• `S`：秒
• `P`：毫秒 | | `G24 X Y Z A B C` | 直接设置舵机环路的当前位姿，可选旋转向量* `A`, `B`, `C`。 | | `G28 A-F` | 归零一个或多个关节。
• 可选关节选择 `A`–`F`。 | | `M17` | 启用电机并将当前位姿读取为起始位姿。 | | `M18` | 禁用电机。 | | `M50` | 获取当前内部位姿。（此处不读取编码器） | | `M51` | 获取当前编码器角度（以度为单位）和原始编码器值。 | | `M52` | 获取规划器队列中的项目数。 | | `M53` | 检查所有规划移动是否完成（`1` = 完成，`0` = 未完成）。 | | `M55 A B C D F` | 设置舵机环路参数。
• `A`, `B`：位置 PI 控制器增益（P 和 I）
• `C`, `D`：速度 PI 控制器增益（P 和 I）
• `F`：速度滤波器时间常数 | | `M56 J S` | 校准关节。
• `J`：关节索引
• `S`：保存校准结果 | | `M57` | 获取设备和舵机环路信息：归零/校准状态、角度、环路频率和文件列表。 | | `M58` | 获取固件版本。 | | `M204 L A` | 设置线性和角加速度。
• `L`：线性加速度
• `A`：角加速度 | *注意：通信协议使用 3D 向量表示旋转。方向代表旋转轴，向量的长度代表绕轴旋转的角度。 ## ❤️ 支持 如果您想支持本项目，请考虑以下事项： - **为构建指南做贡献** – 通过提交 Pull Request 或提出带有建议的 Issue 来帮助改进或扩展构建说明。 - **表征典型径向步进电机轴误差运动** – 测量多个 Nema-17 步进电机轴的径向误差运动（有关该主题的更多信息，请参阅 Cylos Garage：https://www.youtube.com/watch?v=gt2gK-oxy5s）。 - **对构建体验提供反馈** – 让我们知道哪些有效，哪些无效，以及如何让其他人的过程更顺畅。 - **在 Ko-fi 上支持该项目** – 如果您觉得这个项目有价值，可以通过 [Ko-fi](https://ko-fi.com/diffractionlimited) 在经济上支持它 ☕。 ## Youtube 视频 [](https://youtu.be/MgQbPdiuUTw)
[一款开源电动 XYZ 微型机械臂 - 经济实惠的亚微米级运动控制](https://youtu.be/MgQbPdiuUTw)
CAD 文件可以在这里找到：[CAD 模型](construction)。 请注意，使用的是 FreeCAD 版本 **1.2.0dev**，文件可能无法在旧版本上运行。 用于打印的 STL 文件可以在这里找到：[STL 文件](construction/STL_3D_Printing/) ## ⚙ 运动学模型 运动学模型定义在此处：[kinematic_model_delta3d.cpp](firmware/MotionControllerRP/src/kinemtaic_models/kinematic_model_delta3d.cpp)。 请根据构造函数中设置的值检查您构建的尺寸。特别是，确保臂长匹配。 ## ⚙ 电子元件 重要提示：如果您制作的是 PCB 版本 v1.2（请参阅板上的版本标签），您需要钻掉二极管 D1 上一个错位的过孔，该过孔将 5V 轨短路到地（参见 [修复图像](electronics/pcb_v1.2_fix.jpg)）。此问题已在 v1.3 中修复。 电子元件设计使用 **KiCAD**，仅使用通用的常用模块（电机驱动器和 MCU 板）并通过简单的 PCB 连接。填充电路板不需要 SMD 焊接，这使得构建格外容易上手。 对于电机的通常绕组电阻，设备应由 $${\color{lightgreen} 5V-6V }$$ (2A) 供电，以将电流和发热保持在合理水平。
• `X`, `Y`, `Z`：目标位置
• `F`：进给速率 | | `G1 X Y Z F` | 同 `G0`。 | | `G4 S/P` | 停留/暂停指定时间。
• `S`：秒
• `P`：毫秒 | | `G24 X Y Z A B C` | 直接设置舵机环路的当前位姿，可选旋转向量* `A`, `B`, `C`。 | | `G28 A-F` | 归零一个或多个关节。
• 可选关节选择 `A`–`F`。 | | `M17` | 启用电机并将当前位姿读取为起始位姿。 | | `M18` | 禁用电机。 | | `M50` | 获取当前内部位姿。（此处不读取编码器） | | `M51` | 获取当前编码器角度（以度为单位）和原始编码器值。 | | `M52` | 获取规划器队列中的项目数。 | | `M53` | 检查所有规划移动是否完成（`1` = 完成，`0` = 未完成）。 | | `M55 A B C D F` | 设置舵机环路参数。
• `A`, `B`：位置 PI 控制器增益（P 和 I）
• `C`, `D`：速度 PI 控制器增益（P 和 I）
• `F`：速度滤波器时间常数 | | `M56 J S` | 校准关节。
• `J`：关节索引
• `S`：保存校准结果 | | `M57` | 获取设备和舵机环路信息：归零/校准状态、角度、环路频率和文件列表。 | | `M58` | 获取固件版本。 | | `M204 L A` | 设置线性和角加速度。
• `L`：线性加速度
• `A`：角加速度 | *注意：通信协议使用 3D 向量表示旋转。方向代表旋转轴，向量的长度代表绕轴旋转的角度。 ## ❤️ 支持 如果您想支持本项目，请考虑以下事项： - **为构建指南做贡献** – 通过提交 Pull Request 或提出带有建议的 Issue 来帮助改进或扩展构建说明。 - **表征典型径向步进电机轴误差运动** – 测量多个 Nema-17 步进电机轴的径向误差运动（有关该主题的更多信息，请参阅 Cylos Garage：https://www.youtube.com/watch?v=gt2gK-oxy5s）。 - **对构建体验提供反馈** – 让我们知道哪些有效，哪些无效，以及如何让其他人的过程更顺畅。 - **在 Ko-fi 上支持该项目** – 如果您觉得这个项目有价值，可以通过 [Ko-fi](https://ko-fi.com/diffractionlimited) 在经济上支持它 ☕。 ## Youtube 视频 [](https://youtu.be/MgQbPdiuUTw)
标签：3D定位, 3D打印, DIY, G代码, PWM驱动, USB串口, 亚微米精度, 低成本, 光学对准, 嵌入式固件, 并联机械臂, 开源硬件, 微操器, 微纳制造, 显微镜, 步进电机, 电子探针, 磁性编码器, 科研设备, 精密工程, 自动化控制, 运动控制平台, 运动规划, 逆向工具, 闭源控制