本ドキュメントの目的

アールティ版ｽﾀｯｸﾁｬﾝ(以降RT版とする）からModdable SDK(以降Moddableとする）を使い始める人向けに、ソフトウェアの土台となるModdableへの理解を深めることで、RT版ソフトウェア開発に向けた基礎を身につける。

想定とする対象者

Javascript自体の文法などの解説は行わないので、プラットフォーム問わずJavascriptでの開発経験が望ましいです。
Moddableには豊富なサンプルが用意されているので、まずはサンプルを動かし合わせてドキュメントを確認することをオススメします。
RT版をお持ちでない方も、Moddaleに対応したデバイス（M5Stackなど）を持っていれば同様に読み進めることができます。

前提

Moddableの開発環境構築はガイドに従い完了しているものとします
Moddableについての解説を主とするため、RT版のホスト実装詳細の解説や具体的なModsの実装方法は対象外とします
Moddableのドキュメントとして、日本語訳プロジェクトであるmoddable-jpを参照しますが、RT版はModdable v4.1が対象となっているため、ドキュメント記載と実態に差異が発生することは御了承下さい

Moddableとは

Moddableについて、どういったことができるのか、ソースツリー構成などといった概要が記載されています。
Moddaleで出来ることは、すなわちRT版で出来ることになってくるので、まずは一読をお願いします。

サンプルを動かしてみよう

ｽﾀｯｸﾁｬﾝの顔部分となっているM5StackCoreS3もModdableで動作するデバイスの1つであるので、Moddableが用意している多くのサンプルが動作します。実際にサンプルを動かすことによりModdableで出来ることを確認してみましょう。

Moddableのインストール先は、MODDABLEの環境変数に設定されていますので、インストールディレクトリに移動しましょう。以降ディレクトリの起点はこのインストールディレクトリとします。

cd $MODDABLE

Hello, world

まずは一番シンプルとなる、コンソールに文字を出すものを動かしてみます。

対象となるサンプルのフォルダに移動し、

cd examples/helloworld/

サンプルのビルドとファームウェアの転送を行うコマンドを実行します

mcconfig -d -m -p esp32/m5stack_cores3

アプリごとに初回ビルド時は、ファームウェアを一からビルドするため時間がかかりますが、コード修正後の差分ビルド時は時間が短くなります。

無事ビルドが完了すると、デバイスから起動音が鳴りますが、デバイスの画面には何も表示されません。
その代わりに、xsbugというModdableのデバッガーが起動していることが確認できます。

このキャプチャでは、debugger;というステートメントでデバッガーが処理停止をしています。
続いて左上の▶️ボタンを押下すると処理が再開し、CONSOLE欄にHello, world - sample と表示されます。

trace関数がブラウザやNode.jsで言うところのconsole.log相当の機能をします。

Timer処理

一定時間後や一定時間間隔で処理を実行する場合には、setIntervalの代わりにTimerモジュールを使用します。

cd examples/base/timers
mcconfig -d -m -p esp32/m5stack_cores3

Timerモジュールを始めたとした、実デバイスに依存しない基本的な処理を行うモジュール群については、以下ドキュメントを参照

画面描画処理

ここまではコンソール表示しかしておらず、デバイスを活用できていないので、実際にデバイスの画面にサンプルとして、Commodettoというグラフィックライブラリを見てみましょう。
ModdalbeにはPiuというGUIを構築するためのフレームワークも用意されていますが、ｽﾀｯｸﾁｬﾝでは、細かな画面描画の制御を必要としているためCommodettoを使用しています。

cd examples/commodetto/progress
mcconfig -d -m -p esp32/m5stack_cores3

目まぐるしくプログレス処理が描画されていることが確認できます。

タッチ処理

M5StackCoreS3の画面はタッチパネルにもなっているので、タッチ処理も実装ができます

cd examples/commodetto/mini-drag
mcconfig -d -m -p esp32/m5stack_cores3

Commondettoには他にも様々なサンプルが用意されているので、色々と動かし対応するドキュメントを確認してみましょう。

ネットワーク通信(HTTP)

ここではJavaScript経験者には馴染み深いfetchを使ったHTTP通信を使用してみましょう。

cd examples/io/tcp/fetch
mcconfig -d -m -p esp32/m5stack_cores3 ssid="<SSID>" password="<PASSOWRD>"

ここではデバイスがネットワークに接続して通信するため、<SSID>および<PASSWORD>にはご自身の環境のWiFiアクセスポイントの設定をしてください。
WiFiは2.4GHzしか繋がらないので注意

xsbugのコンソール欄にはWifiに接続できたことおよび、HTTPレスポンスが表示されているかと思います。

HTTPS通信も可能ですが、容量節約のため全ての証明書を搭載していないため、証明書エラーが出た場合はコンソール内容に従い、証明書ファイルの格納が必要となります。

サンプルはまだまだあるよ

まずはｽﾀｯｸﾁｬﾝに関連しそうな機能をいくつか取り上げてサンプルを動かしてみました。

別途センサー類が必要だったりと全てのサンプルが動くわけではありませんが、最小限のコードから構成されたサンプルを動かすことがModdableを理解することへの近道だと考えています。

Moddableのコマンドラインツール

ｽﾀｯｸﾁｬﾝではnpm runコマンドを使いビルドやデプロイを行っていますが、その実態としてはこれまでサンプルを動作させるのに使ってきたmcconfigコマンドを実行していることになります。

firmware/package.jsonからの抜粋

 "scripts": {
    "build": "cross-env npm_config_target?=esp32/m5stack cross-env-shell mcconfig -d -m -p \\$npm_config_target -t build ./stackchan/manifest_local.json",
    "bundle": "mcbundle -d -m ./stackchan/manifest.json",
    "deploy": "cross-env npm_config_target?=esp32/m5stack cross-env-shell mcconfig -d -m -p \\$npm_config_target -t deploy ./stackchan/manifest_local.json",
    "debug": "cross-env npm_config_target?=esp32/m5stack cross-env-shell mcconfig -d -m -p \\$npm_config_target ./stackchan/manifest_local.json",
    "mod": "cross-env npm_config_target?=esp32/m5stack cross-env-shell mcrun -d -m -p $npm_config_target",

cross-envはnpm runをLinux/MacおよびWindows環境で動かすためものですが、基本的には
mcconfig -d -m -p <PLATFORM> -t <TARGET> <PATH_TO_MANIFEST> の構成となっています。

<PLATFORM>は対象となるデバイスで、これまでesp32/m5stack_cores3`を指定してきました。

<TARGET>はbuild, deploy, xsbug, cleanなどのビルドターゲットを指定します。これまでサンプルを動かしたように未指定の場合は、ビルド〜ファームウェア転送まで全て一連で行います。

<PATH_TO_MANIFEST> は対象アプリの設定となるマニフェストファイルのパスを指定します。未指定の場合は現在フォルダのmanifest.jsonを探すので、サンプル動作でも特に指定は不要でした。

サンプルを動かす際には、画面の向きを変えることや、Wifiの設定のように設定値を渡すこともできるので、以下のmcconfigのセクションを確認することで、どういった実行方法があるのかが確認できます。

マニフェストファイルについて

Moddableで動作するアプリケーションにはマニフェストファイルが必要で、どういったモジュールを含めるのかや、デバイスやドライバのピンアサインなどビルド時に向けた設定をします。

Modsについて

Moddableの特徴として、Modsという機能を利用してホストアプリケーションに新規機能を追加することができます。
ｽﾀｯｸﾁｬﾝでもこれを採用しており、ホストアプリケーションに顔の描写やサーボーの制御といった基本的には動作モジュールを定義し、ユーザはModとして独自のアプリケーション機能を追加することを目指しています。

Modsにおいて知っておくべきことは、Modsで作成したコードはJavaScriptのバイトコードとしてデバイスに転送されるため、C言語のようなネイティブコードを含めることができないことです。ｽﾀｯｸﾁｬﾝホストではModdableで提供される多くのモジュールをインクルード済みであるため、Modsでも気にせず使用可能な場合が多いですが、Mods側で新規に使用したいモジュールがネイティブコードを含む場合には、ホスト側にインクルードすることの検討が必要となります。

環境構築の補足

ｽﾀｯｸﾁｬﾝの環境構築では、npm run setupから実行されるxs-devというModdableの環境構築自動化ツールを用いて実行されます。

xs-devではホストOSごとに沿って以下手順が自動的に実行されます。

Moddableのインストール

ESP-IDF(ESP32開発環境）のインストール

どういったものがインストールされているのか、あるいは環境面でトラブルが発生した場合にはこれらのドキュメントを確認すると良いでしょう。

終わりに

ここまで駆け足ながらにサンプルの動作とドキュメントを中心にModdableを説明してきました。
まだまだカバーすべき内容は多いですが、この記事を通じてModdableを理解し、ｽﾀｯｸﾁｬﾝ開発へ繋がれば幸いです。