StampFly Ecosystem

Note: English version follows after the Japanese section. / 日本語の後に英語版があります。

自分の手で、ドローンの飛行制御を作りたいあなたへ

StampFly Ecosystem は、ドローン制御を学び、実装し、実験するための 教育・研究プラットフォームです。

「PID制御を教科書で学んだけど、実際に動くものを作りたい」 「姿勢推定アルゴリズムを自分で実装して試したい」 「研究用の飛行実験プラットフォームが欲しい」

そんなあなたのために、このエコシステムは存在します。

---

何ができるのか？

できること	内容
シミュレータで練習	実機がなくても、PC 上の 3D シミュレータで送信機を使った操縦を体験できる
実機での飛行体験	ファームウェアを書き込んだ StampFly を送信機で飛ばす。4 つの飛行モード（ACRO／STABILIZE／高度維持／位置保持）を搭載
センサー値の取得	IMU・気圧・ToF・オプティカルフローの値をリアルタイムに読み出し、表示・記録できる
コントローラからの指令の受信	送信機のスティック・ボタンの値を機体側で受け取り、自分のプログラムから使える
独自の飛行プログラムの作成	sf app new で自分のプロジェクトを作り、制御則や推定器を自分で書ける（→ 独自プログラム開発入門）
ブロックプログラミング	コードを書かずに、ブラウザでブロックを並べて飛ばせる（小中学生・入門者向け。sf blocks、→ ブロックプログラミングガイド）
飛行プログラムの SILS での検証	作成した飛行プログラムを SILS（Software In the Loop Simulation: ファームウェアそのものを PC 上で飛ばす試験）で、実機に書き込む前に確認できる

---

📦 インストール

コマンドライン（CLI）で導入してください。 GUI 版インストーラ「StampFly Setup」もありますが、 まだ動作の安定性を確認できていないため、以下の CLI 手順で進めてください。 GUI 版の説明は GUI インストーラガイド にあります。

手順はどの OS でも同じ 3 段階です。コードブロックは 1 つずつコピーして端末に貼り付け、 実行が終わるのを待ってから次のブロックに進んでください。

段階	内容
① 前提ツール	Git を入れる（Python は不要 — 専用の Python 3.12 と ESP-IDF v5.5.2 がインストーラによって自動導入される）
② 取得と導入	リポジトリを取得し、インストーラを実行する
③ 有効化と診断	開発環境を有効化し、sf doctor で確認する

専用の Python・ESP-IDF・ツール一式は SF_HOME（既定は Windows が C:\StampFly、 macOS/Linux が ~/.stampfly）に自己完結導入され、容量は合計で約 4〜6 GB です。 ダウンロードを含むため、時間とディスクに余裕のあるときに実行してください。 既存の ESP-IDF・システム Python をそのまま使いたい開発者向けの旧来モード （install.bat --use-existing-idf 等）もあります。詳細は セットアップガイド を参照してください。

Windows

コマンドプロンプト（CMD）で実行します。WSL は不要です。

① Git を導入（すでにあれば省略）。末尾の 2 つのオプションは、初回に出る利用規約への同意の質問を省くためのものです。 終わったら CMD を一度閉じて開き直します。

winget install Git.Git --accept-source-agreements --accept-package-agreements

② リポジトリを取得し、インストーラを実行。途中の質問には画面の指示に従って答えます。

git clone https://github.com/M5Fly-kanazawa/stampfly_ecosystem.git
cd stampfly_ecosystem
install.bat

③ 開発環境を有効化して診断。新しい CMD を開くたびに setup_env.bat を実行します。

setup_env.bat
sf doctor

→ Windows セットアップ（詳細・トラブル対応）

macOS

ターミナルで実行します。

① Homebrew を導入（すでにあれば省略）。Enter を押し、Mac のログインパスワードを入力します。 Xcode Command Line Tools が無い場合はここで一緒に導入されます。 終了時に「Next steps」として表示される、brew を PATH に追加するコマンドをそのままコピーして実行してください。

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

続けて、ビルドに必要なツールを入れます（Python は不要です）。

brew install cmake ninja dfu-util ccache

② リポジトリを取得し、インストーラを実行。途中の質問には画面の指示に従って答えます。

git clone https://github.com/M5Fly-kanazawa/stampfly_ecosystem.git
cd stampfly_ecosystem
./install.sh

③ 開発環境を有効化して診断。新しいターミナルを開くたびに source setup_env.sh を実行します。

source setup_env.sh
sf doctor

→ macOS セットアップ（詳細・トラブル対応）

Ubuntu

ターミナルで実行します（Ubuntu 22.04 LTS 以降）。

① Git・ビルドツールを導入（Python は不要です）。パスワードを求められたら入力します。

