# ODrive v3.6 官方文档WEB中文版

**Repository Path**: servo168/ODrive-v3.6-DOC

## Basic Information

- **Project Name**: ODrive v3.6 官方文档WEB中文版
- **Description**: ODrive 官方文档（v0.5.6）中文离线镜像站：33 个页面全部汉化，样式、图片与外链资源均已本地化，断网双击 index.html 即可查阅；覆盖接线、编码器校准、控制模式、CAN 总线与故障排查。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: servo

## README

# ODrive v3.6 官方文档 · 中文离线版

[![star](https://gitee.com/servo168/ODrive-v3.6-DOC/badge/star.svg?theme=dark)](https://gitee.com/servo168/ODrive-v3.6-DOC/stargazers)
[![fork](https://gitee.com/servo168/ODrive-v3.6-DOC/badge/fork.svg?theme=dark)](https://gitee.com/servo168/ODrive-v3.6-DOC/members)
[![固件版本](https://img.shields.io/badge/firmware-v0.5.6-orange.svg)](https://docs.odriverobotics.com/v/0.5.6/)
[![页面数](https://img.shields.io/badge/pages-33-brightgreen.svg)](#文档索引)
[![离线可用](https://img.shields.io/badge/offline-ready-blue.svg)](#快速开始)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

ODrive 官方文档（固件 `v0.5.6`）的完整中文镜像站，原站 33 个页面全部汉化并抓取为纯静态站点。样式、图片、视频与第三方外链资源均已本地化，断网环境下打开 `index.html` 即可查阅，无需服务器或联网。覆盖接线、编码器校准、控制模式、CAN 总线、通信协议与故障排查等日常调试场景，供 ODrive 用户随时速查。

---

## 目录

- [项目背景](#项目背景)
- [核心功能与亮点](#核心功能与亮点)
- [技术栈](#技术栈)
- [目录结构](#目录结构)
- [快速开始](#快速开始)
- [使用示例](#使用示例)
- [文档索引](#文档索引)
- [配套脚本](#配套脚本)
- [常见问题](#常见问题)
- [贡献指南](#贡献指南)
- [开源协议](#开源协议)

---

## 项目背景

ODrive 是一款开源的高性能无刷电机驱动器，官方文档是全英文站点。国内使用者在调试时经常遇到两个实际问题：

1. **术语门槛高** —— 编码器校准、陷波滤波器、前馈增益等概念直译后仍然费解；
2. **访问不稳定** —— 原站部署在境外，加载慢，部分章节的图片与外链资源经常拉取失败。

本仓库将官方 `v0.5.6` 文档整站镜像并汉化，同时把**第三方外链资源一并抓取到本地**，得到一个不依赖网络、可直接双击打开的中文文档包。

> **注意**：本仓库是第三方翻译镜像，非 ODrive Robotics 官方维护。硬件参数请以官方最新发布为准。

---

## 核心功能与亮点

| 项目 | 说明 |
| :--- | :--- |
| 完整汉化 | 33 个官方页面全部翻译为中文，含术语表与参数说明 |
| 全站离线 | 样式、脚本、图片、视频、附件全部本地化，断网可用 |
| 离线搜索 | 内置 Sphinx 搜索索引（`searchindex.js`），支持关键词全文检索 |
| 外链镜像 | 307 处外部链接已镜像至 `_static/external/`，点击不跳出、不会 404 |
| 原版源文件 | 保留 `reStructuredText` 源文件（`_sources/`），便于二次翻译与修订 |
| 零依赖 | 纯静态 HTML，无需数据库、无需后端、无需构建 |

**文档覆盖**：入门接线、编码器配置、控制模式、CAN 总线、引脚定义、电气规格、通信协议、故障排查、固件开发、IDE 配置等。

---

## 技术栈

| 层面 | 选型 |
| :--- | :--- |
| 文档生成器 | [Sphinx](https://www.sphinx-doc.org)（`sphinx_rtd_theme` 主题） |
| 源文件格式 | reStructuredText (`.rst`) |
| 前端 | 原生 HTML + CSS + JavaScript（含 jQuery、Sphinx 搜索） |
| 搜索引擎 | Sphinx 内置 `searchtools.js` + `searchindex.js` |
| 资源抓取 | 自定义镜像脚本，产出记录见 `_mirror_report.json` |
| 托管平台 | Gitee（支持 Gitee Pages 静态托管） |

---

## 目录结构

```text
ODrive-v3.6-DOC/
├── index.html                  文档首页（入口）
├── *.html                      33 个中文文档页面
├── _images/                    文档插图，19 张（接线图 / 波形图 / 尺寸图等）
├── _static/
│   ├── css/ js/                页面主题、样式与交互脚本
│   ├── video/                  演示视频
│   └── external/               第三方外链的本地镜像（约 249 MB，体积主要来源）
├── _sources/                   reStructuredText 源文件，30 个 .rst
├── _downloads/                 文档附件（.dbc 等可下载文件）
├── fibre_types/                Fibre 协议类型定义
├── objects.inv                 Sphinx 交叉引用索引
├── searchindex.js              离线搜索索引
└── _mirror_report.json         镜像抓取记录（源站 URL、页面与资源清单）
```

> 仓库总计约 **283 MB**，其中 249 MB 是 `_static/external/`。若只需要正文，**删除该目录不影响 33 个页面的阅读**，代价是其中 307 处外链会失效。

---

## 快速开始

### 环境要求

| 项目 | 要求 | 说明 |
| :--- | :--- | :--- |
| 浏览器 | Chrome / Edge / Firefox 等现代浏览器 | 必选 |
| Python | 3.6 及以上 | 可选，仅用于启动本地服务器以启用搜索功能 |
| 磁盘空间 | 约 300 MB | 完整克隆 |
| 网络 | 非必需 | 离线可用；外链直连原站时需联网 |

### 安装与运行

**方式一：直接打开（最简单）**

```bash
git clone https://gitee.com/servo168/ODrive-v3.6-DOC.git
cd ODrive-v3.6-DOC
```

双击 `index.html` 即可阅读。

**方式二：启动本地服务器（推荐）**

```bash
cd ODrive-v3.6-DOC

# Python 3
python -m http.server 8000

# 或使用 Node.js
npx serve -l 8000
```

浏览器访问 <http://localhost:8000> 。

> 推荐使用方式二。直接以 `file://` 打开时，浏览器的同源策略会拦截 `searchindex.js` 的加载，**导致搜索功能不可用**。

---

## 使用示例

### 示例一：首次上电到闭环转动

以下流程摘自[入门指南](getting-started.html)，是 ODrive 上电后让电机转起来的最小步骤。

```python
import odrive
from odrive.enums import *

# 1. 连接设备
odrv0 = odrive.find_any()

# 2. 配置保护限值
odrv0.axis0.motor.config.current_lim = 10                             # 电流上限 (A)
odrv0.axis0.controller.config.vel_limit = 2                           # 速度上限 (turn/s)

# 3. 执行完整校准（电机会转动，请确保空载）
odrv0.axis0.requested_state = AXIS_STATE_FULL_CALIBRATION_SEQUENCE

# 4. 进入闭环控制
odrv0.axis0.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL

# 5. 下发位置指令（单位：圈）
odrv0.axis0.controller.input_pos = 1
```

下面按编码器类型给出三种常见组合的完整配置。

#### 1.1 霍尔编码器 + 速度模式

适用于带霍尔（HALL）传感器的电机，如轮毂电机、滑板车电机。分辨率较低（CPR = 极对数 × 6），低速性能弱于其他类型，但成本低、接线简单。

```python
# 编码器配置
odrv0.axis0.encoder.config.mode = ENCODER_MODE_HALL                           # 编码器模式：霍尔
odrv0.axis0.encoder.config.cpr = 12                                           # CPR = 极对数 2 × 6

# 霍尔信号引脚需设为数字输入（axis0 使用 GPIO 9 / 10 / 11）
odrv0.config.gpio9_mode = GPIO_MODE_DIGITAL                                   # Hall A
odrv0.config.gpio10_mode = GPIO_MODE_DIGITAL                                  # Hall B
odrv0.config.gpio11_mode = GPIO_MODE_DIGITAL                                  # Hall C

# 控制配置：速度闭环 + 直通输入
odrv0.axis0.controller.config.control_mode = CONTROL_MODE_VELOCITY_CONTROL
odrv0.axis0.controller.config.input_mode = INPUT_MODE_PASSTHROUGH
odrv0.axis0.controller.config.vel_gain = 0.06                                 # 速度环比例增益
odrv0.axis0.controller.config.vel_integrator_gain = 0.2                       # 速度环积分增益
odrv0.axis0.controller.config.vel_limit = 57                                  # 速度上限 (turn/s)

# 校准：霍尔必须先做极性校准，再做偏移校准
odrv0.axis0.requested_state = AXIS_STATE_ENCODER_HALL_POLARITY_CALIBRATION
odrv0.axis0.requested_state = AXIS_STATE_ENCODER_OFFSET_CALIBRATION
odrv0.axis0.motor.config.pre_calibrated = True
odrv0.axis0.encoder.config.pre_calibrated = True

# 运行
odrv0.axis0.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL
odrv0.axis0.controller.input_vel = 10                                         # 目标转速 (turn/s)
```

> 要点：霍尔模式下直接执行 `AXIS_STATE_FULL_CALIBRATION_SEQUENCE` 也可以，固件会自动按「极性 → 偏移」的顺序完成校准。完整流程脚本见 [霍尔编码器速度闭环配置脚本](scripts/ODrive_霍尔编码器_速度闭环_配置脚本.md)。

#### 1.2 增量编码器 + 位置模式

适用于带 AB 相正交编码器（可带 Z 相索引）的电机，如伺服电机、带编码器云台电机。分辨率高，适合定位控制。

```python
# 编码器配置：正交增量编码器
odrv0.axis0.encoder.config.mode = ENCODER_MODE_INCREMENTAL
odrv0.axis0.encoder.config.cpr = 8192                                         # CPR = 编码器线数 × 4，按实际填写

# 若编码器带 Z 相索引信号，启用上电自动寻索引
odrv0.axis0.encoder.config.use_index = True
odrv0.axis0.config.startup_encoder_index_search = True                        # 每次上电自动转一圈寻找 Z 相

# 控制配置：位置闭环
odrv0.axis0.controller.config.control_mode = CONTROL_MODE_POSITION_CONTROL
odrv0.axis0.controller.config.input_mode = INPUT_MODE_POS_FILTER
odrv0.axis0.controller.config.pos_gain = 20                                   # 位置环增益
odrv0.axis0.controller.config.vel_gain = 0.167                                # 速度环比例增益
odrv0.axis0.controller.config.vel_integrator_gain = 0.333                     # 速度环积分增益
odrv0.axis0.controller.config.vel_limit = 10                                  # 速度上限 (turn/s)

# 校准与运行
odrv0.axis0.requested_state = AXIS_STATE_FULL_CALIBRATION_SEQUENCE
odrv0.axis0.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL
odrv0.axis0.controller.input_pos = 1                                          # 目标位置（单位：圈）
```

> 要点：启用 `startup_encoder_index_search` 后每次上电电机会转动一圈寻找 Z 相，需确保此时空载。若编码器无 Z 相，把 `use_index` 设为 `False` 并关闭该启动项。

#### 1.3 绝对值编码器 + 位置模式

适用于 SPI 接口的绝对值编码器，如 AS5047P、AS5048A（AMS 协议）或 AMT23xx（CUI 协议）。断电后位置不丢失，上电无需重新校准。

```python
# 绝对值 SPI 编码器：AS5047P / AS5048A 用 AMS 协议，AMT23xx 用 CUI 协议
odrv0.axis0.encoder.config.abs_spi_cs_gpio_pin = 4                            # CS 引脚接到哪个 GPIO 就填几
odrv0.axis0.encoder.config.mode = ENCODER_MODE_SPI_ABS_AMS
odrv0.axis0.encoder.config.cpr = 2**14                                        # AMT232A / AMT233A 填 2**12

# 控制配置：位置闭环
odrv0.axis0.controller.config.control_mode = CONTROL_MODE_POSITION_CONTROL
odrv0.axis0.controller.config.input_mode = INPUT_MODE_POS_FILTER
odrv0.axis0.controller.config.pos_gain = 20                                   # 位置环增益
odrv0.axis0.controller.config.vel_gain = 0.167                                # 速度环比例增益
odrv0.axis0.controller.config.vel_integrator_gain = 0.333                     # 速度环积分增益

# 绝对值编码器无需寻索引，但仍需做一次偏移校准
odrv0.axis0.requested_state = AXIS_STATE_ENCODER_OFFSET_CALIBRATION
odrv0.save_configuration()                                                    # 校准值写入 Flash
odrv0.reboot()                                                                # 之后上电免校准

# 运行
odrv0.axis0.requested_state = AXIS_STATE_CLOSED_LOOP_CONTROL
odrv0.axis0.controller.input_pos = 1                                          # 目标位置（单位：圈）
```

> 要点：偏移校准只需做一次，保存后每次上电编码器立即可用。若出现编码器启动慢于 ODrive 的情况，重启后执行一次 [错误清除](#常见问题) 即可。

三种模式的对比：

| 对比项 | 1.1 霍尔 | 1.2 增量 | 1.3 绝对值 |
| :--- | :--- | :--- | :--- |
| 分辨率 | 低（极对数 × 6） | 高（线数 × 4） | 高（2¹⁴） |
| 典型控制模式 | 速度闭环 | 位置闭环 | 位置闭环 |
| 上电是否需校准 | 需重新校准 | 需寻 Z 相 | 仅需一次 |
| 断电位置保持 | 否 | 否 | 是 |
| 接线复杂度 | 低（3 线） | 中（4–5 线） | 中（SPI 4 线） |

完整的参数说明与故障处理见 [commands.html](commands.html) 与 [troubleshooting.html](troubleshooting.html)。

### 示例二：基础接线

电机与编码器的最小接线方式：

![ODrive 基础接线图](_images/ODriveBasicWiring.png)

详见 [getting-started.html](getting-started.html)。

### 示例三：查看编码器实时波形

启动 `odrivetool` 后可用内置绘图器观察位置估计曲线：

![位置估计实时曲线](_images/liveplotter-pos-estimate.png)

详见 [odrivetool.html](odrivetool.html)。

### 示例四：机械尺寸

![ODrive 机械尺寸图](_images/mech_dimensions.png)

详见 [specifications.html](specifications.html)。

---

## 文档索引

共 33 个页面，按主题分类：

| 分类 | 页面 |
| :--- | :--- |
| 入门 | [首页](index.html) · [入门指南](getting-started.html) · [odrivetool 工具](odrivetool.html) |
| 控制 | [控制总览](control.html) · [控制模式](control-modes.html) · [编码器](encoders.html) · [限位开关](endstops.html) |
| 硬件接口 | [引脚定义](pinout.html) · [电气规格](specifications.html) · [USB](usb.html) · [UART](uart.html) · [RC PWM](rc-pwm.html) · [步进/方向](step-direction.html) · [模拟输入](analog-input.html) · [热敏电阻](thermistors.html) |
| CAN 总线 | [CAN 指南](can-guide.html) · [CAN 协议](can-protocol.html) |
| 通信协议 | [协议总览](protocol.html) · [ASCII 协议](ascii-protocol.html) · [Native 协议](native-protocol.html) · [命令参考](commands.html) |
| 开发进阶 | [开发者指南](developer-guide.html) · [VSCode 配置](configuring-vscode.html) · [Eclipse 配置](configuring-eclipse.html) · [Hoverboard 改装](hoverboard.html) |
| 排查与维护 | [故障排查](troubleshooting.html) · [接地环路](ground-loops.html) · [版本迁移](migration.html) · [更新日志](changelog.html) |
| 索引 | [全文搜索](search.html) · [术语索引](genindex.html) |

---

## 配套脚本

| 脚本 | 适用场景 |
| :--- | :--- |
| [霍尔编码器 + 速度闭环配置脚本](scripts/ODrive_霍尔编码器_速度闭环_配置脚本.md) | 极对数 2、霍尔编码器（CPR 12）的双轴电机，按「清配置 → 设参数 → 校准 → CAN → 试转 → 排错 → 查参」全流程配置，含参数注释与安全提示 |
| [增量编码器 + 速度闭环配置脚本](scripts/ODrive_增量编码器_速度闭环_配置脚本.md) | 极对数 20、增量编码器（CPR 8192）、120 A 大电流双电机；含关键参数确认表、上电自检流程、参数整定顺序与故障排查表 |
| [配置示例合集](scripts/ODrive_配置示例合集.md) | 6 个场景的完整配置：增量 8192 双电机、轮毂霍尔、X2212 速度环、X2212 无传感器、X2212 转矩环、MN5212 + AS5047P SPI；附控制模式与轴状态枚举、通用调试指令、配置备份恢复 |

---

## 固件下载

仓库 `固件/` 目录提供 v0.5.1 – v0.5.6 官方固件压缩包，共约 148 MB。

| 固件版本 | 文件 | 大小 |
| :--- | :--- | :--- |
| v0.5.1 | [固件v0.5.1.zip](固件/固件v0.5.1.zip) | 2.0 MB |
| v0.5.2 | [固件v0.5.2.zip](固件/固件v0.5.2.zip) | 31 MB |
| v0.5.3 | [固件v0.5.3.zip](固件/固件v0.5.3.zip) | 31 MB |
| v0.5.4 | [固件v0.5.4.zip](固件/固件v0.5.4.zip) | 31 MB |
| v0.5.5 | [固件v0.5.5.zip](固件/固件v0.5.5.zip) | 36 MB |
| v0.5.6 | [固件v0.5.6.zip](固件/固件v0.5.6.zip) | 19 MB |

> 不同固件版本需搭配对应版本的 `odrivetool`：v0.5.1 固件用 `pip install --upgrade odrive==0.5.1.post0`，
> v0.5.6 用 `pip install --upgrade odrive`。刷机前先执行 `odrv0.enter_dfu_mode()` 进入 DFU 模式。

---

## 常见问题

| 问题 | 原因与解决办法 |
| :--- | :--- |
| **搜索框输入后无结果** | 以 `file://` 直接打开时，浏览器安全策略阻止加载 `searchindex.js`。改用 `python -m http.server` 启动本地服务后访问。 |
| **页面没有样式，只有纯文字** | `_static/` 目录不完整。请重新完整克隆仓库，不要单独下载单个 HTML 文件。 |
| **点外链提示 404** | 外链指向 `_static/external/` 下的本地镜像。若该目录被删除，链接会失效，可手动跳转原站。 |
| **仓库太大，克隆很慢** | 249 MB 来自 `_static/external/`。只需要正文时可删除该目录，体积降至约 33 MB。 |
| **内容与官方文档不一致** | 本镜像对应 **v0.5.6**，官方可能已更新。请以 [docs.odriverobotics.com](https://docs.odriverobotics.com) 最新版为准。 |
| **翻译有误或术语不统一** | 欢迎提交 Issue 或 Pull Request，参与方式见[贡献指南](#贡献指南)。 |
| **能在 Gitee Pages 上直接看吗** | 可以，但需仓库所有者开启 Gitee Pages 并完成实名认证。开启后访问 `https://servo168.gitee.io/ODrive-v3.6-DOC/`。 |

---

## 贡献指南

欢迎参与翻译校对与错误修正。

**流程**

1. Fork 本仓库
2. 新建分支，建议命名 `fix/页面名-简述` 或 `feat/新增内容`
3. 修改后提交 Pull Request，并在描述中说明改动位置与依据

**修改原则**

- 翻译修正请优先改动 `_sources/*.rst` 源文件，再重新生成 HTML；直接改 HTML 会导致源文件与页面不同步。
- **不要**提交对 `_static/external/` 的内容改动，该目录是第三方站点镜像，重新抓取会被覆盖。
- 术语请保持一致，可参考 [genindex.html](genindex.html) 中的已有译法。
- 如发现与官方最新版的功能差异，请在 Issue 中标注对应的固件版本号。

**联系方式**

QQ 技术交流千人群：

- 1 群：20853369（已满）
- 2 群：1109902153

淘宝店：[servo168.taobao.com](http://servo168.taobao.com)

---

## 开源协议

本项目采用 **MIT License**，版权归Magic (`servo168`) 所有，详见 [LICENSE](LICENSE) 文件。

**关于原文档版权**：英文原文版权归 [ODrive Robotics](https://odriverobotics.com) 所有，本仓库是其翻译与离线镜像版本。若涉及二次分发或商业使用，请先与上游确认授权范围。

**免责声明**：硬件操作存在安全风险，因参照本文档操作导致的人身或财产损害，维护者不承担责任。

---

## 致谢

- 原文档：[ODrive Robotics 官方文档](https://docs.odriverobotics.com)
- 文档生成：[Sphinx](https://www.sphinx-doc.org) 与 `sphinx_rtd_theme`
- 翻译档：淘宝店：蒙F外星科技 | [servo168.taobao.com](http://servo168.taobao.com)