Arduino App Lab 外部実行環境構築方法(忘備録)

UNO Qを、Cursorから”Hello World!”を実行するまでの手順です。この後、Arduino側処理との連携もまとまったら記述します。Qのpython環境はdocker化されていること、dockerからArduinoとの連携に必要な、最低限のライブラリをコピーすること、それらが要求しているモジュールをpipすること。ここら辺がポイントの模様です。どなたかのご参考になれば。

1. 現状のまとめ（アーキテクチャ）

デバイス: Arduino UNO Q (Linux搭載マイコンボード)
標準動作: – Arduino App Labは、UNO Q上のDockerコンテナ内でPython実行環境を構築する。
プログラム（main.py）やライブラリはコンテナ内の隔離された環境（/app）にある。
コンテナ内のPythonとMCU（マイコン側）は、Arduino_RouterBridge.h を介して内部シリアル通信を行っている。
課題: – ホストOS（SSH経由のCursor）には、ブリッジ用ライブラリ（arduino モジュール）が存在しないため、直接実行すると ModuleNotFoundError が発生する。

2. 対策のまとめ

App Labの「ガワ」を使わずに、CursorからPythonを実行するために以下の戦略をとった。

ライブラリの救出: Dockerコンテナ内にしかない arduino ライブラリの実体をホストOS側にコピーする。
依存関係の完全同期: コンテナ内のPython環境が保持しているパッケージリストを抽出し、ホスト側の仮想環境（vmenv）に再現する。
競合の回避: シリアルポートの占有を防ぐため、実行時はApp Labのコンテナを停止させる。

3. 実行したコマンド総括

A. ライブラリの抽出

# コンテナ内のシステムライブラリをホストへコピー
docker cp <CONTAINER_ID>:/usr/local/lib/python3.13/site-packages ~/ArduinoApps/libs/system_site_packages

# プロジェクトフォルダへarduinoモジュールを配置
cp -r ~/ArduinoApps/libs/system_site_packages/arduino ~/ArduinoApps/hgt_psms_01/python/

B. 依存環境の同期

# コンテナ内のパッケージリストを抽出
docker exec <CONTAINER_ID> pip freeze > requirements_full.txt

# 不要、またはビルドエラーが出るパッケージ（pyalsaaudio, PyAudio等）を削除後、インストール
pip install -r requirements_full.txt

C. 実行前のコンテナ停止

# 通信ポートを解放するためコンテナを止める
docker stop <CONTAINER_ID>

4. Pythonコードの構成

Cursorで作成する main.py は、以下の構造で動作する。

import sys
from arduino.app_utils import App  # コピーしたライブラリを読み込み

def loop():
    # Arduinoのピン制御やデータ取得ロジック
    pass

if __name__ == "__main__":
    # 内部ブリッジを初期化して実行
    App.run(user_loop=loop)

5. 注意点

ポートの占有: App Labアプリが「Run」状態のままだと、ホスト側からの実行はシリアルポート競合でエラーになる。
依存関係のビルド: pyalsaaudio などのC言語ベースのライブラリは、ホストOSに gcc や libasound2-dev がない場合インストールに失敗する。必要なければ requirements_full.txt から除外してよい。
MCUスケッチ: Pythonだけを動かしても、MCU側に RouterBridge スケッチが書き込まれていないと通信できない。一度App Labで「Run」して書き込んでおく必要がある。

6. 今後のメリット

Cursor AIの活用: プロジェクト内に arduino フォルダがあることで、CursorのAIがライブラリの定義を参照でき、正確なコード補完や提案が可能になる。
デバッグの高速化: App LabのGUIを経由せず、ターミナルから直接 python3 main.py で即座に実行結果を確認できる。

(実際に実行したコマンド＜予備)

  115  /bin/python3 /home/arduino/ArduinoApps/xxx_xxxx_01/python/main.py
  116  python3 -m venv ./vmenv
  117* 
  118  sudo python3 -m venv ./vmenv
  119  ls -al
  120  apt install python3.13-venv
  121  sudo apt install python3.13-venv
  122  python3 -m venv ./vmenv
  123  source ./vmenv/bin/activate
  124  python
  125  pip list
  126  pip install arduino-app-lab
  127  /bin/python3 /home/arduino/ArduinoApps/xxx_xxxx_01/python/main.py
  128  ls -al
  129  deactivate 
  130  cd ..
  131  cd xxx_xxxx_01/
  132  ls- la
  133  ls -al
  134  source ./vmenv/bin/activate
  135  ls
  136  ls -al
  137  mv ./arduino/ ./sketch/
  138  ls -al
  139  cd ..
  140  ls
  141  cd xxx_xxxx_01/sketch/
  142  ls -al
  143  mv ./arduino/ .../python
  144  mv ./arduino/ ../python
  145  cd ../python/
  146  ls -al
  147  /bin/python3 /home/arduino/ArduinoApps/xxx_xxxx_01/python/main.py
  148  pip install numpy pyserial pydantic requests
  149  /bin/python3 /home/arduino/ArduinoApps/xxx_xxxx_01/python/main.py
  150  pip list
  151  /home/arduino/ArduinoApps/xxx_xxxx_01/vmenv/bin/python /home/arduino/ArduinoApps/xxx_xxxx_01/python/main.py
  152  ls
  153  python ./main.py 
  154  pip install msgpack orjson pydantic-core anyio
  155  python ./main.py 
  156  pip install pyserial msgpack orjson pydantic pydantic-core anyio distro h11 httpcore httpx sniffio
  157  python ./main.py 
  158  pip install watchdog watchfiles uvicorn starlette fastapi python-socketio simple-websocket
  159  ls -al
  160  pip install -r requirements_full.txt
  161  python ./main.py 
  162  history

[Arduino]Arduino UNO QをCursorから動かす