Meshtastic ファームウェアソースコード実践チュートリアル

このチュートリアルは、Meshtastic ファームウェアのソースコードをこれから触り始めるユーザーを対象としています。Windows と macOS の両方で共通するワークフローを含んでいます。目的はシンプルで、公式リポジトリをクローンし、ビルドを一度成功させ、UI を 1 か所だけ簡単に変更し、その変更済みファームウェアをデバイスに書き込んで動作を確認することです。

すでに Git、Python、または PlatformIO に慣れている場合は、該当するセクションを飛ばして、ハンズオンのパートに直接進んでも構いません。

ヒント

このガイドには、Windows と macOS の両方で共通して使えるコマンドを掲載しています。スクリーンショットの多くは Windows 環境で撮影していますが、macOS での全体的なワークフローもほぼ同じです。

事前準備

始める前に、次のツールを用意してください。

Git
Python 3
VS Code
PlatformIO

1. Git をインストールする

Windows
macOS

公式の Git for Windows ダウンロードページを開きます。

Git for Windows

ページを開くと、通常はインストーラのダウンロードが自動的に始まります。ダウンロードが完了したら、インストーラをダブルクリックしてセットアップウィザードに従います。

インストール中で最も重要なステップは PATH 環境変数の調整 です。次を選択してください。

Git from the command line and also from 3rd-party software

その他のオプションは、通常はデフォルトのままで問題ありません。そのまま Next をクリックし続けてください。

インストールが完了するまで待ちます。

インストール後、現在開いている PowerShell と VS Code のターミナルウィンドウをすべて閉じてから、新しく PowerShell を開き、次を実行します。

& "C:\Program Files\Git\cmd\git.exe" --version

Git のバージョン番号が表示されれば、Git は正常にインストールされています。

git コマンドがまだ使えない場合

まず PowerShell で次のコマンドを実行し、Git のデフォルトのインストールパスを確認できます。

$gitCmd = "C:\Program Files\Git\cmd"
$gitBin = "C:\Program Files\Git\bin"
Write-Host $gitCmd
Write-Host $gitBin

その後、Git をシステム環境変数に手動で追加します。

GUI での修正手順

Win を押す
「Edit the system environment variables」を検索
開いて Environment Variables をクリック
System variables の下にある Path を探す
Edit をクリック
New をクリックして、次の 2 つのパスを追加します。

C:\Program Files\Git\cmd
C:\Program Files\Git\bin

最後まで OK をクリックして保存します

保存後、次の操作も必要です。

すべての PowerShell ウィンドウを閉じる
PowerShell を再度開く

そのうえで次を実行します。

git --version

バージョン番号が表示されれば、インストールは完了です。

macOS では Git をインストールする方法が複数ありますが、Homebrew を使うのが一般的に最も簡単です。

まず Command Line Tools をインストールします。

xcode-select --install

Homebrew がまだインストールされていない場合は、先にインストールします。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Git をインストールします。

brew install git

インストールされたバージョンを確認します。

git --version

ターミナルですでに有効な Git バージョンが返ってくる場合は、改めてインストールする必要はありません。

Git のユーザー情報を設定する

次に、Git のユーザー情報を設定します。サンプルの値を自分の名前とメールアドレスに置き換えてください。

git config --global user.name "your name"
git config --global user.email "your [email protected]"

その後、次を実行します。

git config --global --list

設定が反映されていることを確認します。

2. Python 3 をインストールする

コマンドラインから Python をインストールする

Windows
macOS

ターミナルで次のコマンドを実行します。

winget search --id Python.Python.3.13 --source winget
winget install -e --id Python.Python.3.13 --source winget

最初のコマンドで Python が見つかる場合、通常は 2 つ目のコマンドでそのままインストールされます。

インストール後、ターミナルを閉じて再度開き、次を実行します。

python --version
pip --version

バージョン番号が表示されれば、Python と pip を使用する準備が整っています。

macOS には、すでに Python 環境が含まれていることがよくあります。新しいバージョンをインストールする前に、python3 と pip3 がすでに利用可能かどうかを確認してください。

python3 --version
pip3 --version

利用できない場合、またはより新しいバージョンが必要な場合は、Homebrew で Python をインストールします。

brew install python

インストール後、ターミナルを開き直して次を実行します。

python3 --version
pip3 --version

python や pip を使いたい場合は、自分でシェルエイリアスを設定しても構いません。ただし macOS では、python3 と pip3 を使う方が一般的により確実です。

3. PlatformIO をインストールする

