大家好，又见面了，我是你们的朋友全栈君。

ODrive固件开发指南

本指南适用于希望修改ODrive固件的开发人员。
因此，它假定您了解诸如如何使用Git，什么是编译器之类的知识。如果这听起来很陌生，以下内容对您来说可能不适合。
官方发行版在master分支上。 但是，由于您是开发人员，因此建议您使用devel分支，因为它包含最新功能。
该项目正在积极开发中，因此请确保检查更新日志以跟踪更新动态。

需要的开发工具

推荐使用的ODrive开发工具为：

• make: 用于调用 tup
• Tup: 用于调用编译命令的构建系统
• ARM GNU Compiler: 对于交叉编译代码
• ARM GDB: 用于调试代码并在设备上逐步执行
• OpenOCD: 用与使用STLink / v2编程器对ODrive进行烧录
• Python3: 用于运行Python工具，并且安装 PyYAML，Jinja2 ，jsonschema 包

有关适用于您的操作系统的特定安装说明，请参见下文。
根据您要执行的操作，可能并不需要所有组件。
一切准备就绪后，您可以运行以下命令来验证安装是否正确：

$ arm-none-eabi-gcc --version
$ arm-none-eabi-gdb --version
$ openocd --version             # should be 0.10.0 or later
$ tup --version                 # should be 0.7.5 or later
$ python --version              # should be 3.7 or later

Linux (Ubuntu)

sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
sudo apt-get update
sudo apt-get install gcc-arm-embedded
sudo apt-get install openocd
sudo add-apt-repository ppa:jonathonf/tup && sudo apt-get update && sudo apt-get install tup

Arch Linux

sudo pacman -S arm-none-eabi-gcc arm-none-eabi-binutils
sudo pacman -S arm-none-eabi-gdb
sudo pacman -S tup

• OpenOCD AUR package

Mac

首先安装Homebrew. 然后您可以在命令终端中输入以下命令:

brew install armmbed/formulae/arm-none-eabi-gcc
brew cask install osxfuse && brew install tup
brew install openocd

Windows

注意: 确保这些程序不仅已安装，而且正确添加到您的环境变量PATH中。

本文档中的某些说明可能假定您正在使用bash命令提示符，例如Windows 10内置bash或Git bash。

• ARM compiler
  • 注意 1: 安装后需要添加 ARM_GCC_ROOT 到您的环境变量，并设置值为您的安装路径 e.g. C:\Program Files (x86)\GNU Tools Arm Embedded\7 2018-q2-update。此变量将被 Visual Studio Code 所使用。
  • 注意 2: 8-2018-q4-major 版本在Windows下存在某些bug。请在Windos下使用 7-2018-q2-update版本。
• Tup
• GNU MCU Eclipse’s Windows Build Tools
• OpenOCD.
• ST-Link/V2 Drivers

配置编译参数

要自定义编译参数，请将文件Firmware/tup.config.default复制或重命名为Firmware/tup.config，然后在该文件中编辑参数：

CONFIG_BOARD_VERSION: 您正在使用的ODrive硬件版本。 可以是v3.1，v3.2，v3.3，v3.4-24V，v3.4-48V，v3.5-24V，v3.5-48V等。检查ODrive上的丝印以找出您使用的版本。 某些ODrive版本未指定电压：在这种情况下，您可以看一下电容器的值：120uF是48V ODrive，470uF是24V ODrive。

CONFIG_USB_PROTOCOL: 定义ODrive在USB接口上使用的协议。

• native: ODrive原生通讯协议。ODrive以USB设备被系统识别。在macOS系统下有可能无法工作。
• native-stream: 和原生通信协议类似，只不过ODrive被系统以UART连接对待。可以在macOS系统下正常工作。
• none: 禁用 USB通讯。虽然插入设备后仍会被现实，但它将忽略所有指令。

注意: 第二个USB接口始终是一个串行端口。

CONFIG_UART_PROTOCOL: 定义ODrive在UART接口（GPIO1和GPIO2）上应使用哪种协议。 请注意，仅ODrive v3.3和更高版本支持UART。

