简体中文 | English

FreeCAD 机电协同 —— 嘉立创 EDA 专业版扩展

通过 WebSocket 实现 PCB 3D 模型及 3D 外壳在嘉立创 EDA 与 FreeCAD 之间的实时协同。支持模型导出、双向位置同步、交叉定位、删除同步、3D 外壳同步。

功能特性

功能	说明
3D 模型导出	将 PCB 的 STEP 模型分片传输到 FreeCAD，支持大文件
3D 外壳导出	将 3D 外壳 STEP 文件发送到 FreeCAD（支持 ZIP 自动解压）
下载脚本文件	一键保存 FreeCAD 宏脚本到本地，免去手动复制
PCB 位置同步	EDA 拖动元件 → FreeCAD 跟着动，反之亦然
外壳自动同步	修改 3D 外壳后自动同步到 FreeCAD（单向）
交叉定位	点击一边的元件，另一边自动聚焦
删除同步	EDA 删除元件，FreeCAD 同步移除
位号重命名	改名后映射自动更新
Z 轴自动对齐	PCB 板子中心自动对齐到上下壳交界处
导入心跳保活	大文件导入期间持续发送进度，防止超时断连

---

环境要求

项目	要求
嘉立创 EDA 专业版	≥ 3.0
FreeCAD	≥ 1.0
网络	本机可用（localhost）

---

安装步骤

第一步：安装 FreeCAD 宏脚本

1. 打开 FreeCAD
2. 顶部菜单栏点击 宏 → 宏编辑器（或按 Alt+F8）
3. 在宏编辑器中点击 新建（或 Ctrl+N）创建新宏
4. 打开本项目 script/Interactive-with-easyeda.py 文件，将全部内容复制粘贴到宏编辑器中（脚本文件也可以通过菜单 FreeCAD机电协同 → 下载脚本文件，一键保存到本地）

1. 点击 保存（Ctrl+S），将宏命名，保存到默认宏目录
2. 点击 执行或双击执行（绿色三角形按钮，或 Ctrl+F5）运行脚本
3. 验证启动成功：点击 视图 → 面板 → 勾选 报告视图，在底部报告视图中应看到：

检查websockets库...
websockets库已安装
初始化WebSocket服务器 0.0.0.0:8766
WebSocket服务器启动成功!
地址: ws://localhost:8766
FreeCAD环境已检测，服务器已启动
已注册主线程定时器（100ms轮询消息队列）
已注册位置监听定时器（500ms轮询位置+选中+删除）
等待客户端连接...

提示： 脚本会自动检测并安装 websockets Python 库。首次运行可能需要几秒钟安装依赖。如果自动安装失败，见下方常见问题。

第二步：安装 EDA 扩展

1. 打开 嘉立创 EDA 专业版
2. 安装完成后，在扩展列表中找到 FreeCAD机电协同，确认已启用 开启外部交互权限：点击 扩展 → 扩展设置 → 开启 外部交互 权限（WebSocket 通信需要）

使用教程

一、导出 3D 模型到 FreeCAD

确保 FreeCAD 宏脚本已运行，然后在 EDA 中：

1. 打开一个 PCB 设计文件，进入 PCB 编辑器
2. 顶部菜单点击 FreeCAD机电协同 → 导出3D到FreeCAD

1首次使用会自动连接 FreeCAD 服务器，看到提示「正在连接到FreeCAD服务器...」

2 连接成功后自动获取 STEP 文件并分片上传，看到提示「PCB STEP文件获取成功」

3 上传完成后 FreeCAD 开始导入，EDA 显示「正在导入STEP文件到FreeCAD...」

4 导入完成，EDA 显示「PCB导入完成」，FreeCAD 中显示 3D 模型

注意： 大文件（元件多、3D 模型复杂）导入可能需要数分钟。导入期间 FreeCAD 界面会无响应，这是正常现象。后台心跳会持续保活连接，不会断开。

二、导出 3D 外壳到 FreeCAD