このステップは、PlatformIO が多くの依存関係を自動的にダウンロードし、インストールに時間がかかるため、初心者には少しとっつきにくく感じられるかもしれません。インストール中にエラーが出た場合は、基本的には焦らず、1 つずつ問題を切り分けて対処するのがよいでしょう。エラーメッセージの確認には、AI ツールを活用すると時間の節約にもなります。

VS Code の Extensions マーケットプレイスで PlatformIO を検索し、インストールします。

インストール後、左側のツールバーにアリの形をしたアイコンが表示されるはずです。

4. Meshtastic ファームウェアリポジトリをクローンする

Meshtastic 公式のファームウェアリポジトリは meshtastic/firmware です。

Windows
macOS

作業ディレクトリのターミナルで次のコマンドを実行します。

git clone https://github.com/meshtastic/firmware.git
cd firmware
git submodule update --init

プロジェクトディレクトリが別のドライブや別のパスにある場合は、先にその場所へ移動してください。

出力が上のスクリーンショットと同様であれば、リポジトリは正常にクローンされています。

作業ディレクトリのターミナルで次のコマンドを実行します。

cd ~/workplace
git clone https://github.com/meshtastic/firmware.git
cd firmware
git submodule update --init

まだ ~/workplace が存在しない場合は、先に作成します。

mkdir -p ~/workplace

コマンドが問題なく完了すれば、リポジトリは正常にクローンされています。

5. ハンズオン実践

この段階では、まだコードの編集を急がないでください。まずはプロジェクトが一通りビルドプロセスを最後まで正常に通過できることを確認します。

最初は次の 3 つのタスクから始めることをおすすめします。

firmware を開く
platformio.ini を確認する
対象ボード用のビルド環境を探す

重要なポイントが 1 つあります。ルートの platformio.ini だけに注目しないでください。実際には、次のような追加の設定ファイルを include しています。

extra_configs =
    variants/*/*.ini
    variants/*/*/platformio.ini
    variants/*/diy/*/platformio.ini

つまり、実際のボードレベルの環境定義は、通常 variants/.../platformio.ini 以下に配置されています。

対象ボードを特定する際は、次の 2 つのディレクトリに特に注意してください。

variants/
boards/

ここでは、例として Wio Tracker L1 Pro をターゲットにします。

これにより、Meshtastic において Wio Tracker L1 / L1 Pro のビルドターゲットが seeed_wio_tracker_L1 であることが分かります。

最小限の変更内容のまとめ

最小限のエンドツーエンドの練習だけを完了したい場合は、次のキーとなるステップに集中してください。

Git、Python 3、VS Code、PlatformIO をインストールする。
meshtastic/firmware リポジトリをクローンし、サブモジュールを初期化する。
pio run -e seeed_wio_tracker_L1 を使って、元のプロジェクトが正常にビルドできることを確認する。
src/graphics/SharedUIDisplay.cpp 内の表示ロジックを変更する。
ファームウェアを再ビルドし、生成された UF2 ファイルをデバイスに書き込んで動作を確認する。

ステップ 1: プロジェクトが正常にビルドできることを確認する

ここでは、ビルドに PlatformIO Core CLI を使用します。

最初のビルドでは、次のコマンドを実行することをおすすめします。

Windows
macOS

cd D:\workplace\firmware  # Adjust to your actual project path
pio run -e seeed_wio_tracker_L1

cd ~/workplace/firmware  # Adjust to your actual project path
pio run -e seeed_wio_tracker_L1

画面が上のスクリーンショットと同じような状態になれば、ビルドプロセスは正しく開始されています。最初のビルドは時間がかかることが多いので、気長に待ちましょう。

ビルドが失敗した場合

ビルドが失敗したときは、まず PlatformIO に現在の環境で必要な依存関係をインストールさせることができます。

Windows
macOS

cd D:\workplace\firmware  # Adjust to your actual project path
pio pkg install -e seeed_wio_tracker_L1

cd ~/workplace/firmware  # Adjust to your actual project path
pio pkg install -e seeed_wio_tracker_L1

この方法にはいくつかの利点があります：

依存関係のみをインストールし、すぐにフルビルドを開始しません。
どのパッケージが問題を引き起こしているかを確認しやすくなります。
エラーメッセージがより絞り込まれ、トラブルシューティングしやすくなります。

依存関係のインストールが完了したら、次を実行します：

Windows
macOS

pio run -e seeed_wio_tracker_L1 -v

pio run -e seeed_wio_tracker_L1 -v

依存関係のインストールが完了したら、通常のビルドをもう一度実行します：

Windows
macOS

pio run -e seeed_wio_tracker_L1