• native: ODrive原生通信协议。如果要使用UART将ODrive连接到PC，并且想使用python工具来控制和设置ODrive，请使用此功能。
• ascii: ASCII 格式通信协议。如果您想使用Arduino控制ODrive，请使用此选项。因为 ODrive Arduino库尚不支持ODrive原生通信协议。
• none: 禁用UART。

构建并烧录固件

1. 在 Firmware 目录下运行 make 。
2. 通过USB连接ODrive并打开电源。
3. 使用 odrivetool dfu命令烧录固件。

使用STLink/v2 烧录固件

• 将烧录器连接到 J2 端子上的GND, SWD, SWC。 注意: 应当首先连接GND 。
• 您仅需通过VCC（3.3v）、5V、**主电源连接（DC总线）**其中一项对ODrive供电。 USB端口（J1）是无法为ODrive供电的。
• 在 Firmware 目录下运行 make flash
  注意: 如果出现错误类似 can't find target interface/stlink-v2.cfg ，您需要设置一个名为OPENOCD_SCRIPTS的环境变量，变量值设置为 openocd 脚本所在目录地址。

如果烧录成功，您可以使用 odrivetool和ODrive通信了。

自动化测试

tools/run_tests.py 这个测试脚本可以自动测试固件的某些特性还能够对ODrive进行老化测试。某些测试项目只需要一个电机加上编码器就可以，还有一些测试需要特定的测试台才可以。要进行任何测试都需要一个YAML文件，在YAML中编写测试参数，例如tools/test-rig-parallel.yaml。其中YAML中烧录器的序列号可以通过运行Firmware/find_programmer.sh脚本来得到(确保烧录器中的固件为STM的最新固件)。
测试脚本会使ODrive以高电流和高转速运行，因此，如果测试台不合适或者不够坚固（或电机空载），则可能会损坏机器。
用法示例：./run_tests.py --test-rig-yaml ../tools/test-rig-parallel.yaml

代码调试

如果您使用的是VSCode，请确保您具有Cortex Debug扩展插件，OpenOCD和STLink。 您可以通过烧录代码来验证OpenOCD和STLink是否正常工作。 打开ODrive_Workspace.code-workspace文件，然后启动调试（F5）。 VSCode将从工作空间中获取正确的设置并自动连接ODrive。 可以在VSCode中以图形方式添加断点。

• 运行 make gdb。 这将重置并在程序启动并暂停。 现在，您可以设置断点并运行程序。 如果您知道如何使用gdb，那就再好不过了。

配置集成开发环境

开发ODrive代码，不需要IDE，但是建议使用开源IDE VSCode。 也可以使用Eclipse。 如果您想使用IDE，请参阅相应的配置文档：

• 配置 Visual Studio Code 开发环境
• 配置Eclipse开发环境

STM32CubeMX

该项目使用 STM32CubeMX 来生成启动代码和外设配置代码。您可以从这里下载CubeMX。所有 CubeMX 相关的文件都在 Firmware/Board/v3文件夹下。

维护修改后生成的代码

STM32CubeMX 生成代码时，会剔除它们提供的某些特殊部分之外的所有内容。 特殊部分标记为“ USER CODE BEGIN” …“ USER CODE END”。
曾经，我们试图确保对生成的代码所做的所有编辑仅会出现在这些部分中，从某些代码结构就可以看出来。
但是随着时间的流逝，我们意识到这将很难实现，因此，当需要重新生成代码时，我们利用git来进行管理。我们使用两个特殊的git分支来实现。它们是 STM32CubeMX-start 和 STM32CubeMX-end。
下例显示了如何使用它们。
注意: 由于使用git rebase方式，所有更改生成代码的开发都应直接在STM32CubeMX-end上进行，而不是基于devel进行，然后按照下面的步骤4进行操作，以将其转移到新的功能分支中。 如果您对基于devel生成的代码进行了一些更改，则只需挑选那些更改到STM32CubeMX-end中即可。