前置条件： 需先完成 PCB 3D 模型导出，再导入外壳。Z 轴自动对齐依赖已导入的 PCB 裸板作为参考基准，若文档中不存在 PCB 模型则无法执行对齐。

1. 在 PCB 编辑器中绘制 3D 外壳图元（上下壳轮廓等）
2. 点击菜单 FreeCAD机电协同 → 导出3D外壳到FreeCAD
3. 外壳 STEP 文件会发送到 FreeCAD，与 PCB 导入到同一文档中
4. 导入后自动执行 Z 轴自动对齐：以 PCB 裸板中心为基准，自动调整外壳 Z 轴位置，使 PCB 板子居中于上下壳交界处

三、启用 PCB 同步

导出 PCB 模型后，可以启用 PCB 同步实现元件位置双向实时同步：

1. 点击菜单 FreeCAD机电协同 → 启用PCB同步
2. EDA 会自动将元件位号与 FreeCAD 3D 对象建立映射（三轮匹配：精确匹配 → 正则匹配 → 位置匹配）
3. 映射成功后看到提示「PCB同步已启动」

此时可以：

• 在 EDA 中拖动元件 → FreeCAD 中的 3D 模型实时跟随移动
• 在 FreeCAD 中拖动对象 → EDA 中的元件同步移动
• 在 EDA 中点击元件 → FreeCAD 自动选中并聚焦
• 在 FreeCAD 中点击对象 → EDA 自动定位到对应元件

四、启用外壳同步

启用外壳同步后，在嘉立创EDA中修改 3D 外壳会自动同步到 FreeCAD：

1. 点击菜单 FreeCAD机电协同 → 启用外壳同步
2. 首次启用会立即同步一次当前外壳
3. 之后修改外壳图元后，1s 无新修改即自动触发同步

注意： 外壳同步为单向（嘉立创EDA → FreeCAD），不支持在 FreeCAD 中修改外壳后反向同步。设计目的是将外壳同步到 FreeCAD 后进行更加细致的外壳加工（如开孔精修、装配特征添加、壁厚调整等）。

五、停止同步

• 点击 FreeCAD机电协同 → 停止PCB同步 停止 PCB 位置同步
• 点击 FreeCAD机电协同 → 停止外壳同步 停止外壳自动同步
• 两个同步可独立启停，互不影响

六、连接管理

菜单选项	功能
导出3D到FreeCAD	自动连接 + 分片上传 + 导入
导出3D外壳到FreeCAD	发送 3D 外壳 STEP 文件 + Z 轴自动对齐
启用PCB同步	开启元件位置双向实时同步
停止PCB同步	关闭 PCB 位置同步
启用外壳同步	开启 3D 外壳修改自动同步（单向）
停止外壳同步	关闭外壳自动同步
连接FreeCAD	手动建立 WebSocket 连接
断开FreeCAD	断开连接（菜单由 EDA 扩展框架提供）
检查FreeCAD连接	查看当前连接状态

---

已知限制

1. 外壳同步加载进度条

现象： 每次修改 3D 外壳后同步到 FreeCAD 时，嘉立创EDA会显示加载进度条。

原因： 嘉立创EDA的 get3DShellFile API 每次调用都会在服务端重新生成完整的 STEP 文件，该过程会触发加载指示器。这是 API 的固有行为，扩展端无法抑制。

与 PCB 同步的区别： PCB 同步仅在首次导出时生成 STEP 文件，后续位置同步只发送轻量的坐标更新消息（几十字节），不会触发加载进度条。外壳同步由于涉及几何形状变化，每次都需要重新生成 STEP 文件。

2. 外壳同步为单向

现象： 外壳同步仅支持 嘉立创EDA → FreeCAD 方向，不支持在 FreeCAD 中修改外壳后反向同步到嘉立创EDA。

设计目的： 外壳同步的设计目标是将在嘉立创EDA中设计的外壳模型同步到 FreeCAD，以便在 FreeCAD 中进行更加细致的外壳加工（如开孔精修、装配特征添加、壁厚调整等机械设计操作）。这些操作通常不需要反向同步回 ECAD。

3. 外壳同步防抖与节流