sudo apt update
sudo apt install -y git curl tar cmake ninja-build wget flex bison gperf ccache \
    libffi-dev libssl-dev dfu-util libusb-1.0-0

② リポジトリを取得し、インストーラを実行。途中の質問には画面の指示に従って答えます。

git clone https://github.com/M5Fly-kanazawa/stampfly_ecosystem.git
cd stampfly_ecosystem
./install.sh

③ 開発環境を有効化して診断。新しいターミナルを開くたびに source setup_env.sh を実行します。

source setup_env.sh
sf doctor

実機や送信機を USB で使うときは、シリアルポートの権限を一度だけ設定します（反映には再ログインが必要）。

sudo usermod -a -G dialout $USER

→ Linux セットアップ（詳細・トラブル対応）

sf doctor が問題なしと表示すれば導入完了です。 後で最新版に更新するときは sf upgrade を実行します（→ アップグレードガイド）。

---

🎮 まずはシミュレータで飛ばしてみよう！

実機がなくても大丈夫。 送信機（M5Stack AtomS3 + Atom JoyStick）と PC があれば、PC 上の 3D シミュレータでドローン操縦を体験できます。 シミュレータでは送信機を USB ゲームパッドとして使うので、先にファームウェアを書き込み、通信モードを USB HID に切り替えます。

① 送信機にファームウェアを書き込む（初回のみ）。送信機を USB ケーブルで PC につなぎ、開発環境を有効化した端末で実行します。

sf build controller
sf flash controller

② 送信機を USB HID モードに切り替える。送信機の画面での操作です。

手順	操作
1	画面（ボタン）を押してメニューを開く
2	右スティックの上下で Comm: ESP-NOW の行を選ぶ
3	右ボタン（モードボタン）を押すと Comm: UDP に変わる。もう一度押すと Comm: USB HID になり、送信機が自動で再起動する
4	再起動後、画面に = USB HID MODE = と表示されれば切替完了。PC にゲームパッドとして認識される

③ シミュレータを起動する。ブラウザが自動で開き、3D ビューが表示されます。スロットルをゆっくり上げると機体が浮き上がります。

sf sim run vpython

スティックの割り当て、地形の切替、うまく動かないときの対処は、シミュレータの使い方ページを参照してください。

→ シミュレータの使い方 | 送信機の使い方

---

🛸 実際に飛ばしてみよう

シミュレータで操縦に慣れたら、実機を飛ばします。機体（StampFly）へのファームウェア書き込み、送信機を実機操縦用の通信モードに戻す設定、機体と送信機のペアリングまでを行います。

① 機体にファームウェアを書き込む。機体を USB ケーブルで PC につなぎ、開発環境を有効化した端末で実行します。

sf build vehicle
sf flash vehicle

② 送信機を ESP-NOW モードに戻す。シミュレータ用に USB HID にした通信モードを、実機と通信する ESP-NOW に戻します。

手順	操作
1	画面（ボタン）を押してメニューを開く
2	右スティックの上下で Comm: USB HID の行を選ぶ
3	右ボタン（モードボタン）を 1 回押すと Comm: ESP-NOW に変わり、送信機が自動で再起動する

③ 機体と送信機をペアリングする（初回のみ。以後は電源を入れるだけで自動接続します）。

手順	操作
1	送信機の電源を切り、画面（ボタン）を押したまま電源を入れる。画面に候補機体の一覧画面（=== PAIRING ===）が表示される
2	機体の電源を入れ、機体のボタンを約 3 秒長押しする。LED が青の速い点滅になり、送信機を探し始める
3	送信機の画面に機体が「MAC下4桁 + チャンネル」の一覧として表示されたら、対象の機体を選んで画面のボタンで確定する。機体から応答があればペアリング完了

ペアリング情報を持たない機体は、電源を入れるだけで自動的に探索を始めます。手順 2 の長押しは、以前の情報を消して確実に探索を始めさせるための操作で、別の送信機と組み替えるときにも使います。教室で複数組が同時にペアリングしても、一覧から選ぶ操作が必須なので取り違えません。機体に MAC 下4桁のラベル（sf monitor で mac コマンドを実行すると確認できる）を貼っておくと、一覧との照合がしやすくなります。詳しい手順は送信機の使い方を参照してください。

飛行前の確認とスティック操作（アーム・離陸・着陸・飛行モードの切替）は、操縦方法のページを参照してください。

→ 操縦方法 | 送信機の使い方

---

🎓 ワークショップで本格的に学ぶ

実機で飛ばせたら、目的に合った講習資料で制御の中身に進みましょう。これまでに実施した 3 つの講習のスライドと手順書を公開しています。

This is the beginning of the README. Read the rest at the original. Read the full README ↗