readme.md · 洲墨/RoboWalker2022_mecanum_infantry

# RoboWalker2022 步兵代码

## 前言

1. 废话就是问题所有可能答案的父集
2. 不要用泛化词作为符号名称（或一部分），但有些词如 handler 已经特化成中断处理函数后缀，所以可以按规定使用
3. 不要使用已经有预约定语义的词，如 pid_t 是 unix 中的 pid type，即进程号类型，易造成困扰
4. 现有的合理命名方案为小驼峰、大驼峰和下划线风格命名
5. 当判断状态时，不要使用裸数字代号，因为该数字不是数学含义，应当使用宏定义或枚举类型定义后再使用常量。
6. 每个函数只做“一件事”，但要清楚采用什么层级的抽象决定了到底做了几件事

## 代码方言解释

| 词语               |                                                              |
| ------------------ | ------------------------------------------------------------ |
| AHRS               | 姿态传感器                                                   |
| SerialPlot         | 统一使用的串口绘图软件相关的命名                             |
| Referee            | 裁判系统                                                     |
| DR16               | 遥控器                                                       |
| chassis            | 底盘，产生车体整体运动的机构                                 |
| pan_tilt           | 云台，控制枪口相对底盘运动的机构                             |
| xx_operation       | xx模块的操作逻辑                                             |
| Remote_Control     | 遥控器操作                                                   |
| Keyboard_Control   | 键盘操作                                                     |
| pitch、yaw、(roll) | 欧拉角：俯仰角、航向角、滚转角，在云台和姿态传感器中描述角度。 |
| manifold           | 妙算，视觉运算平台，用于妙算与开发板通信相关变量和函数的命名。 |
| ...                | ...                                                          |

## 文件架构

### 工程类型

Keil v5 MDK-ARM工程，使用STM32CubeMX生成，使用STM32F427IIH芯片。如需使用vscode开发，请安装vscode插件并配置keil环境，然后你就可以在vscode中使用git版本管理工具进行本项目的开发。

值得注意的时，想要使用vscode中的keil插件开发，你应当在MDK-ARM文件夹下，右键“通过Code打开”，而不是在根目录下。

CubeMX生成的代码，你需要在开发时遵循CubeMX的一切规则。包括但不限于，在CubeMX生成的文件中，你必须在如下两行注释之间写你自己的代码：

```c
/* USER CODE BEGIN ...*/
   
/* USER CODE END ...*/
```

否则，在CubeMX中重新生成工程时，你写的代码将会消失。

### FreeRTOS

在CubeMX配置中采用了FreeRTOS。

FreeRTOS是一个迷你的实时操作系统内核。作为一个轻量级的操作系统，功能包括：任务管理、时间管理、信号量、消息队列、内存管理、记录功能、软件定时器、协程等，可基本满足较小系统的需要。

由于RTOS需占用一定的系统资源(尤其是RAM资源)，只有μC/OS-II、embOS、salvo、FreeRTOS等少数实时操作系统能在小RAM单片机上运行。相对μC/OS-II、embOS等商业操作系统，FreeRTOS操作系统是完全免费的操作系统，具有源码公开、可移植、可裁减、调度策略灵活的特点，可以方便地移植到各种单片机上运行。

FreeRTOS的并行处理实际上是保护现场的分时复用。你可能需要考虑到你写的函数被其他线程打断，或者某一全局变量被其它线程修改所带来的后果。

### SRML

[机器人实验室嵌入式软件中间件层库](./SRML/README.md)

### windows的文件结构

CubeMX工程在根目录下demo.ioc。

Keil工程在MDK-ARM下demo.uvprojx。

串口绘图的配置文件在根目录下"串口配置-xx.ini"。

需要关注的文件夹：SRML和USR

SRML库的文件

USR包含了所有新建的文件，基本与Keil文件结构对应

### Keil的文件结构

**下文讲按照自底向上的顺序介绍**

---

#### 无需修改的文件

##### Application/MDK-ARM

只有一个文件：startup_stm32f427xx.s。这是stm32的启动文件，包括初始化堆栈、初始化PC、LR寄存器等功能。除非你对ARM指令集理解较为深刻并极其确定这个文件出现了问题，否则不要对这个文件进行任何修改。也不要在这个文件目录下添加任何的文件。

##### Drivers/CMSIS

STM32的驱动文件。不要修改。

##### Drivers/STM32F4xx_HAL_Driver

STM32 HAL（Hardware Abstraction Layer）库文件。CubeMX自动生成了这些文件。你写的代码应当符合HAL库的规则，而不是ST官方固件库。不要对这些文件进行任何修改。

##### Middlewares/FreeRTOS

嵌入式实时操作系统存放的文件夹。这里的文件是操作系统运行所必须的一系列文件。这是CubeMX生成的文件。不要修改这些文件。

---

#### 可能稍微修改的文件

##### Application/User

用来进行各种外设初始化配置的文件。

main.c完成了基本的配置，开启freertos，启动一个开始线程，此外没有其他的作用。

stm32f4xx_it.c包含所有的中断函数，如果使用HAL库提供的中断处理无法实现需要的效果，就需要在这里手动添加中断服务函数。

##### Middlewares/Components-外设

包含了SRML库对常用外设的一次封装，包括CAN、FLASH、I2C、SPI、TIMER、UART。

##### Middlewares/Devices/AHRS

