Luaスクリプト入門
もくじ
Luaスクリプトとは
Luaスクリプトとは、プログラミング言語のひとつで、OpenTX (Version 2.0.0以降) またはEdgeTX搭載のプロポで動作させることができます。これは中間言語方式のインタープリター言語で、文法はJavaやJavaScriptに類似しており、これらの言語の経験者は簡単にコーディングすることができます。 ソースコードはテキストファイルで作成し、SDカードの"SCRIPTS"フォルダの下の各フォルダに格納し、OpenTX/EdgeTXプロポの画面で入出力パラメーターや実行タイミング(起動トリガー)を指定します。 言語仕様の詳細は、 プログラミング言語 Lua オフィシャルサイト で読むことができます。 また、OpenTX上でのLuaスクリプトの作成・使用方法、APIなどについては EdgeTX Lua Reference Guide, OpenTX 2.3 Lua Reference Guide で読むことができます。
プログラミング言語 Lua オフィシャルサイト
EdgeTX Lua Reference Guide
OpenTX 2.3 Lua Reference Guide
Luaスクリプトのサンプル
OpenTX/EdgeTXプロポをお持ちの方は、Luaスクリプトのサンプルソースとその動作をすぐに試すことができます。 ドローンのモデルを新規作成 するときに、最初に「Plane」「Delta」「Multi」を選択するウイザード画面が開きますが、このウイザードがLuaスクリプトで書かれています。 そしてこのソースコードが、SDカードイメージの /SCRIPTS/WIZARD フォルダに格納されています。 "wizard.lua"が最初に起動するスクリプトで、「Multi(マルチローター)」を選択したときに呼び出されるのが"multi.lua"です。 JavaやJavaScriptの経験者であれば、これらをテキストエディタで開くと、Luaがどんな言語で、どんなことができるかが、ある程度見当つくと思います。また、 Introduction To OpenTX Lua Scripts (RCdiy) では、いくつかのサンプルコードが公開されています。 サンプルコードと、それをプロポに設定する方法を読むことができます。
Introduction To OpenTX Lua Scripts (RCdiy)
Luaスクリプト開発ツール
Luaスクリプトの統合開発環境(IDE:Integrated Development Environment)として有名なのが ZeroBrane です(USD24.00のシェアウェア)。 これはテキストエディタ、コード補完、シンタックスハイライト、ライブコーディング、コードアナライザー、およびデバッグサポート機能を備えた軽量のLua IDEです。 MacOS(10.9以降)、 Windows(32bit)、Linux 上で動作します。また、 OpenTX Companion, EdgeTX Companion にも送信機シミュレータが搭載されており、Luaスクリプトを実行させることができます。 Luaデバッグスクリーンを開くと、スクリプトの出力結果や、クラッシュ発生場所を知ることができます。
ZeroBrane オフィシャルサイト
ZeroBrane ダウンロードページ
OpenTX Companionのインストール方法
EdgeTX Companionのインストール方法
Luaスクリプトの種類
ユーザーがOpenTX/EdgeTXプロポ上に作成できるLuaスクリプトには、以下のような種類があります。| 種類 | 実行 | モデルあたり 最大数 | SDカード内の 格納フォルダー | 概要 |
|---|---|---|---|---|
| Mix | 自動 | 7 | /SCRIPTS/MIXES | プロポの MIXS画面 に代わる処理を記述します。モデルを選択したときに読み込まれ、繰り返し自動実行されます。ユーザーのスイッチ操作などを読んだり、プロポの画面へ情報を表示することはできません。処理時間は最小限とし、約30ms以内に完了する必要があります。モデルの「CUSTOM SCRIPTS」画面で指定します。 |
| Telemetry | 自動 | 3 | /SCRIPTS/TELEMETRY | 機体からのテレメトリーデータ等を加工し、プロポのメイン画面(カスタムテレメトリー画面)へ表示する処理を記述します。モデルを選択したときに読み込まれ、繰り返し自動実行されます。一つのスクリプトを複数のモデルに割り当てることができます。モデルの DISPLAY画面 で指定します。 |
| One-Time | 手動 | - | どこでも可 (/SCRIPTS/TOOLSの下が推奨) |
ユーザーがRADIO(SYSTEM)メニューの[SD-HC CARD/SD CARD]画面からスクリプトファイルを選択したときに起動し、スクリプトが0以外の値をreturnしたとき、またはユーザーが[EXIT]ボタンを長押ししたときに停止します。
このスクリプトの動作中は、Mix, Telemetry, Function スクリプトは一時停止されます。
/SCRIPTS/TOOLSフォルダの下に格納したスクリプトは、RADIO(SYSTEM)メニューの[TOOLS]画面からでも起動することができます。 |
| Function | 手動 | - | /SCRIPTS/FUNCTIONS | プロポのスイッチが操作されたときに動作させたい処理を記述します。スクリプトに関連付けられたスイッチで、指定された状態が続く限り、繰り返し実行されます。プロポの画面へ情報を表示することはできません。モデルの SPECIAL FUNCTIONS / GLOBAL FUNCTIONS 画面で指定します。 |
| Wizard | 自動 | - | /SCRIPTS/WIZARD | プロポで新しい「モデル」を作成するときに動作するウィザード画面です。OpenTX/EdgeTX(SDカードイメージ)にプリインストールされています。One-Timeスクリプトの一種です。 |
- このほかに、カラーディスプレイ／タッチパネルを搭載したプロポだけで使用できる Widget, Themeスクリプトというものもあります。
- Mix, Telemetryスクリプトは、プロポの起動時またはモデルの切り替え時に読み込まれます。 そしてプロポのメインループのなかから継続的に呼び出され続けます。 ただしエラーが発生したり、実行時間または使用メモリ量が許容値を超えた場合は、実行が中断されます。 このため、このスクリプトを使って飛行そのものの制御を行うことは避けるべきです。 なお、Mix, Telemetryスクリプトのファイル名は 英数6文字 + 拡張子(".lua")でなければなりません。
Widget, Themeスクリプト関連情報
Widget Scripts (OpenTX)
Widget Scripts (EdgeTX)
OpenTX widgets (github)
EdgeTX themes (github)
Betaflight Luaスクリプト
対応するテレメトリー機能を搭載した、Betaflightファームウェアを採用する受信機は、プロポからPID値やVTXの設定を変更することができます。 プロポに Betaflight TX Lua Scripts をインストールして使用します。
Betaflight TX Lua Scripts (github)
Setup Betaflight LUA Script on OpenTX Radios (oscarliang)
Mixスクリプトの書き方
プロポの MIXS画面 に代わる処理を記述します。 1モデルあたり最大7つのMixスクリプトを設定することができます。 プロポのMIXS画面では指定できないような、複雑な混合処理を記述することができます。 入力データには、MIXS画面でSourceとして選択可能なスティック、スイッチ、ダイアル(Pot:Potentiometer)、論理スイッチ、他のMixスクリプトの出力、そしてテレメトリーやチャンネル入力、定数などが指定できます。 出力データは変数として出力され、MIXS画面でSourceとして利用することが可能です。構造
Mixスクリプトには、最低以下の5つの文／関数の定義が必要です。
- Input Table
- 入力データを定義します。最大6個まで定義できます。
- Output Table
- 出力データを定義します。最大6個まで定義できます。省略可能です。
- Init Function
- プロポ起動時またはモデル切り替え時に、最初に1回だけ実行される、初期設定処理を記述します。省略可能です。
- Run Function
- メインの処理を記述します。プロポの制御ループの中で繰り返し実行されます。
- Return Statement
- 上に示した4つの文／関数が、実際のコードのどの部分に適合するかを記述します。
Input Table
以下にInput Tableの記述例を示します。
local inp_tbl =
{
{ "Throttle", SOURCE },
{ "SwitchG", SOURCE },
{ "Speed", VALUE, 0, 100, 0 },
{ "Interval", VALUE, -128, 128, 50 }
}この例では2つのソース( Throttle, SwitchG )と、2つの定数( Speed, Interval )を定義しています。 これらの名前は8文字以内の英数字であればユーザーが自由に定義できます。 これらソースおよび定数への、実際の入力デバイスおよび値の割り当ては、プロポにこのスクリプトを登録するときに指定します。
定数「Speed」は、最小0～最大100の範囲を許容し、デフォルト値は0であることを示しています。 定数「Interval」は、最小-128～最大128の範囲を許容し、デフォルト値は50であることを示しています。 定数に許容される範囲は、最小-128～最大128です。
Output Table
以下にOutput Tableの記述例を示します。
local out_tbl = { "Out1", "Out2" }この例では2つの出力データ( Out1, Out2 )を定義しています。 これら出力データの名前は4文字以内でなければなりません。 プロポにこのスクリプトを登録すると、これら出力データの名前がMIXS画面でSourceとして選択可能になります。
Init Function
以下にInit Functionの記述例を示します。
local function init_func()
-- code here runs only once when the model is loaded
endRun Function
以下にRun Functionの記述例を示します。
local function run_func( inSrc01, inSrc02, inConst01, inConst02 )
-- code here runs every MIX loop
return value1, value2
end関数の入力パラメーターには、Input Tableで定義した入力値が順に割り当てられます。 上の例では、inSrc01 には Throttleに定義した入力が、 inSrc02 には SwitchGに定義した入力が、 inConst01 には Speedに設定した定数が、 inConst02 には Intervalに設定した定数が読み込まれます。
スクリプトに出力データがある場合は、retrun文につづけて列挙します。 Output Tableで定義した変数に順に割り当てられます。 上の例では、value1 が変数Out1として、 value2 が変数Out2として、プロポのMIXS画面でSourceとして選択可能になります。
Return Statement
以下にReturn Statementの記述例を示します。
return { run=run_func, input=inp_tbl, output=out_tbl, init=init_func }プロポでの設定・実行方法
スクリプトを、SDカードのフォルダ /SCRIPTS/MIXES に格納します。 そしてプロポのモデルメニューのCUSTOM SCRIPTS画面を開きます。 ここには1行に1つのスクリプトを定義することができます。
任意の行で[ENTER]を長押しして編集モードに入ります。 1つめのフィールドで、スクリプトの名前を選択します。 すると画面左の「Inputs」欄に、スクリプトのInput Table文に定義した入力データの名前が一覧表示され、 画面右の「Outputs」欄に、スクリプトのOutput Table文に定義した出力データの名前が一覧表示されます。 ソースの指定が必要な入力データには「---」が表示されているので、ここで[ENTER]を押すとソースが選択できます。 また定数の入力データはデフォルト値が表示されているので、ここで[ENTER]を押すと任意の値を指定できます。
つづいてプロポのMODELメニューの MIXS画面 を開きます。 そしてSource欄でスクリプトの名前を選択します(Sourceで利用する場合)。 するとSource欄にはスクリプトの出力データの名前がセットされます。
あとはプロポで設定したモデルを読み込むと、スクリプトが動作します。
Telemetryスクリプトの書き方
機体からの テレメトリーデータ 等を加工し、プロポのメイン画面(カスタムテレメトリー画面)へ表示する処理を記述します。 テレメトリー以外の、OpenTX/EdgeTX内部のデータ(タイマー値など)も利用・表示できます。 1モデルあたり最大3つのTelemetryスクリプトを設定することができます。 なお、スクリプトで使用できる、機体が対応しているテレメトリーセンサーの名前は、MODELメニューの TELEMETRY画面 にある「Sensors」欄で見ることができます。構造
Telemetryスクリプトには、最低以下の4つの文／関数の定義が必要です。
- Init Function
- プロポ起動時またはモデル切り替え時に、最初に1回だけ実行される、初期設定処理を記述します。省略可能です。
- Background Function
- メインの処理を記述します。プロポの制御ループの中で繰り返し実行されます。(OpenTX 2.0 ではプロポでカスタムテレメトリー画面を表示している場合は動作が停止します)
- Run Function
- メインの処理を記述します。プロポでカスタムテレメトリー画面を表示している場合に限り、プロポの制御ループの中で繰り返し実行されます。画面への表示処理はここに記述します。
- Return Statement
- 上に示した3つの関数が、実際のコードのどの部分に適合するかを記述します。
Init Function
以下にInit Functionの記述例を示します。
local function init_func()
-- code here runs only once when the model is loaded
endBackground Function
以下にBackground Functionの記述例を示します。
local function bg_func()
-- code here runs every radio process loop
endRun Function
以下にRun Functionの記述例を示します。
local function run_func( key_event )
-- code here runs every radio process loop when custom telemetry screen is visible
return 0
end最後のreturn文でゼロ以外の戻り値を返すと、スクリプトは停止します。
key_eventには、OpenTX/EdgeTXシステムから、その時に押されていたプロポのキーの情報が渡されます。 必要に応じてRun Functionの中で使用します。 key_eventの詳細は、 Key Event Constants (OpenTX 2.3 Lua Reference Guide) で読めます。 また、プロポの画面への描画については Lcd Functions (OpenTX 2.3 Lua Reference Guide) を使います。文字だけでなく、ラインやドット、ビットマップなどを描画することもできます。
Return Statement
以下にReturn Statementの記述例を示します。
return { run=run_func, background=bg_func, init=init_func }プロポでの設定・実行方法
スクリプトを、SDカードのフォルダ /SCRIPTS/TELEMETRY に格納します。 プロポのMODELメニューから DISPLAY画面 を開き、表示タイプに"Script"を選んでスクリプトの名前を選択します。
または OpenTX Companion、 EdgeTX Companion のモデル編集画面で「Telemetry」タブを開き、画面下の「Telemetry Screen 1/2/3/4」のいずれかを選択します。 「Custom Screen Type」で"Script"およびスクリプトの名前を選択します。 そしてモデルデータをプロポに転送します。
あとはプロポで、設定したモデルを読み込み、カスタムテレメトリー画面を開くとスクリプトの動作結果を見ることができます。
Functionスクリプトの書き方
プロポのスイッチが操作されたときに動作させたい処理を記述します。 画面への表示はできません。 なお、スクリプト中に定義したローカル変数は、スイッチの状態に関係なく、モデルがロードされている限りその値を保持し続けます。構造
Functionスクリプトには、最低以下の3つの文／関数の定義が必要です。
- Init Function
- プロポ起動時またはモデル切り替え時に、最初に1回だけ実行される、初期設定処理を記述します。省略可能です。
- Run Function
- メインの処理を記述します。スクリプトに関連付けられたスイッチで、指定された状態が続く限り、繰り返し実行されます。
- Return Statement
- 上に示した2つの関数が、実際のコードのどの部分に適合するかを記述します。
Init Function
以下にInit Functionの記述例を示します。
local function init_func()
-- code here runs only once when the model is loaded
endRun Function
以下にRun Functionの記述例を示します。
local function run_func()
-- code here runs every radio process loop when specified state lasts on associated switch
endReturn Statement
以下にReturn Statementの記述例を示します。
return { run=run_func, init=init_func }プロポでの設定・実行方法
スクリプトを、SDカードのフォルダ /SCRIPTS/FUNCTIONS に格納します。 そしてプロポのMODELメニューの SPECIAL FUNCTIONS / GLOBAL FUNCTIONS画面 を開きます。 ここには1行に1つのスクリプトを定義することができます。
任意の行で[ENTER]を長押しして編集モードに入ります。 1つめのフィールドで、関連付けるスイッチとその状態を選択します。 2つめのフィールドで、"Lua Script"を選択します。 3つめのフィールドで、スクリプトの名前を選択します。
あとは関連付けたスイッチ操作すると、スクリプトが起動します。
Special Functions / Global Functions の使い方
One-Timeスクリプトの書き方
One-Timeスクリプトには、上で説明した Mix, Telemetry, Function スクリプトにあるような、必須の構造といったものはありません。 Lua言語の文法とOpenTX/EdgeTXのAPI、使用法に従っていれば、自由に記述することができます。スクリプトが0以外の値をreturnしたとき、またはユーザーが[EXIT]ボタンを長押ししたときに停止します。
ただし、One-Timeスクリプトの実行中は、Mix, Telemetry, Function スクリプトは一時停止されます。 そしてOne-Timeスクリプトの実行が終了すると、一時停止していたスクリプトの動作が再開されます。
TOOLS画面にスクリプトのタイトルを表示させる
/SCRIPTS/TOOLSフォルダの下に格納したOne-Timeスクリプトは、RADIO(SYSTEM)メニューの[TOOLS]画面から起動することができます。 スクリプトの先頭に下記の一行を入れると、これがスクリプトのタイトルとして、[TOOLS]画面に表示されます。
-- TNS|title_string|TNEプロポでの設定・実行方法
スクリプトを、SDカードの任意のフォルダ(/SCRIPTS/TOOLSフォルダの下が推奨)に格納し、[Radio]-[SD-HC CARD/SD CARD]画面からスクリプトファイルを選択すると起動します。
