项目入门

来战斗吧，年轻人。

项目的目标是实现一个高性能的机器人规划控制实验平台，在初期规划时就尤为注意其可拓展性，以便后续的研究工作能够顺利进行。本项目一方面希望能够集合整理各类已有的规划、控制、求解、仿真算法，在统一的平台上进行对比和评估，另一方面也希望能够为后续的研究工作提供一个可靠的基础平台，尤其是多臂甚至多智能体的研究工作。

之后的任务文档我都会放在这个文件夹内，每个任务的文档都会以 markdown 的形式存在，以便于查看和修改。

项目文件说明及阅读顺序

在组织中有多个库

Robot-Platform 系统内核库，主语言为 Rust、Python
roplat-pages 项目文档及网页，采用 mkdocs 部署在网页上
roplat Roplat 前端库，主语言为 TypeScript
libfranka-rs franka 机械臂驱动 rust 封装，之后如果有其他机器人驱动，建议重新开辟存储库
franka-rust franka 机械臂驱动的原生 rust 实现
Reference 一些参考文献和论文

建议阅读顺序为：本页->开始:魔法少女第一课->Rust:勇者获得了村好剑->内核->节点:年轻人的第一个节点->任务列表

入门基础

关于 vscode

由于后续工作涉及到多语言多设备的监控和开发。vscode 是一个统一标准的开始!下面是一些项目相关的插件和配置，相信我，你会用到的。

语言支持类插件

（必须）Rust Extension Pack 。这是 rust 相关插件的打包，其中 rust-analyzer 将会成为后续工作中最重要的插件
Python Extension Pack 。这是 python 相关插件的打包，同上
（可选）Pylint 。一款 python 代码规范，但是和 error lens 结合会导致部分人血压飙升（就是那批习惯写python没有规范的人），可以禁用部分功能
Path Intellisense 。这是一个路径自动补全插件，对于多语言开发尤为重要
markdown all in one 。
markdown preview enhanced 。这两个插件是用来写 markdown 的，前者提供了一些快捷键，后者提供了预览功能,后者甚至提供了一些高级功能，如ppt输出、word输出等等，他们有专门的中文文档，自己去看啦
markdownlint 。这是一个 markdown 代码规范插件，对于写文档尤为重要，好好记下markdown格式规范吧小鬼，这个相较于 pylint 要轻柔一点，感恩戴德吧。

注释与报错功能类

（必须）Error Lens 。warning 在下方状态栏可能被无视，糊你一脸就不一样链路。error lens 就是致力于吧报错糊你一脸的插件，结合 pylint 有小儿止啼的效果
（必须）Better Comments 。这是一个注释插件，可以让你的注释更加美观，更加有层次感，会给你不同格式的注释以不同的颜色，
GitLens 。这是一个 git 插件，提供了一些 git 的功能，如历史记录、代码比较等等
github Copilot 。学生身份就能申请到的免费gpt，但是只能用于代码
Ayu 。一款我非常喜欢的主题插件，嚎堪！

有用的配置

你会喜欢的

// setting.json
//*? 这是对编译器全局的设置
{
  "files.autoSave": "onFocusChange", //自动保存
  "files.autoGuessEncoding": true,
  "editor.guides.bracketPairs": true,
  "editor.formatOnType": true,
  "editor.formatOnSave": true,
  "editor.unicodeHighlight.allowedLocales": {
    "zh-hant": true
  },
  "editor.minimap.enabled": false, //控制是否显示缩略图。
  "editor.bracketPairColorization.independentColorPoolPerBracketType": true,
  "editor.renderControlCharacters": true,
  "editor.experimental.pasteActions.enabled": true,
  "editor.suggest.preview": true,
  "editor.suggest.showDeprecated": false,
  "editor.suggest.showStatusBar": true,
  "editor.suggestSelection": "recentlyUsedByPrefix",
  "editor.acceptSuggestionOnEnter": "off",
  "editor.fontFamily": "Fira Code",
  "editor.stickyScroll.defaultModel": "foldingProviderModel",
  "editor.stickyScroll.maxLineCount": 5,
  "editor.stickyScroll.enabled": true,

  "workbench.editor.pinnedTabsOnSeparateRow": true,

  //*? 以下是对 markdownlint 的配置
  "markdownlint.config": {
    "default": true,
    "MD025": false,
    "MD033": false,
    "MD024": false
  },
}

