uvを使った仮想環境でUnitree MuJoCoシミュレータをセットアップする方法の備忘録です。
2025.07.10にClaudeとやり取りしながらトライアンドエラーを経て実施できた手順をもとに記述しています。
このMujoCoのセットアップにより以下が可能になる（らしい。自分もこれから勉強します）：
- 基本的なロボット制御プログラムの開発
- 歩行アルゴリズムの実装とテスト
- センサデータの取得と処理
- 強化学習による制御学習
- Arduino連携での統合制御システム開発
0. 前提条件
- Ubuntu 22.04 LTS
- NVIDIA GPU（RTX5060Tiでテスト済み）
- uv がインストール済み
uvがインストールされていない場合：
curl -LsSf https://astral.sh/uv/install.sh | sh
1. システム依存関係のインストール
# MuJoCo用の依存関係
sudo apt update
sudo apt install libglfw3-dev libxinerama-dev libxcursor-dev libxi-dev
# YAML-CPP
sudo apt install libyaml-cpp-dev
# その他の依存関係
sudo apt install build-essential cmake git
# Eigen3ライブラリ（G1ロボット用サンプルで必要）
sudo apt install libeigen3-dev
# CyclonDDS（システムパッケージを使用）
sudo apt install cyclonedds-dev libddsc0 libcycloneddsidl0
# pip（cycloneDDSインストール用）
sudo apt install python3-pip
2. Unitree SDK2のインストール
以降、作業用ディレクトリとしてrobotics内で実行するものとします。
（個人的なニーズで、GenesisやIssacLabなどのロボット関係のソフトウェアはroboticsディレクトリにまとめて置いておきたいだけです。）
# 推奨インストールパス
sudo mkdir -p /opt/unitree_robotics
# 作業ディレクトリを作成
mkdir ~/robotics
cd ~/robotics
git clone https://github.com/unitreerobotics/unitree_sdk2.git
cd unitree_sdk2/
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/unitree_robotics
sudo make install
注意: G1用のサンプルでEigenエラーが出た場合は続行してください
（シミュレータ本体には影響なし）。
3. MuJoCoのシステムインストール（オプション）
# ソースからMuJoCoをインストール（必要に応じて）
cd ~/robotics
git clone https://github.com/google-deepmind/mujoco.git
cd mujoco
mkdir build && cd build
cmake ..
make -j4
sudo make install
sudo ldconfig
4. Unitree MuJoCoのクローン
# unitree_mujocoをクローン
cd ~/robotics
git clone https://github.com/unitreerobotics/unitree_mujoco.git
5. uvを使った仮想環境の作成（Python 3.10）
# プロジェクト用ディレクトリを作成
mkdir ~/robotics/unitree_workspace
cd ~/robotics/unitree_workspace
# Python 3.10で仮想環境を作成（重要：3.11では問題あり）
uv venv --python 3.10 unitree_env_310
# 仮想環境をアクティベート
source unitree_env_310/bin/activate
6. Python依存関係のインストール
# 基本パッケージをインストール
uv pip install numpy opencv-python pygame ipython jupyter matplotlib
# MuJoCoをバージョン指定でインストール（重要：最新版では問題あり）
uv pip install mujoco==2.3.7
# PyOpenGLをダウングレード
uv pip install pyopengl==3.1.6
7. CyclonDDSの設定
# システムのCyclonDDSを仮想環境で利用できるよう設定
echo 'import sys; sys.path.append("/home/$(whoami)/.local/lib/python3.10/site-packages")' > ~/robotics/unitree_workspace/unitree_env_310/lib/python3.10/site-packages/cyclonedds_path.pth
# システムにCyclonDDSをインストール（仮想環境外で実行）
deactivate
pip install cyclonedds
source unitree_env_310/bin/activate
8. unitree_sdk2_pythonのセットアップ
# unitree_sdk2_pythonをクローン
cd ~/robotics/unitree_workspace
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
# setup.pyのcycloneDDSバージョン制約を緩和
sed -i 's/cyclonedds==0.10.2/cyclonedds>=0.8.2,<0.11.0/' setup.py
# 依存関係チェックを無効にしてインストール
uv pip install -e . --no-deps
9. 環境変数の設定
# 必要な環境変数を設定
echo 'export CYCLONEDDS_HOME=/usr' >> ~/.bashrc
echo 'export CMAKE_PREFIX_PATH=/usr:$CMAKE_PREFIX_PATH' >> ~/.bashrc
echo 'export MUJOCO_GL=disable' >> ~/.bashrc
source ~/.bashrc
10. シミュレータの設定
# Python版シミュレータの設定ファイルを編集
cd ~/robotics/unitree_mujoco/simulate_python
sed -i 's/USE_JOYSTICK = 1/USE_JOYSTICK = 0/' config.py
11. 動作確認
基本テスト
# 仮想環境をアクティベート
cd ~/robotics/unitree_workspace
source unitree_env_310/bin/activate
# CyclonDDSのインポートテスト
python3 -c "
import sys
sys.path.append('/home/$(whoami)/.local/lib/python3.10/site-packages')
import cyclonedds
import cyclonedds.idl
print('CyclonDDS loaded successfully')
"
# unitree_sdk2pyのインポートテスト
python3 -c "
from unitree_sdk2py.core.channel import ChannelFactoryInitialize
print('unitree_sdk2py loaded successfully')
"
# MuJoCoテスト
export MUJOCO_GL=disable
python3 -c "
import mujoco
print('MuJoCo version:', mujoco.__version__)
model = mujoco.MjModel.from_xml_path('~/robotics/unitree_mujoco/unitree_robots/go2/scene.xml')
data = mujoco.MjData(model)
print('Model loaded successfully')
"
シミュレータの実行
# シミュレータを起動
cd ~/robotics/unitree_mujoco/simulate_python
export MUJOCO_GL=disable
python3 unitree_mujoco.py
成功すると以下が表示されます：
- ロボットのリンク情報（18個）
- ジョイント情報（12個）
- アクチュエータ情報（12個）
- センサー情報（50個）
制御テスト（別ターミナル）
# 新しいターミナルで
cd ~/robotics/unitree_workspace
source unitree_env_310/bin/activate
export MUJOCO_GL=disable
cd ~/robotics/unitree_mujoco/example/python
python3 stand_go2.py
正常に動作すると、シミュレータ内のロボットが立ち上がって再び寝そべる動作を行います。
12. 日常的な使用方法
シミュレータ起動
cd ~/robotics/unitree_workspace
source unitree_env_310/bin/activate
export MUJOCO_GL=disable
cd ~/robotics/unitree_mujoco/simulate_python
python3 unitree_mujoco.py
制御プログラム実行（シミュレータ起動後）
# 新しいターミナルで
cd ~/robotics/unitree_workspace
source unitree_env_310/bin/activate
export MUJOCO_GL=disable
cd ~/robotics/unitree_mujoco/example/python
python3 stand_go2.py
13. トラブルシューティング
CyclonDDSが見つからない場合
# パスを確認
python3 -c "import sys; print('\n'.join(sys.path))"
# システムパッケージの場所を確認
deactivate
python3 -c "import cyclonedds; print(cyclonedds.__file__)"
MuJoCoでSegmentation faultが発生する場合
# バージョンを確認
uv pip list | grep mujoco
# 必要に応じてダウングレード
uv pip uninstall mujoco
uv pip install mujoco==2.3.7
OpenGLエラーが発生する場合
# 環境変数が設定されているか確認
echo $MUJOCO_GL
# 設定されていない場合
export MUJOCO_GL=disable
権限エラーの場合
# ゲームパッド関連（使用しない場合は無視）
sudo chmod +x /dev/input/js*
14. 成功かどうか確認するポイント
✅ シミュレータ起動時: ロボット情報が正常に表示される
✅ DDS通信: "selected interface lo" メッセージが表示される
✅ 制御テスト: stand_go2.pyでロボットが立ち上がり動作する
✅ エラーなし: Segmentation faultやImportErrorが発生しない