pio run -e seeed_wio_tracker_L1

この時点でビルドが通れば、ファームウェア出力は正常に生成されています。

ステップ 2: コードを変更する

実践 1: UI 表示を変更する

まず、ボードレベルの設定から表示の実装をトレースしていきます。最初に次を確認できます：

variants/nrf52840/seeed_wio_tracker_L1/platformio.ini
variants/nrf52840/seeed_wio_tracker_L1/variant.h

これらの設定ファイルから、L1 が HAS_SCREEN と USE_SSD1306 を定義していることが分かります。つまり、スクリーンなし構成でも E-Ink ソリューションでもなく、標準的な OLED ディスプレイパイプラインを使用しているということです。

さらに表示ロジックを追っていくと、関連コードのほとんどは次の場所にあります：

src/graphics/
src/graphics/draw/

具体的にどう変更するかは、ソースコードを読む力に依存します。ここではごく簡単な例として、ホーム画面の UI を変更するところから始めます。

変更 1: バッテリーテキストの右端を記録する

Before / After

// Before
int batteryX = 1;
int batteryY = HEADER_OFFSET_Y + 1;

// After
int batteryX = 1;
int batteryY = HEADER_OFFSET_Y + 1;
int batteryTextEndX = batteryX - 1;

src/graphics/SharedUIDisplay.cpp:157

ここでは batteryTextEndX を追加し、バッテリー残量テキストの終端位置を記録しています。これにより、後でバッテリー情報の後ろにカスタムテキストを追加しやすくなります。

変更 2: バッテリー残量描画時に右端境界を計算する

// Before
if (chargePercent != 101) {
    char chargeStr[4];
    snprintf(chargeStr, sizeof(chargeStr), "%d", chargePercent);
    int chargeNumWidth = display->getStringWidth(chargeStr);
    display->drawString(batteryX, textY, chargeStr);
    display->drawString(batteryX + chargeNumWidth - 1, textY, "%");
    if (isBold) {
        display->drawString(batteryX + 1, textY, chargeStr);
        display->drawString(batteryX + chargeNumWidth, textY, "%");
    }
}

// After
if (chargePercent != 101) {
    char chargeStr[4];
    snprintf(chargeStr, sizeof(chargeStr), "%d", chargePercent);
    int chargeNumWidth = display->getStringWidth(chargeStr);
    int percentWidth = display->getStringWidth("%");
    display->drawString(batteryX, textY, chargeStr);
    display->drawString(batteryX + chargeNumWidth - 1, textY, "%");
    if (isBold) {
        display->drawString(batteryX + 1, textY, chargeStr);
        display->drawString(batteryX + chargeNumWidth, textY, "%");
    }
    batteryTextEndX = batteryX + chargeNumWidth + percentWidth - 1 + (isBold ? 1 : 0);
} else {
    batteryTextEndX = batteryX - 1;
}

src/graphics/SharedUIDisplay.cpp:204

このコードはバッテリー残量描画ロジックの内部にあります。バッテリーレベルを通常どおり表示するだけでなく、テキスト領域の右端境界も計算し、その後にカスタムラベルを配置できるようにしています。

変更 3: 右側のアイコン領域用に境界を確保する

// Before
int iconRightEdge = timeX - 2;

// After
int iconRightEdge = timeX - 2;
int headerLabelRight = timeX - 4;

src/graphics/SharedUIDisplay.cpp:263

この部分は、右側の時刻、メール、ミュートなどのアイコンが使用する領域を処理します。ここでは headerLabelRight を追加し、中央テキストの最大右端境界を制限して、右側コンテンツとの重なりを防いでいます。

変更 4: タイトルが空のときにカスタムラベルを描画する

// Newly added core logic
#if defined(SEEED_WIO_TRACKER_L1) && !defined(SEEED_WIO_TRACKER_L1_EINK)
if (titleStr && titleStr[0] == '\0') {
    static const char *yclLabel = "made by AE";
    int labelWidth = display->getStringWidth(yclLabel);
    int labelLeft = batteryTextEndX + 4;
    if (labelLeft + labelWidth <= headerLabelRight) {
        int labelX = labelLeft + ((headerLabelRight - labelLeft) - labelWidth) / 2;
        display->drawString(labelX, textY, yclLabel);
        if (isBold)
            display->drawString(labelX + 1, textY, yclLabel);
    }
}
#endif

src/graphics/SharedUIDisplay.cpp:350

ここが変更の中核となるロジックです。SEEED_WIO_TRACKER_L1 のみに適用され、E-Ink バリアントは明示的に除外しています。バッテリー情報と時刻表示の間の空白に、made by AE というテキストを中央揃えで表示します。

