RPi3 + Osoyoo 3.5インチ SPI スクリーン + Trixie/Bookworm セットアップガイド
ハードウェア: Raspberry Pi 3B/3B+/Zero 2W/Zero W
スクリーン: Osoyoo 3.5インチ SPI タッチスクリーン 480*320 (モデル番号: 2022013800)
システム: Raspberry Pi OS Trixie (64-bit)
注記: 元のチュートリアルは RPi4/5 用です。
このガイドには、Raspberry Pi 3 で SPI スクリーンを動作させるために必要な RPi3 専用の修正 が含まれています。
1システムの準備
まず HDMI モニタを接続して起動し、初期設定（ユーザー名: pi）を完了させ、SSH を有効にします。
sudo apt-get update
sudo apt-get upgrade -y
2SPI スクリーン ドライバのインストール
sudo apt-get install unzip cmake -y
cd ~
sudo wget https://osoyoo.com/driver/osoyoo35b.zip
sudo unzip ./osoyoo35b.zip
sudo cp osoyoo35b.dtbo /boot/overlays/
3必要な X11 パッケージのインストール (RPi3 専用)
sudo apt-get install xserver-xorg-video-fbdev xserver-xorg-legacy -y
パッケージの説明:
xserver-xorg-video-fbdev – fbdev ディスプレイ ドライバ (fbturbo の代替)xserver-xorg-legacy – Xwrapper.config の権限設定を可能にします
4config.txt の編集
sudo nano /boot/firmware/config.txt
4a. 以下の行をコメントアウトする (行頭に # を追加):
#dtoverlay=vc4-kms-v3d
#dtoverlay=vc4-fkms-v3d
#display_auto_detect=1
4b. ファイルの最後に以下を追加する:
# ========== SPI Screen Configuration ==========
gpu_mem=64
display_auto_detect=0
disable_fw_kms_setup=1
max_framebuffers=2
dtparam=spi=on
dtoverlay=osoyoo35b:speed=20000000
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=1
hdmi_mode=87
hdmi_cvt 480 320 60 6 0 0 0
hdmi_drive=2
display_rotate=2
警告: hdmi_cvt は必ず 480 320 に設定してください。640 480 ではありません。
5X11 への切り替えと CLI オートログインの設定
sudo raspi-config nonint do_boot_behaviour B2
sudo raspi-config nonint do_wayland W1
最重要項目: do_wayland W1 は Wayland から X11 への切り替えを行います。Trixie はデフォルトで Wayland ですが、SPI スクリーンは Wayland をサポートしていません。
6X Server 権限の修正 (RPi3 専用)
sudo tee /etc/X11/Xwrapper.config > /dev/null << 'EOF'
allowed_users=anybody
needs_root_rights=yes
EOF
警告: 各行の 先頭にスペースを入れない でください。KMS を無効にすると DRM デバイスへのアクセスが制限されるため、needs_root_rights=yes が必要になります。
7競合する X11 構成ファイルの無効化
# modesetting/kms 設定の無効化
sudo mv /usr/share/X11/xorg.conf.d/20-noglamor.conf \
/usr/share/X11/xorg.conf.d/20-noglamor.conf.bak 2>/dev/null
# fbturbo 設定の削除
sudo rm -f /usr/share/X11/xorg.conf.d/99-fbturbo.conf
8X11 fbdev 設定の作成
sudo nano /etc/X11/xorg.conf.d/99-fbdev.conf
以下の内容を追加します:
Section "ServerLayout"
Identifier "SPI Layout"
Screen "SPI Screen"
EndSection
Section "Device"
Identifier "SPI Display"
Driver "fbdev"
Option "fbdev" "/dev/fb1"
Option "ShadowFB" "on"
EndSection
Section "Monitor"
Identifier "SPI Monitor"
EndSection
Section "Screen"
Identifier "SPI Screen"
Monitor "SPI Monitor"
Device "SPI Display"
DefaultDepth 16
SubSection "Display"
Depth 16
Modes "480x320"
Virtual 480 320
EndSubSection
EndSection
重要ポイント:
– ServerLayout は X に対し、SPI スクリーンのみを使用するよう強制します。
– fbdev "/dev/fb1": RPi3 では SPI スクリーンは fb1 となります (fb0 は HDMI)。
– ShadowFB "on": 16ビット深度でのカラーレンダリングを向上させます。
9.bash_profile の構成
cat > ~/.bash_profile << 'EOF' export FRAMEBUFFER=/dev/fb1 startx 2> /tmp/xorg_errors
EOF
10初回再起動
sudo reboot
成功: 再起動後、SPI スクリーンにデスクトップが表示されます。もし画面が白いままの場合は、一度電源を切り、再度 Pi を起動してください。
11タッチ操作の構成
再起動に成功したら、SSH 経由で接続します:
sudo apt-get install xserver-xorg-input-evdev xinput-calibrator -y
sudo cp -rf /usr/share/X11/xorg.conf.d/10-evdev.conf \
/usr/share/X11/xorg.conf.d/45-evdev.conf
sudo tee /usr/share/X11/xorg.conf.d/99-calibration.conf > /dev/null << 'EOF'
Section "InputClass"
Identifier "calibration"
MatchProduct "ADS7846 Touchscreen"
Option "Calibration" "241 3854 3885 240"
Option "SwapAxes" "1"
EndSection
EOF
sudo reboot
RPi3 と RPi4/5 の違い
| 設定項目 |
オリジナル (RPi4/5) |
RPi3 での変更点 |
| config.txt KMS |
KMS 有効 |
必ず dtoverlay=vc4-kms-v3d をコメントアウトする |
| config.txt gpu_mem |
設定なし |
gpu_mem=64 を追加 |
| X11 パッケージ |
不要 |
必ず xserver-xorg-video-fbdev と xserver-xorg-legacy をインストールする |
| Xwrapper.config |
変更なし |
needs_root_rights=yes を設定 |
| 20-noglamor.conf |
維持 |
必ず無効化する |
| 99-fbturbo.conf |
維持 (fb0 を使用) |
必ず削除する |
| 99-fbdev.conf |
不要 |
ServerLayout + fb1 を指定して必ず作成する |
| SPI スクリーン デバイス |
/dev/fb0 |
/dev/fb1 |
なぜこれらの違いがあるのですか？
– RPi4/5: KMS 有効、SPI スクリーン = fb0 (唯一のフレームバッファ)、X が自動検出します。
– RPi3: KMS 無効、HDMI = fb0、SPI スクリーン = fb1、X に明示的な構成設定が必要です。
トラブルシューティング
診断コマンド
画面が起動ページで止まっている、または白く表示されている場合は、SSH 経由で以下のコマンドを実行してください:
# X Server のエラーを確認
cat /tmp/xorg_errors
# X のログを確認
cat ~/.local/share/xorg/Xorg.0.log
# フレームバッファ デバイスを確認
ls -l /dev/fb*
dmesg | grep -i fb1
# Xwrapper.config の確認 (行頭にスペースがないこと！)
cat /etc/X11/Xwrapper.config
# xserver-xorg-legacy がインストールされているか確認
dpkg -l | grep xserver-xorg-legacy
よくあるエラーと解決策
エラー: Cannot open /dev/tty0 (Permission denied)
解決策: Xwrapper.config が存在しない、行頭にスペースがある、または xserver-xorg-legacy がインストールされていません。以下を実行してください:
sudo apt-get install xserver-xorg-legacy -y
sudo tee /etc/X11/Xwrapper.config > /dev/null << 'EOF'
allowed_users=anybody
needs_root_rights=yes
EOF
エラー: Switching VT failed
解決策: 物理的な tty1 からではなく、SSH から startx を実行しています。これは SSH 経由でのテスト時には通常の動作です。再起動後のオートログイン コンソールでは正しく動作します。
エラー: no displays replace it または no screens found
解決策: KMS が無効になっていますが、LightDM がそれを使用しようとしています。LightDM ではなく、CLI オートログイン (B2) と startx を使用していることを確認してください。以下を実行します:
sudo raspi-config nonint do_boot_behaviour B2
エラー: 画面にデスクトップは表示されるが、ウィンドウがはみ出す
解決策: 480×320 解像度では、一部のアプリ（コントロールセンターなど）でこれは正常な動作です。ウィンドウを閉じるには Alt+F4、ウィンドウを移動するには Alt+ドラッグ を使用してください。回避策については、640×480 仮想解像度のチュートリアルを参照してください。
エラー: 再起動後に画面が白いまま
解決策: 電源の抜き差し（パワーサイクル）を試してください。それでも白い場合は、以下を確認してください:
# fb1 が存在するか確認
ls -l /dev/fb*
# SPI オーバーレイがロードされているか確認
dmesg | grep osoyoo
# config.txt の変更内容を確認
cat /boot/firmware/config.txt | grep -E "(kms|spi|osoyoo)"
エラー: タッチが効かない、または反転している
解決策: タッチスクリーンの再キャリブレーションを行ってください:
DISPLAY=:0 xinput_calibrator
その後、/usr/share/X11/xorg.conf.d/99-calibration.conf を新しい値で更新してください。
クイック修正スクリプト
最初からやり直す必要がある場合は、このワンクリック修正スクリプトを実行してください:
#!/bin/bash
# RPi3 SPI Screen クイック修正
# 必要なパッケージのインストール
sudo apt-get install xserver-xorg-video-fbdev xserver-xorg-legacy -y
# Xwrapper.config の修正
sudo tee /etc/X11/Xwrapper.config > /dev/null << 'EOF' allowed_users=anybody needs_root_rights=yes EOF # 競合する設定の無効化 sudo mv /usr/share/X11/xorg.conf.d/20-noglamor.conf \ /usr/share/X11/xorg.conf.d/20-noglamor.conf.bak 2>/dev/null
sudo rm -f /usr/share/X11/xorg.conf.d/99-fbturbo.conf
# fbdev 設定の作成
sudo mkdir -p /etc/X11/xorg.conf.d
sudo tee /etc/X11/xorg.conf.d/99-fbdev.conf > /dev/null << 'EOF' Section "ServerLayout" Identifier "SPI Layout" Screen "SPI Screen" EndSection Section "Device" Identifier "SPI Display" Driver "fbdev" Option "fbdev" "/dev/fb1" Option "ShadowFB" "on" EndSection Section "Monitor" Identifier "SPI Monitor" EndSection Section "Screen" Identifier "SPI Screen" Monitor "SPI Monitor" Device "SPI Display" DefaultDepth 16 SubSection "Display" Depth 16 Modes "480x320" Virtual 480 320 EndSubSection EndSection EOF # 起動動作の設定 sudo raspi-config nonint do_boot_behaviour B2 sudo raspi-config nonint do_wayland W1 # .bash_profile の構成 cat > ~/.bash_profile << 'EOF' export FRAMEBUFFER=/dev/fb1 startx 2> /tmp/xorg_errors
EOF
echo "修正が完了しました。
再起動してください: sudo reboot"
Raspberry Pi Zero 2W のトラブルシューティング
注記: このチュートリアルは Raspberry Pi Zero 2W と互換性があります。Zero 2W は RPi 3 と同じ BCM2710 プロセッサを使用しているため、この構成で動作するはずです。ただし、ハードウェアの個体差により、一部のユーザーで表示の問題が発生する場合があります。画面が正しく表示されない場合は、以下のトラブルシューティング手順に従ってください。
診断コマンド
まず SSH で接続し、問題を特定するために以下のコマンドを実行します:
# フレームバッファ デバイスが存在するか確認
ls -l /dev/fb*
# SPI オーバーレイが正常にロードされたか確認
dmesg | grep -i spi
dmesg | grep -i osoyoo
dmesg | grep -i fb
# X Server のエラーを確認
cat /tmp/xorg_errors
# config.txt の設定を確認
cat /boot/firmware/config.txt | grep -E "(spi|osoyoo|gpu_mem)"
解決策 1: SPI 速度を下げる
Zero 2W では、安定した動作のために SPI クロック速度を下げる必要がある場合があります:
sudo nano /boot/firmware/config.txt
以下の行を探します:
dtoverlay=osoyoo35b:speed=20000000
これを以下のように変更します:
dtoverlay=osoyoo35b:speed=16000000
それでも動作しない場合は、さらに速度を下げてみてください:
dtoverlay=osoyoo35b:speed=10000000
解決策 2: GPU メモリの調整
Zero 2W の RAM は 512MB です (RPi 3 の 1GB より少ない)。GPU メモリの割り当てを減らすと改善される場合があります:
sudo nano /boot/firmware/config.txt
以下の変更を行います:
gpu_mem=64
これを以下のようにします:
gpu_mem=32
解決策 3: 不要な設定の削除
max_usb_current=1 設定は、USB 電力が制限されていた古い Pi モデル向けのものです。Zero 2W ではコメントアウトしてください:
#max_usb_current=1
Zero 2W 推奨 config.txt
標準設定で動作しない場合は、以下の最適化された設定を使用してください:
# ========== SPI Screen Configuration for Zero 2W ==========
gpu_mem=32
display_auto_detect=0
disable_fw_kms_setup=1
max_framebuffers=2
dtparam=spi=on
dtoverlay=osoyoo35b:speed=16000000
hdmi_force_hotplug=1
hdmi_group=2
hdmi_mode=1
hdmi_mode=87
hdmi_cvt 480 320 60 6 0 0 0
hdmi_drive=2
display_rotate=2
重要: config.txt に変更を加えた後は、必ず再起動して設定を適用してください:
sudo reboot
それでも動作しませんか？
上記の解決策をすべて試しても画面が表示されない場合は、以下を確認してください:
- 電源供給: 安定した 5V/2.5A の電源を使用しているか確認してください。電力が不足すると表示トラブルの原因となります。
- GPIO 接続: SPI スクリーンが GPIO ピンにしっかりと差し込まれているか確認してください。一度取り外して差し直しを試してください。
- SD カード: 別の SD カードを試してください。破損した SD カードや低速なカードは起動トラブルの原因となります。
- クリーンインストール: すべてが失敗した場合は、最新の Raspberry Pi OS Trixie をクリーンインストールし、チュートリアルを最初からやり直してみてください。
成功チェックリスト:
再起動後、SSH で以下の状態を確認してください:
ls /dev/fb1 – /dev/fb1 が存在することを確認します。
dmesg | grep osoyoo – オーバーレイが正常にロードされたことを確認します。
cat /tmp/xorg_errors – ファイルが空であるか、致命的なエラーが表示されていないことを確認します。
既知の制限事項
- 画面解像度は 480×320 固定です (ハードウェアの制限)
- 一部のアプリケーションは、最小ウィンドウサイズが 480×320 より大きくなっています
- 16ビットのカラー深度により、一部の GTK テーマの描画が異なる場合があります
- RPi3 の CPU は RPi4/5 より遅いため、デスクトップの反応が少し遅く感じられる場合があります
リファレンス チュートリアル
お使いの Raspberry Pi モデルと OS バージョンに一致するチュートリアルを選択してください:
Bookworm / Trixie RPi 4/5
Advanced • Trixie/Bookworm • 2025-10-01 以降
Advanced • Trixie/Bookworm • 2025-10-01 以降
どれを選べばよいかわかりませんか？
• Pi モデルを確認する: cat /proc/device-tree/model
• OS バージョンを確認する: cat /etc/os-release
テクニカルサポート
ご不明な点やフィードバックがございましたら、チケットをお送りください。弊社のチームが通常 1〜2営業日 以内に回答いたします。お待ちいただきありがとうございます！
営業時間: 午前9時 〜 午後6時 GMT+8 (月曜日 〜 金曜日)
お問い合わせ先: [email protected]