姿态传感器计算的库。

##### Middlewares/Devices-器件

包含了SRML库以及新添加的常用器件的封装，都是用c++的class实现封装，各个文件的开头都有该模块的使用方式：

DR16.cpp 遥控器

referee.cpp 裁判系统

Serial_Plot.cpp 串口绘图

Moter.h RM的各种电机

AHRS.cpp 姿态传感器

##### Middlewares/Algotithm-算法

包含了SRML库以及新添加的常用算法的封装，都是用c++的class实现封装，各个文件的开头都有该模块的使用方式：

PID.cpp PID控制算法

filters.cpp 常用滤波器算法

---

#### 需要各车实现的文件

##### Application/Module-模块层

各个模块使用c++的class实现封装，由上层（操作层）调用该类实现控制。

chassis.cpp 底盘控制

pan_tilt.cpp 云台控制

##### Application/Operation-操作层

各个模块的操作逻辑，都包含遥控器操作和键盘操作逻辑，由上层Service_Operation.cpp中的线程调用。

##### Application/Service-线程层

System_Config.cpp 包含System_Resource_Init()和System_Task_Init()，这两个函数在main.c中调用，前者是一些在操作系统启动前的初始化语句，后者是由启动线程调用，来开启别的线程。

Service_Communication.cpp 包含通信相关的初始化，主要是uart的初始化、can初始化、can滤波器设置、can接收回调函数、部分串口的接收回调函数。

Service_Module.cpp 包含各个模块运行的线程。

Task_Module线程初始化了各个模块并每隔1ms运行其计算、控制函数。

Device_Referee_UI线程包含自定义UI的内容。

Recv_Referee线程包含对收到的裁判系统数据的处理，无需修改。

Service_Operation.cpp 包含的Task_Operation线程调用操作层接口，实现操作。

Service_Debug.cpp 可以开线程、用于自行调试。

## 命名约定

### 通用命名规则

#### 总述

函数命名, 变量命名, 文件命名要有描述性; 少用缩写.

#### 说明

尽可能使用描述性的命名, 别心疼空间, 毕竟相比之下让代码易于新读者理解更重要. 不要用只有项目开发者能理解的缩写, 也不要通过砍掉几个字母来缩写单词.

```c
int price_count_reader;    // 无缩写
int num_errors;            // "num" 是一个常见的写法
int num_dns_connections;   // 人人都知道 "DNS" 是什么
```

```c
int n;                     // 毫无意义.
int nerr;                  // 含糊不清的缩写.
int n_comp_conns;          // 含糊不清的缩写.
int wgc_connections;       // 只有贵团队知道是什么意思.
int pc_reader;             // "pc" 有太多可能的解释了.
int cstmr_id;              // 删减了若干字母.
```

注意, 一些特定的广为人知的缩写是允许的, 例如用 `i` 表示迭代变量和用 `T` 表示模板参数.

#### 命名名词举例

**大驼峰**：GetChassisSpeed

**小驼峰**：getChassisSpeed

**大驼峰加下划线**：Get_Chassis_Speed

**小写加下划线**：get_chassis_speed

**大写加下划线**：GET_CHASSIS_SPEED

---

### 文件命名

库文件本身就是小写加下划线，例如

```
system_stm32f4xx.c
```

用户文件大驼峰加下划线，例如

```
Auto_Track.c
Auto_Track.h
```

.h与对应的.c同名

### 结构体、枚举类型命名

大驼峰TypeDef结尾，例如

```c
typedef struct {
//...
}VisionSendTypeDef;
```

### 变量、函数命名

#### 局部

函数内变量、函数参数、只在这个.c内部调用的变量、结构体内变量

只在这个.c内部调用的函数

小写加下划线，命名可以较短，例如

```c
static uint16_t key_last,key_new;
```

```c
void computer_control_logic(float*vx,float*vy,float*omega);
```

#### 全局

需要其他文件调用的全局变量或函数（也就是需要声明在.h中的变量或函数），大驼峰加下划线，命名需要较长，谨慎命名，例如

```c
SpeedTypeDef Chassis_Speed; //底盘坐标系，而非云台坐标系
int16_t Moto_Speed[4];//轮速
SpeedTypeDef Chassis_Speed_Max; //根据功率动态调整的速度上限
```

```c
void Get_Chassis_Speed(void);
```

### 宏定义值命名

大写加下划线，计算式必须打括号，例如

```c
//电机rpm到m/s		轮直径*pi/60/减速比
#define RPM_TO_MS (0.15*3.1415/60/(3591/187))

//omega到m/s				(横轮距+纵轮距)/2
#define OMEGA_TO_MS ((0.47+0.48)/2)

//绝对速度限制，任何情况不能超过
#define VX_MAX	3.5f			//横移速度上限 m/s
#define VY_MAX	3.5f			//前进速度上限 m/s
#define OMEGA_MAX 7.0f 		//旋转速度上限 rad/s

#define ACC_FACTOR (1.0f/100)  // 1/线程频率
#define VXY_UP_ACC 		(3.0f*ACC_FACTOR)			 //按键时的加速度 m/s^2		  与速度同向
```

## 标准缩写中英对照

洲墨/RoboWalker2022_mecanum_infantry

简介

发行版

贡献者

近期动态

洲墨/RoboWalker2022_mecanum_infantry .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

洲墨/RoboWalker2022_mecanum_infantry