Skip to content

Commit 52fdde0

Browse files
sogwmssogwms
committed
update doc
1 parent 0e56f41 commit 52fdde0

14 files changed

+571
-197
lines changed

‎README.md‎

Lines changed: 31 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,56 @@
1-
## RT-Robot
1+
# RT-Robot
22

33
## 1、介绍
44

5-
RT-Robot 是 RT-Thread 的机器人框架，希望能够支持智能小车、机械臂、飞控等各种不同类型的机器人。
5+
RT-Robot 是 RT-Thread 的机器人框架，希望能够支持智能小车、机械臂、无人机等各种不同类型的机器人。
66

77
当前以智能车为主要目标，希望支持两轮差分驱动、四轮差分驱动、麦克纳姆轮驱动、经典 Ackerman (两轮差分，一方向连杆) 的小车底盘。
88

9-
### 1.1 目录结构
9+
当前功能特点：
10+
- 支持两轮差分驱动、四轮差分驱动、麦克纳姆轮驱动的小车底盘
1011

11-
`rt-robot` 软件包目录结构如下所示：
12+
- 支持增量、位置式 PID
13+
- 支持单相、AB 相编码器
14+
- 支持双 PWM、单 PWM 的直流电机驱动，支持驱动舵机
15+
- 支持 PS2 遥控器
16+
- 支持 ANO_TC 匿名科创地面站
1217

13-
```
14-
rt-robot
15-
│
16-
├─docs
17-
│ design.md // 模块设计文档
18-
│ api.md // API 说明文档
19-
│ samples.md // 框架应用示例
20-
│
21-
├─controller
22-
│ controller.c // 抽象控制器组件
23-
│ controller.h
24-
│ ps2_controller.c // PS2 手柄模块
25-
│ ps2_controller.h
26-
│
27-
├─robot
28-
│ robot.c // 抽象机器人组件
29-
│ robot.h
30-
│ mobile_robot.c // 小车机器人模块
31-
│ mobile_robot.h
32-
│
33-
├─chassis
34-
│ chassis.c // 小车底盘组件
35-
│ chassis.h
36-
│
37-
├─kinematics
38-
│ kinematics.c // 小车动力学模型组件
39-
│ kinematics.h
40-
│
41-
├─wheel
42-
│ wheel.c // 小车车轮组件
43-
│ wheel.h
44-
│
45-
├─encoder
46-
│ encoder.c // 车轮编码器组件
47-
│ encoder.h
48-
│
49-
├─motor
50-
│ motor.c // 车轮电机组件
51-
│ motor.h
52-
│ dc_motor.c // 直流电机模块
53-
│ dc_motor.h
54-
│
55-
├─pid
56-
│ pid.c // 车轮 PID 组件
57-
│ pid.h
58-
│
59-
├─README.md // 软件包使用说明
60-
│
61-
└─SConscript // RT-Thread 默认的构建脚本
62-
```
18+
### 1.1 许可证
6319

64-
### 1.2 依赖
20+
rt-robot 软件包遵循 Apache-2.0 许可，详见 LICENSE 文件。
6521

22+
### 1.2 依赖
6623
- RT-Thread 3.1.x +
6724

6825
## 2、获取软件包
6926

70-
使用 `rt-robot` 软件包需要在 BSP 目录下使用 menuconfig 命令打开 Env 配置界面，在 `RT-Thread online packages → system packages` 中选择 RT-Robot 软件包，操作界面如下图所示：
27+
使用 `rt-robot` 软件包需要在 BSP 目录下使用 menuconfig 命令打开 Env 配置界面，在 `RT-Thread online packages → system packages` 中选择 RT-Robot 软件包，具体路径如下：
7128