変更 5: 時刻が表示されない分岐を処理する

// Add the same boundary control for the no-time branch
int iconRightEdge = screenW - xOffset;
int headerLabelRight = screenW - xOffset - 2;

src/graphics/SharedUIDisplay.cpp:377

ここは時刻値が表示されない場合に使われる分岐です。同じ境界制御をここにも追加する必要があります。

#if defined(SEEED_WIO_TRACKER_L1) && !defined(SEEED_WIO_TRACKER_L1_EINK)
        if (titleStr && titleStr[0] == '\0') {
            static const char *yclLabel = "made by AE";
            int labelWidth = display->getStringWidth(yclLabel);
            int labelLeft = batteryTextEndX + 4;
            if (labelLeft + labelWidth <= headerLabelRight) {
                int labelX = labelLeft + ((headerLabelRight - labelLeft) - labelWidth) / 2;
                display->drawString(labelX, textY, yclLabel);
                if (isBold)
                    display->drawString(labelX + 1, textY, yclLabel);
            }
        }
#endif

src/graphics/SharedUIDisplay.cpp:426

これは、時刻なし分岐で made by AE を描画する実装です。

完全なコードはこちらで確認できます：

📎SharedUIDisplay.cpp

ステップ 3: 自分のファームウェアをビルドする

変更が終わったら、プロジェクトルートに戻り、同じターゲットを再度ビルドします：

Windows
macOS

cd D:\workplace\firmware  # Adjust to your actual project path
pio run -e seeed_wio_tracker_L1

cd ~/workplace/firmware  # Adjust to your actual project path
pio run -e seeed_wio_tracker_L1

表示ロジックは変更しましたが、ビルドターゲットは同じままです：

seeed_wio_tracker_L1

ビルドが成功すると、出力は通常次の場所にあります：

Windows
macOS

D:\workplace\firmware\.pio\build\seeed_wio_tracker_L1\

~/workplace/firmware/.pio/build/seeed_wio_tracker_L1/

更新されたことを確認すべきファイルは次のとおりです：

firmware-seeed_wio_tracker_L1-*.uf2

6. ファームウェアを書き込む

ビルドが完了したら、公式の書き込みページを開きます：

Meshtastic Flasher

ほとんどの場合、最初に消去操作を行う必要があります。

その後、先ほどビルドしたファームウェアファイルを選択し、デバイスに書き込みます。

これで、Meshtastic ソースコードの実践演習は完了です。環境構築、リポジトリのクローン、ボード設定の調査、ファームウェアのコンパイル、表示ロジックの変更、最終的な書き込み検証まで、一連のワークフローを一通り体験しました。

さらに先に進みたい場合は、次のような方向性を引き続き探求できます：

ホーム画面上の要素をさらに変更する
ボタン、GPS、Bluetooth などのモジュールの動作を調整する
自分のボード用に独立した variant を追加する
src/、variants/、boards/ 間の関係を引き続きトレースする

よくある問題

git コマンドが使用できない

Windows の場合、まず Git が PATH に追加されているか確認します。
macOS の場合、まず git --version を実行します。システムから Command Line Tools のインストールを求められたら、指示に従ってください。

python3 または pip3 が使用できない

Windows の場合、Python が PATH に追加されているか確認するか、ターミナルを開き直して再試行します。
macOS の場合、まず python3 / pip3 が既に存在するか確認し、必要な場合にのみ Homebrew で Python をインストールします。

pio コマンドが使用できない

まず pio --version を実行します。
それでもコマンドが使用できない場合は、VS Code とターミナルを再起動してから再試行します。
必要であれば、PlatformIO 拡張機能を再インストールし、PlatformIO Core が正しく初期化されていることを確認します。

git submodule update --init の後もコードが不完全に見える

まず、自分が firmware リポジトリのルートディレクトリにいることを確認します。
ネットワーク接続が不安定な場合は、次を使って再試行します：

git submodule update --init --recursive

最初のビルドに時間がかかりすぎる

最初のビルドで多くの依存関係をダウンロードするのは正常です。
あまりにも長時間止まっているように見える場合は、まずパッケージを個別にインストールしてみてください：

pio pkg install -e seeed_wio_tracker_L1

その後、もう一度ビルドを実行します。

事前準備​

1. Git をインストールする​

2. Python 3 をインストールする​

3. PlatformIO をインストールする​

4. Meshtastic ファームウェアリポジトリをクローンする​

5. ハンズオン実践​

6. ファームウェアを書き込む​

よくある問題​