Raspberry Pi Zero 2 W トラブルシューティング（授業向け）

対象環境:

  • Raspberry Pi Zero 2 W
  • Raspberry Pi OS Lite 64bit（GUIなし）
  • OSインストール、ユーザー、パスワード、ネットワークは教員側で設定済み
  • プログラムは基本的にPCで作成し、scpでRaspberry Piへ転送して実行

0. 最初に確認すること（共通）

トラブルが起きたら、次の順で切り分けると早いです。

  1. 電源ランプは安定しているか
  2. PCとRaspberry Piは同じネットワークか
  3. IPアドレス、ユーザー名、ファイルパスの打ち間違いがないか
  4. エラーメッセージを1行目から読む（最後だけ見ない）

1. SSH接続でハマる（5項目）

1-1. sshで接続できない（タイムアウト）

  • 症状
  • ssh user@IP を実行しても応答がなくタイムアウトする
  • 原因
  • IPアドレスの打ち間違い
  • PCとRaspberry Piが別ネットワーク
  • 解決方法
  • 配布されたIPを再確認する（1文字ずつ）
  • PC側で ping IPアドレス を実行し疎通確認する
  • 同じ教室Wi-Fi/有線セグメントにいるか確認する

1-2. Connection refused が出る

  • 症状
  • すぐ Connection refused になる
  • 原因
  • Raspberry Piが未起動、または起動直後でsshサービスが未準備
  • 解決方法
  • 電源状態を確認し、起動後30-60秒待って再試行する
  • それでも不可なら教員へ連絡し本体側状態を確認する

1-3. パスワード入力してもPermission denied

  • 症状
  • Permission denied, please try again.
  • 原因
  • ユーザー名ミス
  • キーボード配列差（@, :, -, _ など）
  • 解決方法
  • ssh ユーザー名@IP のユーザー名を配布表と照合する
  • パスワードは画面に表示されない仕様なのでそのまま入力する
  • 3回失敗したら入力内容を紙に書いて確認する

1-4. 初回接続メッセージで止まる

  • 症状
  • Are you sure you want to continue connecting (yes/no/[fingerprint])? で進まない
  • 原因
  • 初回接続時のホスト鍵確認メッセージで入力待ちになっている
  • 解決方法
  • yes と入力して Enter を押す
  • 次回以降は同じPCから同じ端末へなら表示されない

1-5. 接続中に突然切れる

  • 症状
  • 作業中に Connection reset などで切断される
  • 原因
  • Wi-Fi不安定
  • 電源品質不良
  • 解決方法
  • 端末位置を変更し電波状態を改善する
  • 電源ケーブル・アダプタ接続を確認する
  • 再接続して直前コマンドを再実行する

2. CUI操作でハマる（5項目）

2-1. どこで作業しているか分からない

  • 症状
  • ファイル作成後に「どこに保存されたか不明」になる
  • 原因
  • 作業前後のカレントディレクトリ確認が不足している
  • 解決方法
  • pwd で現在位置を必ず確認する
  • ls で中身を見てから cd する
  • 1操作ごとに「いまどこか」を確認する習慣をつける

2-2. コマンド実行でNo such file or directory

  • 症状
  • cd や実行時に No such file or directory
  • 原因
  • ファイル名・フォルダ名のタイプミス
  • 全角文字や全角スペース混入
  • 解決方法
  • ls で正確な名前を確認して再入力する
  • 補完（Tabキー）を使って入力ミスを減らす
  • 日本語名より半角英数字名を優先する

2-3. Permission deniedでスクリプト実行不可

  • 症状
  • ./script.sh 実行時に Permission denied
  • 原因
  • 実行権限がない
  • 解決方法
  • chmod +x script.sh を実行する
  • ls -l で権限表示を確認する
  • 実行は ./script.sh の形式を使う

2-4. sudoを付けるべきか分からない

  • 症状
  • 設定変更系コマンドが権限エラーになる
  • 原因
  • 一般ユーザー権限と管理者権限の違いが曖昧
  • 解決方法
  • システム設定変更時のみ sudo を使う
  • ファイル編集や自作プログラム実行では通常 sudo 不要
  • 迷ったらまず sudo なしで実行し、エラー内容を確認する

2-5. 終了せず電源を抜いてしまう

  • 症状
  • 次回起動時に不調、ファイル破損
  • 原因
  • shutdown を実行せずに電源を切っている
  • 解決方法
  • 作業終了時は必ず sudo shutdown -h now を実行する
  • ランプ消灯を確認してから電源を外す

3. PCで作ってscp転送時にハマる（5項目）

3-1. scpコマンドの向きが逆

  • 症状
  • 転送されたと思ったのにRaspberry Pi側にファイルがない
  • 原因
  • 「PC -> Pi」と「Pi -> PC」の記法を混同
  • 解決方法
  • PCからPiへ送る基本形を固定して覚える
  • scp ローカルファイル ユーザー名@IP:保存先 を使う
  • 転送後にPi側で ls して存在確認する

