<a href="https://hackmd.io/@UnmannedVehicle/H1x6IIA31l">Catalogue</a>

---

> 提示：Gazebo、STIL、QGroundControl、PX4、Ardupilot

---

# 前言

**隨著無人機模擬與軟體在迴路（SITL）技術的快速發展，低成本、高效能的平台成為開發者測試與驗證的重要工具。本文將介紹如何在ubuntu 上運行 Gazebo Harmonic 與 SITL，並透過網路與 Windows 系統上的 QGroundControl 進行整合與控制，實現跨平台的模擬操作流程。本指南將涵蓋系統設定、軟體安裝、模擬啟動與遠端連線等步驟，協助開發者快速建立穩定的模擬環境，用於飛控開發、任務測試及教育訓練等多元應用。**

---

`提示：以下是本篇文章正文内容，下面案例可供参考`

# 一、設置含Gazebo Harmonic的Docker虛擬環境
- 建立含 Gazebo Harmonic 的 Dockerfile
🚩安裝docker：

sudo apt update  
sudo apt install -y docker.io  
sudo usermod -aG docker $USER
sudo usermod -aG docker $USER
newgrp docker

🚩建議使用 Ubuntu 22.04 (Jammy) 為基礎：
建立含 Gazebo Harmonic 的 Dockerfile
Dockerfile 範例：

FROM ubuntu:jammy  
  
# 安裝必要工具  
RUN apt-get update && apt-get install -y curl gnupg lsb-release wget software-properties-common \  
    && rm -rf /var/lib/apt/lists/*  
  
# 設定Gazebo Harmonic repository (正式Gazebo官方建議方式)  
RUN curl -sSL https://packages.osrfoundation.org/gazebo.key | \  
    gpg --dearmor -o /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg \  
    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] \  
      https://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" \  
    > /etc/apt/sources.list.d/gazebo-stable.list  
  
# 安裝 Gazebo Harmonic  
RUN apt-get update && apt-get install -y \  
    gz-harmonic \  
    libgz-sim8-dev \  
    libgz-transport13-dev \  
    libgz-sensors8-dev \  
    libgz-msgs10-dev \  
    libgz-plugin2-dev \  
    libgz-utils3-dev \  
    libgz-gui8-dev \  
    gz-tools \  
    libgl1-mesa-glx \  
    libqt5gui5 \  
    libxcb-xinerama0 \  
    libxcb-render-util0 \  
    && apt-get clean \  
    && rm -rf /var/lib/apt/lists/*  
  
# 設定環境變數（視需要）  
ENV LANG C.UTF-8  
ENV LC_ALL C.UTF-8  
  
# 設定預設工作目錄（可選）  
WORKDIR /root

🚩建立 Docker 映像檔 (Image)

docker build --no-cache -t gazebo-harmonic:latest .

🚩Docker 啟動指令
Gazebo 需要 GUI，必須允許 Docker 存取主機的顯示介面：
在主機（非Docker容器）先允許顯示連接：

xhost +local:dockerGazebo

這個信息是

non-network local connections being added to access control list

代表已經成功允許 本地 Docker 容器（使用 Unix socket） 連接到你本機的圖形介面（X server）。
🚩然後使用以下指令啟動 Docker 容器：

 docker run -it \  
  --env="DISPLAY=$DISPLAY" \  
  --env="QT_X11_NO_MITSHM=1" \  
  --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \  
  --network host \
  --name gazebo_sitl \
  -v $HOME:/host_home \
  gazebo-harmonic \  
  /bin/bash

這個設定：
1. 讓 Docker 使用主機的顯示環境
2. 防止 Qt 出現共享記憶體問題

- 確認安裝成功
在容器內啟動 Gazebo：

gz sim --version

# 二、下載PX4-Autopilot並建置
在Raspi5中要建置成功需要修改ubuntu.sh，將g++-multilib、gcc-multilib兩行刪除(#號的部分需要刪除)，可以參考SITL on the Raspberry Pi 5這一篇文章。

git clone https://github.com/PX4/PX4-Autopilot.git --recursive  
cd PX4-Autopilot  
git submodule update --init --recursive
bash ./Tools/setup/ubuntu.sh

# 三、編譯SITL並啟動
編譯並建立 SITL
其中PX4_GA_WORLD的場景是讀取*/PX4_Autopilot/Tools/simulation/gz/worlds/.sdf*
而gz_x500是飛機模型，讀取自*/PX4_Autopilot/Tools/simulation/gz/models*

export PX4_GZ_WORLD=default  
make px4_sitl gz_x500

相關資料：
⭐[https://docs.px4.io/main/en/sim_gazebo_gz/](https://docs.px4.io/main/en/sim_gazebo_gz/)
⭐[https://gazebosim.org/docs/harmonic/getstarted/](https://gazebosim.org/docs/harmonic/getstarted/)

# 四、連線QGC並起飛
​**開啟UDP，輸入QGC IP位置，使SITL與QGC連線**

pxh> mavlink start -u 14570 -r 4000000 -m onboard -o 14550 -t 192.168.0.107

**輸入強制解除限制並起飛**

pxh> commander arm -f  
pxh> commander takeoff

---

# 總結
**以上就是 Gazebo Harmonic 搭配 SITL 模擬系統的建置流程，整體步驟不算複雜，只要依照順序設定好環境與參數，就能順利啟動模擬。透過這樣的模擬平台，不但可以事先驗證功能，也能大幅降低實際測試的風險與成本，是進行開發與調試時非常實用的工具。**