Contents
1. 前提条件とハードウェア概要
このセクションでは、本ガイドで前提とする PC スペック・デバッグプローブ・対象ボードを整理し、読者が「何が必要か」を一目で把握できるようにします。
1.1 必要なハードウェア
- PC
- CPU: x86_64 2 コア以上（Intel 13 世代以降または同等 AMD）
- メモリ: 8 GB 以上（快適さを求めるなら 16 GB 推奨）
-
ストレージ: SSD 100 GB の空き領域
-
デバッグプローブ（USB 経由で使用）
-
ST‑Link/V2、ST‑Link/V3、または ESP‑PROG（FTDI ベース）
-
対象ボード例
- STM32F4 系列（Nucleo / Discovery 等）
- ESP32/ESP32‑C3 系列（開発キット付属の USB‑UART／ESP‑PROG）
ポイント: 上記ハードウェアが揃っていれば、ローカルマシンだけで完結でき、クラウドや CI の導入はオプションです。
2. macOS ネイティブ環境の構築手順
macOS でも Ubuntu と同等の開発体験を得られるように、Homebrew を中心としたインストールフローを示します。
2.1 Homebrew のインストール（導入文）
まずは macOS にパッケージマネージャ Homebrew が無い場合に備えてインストールします。
|
1 2 |
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
公式ドキュメント: https://brew.sh/
2.2 必要パッケージの取得（導入文）
以下のコマンドでビルドに必要なツールとデバッグユーティリティを一括インストールします。
|
1 2 |
brew install gcc make git cmake openocd pkg-config |
gccは macOS 標準の Clang ではなく、GNU GCC 系列が必要です。Homebrew が提供する GNU バージョンは/usr/local/opt/gcc/bin/gcc-13のようにインストールされます。
2.3 ARM 用ツールチェーンの取得（導入文）
ARM 向けクロスコンパイラは公式サイトから直接ダウンロードするか、Homebrew の tap を利用します。将来バージョンが変わっても安全に更新できるよう、ArmMbed が提供する formula を使用します。
|
1 2 3 |
brew tap ArmMbed/homebrew-formulae brew install arm-none-eabi-gcc |
インストール後はパスが自動的に通りますが、ターミナルを再起動して以下で確認してください。
|
1 2 |
arm-none-eabi-gcc --version # 例: 13.2.1 (2025‑xx‑xx) |
代替案: Ubuntu のように
aptが使える Linux 環境ではsudo apt install gcc-arm-none-eabiでも取得可能です。
2.4 VS Code と PlatformIO のセットアップ（導入文）
VS Code は公式サイトまたは Homebrew Cask でインストールし、拡張機能は CLI 経由で自動追加できます。
|
1 2 3 4 5 |
brew install --cask visual-studio-code code --install-extension ms-vscode.cpptools code --install-extension platformio.platformio-ide code --install-extension marus25.cortex-debug |
注意: VS Code の Insiders ビルドを使用する場合は
code-insidersコマンドに置き換えてください。安定版と機能差があるため、プロジェクトメンテナンス時に統一を推奨します。
3. Windows + WSL2（Ubuntu 22.04）環境の構築
Windows ユーザーは WSL2 を利用すれば、ほぼ Linux と同等の開発体験が得られます。ここでは Ubuntu のインストールから USB デバイス共有までを詳述します。
3.1 WSL2 と Ubuntu のインストール（導入文）
Microsoft の公式ドキュメントに従って、WSL2 を有効化し Ubuntu 22.04 LTS をインストールします。
|
1 2 3 |
# PowerShell (管理者) 実行 wsl --install -d Ubuntu-22.04 |
Microsoft Docs: https://learn.microsoft.com/windows/wsl/install
インストール後、次のコマンドでバージョンを確認してください。
|
1 2 |
wsl -l -v # Ubuntu‑22.04 が Version 2 と表示されれば完了 |
3.2 USB デバイス（ST‑Link / ESP‑PROG）共有設定（導入文）
WSL2 はデフォルトでホスト側の USB を認識しません。usbip ユーティリティを用いてデバイスを Linux 側に転送します。
3.2.1 Windows 側準備
-
Windows の機能有効化
powershell
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart -
usbipd-win のインストール（GitHub リリースから取得）
powershell
iwr -useb https://github.com/dorssel/usbipd-win/releases/download/v4.0.1/usbipd-windows-4.0.1.zip -OutFile $env:TMP\usbipd.zip
Expand-Archive $env:TMP\usbipd.zip -DestinationPath "$env:ProgramFiles\usbipd"
# パスを通す（管理者権限で実行）
setx /M PATH "%PATH%;C:\Program Files\usbipd" -
サービス起動
powershell
usbipd-windows install
Start-Service usbipd
3.2.2 WSL 側準備
|
1 2 3 4 |
# Ubuntu ターミナル内 sudo apt update && sudo apt install -y linux-tools-$(uname -r) linux-cloud-tools-$(uname -r) sudo usermod -aG plugdev $USER # 権限付与（再ログインが必要） |
3.2.3 デバイスのバインドと共有
-
デバイス一覧取得（Windows PowerShell）
powershell
usbipd list -
対象デバイスをバインド（例: ST‑Link が busid 1-2 の場合）
powershell
usbipd bind --busid 1-2 -
WSL 側でデバイスを確認
bash
lsusb | grep -i stlink # または esp‑prog が表示されることを確認
トラブルシュート:
permission deniedエラーが出たら、WSL 内でsudo chmod 666 /dev/bus/usb/*/*を一時的に実行し、再度権限設定を見直してください。
3.3 Ubuntu の基本セットアップ（導入文）
Ubuntu 起動後はシステム更新と必須パッケージのインストールだけで開発基盤が完成します。
|
1 2 3 |
sudo apt update && sudo apt upgrade -y sudo apt install -y build-essential git curl wget openocd python3-pip |
4. GNU Arm Embedded Toolchain の取得と代替インストール方法
Toolchain のバージョンは将来変わる可能性があるため、公式サイトからの手動ダウンロードと APT/PP‑A での自動取得 を併記します。
4.1 手動ダウンロード方式（導入文）
最新版（執筆時点は 13.3.rel1）を直接取得し、/opt 配下に配置します。
|
1 2 3 4 5 6 7 8 |
TOOLCHAIN_VER=13.3.rel1 wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/${TOOLCHAIN_VER}/gcc-arm-none-eabi-${TOOLCHAIN_VER}-x86_64-linux.tar.xz -O /tmp/gcc-arm.tar.xz sudo mkdir -p /opt/gcc-arm-none-eabi-${TOOLCHAIN_VER} sudo tar -xf /tmp/gcc-arm.tar.xz -C /opt/gcc-arm-none-eabi-${TOOLCHAIN_VER} --strip-components=1 echo 'export PATH=$PATH:/opt/gcc-arm-none-eabi-'${TOOLCHAIN_VER}'/bin' >> ~/.bashrc source ~/.bashrc arm-none-eabi-gcc --version # バージョンが表示されれば OK |
4.2 APT パッケージ方式（導入文）
Ubuntu の公式リポジトリに含まれる gcc-arm-none-eabi はやや古い場合があります。最新バージョンを取得したいときは PPA を追加します。
|
1 2 3 4 5 6 7 8 |
# ① Ubuntu 標準パッケージ（保守的） sudo apt install -y gcc-arm-none-eabi # ② 最新版を提供する PPA（2025‑xx 以降の更新に対応） sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa sudo apt update sudo apt install -y gcc-arm-embedded |
メリット:
apt管理下なので将来のアップデートが自動的に反映され、パス設定も不要です。
5. VS Code・PlatformIO・Remote‑Containers の統合
本章ではローカル環境だけでなく、Docker コンテナを VS Code Remote‑Containers で利用する方法を示します。devcontainer.json と Dockerfile のサンプルを併せて提供します。
5.1 VS Code 本体と拡張機能のインストール（導入文）
|
1 2 3 4 5 6 |
# Ubuntu / WSL2 用（Snap 推奨） sudo snap install --classic code # Stable エディション # Insiders を使う場合は公式サイトから .deb を取得し、以下でインストール # sudo dpkg -i code-insiders_*.deb |
拡張機能は CLI で一括導入できます。
|
1 2 3 4 5 |
code --install-extension ms-vscode.cpptools code --install-extension platformio.platformio-ide code --install-extension marus25.cortex-debug code --install-extension ms-vscode-remote.remote-containers |
注意: Insiders と Stable では拡張機能のバージョンが異なることがあります。チームで統一する際はどちらかに揃えてください。
5.2 Dockerfile（開発コンテナイメージ）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# ------------------------------------------------- # ベース: Ubuntu 22.04 + 必要ツールチェーン # ------------------------------------------------- FROM ubuntu:22.04 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y \ build-essential git curl wget openocd python3-pip \ gcc-arm-none-eabi libnewlib-arm-none-eabi \ && rm -rf /var/lib/apt/lists/* # PlatformIO のインストール（pip 経由） RUN pip3 install --no-cache-dir platformio |
ビルド例:
|
1 2 |
docker build -t embedded-dev:2026 . |
5.3 devcontainer.json 設定例（導入文）
/.devcontainer/devcontainer.json をプロジェクト直下に作成し、VS Code から Remote‑Containers: Open Folder in Container を選択します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "name": "Embedded Development (Ubuntu 22.04)", "image": "embedded-dev:2026", "features": { "ghcr.io/devcontainers/features/python:1": {} }, "customizations": { "vscode": { "extensions": [ "ms-vscode.cpptools", "platformio.platformio-ide", "marus25.cortex-debug" ] } }, "postCreateCommand": "pio system info", // PlatformIO の初期化 "remoteUser": "root" } |
ポイント: コンテナ内部は root ユーザーになるため、USB デバイスを共有したい場合は
docker run --device=/dev/bus/usbオプションでデバイスパスをマウントします（WSL2 でも同様）。
6. OpenOCD を用いた書き込み・リアルタイムデバッグ
OpenOCD の設定ファイルは PlatformIO が自動生成しますが、手動で実行したいケースに備えて基本コマンドをまとめます。
6.1 ST‑Link 用書き込み例（導入文）
interface/stlink.cfg と target/stm32f4x.cfg は Ubuntu パッケージに同梱されています。
|
1 2 3 |
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \ -c "program .pio/build/Nucleo_F411RE/firmware.bin verify reset exit" |
6.2 ESP‑PROG 用書き込み例（導入文）
|
1 2 3 |
openocd -f interface/ftdi/esp32_devkit.cfg -f target/esp32.cfg \ -c "program .pio/build/esp32dev/firmware.bin verify reset exit" |
6.3 VS Code デバッグ設定（導入文）
.vscode/launch.json に以下を追記すれば、デバッガ起動がワンクリックで可能です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "name": "Cortex Debug (ST-Link)", "type": "cortex-debug", "request": "launch", "executable": "${workspaceFolder}/.pio/build/Nucleo_F411RE/firmware.elf", "servertype": "openocd", "device": "STM32F411RE", "configFiles": [ "interface/stlink.cfg", "target/stm32f4x.cfg" ], "runToMain": true } |
ヒント: デバッグ中に
Ctrl+Shift+P→ Cortex Debug: Reset and Run を実行すると、リセット後すぐにコードが走り出します。
7. トラブルシューティングと FAQ
以下は環境構築時によく遭遇するエラーとその対処法です。表形式でまとめましたので、問題が起きたらまずここを確認してください。
| エラー | 原因 | 解決策 |
|---|---|---|
arm-none-eabi-gcc: command not found |
PATH にツールチェーンが未設定 | source ~/.bashrc か端末再起動、もしくは sudo apt install gcc-arm-none-eabi を実行 |
permission denied while accessing /dev/ttyACM0 |
USB デバイスの権限不足（WSL2） | Windows 側でデバイスドライバがインストールされたか確認し、WSL2 で sudo usermod -aG dialout $USER 後再ログイン |
openocd: cannot find interface/stlink.cfg |
OpenOCD パッケージ未インストールまたはパス不一致 | sudo apt install openocd 再インストール、もしくは locate stlink.cfg で実際の場所を確認 |
| Docker コンテナ内から USB が見えない | --device オプション忘れ |
docker run -it --rm --device=/dev/bus/usb embedded-dev:2026 bash で起動 |
| VS Code Remote‑Containers が接続できない | WSL2 の Docker Desktop が無効 | Docker Desktop → Settings → Resources → WSL Integration を有効化し、再起動 |
8. CI/CD（GitHub Actions）での自動ビルド例
CI 環境でも同一ツールチェーンを使えるように、先ほど作成した Docker イメージを GitHub Container Registry にプッシュします。
8.1 Docker イメージの公開手順（導入文）
|
1 2 3 4 5 6 7 |
# ローカルでビルド docker build -t ghcr.io/yourorg/embedded-dev:2026 . # GitHub にログイン echo $CR_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin # プッシュ docker push ghcr.io/yourorg/embedded-dev:2026 |
8.2 workflow ファイル（導入文）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
name: Embedded Build CI on: push: paths: - '**.c' - 'platformio.ini' jobs: build: runs-on: ubuntu-latest container: image: ghcr.io/yourorg/embedded-dev:2026 steps: - uses: actions/checkout@v3 - name: Install PlatformIO CLI run: pip install --no-cache-dir platformio - name: Build Firmware run: pio run |
プルリクエストごとに自動ビルドが走り、失敗した場合は GitHub の Checks で即座に通知されます。
9. まとめ
- macOS は Homebrew によりすべてのツールをワンコマンドで取得可能。
- Windows + WSL2 では
usbipd-winと Linux 側usbipの組み合わせで ST‑Link／ESP‑PROG をシームレスに共有できる。 - Toolchain は公式ダウンロードと APT/PP‑A の二通りを提示し、将来のバージョン変動にも耐える構成にした。
- VS Code + Remote‑Containers で Docker コンテナ化すれば、環境汚染なしに統一された開発体験が実現できる。
- OpenOCD と Cortex‑Debug の設定例を示し、デバッグのハードルを低減した。
- CI/CD 用 Docker イメージと GitHub Actions で自動ビルドパイプラインを構築すれば、チーム開発やオープンソース公開も楽になる。
以上の手順に沿って環境を整えれば、2026 年時点でも 無料 OSS ツールだけ で組み込み C 言語開発がフルサイクル（コード → ビルド → 書き込み → デバッグ）できるようになります。ぜひ実際に手を動かし、問題があれば本稿のトラブルシューティング表をご参照ください。