72-
[![选中 RT-Robot 软件包](docs/figures/rt-robot-menuconfig.png)](https://github.com/RT-Thread-packages/paho-mqtt/blob/master/docs/figures/select_mqtt_package.png)
29+
```shell
30+
RT-Thread online packages
31+
system packages --->
32+
[*] RT-Robot: RT-Thread robots development platform --->
33+
Version (latest) --->
34+
```
7335

74-
选择合适的配置项后，使用 `pkgs --update` 命令下载软件包并添加到工程中即可。
36+
配置完成后让 RT-Thread 的包管理器自动更新，或者使用 pkgs --update 命令更新包到 BSP 中。
7537

7638
## 3、使用 rt-robot
7739

78-
- 框架设计说明，请参考 [设计手册](docs/design.md)。
79-
- 完整的 API 文档，请参考 [API 手册](docs/api.md)。
80-
- 详细的示例介绍，请参考 [示例文档](docs/samples.md) 。
40+
- 软件包详细介绍，请参考 [软件包介绍](docs/introduction.md)
8141

82-
## 4、注意事项
42+
- 如何从零开始使用，请参考 [用户指南](docs/user-guide.md)
43+
- 框架设计说明，请参考 [设计手册](docs/design.md)
44+
- 完整的 API 文档，请参考 [API 手册](docs/api.md)
45+
- 详细的示例介绍，请参考 [示例文档](docs/samples.md)
8346

84-
- 当前框架正在逐步实现，各种类型的小车还在一步步测试，欢迎大家提 PR 一起完善
47+
## 4、注意事项
8548

49+
- 当前框架正在逐步完善，欢迎大家来提 PR
8650

8751
## 5、联系方式 & 感谢
8852

89-
- 维护：RT-Thread 开发团队
90-
- 主页：https://github.com/RT-Thread-packages/rt-robot
53+
| 维护 | 主页 | 邮箱 |
54+
| -------- | ---------- | --- |
55+
| Wu Han | http://wuhanstudio.cc | [email protected] |
56+
| sogwms | https://github.com/sogwms | [email protected] |

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,7 @@
1010
| ------------------------------------------------------------ | -------- |
1111
| [design.md](./design.md) | 设计说明 |
1212
| [api.md](./api.md) | API 说明 |
13+
| [introduction.md](./introduction.md) | 详细介绍 |
1314
| [samples.md](./samples.md) | 应用示例 |
15+
| [user-guide.md](./user-guide.md) | 用户指南 |
1416

‎docs/api.md‎

Lines changed: 218 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,6 @@
11
# RT-Robot API 介绍
22

3-
在各个模块硬件测试通过后，会一步步将稳定的 API 添加到这里，现在大家可以参照[例程](./samples.md)里面提供的方法进行初始化和控制。
4-
5-
6-
7-
## 控制器 API (controller)
8-
9-
不同手柄按键指令与机器人运动指令间的转换。
3+
## 协议 API (protocol)
104

115

126

@@ -18,32 +12,241 @@
1812

1913
#### 1 车底盘 API (chassis)
2014

15+
```c
16+
chassis_t chassis_create(wheel_t* c_wheel, kinematics_t c_kinematics);
17+
```
18+
19+
创建车底盘
20+
21+
|**参数** | **描述** |
22+
| :------- | :------------------- |
23+
| c_wheel | 车轮对象数组 |
24+
| c_kinematics | 动力学模型对象 |
25+
| **返回** | **--** |
26+
| | |
27+
28+
```c
29+
rt_err_t chassis_set_velocity(chassis_t chas, struct velocity target_velocity);
30+
```
31+
32+
设置小车底盘速度
33+
34+
|**参数** | **描述** |
35+
| :------- | :------------------- |
36+
| chas | 车底盘对象 |
37+
| target_velocity | 预设速度(x,y,w)。x、y速度单位为m/s，w单位为rad/s|
38+
| **返回** | **--** |
39+
| | |
2140

41+
```c
42+
rt_err_t chassis_set_rpm(chassis_t chas, rt_int16_t target_rpm[]);
43+
```
44+
45+
设置小车底盘车轮速度（单位：转/分）
46+
47+
|**参数** | **描述** |
48+
| :------- | :------------------- |
49+
| chas | 车底盘 |
50+
| target_rpm | 预设速度(转每分) |
51+
| **返回** | **--** |
52+
| | |
2253
2354
##### 1.1 车轮 API (wheel)
2455
25-
闭环车轮的运动。
56+
```c
57+
wheel_t wheel_create(motor_t w_motor, encoder_t w_encoder, controller_t w_controller, float radius, rt_uint16_t gear_ratio);
58+
```
59+
60+
创建车轮
61+
62+
|**参数** | **描述** |
63+
| :------- | :------------------- |
64+
| w_motor | 电机对象 |
65+
| w_encoder | 编码器对象 |
66+
| w_controller | 控制器对象 |
67+
| radius | 车轮直径 |
68+
| gear_ratio | 电机减速比 |
69+
| **返回** | **--** |
70+
| | |
71+
72+
```c
73+
rt_err_t wheel_set_speed(wheel_t whl, double speed);
74+
```
75+
76+
设定车轮速度
77+
78+
|**参数** | **描述** |
79+
| :------- | :------------------- |
80+
| whl | 车轮对象 |
81+
| speed | 速度（单位：m/s） |
82+
| **返回** | **--** |
83+
| | |
84+
85+
```c
86+
rt_err_t wheel_set_rpm(wheel_t whl, rt_int16_t rpm);
87+
```
2688

89+
设定车轮速度
2790

91+
|**参数** | **描述** |
92+
| :------- | :------------------- |
93+
| whl | 车轮对象 |
94+
| rpm | 速度（单位：rpm |
95+
| **返回** | **--** |
96+
| | |
2897

2998
**1.1.1 电机 API (motor)**
3099

31-
电机控制相关。
100+
**直流电机**
32101

33-
**1.1.2 编码器 API (encoder)**
102+
```c
103+
dual_pwm_motor_t dual_pwm_motor_create(char *pwm1, int pwm1_channel, char *pwm2, int pwm2_channel);
104+
```
34105
35-
获取编码器信息。
106+
创建双 PWM 驱动方式电机
107+
108+
|**参数** | **描述** |
109+
| :------- | :------------------- |
110+
| pwm1 | pwm设备名 |
111+
| pwm1_channel | pwm通道 |
112+
| pwm2 | pwm设备名 |
113+
| pwm2_channel | pwm通道 |
114+
| **返回** | **--** |
115+
| | |
116+
117+
```c
118+
single_pwm_motor_t single_pwm_motor_create(char *pwm, int channel, rt_base_t pin1, rt_base_t pin2);
119+
```
120+
121+
创建单 PWM 驱动方式电机
122+
123+
|**参数** | **描述** |
124+
| :------- | :------------------- |
125+
| pwm | pwm设备名 |
126+
| channel | pwm通道 |
127+
| pin1 | 控制引脚1 |
128+
| pin2 | 控制引脚2 |
129+
| **返回** | **--** |
130+
| | |
131+
132+
**舵机**
133+
134+
```c
135+
servo_t servo_create(const char * pwm, int channel, float angle, rt_uint32_t pluse_min, rt_uint32_t pluse_max);
136+
```
137+
138+
创建舵机
36139
37-
**1.1.3 PID API (PID)**
140+
|**参数** | **描述** |
141+
| :------- | :------------------- |
142+
| pwm | pwm 设备名 |
143+
| channel | pwm 通道 |
144+
|angle|角度范围|
145+
| pluse_min | 最小脉宽 （单位：ns）；传入 RT_NULL 则设为默认值 |
146+
| pluse_max | 最大脉宽 （单位：ns）；传入 RT_NULL 则设为默认值|
147+
| **返回** | **--** |
148+
| | |
38149
39-
闭环控制。
150+
```c
151+
rt_err_t servo_set_angle(servo_t servo, float angle);
152+
```
40153

154+
设定舵机转动角度
41155

156+
|**参数** | **描述** |
157+
| :------- | :------------------- |
158+
| servo | pwm 设备名 |
159+
| angle | 转动角度 （从零至最大值，最大值取决于 create 时传入的 angle 参数）|
160+
| **返回** | **--** |
161+
| | |
162+
163+
164+
**1.1.2 编码器 API (encoder)**
165+
166+
获取编码器信息。
167+
168+
```c
169+
ab_phase_encoder_t ab_phase_encoder_create(rt_base_t pin_a, rt_base_t pin_b, rt_uint16_t pulse_revol);
170+
```
171+
172+
创建AB相编码器
173+
174+
|**参数** | **描述** |
175+
| :------- | :------------------- |
176+
| pin_a | A相引脚 |
177+
| pin_b | B相引脚 |
178+
| pulse_revol | 车轮转一圈输出的脉冲数 |
179+
| **返回** | **--** |
180+
| | |
181+
182+
```c
183+
single_phase_encoder_t single_phase_encoder_create(rt_base_t pin, rt_uint16_t pulse_revol);
184+
```
185+
186+
创建单相编码器
187+
188+
|**参数** | **描述** |
189+
| :------- | :------------------- |
190+
| pin | 引脚 |
191+
| pulse_revol | 车轮转一圈输出的脉冲数 |
192+
| **返回** | **--** |
193+
| | |
194+
195+
**1.1.3 控制器 API (controller)**
196+
197+
```c
198+
inc_pid_controller_t inc_pid_controller_create(float kp, float ki, float kd, rt_uint16_t sample_time);
199+
```
200+
201+
创建增量式 PID 控制器
202+
203+
|**参数** | **描述** |
204+
| :------- | :------------------- |
205+
| kp | 参数Kp值 |
206+
| ki | 参数Ki值 |
207+
| kd | 参数Kd值 |
208+
| sample_time | 计算周期 |
209+
| **返回** | **--** |
210+
| | |
211+
212+
```c
213+
pos_pid_controller_t pos_pid_controller_create(float kp, float ki, float kd, rt_uint16_t sample_time);
214+
```
215+
216+
创建位置式 PID 控制器
217+
218+
|**参数** | **描述** |
219+
| :------- | :------------------- |
220+
| kp | 参数Kp值 |
221+
| ki | 参数Ki值 |
222+
| kd | 参数Kd值 |
223+
| sample_time | 计算周期 |
224+
| **返回** | **--** |
225+
| | |
42226

43227
##### 1.2 动力学模型 API (kinematics)
44228

45-
小车速度 (x, y, w) 与各个电机转速 (rpm1, rpm2, rpm3, rpm4) 之间的相互转换。
229+
```c
230+
kinematics_t kinematics_create(enum base k_base, float length_x, float length_y, float wheel_radius);
231+
```
232+
233+
创建动力学模型
234+
235+
|**参数** | **描述** |
236+
| :------- | :------------------- |
237+
| k_base | 类型 |
238+
| length_x | X轴两轮间距 |
239+
| length_y | Y轴两轮间距 |
240+
| wheel_radius | 车轮直径 |
241+
| **返回** | **--** |
242+
| | |
46243
244+
_小车速度 (x, y, w) 与各个电机转速 (rpm1, rpm2, rpm3, rpm4) 之间的相互转换。_
47245
246+
```c
247+
rt_int16_t* kinematics_get_rpm(struct kinematics kin, struct velocity target_vel);
248+
```
48249

49-
#### 2 传感器 API (sensor)
250+
```c
251+
struct velocity kinematics_get_velocity(struct kinematics kin, struct rpm current_rpm);
252+
```

0 commit comments

Comments
 (0)