3-2. scpでNo such file or directory

  • 症状
  • scp実行直後にパス不正エラー
  • 原因
  • ローカル側パス誤り
  • 保存先ディレクトリがPi側に存在しない
  • 解決方法
  • PC側でファイルの場所を確認してからscp実行する
  • Pi側で mkdir -p 保存先 を先に作る
  • パスに空白がある場合は引用符で囲む

3-3. 転送後に古いコードが動いている

  • 症状
  • 修正したはずの動作に変わらない
  • 原因
  • 別名ファイルを転送した
  • 実行ディレクトリが違う
  • 解決方法
  • 実行前に pwd と ls で対象ファイルを確認する
  • cat ファイル名 で最新内容か確認する
  • ファイル名を授業内で統一する

3-4. 改行コード差でシェルスクリプトが動かない

  • 症状
  • bad interpreter や見慣れない記号エラー
  • 原因
  • Windows改行（CRLF）のまま転送
  • 解決方法
  • エディタの改行コードをLFで保存する
  • 必要に応じてPi上で dos2unix を使う

3-5. 文字コード差で日本語が崩れる

  • 症状
  • コメントや文字列が文字化け
  • 原因
  • 文字コードがUTF-8以外
  • 解決方法
  • エディタ保存形式をUTF-8に統一する
  • ターミナル側もUTF-8前提で扱う

4. Python実行でハマる（5項目）

4-1. pythonコマンドで起動できない

  • 症状
  • python: command not found
  • 原因
  • 環境によっては python3 が標準
  • 解決方法
  • python3 ファイル名.py で実行する
  • 授業では python3 を統一表記にする

4-2. ModuleNotFoundError が出る

  • 症状
  • No module named ...
  • 原因
  • 必要ライブラリ未導入
  • ライブラリ名とパッケージ名の取り違え
  • 解決方法
  • エラーメッセージのモジュール名を確認する
  • 配布手順どおりにインストールする
  • 同じコマンドを全員で統一する

4-3. IndentationError が出る

  • 症状
  • IndentationError や unexpected indent
  • 原因
  • インデント崩れ（スペース/タブ混在）
  • 解決方法
  • エディタでインデントをスペース4つに統一する
  • 問題行の前後を見て字下げを揃える
  • まず最小サンプルから再実行する

4-4. 実行したらすぐ終了して結果が見えない

  • 症状
  • 何も起きないように見える
  • 原因
  • 例外で即終了している
  • 期待した出力文がない
  • 解決方法
  • print() を途中に追加して到達点を確認する
  • 端末に出たTraceback全文を読む
  • 1ブロックずつ段階実行して切り分ける

4-5. 無限ループを止められない

  • 症状
  • LED点滅などが止まらない
  • 原因
  • while True の停止方法を知らない
  • 解決方法
  • 端末で Ctrl + C を押して停止する
  • 終了処理（例: GPIO cleanup）を except KeyboardInterrupt で書く

5. GPIO・配線でハマる（5項目）

5-1. LEDが点灯しない

  • 症状
  • 実行してもLED無反応
  • 原因
  • LED極性逆
  • GND未接続
  • ピン番号の指定ミス
  • 解決方法
  • 長い足（アノード）と短い足（カソード）を確認する
  • GNDへの経路があるか配線を追う
  • 配線図とコードのピン番号を一致させる

5-2. BOARD番号とBCM番号を混同

  • 症状
  • 想定と別ピンが動く、または無反応
  • 原因
  • 物理ピン番号とGPIO番号の混在
  • 解決方法
  • 授業では方式を1つに統一する（例: BCM）
  • GPIO.setmode(GPIO.BCM) と配線図の対応を確認する

5-3. 部品やPi本体が熱い

  • 症状
  • 異常発熱、焦げ臭いにおい
  • 原因
  • 3.3V/5V配線ミス
  • ショート
  • 解決方法
  • 直ちに電源を切る
  • 配線を全外しして最小構成でやり直す
  • 教員確認後に再通電する

5-4. センサー値が不安定

  • 症状
  • 値が大きくぶれる、時々0や異常値
  • 原因
  • 配線接触不良
  • GND共有不足
  • サンプリング条件不適切
  • 解決方法
  • ジャンパ線を挿し直す
  • GND共通化を再確認する
  • 読み取り間隔を適切に設定する

5-5. 実験後に次の班が再現できない

  • 症状
  • 同じコードなのに動かない
  • 原因
  • 配線を戻していない
  • 変更箇所が記録されていない
  • 解決方法
  • 実験後に配線写真を残す
  • 「配線図」「使用ピン」「実行コマンド」を3点セットで記録する
  • 班内で再現確認してから終了する

6. 相談時に持ってくると解決が早い情報

質問するときは次を提示してください。

  1. 実行したコマンド（コピペ）
  2. エラーメッセージ全文
  3. pwd と ls の結果
  4. 配線写真（GPIOを含む全体）
  5. どこまでできて、どこで止まったか

この5点が揃っていると、教員・TA・チームメンバーが短時間で原因を特定できます。

関連ページへのリンク候補