• 修改外壳后需等待 1s 无新修改才会触发同步（防抖）
• 两次同步间隔至少 3 秒（节流），防止高频修改导致同步风暴
• 如果同步过程中再次修改外壳，会在当前同步完成后自动重试

---

技术说明

项目	说明
通信协议	WebSocket（JSON），地址 ws://localhost:8766
文件格式	STEP (.step)
文件传输	512KB 分片 Base64 编码，支持大文件
线程模型	FreeCAD 主线程（QTimer）+ WebSocket 异步线程 + 消息队列
导入保活	后台心跳线程每 2 秒发送进度，防止大文件导入超时
外壳同步	事件驱动（onPcbPrimitiveChange），1s 防抖 + 3 秒节流
变化检测	文件大小 + 前 1KB 内容指纹双重检测，跳过未变内容

---

常见问题

连接 FreeCAD 失败

请按顺序检查：

1. FreeCAD 是否已启动，且宏脚本已运行
2. 端口 8766 是否被占用 — 如果上次 FreeCAD 非正常关闭，端口可能残留。关闭所有 FreeCAD 进程后重试
3. 外部交互权限 — EDA 扩展设置中是否已开启外部交互权限
4. 防火墙 — 检查 Windows 防火墙是否拦截了 8766 端口

websockets 库自动安装失败

手动安装：

执行命令示例
"<FreeCAD安装目录>/bin/python.exe" -m pip install websockets==13.1 -i https://pypi.tuna.tsinghua.edu.cn/simple

Windows 示例
"C:\Program Files\FreeCAD 1.1.1\bin\python.exe" -m pip install websockets==13.1 -i https://pypi.tuna.tsinghua.edu.cn/simple

macOS 示例
"/Applications/FreeCAD.app/Contents/Resources/bin/python3" -m pip install websockets==13.1 -i https://pypi.tuna.tsinghua.edu.cn/simple

导入大文件时 FreeCAD 卡住

这是正常现象。FreeCAD 的 STEP 解析使用 OpenCASCADE 内核，是单线程的。80 个对象的 PCB 通常需要数分钟。导入期间：

• FreeCAD 界面会无响应
• EDA 端会收到 import_progress 心跳消息（控制台可见）
• 导入完成后 FreeCAD 自动恢复响应

加速建议： CPU 单核性能越高越快；内存充足避免磁盘交换。

导入后 FreeCAD 报告视图有错误

点击 视图 → 面板 → 报告视图 打开日志面板，查看详细错误信息。常见问题：

• STEP 文件不完整 → 重新导出
• FreeCAD 版本过低 → 升级到 1.0 以上

导入后 FreeCAD 报告视图有错误

嘉立创eda 和 freeCad 开了多个并且来回切换导致同步出现错位

• 目前仅支持一对一连接。多个PCB或多个FreeCAD文 档之间会串数据，不要同时开多个pbc并开启同步

双向交互位置不同步

1. 确认已经 先导出模型，再启用双向交互
2. 检查 FreeCAD 报告视图中映射日志，确认元件匹配数量
3. 如果匹配数为 0，可能是位号格式不标准，尝试在 FreeCAD 中检查对象的 Label

---

项目结构

pcb-export-to-freeCad/
├── src/
│   └── index.ts                         # EDA 扩展主逻辑（TypeScript）
├── script/
│   ├── Interactive-with-easyeda.py      # FreeCAD WebSocket 服务器（Python 宏）
│   └── eda_api_reference.md             # EDA 扩展 API 参考手册
├── config/
│   ├── esbuild.common.ts                # 构建配置
│   └── esbuild.prod.ts
├── build/
│   ├── packaged.ts                      # 打包脚本
│   └── dist/
│       └── mcad-integration-with-freecad_v1.0.0.eext  # 发布包
├── locales/
│   ├── zh-Hans.json                     # 中文翻译
│   └── en.json                          # 英文翻译
├── images/
│   └── logo.png                         # 扩展图标
├── extension.json                       # 扩展配置清单
├── package.json
└── tsconfig.json