mirror of
https://gitee.com/mirrors_PX4/PX4-Autopilot.git
synced 2026-10-03 12:38:54 +08:00
Move PX4 Guide source into /docs (#24490)
* Add vitepress tree * Update existing workflows so they dont trigger on changes in the docs path * Add nojekyll, package.json, LICENCE etc * Add crowdin docs upload/download scripts * Add docs flaw checker workflows * Used docs prefix for docs workflows * Crowdin obvious fixes * ci: docs move to self hosted runner runs on a beefy server for faster builds Signed-off-by: Ramon Roche <mrpollo@gmail.com> * ci: don't run build action for docs or ci changes Signed-off-by: Ramon Roche <mrpollo@gmail.com> * ci: update runners Signed-off-by: Ramon Roche <mrpollo@gmail.com> * Add docs/en * Add docs assets and scripts * Fix up editlinks to point to PX4 sources * Download just the translations that are supported * Add translation sources for zh, uk, ko * Update latest tranlsation and uorb graphs * update vitepress to latest --------- Signed-off-by: Ramon Roche <mrpollo@gmail.com> Co-authored-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Hamish Willee
co-authored by
Ramon Roche
Ramon Roche
parent
8e6d2ebe4a
commit
88d623bedb
@@ -0,0 +1,58 @@
|
||||
# 二进制大小分析
|
||||
|
||||
The `bloaty_compare_master` build target allows you to get a better understanding of the impact of changes on code size.
|
||||
When it is used, the toolchain downloads the latest successful master build of a particular firmware and compares it to the local build (using the [bloaty](https://github.com/google/bloaty) size profiler for binaries).
|
||||
|
||||
:::tip
|
||||
This can help analyse changes that (may) cause `px4_fmu-v2_default` to hit the 1MB flash limit.
|
||||
:::
|
||||
|
||||
_Bloaty_ must be in your path and found at _cmake_ configure time.
|
||||
The PX4 [docker files](https://github.com/PX4/containers/blob/master/docker/Dockerfile_nuttx-bionic) install _bloaty_ as shown:
|
||||
|
||||
```sh
|
||||
git clone --recursive https://github.com/google/bloaty.git /tmp/bloaty \
|
||||
&& cd /tmp/bloaty && cmake -GNinja . && ninja bloaty && cp bloaty /usr/local/bin/ \
|
||||
&& rm -rf /tmp/*
|
||||
```
|
||||
|
||||
The example below shows how you might see the impact of removing the _mpu9250_ driver from `px4_fmu-v2_default`.
|
||||
First it locally sets up a build without the driver:
|
||||
|
||||
```sh
|
||||
% git diff
|
||||
diff --git a/boards/px4/fmu-v2/default.px4board b/boards/px4/fmu-v2/default.px4board
|
||||
index 40d7778..2ce7972 100644
|
||||
--- a/boards/px4/fmu-v2/default.px4board
|
||||
+++ b/boards/px4/fmu-v2/default.px4board
|
||||
@@ -36,7 +36,7 @@
|
||||
- CONFIG_DRIVERS_IMU_INVENSENSE_MPU9250=y
|
||||
+ CONFIG_DRIVERS_IMU_INVENSENSE_MPU9250=n
|
||||
```
|
||||
|
||||
Then use the make target, specifying the target build to compare (`px4_fmu-v2_default` in this case):
|
||||
|
||||
```sh
|
||||
% make px4_fmu-v2_default bloaty_compare_master
|
||||
...
|
||||
...
|
||||
...
|
||||
VM SIZE FILE SIZE
|
||||
-------------- --------------
|
||||
[DEL] -52 MPU9250::check_null_data(unsigned int*, unsigned char) -52 [DEL]
|
||||
[DEL] -52 MPU9250::test_error() -52 [DEL]
|
||||
[DEL] -52 MPU9250_gyro::MPU9250_gyro(MPU9250*, char const*) -52 [DEL]
|
||||
[DEL] -56 mpu9250::info(MPU9250_BUS) -56 [DEL]
|
||||
[DEL] -56 mpu9250::regdump(MPU9250_BUS) -56 [DEL]
|
||||
... -336 [DEL]
|
||||
[DEL] -344 MPU9250_mag::_measure(ak8963_regs) -344 [DEL]
|
||||
[DEL] -684 MPU9250::MPU9250(device::Device*, device::Device*, char const*, char const*, cha -684 [DEL]
|
||||
[DEL] -684 MPU9250::init() -684 [DEL]
|
||||
[DEL] -1000 MPU9250::measure() -1000 [DEL]
|
||||
-41.3% -1011 [43 Others] -1011 -41.3%
|
||||
-1.0% -1.05Ki [Unmapped] +24.2Ki +0.2%
|
||||
-1.0% -10.3Ki TOTAL +14.9Ki +0.1%
|
||||
```
|
||||
|
||||
This shows that removing _mpu9250_ from `px4_fmu-v2_default` would save 10.3 kB of flash.
|
||||
It also shows the sizes of different pieces of the _mpu9250_ driver.
|
||||
@@ -0,0 +1,89 @@
|
||||
# PX4 控制台/Shell
|
||||
|
||||
PX4 enables terminal access to the system through the [MAVLink Shell](../debug/mavlink_shell.md) and the [System Console](../debug/system_console.md).
|
||||
|
||||
这里将说明它们的主要区别，以及如何使用。
|
||||
|
||||
<a id="console_vs_shell"></a>
|
||||
|
||||
## System Console vs. Shells
|
||||
|
||||
The PX4 _System Console_ provides low-level access to the system, debug output and analysis of the system boot process.
|
||||
|
||||
There is just one _System Console_, which runs on one specific UART (the debug port, as configured in NuttX), and is commonly attached to a computer via an FTDI cable (or some other debug adapter like a [Dronecode probe](https://kb.zubax.com/display/MAINKB/Dronecode+Probe+documentation)).
|
||||
|
||||
- Used for _low-level debugging/development_: bootup, NuttX, startup scripts, board bringup, development on central parts of PX4 (e.g. uORB).
|
||||
- 更具体一点，这里是包括自启动的用户应用在内的整个PX4系统下所有启动过程唯一的输出位置。
|
||||
|
||||
Shell 提供对系统的上层访问能力：
|
||||
|
||||
- 用于执行基础的模块调试运行命令。
|
||||
- Only _directly_ display the output of modules you start.
|
||||
- Cannot _directly_ display the output of tasks running on the work queue.
|
||||
- 在 PX4 系统无法启动时无助于调试（它并没有运行）。
|
||||
|
||||
:::info
|
||||
The `dmesg` command is now available through the shell on some boards, enabling much lower level debugging than previously possible.
|
||||
For example, with `dmesg -f &` you also see the output of background tasks.
|
||||
:::
|
||||
|
||||
<a href="../debug/system_console.md">系统控制台（System Console）</a>在调试系统无法启动时十分必要，它会在飞控板上电后输出启动日志。
|
||||
Since MAVLink provides more flexibility, currently only the [MAVLink Shell](../debug/mavlink_shell.md) is used.
|
||||
|
||||
The [System Console](../debug/system_console.md) is essential when the system does not boot (it displays the system boot log when power-cycling the board).
|
||||
The [MAVLink Shell](../debug/mavlink_shell.md) is much easier to setup, and so is more generally recommended for most debugging.
|
||||
|
||||
<a id="using_the_console"></a>
|
||||
|
||||
## 使用控制台/Shell
|
||||
|
||||
The MAVLink shell/console and the [System Console](../debug/system_console.md) are used in much the same way.
|
||||
|
||||
For example, type `ls` to view the local file system, `free` to see the remaining free RAM, `dmesg` to look at boot output.
|
||||
|
||||
```sh
|
||||
nsh> ls
|
||||
nsh> free
|
||||
nsh> dmesg
|
||||
```
|
||||
|
||||
Below are a couple of commands which can be used in the [NuttShell](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139629410) to get insights of the system.
|
||||
|
||||
此 NSH 命令提供剩余的可用内存：
|
||||
|
||||
```sh
|
||||
free
|
||||
```
|
||||
|
||||
top命令显示每个应用成虚使用的堆栈情况：
|
||||
|
||||
```sh
|
||||
top
|
||||
```
|
||||
|
||||
注意堆栈使用量是通过堆栈着色计算的，并且是任务开始以来的最大值（不是当前使用量）。
|
||||
|
||||
要查看工作队列的运行抢空以及运行速度，使用：
|
||||
|
||||
```sh
|
||||
work_queue status
|
||||
```
|
||||
|
||||
调试 uORB 主题：
|
||||
|
||||
```sh
|
||||
uorb top
|
||||
```
|
||||
|
||||
检查特定的 uORB 主题：
|
||||
|
||||
```sh
|
||||
listener <topic_name>
|
||||
```
|
||||
|
||||
Many other system commands and modules are listed in the [Modules and Command Reference](../modules/modules_main.md) (e.g. `top`, `listener`, etc.).
|
||||
|
||||
:::tip
|
||||
Some commands may be disabled on some boards (i.e. the some modules are not included in firmware for boards with RAM or FLASH constraints).
|
||||
In this case you will see the response: `command not found`
|
||||
:::
|
||||
@@ -0,0 +1,110 @@
|
||||
# 发送和接收调试值
|
||||
|
||||
在软件开发过程中，输出单个重要数字通常是必要的。
|
||||
This is where the generic `NAMED_VALUE_FLOAT`, `DEBUG` and `DEBUG_VECT` packets of MAVLink come in.
|
||||
|
||||
## 在 MAVLink 调试消息和 uORB 主题之间进行映射
|
||||
|
||||
MAVLink调试消息转换为/自 uORB 主题。
|
||||
为了发送或接收 MAVLink 调试消息，您必须分别发布或订阅相应的主题。
|
||||
下面是一个表，其中总结了 MAVLink 调试消息和 uORB 主题之间的映射：
|
||||
|
||||
| MAVLink 消息 | uORB topic |
|
||||
| ----------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| NAMED_VALUE_FLOAT | debug_key_value |
|
||||
| DEBUG | debug_value |
|
||||
| DEBUG_VECT | debug_vect |
|
||||
|
||||
## 教程：发送字符串/浮点配对
|
||||
|
||||
This tutorial shows how to send the MAVLink message `NAMED_VALUE_FLOAT` using the associated uORB topic `debug_key_value`.
|
||||
|
||||
本教程的代码可在此处找到：
|
||||
|
||||
- [Debug Tutorial Code](https://github.com/PX4/PX4-Autopilot/blob/main/src/examples/px4_mavlink_debug/px4_mavlink_debug.cpp)
|
||||
- [Enable the tutorial app](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v5/default.px4board) by ensuring the MAVLink debug app (**CONFIG_EXAMPLES_PX4_MAVLINK_DEBUG**) is in the config of your board and set set to 'y'.
|
||||
|
||||
设置调试发布所需的只是此代码段。
|
||||
首先添加头文件：
|
||||
|
||||
```C
|
||||
#include <uORB/uORB.h>
|
||||
#include <uORB/topics/debug_key_value.h>
|
||||
#include <string.h>
|
||||
```
|
||||
|
||||
然后广播调试值主题（一个针对不同发布名称的广播就足够了）。
|
||||
把这个放在你的主循环前面：
|
||||
|
||||
```C
|
||||
/* advertise debug value */
|
||||
struct debug_key_value_s dbg;
|
||||
strncpy(dbg.key, "velx", sizeof(dbg.key));
|
||||
dbg.value = 0.0f;
|
||||
orb_advert_t pub_dbg = orb_advertise(ORB_ID(debug_key_value), &dbg);
|
||||
```
|
||||
|
||||
而发送主循环更简单：
|
||||
|
||||
```C
|
||||
dbg.value = position[0];
|
||||
orb_publish(ORB_ID(debug_key_value), pub_dbg, &dbg);
|
||||
```
|
||||
|
||||
:::warning
|
||||
Multiple debug messages must have enough time between their respective publishings for Mavlink to process them.
|
||||
This means that either the code must wait between publishing multiple debug messages, or alternate the messages on each function call iteration.
|
||||
:::
|
||||
|
||||
The result in QGroundControl then looks like this on the real-time plot:
|
||||
|
||||
|
||||
|
||||
## 教程：发送字符串/浮点配对
|
||||
|
||||
The following code snippets show how to receive the `velx` debug variable that was sent in the previous tutorial.
|
||||
|
||||
First, subscribe to the topic `debug_key_value`:
|
||||
|
||||
```C
|
||||
#include <poll.h>
|
||||
#include <uORB/topics/debug_key_value.h>
|
||||
|
||||
int debug_sub_fd = orb_subscribe(ORB_ID(debug_key_value));
|
||||
[...]
|
||||
```
|
||||
|
||||
当 <code>debug_key_value</code> 主题上有新消息可用时，不要忘记根据其键属性对其进行筛选，以便放弃键与 <code>velx</code> 不同的消息：
|
||||
|
||||
```C
|
||||
[...]
|
||||
/* one could wait for multiple topics with this technique, just using one here */
|
||||
px4_pollfd_struct_t fds[] = {
|
||||
{ .fd = debug_sub_fd, .events = POLLIN },
|
||||
};
|
||||
|
||||
while (true) {
|
||||
/* wait for debug_key_value for 1000 ms (1 second) */
|
||||
int poll_ret = px4_poll(fds, 1, 1000);
|
||||
|
||||
[...]
|
||||
```
|
||||
|
||||
When a new message is available on the `debug_key_value` topic, do not forget to filter it based on its key attribute in order to discard the messages with key different than `velx`:
|
||||
|
||||
```C
|
||||
[...]
|
||||
if (fds[0].revents & POLLIN) {
|
||||
/* obtained data for the first file descriptor */
|
||||
struct debug_key_value_s dbg;
|
||||
|
||||
/* copy data into local buffer */
|
||||
orb_copy(ORB_ID(debug_key_value), debug_sub_fd, &dbg);
|
||||
|
||||
/* filter message based on its key attribute */
|
||||
if (strcmp(_sub_debug_vect.get().key, "velx") == 0) {
|
||||
PX4_INFO("velx:\t%8.4f", dbg.value);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,158 @@
|
||||
# Debugging with Eclipse and J-Link
|
||||
|
||||
This topic explains how to setup and use [MCU Eclipse](https://gnu-mcu-eclipse.github.io/) with a _Segger Jlink adapter_ to debug PX4 running on NuttX (e.g. Pixhawk series boards).
|
||||
|
||||
## Required Hardware
|
||||
|
||||
- [J-Link EDU Mini](https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/)
|
||||
- Adapter to connect Segger JLink to Flight Controller [SWD Debug Port](../debug/swd_debug.md) (debug port).
|
||||
- Micro USB cable
|
||||
|
||||
## 安装
|
||||
|
||||
### ROS
|
||||
|
||||
Setup PX4 by following the normal guidelines:
|
||||
|
||||
- [Setup the PX4 Developer Environment/Toolchain](../dev_setup/dev_env.md) for your platform (e.g. for Linux see: [Development Environment on Ubuntu LTS / Debian Linux](../dev_setup/dev_env_linux_ubuntu.md)).
|
||||
- [Download PX4](../dev_setup/building_px4.md) and optionally build it on the command line.
|
||||
|
||||
### Eclipse
|
||||
|
||||
To install _Eclipse_:
|
||||
|
||||
1. Download [Eclipse CDT for C/C++ Developers](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/) (MCU GitHub).
|
||||
2. Extract the Eclipse folder and copy it anywhere (there is no need to run any install scripts).
|
||||
3. Run _Eclipse_ and choose a location for your initial workbench.
|
||||
|
||||
### Segger Jlink Tools
|
||||
|
||||
To install the _Segger Jlink_ tools:
|
||||
|
||||
1. Download and run the [J-Link Software and Documentation Pack](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) for your OS (Windows and Linux packages available).
|
||||
- On Linux the tools are installed in **/usr/bin**.
|
||||
|
||||
For more information, see: [https://gnu-mcu-eclipse.github.io/debug/jlink/install/](https://gnu-mcu-eclipse.github.io/debug/jlink/install/).
|
||||
|
||||
## First Use
|
||||
|
||||
1. Connect the _Segger JLink_ to the host computer and the [flight controller debug port](../debug/swd_debug.md) (via an adapter).
|
||||
|
||||
2. Power the flight controller.
|
||||
|
||||
3. Run _Eclipse_.
|
||||
|
||||
4. Add a source by choosing **File > Import > C/C++ > Existing Code as Makefile Project** and click **Next**.
|
||||
|
||||
5. Point it to the **PX4-Autopilot** folder and give it a name, then select _ARM Cross GCC_ in the _Toolchain for Indexer Settings_ and click **Finish**.
|
||||
Import takes a while, wait for it to complete.
|
||||
|
||||
6. Set the MCU settings: right-click on the top-level project in the Project Explorer, select _Properties_ then under MCU choose _SEGGER J-Link Path_.
|
||||
Set it as shown in the screenshot below.
|
||||
|
||||
|
||||
7. Update packs:
|
||||
|
||||
- Click the small icon on the top right called _Open Perspective_ and open the _Packs_ perspective.
|
||||
|
||||
|
||||
- Click the **update all** button.
|
||||
|
||||
:::tip
|
||||
This takes a VERY LONG TIME (10 minutes).
|
||||
Ignore all the errors about missing packages that pop up.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
- The STM32Fxx devices are found in the Keil folder, install by right-clicking and then selecting **install** on the according device for F4 and F7.
|
||||
|
||||
8. Setup debug configuration for target:
|
||||
|
||||
- Right click project and open the _Settings_ (menu: **C/C++ Build > Settings**)
|
||||
- Choose the _Devices_ Tab, _Devices_ section (Not _Boards_).
|
||||
- Find the FMU chip you wish to debug.
|
||||
|
||||
|
||||
|
||||
9. Select debug configurations with the small drop-down next to the bug symbol:
|
||||
|
||||
|
||||
10. Then select _GDB SEGGER J-Link Debugging_ and then the **New config** button on the top left.
|
||||
|
||||
|
||||
11. Setup build config:
|
||||
|
||||
- Give it a name and set the _C/C++ Application_ to the corresponding **.elf** file.
|
||||
- Choose _Disable Auto build_
|
||||
|
||||
::: info
|
||||
Remember that you must build the target from the command line before starting a debug session.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
12. The _Debugger_ and _Startup_ tabs shouldn’t need any modifications (just verify your settings with the screenshots below)
|
||||
|
||||
|
||||
|
||||
|
||||
## SEGGER Task-aware debugging
|
||||
|
||||
Task-aware debugging (also known as [thread-aware debugging](https://www.segger.com/products/debug-probes/j-link/tools/j-link-gdb-server/thread-aware-debugging/)) allows you to show the context of all running threads/tasks instead of just the stack current task.
|
||||
This is quite useful since PX4 tends to run many different tasks.
|
||||
|
||||
To enable this feature for use in Eclipse:
|
||||
|
||||
1. You first need to enable `CONFIG_DEBUG_TCBINFO` in the NuttX configuration for your build (to expose the TCB offsets).
|
||||
|
||||
- Open a terminal in the root of your PX4-Autopilot source code
|
||||
|
||||
- In the terminal, open `menuconfig` using the appropriate make target for the build.
|
||||
This will be something like:
|
||||
|
||||
```sh
|
||||
make px4_fmu-v5_default boardguiconfig
|
||||
```
|
||||
|
||||
(See [PX4 Menuconfig Setup](../hardware/porting_guide_config.md#px4-menuconfig-setup) for more information) on using the config tools).
|
||||
|
||||
- Ensure that the _Enable TCBinfo struct for debug_ is selected as shown:
|
||||
|
||||
|
||||
2. Compile the **jlink-nuttx.so** library in the terminal by running the following command in the terminal: `make jlink-nuttx`
|
||||
|
||||
3. Modify Eclipse to use this libary.
|
||||
In the _J-Link GDB Server Setup_ configuration, update **Other options** to include `-rtos /home/<PX4 path>/Tools/jlink-nuttx.so`, as shown in the image below.
|
||||
|
||||
|
||||
|
||||
4. When running the debugger you should see now multiple threads instead of just one:
|
||||
|
||||
|
||||
|
||||
## 故障处理
|
||||
|
||||
### Target CPU not in Package Manager
|
||||
|
||||
If the target CPU does not appear in the package manager you may need these steps to get the register view working.
|
||||
|
||||
:::tip
|
||||
This should not generally happen (but anecdotally has been reported when connecting to an STM F7 controller).
|
||||
:::
|
||||
|
||||
Adding missing SVD files for the _Peripheral View_:
|
||||
|
||||
1. Find out where MCU Eclipse stores its packages (**Preferences > C/C++ > MCU Packages**):
|
||||
|
||||
|
||||
|
||||
2. Download missing packages from: http://www.keil.com/dd2/Pack/
|
||||
|
||||
3. Open downloaded pack with a decompression tool, and extract the **.SVD** files from: **/CMSIS/SVD**.
|
||||
|
||||
4. Select desired **.SVD** file in: **Debug Options > GDB SEGGER JLink Debugging > SVD Path**
|
||||
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# System Failure Injection
|
||||
|
||||
System failure injection allows you to induce different types of sensor and system failures, either programmatically using the [MAVSDK failure plugin](https://mavsdk.mavlink.io/main/en/cpp/api_reference/classmavsdk_1_1_failure.html), or "manually" via a PX4 console like the [MAVLink shell](../debug/mavlink_shell.md#mavlink-shell).
|
||||
This enables easier testing of [safety failsafe](../config/safety.md) behaviour, and more generally, of how PX4 behaves when systems and sensors stop working correctly.
|
||||
|
||||
Failure injection is disabled by default, and can be enabled using the [SYS_FAILURE_EN](../advanced_config/parameter_reference.md#SYS_FAILURE_EN) parameter.
|
||||
|
||||
:::warning
|
||||
Failure injection still in development.
|
||||
At time of writing (PX4 v1.14):
|
||||
|
||||
- It can only be used in simulation (support for both failure injection in real flight is planned).
|
||||
- It requires support in the simulator.
|
||||
It is supported in Gazebo Classic
|
||||
- Many failure types are not broadly implemented.
|
||||
In those cases the command will return with an "unsupported" message.
|
||||
|
||||
:::
|
||||
|
||||
## Failure System Command
|
||||
|
||||
Failures can be injected using the [failure system command](../modules/modules_command.md#failure) from any PX4 console/shell, specifying both the target and type of the failure.
|
||||
|
||||
### Syntax
|
||||
|
||||
The full syntax of the [failure](../modules/modules_command.md#failure) command is:
|
||||
|
||||
```sh
|
||||
failure <component> <failure_type> [-i <instance_number>]
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
- _component_:
|
||||
- 传感器：
|
||||
- `gyro`: Gyro.
|
||||
- `accel`: Accelerometer.
|
||||
- `mag`: Magnetometer
|
||||
- `baro`: Barometer
|
||||
- `gps`: GPS
|
||||
- `optical_flow`: Optical flow.
|
||||
- `vio`: Visual inertial odometry.
|
||||
- `distance_sensor`: Distance sensor (rangefinder).
|
||||
- `airspeed`: Airspeed sensor.
|
||||
- Systems:
|
||||
- `battery`: Battery.
|
||||
- `motor`: Motor.
|
||||
- `servo`: Servo.
|
||||
- `avoidance`: Avoidance.
|
||||
- `rc_signal`: RC Signal.
|
||||
- `mavlink_signal`: MAVLink signal (data telemetry).
|
||||
- _failure_type_:
|
||||
- `ok`: Publish as normal (Disable failure injection).
|
||||
- `off`: Stop publishing.
|
||||
- `stuck`: Report same value every time (_could_ indicate a malfunctioning sensor).
|
||||
- `garbage`: Publish random noise. This looks like reading uninitialized memory.
|
||||
- `wrong`: Publish invalid values (that still look reasonable/aren't "garbage").
|
||||
- `slow`: Publish at a reduced rate.
|
||||
- `delayed`: Publish valid data with a significant delay.
|
||||
- `intermittent`: Publish intermittently.
|
||||
- _instance number_ (optional): Instance number of affected sensor.
|
||||
0 (default) indicates all sensors of specified type.
|
||||
|
||||
### Example
|
||||
|
||||
To simulate losing RC signal without having to turn off your RC controller:
|
||||
|
||||
1. Enable the parameter [SYS_FAILURE_EN](../advanced_config/parameter_reference.md#SYS_FAILURE_EN).
|
||||
2. Enter the following commands on the MAVLink console or SITL _pxh shell_:
|
||||
|
||||
```sh
|
||||
# Fail RC (turn publishing off)
|
||||
failure rc_signal off
|
||||
|
||||
# Restart RC publishing
|
||||
failure rc_signal ok
|
||||
```
|
||||
|
||||
## MAVSDK Failure Plugin
|
||||
|
||||
The [MAVSDK failure plugin](https://mavsdk.mavlink.io/main/en/cpp/api_reference/classmavsdk_1_1_failure.html) can be used to programmatically inject failures.
|
||||
It is used in [PX4 Integration Testing](../test_and_ci/integration_testing_mavsdk.md) to simulate failure cases (for example, see [PX4-Autopilot/test/mavsdk_tests/autopilot_tester.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/test/mavsdk_tests/autopilot_tester.cpp)).
|
||||
|
||||
The plugin API is a direct mapping of the failure command shown above, with a few additional error signals related to the connection.
|
||||
@@ -0,0 +1,39 @@
|
||||
# 常见问题
|
||||
|
||||
## 编译错误
|
||||
|
||||
### 闪存溢出
|
||||
|
||||
可以加载到主板上的代码量受到其具有的闪存量的限制。
|
||||
当添加其他模块或代码时，添加可能会超过闪存。
|
||||
这将导致 "闪存溢出"。 The upstream version will always build, but depending on what a developer adds it might overflow locally.
|
||||
|
||||
```sh
|
||||
region `flash' overflowed by 12456 bytes
|
||||
```
|
||||
|
||||
若要解决此问题，请使用较新的硬件或从生成中删除对您的用例不重要的模块。
|
||||
The configuration is stored in **/PX4-Autopilot/boards/px4** (e.g. [PX4-Autopilot/boards/px4/fmu-v5/default.px4board](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v5/default.px4board)).
|
||||
要删除模块，只需将其注释掉：
|
||||
|
||||
```cmake
|
||||
#drivers/trone
|
||||
```
|
||||
|
||||
#### Identifying large memory consumers
|
||||
|
||||
The command below will list the largest static allocations:
|
||||
|
||||
```sh
|
||||
sudo apt-get remove modemmanager
|
||||
```
|
||||
|
||||
## USB 错误
|
||||
|
||||
### 上传从不成功
|
||||
|
||||
On Ubuntu, uninstall the modem manager:
|
||||
|
||||
```sh
|
||||
sudo apt-get remove modemmanager
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
# Debugging with GDB
|
||||
|
||||
The [GNU DeBugger (GDB)](https://sourceware.org/gdb/documentation/) comes installed with the compiler toolchain in the form of the `arm-none-eabi-gdb` binary.
|
||||
调试器读取ELF文件内的调试富豪，以了解PX4固件的静态和动态内存布局。
|
||||
To access the PX4 autopilot microcontroller, it needs to connect to a [Remote Target](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Connecting.html), which is provided by a [SWD debug probe](swd_debug.md).
|
||||
|
||||
信息流看起来像这样：
|
||||
|
||||
```sh
|
||||
Developer <=> GDB <=> GDB Server <=> Debug Probe <=> SWD <=> PX4 Autopilot.
|
||||
```
|
||||
|
||||
## 快速入门
|
||||
|
||||
要启动调试会话，您通常需要：
|
||||
|
||||
1. Need a specialized [SWD debug probe](../debug/swd_debug.md#debug-probes).
|
||||
2. Find and connect to the [SWD debug port](../debug/swd_debug.md#autopilot-debug-ports).
|
||||
You may need a [debug adapter](swd_debug.md#debug-adapters).
|
||||
3. 配置并启动调试探测来创建 GDB 服务。
|
||||
4. 启动GDB并作为远程目标连接到 GDB 服务。
|
||||
5. 以交互方式调试您的固件。
|
||||
|
||||
See the debug probe documentation for details on how to setup your debug connection:
|
||||
|
||||
- [SEGGER J-Link](probe_jlink.md): commercial probe, no built-in serial console, requires adapter.
|
||||
- [Black Magic Probe](probe_bmp.md): integrated GDB server and serial console, requires adapter.
|
||||
- [STLink](probe_stlink): best value, integrated serial console, adapter must be soldered.
|
||||
|
||||
We recommend using the J-Link with the Pixhawk Debug Adapter or the STLinkv3-MINIE with a soldered custom cable.
|
||||
|
||||
Once connected, you can use the usual GDB commands such as:
|
||||
|
||||
- `continue` to continue program execution
|
||||
- `run` to start from the beginning
|
||||
- `backtrace` to see the backtrace
|
||||
- `break somewhere.cpp:123` to set a breakpoint
|
||||
- `delete somewhere.cpp:123` to remove it again
|
||||
- `info locals` to print local variables
|
||||
- `info registers` to print the registers
|
||||
|
||||
Consult the [GDB documentation](https://sourceware.org/gdb/documentation/) for more details.
|
||||
|
||||
:::tip
|
||||
To avoid having to type all commands to connect in GDB each time, you can write them into `~/.gdbinit`.
|
||||
:::
|
||||
|
||||
## Gazebo dependencies
|
||||
|
||||
You've now connected the flight controller to an SWD debug probe!
|
||||
|
||||
The following topics explain how to start on-target debugging:
|
||||
|
||||
- [MCU Eclipse/J-Link Debugging for PX4](eclipse_jlink.md).
|
||||
- [Visual Studio Code IDE (VSCode)](../dev_setup/vscode.md).
|
||||
|
||||
## Embedded Debug Tools
|
||||
|
||||
The [Embedded Debug Tools](https://pypi.org/project/emdbg/) connect several software and hardware debugging tools together in a user friendly Python package to more easily enable advanced use cases for ARM Cortex-M microcontrollers and related devices.
|
||||
|
||||
The library orchestrates the launch and configuration of hardware debug and trace probes, debuggers, logic analyzers, and waveform generators and provides analysis tools, converters, and plugins to provide significant insight into the software and hardware state during or after execution.
|
||||
|
||||
The `emdbg` library contains [many useful GDB plugins](https://github.com/Auterion/embedded-debug-tools/blob/main/src/emdbg/debug/gdb.md#user-commands) that make debugging PX4 easier.
|
||||
It also provides tools for [profiling PX4 in real-time](https://github.com/Auterion/embedded-debug-tools/tree/main/ext/orbetto).
|
||||
@@ -0,0 +1,89 @@
|
||||
# Hard Fault Debugging
|
||||
|
||||
A hard fault is a state when a CPU executes an invalid instruction or accesses an invalid memory address.
|
||||
This might occur when key areas in RAM have been corrupted.
|
||||
|
||||
## 视频
|
||||
|
||||
The following video demonstrates hardfault debugging on PX4 using Eclipse and a JTAG debugger.
|
||||
It was presented at the PX4 Developer Conference 2019.
|
||||
|
||||
<lite-youtube videoid="KZkAM_PVOi0" title="Hardfault debugging on PX4"/>
|
||||
|
||||
## Debugging Hard Faults in NuttX
|
||||
|
||||
A typical scenario that can cause a hard fault is when the processor overwrites the stack and then the processor returns to an invalid address from the stack.
|
||||
This may be caused by a bug in code were a wild pointer corrupts the stack, or another task overwrites this task's stack.
|
||||
|
||||
- NuttX maintains two stacks: The IRQ stack for interrupt processing and the user stack
|
||||
- The stack grows downward.
|
||||
So the highest address in the example below is 0x20021060, the size is 0x11f4 (4596 bytes) and consequently the lowest address is 0x2001fe6c.
|
||||
|
||||
```sh
|
||||
Assertion failed at file:armv7-m/up_hardfault.c line: 184 task: ekf_att_pos_estimator
|
||||
sp: 20003f90
|
||||
IRQ stack:
|
||||
base: 20003fdc
|
||||
size: 000002e8
|
||||
20003f80: 080d27c6 20003f90 20021060 0809b8d5 080d288c 000000b8 08097155 00000010
|
||||
20003fa0: 20003ce0 00000003 00000000 0809bb61 0809bb4d 080a6857 e000ed24 080a3879
|
||||
20003fc0: 00000000 2001f578 080ca038 000182b8 20017cc0 0809bad1 20020c14 00000000
|
||||
sp: 20020ce8
|
||||
User stack:
|
||||
base: 20021060
|
||||
size: 000011f4
|
||||
20020ce0: 60000010 2001f578 2001f578 080ca038 000182b8 0808439f 2001fb88 20020d4c
|
||||
20020d00: 20020d44 080a1073 666b655b 65686320 205d6b63 6f6c6576 79746963 76696420
|
||||
20020d20: 65747265 63202c64 6b636568 63636120 63206c65 69666e6f 08020067 0805c4eb
|
||||
20020d40: 080ca9d4 0805c21b 080ca1cc 080ca9d4 385833fb 38217db9 00000000 080ca964
|
||||
20020d60: 080ca980 080ca9a0 080ca9bc 080ca9d4 080ca9fc 080caa14 20022824 00000002
|
||||
20020d80: 2002218c 0806a30f 08069ab2 81000000 3f7fffec 00000000 3b4ae00c 3b12eaa6
|
||||
20020da0: 00000000 00000000 080ca010 4281fb70 20020f78 20017cc0 20020f98 20017cdc
|
||||
20020dc0: 2001ee0c 0808d7ff 080ca010 00000000 3f800000 00000000 080ca020 3aa35c4e
|
||||
20020de0: 3834d331 00000000 01010101 00000000 01010001 000d4f89 000d4f89 000f9fda
|
||||
20020e00: 3f7d8df4 3bac67ea 3ca594e6 be0b9299 40b643aa 41ebe4ed bcc04e1b 43e89c96
|
||||
20020e20: 448f3bc9 c3c50317 b4c8d827 362d3366 b49d74cf ba966159 00000000 00000000
|
||||
20020e40: 3eb4da7b 3b96b9b7 3eead66a 00000000 00000000 00000000 00000000 00000000
|
||||
20020e60: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
|
||||
20020e80: 00000016 00000000 00000000 00010000 00000000 3c23d70a 00000000 00000000
|
||||
20020ea0: 00000000 20020f78 00000000 2001ed20 20020fa4 2001f498 2001f1a8 2001f500
|
||||
20020ec0: 2001f520 00000003 2001f170 ffffffe9 3b831ad2 3c23d70a 00000000 00000000
|
||||
20020ee0: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
|
||||
20020f00: 00000000 00000000 00000000 00000000 2001f4f0 2001f4a0 3d093964 00000001
|
||||
20020f20: 00000000 0808ae91 20012d10 2001da40 0000260b 2001f577 2001da40 0000260b
|
||||
20020f40: 2001f1a8 08087fd7 08087f9d 080cf448 0000260b 080afab1 080afa9d 00000003
|
||||
20020f60: 2001f577 0809c577 2001ed20 2001f4d8 2001f498 0805e077 2001f568 20024540
|
||||
20020f80: 00000000 00000000 00000000 0000260b 3d093a57 00000000 2001f540 2001f4f0
|
||||
20020fa0: 0000260b 3ea5b000 3ddbf5fa 00000000 3c23d70a 00000000 00000000 000f423f
|
||||
20020fc0: 00000000 000182b8 20017cc0 2001ed20 2001f4e8 00000000 2001f120 0805ea0d
|
||||
20020fe0: 2001f090 2001f120 2001eda8 ffffffff 000182b8 00000000 00000000 00000000
|
||||
20021000: 00000000 00000000 00000009 00000000 08090001 2001f93c 0000000c 00000000
|
||||
20021020: 00000101 2001f96c 00000000 00000000 00000000 00000000 00000000 00000000
|
||||
20021040: 00000000 00000000 00000000 00000000 00000000 0809866d 00000000 00000000
|
||||
R0: 20000f48 0a91ae0c 20020d00 20020d00 2001f578 080ca038 000182b8 20017cc0
|
||||
R8: 2001ed20 2001f4e8 2001ed20 00000005 20020d20 20020ce8 0808439f 08087c4e
|
||||
xPSR: 61000000 BASEPRI: 00000000 CONTROL: 00000000
|
||||
EXC_RETURN: ffffffe9
|
||||
```
|
||||
|
||||
To decode the hard fault, load the _exact_ binary into the debugger:
|
||||
|
||||
```sh
|
||||
arm-none-eabi-gdb build/px4_fmu-v2_default/px4_fmu-v2_default.elf
|
||||
```
|
||||
|
||||
Then in the GDB prompt, start with the last instructions in R8, with the first address in flash (recognizable because it starts with `0x080`, the first is `0x0808439f`).
|
||||
The execution is left to right. So one of the last steps before the hard fault was when `mavlink_log.c` tried to publish something,
|
||||
|
||||
```sh
|
||||
(gdb) info line *0x0808439f
|
||||
Line 77 of "../src/modules/systemlib/mavlink_log.c" starts at address 0x8084398 <mavlink_vasprintf+36>
|
||||
and ends at 0x80843a0 <mavlink_vasprintf+44>.
|
||||
```
|
||||
|
||||
```sh
|
||||
(gdb) info line *0x08087c4e
|
||||
Line 311 of "../src/modules/uORB/uORBDevices_nuttx.cpp"
|
||||
starts at address 0x8087c4e <uORB::DeviceNode::publish(orb_metadata const*, void*, void const*)+2>
|
||||
and ends at 0x8087c52 <uORB::DeviceNode::publish(orb_metadata const*, void*, void const*)+6>.
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
# 调试主题
|
||||
@@ -0,0 +1,49 @@
|
||||
# MAVLink 控制台
|
||||
|
||||
The MAVLink Shell is an _NSH console_ that can be accessed via MAVLink over serial (USB/Telemetry) or WiFi (UDP/TCP) links (in particular, on NuttX-based systems like: Pixhawk, Pixracer, etc.).
|
||||
|
||||
它可用于启动系统指令与模块，并得到输出信息。
|
||||
While the shell cannot _directly_ display the output of modules that it does not start, it can do so indirectly using the `dmesg` command (`dmesg -f &` can be used to display the output of other modules and tasks running on the work queue).
|
||||
|
||||
:::tip
|
||||
The [QGroundControl MAVLink Console](#qgroundcontrol) is the easiest way to access the console.
|
||||
If the system does not start properly you should instead use the [System Console](../debug/system_console.md).
|
||||
:::
|
||||
|
||||
## 启用 Shell
|
||||
|
||||
<a id="qgroundcontrol"></a>
|
||||
|
||||
### QGroundControl MAVLink Console
|
||||
|
||||
The easiest way to access shell is to use the [QGroundControl MAVLink Console](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/analyze_view/mavlink_console.html) (see **Analyze View > Mavlink Console**).
|
||||
|
||||
### mavlink_shell.py
|
||||
|
||||
You can also access the shell in a terminal using the **mavlink_shell.py** script:
|
||||
|
||||
1. Shut down _QGroundControl_.
|
||||
|
||||
2. 安装依赖项
|
||||
|
||||
```sh
|
||||
pip3 install --user pymavlink pyserial
|
||||
```
|
||||
|
||||
3. Open terminal (in PX4-Autopilot directory) and start the shell:
|
||||
|
||||
```sh
|
||||
# For serial port
|
||||
./Tools/mavlink_shell.py /dev/ttyACM0
|
||||
```
|
||||
|
||||
```sh
|
||||
# For Wifi connection
|
||||
./Tools/mavlink_shell.py 0.0.0.0:14550
|
||||
```
|
||||
|
||||
Use `mavlink_shell.py -h` to get a description of all available arguments.
|
||||
|
||||
## 使用 MAVLink Shell
|
||||
|
||||
For information see: [PX4 Consoles/Shells > Using Consoles/Shells](../debug/consoles.md#using_the_console).
|
||||
@@ -0,0 +1,129 @@
|
||||
# Plotting uORB Topic Data in Real Time using PlotJuggler
|
||||
|
||||
This topic shows how you can graph the "live" values of [uORB topics](../msg_docs/index.md) (in real time) using [PlotJuggler](../log/flight_log_analysis.md#plotjuggler) and the _uXRCE-DDS Agent_.
|
||||
|
||||
This technique uses PX4 [uXRCE-DDS](../middleware/uxrce_dds.md) middleware to export uORB topics as ROS2 topics, which can then be read and plotted by PlotJuggler as they change (PlotJuggler cannot directly read uORB topics, but the values of the corresponding ROS 2 topics are the same).
|
||||
|
||||
The video below demonstrates this for a simulated vehicle — the approach works equally well on real hardware.
|
||||
|
||||
<video src="../../assets/debug/realtime_debugging/realtime_debugging.mp4" width="720" controls></video>
|
||||
|
||||
## 系统必备组件
|
||||
|
||||
Follow the [ROS 2 Installation & Setup](../ros2/user_guide.md#installation-setup) instructions in the _ROS2 user guide_ to install:
|
||||
|
||||
- ROS 2
|
||||
- [Micro XRCE-DDS Agent](../ros2/user_guide.md#setup-micro-xrce-dds-agent-client)
|
||||
- [PX4/px4_msgs](https://github.com/PX4/px4_msgs): PX4/ROS2 shared message definitions.
|
||||
- PX4 source code and build the simulator.
|
||||
|
||||
::: tip
|
||||
If you're using real hardware instead of the simulator, you will only need PX4 source code if you need to change the set of topics that are published to ROS 2 (only a subset of uORB topics are published by default).
|
||||
|
||||
:::
|
||||
|
||||
You will also need to install:
|
||||
|
||||
- [PlotJuggler for ROS2](https://github.com/facontidavide/PlotJuggler)
|
||||
|
||||
::: tip
|
||||
Use the Debian packages (the snap files are not supported).
|
||||
|
||||
:::
|
||||
|
||||
## 用法
|
||||
|
||||
First we need to build a ROS 2 workspace that includes the `px4_msgs` that correspond to the PX4 build to be monitored, and then launch PlotJuggler from within that workspace.
|
||||
This allows ROS 2 and PlotJuggler to interpret the messages.
|
||||
If you're using unmodified PX4, the definitions from [PX4/px4_msgs](https://github.com/PX4/px4_msgs) can be used.
|
||||
|
||||
:::info
|
||||
This is the same process as covered in [Build ROS 2 Workspace](../ros2/user_guide.md#build-ros-2-workspace) in _ROS 2 Installation & Setup_.
|
||||
:::
|
||||
|
||||
Assuming your ROS 2 workspace is named `~/ros2_ws/`, fetch and build the `px4_msgs` package in a terminal as shown:
|
||||
|
||||
```sh
|
||||
cd ~/ros2_ws/src/
|
||||
git clone https://github.com/PX4/px4_msgs.git
|
||||
cd ..
|
||||
colcon build
|
||||
source install/setup.bash
|
||||
```
|
||||
|
||||
Then run PlotJuggler by entering the following commands in a terminal:
|
||||
|
||||
```sh
|
||||
ros2 run plotjuggler plotjuggler
|
||||
```
|
||||
|
||||
To start sending ROS 2 topics from PX4, the uXRCE-DDS **client** has to be running on PX4, and the `MicroXRCEAgent` has to be running on the same computer as PlotJuggler.
|
||||
|
||||
### PX4 Simulator
|
||||
|
||||
Next we'll start the [Gazebo](../sim_gazebo_gz/index.md) simulator for a quadcopter.
|
||||
Because we're using a PX4 simulator the client is started automatically, but we will still need to start the agent and connect to the client.
|
||||
|
||||
First open another terminal.
|
||||
Then navigate to the root of the PX4 source code and start the simulator using the following commands:
|
||||
|
||||
```sh
|
||||
cd ~/PX4-Autopilot
|
||||
make px4_sitl gz_x500
|
||||
```
|
||||
|
||||
Open another terminal and start the `MicroXRCEAgent` to connect to the the simulator:
|
||||
|
||||
```sh
|
||||
MicroXRCEAgent udp4 -p 8888; exec bash
|
||||
```
|
||||
|
||||
That's all that should be needed for connecting to the simulator.
|
||||
|
||||
### PX4 on Hardware
|
||||
|
||||
If you're working with real hardware you'll need to explicitly start the client on PX4 and your agent connection command will be slightly different.
|
||||
[Using flight controller hardware](../ros2/user_guide.md#using-flight-controller-hardware) in the _ROS 2 User Guide_ provides links to setup information.
|
||||
|
||||
## Unavailable/New Messages
|
||||
|
||||
All PX4 message definitions from `main` are exported to the [PX4/px4_msgs](https://github.com/PX4/px4_msgs) repository.
|
||||
These must be imported into your ROS 2 workspace, allowing PlotJuggler to interpret messages from PX4.
|
||||
|
||||
:::info
|
||||
Exporting the messages allows ROS 2 and the uXRCE-DDS agent to be independent of PX4, which is why you only need the PX4 source code if you need to build the simulator or modify the messages.
|
||||
:::
|
||||
|
||||
While `px4_msgs` has messages for all uORB topics in PX4, not all messages in `px4_msgs` are available to ROS 2/PlotJuggler by default.
|
||||
The set that are available must be built into the client running on PX4.
|
||||
These are defined in [dds_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/uxrce_dds_client/dds_topics.yaml).
|
||||
|
||||
The instructions below explain the changes needed to monitor topics that are not available by default.
|
||||
|
||||
### Missing Topics
|
||||
|
||||
If a normal uORB topic is not available in PlotJuggler you will need to modify the [dds_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/uxrce_dds_client/dds_topics.yaml) to include the topic and rebuild PX4.
|
||||
|
||||
If working with real hardware you will need to build and [install](../config/firmware.md#installing-px4-main-beta-or-custom-firmware) custom firmware after changing the YAML file.
|
||||
|
||||
### Modified Messages
|
||||
|
||||
If you have modified any uORB messages you must update the ROS2 messages used by PlotJuggler.
|
||||
|
||||
You will need to rebuild PX4 with your new messages, and replace the `px4_msgs` (from the repository) in your workspace with the new ones.
|
||||
|
||||
Assuming that you have already built PX4 in the directory `~/PX4-Autopilot/`, and that `~/ros2_ws` is your ROS2 workspace, enter the following commands to copy the messages across and rebuild your workspace:
|
||||
|
||||
```sh
|
||||
rm -f ~/ros2_ws/src/px4_msgs/msg/*.msg
|
||||
cp ~/PX4-Autopilot/msg/*.msg ~/ros2_ws/src/px4_msgs/msg/
|
||||
cd ~/ros2_ws/ && colcon build
|
||||
```
|
||||
|
||||
### Custom Topics
|
||||
|
||||
After defining the topic, follow the instructions above to add the topic to [dds_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/uxrce_dds_client/dds_topics.yaml), and export the new message into your ROS 2 workspace.
|
||||
|
||||
## See also
|
||||
|
||||
[ROS 2 User Guide](../ros2/user_guide.md)
|
||||
@@ -0,0 +1,62 @@
|
||||
# Black Magic Probe (and Dronecode Probe)
|
||||
|
||||
The [Black Magic Probe](https://black-magic.org) is an easy to use, mostly plug-and-play, JTAG/SWD debugger for embedded microcontrollers.
|
||||
Since the Black Magic Probe is a generic debug probe, you will need an adapter to connect to Pixhawk flight controllers, which can be purchased here:
|
||||
|
||||
- [Drone Code Debug Adapter](https://1bitsquared.com/products/drone-code-debug-adapter) (1 BIT SQUARED).
|
||||
|
||||
## Dronecode Probe
|
||||
|
||||
The [Dronecode Probe](https://kb.zubax.com/display/MAINKB/Dronecode+Probe+documentation) is a specialization of the Black Magic Probe for debugging PX4 autopilots.
|
||||
|
||||
The probe's USB interface exposes two separate virtual serial port interfaces: one for connecting to the [System Console](system_console.md) (UART) and the other for an embedded GDB server (SWD interface).
|
||||
|
||||
The probe provides a DCD-M connector cable for attaching to the [Pixhawk Debug Mini](swd_debug.md#pixhawk-debug-mini).
|
||||
|
||||
:::info
|
||||
The _6-pos DF13_ connector that comes with the probe cannot be used for SWD debugging (it is for using the System Console).
|
||||
:::
|
||||
|
||||
## Using the Probe
|
||||
|
||||
:::info
|
||||
To debug STM32F7 or later (FMUv5 and newer) the Dronecode probe / Blackmagic probe likely requires a firmware update.
|
||||
You can find how to update the [blackmagic probe here](https://github.com/blacksphere/blackmagic/wiki/Upgrading-Firmware).
|
||||
:::
|
||||
|
||||
To use a Dronecode probe with GDB, start GDB with the exact ELF file that is currently flashed on the autopilot:
|
||||
|
||||
```sh
|
||||
arm-none-eabi-gdb build/px4_fmu-v5_default/px4_fmu-v5_default.elf
|
||||
```
|
||||
|
||||
Then, you have to select the Dronecode probe interface, on Linux this is e.g.:
|
||||
|
||||
```sh
|
||||
target ext /dev/serial/by-id/usb-Black_Sphere_Technologies_Black_Magic_Probe_f9414d5_7DB85DAC-if00
|
||||
```
|
||||
|
||||
Then you scan for the target:
|
||||
|
||||
```sh
|
||||
monitor swdp_scan
|
||||
```
|
||||
|
||||
And you should see something like:
|
||||
|
||||
```sh
|
||||
Target voltage: 3.3V
|
||||
Available Targets:
|
||||
No. Att Driver
|
||||
1 STM32F76x M7
|
||||
```
|
||||
|
||||
Note that for some autopilots it shows 0.0V but the subsequent steps work nevertheless.
|
||||
|
||||
You can now attach to that target:
|
||||
|
||||
```sh
|
||||
attach 1
|
||||
```
|
||||
|
||||
And now you should be connected.
|
||||
@@ -0,0 +1,71 @@
|
||||
# JLink Debug Probe
|
||||
|
||||
The [J-Link debug probe][jlink] is a closed-source, commercial hardware probe which supports almost all ARM Cortex-M devices.
|
||||
You need to install the [J-Link drivers][drivers] for this probe to work:
|
||||
|
||||
```sh
|
||||
# Ubuntu
|
||||
wget --post-data "accept_license_agreement=accepted" https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.deb
|
||||
sudo dpkg -i JLink_Linux_x86_64.deb
|
||||
# macOS
|
||||
brew install segger-jlink
|
||||
```
|
||||
|
||||
Once installed, you can start the server using:
|
||||
|
||||
```sh
|
||||
JLinkGDBServer -if swd -device STM32F765II
|
||||
```
|
||||
|
||||
It might then prompt you to update the JLink which is recommended, and then to specify which device it is communicating with.
|
||||
Check the docs of your autopilot for the specific device.
|
||||
|
||||
Once that's done, the GDB server should be start listening on port `2331`, e.g. like so:
|
||||
|
||||
```sh
|
||||
Checking target voltage...
|
||||
Target voltage: 3.28 V
|
||||
Listening on TCP/IP port 2331
|
||||
Connecting to target...
|
||||
Connected to target
|
||||
Waiting for GDB connection...
|
||||
```
|
||||
|
||||
You can now start GDB with the exact elf file that is currently flashed on the autopilot (in a separate terminal):
|
||||
|
||||
```sh
|
||||
arm-none-eabi-gdb build/px4_fmu-v5_default/px4_fmu-v5_default.elf -ex "target extended-remote :2331"
|
||||
```
|
||||
|
||||
And now you should be connected.
|
||||
|
||||
To use an IDE instead, see the instructions for [Eclipse](../debug/eclipse_jlink.md) or [VSCode](../dev_setup/vscode.md#hardware-debugging).
|
||||
See the [Embedded Debug Tools][emdbg] for more advanced debug options.
|
||||
|
||||
<a id="segger_jlink_edu_mini"></a>
|
||||
|
||||
### Segger JLink EDU Mini Debug Probe
|
||||
|
||||
The [Segger JLink EDU Mini](https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/) is an inexpensive and popular SWD debug probe.
|
||||
The probe's connector pinout looks like the image below (connect to this using an ARM 10-pin mini connector like [FTSH-105-01-F-DV-K](https://www.digikey.com/products/en?keywords=SAM8796-ND)).
|
||||
|
||||
|
||||
|
||||
The pin mapping to connect the J-Link Edu Mini to [Pixhawk Debug Mini](swd_debug.md#pixhawk-debug-mini) is shown below.
|
||||
|
||||
| 针脚 | 信号 | JLink |
|
||||
| -: | :--------- | ----: |
|
||||
| 1 | **VREF** | 1 |
|
||||
| 2 | Console TX | |
|
||||
| 3 | Console RX | |
|
||||
| 4 | **SWDIO** | 2 |
|
||||
| 5 | **SWDCLK** | 4 |
|
||||
| 6 | **GND** | 3, 5 |
|
||||
|
||||
Note that none of the JLink debug probes have a built in serial connection, so you need to connect the console separately.
|
||||
|
||||
<!-- Image of SWD cable and connector to debug port - proposed? -->
|
||||
|
||||
[jlink]: https://www.segger.com/products/debug-probes/j-link/
|
||||
[drivers]: https://www.segger.com/downloads/jlink/
|
||||
[emdbg]: https://pypi.org/project/emdbg/
|
||||
@@ -0,0 +1,84 @@
|
||||
# MCU-Link Debug Probe
|
||||
|
||||
The [MCU-Link Debug Probe](https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/mcu-link-debug-probe:MCU-LINK) is a cheap, fast and highly capable debug probe that can serve as a stand-alone debug and console communicator whn working with Pixhawk boards.
|
||||
|
||||
主要特性：
|
||||
|
||||
- Just one single USB-C connection for Reset, SWD, SWO, and serial in a very small package!
|
||||
- Up to 9.6MBit/s SWO connection.
|
||||
Up to 5 MBaud serial. 1.2V to 5V target voltage.
|
||||
USB2 high-speed 480 Mbps connection.
|
||||
- Driven by NXP LinkServer or pyOCD software with wide device support.
|
||||
- Much cheaper (<15€) than a Pixhawk Debug Adapter (~20€) with a JLink EDU mini (~55€) or JLink BASE (~400€) while having better hardware specs.
|
||||
|
||||
The [Pixhawk Debug Adapter](https://holybro.com/products/pixhawk-debug-adapter) provides an easy way to connect a Pixhawk to an MCU-Link (the probe does not come with an adapter for working with Pixhawk flight controllers).
|
||||
|
||||
:::info
|
||||
These instructions have been tested on: FMUv6X-RT, FMUv6X, FMUv6c, FMUv5X.
|
||||
:::
|
||||
|
||||
## Debugging Configuration using NXP LinkServer
|
||||
|
||||
The MCU-Link provides for NXP (FMUv6X-RT) chips the [LinkServer](https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/linkserver-for-microcontrollers:LINKERSERVER) GDB server:
|
||||
|
||||
[Download](https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/linkserver-for-microcontrollers:LINKERSERVER#downloads) the Linkserver for your operating system and follow the installation instructions.
|
||||
|
||||
On Windows LinkServer gets installed to `C:\NXP\LinkServer_x.x.x`
|
||||
On Linux LinkServer gets installed `/usr/local/LinkServer/LinkServer`
|
||||
|
||||
To flash you can use the `LinkServer flash` command with target `MIMXRT1176xxxxx:MIMXRT1170-EVK-CM7-ONLY` for the FMUv6X-RT
|
||||
|
||||
```sh
|
||||
/usr/local/LinkServer/LinkServer flash MIMXRT1176xxxxx:MIMXRT1170-EVK-CM7-ONLY load build/px4_fmu-v6xrt_default/px4_fmu-v6xrt_default.elf
|
||||
```
|
||||
|
||||
You can launch the GDB server in a new terminal shell:
|
||||
|
||||
```sh
|
||||
/usr/local/LinkServer/LinkServer gdbserver MIMXRT1176xxxxx:MIMXRT1170-EVK-CM7-ONLY
|
||||
```
|
||||
|
||||
Then connect to port 3333 via GDB:
|
||||
|
||||
```sh
|
||||
arm-none-eabi-gdb build/px4_fmu-v6xrt_default/px4_fmu-v6xrt_default.elf -ex "target extended-remote :3333"
|
||||
```
|
||||
|
||||
Use GDB to load the binary into the Pixhawk:
|
||||
|
||||
```sh
|
||||
(gdb) load
|
||||
```
|
||||
|
||||
## Debugging Configuration using pyOCD
|
||||
|
||||
The MCU-Link provides the [GDB server via pyOCD](https://pyocd.io/):
|
||||
|
||||
```sh
|
||||
python3 -m pip install -U pyocd
|
||||
```
|
||||
|
||||
You can launch the GDB server in a new terminal shell:
|
||||
|
||||
```sh
|
||||
pyocd gdb -t mimxrt1170_cm7
|
||||
```
|
||||
|
||||
The target needs to be one of:
|
||||
|
||||
- FMUv6X-RT: `mimxrt1170_cm7`
|
||||
- FMUv6X: `stm32h743xx`
|
||||
- FMUv6C: `stm32h743xx`
|
||||
- FMUv5X: `stm32f767zi`
|
||||
|
||||
You can then connect to port 3333 via GDB:
|
||||
|
||||
```sh
|
||||
arm-none-eabi-gdb build/px4_fmu-v6xrt_default/px4_fmu-v6xrt_default.elf -ex "target extended-remote :3333"
|
||||
```
|
||||
|
||||
Use GDB to load the binary into the Pixhawk:
|
||||
|
||||
```sh
|
||||
(gdb) load
|
||||
```
|
||||
@@ -0,0 +1,203 @@
|
||||
# STLink Debug Probe
|
||||
|
||||
The [STLinkv3-MINIE](https://www.st.com/en/development-tools/stlink-v3minie.html) is a cheap, fast and highly capable debug probe that can serve as a stand-alone debug and console communicator for a PX4 developer:
|
||||
|
||||
- Just one single USB-C connection for Reset, SWD, SWO, and serial in a very small package!
|
||||
- Up to 24MHz SWD and SWO connection.
|
||||
Up to 16 MBaud serial. 1.65V to 3.6V target voltage.
|
||||
USB2 high-speed 480 Mbps connection.
|
||||
- Driven by STLink or OpenOCD software with wide device support.
|
||||
- Much cheaper (<15€) than a Pixhawk Debug Adapter (~20€) with a JLink EDU mini (~55€) or JLink BASE (~400€) while having better hardware specs.
|
||||
|
||||
The STLink Debug Probe does not come with an adapter for working with Pixhawk flight controllers.
|
||||
The [Pixhawk Debug Port Adapter](#pixhawk-debug-port-adapter) section below explains how you can create your own (some soldering required).
|
||||
|
||||
:::info
|
||||
The [CUAV C-ADB Pixhawk Debugging Adapter](../debug/swd_debug.md#cuav-c-adb-pixhawk-debug-adapter) (~65€) comes with an STLinkv3-MINIE!
|
||||
This has a connector for the [Pixhawk Debug Full](../debug/swd_debug.md#pixhawk-debug-full) 10-pin SH port (but not the [Pixhawk Debug Mini](../debug/swd_debug.md#pixhawk-debug-mini)).
|
||||
:::
|
||||
|
||||
## Debugging Configuration
|
||||
|
||||
The STLink provides the [GDB server via OpenOCD](https://openocd.org/doc-release/html/index.html):
|
||||
|
||||
```sh
|
||||
# Ubuntu
|
||||
sudo apt install openocd
|
||||
# macOS
|
||||
brew install open-ocd
|
||||
```
|
||||
|
||||
You can launch the GDB server in a new terminal shell:
|
||||
|
||||
```sh
|
||||
openocd -f interface/stlink.cfg -f target/stm32f7x.cfg
|
||||
```
|
||||
|
||||
The config file needs to be:
|
||||
|
||||
- FMUv2-v4: `-f target/stm32f4x.cfg`
|
||||
- FMUv5: `-f target/stm32f7x.cfg`
|
||||
- FMUv6: `-f target/stm32h7x.cfg`
|
||||
|
||||
You can then connect to port 3333 via GDB:
|
||||
|
||||
```sh
|
||||
arm-none-eabi-gdb build/px4_fmu-v5x_default/px4_fmu-v5x_default.elf -ex "target extended-remote :3333"
|
||||
```
|
||||
|
||||
See the [Embedded Debug Tools][emdbg] for more advanced debug options.
|
||||
|
||||
## Pixhawk Debug Port Adapter
|
||||
|
||||
To connect to the Pixhawk Debug Port, you need to solder an adapter (unless using the [CUAV Debug Adaptor](../debug/swd_debug.md#cuav-c-adb-pixhawk-debug-adapter)).
|
||||
|
||||
For this solder guide you need:
|
||||
|
||||
- 1x [STLinkv3-MINIE](https://www.st.com/en/development-tools/stlink-v3minie.html).
|
||||
|
||||
- 1x cable connector for mating with [JST SM10B (Full)](https://www.digikey.com/products/en?keywords=A10SR10SR30K203A) or [JST SM06B (Mini)](https://www.digikey.com/products/en?keywords=A06SR06SR30K152A).
|
||||
|
||||
We recommend buying fully assembled cables with two connectors on either side.
|
||||
|
||||
- 1x soldering iron and solder.
|
||||
|
||||
- Some tongs, cutting pliers, and tweezers.
|
||||
|
||||
The [Pixhawk Debug Port is standardized in DS-009](https://github.com/pixhawk/Pixhawk-Standards/blob/master/DS-009%20Pixhawk%20Connector%20Standard.pdf) and needs to be connected to the STLinkv3-MINIE Board-To-Board (BTB) card edge connector CN2.
|
||||
The pinout mapping is described here:
|
||||
|
||||
| #Full | #Mini | Pixhawk Debug | STLinkv3 | #BTB |
|
||||
| ----: | ----: | :---------------------------------- | :-------------------------- | ---: |
|
||||
| 1 | 1 | **VREF** | VCC | 10 |
|
||||
| 2 | 2 | Console TX (out) | TX (in) | 8 |
|
||||
| 3 | 3 | Console RX (in) | RX (out) | 7 |
|
||||
| 4 | 4 | **SWDIO** | TMS | 3 |
|
||||
| 5 | 5 | **SWCLK** | CLK | 4 |
|
||||
| 6 | | SWO | TDO | 5 |
|
||||
| 7 | | GPIO1 | | |
|
||||
| 8 | | GPIO2 | | |
|
||||
| 9 | | nRST | RST | 9 |
|
||||
| 10 | 6 | **GND** | GND | 6 |
|
||||
|
||||
The GPIO1/2 pins are not supported by the STLinkv3, and we recommend using digital ITM profiling over SWO which is much more flexible and supports cycle accurate timestamping.
|
||||
|
||||
You can choose to solder a short or long cable to the BTB connector.
|
||||
The short cable is better for high-speed communication, but is more difficult to solder.
|
||||
We recommend soldering the long cable first and testing how fast you can communicate with your target.
|
||||
|
||||
:::info
|
||||
This guide is written for the full 10-pin debug port.
|
||||
If you want to solder the mini 6-pin version, just leave out the signals you don't have.
|
||||
The STLink supports any SWD/JTAG-based debug interface, so you can adapt this guide for any other connector you may have.
|
||||
The debug probes are so cheap, you can just have one per connector instead of using adapters.
|
||||
:::
|
||||
|
||||
This is how the STLinkv3-MINIE is delivered.
|
||||
|
||||
|
||||
|
||||
Unwrap the PCB and check it for any damage.
|
||||
Plug it in and see if it powers on correctly.
|
||||
|
||||
|
||||
|
||||
### Short Cable
|
||||
|
||||
The short cable requires a wire cutter and stripper and requires a little more soldering skill.
|
||||
However, it makes the entire debug probe even smaller.
|
||||
|
||||
Assemble a 10-pin connector without GPIO1/2. If you already have an assembled cable, carefully remove the two GPIO1/2 cables with a tweezer by lifting the pegs that keep the cables secured.
|
||||
Cut the cables to a short ~2cm (~1in) length and strip the wires.
|
||||
|
||||
|
||||
|
||||
Tin both the BTB connector on the STLink and the cables.
|
||||
|
||||
|
||||
|
||||
First solder the GND and VCC signals to align the connector in parallel to the edge.
|
||||
Then solder the TX and RX pins. Solder the RST connection last.
|
||||
|
||||
|
||||
|
||||
Turn the STLink over and solder the remaining three wires.
|
||||
Start with SWDIO->TMS, then SWCLK->CLK, and finally SWO->TDO.
|
||||
|
||||
|
||||
|
||||
### Long Cable
|
||||
|
||||
The long cable is particularly useful if you use pre-assembled cables as it removes the need to cut wires or strip them.
|
||||
|
||||
Carefully remove the two GPIO1/2 cables from one connector of the cable.
|
||||
Then remove all cables from the other connector.
|
||||
You are left with a eight crimped connectors at the end of the wires.
|
||||
|
||||
|
||||
|
||||
Tin the crimped cable connectors and BTB connector and solder the crimped connectors directly to the STLinkv3.
|
||||
Be careful to not create shorts between the cables, as the crimped connectors are quite large.
|
||||
|
||||
|
||||
|
||||
### 测试
|
||||
|
||||
You should now test your debug probe to ensure you do not have any electrical shorts.
|
||||
|
||||
1. Plug the probe into your target via the Pixhawk Debug Port.
|
||||
2. Test the serial port with a program of your choice.
|
||||
3. Test the SWD and RST connection via [OpenOCD][https://openocd.org] or [STLink](https://www.st.com/en/development-tools/stsw-link004.html) software.
|
||||
4. Test the SWO connection via [Orbuculum][https://github.com/orbcode/orbuculum].
|
||||
|
||||
See the [Embedded Debug Tools][emdbg] for more information about software support for the PX4 FMUv5 and FMUv6 flight controllers.
|
||||
|
||||
### Make it Smaller
|
||||
|
||||
This step removes the 14-pin debug interface on the back of the STLinkv3-MINIE and adds shrink tubing around the entire device to improve handling and prevent shorting the STLink against metal parts or PCBs.
|
||||
This step is strictly optional and requires:
|
||||
|
||||
- 1x 20mm shrink tubing about 5cm long.
|
||||
- 1x flat tongs to hold the STLinkv3 by the USB-C port.
|
||||
- 1x fine cutting pliers or soldering iron.
|
||||
- 1x heat gun.
|
||||
|
||||
Use the pliers to gently pull off the plastic part of the STDC14 connector.
|
||||
This leaves you with only the connector pins.
|
||||
|
||||
|
||||
|
||||
Using the fine pliers, cut off the connector pins being very careful not to damage the PCB or any components on the PCB.
|
||||
Alternatively, you can solder these connector pin off the PCB, but it can take longer.
|
||||
|
||||
|
||||
|
||||
Rotate the STLinkv3 to cut off the other row, again being very careful to not damage it.
|
||||
|
||||
|
||||
|
||||
Cut a ~5cm (~2in) long piece of shrink tube.
|
||||
It should be flush with the USB-C connector and extend a little beyond the end.
|
||||
|
||||
|
||||
|
||||
Hold both the PCB and the shrink tube with the flat tongs by the **bottom** metal part of the USB-C connector.
|
||||
Be careful not to accidentally squeeze the middle plastic part of the USB-C connector!
|
||||
|
||||
|
||||
|
||||
Use the heat gun to shrink the tubing all around the debug probe.
|
||||
Make sure the tubing is equally shrunk and protects the whole PCB.
|
||||
|
||||
|
||||
|
||||
Optionally, you may add a logo of your choice printed on paper and cut to size.
|
||||
Be aware that the heat can make the ink flow a little, so you may need to experiment with what settings work with your printer.
|
||||
|
||||
|
||||
|
||||
[emdbg]: https://pypi.org/project/emdbg/
|
||||
|
||||
## See also
|
||||
|
||||
- [STLINK-V3MINIE debugger/programmer tiny probe for STM32 microcontrollers](https://www.st.com/resource/en/user_manual/um2910-stlinkv3minie-debuggerprogrammer-tiny-probe-for-stm32-microcontrollers-stmicroelectronics.pdf) (User Manual)
|
||||
@@ -0,0 +1,120 @@
|
||||
# Poor Man's Sampling Profiler
|
||||
|
||||
This section describes how you can use the [Poor Man's Sampling Profiler](https://github.com/PX4/PX4-Autopilot/blob/main/platforms/nuttx/Debug/poor-mans-profiler.sh) (PMSP) shell script to assess the performance of PX4.
|
||||
This is an implementation of a known method originally invented by [Mark Callaghan and Domas Mituzas](https://poormansprofiler.org/).
|
||||
|
||||
## 方法
|
||||
|
||||
PMSP 是一种 shell 脚本,它通过定期中断固件的执行来运行，便对当前堆栈跟踪进行采样。
|
||||
采样的堆栈跟踪将追加到文本文件中。
|
||||
Once sampling is finished (which normally takes about an hour or more), the collected stack traces are _folded_.
|
||||
The result of _folding_ is another text file that contains the same stack traces, except that all similar stack traces (i.e. those that were obtained at the same point in the program) are joined together, and the number of their occurrences is recorded.
|
||||
The folded stacks are then fed into the visualization script, for which purpose we employ [FlameGraph - an open source stack trace visualizer](http://www.brendangregg.com/flamegraphs.html).
|
||||
|
||||
## 基本用法
|
||||
|
||||
### 系统必备组件
|
||||
|
||||
探查器的基本用法可通过生成系统使用。
|
||||
例如，下面的命令生成和探查出 px4_fmu-v4pro 目标的10000个样本（提取 <em x-id="3">FlameGraph</em> 并根据需要将其添加到路径中）。
|
||||
You will then need a [debug probe](../debug/swd_debug.md#debug-probes) (such as the DroneCode Probe), to run the GDB server and interact with the board.
|
||||
|
||||
### Determine the Debugger Device
|
||||
|
||||
The `poor-mans-profiler.sh` automatically detects and uses the correct USB device if you use it with a [DroneCode Probe](../debug/probe_bmp.md#dronecode-probe).
|
||||
If you use a different kind of probe you may need to pass in the specific _device_ on which the debugger is located.
|
||||
You can use the bash command `ls -alh /dev/serial/by-id/` to enumerate the possible devices on Ubuntu.
|
||||
For example the following devices are enumerated with a Pixhawk 4 and DroneCode Probe connected over USB:
|
||||
|
||||
```sh
|
||||
user@ubuntu:~/PX4-Autopilot$ ls -alh /dev/serial/by-id/
|
||||
total 0
|
||||
drwxr-xr-x 2 root root 100 Apr 23 18:57 .
|
||||
drwxr-xr-x 4 root root 80 Apr 23 18:48 ..
|
||||
lrwxrwxrwx 1 root root 13 Apr 23 18:48 usb-3D_Robotics_PX4_FMU_v5.x_0-if00 -> ../../ttyACM0
|
||||
lrwxrwxrwx 1 root root 13 Apr 23 18:57 usb-Black_Sphere_Technologies_Black_Magic_Probe_BFCCB401-if00 -> ../../ttyACM1
|
||||
lrwxrwxrwx 1 root root 13 Apr 23 18:57 usb-Black_Sphere_Technologies_Black_Magic_Probe_BFCCB401-if02 -> ../../ttyACM2
|
||||
```
|
||||
|
||||
In this case, the script would automatically pick up the device named `*Black_Magic_Probe*-if00`.
|
||||
But if you were using a different device you would be able discover the appropriate id from the listing above.
|
||||
|
||||
Then pass in the appropriate device using the `--gdbdev` argument like this:
|
||||
|
||||
```sh
|
||||
./poor-mans-profiler.sh --elf=build/px4_fmu-v4_default/px4_fmu-v4_default.elf --nsamples=30000
|
||||
```
|
||||
|
||||
### Running
|
||||
|
||||
在火焰图上，水平水平表示堆叠帧，而每个帧的宽度与采样次数成正比。
|
||||
For example, the following command builds and profiles px4_fmu-v4pro target with 10000 samples (fetching _FlameGraph_ and adding it to the path as needed).
|
||||
|
||||
```sh
|
||||
./poor-mans-profiler.sh --elf=build/px4_fmu-v4_default/px4_fmu-v4_default.elf --nsamples=30000 --append
|
||||
```
|
||||
|
||||
For more control over the build process, including setting the number of samples, see the [Implementation](#implementation).
|
||||
|
||||
## 理解输出
|
||||
|
||||
A screenshot of an example output is provided below (note that it is not interactive here):
|
||||
|
||||
|
||||
|
||||
PMSP 使用 GDB 收集堆栈跟踪。
|
||||
目前，它使用 <code>arm-none-eabi-gdb</code>，今后可能会添加其他工具链。
|
||||
|
||||
## 可能的问题
|
||||
|
||||
为了能够映射内存地址到符号，脚本需要被当前运行的文件中提及。
|
||||
这个是在 <code>--elf=&lt;file&gt;</code> 的选项帮助下完成的，该选项需要一个指向当前执行ELF位置的路径来执行（相对于储存库的root）。
|
||||
|
||||
- 如果 GDB 出现故障，脚本可能无法检测到该问题，并继续运行。
|
||||
在这种情况下，显然不会产生可用的堆栈。
|
||||
In order to avoid that, the user should periodically check the file `/tmp/pmpn-gdberr.log`, which contains the stderr output of the most recent invocation of GDB.
|
||||
将来，应修改脚本以在安静模式下调用 GDB，在安静模式下，它将通过其退出代码指示问题。
|
||||
|
||||
- 有时 GDB 一直运行，同时采样堆栈跟踪。
|
||||
在此失败期间，目标将无限期停止。
|
||||
The solution is to manually abort the script and re-launch it again with the `--append` option.
|
||||
将来，应修改脚本以对每次 GDB 调用强制执行超时。
|
||||
|
||||
- 不支持多线程环境。
|
||||
这不会影响单个核心嵌入式目标，因为它们总是在一个线程中执行，但这一限制使探查器与许多其他应用程序不兼容。
|
||||
将来，应修改堆栈文件夹以支持每个示例的多个堆栈跟踪。
|
||||
|
||||
## 实现
|
||||
|
||||
The script is located at [/platforms/nuttx/Debug/poor-mans-profiler.sh](https://github.com/PX4/PX4-Autopilot/blob/main/platforms/nuttx/Debug/poor-mans-profiler.sh)
|
||||
Once launched, it will perform the specified number of samples with the specified time interval.
|
||||
Collected samples will be stored in a text file in the system temp directory (typically `/tmp`).
|
||||
Once sampling is finished, the script will automatically invoke the stack folder, the output of which will be stored in an adjacent file in the temp directory.
|
||||
If the stacks were folded successfully, the script will invoke the _FlameGraph_ script and store the result in an interactive SVG file.
|
||||
Please note that not all image viewers support interactive images;
|
||||
it is recommended to open the resulting SVG in a web browser.
|
||||
|
||||
The FlameGraph script must reside in the `PATH`, otherwise PMSP will refuse to launch.
|
||||
|
||||
PMSP uses GDB to collect the stack traces.
|
||||
Currently it uses `arm-none-eabi-gdb`, other toolchains may be added in the future.
|
||||
|
||||
In order to be able to map memory locations to symbols, the script needs to be referred to the executable file that is currently running on the target.
|
||||
This is done with the help of the option `--elf=<file>`, which expects a path (relative to the root of the repository) pointing to the location of the currently executing ELF.
|
||||
|
||||
该想法的功劳归属 <a href="https://dom.as/2009/02/15/poor-mans-contention-profiling/">Mark Callaghan and Domas Mituzas</a>。
|
||||
|
||||
```sh
|
||||
./poor-mans-profiler.sh --elf=build/px4_fmu-v4_default/px4_fmu-v4_default.elf --nsamples=30000
|
||||
```
|
||||
|
||||
Note that every launch of the script will overwrite the old stacks.
|
||||
Should you want to append to the old stacks rather than overwrite them, use the option `--append`:
|
||||
|
||||
```sh
|
||||
./poor-mans-profiler.sh --elf=build/px4_fmu-v4_default/px4_fmu-v4_default.elf --nsamples=30000 --append
|
||||
```
|
||||
|
||||
As one might suspect, `--append` with `--nsamples=0` will instruct the script to only regenerate the SVG without accessing the target at all.
|
||||
|
||||
Please read the script for a more in depth understanding of how it works.
|
||||
@@ -0,0 +1,22 @@
|
||||
# 使用侦听器命令进行传感器/主题调试
|
||||
|
||||
The uORB is an asynchronous `publish()` / `subscribe()` messaging API used for
|
||||
inter-thread/inter-process communication. The `listener` command can be used from the _QGroundControl MAVLink Console_ to inspect topic (message) values, including the current values published by sensors.
|
||||
|
||||
:::tip
|
||||
这是一个非常实用的调试工具，应为它可以在QGC通过无线连接的时候使用（例如，当机体在飞行中）。
|
||||
:::
|
||||
|
||||
:::info
|
||||
The `listener` command is also available through the [System Console](../debug/system_console.md) and the [MAVLink Shell](../debug/mavlink_shell.md).
|
||||
:::
|
||||
|
||||
:::tip
|
||||
To check what topics are available at what rate, just use the `uorb top` command.
|
||||
:::
|
||||
|
||||
The image below demonstrates _QGroundControl_ being used to get the value of the acceleration sensor.
|
||||
|
||||
|
||||
|
||||
For more information about how to determine what topics are available and how to call `listener` see: [uORB Messaging > Listing Topics and Listening in](../middleware/uorb.md#listing-topics-and-listening-in).
|
||||
@@ -0,0 +1,195 @@
|
||||
# 仿真调试
|
||||
|
||||
当模拟在主机上运行时，所有桌面开发工具都可用。
|
||||
|
||||
## CLANG Address Sanitizer (Mac OS, Linux)
|
||||
|
||||
The Clang address sanitizer can help to find alignment (bus) errors and other memory faults like segmentation faults. The command below sets the right compile options. 下面的命令设置了正确的编译选项。
|
||||
|
||||
```sh
|
||||
make clean # 仅需在常规编译后，第一次运行 address sanitizer 时使用
|
||||
PX4_ASAN=1 make px4_sitl jmavsim
|
||||
```
|
||||
|
||||
## Valgrind
|
||||
|
||||
```sh
|
||||
brew install valgrind
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```sh
|
||||
sudo apt-get install valgrind
|
||||
```
|
||||
|
||||
SITL can be launched with and without debugger attached and with either jMAVSim or Gazebo as simulation backend. This results in the start options below:
|
||||
|
||||
```sh
|
||||
make px4_sitl_default # 通过 cmake 配置
|
||||
make -C build/px4_sitl_default jmavsim___gdb
|
||||
```
|
||||
|
||||
## Launch Gazebo Classic SITL Without Debugger
|
||||
|
||||
By default SITL is launched without a debugger attached when using any simulator backend:
|
||||
|
||||
```sh
|
||||
make px4_sitl_default gz
|
||||
make px4_sitl_default gazebo-classic
|
||||
make px4_sitl_default jmavsim
|
||||
```
|
||||
|
||||
For Gazebo Classic (only) you can also start the simulator with a debugger attached.
|
||||
Note however, that you must provide the vehicle type in the simulator target, as shown below:
|
||||
|
||||
```sh
|
||||
make px4_sitl_default gazebo-classic_iris_gdb
|
||||
make px4_sitl_default gazebo-classic_iris_lldb
|
||||
```
|
||||
|
||||
This will start the debugger and launch the SITL application with Gazebo and the Iris simulator.
|
||||
In order to break into the debugger shell and halt the execution, hit `CTRL-C`:
|
||||
|
||||
```sh
|
||||
Process 16529 stopped
|
||||
* thread #1: tid = 0x114e6d, 0x00007fff90f4430a libsystem_kernel.dylib`__read_nocancel + 10, name = 'px4', queue = 'com.apple.main-thread', stop reason = signal SIGSTOP
|
||||
frame #0: 0x00007fff90f4430a libsystem_kernel.dylib`__read_nocancel + 10
|
||||
libsystem_kernel.dylib`__read_nocancel:
|
||||
-> 0x7fff90f4430a <+10>: jae 0x7fff90f44314 ; <+20>
|
||||
0x7fff90f4430c <+12>: movq %rax, %rdi
|
||||
0x7fff90f4430f <+15>: jmp 0x7fff90f3fc53 ; cerror_nocancel
|
||||
0x7fff90f44314 <+20>: retq
|
||||
(lldb)
|
||||
```
|
||||
|
||||
In order to not have the DriverFrameworks scheduling interfere with the debugging session `SIGCONT` should be masked in LLDB and GDB:
|
||||
|
||||
```sh
|
||||
(lldb) process handle SIGCONT -n false -p false -s false
|
||||
```
|
||||
|
||||
或者在 GDB 下：
|
||||
|
||||
```sh
|
||||
(gdb) handle SIGCONT noprint nostop
|
||||
```
|
||||
|
||||
之后，lldb 或 gdb 脚本的行为类似于正常会话，请参阅 ldb/gdbb 文档。
|
||||
|
||||
The last parameter, the <viewer_model_debugger> triplet, is actually passed to make in the build directory, so
|
||||
|
||||
```sh
|
||||
make px4_sitl_default gazebo-classic_iris_gdb
|
||||
```
|
||||
|
||||
等价于
|
||||
|
||||
```sh
|
||||
make px4_sitl_default # Configure with cmake
|
||||
make -C build/px4_sitl_default classic_iris_gdb
|
||||
```
|
||||
|
||||
A full list of the available make targets in the build directory can be obtained with:
|
||||
|
||||
```sh
|
||||
make help
|
||||
```
|
||||
|
||||
## Attaching GDB to running SITL
|
||||
|
||||
You can also start your simulation, and _then_ attach `gdb`:
|
||||
|
||||
1. In one terminal screen enter the command to start your simulation:
|
||||
|
||||
```sh
|
||||
make px4_sitl_default gazebo-classic
|
||||
```
|
||||
|
||||
As the script runs, note the **SITL COMMAND:** output text located right above the large "PX4" text.
|
||||
It will list the location of your px4 bin file for later use.
|
||||
|
||||
```sh
|
||||
SITL COMMAND: "<px4 bin file>" "<build dir>"/etc
|
||||
|
||||
______ __ __ ___
|
||||
| ___ \ \ \ / / / |
|
||||
| |_/ / \ V / / /| |
|
||||
| __/ / \ / /_| |
|
||||
| | / /^\ \ \___ |
|
||||
\_| \/ \/ |_/
|
||||
|
||||
px4 starting.
|
||||
|
||||
INFO [px4] startup script: /bin/sh etc/init.d-posix/rcS 0
|
||||
INFO [init] found model autostart file as SYS_AUTOSTART=10015
|
||||
```
|
||||
|
||||
2. Open another terminal and type:
|
||||
|
||||
```sh
|
||||
ps -a
|
||||
```
|
||||
|
||||
You will want to note the PID of the process named "PX4"
|
||||
|
||||
(In this example it is 14149)
|
||||
|
||||
```sh
|
||||
atlas:~/px4/main/PX4-Autopilot$ ps -a
|
||||
PID TTY TIME CMD
|
||||
1796 tty2 00:01:59 Xorg
|
||||
1836 tty2 00:00:00 gnome-session-b
|
||||
14027 pts/1 00:00:00 make
|
||||
14077 pts/1 00:00:00 sh
|
||||
14078 pts/1 00:00:00 cmake
|
||||
14079 pts/1 00:00:00 ninja
|
||||
14090 pts/1 00:00:00 sh
|
||||
14091 pts/1 00:00:00 bash
|
||||
14095 pts/1 00:01:23 gzserver
|
||||
14149 pts/1 00:02:48 px4
|
||||
14808 pts/2 00:00:00 ps
|
||||
```
|
||||
|
||||
3. Then type in the same window
|
||||
|
||||
```sh
|
||||
sudo gdb [px4 bin file path (from step 1) here]
|
||||
```
|
||||
|
||||
would suppress optimization of the targets: platforms\*\_posix<strong x-id="1">px4\_layer, modules</strong>systemlib, modules<strong x-id="1">uORB, examples</strong>px4\_simple\_app, modules\*\*uORB\*\_uORB\_tests and px4.
|
||||
|
||||
```sh
|
||||
sudo gdb /home/atlas/px4/base/PX4-Autopilot/build/px4_sitl_default/bin/px4
|
||||
```
|
||||
|
||||
Now, you can attach to the PX4 instance by entering the PID noted in step 2.
|
||||
|
||||
```sh
|
||||
attach [PID on px4]
|
||||
```
|
||||
|
||||
You should now have a GDB interface to debug with.
|
||||
|
||||
## 编译器优化
|
||||
|
||||
It is possible to suppress compiler optimization for given executables and/or modules (as added by cmake with `add_executable` or `add_library`) when configuring
|
||||
for `posix_sitl_*`.
|
||||
This can be handy when it is necessary to step through code with a debugger or print variables that would otherwise be optimized out.
|
||||
|
||||
To do so, set the environment variable `PX4_NO_OPTIMIZATION` to be a semi-colon separated list of regular expressions that match the targets that need to be compiled without optimization.
|
||||
This environment variable is ignored when the configuration isn't `posix_sitl_*`.
|
||||
|
||||
would suppress optimization of the targets: platforms\*\_posix<strong x-id="1">px4\_layer, modules</strong>systemlib, modules<strong x-id="1">uORB, examples</strong>px4\_simple\_app, modules\*\*uORB\*\_uORB\_tests and px4.
|
||||
|
||||
```sh
|
||||
export PX4_NO_OPTIMIZATION='px4;^modules__uORB;^modules__systemlib$'
|
||||
```
|
||||
|
||||
would suppress optimization of the targets: platforms\_\_posix\_\_px4_layer, modules\_\_systemlib, modules\_\_uORB, examples\_\_px4_simple_app, modules\_\_uORB\_\_uORB_tests and px4.
|
||||
|
||||
The targets that can be matched with these regular expressions can be printed with the command:
|
||||
|
||||
```sh
|
||||
make -C build/posix_sitl_* list_cmake_targets
|
||||
```
|
||||
@@ -0,0 +1,221 @@
|
||||
# SWD Debug Port
|
||||
|
||||
PX4 runs on ARM Cortex-M microcontrollers, which contain dedicated hardware for interactive debugging via the [_Serial Wire Debug (SWD)_][swd] interface and non-invasive profiling and high-bandwidth tracing via the [_Serial Wire Ouput (SWO)_][itm] and [_TRACE_ pins][etm].
|
||||
|
||||
The SWD debug interface allows direct, low-level, hardware access to the microcontroller's processor and peripherals, so it does not depend on any software on the device.
|
||||
Therefore it can be used to debug bootloaders and operating systems such as NuttX.
|
||||
|
||||
## Debug Signals
|
||||
|
||||
Four signals are required for debugging (in bold) while the rest is recommended.
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
| :-------------------------------------------------------------- | :---- | :-------------------------------------------------------------------------------------------------------- |
|
||||
| **GND** | 电源 | Shared potential, common ground. |
|
||||
| **VREF** | 电源 | The target reference voltage allows the debug probe to use level shifters on the signals. |
|
||||
| **SWDIO** | I/O | Serial Wire Debug data pin. |
|
||||
| **SWCLK** | Input | Serial Wire Debug clock pin. |
|
||||
| nRST | Input | The reset pin is optional (n = active low). |
|
||||
| SWO | 输出 | Single wire trace asynchronous data out can output ITM and DWT data. |
|
||||
| TRACECK | 输出 | Trace clock for parallel bus. |
|
||||
| TRACED[0-3] | 输出 | Trace synchronous data bus with 1, 2, or 4 bits. |
|
||||
|
||||
The hardware reset pin is optional, as most devices can also be reset via the SWD lines. However, quickly resetting the device via a button can be great for development.
|
||||
|
||||
The SWO pin can emit low-overhead, real-time profiling data with nanosecond timestamping and is therefore strongly recommended to have accessible for debugging.
|
||||
|
||||
The TRACE pins require specialized debug probes to deal with the high bandwidth and subsequent datastream decoding.
|
||||
They are usually not accessible and are typically only used to debug very specific timing issues.
|
||||
|
||||
<a id="debug-ports"></a>
|
||||
|
||||
## Autopilot Debug Ports
|
||||
|
||||
Flight controllers commonly provide a single debug port that exposes both the [SWD Interface](#debug-signals) and [System Console](system_console).
|
||||
|
||||
The [Pixhawk Connector Standards](#pixhawk-standard-debug-ports) formalize the port that must be used in each FMU version.
|
||||
However there are still many boards that use different pinouts or connectors, so we recommend you check the [documentation for your autopilot](../flight_controller/index.md) to confirm port location and pinout.
|
||||
|
||||
The debug port location and pinouts for a subset of autopilots are linked below:
|
||||
|
||||
<a id="port-information"></a>
|
||||
|
||||
| 飞控 | 调试接口 |
|
||||
| :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Holybro Pixhawk 6X-RT (FMUv6X-RT) | [Pixhawk Debug Full](#pixhawk-debug-full) |
|
||||
| Holybro Pixhawk 6X (FMUv6x) | [Pixhawk Debug Full](#pixhawk-debug-full) |
|
||||
| Holybro Pixhawk 5X (FMUv5x) | [Pixhawk Debug Full](#pixhawk-debug-full) |
|
||||
| [Holybro Durandal](../flight_controller/durandal.md#debug-port) | [Pixhawk Debug Mini](#pixhawk-debug-mini) |
|
||||
| [Holybro Kakute F7](../flight_controller/kakutef7.md#debug-port) | Solder pads |
|
||||
| [Holybro Pixhawk 4 Mini](../flight_controller/pixhawk4_mini.md#debug-port) (FMUv5) | [Pixhawk Debug Mini](#pixhawk-debug-mini) |
|
||||
| [Holybro Pixhawk 4](../flight_controller/pixhawk4.md#debug_port) (FMUv5) | [Pixhawk Debug Mini](#pixhawk-debug-mini) |
|
||||
| [Drotek Pixhawk 3 Pro](../flight_controller/pixhawk3_pro.md#debug-port) (FMU-v4pro) | [Pixhawk Debug Mini](#pixhawk-debug-mini) |
|
||||
| [CUAV V5+](../flight_controller/cuav_v5_plus.md#debug-port) | 6-pin JST GH<br>Digikey: [BM06B-GHS-TBT(LF)(SN)(N)][bm06b-ghs-tbt(lf)(sn)(n)] (vertical mount), [SM06B-GHS-TBT(LF)(SN)(N)][sm06b-ghs-tbt(lf)(sn)(n)] (side mount) |
|
||||
| [CUAV V5nano](../flight_controller/cuav_v5_nano.md#debug_port) | 6-pin JST GH<br>Digikey: [BM06B-GHS-TBT(LF)(SN)(N)][bm06b-ghs-tbt(lf)(sn)(n)] (vertical mount), [SM06B-GHS-TBT(LF)(SN)(N)][sm06b-ghs-tbt(lf)(sn)(n)] (side mount) |
|
||||
| [3DR Pixhawk](../flight_controller/pixhawk.md#swd-port) | ARM 10-pin JTAG Connector (also used for FMUv2 boards including: _mRo Pixhawk_, _HobbyKing HKPilot32_). |
|
||||
|
||||
<a id="pixhawk-standard-debug-ports"></a>
|
||||
|
||||
## Pixhawk Connector Standard Debug Ports
|
||||
|
||||
The Pixhawk project has defines a standard pinout and connector type for different Pixhawk FMU releases:
|
||||
|
||||
:::tip
|
||||
Check your [specific board](#port-information) to confirm the port used.
|
||||
:::
|
||||
|
||||
| FMU Version | Pixhawk Version | 调试接口 |
|
||||
| :---------- | :-------------------------------------------------------------- | :---------------------------------------- |
|
||||
| FMUv2 | [Pixhawk / Pixhawk 1](../flight_controller/pixhawk.md#swd-port) | 10 pin ARM Debug |
|
||||
| FMUv3 | Pixhawk 2 | 6 pin SUR Debug |
|
||||
| FMUv4 | Pixhawk 1/2 | [Pixhawk Debug Mini](#pixhawk-debug-mini) |
|
||||
| FMUv5 | Pixhawk 4 FMUv5 | [Pixhawk Debug Mini](#pixhawk-debug-mini) |
|
||||
| FMUv5X | Pixhawk 5X | [Pixhawk Debug Full](#pixhawk-debug-full) |
|
||||
| FMUv6 | Pixhawk 6 | [Pixhawk Debug Full](#pixhawk-debug-full) |
|
||||
| FMUv6X | Pixhawk 6X | [Pixhawk Debug Full](#pixhawk-debug-full) |
|
||||
| FMUv6X-RT | Pixhawk 6X-RT | [Pixhawk Debug Full](#pixhawk-debug-full) |
|
||||
|
||||
:::info
|
||||
There FMU and Pixhawk versions are (only) consistent after FMUv5X.
|
||||
:::
|
||||
|
||||
### Pixhawk Debug Mini
|
||||
|
||||
The [Pixhawk Connector Standard](https://github.com/pixhawk/Pixhawk-Standards/blob/master/DS-009%20Pixhawk%20Connector%20Standard.pdf) defines the _Pixhawk Debug Mini_, a _6-Pin SH Debug Port_ that provides access to both SWD pins and the [System Console](system_console).
|
||||
|
||||
This is used in FMUv4 and FMUv5.
|
||||
|
||||
The pinout is as shown below (pins required for debugging are bold):
|
||||
|
||||
| 针脚 | 信号 |
|
||||
| -: | :--------- |
|
||||
| 1 | **VREF** |
|
||||
| 2 | Console TX |
|
||||
| 3 | Console RX |
|
||||
| 4 | **SWDIO** |
|
||||
| 5 | **SWDCLK** |
|
||||
| 6 | **GND** |
|
||||
|
||||
The debug port definition includes the following solder pads (on board next to connector):
|
||||
|
||||
| Pad | 信号 | Voltage |
|
||||
| --: | :---- | :-------------------- |
|
||||
| 1 | nRST | +3.3V |
|
||||
| 2 | GPIO1 | +3.3V |
|
||||
| 3 | GPIO2 | +3.3V |
|
||||
|
||||
The socket is a _6-pin JST SH_ - Digikey number: [BM06B-SRSS-TBT(LF)(SN)](https://www.digikey.com/products/en?keywords=455-2875-1-ND) (vertical mount), [SM06B-SRSS-TBT(LF)(SN)](https://www.digikey.com/products/en?keywords=455-1806-1-ND)(side mount).
|
||||
|
||||
You can connect to the debug port using a [cable like this one](https://www.digikey.com/products/en?keywords=A06SR06SR30K152A).
|
||||
|
||||
|
||||
|
||||
### Pixhawk Debug Full
|
||||
|
||||
The [Pixhawk Connector Standard](https://github.com/pixhawk/Pixhawk-Standards/blob/master/DS-009%20Pixhawk%20Connector%20Standard.pdf) defines _Pixhawk Debug Full_, a _10-Pin SH Debug Port_ that provides access to both SWD pins and the [System Console](system_console).
|
||||
This essentially moves the solder pads from beside the [Pixhawk Debug Mini](#pixhawk-debug-mini) into the connector, and also adds an SWO pin.
|
||||
|
||||
该端口指定用于FMUv5x, FMUv6, FMUv6x。
|
||||
|
||||
The pinout is as shown below (pins required for debugging are bold):
|
||||
|
||||
| 针脚 | 信号 |
|
||||
| -: | :--------- |
|
||||
| 1 | **VREF** |
|
||||
| 2 | Console TX |
|
||||
| 3 | Console RX |
|
||||
| 4 | **SWDIO** |
|
||||
| 5 | **SWDCLK** |
|
||||
| 6 | SWO |
|
||||
| 7 | GPIO1 |
|
||||
| 8 | GPIO2 |
|
||||
| 9 | nRST |
|
||||
| 10 | **GND** |
|
||||
|
||||
The GPIO1/2 pins are free pins that can be used to generate signals in software for timing analysis with a logic analyzer.
|
||||
|
||||
The socket is a _10-pin JST SH_ - Digikey number: [BM10B-SRSS-TB(LF)(SN)](https://www.digikey.com/products/en?keywords=455-1796-2-ND) (vertical mount) or [SM10B-SRSS-TB(LF)(SN)](https://www.digikey.com/products/en?keywords=455-1810-2-ND) (side mount).
|
||||
|
||||
You can connect to the debug port using a [cable like this one](https://www.digikey.com/products/en?keywords=A10SR10SR30K203A).
|
||||
|
||||
<!-- FIXME: better to have image showing proper connections for SWD+SWO -->
|
||||
|
||||
|
||||
|
||||
<a id="debug-probes"></a>
|
||||
|
||||
## Debug Probes for PX4 Hardware
|
||||
|
||||
Flight controllers commonly provide a [single debug port](#autopilot-debug-ports) that exposes both the [SWD Interface](#debug-signals) and [System Console](system_console).
|
||||
|
||||
There are several debug probes that are tested and supported for connecting to one or both of these interfaces:
|
||||
|
||||
- [SEGGER J-Link](../debug/probe_jlink.md): commercial probe, no built-in serial console, requires adapter.
|
||||
- [Black Magic Probe](../debug/probe_bmp.md): integrated GDB server and serial console, requires adapter.
|
||||
- [STLink](../debug/probe_stlink): best value, integrated serial console, adapter must be soldered.
|
||||
- [MCU-Link](../debug/probe_mculink): best value, integrated serial console, requires adapter.
|
||||
|
||||
An adapter to connect to the debug port may come with your flight controller or debug probe.
|
||||
Other options are given below.
|
||||
|
||||
## Debug Adapters
|
||||
|
||||
### Holybro Pixhawk Debug Adapter
|
||||
|
||||
The [Holybro Pixhawk Debug Adapter](https://holybro.com/products/pixhawk-debug-adapter) is _highly recommended_ when debugging controllers that use one of the Pixhawk-standard debug connectors.
|
||||
|
||||
It is the easiest way to connect:
|
||||
|
||||
- Flight controllers that use either the [Pixhawk Debug Full](#pixhawk-debug-full) (10-pin SH) or [Pixhawk Debug Mini](#pixhawk-debug-mini) (6-pin SH) debug port.
|
||||
- SWD debug probes that support the 10-pin ARM compatible interface standard used by the [Segger JLink EDU mini](../debug/probe_jlink.md) or 20-pin compatible with the Segger JLink or STLink.
|
||||
|
||||
|
||||
|
||||
### CUAV C-ADB Pixhawk Debug Adapter
|
||||
|
||||
The [CUAV C-ADB Secondary Development Pixhawk Flight Controller Debug Adapter](https://store.cuav.net/shop/cuav-c-adb/) comes with an [STLinkv3-MINIE Debug Probe](../debug/probe_stlink.md).
|
||||
|
||||
This has a ports for connecting to the [Pixhawk Debug Full](#pixhawk-debug-full) (10-pin SH) and CUAV-standard DSU interface (but not the [Pixhawk Debug Mini](../debug/swd_debug.md#pixhawk-debug-mini) (6-pin SH)).
|
||||
|
||||
The M2 connector on the adaptor is 14-pin CN4 STDC14 (see the [STLinkv3-MINIE User Manual](https://www.st.com/resource/en/user_manual/um2910-stlinkv3minie-debuggerprogrammer-tiny-probe-for-stm32-microcontrollers-stmicroelectronics.pdf) for more information).
|
||||
The cable used to connect the M2 and the STLinkv3-MINIE comes with the adaptor.
|
||||
|
||||
|
||||
|
||||
### Debug Probe Adapters
|
||||
|
||||
Some SWD [debug probes](#debug-probes) come with adapters/cables for connecting to common Pixhawk [debug ports](#debug-ports).
|
||||
Probes that are known to come with connectors are listed below:
|
||||
|
||||
- [DroneCode Probe](../debug/probe_bmp.md#dronecode-probe): comes with a connector for attaching to the [Pixhawk Debug Mini](#pixhawk-debug-mini)
|
||||
|
||||
### Board-specific Adapters
|
||||
|
||||
Some manufacturers provide cables to make it easy to connect the SWD interface and [System Console](../debug/system_console).
|
||||
|
||||
- [CUAV V5nano](../flight_controller/cuav_v5_nano.md#debug_port) and [CUAV V5+](../flight_controller/cuav_v5_plus.md#debug-port) include this debug cable:
|
||||
|
||||
|
||||
|
||||
### Custom Cables
|
||||
|
||||
You can also create custom cables for connecting to different boards or probes:
|
||||
|
||||
- Connect `SWDIO`, `SWCLK` and `GND` pins on the debug probe to the corresponding pins on the debug port.
|
||||
- Connect the VREF pin, if supported by the debug probe.
|
||||
- Connect the remaining pins, if present.
|
||||
|
||||
See the [STLinkv3-MINIE](probe_stlink) for a guide on how to solder a custom cable.
|
||||
|
||||
:::tip
|
||||
Where possible, we highly recommend that you create or obtain an adapter board rather than custom cables for connecting to SWD/JTAG debuggers and computers.
|
||||
This reduces the risk or poor wiring contributing to debugging problems, and has the benefit that adapters usually provide a common interface for connecting to multiple popular flight controller boards.
|
||||
:::
|
||||
|
||||
<!-- Reference links used above -->
|
||||
|
||||
[swd]: https://developer.arm.com/documentation/ihi0031/a/The-Serial-Wire-Debug-Port--SW-DP-
|
||||
[itm]: https://developer.arm.com/documentation/ddi0403/d/Appendices/Debug-ITM-and-DWT-Packet-Protocol?lang=en
|
||||
[etm]: https://developer.arm.com/documentation/ihi0064/latest/
|
||||
[bm06b-ghs-tbt(lf)(sn)(n)]: https://www.digikey.com/products/en?keywords=455-1582-1-ND
|
||||
[sm06b-ghs-tbt(lf)(sn)(n)]: https://www.digikey.com/products/en?keywords=455-1568-1-ND
|
||||
@@ -0,0 +1,81 @@
|
||||
# PX4 系统控制台
|
||||
|
||||
The PX4 _System Console_ provides low-level access to the system, debug output and analysis of the system boot process.
|
||||
|
||||
:::tip
|
||||
The console should be used for debugging if the system won't boot.
|
||||
The [MAVLink Shell](../debug/mavlink_shell.md) may otherwise be more suitable, as it is much easier to set up and can be used for [many of the same tasks](../debug/consoles.md#console_vs_shell).
|
||||
:::
|
||||
|
||||
## System Console vs. Shells
|
||||
|
||||
The console is made available through a (board-specific) UART that can be connected to a computer USB port using a [3.3V FTDI](https://www.digikey.com/en/products/detail/TTL-232R-3V3/768-1015-ND/1836393) cable.
|
||||
This allows the console to be accessed using a terminal application.
|
||||
|
||||
Pixhawk controller manufacturers are expected to expose the console UART and SWD (JTAG) debug interfaces through a dedicated _debug port_ that complies with the [Pixhawk Connector Standard](#pixhawk_debug_port).
|
||||
Unfortunately some boards predate this standard or a non-compliant.
|
||||
|
||||
:::info
|
||||
Developers targeting a number of different boards may wish to use a [debug adapter](../debug/swd_debug.md#debug-adapters) to simplify connecting boards to FTDI cables and [debug probes](../debug/swd_debug.md#debug-probes-for-px4-hardware).
|
||||
:::
|
||||
|
||||
Connect the 6-pos JST SH 1:1 cable to the Dronecode probe or connect the individual pins of the cable to a FTDI cable like this:
|
||||
|
||||
### Connecting via Dronecode Probe
|
||||
|
||||
The System Console UART pinouts/debug ports are typically documented in [autopilot overview pages](../flight_controller/index.md) (some are linked below):
|
||||
|
||||
- [3DR Pixhawk v1 Flight Controller](../flight_controller/pixhawk.md#console-port) (also applies to
|
||||
[mRo Pixhawk](../flight_controller/mro_pixhawk.md#debug-ports), [Holybro pix32](../flight_controller/holybro_pix32.md#debug-port))
|
||||
- [Pixhawk 3](../flight_controller/pixhawk3_pro.md#debug-port)
|
||||
- [Pixracer](../flight_controller/pixracer.md#debug-port)
|
||||
|
||||
<a id="pixhawk_debug_port"></a>
|
||||
|
||||
### Connecting via FTDI 3.3V Cable
|
||||
|
||||
Pixhawk flight controllers usually come with a [Pixhawk Connector Standard Debug Port](../debug/swd_debug.md#pixhawk-connector-standard-debug-ports) which will be either the 10 pin [Pixhawk Debug Full](../debug/swd_debug.md#pixhawk-debug-full) or 6 pin [Pixhawk Debug Mini](../debug/swd_debug.md#pixhawk-debug-mini) port.
|
||||
|
||||
These ports have pins for console TX and RX which can connect to an FTDI cable.
|
||||
The mapping for the [Pixhawk Debug Mini](../debug/swd_debug.md#pixhawk-debug-mini) to FTDI is shown below.
|
||||
|
||||
| Connecting via FTDI 3.3V Cable | - | FTDI | - |
|
||||
| ---------------------------------------------- | ---------------------------- | ---- | -------------------------------- |
|
||||
| 1（红） | + 5v (红色) | | N/C |
|
||||
| 2 | UART7 Tx | 5 | FTDI RX （黄色） |
|
||||
| 3 | UART7 Rx | 4 | FTDI TX （橙色） |
|
||||
| 4（黑） | SWDIO | | N/C |
|
||||
| 6 | SWCLK | | N/C |
|
||||
| 6 | GND | 1 | FTDI GND (黑色) |
|
||||
|
||||
The [SWD Debug Port](../debug/swd_debug.md) page and individual flight controller pages have more information about debug port pinouts.
|
||||
|
||||
## 打开控制台
|
||||
|
||||
After the console connection is wired up, use the default serial port tool of your choice or the defaults described below:
|
||||
|
||||
### Linux / Mac OS: Screen
|
||||
|
||||
下载 <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html">PuTTY</a> 并启动它。
|
||||
|
||||
```sh
|
||||
sudo apt-get install screen
|
||||
```
|
||||
|
||||
- 串口：pixhawk v1/pixracer 使用 57600 波特率
|
||||
|
||||
Connect screen at BAUDRATE baud, 8 data bits, 1 stop bit to the right serial port (use `ls /dev/tty*` and watch what changes when unplugging / replugging the USB device). Common names are `/dev/ttyUSB0` and `/dev/ttyACM0` for Linux and `/dev/tty.usbserial-ABCBD` for Mac OS.
|
||||
|
||||
```sh
|
||||
screen /dev/ttyXXX BAUDRATE 8N1
|
||||
```
|
||||
|
||||
### Windows: PuTTY
|
||||
|
||||
Download [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) and start it.
|
||||
|
||||
Then select 'serial connection' and set the port parameters to:
|
||||
|
||||
- 57600 波特率
|
||||
- 8 数据位
|
||||
- 1 个停止位
|
||||
@@ -0,0 +1,185 @@
|
||||
# 全系统回放
|
||||
|
||||
It is possible to record and replay arbitrary parts of the system based on ORB messages.
|
||||
|
||||
Replay is useful to test the effect of different parameter values based on real data, compare different estimators, etc.
|
||||
|
||||
## 系统必备组件
|
||||
|
||||
The first step is to identify the module or modules that should be replayed.
|
||||
Then, identify all the inputs to these modules, i.e. subscribed ORB topics.
|
||||
For system-wide replay, this consists of all hardware input: sensors, RC input, MAVLink commands and file system.
|
||||
|
||||
All identified topics need to be logged at full rate (see [logging](../dev_log/logging.md)).
|
||||
For `ekf2` this is already the case with the default set of logged topics.
|
||||
|
||||
It is important that all replayed topics contain only a single absolute timestamp, which is the automatically generated field `timestamp`.
|
||||
Should there be more timestamps, they must be relative to the main timestamp.
|
||||
For an example, see [SensorCombined.msg](https://github.com/PX4/PX4-Autopilot/blob/main/msg/SensorCombined.msg).
|
||||
造成这种情况的原因如下。
|
||||
|
||||
## 用法
|
||||
|
||||
- First, choose the file to replay and build the target (from within the PX4-Autopilot directory):
|
||||
|
||||
```sh
|
||||
export replay=<absolute_path_to_log_file.ulg>
|
||||
make px4_sitl_default
|
||||
```
|
||||
|
||||
This will create the build/make output in a separate build directory `build/px4_sitl_default_replay` (so that the parameters don't interfere with normal builds).
|
||||
It's possible to choose any posix SITL build target for replay, since the build system knows through the `replay` environment variable that it's in replay mode.
|
||||
|
||||
- Add ORB publisher rules in the file `build/px4_sitl_default_replay/rootfs/orb_publisher.rules`.
|
||||
This file defines the modules that are allowed to publish particular messages.
|
||||
It has the following format:
|
||||
|
||||
```sh
|
||||
restrict_topics: <topic1>, <topic2>, ..., <topicN>
|
||||
module: <module>
|
||||
ignore_others: <true/false>
|
||||
```
|
||||
|
||||
This means that the given list of topics should only be published by `<module>` (which is the command name).
|
||||
Publications to any of these topics from another module are silently ignored.
|
||||
If `ignore_others` is `true`, publications to other topics from `<module>` are ignored.
|
||||
|
||||
For replay, we only want the `replay` module to be able to publish the previously identified list of topics.
|
||||
So, for replaying `ekf2`, the rules file should look like this:
|
||||
|
||||
```sh
|
||||
restrict_topics: sensor_combined, vehicle_gps_position, vehicle_land_detected
|
||||
module: replay
|
||||
ignore_others: true
|
||||
```
|
||||
|
||||
With this, the modules that usually publish these topics don't need to be disabled for the replay.
|
||||
|
||||
- _(Optional)_ Setup parameter overrides (see [instructions below](#overriding-parameters-in-the-original-log)).
|
||||
|
||||
- _(Optional)_ Copy a `dataman` mission file from the SD card to the build directory.
|
||||
This is only necessary if a mission should be replayed.
|
||||
|
||||
- Start the replay:
|
||||
|
||||
```sh
|
||||
make px4_sitl_default jmavsim
|
||||
```
|
||||
|
||||
This will automatically open the log file, apply the parameters and start the replay.
|
||||
Once done, it will report the outcome and exit.
|
||||
The newly generated log file can then be analyzed. It can be found in `rootfs/fs/microsd/log`, in subdirectories organised by date.
|
||||
Replayed log file names will have the `_replayed` suffix.
|
||||
|
||||
Note that the above command will show the simulator as well, but - depending on what is being replayed - it will not show what's actually going on.
|
||||
It is still possible to connect via QGC and, for example, view the changing attitude during replay.
|
||||
|
||||
- Finally, unset the environment variable, so that the normal build targets are used again:
|
||||
|
||||
```sh
|
||||
unset replay
|
||||
```
|
||||
|
||||
### Overriding Parameters in the Original Log
|
||||
|
||||
By default, all parameters from the original log file are applied during a replay.
|
||||
If a parameter changes during recording, it will be changed at the right time during the replay.
|
||||
|
||||
Parameters can be overridden during a replay in two ways: _fixed_ and _dynamic_.
|
||||
When parameters are overridden, corresponding parameter changes in the log are not applied during replay.
|
||||
|
||||
- **Fixed parameter overrides** will override parameters from the start of the replay.
|
||||
They are defined in the file `build/px4_sitl_default_replay/rootfs/replay_params.txt`, where each line should have the format `<param_name> <value>`.
|
||||
例如：
|
||||
|
||||
```sh
|
||||
EKF2_RNG_NOISE 0.1
|
||||
```
|
||||
|
||||
- **Dynamic parameter overrides** will update parameter values at specified times.
|
||||
These parameters will still be initialised to the values in the log or in the fixed overrides.
|
||||
Parameter update events should be defined in `build/px4_sitl_default_replay/rootfs/replay_params_dynamic.txt`, where each line has the format `<param_name> <value> <timestamp>`.
|
||||
The timestamp is the time in seconds from the start of the log. 例如：
|
||||
|
||||
```sh
|
||||
EKF2_RNG_NOISE 0.15 23.4
|
||||
EKF2_RNG_NOISE 0.05 56.7
|
||||
EKF2_RNG_DELAY 4.5 30.0
|
||||
```
|
||||
|
||||
### 重要提示
|
||||
|
||||
- 在重播过程中，将报告日志文件中的所有退出。
|
||||
These have a negative effect on the replay, so care should be taken to avoid dropouts during recording.
|
||||
- It is currently only possible to replay in 'real-time': as fast as the recording was done.
|
||||
这项工作计划今后延长。
|
||||
- A message that has a timestamp of 0 will be considered invalid and not be replayed.
|
||||
|
||||
## EKF2 回放
|
||||
|
||||
This is a specialization of the system-wide replay for fast EKF2 replay. It will automatically create the ORB publisher rules and works as following:
|
||||
|
||||
:::info
|
||||
The recording and replay of flight logs with [multiple EKF2 instances](../advanced_config/tuning_the_ecl_ekf.md#running-multiple-ekf-instances) is not supported.
|
||||
To enable recording for EKF replay you must set the parameters to enable a [single EKF2 instance](../advanced_config/tuning_the_ecl_ekf.md#running-a-single-ekf-instance).
|
||||
:::
|
||||
|
||||
In EKF2 mode, the replay will automatically create the ORB publisher rules described above.
|
||||
|
||||
To perform an EKF2 replay:
|
||||
|
||||
- Record the original log.
|
||||
Optionally set `SDLOG_MODE` to `1` to log from boot.
|
||||
|
||||
- In addition to the `replay` environment variable, set `replay_mode` to `ekf2`:
|
||||
|
||||
```sh
|
||||
export replay_mode=ekf2
|
||||
export replay=<absolute_path_to_log.ulg>
|
||||
```
|
||||
|
||||
- Run the replay with the `none` target:
|
||||
|
||||
```sh
|
||||
make px4_sitl none
|
||||
```
|
||||
|
||||
- Once finished, unset both `replay` and `replay_mode`.
|
||||
|
||||
```sh
|
||||
unset replay; unset replay_mode
|
||||
```
|
||||
|
||||
### Adjusting EKF2-specific Parameters for the Replay
|
||||
|
||||
First install `pyulog`:
|
||||
|
||||
```sh
|
||||
pip install --user pyulog
|
||||
```
|
||||
|
||||
Extract the original log's parameters to `replay_params.txt`:
|
||||
|
||||
```sh
|
||||
ulog_params -i "$replay" -d ' ' | grep -e '^EKF2' > build/px4_sitl_default_replay/rootfs/replay_params.txt
|
||||
```
|
||||
|
||||
Adjust these as desired, and add dynamic parameter overrides in `replay_params_dynamic.txt` if necessary.
|
||||
|
||||
## 后台
|
||||
|
||||
回放分为3个组件:
|
||||
|
||||
- A replay module
|
||||
These have a negative effect on replay, so care should be taken to avoid dropouts during recording.
|
||||
- It is currently only possible to replay in 'real-time': as fast as the recording was done.
|
||||
|
||||
The replay module reads the log and publishes the messages at the same speed as they were recorded.
|
||||
将常量偏移量添加到每条消息的时间戳中，以匹配当前系统时间（这就是为什么所有其他时间戳都需要是相对的原因）。
|
||||
The command `replay tryapplyparams` is executed before all other modules are loaded and applies the parameters from the log and user-set parameters.
|
||||
Then as the last command, `replay trystart` will again apply the parameters and start the actual replay.
|
||||
Both commands do nothing if the environment variable `replay` is not set.
|
||||
|
||||
The ORB publisher rules allow to select which part of the system is replayed, as described above. They are only compiled for the posix SITL targets. 只编译 posix SITL 目标。
|
||||
|
||||
The **time handling** is still an **open point**, and needs to be implemented.
|
||||
Reference in New Issue
Block a user