# odrive-can-protocol
[](https://crates.io/crates/odrive_can_driver)
[](https://crates.io/crates/odrive-can-protocol)
[](https://docs.rs/odrive-can-protocol)
[](https://docs.rs/crate/odrive-can-protocol/0.1.3/source/LICENSE)
[](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0/)
> **已弃用 / Deprecated**:本 crate 已合并到 [`odrive_can_driver`](https://crates.io/crates/odrive_can_driver) 的 `protocol` 模块,停止独立维护。新项目和后续更新请使用 `odrive_can_driver`。
>
> `0.1.3` 仅更新包元数据和文档;协议实现、现有 API、依赖与 MSRV 保持不变。crates.io 历史版本继续保留,供已有依赖使用。
## 迁移到 odrive_can_driver
使用 `odrive_can_driver 0.2`(要求 Rust 1.98.1 或更新版本):
```toml
[dependencies]
odrive_can_driver = "0.2"
```
将旧导入路径增加 `protocol` 层,例如:
```diff
-use odrive_can_protocol::fw_v0_5_1::{encode, Command, Message, NodeId};
+use odrive_can_driver::protocol::fw_v0_5_1::{encode, Command, Message, NodeId};
```
原 crate 根的类型和函数迁至 `odrive_can_driver::protocol`,帧适配入口迁至 `odrive_can_driver::protocol::compat`。`embedded-can`、`embassy-stm32`、`socketcan` 三个可选 feature 名称不变;仅编解码仍可使用默认 `no_std`、无分配、零依赖构建。旧包和新包定义的类型不能混用,应同时更新相关导入。
新包同时提供设备驱动、查询与收发后端。迁移和接入方式见[新项目 README](https://github.com/MRNIU/odrive-can-driver)及[协议 API](https://docs.rs/odrive_can_driver/0.2.0/odrive_can_driver/protocol/)。
## 旧包参考
以下内容仅供仍使用 `odrive-can-protocol 0.1` 的项目参考。
`odrive-can-protocol` 是 ODrive CANSimple 的硬件无关编解码库。默认构建使用 Rust 2024、`#![no_std]`、无 `alloc`、零依赖,MSRV 为 Rust 1.85;它不访问 CAN 外设,也不管理任务、时序或控制策略。
## 安装
```toml
[dependencies]
odrive-can-protocol = "0.1.3"
```
Rust 中的 crate 名为 `odrive_can_protocol`。完整 API 见 [rustdoc](https://docs.rs/odrive-can-protocol)。
## 快速开始
```rust
use odrive_can_protocol::fw_v0_5_1::{encode, Command, Message, NodeId};
let frame = encode(
NodeId::new(1).unwrap(),
Message::Command(Command::SetInputVel {
velocity: -2.5,
torque_ff: 0.25,
}),
)
.unwrap();
assert_eq!(frame.id(), 0x02d);
```
更多编码、RTR 查询和 Heartbeat 解码见 [`examples/encode_decode.rs`](https://docs.rs/crate/odrive-can-protocol/0.1.3/source/examples/encode_decode.rs):
```sh
cargo run --example encode_decode
```
## 协议支持
当前 API 位于 `odrive_can_protocol::fw_v0_5_1`,crate 根同时重导出主要类型与 `encode`、`decode`。它支持标准 11-bit Classic CAN;多字节字段为 little-endian,浮点字段为 IEEE 754 binary32。
| ODrive `fw-v0.5.1` | `fw_v0_5_1` | 已支持 |
| MKS ODrive Mini `ODriveMINI-fw-v0.5.1-20250326` | `fw_v0_5_1` | 已支持,同一 CANSimple 布局 |
MKS 结论仅覆盖该固定源码包:[ODriveMINI-fw-v0.5.1-20250326.rar](https://github.com/makerbase-motor/MKS-ODrive/blob/e15782976ae93d42b1f0648ceec96503141a343b/Firmware/MKS%20ODrive%20MINI/ODriveMINI-fw-v0.5.1-20250326.rar)。该包的 CANSimple 源码与官方 [ODrive `fw-v0.5.1`](https://github.com/odriverobotics/ODrive/tree/7831d795235e5ef8535e4b46621a0721b458ec8f) 基线一致,因此无需 MKS 专用 feature 或转换层。其他 MKS 固件版本应先核对源码。
## 可选兼容层
兼容层是 crate 的 optional feature;启用后可直接使用原生帧类型,无需自行复制转换代码。`embedded-can` 是 Embassy STM32 与 SocketCAN 的共同基础,后两者会自动启用它。
| `embedded-can` | 通用 Classic `embedded_can::Frame` 转换 | MSRV 1.85 |
| `embassy-stm32` | `embassy_stm32::can::Frame`、`FdFrame` 转换 | 消费方选择芯片与 `embassy-stm32 0.6` feature |
| `socketcan` | Linux `socketcan::CanFrame`、`CanAnyFrame` 转换 | Linux、SocketCAN 4、Rust 1.89 |
`embedded-can` 使用 `EncodedFrame::to_embedded_can::<F>() -> Option<F>` 创建原生 Classic 帧;`FrameRef::from_classic_embedded_can(&frame)` 借用解码,并在 `compat::embedded_can::InvalidFrameLength` 中报告无法表示的长度。该 trait 不携带 CAN FD 或 Linux 错误帧语义,因此该入口只接收已确认的 Classic 帧。
启用 `embassy-stm32` 后,`embassy_stm32::can::Frame` 与 `FdFrame` 均实现 `From<&EncodedFrame>`,`FrameRef` 实现对二者借用的 `TryFrom`;错误类型位于 `compat::embassy`。启用 `socketcan` 后,`socketcan::CanFrame` 实现 `From<&EncodedFrame>`,`FrameRef` 实现对 `CanFrame` 和 `CanAnyFrame` 借用的 `TryFrom`;错误类型位于 `compat::socketcan`。
驱动依赖、芯片选择和最小接入示例见 [examples](https://docs.rs/crate/odrive-can-protocol/0.1.3/source/examples/README.md)。
## API 边界
`encode(node, message)` 只完成协议编码;`decode(node, frame)` 只还原该节点的已知消息。设备错误位、未知状态和线上浮点位模式作为协议数据保留。应用负责收发、设备许可、超时、重试、单位换算和动作结果判断。
## 后续维护
此旧包停止独立维护。问题反馈、修复和功能贡献请前往 [`odrive-can-driver`](https://github.com/MRNIU/odrive-can-driver)。
## License
本项目采用 [MIT License](https://docs.rs/crate/odrive-can-protocol/0.1.3/source/LICENSE),保留原版权信息。