fly316/PX4-Autopilot
7
0
Fork 0
mirror of https://gitee.com/mirrors_PX4/PX4-Autopilot.git synced 2026-10-16 13:13:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Move PX4 Guide source into /docs (#24490)

Browse Source 
* 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
2025-03-13 16:08:27 +11:00
committed by GitHub
co-authored by Ramon Roche
parent 8e6d2ebe4a
commit 88d623bedb
5176 changed files with 558771 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh/dev_setup/building_px4.md
+401
View File
@@ -0,0 +1,401 @@
# 构建 PX4 软件
无论对于模拟器还是硬件目标设备，PX4固件可以在控制台或者IDE中从源码构建
You need to build PX4 in order to use [simulators](../simulation/index.md), or if you want to modify PX4 and create a custom build.
如果您只想在实际硬件上试试 PX4，那么可以使用 QGroundControl[烧录预构建的二进制文件](../config/firmware.md)(无需跟着下面的指导)。
:::info
在跟着这些指导之前，你必须先为主机操作系统和目标硬件安装 [开发者工具链](../dev_setup/dev_env.md)。
如果您在跟着这些步骤操作后有任何问题，请参阅下面的 [Troubleshooting](#troubleshooting)。
:::
## 下载 PX4 源代码
PX4 源代码存储在 Github 上的 [PX4/PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) 仓库中。
如果要在您的计算机上获得 _最新的_（main分支）版本，请在终端中输入以下命令：
```sh
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
```
Note that you may already have done this when installing the [Developer Toolchain](../dev_setup/dev_env.md)
:::info
This is all you need to do in order to get the latest code.
If needed you can also [get the source code specific to a particular release](../contribute/git_examples.md#get-a-specific-release).
[GIT Examples](../contribute/git_examples.md) provides a lot more information working with releases and contributing to PX4.
:::
## 初次构建（使用模拟器）
首先我们要用控制台环境来构建一个模拟器目标
这使我们能够在转移到真正的硬件和 IDE 之前验证系统设置。
切换到 **PX4-Autopilot** 目录。
Depending on your operating system you will have installed either [Gazebo SITL](../sim_gazebo_gz/index.md) or [Gazebo Classic SITL](../sim_gazebo_classic/index.md) (if you don't know which you can try both).
:::: tabs
:::tab Gazebo
使用以下命令启动 [Gazebo SITL](../sim_gazebo_gz/index.md)：
```sh
make px4_sitl gz_x500
```
:::
:::tab Gazebo-Classic
使用以下命令启动 [Gazebo SITL](../sim_gazebo_gz/index.md)：
```sh
make px4_sitl gazebo-classic
```
:::
::::
这将显示 PX4 控制台：
![PX4 Console](../../assets/toolchain/console_gazebo.png)
:::info
You may need to start _QGroundControl_ before proceeding, as the default PX4 configuration requires a ground control connection before takeoff.
This can be [downloaded from here](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html).
:::
可以通过键入以下命令（如上方控制台中所示）来控制飞行器。
```sh
pxh> commander takeoff
```
该载具将起飞，您将在模拟器UI中看到：
:::: tabs
:::tab Gazebo
![Gazebo UI with vehicle taking off](../../assets/toolchain/gazebo_takeoff.png)
:::
:::tab Gazebo-Classic
![Gazebo Classic UI with vehicle taking off](../../assets/toolchain/gazebo_classic_takeoff.png)
:::
::::
The drone can be landed by typing `commander land` and the whole simulation can be stopped by doing **CTRL+C** (or by entering `shutdown`).
与地面站一起飞模拟器更接近飞机的实际运行。
在飞机飞行时（Takeoff飞行模式），单击地图上的某个位置并启用滑块。
这将重新定位飞机。
![QGroundControl GoTo](../../assets/toolchain/qgc_goto.jpg)
## 基于NuttX / Pixhawk 的飞控板
### 为NuttX构建
To build for NuttX- or Pixhawk- based boards, navigate into the **PX4-Autopilot** directory and then call `make` with the build target for your board.
For example, to build for [Pixhawk 4](../flight_controller/pixhawk4.md) hardware you could use the following command:
```sh
cd PX4-Autopilot
make px4_fmu-v5_default
```
运行成功后将输出类似结果：
```sh
-- Build files have been written to: /home/youruser/src/PX4-Autopilot/build/px4_fmu-v4_default
[954/954] Creating /home/youruser/src/PX4-Autopilot/build/px4_fmu-v4_default/px4_fmu-v4_default.px4
```
The first part of the build target `px4_fmu-v4` indicates the target flight controller hardware for the firmware.
The suffix, in this case `_default`, indicates a firmware _configuration_, such as supporting or omitting particular features.
:::info
The `_default` suffix is optional.
For example, `make px4_fmu-v5` and `px4_fmu-v5_default` result in the same firmware.
:::
The following list shows the build commands for the [Pixhawk standard](../flight_controller/autopilot_pixhawk_standard.md) boards:
- [Holybro Pixhawk 6X-RT (FMUv6X)](../flight_controller/pixhawk6x-rt.md): `make px4_fmu-v6xrt_default`
- [Holybro Pixhawk 6X (FMUv6X)](../flight_controller/pixhawk6x.md): `make px4_fmu-v6x_default`
- [Holybro Pixhawk 6C (FMUv6C)](../flight_controller/pixhawk6c.md): `make px4_fmu-v6c_default`
- [Holybro Pixhawk 6C Mini (FMUv6C)](../flight_controller/pixhawk6c_mini.md): `make px4_fmu-v6c_default`
- [Holybro Pix32 v6 (FMUv6C)](../flight_controller/holybro_pix32_v6.md): `make px4_fmu-v6c_default`
- [Holybro Pixhawk 5X (FMUv5X)](../flight_controller/pixhawk5x.md): `make px4_fmu-v5x_default`
- [Pixhawk 4 (FMUv5)](../flight_controller/pixhawk4.md): `make px4_fmu-v5_default`
- [Pixhawk 4 Mini (FMUv5)](../flight_controller/pixhawk4_mini.md): `make px4_fmu-v5_default`
- [CUAV V5+ (FMUv5)](../flight_controller/cuav_v5_plus.md): `make px4_fmu-v5_default`
- [CUAV V5 nano (FMUv5)](../flight_controller/cuav_v5_nano.md): `make px4_fmu-v5_default`
- [Pixracer (FMUv4)](../flight_controller/pixracer.md): `make px4_fmu-v4_default`
- [Pixhawk 3 Pro](../flight_controller/pixhawk3_pro.md): `make px4_fmu-v4pro_default`
- [Pixhawk Mini](../flight_controller/pixhawk_mini.md): `make px4_fmu-v3_default`
- [Pixhawk 2 (Cube Black) (FMUv3)](../flight_controller/pixhawk-2.md): `make px4_fmu-v3_default`
- [mRo Pixhawk (FMUv3)](../flight_controller/mro_pixhawk.md): `make px4_fmu-v3_default` (supports 2MB Flash)
- [Holybro pix32 (FMUv2)](../flight_controller/holybro_pix32.md): `make px4_fmu-v2_default`
- [Pixfalcon (FMUv2)](../flight_controller/pixfalcon.md): `make px4_fmu-v2_default`
- [Dropix (FMUv2)](../flight_controller/dropix.md): `make px4_fmu-v2_default`
- [Pixhawk 1 (FMUv2)](../flight_controller/pixhawk.md): `make px4_fmu-v2_default`
:::warning
You **must** use a supported version of GCC to build this board (e.g. the same as used by [CI/docker](../test_and_ci/docker.md)) or remove modules from the build. Building with an unsupported GCC may fail, as PX4 is close to the board's 1MB flash limit.
:::
- Pixhawk 1 with 2 MB flash: `make px4_fmu-v3_default`
Build commands for non-Pixhawk NuttX fight controllers (and for all other-boards) are provided in the documentation for the individual [flight controller boards](../flight_controller/index.md).
### 将固件烧录到飞控板
Append `upload` to the make commands to upload the compiled binary to the autopilot hardware via USB.
例如
```sh
make px4_fmu-v4_default upload
```
运行成功后将有以下输出：
```sh
Erase : [====================] 100.0%
Program: [====================] 100.0%
Verify : [====================] 100.0%
Rebooting.
[100%] Built target upload
```
:::tip
This is not supported when developing on WSL2.
See [ Windows Development Environment (WSL2-Based) > Flash a Control Board](../dev_setup/dev_env_windows_wsl.md#flash-a-flight-control-board).
:::
## 其他飞控板
Build commands for other boards are given the [board-specific flight controller pages](../flight_controller/index.md) (usually under a heading _Building Firmware_).
您还可以使用以下命令列出所有配置目标：
```sh
make list_config_targets
```
## 用图形界面 IDE 编译
[VSCode](../dev_setup/vscode.md) is the officially supported (and recommended) IDE for PX4 development.
It is easy to set up and can be used to compile PX4 for both simulation and hardware environments.
## 故障处理
### 常规构建错误
许多构建问题是由不匹配的子模块或未完全清理的构建环境引起的。
Updating the submodules and doing a `distclean` can fix these kinds of errors:
```sh
git submodule update --recursive
make distclean
```
### 闪存溢出了 XXX 字节
The `region 'flash' overflowed by XXXX bytes` error indicates that the firmware is too large for the target hardware platform.
This is common for `make px4_fmu-v2_default` builds, where the flash size is limited to 1MB.
If you're building the _vanilla_ master branch, the most likely cause is using an unsupported version of GCC.
In this case, install the version specified in the [Developer Toolchain](../dev_setup/dev_env.md) instructions.
如果在构建自己的分支，您可能已将固件大小增加到超过1MB的限制。
在这种情况下，您需要从构建中删除您不需要的任何驱动程序/模块。
### macOS：打开文件过多错误
MacOS 默认允许在所有正在运行的进程中最多打开256个文件。
PX4构建系统打开大量文件，因此您可能会超出此数量。
The build toolchain will then report `Too many open files` for many files, as shown below:
```sh
/usr/local/Cellar/gcc-arm-none-eabi/20171218/bin/../lib/gcc/arm-none-eabi/7.2.1/../../../../arm-none-eabi/bin/ld: cannot find NuttX/nuttx/fs/libfs.a: Too many open files
```
解决方案是增加允许打开文件的最大数量（例如增加到300）。
You can do this in the macOS _Terminal_ for each session:
- Run this script [Tools/mac_set_ulimit.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/mac_set_ulimit.sh), or
- 运行这个命令:
```sh
ulimit -S -n 300
```
### macOS Catalina：运行cmake时出现问题
As of macOS Catalina 10.15.1 there may be problems when trying to build the simulator with _cmake_.
如果您在这个平台上遇到构建问题，请尝试在终端中运行以下命令：
```sh
xcode-select --install
sudo ln -s /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/* /usr/local/include/
```
### Ubuntu 18.04：涉及arm_none_eabi_gcc的编译错误
Build issues related to `arm_none_eabi_gcc`may be due to a broken g++ toolchain installation.
您可以通过检查缺少的依赖项来验证这一点：
```sh
arm-none-eabi-gcc --version
arm-none-eabi-g++ --version
arm-none-eabi-gdb --version
arm-none-eabi-size --version
```
缺少依赖项的 bash 输出示例：
```sh
arm-none-eabi-gdb --version
arm-none-eabi-gdb: command not found
```
This can be resolved by removing and [reinstalling the compiler](https://askubuntu.com/questions/1243252/how-to-install-arm-none-eabi-gdb-on-ubuntu-20-04-lts-focal-fossa).
### Ubuntu 18.04：Visual Studio Code 无法监视此大型工作区中的文件更改
See [Visual Studio Code IDE (VSCode) > Troubleshooting](../dev_setup/vscode.md#troubleshooting).
### 导入Python软件包失败
"Failed to import" errors when running the `make px4_sitl jmavsim` command indicates that some Python packages are not installed (where expected).
```sh
Failed to import jinja2: No module named 'jinja2'
您可能需要使用以下方式进行安装:
pip3 install --user jinja2
```
如果您已经安装了这些依赖关系，这可能是因为计算机上存在多个 Python 版本（例如 Python 2.7.16 和 Python 3.8.3），并且该模块不存在于构建工具链使用的版本中。
您应该能够按照所示明确安装依赖项来解决此问题。
```sh
pip3 install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging
```
## PX4 创建生成目标
The previous sections showed how you can call _make_ to build a number of different targets, start simulators, use IDEs etc.
This section shows how _make_ options are constructed and how to find the available choices.
The full syntax to call _make_ with a particular configuration and initialization file is:
```sh
make [VENDOR_][MODEL][_VARIANT] [VIEWER_MODEL_DEBUGGER_WORLD]
```
**VENDOR_MODEL_VARIANT**: (also known as `CONFIGURATION_TARGET`)
- **VENDOR:** The manufacturer of the board: `px4`, `aerotenna`, `airmind`, `atlflight`, `auav`, `beaglebone`, `intel`, `nxp`, etc.
The vendor name for Pixhawk series boards is `px4`.
- **MODEL:** The _board model_ "model": `sitl`, `fmu-v2`, `fmu-v3`, `fmu-v4`, `fmu-v5`, `navio2`, etc.
- **VARIANT:** Indicates particular configurations: e.g. `bootloader`, `cyphal`, which contain components that are not present in the `default` configuration.
Most commonly this is `default`, and may be omitted.
:::tip
You can get a list of _all_ available `CONFIGURATION_TARGET` options using the command below:
```sh
make list_config_targets
```
:::
**VIEWER_MODEL_DEBUGGER_WORLD:**
- **VIEWER:** This is the simulator ("viewer") to launch and connect: `gz`, `gazebo`, `jmavsim`, `none` <!-- , ?airsim -->
:::tip
`none` can be used if you want to launch PX4 and wait for a simulator (jmavsim, Gazebo, Gazebo Classic, or some other simulator).
For example, `make px4_sitl none_iris` launches PX4 without a simulator (but with the iris airframe).
:::
- **MODEL:** The _vehicle_ model to use (e.g. `iris` (_default_), `rover`, `tailsitter`, etc), which will be loaded by the simulator.
The environment variable `PX4_SIM_MODEL` will be set to the selected model, which is then used in the [startup script](../simulation/index.md#startup-scripts) to select appropriate parameters.
- **DEBUGGER:** Debugger to use: `none` (_default_), `ide`, `gdb`, `lldb`, `ddd`, `valgrind`, `callgrind`.
For more information see [Simulation Debugging](../debug/simulation_debugging.md).
- **WORLD:** (Gazebo Classic only).
Set the world ([PX4-Autopilot/Tools/simulation/gazebo-classic/sitl_gazebo-classic/worlds](https://github.com/PX4/PX4-SITL_gazebo-classic/tree/main/worlds)) that is loaded.
Default is [empty.world](https://github.com/PX4/PX4-SITL_gazebo-classic/blob/main/worlds/empty.world).
For more information see [Gazebo Classic > Loading a Specific World](../sim_gazebo_classic/index.md#loading-a-specific-world).
:::tip
You can get a list of _all_ available `VIEWER_MODEL_DEBUGGER_WORLD` options using the command below:
```sh
make px4_sitl list_vmd_make_targets
```
:::
::: info
- Most of the values in the `CONFIGURATION_TARGET` and `VIEWER_MODEL_DEBUGGER` have defaults, and are hence optional.
For example, `gazebo-classic` is equivalent to `gazebo-classic_iris` or `gazebo-classic_iris_none`.
- 如果要在其他两个设置之间指定默认值，可以使用三个下划线。
For example, `gazebo-classic___gdb` is equivalent to `gazebo-classic_iris_gdb`.
- You can use a `none` value for `VIEWER_MODEL_DEBUGGER` to start PX4 and wait for a simulator.
For example start PX4 using `make px4_sitl_default none` and jMAVSim using `./Tools/simulation/jmavsim/jmavsim_run.sh -l`.
:::
The `VENDOR_MODEL_VARIANT` options map to particular _px4board_ configuration files in the PX4 source tree under the [/boards](https://github.com/PX4/PX4-Autopilot/tree/main/boards) directory.
Specifically `VENDOR_MODEL_VARIANT` maps to a configuration file **boards/VENDOR/MODEL/VARIANT.px4board**
(e.g. `px4_fmu-v5_default` corresponds to [boards/px4/fmu-v5/default.px4board](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v5/default.px4board)).
其他 make 目标在相关章节中讨论：
- `bloaty_compare_master`: [Binary Size Profiling](../debug/binary_size_profiling.md)
- ...
## Firmware Version & Git Tags
The _PX4 Firmware Version_ and _Custom Firmware Version_ are published using the MAVLink [AUTOPILOT_VERSION](https://mavlink.io/en/messages/common.html#AUTOPILOT_VERSION) message, and displayed in the _QGroundControl_ **Setup > Summary** airframe panel:
![Firmware info](../../assets/gcs/qgc_setup_summary_airframe_firmware.jpg)
These are extracted at build time from the active _git tag_ for your repo tree.
The git tag should be formatted as `<PX4-version>-<vendor-version>` (e.g. the tag in the image above was set to `v1.8.1-2.22.1`).
:::warning
If you use a different git tag format, versions information may not be displayed properly.
:::
docs/zh/dev_setup/config_initial.md
+58
View File
@@ -0,0 +1,58 @@
# Initial Setup & Configuration
我们建议开发者们获取下文描述的基本配置的硬件设备（或者相似的设备）并使用"默认" <a href="../airframes/airframe_reference.md">机架</a> 构型。
## 基本设备
:::tip
PX4 can be used with a much wider range of equipment than described here, but new developers will benefit from going with one of the standard setups.
A Taranis RC and a mid-range Android tablet make a very inexpensive field kit.
:::
飞机配置流程：
- **RC controller** for the safety pilot
- [Taranis Plus](https://www.frsky-rc.com/product/taranis-x9d-plus-2/) RC control (or equivalent)
- **Development computer**
::: info
The listed computers have acceptable performance, but a more recent and powerful computer is recommended.
:::
- Lenovo Thinkpad with i5-core running Windows 11
- MacBook Pro (early 2015 and later) with macOS 10.15 or later
- Lenovo Thinkpad i5 with Ubuntu Linux 20.04 or later
- **Ground control station** (computer or tablet):
- iPad (may require Wifi telemetry adapter)
- 任意 MacBook 或者 Ubuntu Linux 笔记本电脑（可使用开发用计算机兼任）
- A recent mid-range Android tablet or phone with a large enough screen to run _QGroundControl_ effectively (6 inches).
- **Vehicle capable of running PX4**:
- [Get a prebuilt vehicle](../complete_vehicles_mc/index.md)
- [Build your own](../frames_multicopter/kits.md)
- **Safety glasses**
- **Tether** (multicopter only - for more risky tests)
## 飞机配置
Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md) for a **desktop OS**.
To configure the vehicle:
1. [Install PX4 firmware](../config/firmware.md#installing-px4-main-beta-or-custom-firmware) (including "custom" firmware with your own changes).
2. [Start with the airframe](../config/airframe.md) that best-matches your vehicle from the [airframe reference](../airframes/airframe_reference.md).
3. [Basic Configuration](../config/index.md) explains how to perform basic configuration.
4. [Parameter Configuration](../advanced_config/parameters.md) explains how you can find and modify individual parameters.
::: info
- _QGroundControl_ mobile variants do not support vehicle configuration.
- The _daily build_ includes development tools and new features that are not available in the official release.
- Configuration in the airframe reference have been flown on real vehicles, and are a good starting point for "getting off the ground".
:::
docs/zh/dev_setup/dev_env.md
+30
View File
@@ -0,0 +1,30 @@
# 安装文件和代码
The _supported platforms_ for PX4 development are:
- [Ubuntu Linux (22.04/20.04/18.04)](../dev_setup/dev_env_linux_ubuntu.md) — Recommended
- [Windows (10/11)](../dev_setup/dev_env_windows_wsl.md) — via WSL2
- [Mac OS](../dev_setup/dev_env_mac.md)
## 支持的编译目标
下表显示了您可以在每个操作系统上构建何种 PX平台的固件编译。
| 平台 | Linux (Ubuntu) | Mac | Windows |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------: | :-------------------------: | :-------------------------: |
| **NuttX based hardware:** [Pixhawk Series](../flight_controller/pixhawk_series.md), [Crazyflie](../complete_vehicles_mc/crazyflie2.md) | &check; | &check; | &check; |
| **Linux-based hardware:** [Raspberry Pi 2/3](../flight_controller/raspberry_pi_navio2.md) | &check; | | |
| **Simulation:** [Gazebo SITL](../sim_gazebo_gz/index.md) | &check; | &check; | &check; |
| **Simulation:** [Gazebo Classic SITL](../sim_gazebo_classic/index.md) | &check; | &check; | &check; |
| **Simulation:** [ROS with Gazebo Classic](../simulation/ros_interface.md) | &check; | | &check; |
| **Simulation:** ROS 2 with Gazebo | &check; | | &check; |
Experienced Docker users can also build with the containers used by our continuous integration system: [Docker Containers](../test_and_ci/docker.md)
## Gazebo dependencies
如果你对 Docker 比较熟悉的话你也可以使用预先构建好的容器作为开发环境：<a href="../test_and_ci/docker.md">Docker 容器</a>。
- Install [VSCode](../dev_setup/vscode.md) (if you prefer using an IDE to the command line).
- Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md)
- Continue to [Building PX4 Software](../dev_setup/building_px4.md).
docs/zh/dev_setup/dev_env_advanced_linux.md
+36
View File
@@ -0,0 +1,36 @@
# 高级 Linux 安装用例
## 使用 JTAG 编程调试器
Linux 用户需要为 JTAG 调试器接入 USB 总线开放权限。
:::info
For Archlinux: replace the group plugdev with uucp in the following commands
:::
Run a simple `ls` in `sudo` mode to ensure the commands below succeed:
```sh
sudo ls
```
Then with `sudo` rights temporarily granted, run this command:
```sh
cat > $HOME/rule.tmp <<_EOF
# All 3D Robotics (includes PX4) devices
SUBSYSTEM=="usb", ATTR{idVendor}=="26AC", GROUP="plugdev"
# FTDI (and Black Magic Probe) Devices
SUBSYSTEM=="usb", ATTR{idVendor}=="0483", GROUP="plugdev"
# Olimex Devices
SUBSYSTEM=="usb", ATTR{idVendor}=="15ba", GROUP="plugdev"
_EOF
sudo mv $HOME/rule.tmp /etc/udev/rules.d/10-px4.rules
sudo /etc/init.d/udev restart
```
The user needs to be added to the group **plugdev**:
```sh
sudo usermod -a -G plugdev $USER
```
docs/zh/dev_setup/dev_env_linux.md
+1
View File
@@ -0,0 +1 @@
<Redirect to="dev_env_linux_ubuntu" />
docs/zh/dev_setup/dev_env_linux_arch.md
+50
View File
@@ -0,0 +1,50 @@
# ArchLinux 上的开发环境
:::warning
This development environment is [community supported and maintained](../advanced/community_supported_dev_env).
It may or may not work with current versions of PX4.
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
The PX4-Autopilot repository provides a convenient script to set your Arch installation up for PX4 development: [Tools/setup/arch.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/arch.sh). <!-- NEED px4_version -->
The script installs (by default) all tools to build PX4 for NuttX targets and run simulation with [JMAVSim](../sim_jmavsim/index.md).
You can additionally install the [Gazebo Classic](../sim_gazebo_classic/index.md) simulator by specifying the command line argument: `--gazebo`.
![Gazebo on Arch](../../assets/simulation/gazebo_classic/arch-gazebo.png)
:::info
The instructions have been tested on [Manjaro](https://manjaro.org/) (Arch based distribution) as it is much easier to set up than Arch Linux.
:::
To get and run the scripts, do either of:
- [Download PX4 Source Code](../dev_setup/building_px4.md) and run the scripts in place:
```sh
git clone https://github.com/PX4/PX4-Autopilot.git
bash PX4-Autopilot/Tools/setup/arch.sh
```
- 只下载你所需的脚本并运行他们：
```sh
wget https://raw.githubusercontent.com/PX4/PX4-Autopilot/main/Tools/setup/arch.sh
wget https://raw.githubusercontent.com/PX4/PX4-Autopilot/main/Tools/setup/requirements.txt
bash arch.sh
```
The script takes the following optional parameters:
- `--gazebo`: Add this parameter to install Gazebo from the [AUR](https://aur.archlinux.org/packages/gazebo/).
::: info
Gazebo gets compiled from source.
It takes some time to install and requires entering the `sudo` password multiple times (for dependencies).
:::
- `--no-nuttx`: Do not install the NuttX/Pixhawk toolchain (i.e. if only using simulation).
- `--no-sim-tools`: Do not install jMAVSim/Gazebo (i.e. if only targeting Pixhawk/NuttX targets)
docs/zh/dev_setup/dev_env_linux_centos.md
+99
View File
@@ -0,0 +1,99 @@
# CentOS 上的开发环境
:::warning
This development environment is [community supported and maintained](../advanced/community_supported_dev_env.md).
It may or may not work with current versions of PX4.
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
The build requires Python 2.7.5. Therefore as of this writing Centos 7 should be used.
(For earlier Centos releases a side-by-side install of python v2.7.5 may be done. But it is not recommended because it can break yum.)
## 通用依赖项
The EPEL repositories are required for openocd libftdi-devel libftdi-python
```sh
wget https://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-5.noarch.rpm
sudo yum install epel-release-7-5.noarch.rpm
yum update
yum groupinstall “Development Tools”
yum install python-setuptools python-numpy
easy_install pyserial
easy_install pexpect
easy_install toml
easy_install pyyaml
easy_install cerberus
yum install openocd libftdi-devel libftdi-python python-argparse flex bison-devel ncurses-devel ncurses-libs autoconf texinfo libtool zlib-devel cmake vim-common
```
:::info
You may want to also install `python-pip` and `screen`.
:::
## GCC 工具链安装
<!-- GCC toolchain documentation used for all Linux platforms to build NuttX -->
Execute the script below to install GCC 7-2017-q4:
:::warning
This version of GCC is out of date.
At time of writing the current version on Ubuntu is `9-2020-q2-update` (see [focal nuttx docker file](https://github.com/PX4/PX4-containers/blob/master/docker/Dockerfile_nuttx-focal#L28))
:::
```sh
pushd .
cd ~
wget https://armkeil.blob.core.windows.net/developer/Files/downloads/gnu-rm/7-2017q4/gcc-arm-none-eabi-7-2017-q4-major-linux.tar.bz2
tar -jxf gcc-arm-none-eabi-7-2017-q4-major-linux.tar.bz2
exportline="export PATH=$HOME/gcc-arm-none-eabi-7-2017-q4-major/bin:\$PATH"
if grep -Fxq "$exportline" ~/.profile; then echo nothing to do ; else echo $exportline >> ~/.profile; fi
popd
```
Now restart your machine.
**Troubleshooting**
Check the version by entering the following command:
```sh
arm-none-eabi-gcc --version
```
The output should be something similar to:
```sh
arm-none-eabi-gcc (GNU Tools for Arm Embedded Processors 7-2017-q4-major) 7.2.1 20170904 (release) [ARM/embedded-7-branch revision 255204]
Copyright (C) 2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```
<!-- import docs ninja build system -->
## Ninja Build System
[Ninja](https://ninja-build.org/) is a faster build system than _Make_ and the PX4 _CMake_ generators support it.
On Ubuntu Linux you can install this automatically from normal repos.
```sh
sudo apt-get install ninja-build -y
```
Other systems may not include Ninja in the package manager.
In this case an alternative is to download the binary and add it to your path:
```sh
mkdir -p $HOME/ninja
cd $HOME/ninja
wget https://github.com/martine/ninja/releases/download/v1.6.0/ninja-linux.zip
unzip ninja-linux.zip
rm ninja-linux.zip
exportline="export PATH=$HOME/ninja:\$PATH"
if grep -Fxq "$exportline" ~/.profile; then echo nothing to do ; else echo $exportline >> ~/.profile; fi
. ~/.profile
```
docs/zh/dev_setup/dev_env_linux_ubuntu.md
+123
View File
@@ -0,0 +1,123 @@
# Ubuntu LTS/Debian Linux 的开发环境
The following instructions use a bash script to set up the PX4 development environment on the [Ubuntu Linux LTS](https://wiki.ubuntu.com/LTS) versions supported by PX4: Ubuntu 22.04 (Jammy Jellyfish), 20.04 (Focal Fossa), and 18.04 (Bionic Beaver).
The environment includes:
- [Gazebo Simulator](../sim_gazebo_gz/index.md) ("Harmonic") on Ubuntu 22.04
- [Gazebo Classic Simulator](../sim_gazebo_classic/index.md) on Ubuntu 20.04 and Ubuntu 18.04
- [Build toolchain for Pixhawk (and other NuttX-based hardware)](../dev_setup/building_px4.md#nuttx-pixhawk-based-boards).
:::info
The build toolchain for other flight controllers, simulators, and working with ROS are discussed in the [Other Targets](#other-targets) section below.
:::
:::tip
if you need to use Gazebo on Ubuntu 20.04 you can [manually install Gazebo "Garden"](../sim_gazebo_gz/index.md#installation-ubuntu-linux), with the caveat that this is end-of-life in November 2024.
If you want to use Gazebo Classic on Ubuntu 22.04 (say) then you can manually install it by following the instructions in [Gazebo Classic > Installation](../sim_gazebo_classic/index.md#installation).
:::
## Simulation and NuttX (Pixhawk) Targets
Use the [ubuntu.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/ubuntu.sh) script to set up a development environment that allows you to build for simulators and/or the [NuttX/Pixhawk](../dev_setup/building_px4.md#nuttx-pixhawk-based-boards) toolchain.
:::tip
The script is intended to be run on _clean_ Ubuntu LTS installations, and may not work if run "on top" of an existing system, or on a different Ubuntu release.
:::
To install the toolchain:
1. [Download PX4 Source Code](../dev_setup/building_px4.md):
```sh
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
```
::: info
The environment setup scripts in the source usually work for recent PX4 releases.
If working with an older version of PX4 you may need to [get the source code specific to your release](../contribute/git_examples.md#get-a-specific-release).
:::
2. Run the **ubuntu.sh** with no arguments (in a bash shell) to install everything:
```sh
bash ./PX4-Autopilot/Tools/setup/ubuntu.sh
```
- 在安装过程中确认并通过所有的提示。
- You can use the `--no-nuttx` and `--no-sim-tools` options to omit the NuttX and/or simulation tools.
3. 完成后重新启动计算机。
:::details
Additional notes
These notes are provided "for information only":
- This setup is supported by the PX4 Dev Team.
The instructions may also work on other Debian Linux based systems.
- You can verify the NuttX installation by confirming the `gcc` version as shown:
```sh
$arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Arm Embedded Toolchain 9-2020-q2-update) 9.3.1 20200408 (release)
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```
- You're going to need the PX4 source code anyway.
But if you just wanted to set up the development environment without getting all the source code you could instead just download [ubuntu.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/ubuntu.sh) and [requirements.txt](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/requirements.txt) and then run **ubuntu.sh**:
```sh
wget https://raw.githubusercontent.com/PX4/PX4-Autopilot/main/Tools/setup/ubuntu.sh
wget https://raw.githubusercontent.com/PX4/PX4-Autopilot/main/Tools/setup/requirements.txt
bash ubuntu.sh
```
:::
## 一键安装脚本
This video shows how to install the toolchain for NuttX and simulation targets ([as covered below](#simulation-and-nuttx-pixhawk-targets)) along with the basic testing covered in [Building PX4 Software](../dev_setup/building_px4.md).
:::warning
The video suggests that you build source using JMAVSim, entering the command: `make px4_sitl jmavsim`.
As JMAVSim is now community-supported, you should instead build using Gazebo or Gazebo Classic, as shown in [Building the Code](../dev_setup/building_px4.md#first-build-using-a-simulator)
:::
<lite-youtube videoid="OtValQdAdrU" title=" Setting up your PX4 development environment on Linux"/>
## Other Targets
The Ubuntu development environment for ROS, other simulators, and other hardware targets, is covered in their respective documentation.
A subset of the relevant topics are linked below.
通用依赖
- [Raspberry Pi 2/3 Navio2 Autopilot > PX4 Development Environment](../flight_controller/raspberry_pi_navio2.md#px4-development-environment)
- [Raspberry Pi 2/3/4 PilotPi Shield](../flight_controller/raspberry_pi_pilotpi.md).
ROS
- ROS 2: [ROS 2 User Guide > Installation & Setup](../ros2/user_guide.md#installation-setup).
- ROS (1): [ROS (1) Installation Guide](../ros/mavros_installation.md)
## Gazebo dependencies
Once you have finished setting up the command-line toolchain:
- Install [VSCode](../dev_setup/vscode.md) (if you prefer using an IDE to the command line).
- Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md)
:::tip
The _daily build_ includes development tools that hidden in release builds.
It may also provide access to new PX4 features that are not yet supported in release builds.
:::
- Continue to the [build instructions](../dev_setup/building_px4.md).
docs/zh/dev_setup/dev_env_mac.md
+129
View File
@@ -0,0 +1,129 @@
# Mac 上的开发环境
MacOS 是受支持的 PX4 开发平台。
根据本文的指示构建的开发环境可以用编译：
- 基于 NuttX 的硬件 (Pixhawk等)
- [Gazebo Classic Simulation](../sim_gazebo_classic/index.md)
:::tip
This setup is supported by the PX4 dev team.
To build other targets you will need to use a [different OS](../dev_setup/dev_env.md#supported-targets) (or an [unsupported development environment](../advanced/community_supported_dev_env.md)).
:::
## 一键安装脚本
<lite-youtube videoid="tMbMGiMs1cQ" title="Setting up your PX4 development environment on macOS"/>
## Base Setup
The "base" macOS setup installs the tools needed for building firmware, and includes the common tools that will be needed for installing/using the simulators.
### Environment Setup
:::details
Apple Silicon Macbook users!
If you have an Apple M1, M2 etc. Macbook, make sure to run the terminal as x86 by setting up an x86 terminal:
1. Locate the Terminal application within the Utilities folder (**Finder > Go menu > Utilities**)
2. Select _Terminal.app_ and right-click on it, then choose **Duplicate**.
3. Rename the duplicated Terminal app, e.g. to _x86 Terminal_
4. Now select the renamed _x86 Terminal_ app and right-click and choose \*_Get Info_
5. Check the box for **Open using Rosetta**, then close the window
6. Run the _x86 Terminal_ as usual, which will fully support the current PX4 toolchain
:::
First set up the environment
1. Enable more open files by appending the following line to the `~/.zshenv` file (creating it if necessary):
```sh
echo ulimit -S -n 2048 >> ~/.zshenv
```
::: info
If you don't do this, the build toolchain may report the error: `"LD: too many open files"`
:::
2. Enforce Python 3 by appending the following lines to `~/.zshenv`
```sh
# Point pip3 to MacOS system python 3 pip
alias pip3=/usr/bin/pip3
```
### Common Tools
To setup the environment to be able to build for Pixhawk/NuttX hardware (and install the common tools for using simulators):
1. Install Homebrew by following these [installation instructions](https://brew.sh).
2. Run these commands in your shell to install the common tools:
```sh
brew tap PX4/px4
brew install px4-dev
```
3. Install the required Python packages:
```sh
# install required packages using pip3
python3 -m pip install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging kconfiglib future jsonschema
# if this fails with a permissions error, your Python install is in a system path - use this command instead:
sudo -H python3 -m pip install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging kconfiglib future jsonschema
```
## Gazebo Classic 模拟
To setup the environment for [Gazebo Classic](../sim_gazebo_classic/index.md) simulation:
1. Run the following commands in your shell:
```sh
brew unlink tbb
sed -i.bak '/disable! date:/s/^/ /; /disable! date:/s/./#/3' $(brew --prefix)/Library/Taps/homebrew/homebrew-core/Formula/tbb@2020.rb
brew install tbb@2020
brew link tbb@2020
```
::: info
September 2021: The commands above are a workaround to this bug: [PX4-Autopilot#17644](https://github.com/PX4/PX4-Autopilot/issues/17644).
They can be removed once it is fixed (along with this note).
:::
2. To install SITL simulation with Gazebo Classic:
```sh
brew install --cask temurin
brew install --cask xquartz
brew install px4-sim-gazebo
```
3. Run the macOS setup script: `PX4-Autopilot/Tools/setup/macos.sh`
The easiest way to do this is to clone the PX4 source, and then run the script from the directory, as shown:
```sh
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot/Tools/setup
sh macos.sh
```
## Gazebo dependencies
Once you have finished setting up the command-line toolchain:
- Install [VSCode](../dev_setup/vscode.md) (if you prefer using an IDE to the command line).
- Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md)
:::tip
The _daily build_ includes development tools that are hidden in release builds.
It may also provide access to new PX4 features that are not yet supported in release builds.
:::
- Continue to the [build instructions](../dev_setup/building_px4.md).
docs/zh/dev_setup/dev_env_windows.md
+1
View File
@@ -0,0 +1 @@
<Redirect to="dev_env_windows_wsl" />
docs/zh/dev_setup/dev_env_windows_cygwin.md
+154
View File
@@ -0,0 +1,154 @@
# Windows Development Environment (Cygwin-based)
:::warning
This development environment is [community supported and maintained](../advanced/community_supported_dev_env.md).
It may or may not work with current versions of PX4.
The toolchain was previously recommended, but does not work with PX4 v1.12 and later due to packaging issues.
The [Windows WSL2-Based Development Environment](../dev_setup/dev_env_windows_wsl.md) should be used by preference.
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
该工具链非常轻便，而且容易安装和使用。
根据本文的指示构建的开发环境可以用编译：
- 基于 NuttX 的硬件 (Pixhawk等)
- [jMAVSim Simulation](../sim_jmavsim/index.md)
<a id="installation"></a>
## 安装说明
1. Download the latest version of the ready-to-use MSI installer from: [Github releases](https://github.com/PX4/windows-toolchain/releases) or [Amazon S3](https://s3-us-west-2.amazonaws.com/px4-tools/PX4+Windows+Cygwin+Toolchain/PX4+Windows+Cygwin+Toolchain+0.9.msi) (fast download).
2. Run it, choose your desired installation location, let it install:
![jMAVSimOnWindows](../../assets/toolchain/cygwin_toolchain_installer.png)
3. Tick the box at the end of the installation to _clone the PX4 repository, build and run simulation with jMAVSim_ (this simplifies the process to get you started).
::: info
If you missed this step you will need to [clone the PX4-Autopilot repository manually](#getting-started).
:::
:::warning
At time of writing the installer is missing some dependencies (and cannot yet be rebuilt to add them - see [PX4-windows-toolchain#31](https://github.com/PX4/PX4-windows-toolchain/issues/31)).
To add these yourself:
1. 进入到工具链的安装目录(默认<strong x-id="1">C:\PX4</strong>)
2. Run **run-console.bat** (double click) to start the linux-like Cygwin bash console
3. Enter the following command in the console:
```sh
pip3 install --user kconfiglib jsonschema future
```
:::
## 入门指南
The toolchain uses a specially configured console window (started by running the **run-console.bat** script) from which you can call the normal PX4 build commands:
1. 进入到工具链的安装目录(默认<strong x-id="1">C:\PX4</strong>)
2. Run **run-console.bat** (double click) to start the linux-like Cygwin bash console (you must use this console to build PX4).
3. Clone the PX4 PX4-Autopilot repository from within the console:
::: info
Skip this step if you ticked the installer option to _clone the PX4 repository, build and run simulation with jMAVSim_.
Cloning only needs to be done once!
:::
```sh
# Clone the PX4-Autopilot repository into the home folder & loads submodules in parallel
git clone --recursive -j8 https://github.com/PX4/PX4-Autopilot.git
```
You can now use the console/PX4-Autopilot repository to build PX4.
4. For example, to run JMAVSim:
```sh
# Navigate to PX4-Autopilot repo
cd Firmware
# Build and runs SITL simulation with jMAVSim to test the setup
make px4_sitl jmavsim
```
The console will then display:
![jMAVSimOnWindows](../../assets/simulation/jmavsim/jmavsim_windows_cygwin.png)
## Gazebo dependencies
Once you have finished setting up the command-line toolchain:
- Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md)
- Continue to the [build instructions](../dev_setup/building_px4.md).
## 故障处理
### Windows &amp; Git 特殊情况
Antivirus and other background file monitoring tools can significantly slow down both installation of the toolchain and PX4 build times.
You may wish to halt them temporarily during builds (at your own risk).
### Windows & Git Special Cases
#### Windows CR+LF 对比 Unix LF 行结尾
We recommend that you force Unix style LF endings for every repository you're working with using this toolchain (and use an editor which preserves them when saving your changes - e.g. Eclipse or VS Code).
Compilation of source files also works with CR+LF endings checked out locally, but there are cases in Cygwin (e.g. execution of shell scripts) that require Unix line endings (otherwise you get errors like `$'\r': Command not found.`).
Luckily git can do this for you when you execute the two commands in the root directory of your repo:
```sh
git config core.autocrlf false
git config core.eol lf
```
If you work with this toolchain on multiple repositories you can also set these two configurations globally for your machine:
```sh
git config --global ...
```
This is not recommended because it may affect any other (unrelated) git use on your Windows machine.
#### Unix 执行权限
Under Unix there's a flag in the permissions of each file that tells the OS whether or not the file is allowed to be executed.
_git_ under Cygwin supports and cares about that bit (even though the Windows NTFS file system does not use it).
This often results in _git_ finding "false-positive" differences in permissions.
The resulting diff might look like this:
```sh
diff --git ...
old mode 100644
new mode 100755
```
We recommend globally disabling the permission check on Windows to avoid the problem:
```sh
git config --global core.fileMode false # disable execution bit check globally for the machine
```
For existing repositories that have this problem caused by a local configuration, additionally:
```sh
# remove the local option for this repository to apply the global one
git config --unset core.filemode
# remove the local option for all submodules
git submodule foreach --recursive git config --unset core.filemode
```
<!--
Instructions for building/updating this toolchain are covered in [Windows Cygwin Development Environment (Maintenance Instructions)](../dev_setup/dev_env_windows_cygwin_packager_setup.md)
-->
docs/zh/dev_setup/dev_env_windows_cygwin_packager_setup.md
+167
View File
@@ -0,0 +1,167 @@
# Windows Cygwin Development Environment (Maintenance Instructions)
:::warning
This development environment is [community supported and maintained](../advanced/community_supported_dev_env.md).
It may or may not work with current versions of PX4.
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
This topic explains how to construct and extend the development environment used for the no-longer-supported [Cygwin-based Windows Development Environment](../dev_setup/dev_env_windows_cygwin.md).
## 附加信息
### Features / Issues
The following features are known to work (version 2.0):
- Building and running SITL with jMAVSim with significantly better performance than a VM (it generates a native windows binary **px4.exe**).
- Building and uploading NuttX builds (e.g.: px4_fmu-v2 and px4_fmu-v4)
- Style check with _astyle_ (supports the command: `make format`)
- Command line auto completion
- Non-invasive installer! The installer does NOT affect your system and global path (it only modifies the selected installation directory e.g. \*\*C:\PX4\*\* and uses a temporary local path).
- The installer supports updating to a new version keeping your personal changes inside the toolchain folder
Omissions:
- Simulation: Gazebo and ROS are not supported.
- Only NuttX and JMAVSim/SITL builds are supported.
- [Known problems](https://github.com/orgs/PX4/projects/6) (Also use to report issues).
### Shell Script Installation
You can also install the environment using shell scripts in the Github project.
1. Make sure you have [Git for Windows](https://git-scm.com/download/win) installed.
2. Clone the repository https://github.com/PX4/windows-toolchain to the location you want to install the toolchain. Default location and naming is achieved by opening the `Git Bash` and executing:
```sh
cd /c/
git clone https://github.com/PX4/windows-toolchain PX4
```
3. If you want to install all components navigate to the freshly cloned folder and double click on the script `install-all-components.bat` located in the folder `toolchain`. If you only need certain components and want to safe Internet traffic and or disk space you can navigate to the different component folders like e.g. `toolchain\cygwin64` and click on the **install-XXX.bat** scripts to only fetch something specific.
4. Continue with [Getting Started](../dev_setup/dev_env_windows_cygwin.md#getting-started).
### Manual Installation (for Toolchain Developers)
This section describes how to setup the Cygwin toolchain manually yourself while pointing to the corresponding scripts from the script based installation repo.
The result should be the same as using the scripts or MSI installer.
:::info
The toolchain gets maintained and hence these instructions might not cover every detail of all the future changes.
:::
1. Create the _folders_: \*\*C:\PX4\*\*, \*\*C:\PX4\toolchain\*\* and \*\*C:\PX4\home\*\*
2. Download the _Cygwin installer_ file [setup-x86_64.exe](https://cygwin.com/setup-x86_64.exe) from the [official Cygwin website](https://cygwin.com/install.html)
3. Run the downloaded setup file
4. In the wizard choose to install into the folder: \*\*C:\PX4\toolchain\cygwin64\*\*
5. Select to install the default Cygwin base and the newest available version of the following additional packages:
- **Category:Packagename**
- Devel:cmake (3.3.2 gives no deprecated warnings, 3.6.2 works but has the warnings)
- Devel:gcc-g++
- Devel:gdb
- Devel:git
- Devel:make
- Devel:ninja
- Devel:patch
- Editors:xxd
- Editors:nano (unless you're the vim pro)
- Python:python2
- Python:python2-pip
- Python:python2-numpy
- Python:python2-jinja2
- Python:python2-pyyaml
- Python:python2-cerberus
- Archive:unzip
- Utils:astyle
- Shells:bash-completion
- Web:wget
::: info
Do not select as many packages as possible which are not on this list, there are some which conflict and break the builds.
:::
::: info
That's what [cygwin64/install-cygwin-px4.bat](https://github.com/MaEtUgR/PX4Toolchain/blob/master/toolchain/cygwin64/install-cygwin-px4.bat) does.
:::
6. Write up or copy the **batch scripts** [`run-console.bat`](https://github.com/MaEtUgR/PX4Toolchain/blob/master/run-console.bat) and [`setup-environment.bat`](https://github.com/PX4/windows-toolchain/blob/master/toolchain/scripts/setup-environment.bat).
The reason to start all the development tools through the prepared batch script is they preconfigure the starting program to use the local, portable Cygwin environment inside the toolchain's folder.
This is done by always first calling the script [**setup-environment.bat**](https://github.com/PX4/windows-toolchain/blob/master/toolchain/scripts/setup-environment.bat) and the desired application like the console after that.
The script [setup-environment.bat](https://github.com/PX4/windows-toolchain/blob/master/toolchain/scripts/setup-environment.bat) locally sets environmental variables for the workspace root directory `PX4_DIR`, all binary locations `PATH`, and the home directory of the unix environment `HOME`.
7. Add necessary **python packages** to your setup by opening the Cygwin toolchain console (double clicking **run-console.bat**) and executing
```sh
pip2 install toml
pip2 install pyserial
pip2 install pyulog
```
::: info
That's what [cygwin64/install-cygwin-python-packages.bat](https://github.com/MaEtUgR/PX4Toolchain/blob/master/toolchain/cygwin64/install-cygwin-python-packages.bat) does.
:::
8. Download the [**ARM GCC compiler**](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) as zip archive of the binaries for Windows and unpack the content to the folder `C:\PX4\toolchain\gcc-arm`.
::: info
This is what the toolchain does in: [gcc-arm/install-gcc-arm.bat](https://github.com/MaEtUgR/PX4Toolchain/blob/master/toolchain/gcc-arm/install-gcc-arm.bat).
:::
9. Install the JDK:
- Download Java 14 from [Oracle](https://www.oracle.com/java/technologies/javase-jdk14-downloads.html) or [AdoptOpenJDK](https://adoptopenjdk.net/).
- Because sadly there is no portable archive containing the binaries directly you have to install it.
- Find the binaries and move/copy them to **C:\PX4\toolchain\jdk**.
- You can uninstall the Kit from your Windows system again, we only needed the binaries for the toolchain.
::: info
This is what the toolchain does in: [jdk/install-jdk.bat](https://github.com/MaEtUgR/PX4Toolchain/blob/master/toolchain/jdk/install-jdk.bat).
:::
10. Download [**Apache Ant**](https://ant.apache.org/bindownload.cgi) as zip archive of the binaries for Windows and unpack the content to the folder `C:\PX4\toolchain\apache-ant`.
:::tip
Make sure you don't have an additional folder layer from the folder which is inside the downloaded archive.
:::
::: info
This is what the toolchain does in: [apache-ant/install-apache-ant.bat](https://github.com/MaEtUgR/PX4Toolchain/blob/master/toolchain/apache-ant/install-apache-ant.bat).
:::
11. Download, build and add _genromfs_ to the path:
- Clone the source code to the folder **C:\PX4\toolchain\genromfs\genromfs-src** with
```sh
cd /c/toolchain/genromfs
git clone https://github.com/chexum/genromfs.git genromfs-src
```
- Compile it with:
```sh
cd genromfs-src
make all
```
- Copy the resulting binary **genromfs.exe** one folder level out to: **C:\PX4\toolchain\genromfs**
12. Make sure all the binary folders of all the installed components are correctly listed in the `PATH` variable configured by [**setup-environment.bat**](https://github.com/PX4/windows-toolchain/blob/master/toolchain/scripts/setup-environment.bat).
docs/zh/dev_setup/dev_env_windows_vm.md
+124
View File
@@ -0,0 +1,124 @@
# Windows 虚拟机托管的工具链
:::warning
This development environment is [community supported and maintained](../advanced/community_supported_dev_env.md).
It may or may not work with current versions of PX4.
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
Windows developers can run the PX4 toolchain in a virtual machine (VM) with Linux as the guest operating system.
After setting up the virtual machine, the installation and setup of PX4 within the VM is exactly the same as on a native Linux computer.
While using a VM is a very easy way to set up and test an environment for building firmware, users should be aware:
1. 固件的编译速度比原生 Linux 要更慢一些。
2. The JMAVSim simulation, frame rate be much slower than on native Linux.
虚拟机运行资源不足可能导致特定情况下无人机坠毁。
3. 可以安装 Gazebo 和 ROS，但运行速度非常慢。
:::tip
Allocate as many CPU cores and memory resources to the VM as possible.
:::
There are multiple ways to setup a VM which is capable of executing the PX4 environment on your system.
This guide walks you through a VMWare setup.
There is also an incomplete section for VirtualBox at the end (we'd welcome expansion of this section from a community member).
## VMWare Setup
VMWare performance is acceptable for basic usage (building Firmware) but not for running ROS or Gazebo Classic.
1. Download [VMWare Player Freeware](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html)
2. 将其安装在 Windows 系统上。
3. Download the desired version of [Ubuntu Desktop ISO Image](https://www.ubuntu.com/download/desktop).
(see [Linux Instructions Page](../dev_setup/dev_env_linux.md) for recommended Ubuntu version).
4. Open _VMWare Player_.
5. Enable 3D acceleration in the VM's settings: **VM > Settings > Hardware > Display > Accelerate 3D graphics**
::: info
This option is required to properly run 3D simulation environments like jMAVSim and Gazebo Classic.
We recommend this is done before installing Linux in the virtual environment.
:::
6. Select the option to create a new virtual machine.
7. In the VM creation wizard choose the downloaded Ubuntu ISO image as your installation medium and will automatically detect the operating system you want to use.
8. Also in the wizard, select the resources you want to allocate to your virtual machine while it is running.
Allocate as much memory and as many CPU cores as you can without rendering your host Windows system unusable.
9. Run your new VM at the end of the wizard and let it install Ubuntu following the setup instructions.
Remember all settings are only for within your host operating system usage and hence you can disable any screen saver and local workstation security features which do not increase risk of a network attack.
10. Once the new VM is booted up make sure you install _VMWare tools drivers and tools extension_ inside your guest system.
This will enhance performance and usability of your VM usage:
- Significantly enhanced graphics performance
- Proper support for hardware device usage like USB port allocation (important for target upload), proper mouse wheel scrolling, sound support
- Guest display resolution adaption to the window size
- Clipboard sharing to host system
- File sharing to host system
11. Continue with [PX4 environment setup for Linux](../dev_setup/dev_env_linux.md)
## VirtualBox 7 Setup
The setup for VirtualBox is similar to VMWare.
Community members, we'd welcome a step-by-step guide here!
### USB passthrough for QGroundControl / Firmware Flashing
:::tip
This section has been tested for VirtualBox 7 running Ubuntu 20.04 LTS on a Windows 10 host machine.
:::
One limitation of virtual machines is that you can't automatically connect to a flight controller attached to the host computer USB port in order to [build and upload PX4 firmware from a terminal](../dev_setup/building_px4.md#uploading-firmware-flashing-the-board).
You also can't connect to the flight controller from QGroundControl in the virtual machine.
To allow this, you need to configure USB passthrough settings:
1. Ensure that the user has been added to the dialout group in the VM using the terminal command:
```sh
sudo usermod -a -G dialout $USER
```
Then restart Ubuntu in the virtual machine.
2. Enable serial port(s) in VM: **VirtualBox > Settings > Serial Ports 1/2/3/etc...**
3. Enable USB controller in VM: **VirtualBox > Settings > USB**
4. Add USB filters for the bootloader in VM: **VirtualBox > Settings > USB > Add new USB filter**.
- Open the menu and plug in the USB cable connected to your autopilot.
Select the `...Bootloader` device when it appears in the UI.
::: info
The bootloader device only appears for a few seconds after connecting USB.
If it disappears before you can select it, disconnect and then reconnect USB.
:::
- Select the `...Autopilot` device when it appears (this happens after the bootloader completes).
5. Select the device in the VM instance's dropdown menu **VirtualBox > Devices > your_device**
If successful, your device will show up with `lsusb` and QGroundControl will connect to the device automatically.
You should also be able to build and upload firmware using a command like:
```sh
make px4_fmu-v5_default upload
```
### Telemetry over WiFi for QGroundControl
If using _QGroundControl_ within a virtual machine you should set the VM networking settings to "Bridged Adapter" mode.
This gives the guest OS direct access to networking hardware on the host.
If you use the Network Address Translation (NAT), which is set by default for VirtualBox 7 running Ubuntu 20.04 LTS, this will block the outbound UDP packets that QGroundControl uses to communicate with the vehicle.
docs/zh/dev_setup/dev_env_windows_wsl.md
+352
View File
@@ -0,0 +1,352 @@
# Windows Development Environment (WSL2-Based)
The following instructions explain how to set up a PX4 development environment on Windows 10 or 11, running on Ubuntu Linux within [WSL2](https://docs.microsoft.com/en-us/windows/wsl/about).
根据本文的指示构建的开发环境可以用编译：
- [Pixhawk and other NuttX-based hardware](../dev_setup/building_px4.md#nuttx-pixhawk-based-boards)
- [Gazebo Simulation](../sim_gazebo_gz/index.md)
- [Gazebo-Classic Simulation](../sim_gazebo_classic/index.md)
:::tip
This setup is supported by the PX4 dev team.
The environment should in theory be able to build any target that can be built on Ubuntu.
The list above are those targets that are regularly tested.
:::
## 综述
The [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) ([WSL2](https://docs.microsoft.com/en-us/windows/wsl/compare-versions)) allows users to install and run the [Ubuntu Development Environment](../dev_setup/dev_env_linux_ubuntu.md) on Windows, _almost_ as though we were running it on a Linux computer.
With this environment developers can:
- Build any simulator or hardware target supported by [Ubuntu Development Environment](../dev_setup/dev_env_linux_ubuntu.md) in the WSL Shell.
(Ubuntu is the best supported and tested PX4 development platform).
- Debug code in [Visual Studio Code](dev_env_windows_wsl.md#visual-studio-code-integration) running on Windows.
- Monitor a _simulation_ using _QGroundControl for Linux_ running in WSL.
QGC for Linux connects automatically to the simulation.
_QGroundControl for Windows_ is additionally required if you need to:
- [Update firmware](#flash-a-flight-control-board) on a real vehicle.
- Monitor a real vehicle.
Note that you can also use it to monitor a simulation, but you must manually [connect to the simulation running in WSL](#qgroundcontrol-on-windows).
:::info
Connecting to a USB device from within WSL is not supported, so you can't update firmware using the [`upload`](../dev_setup/building_px4.md#uploading-firmware-flashing-the-board) option when building on the command line, or from _QGroundControl for Linux_.
:::
:::info
The approach is similar to installing PX4 in your _own_ virtual machine, as described in [Windows VM-Hosted Toolchain](../dev_setup/dev_env_windows_vm.md).
The benefit of WSL2 is that its virtual machine is deeply integrated into Windows, system-managed, and performance optimised.
:::
## 安装
### Install WSL2
To install WSL2 with Ubuntu on a new installation of Windows 10 or 11:
1. Make sure your computer your computer's virtualization feature is enabled in the BIOS.
It's usually referred as "Virtualization Technology", "Intel VT-x" or "AMD-V" respectively
2. Open _cmd.exe_ as administrator.
This can be done by pressing the start key, typing `cmd`, right-clicking on the _Command prompt_ entry and selecting **Run as administrator**.
3. Execute the following commands to install WSL2 and a particular Ubuntu version:
- Default version (Ubuntu 22.04):
```sh
wsl --install
```
- Ubuntu 20.04 ([Gazebo-Classic Simulation](../sim_gazebo_classic/index.md))
```sh
wsl --install -d Ubuntu-20.04
```
- Ubuntu 22.04 ([Gazebo Simulation](../sim_gazebo_gz/index.md))
```sh
wsl --install -d Ubuntu-22.04
```
::: info
You can also install[Ubuntu 20.04](https://www.microsoft.com/store/productId/9MTTCL66CPXJ) and [Ubuntu 22.04](https://www.microsoft.com/store/productId/9PN20MSR04DW) from the store, which allows you to delete the application using the normal Windows Add/Remove settings:
:::
4. WSL will prompt you for a user name and password for the Ubuntu installation.
Record these credentials as you will need them later on!
The command prompt is now a terminal within the newly installed Ubuntu environment.
### Opening a WSL Shell
All operations to install and build PX4 must be done within a WSL Shell (you can use the same shell that was used to install WSL2 or open a new one).
If you're using [Windows Terminal](https://learn.microsoft.com/en-us/windows/terminal/install) you can open a shell into an installed WSL environment as shown, and exit it by closing the tab.
![Windows Terminal showing how to select a Ubuntu shell](../../assets/toolchain/wsl_windows_terminal.png)
To open a WSL shell using a command prompt:
1. Open a command prompt:
- Press the Windows **Start** key.
- Type `cmd` and press **Enter** to open the prompt.
2. To start WSL and access the WSL shell, execute the command:
```sh
wsl -d <distribution_name>
```
例如：
```sh
wsl -d Ubuntu
```
```sh
wsl -d Ubuntu-20.04
```
If you only have one version of Ubuntu, you can just use `wsl`.
Enter the following commands to first close the WSL shell, and then shut down WSL:
```sh
exit
wsl -d <distribution_name> --shutdown
```
Alternatively, after entering `exit` you can just close the prompt.
### Install PX4 Toolchain
Next we download the PX4 source code within the WSL2 environment, and use the normal _Ubuntu installer script_ to set up the developer environment.
This will install the toolchain for Gazebo Classic simulation and Pixhawk/NuttX hardware.
To install the development toolchain:
1. [Open a WSL2 Shell](#opening-a-wsl-shell) (if it is still open you can use the same one that was used to install WSL2).
2. Execute the command `cd ~` to switch to the home folder of WSL for the next steps.
:::warning
This is important!
If you work from a location outside of the WSL file system you'll run into issues such as very slow execution and access right/permission errors.
:::
3. Download the PX4 source code using `git` (which is already installed in WSL2):
```sh
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
```
::: info
The environment setup scripts in the source usually work for recent PX4 releases.
If working with an older version of PX4 you may need to [get the source code specific to your release](../contribute/git_examples.md#get-a-specific-release).
:::
4. Run the **ubuntu.sh** installer script and acknowledge any prompts as the script progresses:
```sh
bash ./PX4-Autopilot/Tools/setup/ubuntu.sh
```
::: info
This installs tools to build PX4 for Pixhawk and either Gazebo or Gazebo Classic targets:
- You can use the `--no-nuttx` and `--no-sim-tools` options to omit the NuttX and/or simulation tools.
- Other Linux build targets are untested (you can try these by entering the appropriate commands in [Ubuntu Development Environment](../dev_setup/dev_env_linux_ubuntu.md) into the WSL shell).
:::
5. Restart the "WSL computer" after the script completes (exit the shell, shutdown WSL, and restart WSL):
```sh
exit
wsl --shutdown
wsl
```
6. Switch to the PX4 repository in the WSL home folder:
```sh
cd ~/PX4-Autopilot
```
7. Build the PX4 SITL target and test your environment:
```sh
make px4_sitl
```
For more build options see [Building PX4 Software](../dev_setup/building_px4.md).
## Visual Studio Code Integration
VS Code running on Windows is well integrated with WSL.
To set up the integration:
1. [Download](https://code.visualstudio.com/) and install Visual Studio Code (VS Code) on Windows,
2. Open _VS Code_.
3. Install the extension called [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) (marketplace)
4. [Open a WSL shell](#opening-a-wsl-shell)
5. In the WSL shell, switch to the PX4 folder:
```sh
cd ~/PX4-Autopilot
```
6. In the WSL shell, start VS Code:
```sh
code .
```
This will open the IDE fully integrated with the WSL shell.
Make sure you always open the PX4 repository in the Remote WSL mode.
7. Next time you want to develop WSL2 you can very easily open it again in Remote WSL mode by selecting **Open Recent** (as shown below).
This will start WSL for you.
![](../../assets/toolchain/vscode/vscode_wsl.png)
Note however that the IP address of the WSL virtual machine will have changed, so you won't be able to monitor simulation from QGC for Windows (you can still monitor using QGC for Linux)
## QGroundControl
You can run QGroundControl in either WSL or Windows to connect to the running simulation.
If you need to [flash a flight control board](#flash-a-flight-control-board) with new firmware you can only do this from the QGroundControl for Windows.
### QGroundControl in WSL
The easiest way to set up and use QGroundControl is to download the Linux version into your WSL.
You can do this from within the WSL shell.
1. In a web browser, navigate to the QGC [Ubuntu download section](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html#ubuntu)
2. Right-click on the **QGroundControl.AppImage** link, and select "Copy link address".
This will be something like _https://d176td9ibe4jno.cloudfront.net/builds/master/QGroundControl.AppImage_
3. [Open a WSL shell](#opening-a-wsl-shell) and enter the following commands to download the appimage and make it executable (replace the AppImage URL where indicated):
```sh
cd ~
wget <the_copied_AppImage_URL>
chmod +x QGroundControl.AppImage
```
4. Run QGroundControl:
```sh
./QGroundControl.AppImage
```
QGroundControl will launch and automatically connect to a running simulation and allow you to monitor and control your vehicle(s).
You will not be able to use it to install PX4 firmware because WSL does not allow access to serial devices.
### QGroundControl on Windows
Install [QGroundControl on Windows](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html#windows) if you want to be able to update hardware with firmware created within PX4.
These steps describe how you can connect to the simulation running in the WSL:
1. [Open a WSL shell](#opening-a-wsl-shell)
2. Check the IP address of the WSL virtual machine by running the command `ip addr | grep eth0`:
```sh
$ ip addr | grep eth0
6: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
inet 172.18.46.131/20 brd 172.18.47.255 scope global eth0
```
Copy the first part of the `eth0` interface `inet` address to the clipboard.
In this case: `172.18.46.131`.
3. In QGC go to **Q > Application Settings > Comm Links**
4. Add a UDP Link called "WSL" to port `18570` of the IP address copied above.
5. Save it and connect to it.
:::info
You will have to update the WSL comm link in QGC every time WSL restarts (because it gets a dynamic IP address).
:::
## Flash a Flight Control Board
Flashing a custom built PX4 binary has to be done using [QGroundControl for Windows](#qgroundcontrol-on-windows).
:::info
WSL2 does not natively offer direct access to serial/USB devices like Pixhawk flight controllers connected to your computer.
That means you can't connect QGC running inside WSL2 to a flight controller to install firmware, or use the `upload` command to [upload firmware as it is built](../dev_setup/building_px4.md#uploading-firmware-flashing-the-board).
Instead you connect [QGroundControl for Windows](#qgroundcontrol-on-windows) to PX4 running in WSL2 and to the Flight controller in order to upload the firmware.
:::
Do the following steps to flash your custom binary built in WSL:
1. If you haven't already built the binary in WSL e.g. with a [WSL shell](dev_env_windows_wsl.md#opening-a-wsl-shell) and by running:
```sh
cd ~/PX4-Autopilot
make px4_fmu-v5
```
::: tip
Use the correct `make` target for your board.
`px4_fmu-v5` can be used for a Pixhawk 4 board.
:::
2. Detach the USB cable of your Pixhawk board from the computer if it was connected.
3. Open QGC and navigate to **Q > Vehicle Setup > Firmware**.
4. Plug your Pixhawk board via USB
5. Once connected select "PX4 Flight Stack", check **Advanced settings** and choose _Custom firmware file ..._ from the drop down below.
6. Continue and select the firmware binary you just built in WSL.
In the open dialog look for the "Linux" location with the penguin icon in the left pane.
It's usually all the way at the bottom.
Choose the file in the path: `Ubuntu\home\{your WSL user name}\PX4-Autopilot\build\{your build target}\{your build target}.px4`
::: info
You can add the folder to the favourites to access it quickly next time.
:::
7. Start the flashing.
For more information see [Installing PX4 Main, Beta or Custom Firmware (Loading Firmware)](../config/firmware.md#installing-px4-main-beta-or-custom-firmware).
## 故障处理
If you have any problems with your setup, check the current [Microsoft WSL installation documentation](https://learn.microsoft.com/en-us/windows/wsl/install).
We also recommend that you have the latest Windows GPU drivers installed and also install a recent version of [kisak mesa](https://launchpad.net/~kisak/+archive/ubuntu/kisak-mesa) in your Ubuntu environment so that most OpenGL features get emulated:
```sh
sudo add-apt-repository ppa:kisak/kisak-mesa
sudo apt update
sudo apt upgrade
```
docs/zh/dev_setup/getting_started.md
+9
View File
@@ -0,0 +1,9 @@
# 入门指南
本节包含有关开始 PX4 开发的主题：
- [Initial Setup](../dev_setup/config_initial.md)
- [Toolchain Installation](../dev_setup/dev_env.md)
- [Building the Code](../dev_setup/building_px4.md)
- [Writing an Application](../modules/hello_sky.md)
- [Application/Module Template](../modules/module_template.md)
docs/zh/dev_setup/qgc_daily_build.md
+9
View File
@@ -0,0 +1,9 @@
# QGroundControl Daily Build
The QGroundControl _Daily Build_ includes development tools that are hidden in release builds, and provides access to new PX4 features that are not yet supported in release builds.
![QGroundControl](../../assets/toolchain/qgc_goto.jpg)
It should be used instead of the stable release when working with new code forked from the PX4 `main` branch.
- [Download daily builds](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/releases/daily_builds.html)
docs/zh/dev_setup/qtcreator.md
+59
View File
@@ -0,0 +1,59 @@
# Qt Creator IDE
:::warning
This development environment is [community supported and maintained](../advanced/community_supported_dev_env.md).
It may or may not work with current versions of PX4.
Qt Creator has been replaced by [VSCode](../dev_setup/vscode.md) as the officially supported (and recommended) IDE for PX4 development.
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
[Qt Creator](https://www.qt.io/download-open-source) is a popular cross-platform open-source IDE that can be used to compile and debug PX4.
## Qt Creator Functionality
Qt creator offers clickable symbols, auto-completion of the complete codebase and building and flashing firmware.
![Screenshot of Qt Creator](../../assets/toolchain/qtcreator.png)
The video below shows how it is used.
<lite-youtube videoid="Bkk8zttWxEI" title="(Qt Creator) PX4 Flight Stack Build Experience"/>
## IDE Setup
### Qt Creator on Linux
Before starting Qt Creator, the [project file](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/Generator-Specific-Information#codeblocks-generator) needs to be created:
```sh
cd ~/src/PX4-Autopilot
mkdir ../Firmware-build
cd ../Firmware-build
cmake ../PX4-Autopilot -G "CodeBlocks - Unix Makefiles"
```
Then load the CMakeLists.txt in the root PX4-Autopilot folder via **File > Open File or Project** (Select the CMakeLists.txt file).
After loading, the **play** button can be configured to run the project by selecting 'custom executable' in the run target configuration and entering 'make' as executable and 'upload' as argument.
### Qt Creator on Windows
:::info
Windows has not been tested for PX4 development with Qt Creator.
:::
### Qt Creator on Mac OS
Before starting Qt Creator, the [project file](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/Generator-Specific-Information#codeblocks-generator) needs to be created:
```sh
cd ~/src/PX4-Autopilot
mkdir -p build/creator
cd build/creator
cmake ../.. -G "CodeBlocks - Unix Makefiles"
```
设置完成！ Start _Qt Creator_ and then set up the project to build.
<!-- note, video here was removed/made private, and in any case out of date. Just hoping people can work it out -->
docs/zh/dev_setup/vscode.md
+141
View File
@@ -0,0 +1,141 @@
# Visual Studio Code IDE (VSCode)
[Visual Studio Code](https://code.visualstudio.com/) is a powerful cross-platform source code editor/IDE that can be used for PX4 development on Ubuntu, Windows, and macOS.
使用 VSCode 进行PX4 开发的原因：
- Getting setup _really_ only takes a few minutes.
- A rich extension ecosystem that enables a huge range of tools needed for PX4 development: C/C++ (with solid _cmake_ integration), _Python_, _Jinja2_, ROS messages, and even DroneCAN dsdl.
- 非常好的Github 集成功能
本主题解释了如何设置IDE并开始开发。
:::info
There are other powerful IDEs, but they typically take more effort to integrate with PX4.
With _VScode_, configuration is stored in the PX4/PX4-Autopilot tree ([PX4-Autopilot/.vscode](https://github.com/PX4/PX4-Autopilot/tree/main/.vscode)) so the setup process is as simple as adding the project folder.
:::
## 操作前提
You must already have installed the command line [PX4 developer environment](../dev_setup/dev_env.md) for your platform and downloaded the _Firmware_ source code repo.
## Installation & Setup
1. [Download and install VSCode](https://code.visualstudio.com/) (you will be offered the correct version for your OS).
2. Open VSCode and add the PX4 source code:
- Select _Open folder ..._ option on the welcome page (or using the menu: **File > Open Folder**):
![Open Folder](../../assets/toolchain/vscode/welcome_open_folder.jpg)
- A file selection dialog will appear.
Select the **PX4-Autopilot** directory and then press **OK**.
The project files and configuration will then load into _VSCode_.
3. Press **Install All** on the _This workspace has extension recommendations_ prompt (this will appear on the bottom right of the IDE).
![Install extensions](../../assets/toolchain/vscode/prompt_install_extensions.jpg)
VSCode will open the _Extensions_ panel on the left hand side so you can watch the progress of installation.
![PX4 loaded into VSCode Explorer](../../assets/toolchain/vscode/installing_extensions.jpg)
4. A number of notifications/prompts may appear in the bottom right corner
:::tip
If the prompts disappear, click the little "alarm" icon on the right of the bottom blue bar.
:::
- If prompted to install a new version of _cmake_:
- Say **No** (the right version is installed with the [PX4 developer environment](../dev_setup/dev_env.md)).
- If prompted to sign into _github.com_ and add your credentials:
- This is up to you! It provides a deep integration between Github and the IDE, which may simplify your workflow.
- Other prompts are optional, and may be installed if they seem useful. <!-- perhaps add screenshot of these prompts -->
<a id="building"></a>
## Building PX4
To build:
1. Select your build target ("cmake build config"):
- The current _cmake build target_ is shown on the blue _config_ bar at the bottom (if this is already your desired target, skip to next step).
![Select Cmake build target](../../assets/toolchain/vscode/cmake_build_config.jpg)
::: info
The cmake target you select affects the targets offered for when [building/debugging](#debugging) (i.e. for hardware debugging you must select a hardware target like `px4_fmu-v6`).
:::
- Click the target on the config bar to display other options, and select the one you want (this will replace any selected target).
- _Cmake_ will then configure your project (see notification in bottom right).
![Cmake config project](../../assets/toolchain/vscode/cmake_configuring_project.jpg)
- Wait until configuration completes.
When this is done the notification will disappear and you'll be shown the build location:
![Cmake config project](../../assets/toolchain/vscode/cmake_configuring_project_done.jpg).
2. You can then kick off a build from the config bar (select either **Build** or **Debug**).
![Run debug or build](../../assets/toolchain/vscode/run_debug_build.jpg)
After building at least once you can now use [code completion](#code completion) and other _VSCode_ features.
## 调试
<a id="debugging_sitl"></a>
### SITL Debugging
To debug PX4 on SITL:
1. Select the debug icon on the sidebar (marked in red) to display the debug panel.
![Run debug](../../assets/toolchain/vscode/vscode_debug.jpg)
2. Then choose your debug target (e.g. _Debug SITL (Gazebo Iris)_) from the top bar debug dropdown (purple box).
::: info
The debug targets that are offered (purple box) match your build target (yellow box on the bottom bar).
For example, to debug SITL targets, your build target must include SITL.
:::
3. Start debugging by clicking the debug "play" arrow (next to the debug target in the top bar - pink box).
While debugging you can set breakpoints, step over code, and otherwise develop as normal.
### Hardware Debugging
The instructions in [SWD Debug Port](../debug/swd_debug.md) explain how to connect to the SWD interface on common flight controllers (for example, using the Dronecode or Blackmagic probes).
After connecting to the SWD interface, hardware debugging in VSCode is then the same as for [SITL Debugging](#debugging_sitl) except that you select a debug target appropriate for your debugger type (and firmware) - e.g. `jlink (px4_fmu-v5)`.
:::tip
To see the `jlink` option you must have selected a [cmake target for building firmware](#building-px4).
:::
![Image showing hardware targets with options for the different probes](../../assets/toolchain/vscode/vscode_hardware_debugging_options.png)
<a id="code completion"></a>
## Code Completion
In order for the code completion to work (and other IntelliSense magic) you need an active configuration and to have [built the code](#building).
Once that is done you don't need to do anything else; the toolchain will automatically offer you symbols as you type.
![IntelliSense](../../assets/toolchain/vscode/vscode_intellisense.jpg)
## 故障处理
This section includes guidance on setup and build errors.
### Ubuntu 18.04: "Visual Studio Code is unable to watch for file changes in this large workspace"
This error surfaces on startup.
On some systems, there is an upper-limit of 8192 file handles imposed on applications, which means that VSCode might not be able to detect file modifications in `/PX4-Autopilot`.
You can increase this limit to avoid the error, at the expense of memory consumption.
Follow the [instructions here](https://code.visualstudio.com/docs/setup/linux#_visual-studio-code-is-unable-to-watch-for-file-changes-in-this-large-workspace-error-enospc).
A value of 65536 should be more than sufficient.