1. 准备更改

• 我们对STM32CubeMX配置进行的所有更改，并重新生成代码都应该在STM32CubeMX-start分支上。所以我们使用下面的命令切换到STM32CubeMX-start分支上。
  • git checkout STM32CubeMX-start
• 运行stm32cubeMX 然后载入Firmware/Board/v3/Odrive.ioc 工程文件。
  • 如果载入过程中询问您是否要迁移到新版本，请选择下载旧的固件包（除非您要使用最新的库）。
• 在不更改任何设置的情况下，点击 Project -> Generate code。
• 您可能需要让它下载一些驱动程序等。
• STM32CubeMX现在可能具有某些库已经更新，因此即使我们未更改任何设置，生成的代码也可能有所更改。 我们需要检查一切是否仍在工作，并检查更改：
• git config --local core.autocrlf input 这会告诉git的所有文件应与LF结尾（CubeMX产生CRLF结尾）进行检查。
• git diff 忽略一堆行结束警告。
• 如果您觉得可以: 您现在可以检查CubeMX是否引入了一些愚蠢的方法。 如果有任何更改，并且看起来可以接受，我们应该提交它们：
  • git commit -am "Run STM32CubeMX v1.21" 替换为实际版本的CubeMX。

2. 更改STM32CubeMX配置

• 完成上述步骤后，请确保工作目录是干净的：
  • git status 应该会显示 “nothing to commit, working tree clean”
• 使用STM32CubeMX进行配置，保存，然后重新生成代码 (Project -> Generate code)。
• git diff 检查引入的更改是否符合预期
• 如果一切正常，则可以提交更改。

3. 将重新配置生成的代码rebase到STM32CubeMX-end分支

• git checkout STM32CubeMX-end
• git rebase STM32CubeMX-start
• 确保完成rebase，并修复可能出现的任何冲突。

4. 将新的STM32CubeMX代码合并到功能分支中

只需将STM32CubeMX-end分支合并到新功能分支中。

• git checkout your-feature
• git merge STM32CubeMX-end

5. 将您的新特性分支提交到原作者

• 为您的新功能生成正常的pull，request。
• 确保已将提交STM32CubeMX-start和STM32CubeMX-end分支，到您的分支。
• 并在提交记录中说明需要更新STM32CubeMX分支。

故障排除

使用 STLink/v2烧录提示LIBUSB_ERROR_IO

问题描述: 当我使用STLink对ODrive进行烧录时提示如下错误：

Open On-Chip Debugger 0.10.0
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 2000 kHz
adapter_nsrst_delay: 100
none separate
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : clock speed 1800 kHz
Error: libusb_open() failed with LIBUSB_ERROR_IO
Error: open failed
in procedure 'init' 
in procedure 'ocd_bouncer'

解决方案:
这种情况时有发生。可以按照下列步骤来操作：

1. 从电脑拔出 STLink 和 ODrive
2. 断开 ODrive 的供电
3. 将STLink插入电脑
4. ODrive上电
5. 再次尝试执行 make flash

发布

我们使用GitHub Releases发布固件。

1. 查看changelog以了解新固件的新特性。
2. 将其他特性分支合并到master支。
3. 将（轻量级）标签推送到master分支。 请遵循现有的命名约定。
4. 将python工具推送到PyPI。
5. 在GitHub上发布该版本以添加标题和描述（从changelog复制并粘贴）。

其他代码维护说明

cortex M4F处理器具有硬件单精度浮点单元。 但是，双精度运算并没有被加速，因此应该避免。 以下正则表达式会清除双精度运算：
find: ([-+]?[0-9]+\.[0-9]+(?:[eE][-+]?[0-9]+)?)([^f0-9e])
replace: \1f\2

代码提交须知

一般而言，该项目使用 Google C++ Style Guide，不同之处在于默认指示符为4个空格，并且对80个字符的限制不是非常严格的。

如果您有任何问题或疑问，欢迎您加入ODrive社区或QQ群 851421965 进行交流。