トラブルシューティング¶

このページでわかること

ロボット運用中によくある症状とその原因・対処法がわかります。症状で検索して該当する項目を確認してください。

ROS 2 起動時の問題¶

`ros2 launch` でノードが起動しない¶

症状	原因	対処
`package 'questix_launcher' not found`	install が読み込まれていない	`source ~/robot_ws/install/setup.bash` を実行
`ModuleNotFoundError`	パッケージがビルドされていない	`colcon build --symlink-install` を実行
デバイスファイルが開けないエラー	ハードウェアが未接続 / udev 未適用	デバイスの接続を確認・再起動

`ros2 topic list` が空¶

ROS 2 のノードが 1 つも起動していない状態です。launch ファイルを実行してください。

ros2 launch questix_launcher questix_core.launch.xml

コントローラの問題¶

コントローラを動かしてもロボットが動かない¶

/joy トピックに入力が届いているか確認します。
```
ros2 topic echo /joy
```
joy_gate が遮断していないか確認します。
```
ros2 topic echo /gpio/controllable
```
data: false の場合は GPIO 参照系が「操作不可」と判定しています。enable_gpio_ref:=false で起動するか、GPIO の配線を確認してください。
DualShock が認識されているか確認します。
```
ls /dev/input/js*
```

UART コントローラが認識されない¶

ls /dev/ttyUSB* /dev/ttyACM*

デバイスファイルが存在しない場合は、ケーブルの接続・ドライバの状態を確認してください。

走行の問題¶

前後が逆に動く¶

joy_axis_drive_params.yaml の invert_left_axis / invert_right_axis を反転してください。

invert_left_axis: true    # デフォルト: false
invert_right_axis: false  # デフォルト: true

変更後はビルド不要（--symlink-install でビルド済みの場合）ですが、ノードの再起動が必要です。

ロボットの速度が出ない¶

drive_component.yaml の max_motor_rpm を確認してください。

max_motor_rpm: 1000  # 組立確認時は 100 程度から始める

走行中にモーターが突然停止する¶

drive_component.yaml の control_mode が current の場合、max_current_amp の制限に達している可能性があります。値を増やすか、control_mode: velocity に変更してください。

発射機構の問題¶

発射ボタンを押しても動かない¶

shot_component が起動しているか確認します（enable_shot:=true が必要）。
/dev/servo が存在するか確認します。
```
ls /dev/servo
```
サーボのボーレートと ID を shot_config.yaml で確認します。

発射角度がずれている¶

shot_config.yaml の fire_angle / home_angle を調整します。値は度（°）で指定します。

GPIO・ハードウェアの問題¶

`gpio_status` でエラーが出る¶

グループ設定が未反映です。再起動すると解消することがほとんどです。

# グループを確認
groups $USER
# gpio が含まれていれば OK

I2C デバイスが認識されない¶

再起動後に確認します。

i2cdetect -y 1

デバイスが表示されない場合、/boot/firmware/config.txt の dtparam=i2c_arm=on を確認してください。

自動起動の問題¶

電源を入れてもロボットが自動起動しない¶

モードを確認します。
```
cat /etc/questix_robot/mode
```
competition でなければ自動起動しません。

サービスの状態を確認します。

systemctl status questix_robot.service
journalctl -u questix_robot.service -n 50

自動起動後すぐにサービスが停止する¶

ログでエラーを確認します。

journalctl -u questix_robot.service -n 100

よくある原因：ワークスペースがビルドされていない、launch.env の ROBOT_WS が間違っている。

ネットワーク・SSH の問題¶

SSH で接続できない¶

# Pi の IP アドレスを確認（Pi に直接ログインして）
hostname -I

ルーターの管理画面や nmap でも確認できます。

問題が解決しない場合¶

journalctl -u questix_robot.service -f でログを確認してください。
ROS 2 ノードのログは ~/.ros/log/ に保存されています。
QUESTiX GitHub Issues で報告してください。