From fa4a78a7a1b746e7837e51b742961333ce2f065b Mon Sep 17 00:00:00 2001 From: NeoZng Date: Mon, 24 Jul 2023 23:29:13 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E6=96=B0=E7=BB=84=E7=BB=87=E4=BA=86?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=E5=88=86=E7=B1=BB=EF=BC=8C?= =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E4=BA=86VSCode=E8=87=AA=E5=AE=9A=E4=B9=89?= =?UTF-8?q?=E5=85=A5=E9=97=A8=E6=95=99=E7=A8=8B=EF=BC=8C=E7=BC=96=E5=86=99?= =?UTF-8?q?=E4=BA=86=E9=83=A8=E5=88=86Readme=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 51 +++++++++++++++++++-- application/application.md | 2 +- 必须做&禁止做.md | 4 ++ 让VSCode成为更称手的IDE.md | 93 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 144 insertions(+), 6 deletions(-) create mode 100644 让VSCode成为更称手的IDE.md diff --git a/README.md b/README.md index c513394..a62dad7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # YueLu2022/2023 EC basic_framework-dev - +> ***可能是最完整最详细最好的电控开源！*** [TOC] @@ -9,25 +9,32 @@ - 若无法访问github，戳[gitee仓库](https://gitee.com/hnuyuelurm/basic_framework) - 若gitee内容被屏蔽，戳[github仓库](https://github.com/HNUYueLuRM/basic_framework) -> 基于basic_framework打造的C++进阶重构版本[***powerful_framework***](https://gitee.com/hnuyuelurm/powerful_framework)现已发布！增加全新的消息交互机制和严格的跨任务数据读写保护，采用了现代构建系统CMake+Ninja以追求极致的编译速度，各种针对嵌入式的编译优化全开，DIY程度进一步提升，更有自定义CMSIS-DSP和Eigen等扩展库支持！快来加入试用/和我们一起开发吧。 +> 基于basic_framework打造的C++进阶重构版本[***powerful_framework***](https://gitee.com/hnuyuelurm/powerful_framework)现已发布！增加全新的消息交互机制和严格的跨任务数据读写保护，采用了现代构建系统CMake+Ninja以追求极致的编译速度，各种针对嵌入式的编译优化全开，DIY程度进一步提升，更有自定义CMSIS-DSP和Eigen等扩展库支持！快来加入试用/和我们一起开发吧😋 ## 架构 +### 软件栈 - -## 开发工具 +### 多任务协作 +### 设计思想 +框架在结构上分为三层：bsp/module/app。整体使用的设计模式是**结构层级模式**，即每个“类”包含需要使用的底层“类”，通过组装不同的基础模实现更强大的功能。而最顶层的app之间则通过**pub-sub消息机制**进行解耦，使得在编写代码时不会出现相互包含的情况。 -## 设计思想 +**pub-sub机制的体现**：以本仓库的app层为例，包含了chassis，gimbal，shoot，cmd四个应用，每个应用都对应了机器人上的不同模组。cmd应用负责从机器人控制信号来源（遥控器/上位机/环境传感器）处获取信息并解析成各个**执行单元的实际动作**（电机/舵机/气缸/阀门等的扭矩/速度/位置/角度/开度等），并将此信息**发布**出去。chassis、gimbal、shoot等包含了执行单元的应用则**订阅**这些消息，并通过自己包含的子模块，调用它们的接口实现动作。 +**结构层级模式的体现**：以chassis应用为例，chassis中包含了4个底盘电机模块。当chassis收到cmd应用的信息，希望让底盘以1m/s的速度前进。chassis首先根据底盘的类型（舵轮/麦克纳姆轮/全向轮/平衡底盘）以及对应的动力学/运动学解算函数，计算得到每个电机的输目标输入值，此时chassis将输入通过电机模块（motor module）的接口将设定值告知电机。而每个电机模块又有各自的PID计算模块和自身电流&速度&角度传感器的信息，可以计算出最终需要的电流设定值。假设该电机使用CAN协议与电调通信，则电机通过自身包含的CANInstance（bsp_can提供）用于和实际硬件交互，电机模块将设定值电流值或其他指令按照通信协议组织在CAN报文中，通过CANInstance提供的接口，把最终控制数据发送给电调，实现控制闭环。可以看到，**包含关系为chassis∈motor∈bspcan**。 +有了上面的大体认知，我们分别介绍框架的三层结构。 + +- **bsp**即板级支持包，提供对开发板外设的软件抽象，让module层能使用和硬件无关的接口（由bsp提供）进行数据处理与交互。bsp层和ST的HAL为强耦合，与硬件直接绑定。若要向其他的ST芯片移植，基本不需要修改bsp层；若是其他单片机则建议保留**接口设计**，对接口调用进行重现实现。每一种外设的头文件中都定义了一个**XXXInstance**（xxx为外设名），其中包含了使用该外设所需要的所有数据，如发送/接收的数据，长度，id（如果有），父指针（指向module实例的指针，用于回调）等。由于C没有`class`，因此所有bsp的接口都需要传入一个额外的参数：XXXInstance*，用于实现c++的`this`指针以区分具体是哪一个实例调用了接口。 +- **module**即模块层，包括了需要开发板硬件外设支持的（一般用于通信）真实**硬件模组**如电机、舵机、imu、测距传感器，以及通过 @@ -37,7 +44,41 @@ +## 开发工具 + +介绍完整的工作流。 + +### 工具链 + +强烈推荐使用arm-gnu工具链进行编译（arm-none-eabi-xxx）。 + +官方下载地址：[Arm GNU Toolchain Downloads – Arm Developer](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) + +我们更推荐使用Msys2进行库和开发工具管理，关于如何使用Msys2请参考：[如何使用本框架](##如何使用本框架) + +> 仍然支持使用arm-cc工具链（即keil默认的工具链）进行开发，在cubemx初始化时生成MDK项目即可，然后再手动添加basic_framework的所有头文件和源文件。但非常不建议这样做，arm-cc仅支持单线程编译且编译优化选项远不如arm-gnu多，自定义程度同样不比。~~若你一定要这样做，则可以在VSCode中安装keil assistant插件。~~ + +### IDE? + +使用VSCode作为“IDE”。需要的插件支持均已经在[VSCode+Ozone使用方法.md](VSCode+Ozone使用方法.md)中给出。通过VSCode强大的插件系统、language server以及代码补全高亮助力效率倍增。编译则使用集成的task进行，还可以将开发环境终端加入VSCode进一步提升体验。基本的调试如变量&寄存器查看均已在插件中提供支持，`launch.json`可以进行高自由度的自定义。 + +`Git`集成与额外插件补充让版本管理和协作从未如此简单，`live share`把你的伙伴们聚在一起集思广益，一同对抗困难的bug。更多特性和开发技巧请参考"如何使用本框架"章节。 + +> **不论如何，请不要使用KEIL作为你的代码编辑器。** + +### 调试和性能分析 + +- 基础的调试可以在VSCode中完成。cortex-debug插件的最新版本已经支持多个gdb-server（jlink/stlink/openocd/pyocd）的live watch（动态变量监视）和变量示波器（可视化）。若不是有特别的需求，**请勿使用串口调试器**。 + +- 有高速变量查看和数据记录、多路数据可视化的需求（如进行pid参数整定、查找难以定位的bug）时，使用**Segger Ozone**。 +- FreeMaster也可以作为调试的备选项。 +- 基本的、日常性能分析可以通过`bsp_dwt`完成。若要分析关于任务运行和每个函数执行的详细信息和时间，推荐使用**Segger Systemviewer**。 + ## 如何使用本框架 + + + + ## 后续计划 diff --git a/application/application.md b/application/application.md index cc69d22..9e9636b 100644 --- a/application/application.md +++ b/application/application.md @@ -22,7 +22,7 @@ Robot.c是整个机器人的抽象，其下有4个应用：robot_cmd，gimbal，chassis，shoot。此框架当前是针对步兵/英雄/哨兵设计的，其他机器人只需要根据各自的特殊机构进行修改即可。robot_cmd是整个机器人的核心应用，其负责接受遥控器/上位机发来的指令，并将指令转化为实际的运动控制目标，发送给其他三个应用。后者会根据robot_cmd发来的命令，设定电机和其他执行单元的参考值等。 -为了进一步解耦应用之间的关系，这里并没有采用层级结构（或设计模式中所谓的**工厂模式**，即robot_cmd包含其他三个模块），而采用了应用并列的**发布-订阅**机制，四个应用之间没有任何相互包含关系，他们之间的通信通过module层提供的`message_center`实现。每个应用会通过该模块向一些话题（事件）发布一些消息，同时从一些话题订阅消息。如robot_cmd应用会发布其他三个模块的控制信息，同时订阅其他三个模块的反馈信息。其他三个模块会订阅robot_cmd发布的控制信息，同时发布反馈给robot_cmd的信息，他们不需要知道彼此的存在，只是从`message_center`处获取其他应用发布的消息或向自己发布的话题推送消息。 +为了进一步解耦应用之间的关系，app层并没有module和bsp之间的那种层级结构（或设计模式中所谓的**结构类型模式**，即robot_cmd包含其他三个模块），而采用了应用并列的**发布-订阅**机制，四个应用之间没有任何相互包含关系，他们之间的通信通过module层提供的`message_center`实现。每个应用会通过该模块向一些话题（事件）发布一些消息，同时从一些话题订阅消息。如robot_cmd应用会发布其他三个模块的控制信息，同时订阅其他三个模块的反馈信息。其他三个模块会订阅robot_cmd发布的控制信息，同时发布反馈给robot_cmd的信息，他们不需要知道彼此的存在，只是从`message_center`处获取其他应用发布的消息或向自己发布的话题推送消息。 application在初始化module的时候，初始化参数会包含部分bsp的内容，但仅仅是外设和引脚的选择以及id设置（用于通信的外设需要id设置）。实际上当前框架的app层和cubemx初始化部分耦合，在配置的时候就必须确定每个外设的作用和归属权，一旦cubemx完成设置app层必须按照对应参数设置引脚和并分配module的外设。后续考虑将cubemx和bsp耦合，去除顶层代码和底层的关系 diff --git a/必须做&禁止做.md b/必须做&禁止做.md index 06cc739..0858ab7 100644 --- a/必须做&禁止做.md +++ b/必须做&禁止做.md @@ -8,6 +8,10 @@ 除非你使用的是基于计数寄存器差值的延时方法,或阻塞式的for延时。 **若有必要，应该使用`bsp_dwt.h`提供的接口。 +## 若任务耗时较长导致可能出现数据读写被中断或更高优先级的任务打断，请为你的数据添加锁 + +若同时要求数据的实时性，考虑将低优先级线程设置为由高优先级任务唤醒，或添加位互斥锁（而不是osMutex！确保中断也可以使用）。 + ## 禁止图方便直接将电机/电调连接在开发板的xt30接口上，否则电机的反电动势可能烧毁开发板 后续考虑增加一个xt30转接器，其上实现隔离电路，再连接开发板充当分电板。 diff --git a/让VSCode成为更称手的IDE.md b/让VSCode成为更称手的IDE.md new file mode 100644 index 0000000..dbda057 --- /dev/null +++ b/让VSCode成为更称手的IDE.md @@ -0,0 +1,93 @@ +# 让VSCode变成你熟悉的形状 + +VSCode的各种配置如快捷键、高亮颜色、主题、界面形状和位置等（也包括各种插件的设置）可以通过在`ctrl+,`打开的设置页面修改，更好的方式是你已经尝试过的——通过xxx.json文件进行配置。VSCode的配置系统同样通过`.json`文件完成，且存在继承和覆盖的关系。VSCode的底层配置`setting.json`是针对整个VSCode进行设置的，而工作区目录下创建的`.vscode/setting.json`则可以覆盖底层配置。了解了基本的配置结构后，这里将介绍一些入手必备的设置和推荐安装的插件。 + +[TOC] + +## 快捷键 + + + + + + + +## 提高效率 + + + + + +## 代码高亮 + + + + + +## 终端工具 + + + + + + + +## 插件 + +> 学习一个插件的使用，最好的方式是阅读插件的wiki和说明文档，而不是在搜索引擎里面搜索！询问ChatGPT或者Copilot Chat也是一个比较好的办法，初级的问题它们几乎不会犯错。 + +- **Better C++ Syntax** + +用于静态解析C++代码，为intellisense以及language server提供代码高亮和完整的智能提示选项。 + +- **Blockman** + +为代码分块。不同的作用域会被浅色背景边框包围，同时高亮当前focus的代码块，方便在大段代码中定位程序控制流。 + +- **Bookmarks** + +为代码添加书签，可以在左侧tab页中跳转到对应位置，方便阅读代码时往复查看，也有助于阅读理解。右键点击代码行号左侧（即打断点的地方）可以添加书签或带label的书签。 + +- **C/C++ Snippets** + +为基本的语句（关键字）提供代码补全，如输入`for`自动生成下面的代码： + +```c +for (size_t i = 0; i < count; i++) +{ + /* code */ +} +``` + +补全之后，按下tab会进入不同的位置，方便进一步修改snippet。你也可以在VSCode中自定义常用的snippet补全。 + +- **Code Issue Manager** + +可以在代码的任意地方插入“便签”和“评注”，支持多人协作。是一个比注释更好的TODO list和注意事项提醒。插入的issue支持markdown格式。 + +- **Doxygen Documention Generator** + +为你的代码生成doxygen文档格式的注释。同时也支持一些基本的注释块生成。输入`/**`再按下回车会根据当前注释的位置自动生成合适的注释块。本框架中的注释均通过该插件生成。 + +- **Github Copilot / Copilot Labs / Copilot Chat** + +体验大模型的威力。尤其是Copilot Chat非常适合为你提供一门语言的入门级咨询。 + +- **Gitlens** + +方便地通过图形化的方式管理你的git仓库。 + +- **HexEditor & Hex Hover Converter** + +以十六进制编辑文件 & 鼠标悬停在任意数值类型上时自动提供2/8/16进制的转换。 + +- **Live Share** + +和你的伙伴一起coding。 + +- **SonarLint** + +VSCode上最强大的静态检查工具，在VSCode自动静态检查的基础上提供更严格的代码建议，尽可能降低出错的可能。其中也包含了不同语言的最佳实践。 + +cmake可以通过添加`DCMAKE_EXPORT_COMPILE_COMMANDS=True` 的指令（直接在cmakelists中通过`set()`设定也可以），makefile则通过Makefile Tools插件设置生成`compile_commands.json`的路径。 +