关于 Rust

为了实现高性能的实验平台的搭建，留给我们的选择并不多。在一项关于不同编程语言的运行效率和其消耗的能源的研究中https://greenlab.di.uminho.pt/wp-content/uploads/2017/10/sleFinal.pdf其分析结果如下图。图 0

可以看到 C 语言与 Rust 语言在运行效率和能源消耗上具有遥遥领先的地位，甚至超越 C++ 半个头（近乎是 Python 的 76 倍！）。同时 Rust 语言在代码安全、系统并发甚至coding阶段对代码运行时的逻辑检查等方面有这其他语言近乎无法比拟的优势。因此我们选择 Rust 语言作为我们的项目开发语言。

在 coding 阶段就能对代码逻辑检查这个简直太厉害了，相同的功能在 c++ 或者 python 中几乎没有或者需要额外的工具才能实现，而这个功能能有效的减少代码与数学逻辑不符的部分，显著减少后期在调试和debug上的精力和时间。

一个简单的例子被我写在 /tests/code-check.rs 中：以下是可以正常运行的代码图 2
但是如果你在编码或者数学上犯了点小错误，比如吧不同长度的向量相加，这种问题 eigen 库会在运行时通过一次 assert 来报错，而 rust 呢？我们严苛的编译器老师会毫不留情的指出来图 1

更多的例子不再一一例举，总而言之，Rust 编译器会鞭打你的代码，直到它变得足够强壮。

入门圣经在这里https://course.rs/about-book.html

这可能将会是你入门时感觉最简单或者最难的一门语言，毕竟千人千面，但是一旦当你拿着这把武器开始编码的时候，你就会被虐的体无完肤（x。准确说入门的前半段时间就是和编译器战斗，编译期将改造你的代码审美，让你的代码更加优雅，更加安全，更加高效。之后某个时间点，你会突然感叹 Rust 的精巧设计和伟大之处，发出卧槽卧槽的感叹。

当然，还有一些注意事项，如注释格式、文档格式、命名风格等，编译器无法强行要求你这些内容，但是仍然有约定俗成的规定

关于注释和文档 https://course.rs/basic/comment.html
关于变量和函数命名 https://course.rs/practice/naming.html
关于项目架构 https://course.rs/cargo/guide/package-layout.html https://course.rs/cargo/reference/workspaces.html

当然出于本人对 Rust 圣经的推崇（我就是新任传教士），上面的连接大多节选自 Rust 圣经，如果有时间的话，我还是非常建议你能阅读完这本书。

关于更多的 Rust 简易入门的内容，见

关于机器人学

较多机器人学的相关知识，如规划啊、控制啊、优化问题啊如此如此这般这般。

较好的方案是找本教材看啦，当然也有速成的方法。谁说抱佛脚不算虔诚呢？

下面应该列举一系列必读文章或者书单，但是我自己也还没找全呢，有机会再列举吧，项目相关的论文被我塞在组织中的另外一个私有库了，毕竟人家的成果咱分析分析得了。

关于项目管理

git 管理

开始操作的时候一定要新建自己的分支，不要直接在主分支上操作。可以从主分支或者我的分支（yixing）开一个分支给自己，然后在自己的分支上操作，操作完了之后再合并到主分支或者我的分支上。

提交代码时请务必确保 0 warning 0 error，这是一个非常基本的要求！！ rust 代码要求过一遍 cargo clippy

代码管理

本项目编程语言以 rust 为主，python 为辅，还有一些标记语言如 json 或者 yaml 文件，受困与 ros-rust 的部分功能不完善，我们可能还要考虑 C++ 语言的使用。

不同的代码语言有自己对应的路径位置，如 rust 代码放在 /src 文件夹下，python 和 matlab 应该放在 /scripts 文件夹下，C++ 代码放在 /src 文件夹下另开文件夹，但是万不得已还是不要用 C++ 了。（我不想给 C++ 项目写编译链和依赖关系）