セクションの複数ページをまとめています。印刷またはPDF形式で保存...

最適な出力のために、Google Chrome（15以降）または Microsoft Edge（79以降）を推奨いたします。

2024-05-14 現在

TWELITE STAGE SDK / act

TWELITE のファームウェアを開発する

1: 開発環境

2: SDKのインストール

3: アクトのビルド

4: 新しいプロジェクトの作成

5: VSCodeのインストール

6: ビルド定義 Makefile

7: 他のプラットフォーム

TWELITE STAGE SDK を使うことで、独自のファームウェアを TWELITE 向けに開発できます。

MWX ライブラリと act

MWX ライブラリは、TWELITE 無線モジュールのコード表記を簡素化することを目的としています。MWXで作成されたプログラムをアクト act と呼びます。アクトにはループによる記述と、イベントによる記述（ビヘイビア behavior と呼びます）の二種類があります。

ループによる記述 (setup(), loop())

小規模な機能を記述する場合に適しています。

#include <TWELITE>
const uint8_t PIN_LED = 5;

void setup() {
  pinMode(PIN_LED, OUTPUT);
}

void loop() {
  if (TickTimer.available()) {
    uint32 t_now = millis();

    // blink LED every 1024ms
    digitalWrite(PIN_LED, (t_now >> 10) & 1 ? HIGH : LOW);
  }
}

イベントドリブンのアプリケーション記述

各種イベント・割り込みハンドラの定義、アプリケーションの複雑な振る舞いを記述するのに適したステートマシンをクラス内に定義して、見通しの良いコードを記述できます。この記述方法をビヘイビアと呼びます。

// myApp.hpp
...
class myApp : MWX_APPDEFS_CRTP(myApp) {
...
  void loop() {
    // main loop
  }

  void receive(mwx::packet_rx& rx) {
    // on receive
  }
};

// myApp.cpp
...
MWX_DIO_EVENT(12, uint32_t arg) {
		// on event from DIO12
}

ペリフェラルの手続きを簡素化

よく使われる UART, I2C, SPI, ADC, DIO, タイマー, パルスカウンタを取り扱うクラスオブジェクトを定義しています。

void loop() {
  while(Serial.available() {
    auto x = Serial.read(); ... } // serial message
  if (Analogue.available() {
    auto x = Analogue.read(...); } // adc values
  if (Buttons.available() {
    Buttons.read(...); } // DIO changes
  if (the_twelite.receiver.available()) {
    auto&& rx = the_twelite.receiver.read(); } // on rx packet
}

シンプルな中継ネットワークを定義

この中継ネットワークは TWELITE 標準アプリケーションと同等の実装で、個体アドレスの管理は 8bit の論理IDで行うこと、ネットワーク構築のための通信を行わないため電源投入後すぐにネットワーク宛に無線パケットを送ることができる点が特徴です。

#include <TWELITE>
#include <NWK_SIMPLE>

void setup() {
  ...
  auto&& nwksmpl = the_twelite.network.use<NWK_SIMPLE>();
	nwksmpl << NWK_SIMPLE::logical_id(0xFE)
	           // set Logical ID. (0xFE means a child device with no ID)
	        << NWK_SIMPLE::repeat_max(3);
	           // can repeat a packet up to three times.
}

void loop() {
  ...
  vTransmit();
  ...
}

void vTransmit() {
  if (auto&& pkt =
    the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet();
  pkt << tx_addr(0x00)  // to parent
	  	<< tx_retry(0x3); // set retry

	pack_bytes(pkt.get_payload() // prepare payload data
	    , uint8_t(0x01)
	    , uint16_t(analogRead(PIN_ANALOGUE::A1))
	    , uint16_t(analogRead_mv(PIN_ANALOGUE::VCC)));

	pkt.transmit(); // transmit!
}

TWELITE APPS のパケットとの互換性はありません

TWELITE APPS における中継回数は原則として3回に限られますが、act のパケットは64回まで中継できます。

中継回数を増やす際は、中継済みのパケット（重複パケットの管理テーブルがクリアされたもの）であっても、パケットが遠回りして一定時間経過後に戻ってきた際には、再び中継されてしまう場合があることに注意してください。

PAL や MONOSTICK 向けのボード定義

ボード上のセンサーなどを容易に取り扱えます。

#include <TWELITE>
#include <PAL_AMB> // include the board support of PAL_AMB

void setup() {
	auto&& brd = the_twelite.board.use<PAL_AMB>(); // use PAL AMB
	uint8_t u8dip = brd.get_DIP_SW();   // check DIP s/w status
	brd.set_led(LED_TIMER::BLINK, 100); // LED switchs on/off every 100ms
	...

	// start capture of sensors
	brd.sns_SHTC3.begin();
}

void loop() {
	if (TickTime.available()) { // check every ms
		auto&& brd = the_twelite.board.use<PAL_AMB>();

		if (brd.sns_LTR308ALS.available()) {
		  Serial << brd.sns_SHTC3..get_temp();
		} else {
		  // notify sensor that 1ms passed.
			brd.sns_SHTC3.process_ev(E_EVENT_TICK_TIMER);
		}
	}
}

1 - 開発環境

開発環境（OSなど）について

開発環境を構築するためには、ソフトウェア群のインストール、またこれらの利用許諾に同意する必要があります。また、PC、ワークステーション上でセキュリティ設定等が必要になる場合があります。

配布時には十分注意しておりますが、ウィルスなどの確認はお客様のほうでも留意いただくようお願いいたします。
お客様のセキュリティの考え方や運用（例：外部アプリケーションのインストールの可否）については、お客様の環境の管理者にご確認ください。

また、開発環境をインストールまた動作するにあたり、OSが介在し設定等必要になる場合があります（例：開発元が不明なアプリケーションの実行。開発環境または紹介するツール群の多くは、アプリケーションは開発元を証明する仕組みが組み込まれせん）。設定方法については、一般の情報を参考いただくようお願いいたします。

MWXライブラリを用いてアプリケーションを記述するには以下が必要です。

MWSDK（ソフトウェア開発環境）
開発用エディタ（Microsoft社のVisual Studio Codeを紹介します）

Windows

コンパイラのツールチェインなどは比較的環境への依存度が低いため、多くの環境で動作することが期待できますが、現在サポートされている Windows10および11バージョンを推奨します。動作環境の差異により動作しないような場合は、当社で確認している環境を参考に別途環境を用意してください。

以下、開発で使用しているバージョンを挙げます。

Windows11 21H2 (Visual Studio 2019)
FTDI社のドライバが動作していること (MONOSTICK, TWELITE Rを動作させるため)

WSL (Windows Subsystem Linux) 環境下でもコンパイラを動作させることが出来ます。ただしコンパイルのみでファームウェアの書き換え等はWindows10上のユーティリティから実施してください。

WSL環境は必須ではありません。

Linux

コンパイラのツールチェインなどは比較的環境への依存度が低いため、多くの環境で動作することが期待できますが、現在サポートされているディストリビューションを推奨します。動作環境の差異により動作しないような場合は、当社で確認している環境を参考に別途環境を用意してください。

以下、開発で使用しているバージョンを挙げます。

Ubuntu 18.04 LTS 64bit
Ubuntu 20.04 LTS 64bit

32bitのシステムはサポートしません。

macOS

コンパイラのツールチェインなどは比較的環境への依存度が低いため、多くの環境で動作することが期待できますが、現在サポート中のmacOSバージョンを推奨します。動作環境の差異により動作しないような場合は、当社で確認している環境を参考に別途環境を用意してください。

以下、開発で使用しているバージョンを挙げます。

macOS 10.14 Mojave (Intel)
macOS 12 Monterey (Apple Silicon)

Visual Studio Code などの開発ツールについて

開発環境を動作させるためのツールや使用方法については、その開発元やコミュニティの情報を参照ください。

コード記述作業の効率面で Visual Studio Code (VSCode) の利用を推奨します。

MWXライブラリでは、C言語の開発に比べ、読み込むヘッダファイルが多くなるため、VSCode上でのコード解釈等にはより多くのPCのリソースを要求します。

なお、VSCodeは必須ではありません。使い慣れたエディタがある場合には、そちらを使用していただいても結構です。

LSP (Language Server Protocol)を使用できる環境であれば、一般的にVSCodeと同等の作業効率を実現できるものと考えられます。

ビルド環境による差異

Linux/WSL環境下/macOSのビルド結果はWindows10の結果と異なります。通常系の動作で差異が見られることは当社が把握する限りありませんが、特にgccのLTOを無効にしているためバイナリサイズが数%程度大きくなる傾向にあります。

動作等に疑問を感じた際は、必ず Windows10,11 上のビルドを実施し再現することを確認してから、お問い合わせください。

2 - SDKのインストール

TWELITE SDK のインストール

TWELITE STAGE SDK の導入

TWELITE STAGE SDK 配布アーカイブ(ZIPなど)をダウンロードし、適切なフォルダに展開します。

TWELITE STAGE SDK の導入方法をご覧ください。

以下のように展開したら完了です。

環境変数の設定

コマンドラインでビルドを行う場合には、環境変数を設定してください。TWELITE STAGE アプリは自動で設定するため不要です。

MWSDK_ROOT, MWSDK_ROOT_WINNAME （Windowsのみ）を設定します。

Windows

ここでは展開後のフォルダ名を C:\MWSTAGE とします。別のフォルダへインストールした場合は、読み替えてください。

C:\MWSTAGE\Tools\SET_ENV.CMD を実行してください。以下の環境変数を設定します。

MWSDK_ROOT
MWSDK_ROOT_WINNAME

例えば以下のような設定になります。

MWSDK_ROOT=C:/MWSTAGE/MWSDK/
MW_ROOT_WINNAME=C:\MWSTAGE\MWSDK\

インストールしたPC上からTWELITE STAGE SDKをアンインストールするには以下を行ってください。

UNSET_ENV.cmdを実行してください。環境変数の設定を解除します。
MWSTAGEフォルダを削除します。

Linux

開発環境やシェルに MWX_ROOT

方法はいくつかありますが、ホームフォルダの.profile（ファイルがなければ新しく作成してください）に以下の設定を追加します。この設定でVSCodeのビルドまで可能です。環境変数が反映されるように設定してください。

MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK/
export MWSDK_ROOT

エディタを使用せずに追加するには以下のようにコマンド入力します。$はプロンプトで環境によって表示が違います。/foo/bar/MWSTAGEの部分はインストールしたフォルダに応じて書き換えてください。


cd $HOME
echo MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK>>.profile
echo export MWSDK_ROOT>>.profile

macOS

開発環境やシェルに MWX_ROOT環境変数が反映されるように設定してください。

方法はいくつかありますが、ホームフォルダの.profile（ファイルがなければ新しく作成してください）に以下の設定を追加します。この設定でVSCodeのビルドまで可能です。

MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK/
export MWSDK_ROOT

エディタを使用せずに追加するには以下のようにコマンド入力します。$はプロンプトで環境によって表示が違います。/foo/bar/MWSTAGEの部分はインストールしたフォルダに応じて書き換えてください

環境全体にMWSDK_ROOTを適用にするには、launchdを用います。 VSCodeの一部の設定で環境変数を参照していますが、ビルドには必須ではありません。

3 - アクトのビルド

アクト(act)のビルド

MWXライブラリで記述したアプリケーションプログラムをアクト(act)と呼びます。まずは、これをビルドして書き込みます。

ビルドフォルダ構成について
Visual Studio Code (VSCodeと記載) でのビルドについて

本ページでは、いくつかのビルド方法を記載していますが、いずれの方法も最終的にはmakeコマンドを実行しています。詳細はMakefileの解説を参照ください。

OS環境によっては各実行プログラム(makeやgccなどビルドツールチェイン)の動作時にセキュリティ警告が出る場合があります。警告を抑制する設定が必要になります。警告を抑制してプログラムを動作する運用を行うかは、お客さま自身またはシステム管理者に相談のうえ、ご判断ください。

ビルドフォルダ構成について

MWSDKをインストールしたフォルダMWSDK_ROOT (例 C:\MWSDK)を開きます。以下のような構成になっています。

MWSDK_ROOT
  |
  +-ChipLib      : 半導体ライブラリ
  +-License      : ソフトウェア使用許諾契約書
  +-MkFiles      : makefile
  +-Tools        : コンパイラ等のツール一式
  +-TWENET       : TWENET/MWXライブラリ
  +-Act_samples  : アクトサンプル
  ...

アクトファイルはAct_samples以下に格納しています。（以下は一部割愛しています）

Act_samples
  |
  +-CoreAppTwelite    : App_TweLiteと同じ構成のボード用のアクト
  +-PAL_AMB           : 環境センス PAL 用のアクト
  +-PAL_MAG           : 開閉センス PAL 用のアクト
  +-PAL_MOT           : 動作センス PAL 用のアクト
  ..
  +-Parent-MONOSTICK  : 親機アクト、MONOSTICK用
  +-PingPong          : PingPong アクト
  +-PulseCounter      : パルスカウンタを利用したアクト
  +-act0              : スクラッチ（とりあえず書いてみる）用アクト

これらのアクトは、MWXライブラリの記述の参考となるシンプルな例ですが、多くのアクトは以下の機能を有しています。

センサー値を取得する
センサー値取得後、無線パケットを親機宛に送信する
送信完了後、一定時間スリープする（または割り込みを待つ）

Parent-MONOSTICKのアクトによりパケットの受信と表示を行っています。この親機用のアクトは、アスキー形式で出力しています。 (:00112233AABBCC...FF[CR][LF] のような : で始まり、途中は16進数のバイトをアスキー文字2字で表現する形式です。末尾の??は同様に2字のバイトとなりますがLRCというチェックサムバイトになります。参考：アスキー形式)

実際に動作させてみるときは、以下の組み合わせを試してみてください。

親	子	解説
`BRD_APPTWELITE`	`BRD_APPTWELITE`	親機はM1ピンをLOW(GNDレベル)にして起動する。通常モード（常時稼働）にて、`App_Twelite`のような動作を確認できます。
`PingPong`	`PingPong`	子機2台を使って動作します。片方から Ping パケットを送ると、相手方から Pong パケットが戻ってきます。
`Parent-MONOSTICK`	その他	子機用のアクトのパケット送信を確認できます。

では、アクトの中から PingPong のフォルダの中を見てみましょう。

Act_samples にある他のアクトもビルドできます。その場合、フォルダ名・ファイル名は読み替えるようにしてください。

Act_samples
  +-PingPong
    +-PingPong.cpp   : アクトファイル
    +-build          : ビルドフォルダ
    +-.vscode        : VSCode 用の設定ファイル

必ずフォルダ直下にフォルダと同名の .cpp ファイルが必要です。

小規模なアクトならこの.cppファイル内に記述します。規模が大きくなってきたときはMakefileの解説を参考にして複数のファイルに分割してビルドすることが出来ます。

PingPong フォルダ直下にアクトファイル PingPong.cpp があります。フォルダ名を変更した場合は、必ず .cpp ファイルの名前もフォルダ名と同名にします。

次にビルドフォルダを開きます。

Act_samples
  +-PingPong
    +-build
      +-Makefile        : makefile
      +-build-BLUE.cmd  : TWELITE BLUE 用ビルドスクリプト(Windows用)
      +-build-RED.cmd   : TWELITE RED 用ビルドスクリプト(Windows用)
      +-build-clean.cmd : obj_* ファイル削除

ビルドに必要なスクリプトとMakefileが格納されています。

このMakefile のあるフォルダで make TWELITE={BLUEまたはRED} を実行することで、ビルドが行われます。VSCode でのビルドも同様で内部的に make を呼び出します。

TWELITE STAGE アプリでのビルド

TWETLITE STAGE アプリを用いて、ビルドから書き込み、実行までを行えます。ここでは、TWELITE STAGE アプリの起動からビルドまでを解説します。

0. TWELITE の接続

MONOSTICKまたはTWELITE Rをお使いのUSBポートに接続します。

TWELITE は繊細な電子部品ですので、取り扱いには十分注意してください。以下に代表的な注意事項を記載します。

特にTWELITE Rを用いている場合は、多くの場合電子基板がケースなどを介さず直接外部に触れる状態で使用するため、意図しないショートやノイズなどUSBデバイスが正常に動作しない状態になる場合があります。

この場合は、アプリケーションを終了させUSBデバイスを抜き差しすることで通常は回復します。最悪、USBデバイスの破損やPCの破損も考えられます。

電子基板の取り扱いには十分注意してください。

回路の間違い
- 電源を入れる前にはもう一度回路を確認してください。
- 電池の逆差しや過大電圧には注意してください。
静電気
- 人感がない電圧であっても半導体の故障になりえます。大掛かりな対応をしなくとも、金属部に触れてから作業する・リストバンド・専用マットなど簡易にできる対応でも相応の効果はあります。
金属物などが触れることでのショート
- 電子基板の近くには金属物がないようにしてください。クリップなどが散らかっているとこれが原因でショートすることもありますし、電池が大放電して加熱する危険な状況も考えられます。

1. TWELITE STAGE アプリの起動

{TWELITE SDK インストール} フォルダにある実行形式 TWELITE_Stage.{拡張子} を起動します(参考: TWELITE STAGE アプリマニュアル)。

以下は、TWELITE STAGE アプリ動作中の画面例です。左側の主画面とコマンドプロンプト画面がありますが、主画面を操作します。コマンドプロンプト画面は通常使用しませんが、諸情報及びTWELITEマイコンシリアルポートからの入力データが表示されます。

主画面での主な操作は以下です。

マウス左クリック（選択）
マウス右ダブルクリック（前の画面に戻る）
素早く ESC を２回, 一部画面では ESC １回（前の画面に戻る）
Alt(⌘) キーを押し続ける（ヘルプ画面）
通常キーボード入力（画面に従う）

(参考: TWELITE STAGE アプリマニュアル)

2. シリアルポートの選択

TWELITE STAGE アプリを起動すると最初に表示される画面です。事前に TWELITE R や MONOSTICK を接続しておけば、この画面に列挙されます。この画面で操作したい TWELITE を選択します。この画面で選択せずに、別の操作で選択することも可能です。

(参考: TWELITE STAGE アプリマニュアル)

3. メインメニュー

シリアルポート選択画面を抜けると、メインメニューが表示されます。ビルドや書込は「アプリ書換」メニューを選択します。

(参考: TWELITE STAGE アプリマニュアル)

4. アプリ書換メニュー

アプリ書換メニューを選択する前に、TWELITE の接続とシリアルポートの選択を確認しておいてください。シリアルポートの選択状況は Alt(⌘) キーを押し続けると出現するヘルプ画面上で確認できます。

TWELITE STAGE アプリから参照できるプロジェクトはいくつかに分類されています。右側のﾍﾙﾌﾟは関連情報をブラウザで表示します。ﾌｫﾙﾀﾞはプロジェクトのあるフォルダを表示します。

TWELITE が接続済みであれば、メニューを選択したときに、TWELITE のモデルが判定されます。（TWELITE STAGE アプリ内部では、この判定したTWELITEモデルに応じたビルドを行うようになっています）。

ここでエラーが出た場合は、この画面からメインメニューに戻って、メニューを再選択します。解決しない場合は、必要に応じてTWELITE STAGE アプリ上で Alt(⌘) + 0 を入力してシリアルポート選択を解除を行ったうえで USB 接続を含む各種接続を確認するなどします。USB接続のエラーによっては、お使いのコンピュータを再起動しないと解決しない場合もあります。

(参考: TWELITE STAGE アプリマニュアル)

4. プロジェクトの選択

ここでは「アプリ書換メニュー」から「actビルド&書換」を選択します。

5. ビルド&書換

ここでは、先ほどのプロジェクト選択画面中で BRD_APPTWELITE を選択します。

選択すると、以下の画面例のように書き込みが行われます。エラーが表示された場合は、画面の指示に従うか、前の画面戻ってやり直してください。

(参考: TWELITE STAGE アプリマニュアル)

6. インタラクティブモードに移動

書換が正常に終了すると、続けてインタラクティブモード（設定画面）に移行します。ただし、インタラクティブモードに対応するファームウェアでないと画面は表示されません。

インタラクティブモードでは、TWELITE の無線チャネルなど、各種設定を行えます。

(参考: TWELITE STAGE アプリマニュアル)

7. ターミナル画面

ルートメニューに戻って「ビューア」→「ターミナル」を選択します。

ごく簡易的なシリアルターミナルです。TWELITE からのメッセージの確認と、TWELITE に対するメッセージの入力を行えます。

画面では、約１秒おきに無線送信したときのメッセージが表示されます。+ + + 入力によるインタラクティブモード画面への遷移も行えます。

(参考: TWELITE STAGE アプリマニュアル)

VSCode でのビルドについて

VSCode はソース編集の強力なエディタですが、VSCode上で TWELITE マイコン用のファームウェアをビルドすることも可能です。

VSCode の起動は TWELITE STAGE アプリの「ビルド＆書換」メニュー以下のプロジェクト一覧より行います。

ビルドのリスト中の右端 [VSCode] を押してください。

この動作を行うためには TWELITE STAGE アプリの設定が必要です。

STAGE設定で「code でフォルダを開く(VSCode)」を 1 にしてください。

Windows, Linux, macOS では、デフォルトで上記設定を有効化した TWELITE_Stage_VSCode.{拡張子} の実行形式を配布しています。

すでに VSCode が立ち上がった状態では必要な設定が反映されない場合があります。その場合は、一旦 VSCode を終了して、改めて TWELITE STAGE アプリから VSCode を起動します。

情報の反映のためにシステム環境変数を用いてるため、原理的に、別々のライブラリフォルダを参照する複数の TWELITE STAGE の同時運用では問題が出る場合があります。VSCode 上で Terminal を開き、環境変数 MWSDK_ROOT が適切に設定されている場合はビルドは正常に行われることが期待できます。

VSCode のビルドタスク

最初にビルドしたいワークスペースを開いておきます。TWELITE STAGE SDK添付のワークスペースにはビルドタスクの定義が追加されています。

以下の例では英語インタフェースの画面例で、ワークスペースを開いています。

ワークスペースを開き [Terminal>Run Task...] を選択します。

ビルドするTWELITE無線モジュールの種別(BLUE/RED)とアクト名を選択します。以下の例では Build for TWELITE BLUE を選択しています。選択後すぐにビルドが始まります。

ビルド中の経過は画面下部のターミナル部分に出力されます。

正しくビルドできた場合、上記画面例の反転表示部のように .elf ファイルが生成されるメッセージがサイズ情報(text data bss dec hex filenameと記載がある部分)とともに出力されます。

またBINファイル（上記では BRD_APPTWELITE_BLUE_???.bin）ファイルがbuildフォルダ下に出来上がっているはずです。確認してみてください。

VSCodeのタスク定義には Windowsのファイルシステムに適合しないフォルダ名 (例：/c/User/...)を変換する(例：C:/User/...) 定義を追加しています。

下記.vscode/tasks.json 中の変換ルールは完全ではありませんが、出力メッセージ中のドライブ名相当部分の文字列をVSCodeが識別できる形式に書き換えています。この書換によりコンパイルメッセージからエラーが発生しているファイル名と行番号をVSCode中で表示できます。

...
"windows": {
    "command": "sh",
    "args": [
        "-c", "make TWELITE=BLUE 2>&1 | sed -E -e s#\\(/mnt\\)?/\\([a-zA-Z]\\)/#\\\\\\2:/#g"
    ],

ビルドがうまくいかない場合は、まずエラーメッセージを確認して下さい。errorという文字列が含まれる行中のメッセージから、エラー原因が容易に特定できる場合も少なくありません。

また、クリーン(objs_??? フォルダにある中間ファイルの削除)を行い、ビルドを再実行してみてください。（他の環境でビルドした中間ファイルが残っているとmake cleanを含めすべての操作が失敗します)

コマンドラインでのビルド

コマンドライン環境でのビルドについて補足します。

コマンドライン(bashやzshなど)の利用についての知識を必要とします。

OS環境によっては各実行プログラムの動作時にセキュリティ警告が出る場合があります。警告を抑制する設定が必要になります。（警告を抑制してプログラムを動作する運用を行うかは、お客自身またはシステム管理者に相談の上、ご判断ください）

Linux, macOS 環境

コマンドラインでのビルドは、bashやzsh(または他のシェル)が動作するウインドウでmakeを実行します。事前に環境変数MWSDK_ROOTが正しく設定されていることを確認してください。例えば/work/MWSDKにインストールした場合は ~/.profile （など）に以下のような設定を行います。

MWSDK_ROOT=/work/MWSDK
export MWSDK_ROOT

コマンドラインよりmakeを実行します。makeがない場合はパッケージをインストールする必要があります。

Linuxの場合は、パッケージマネージャからインストールできます（下記はAPTの例）。


sudo apt install make

または


sudo apt install build-essential

macOSの場合は、Command Line Tools for Xcode に同梱されています。
```
xcode-select --install
```

Windows 環境

Windowsでは {MWSTAGE SDK インストール}/MWSDK/WIN_BASH.cmd を実行します。環境変数や make ユーティリティが設定済みです。

ビルド

ビルドは以下のようになります。


cd $MWSDK_ROOT
cd Act_samples/PingPong/build
pwd
/mnt/c/MWSDK/Act_samples/PingPong/build

ls
... ファイル一覧の表示

rm -rfv objs_*
... 念のため中間ファイルを削除

make TWELITE=BLUE
... BLUE用に通常ビルド

make -j8 TWELITE=BLUE
... BLUE用にパラレルビルド(同時に8プロセス)

コマンド例

詳細はMakefileの解説をご覧ください。

make TWELITE=BLUE：TWELITE BLUE用にビルド
make TWELITE=RED：TWELITE RED用にビルド
make cleanall：中間ファイルの削除

中間ファイルについて

ビルドが行われると objs_??? フォルダが作成され、その中に中間ファイルが生成されます。このファイルはコンパイルした環境に依存しているため、他の環境のファイルが残っているとmakeがエラーとなりビルドが失敗します。

直接 objs_??? フォルダを削除すると make のエラーが解消する場合があります。

4 - 新しいプロジェクトの作成

新しいプロジェクトの作成

新しいプロジェクトを作成するには、既存のサンプルアクトのフォルダを別の名前でコピーし、ファイル名の編集を行います。

コピー先のフォルダは MWSDK 配下のフォルダでなくても構いません。ただし、フォルダ名に空白文字や日本語名が含まれてはいけません。

プロジェクトのファイル構造は以下のようになっています（ここでは PingPong を例に挙げます）。

Act_samples
  +-PingPong
    +-PingPong.cpp   : アクトファイル
    +-build          : ビルドフォルダ
    +-.vscode        : VSCode 用の設定ファイル

この PingPong フォルダを別の場所（ただしフォルダ名に日本語や空白が含まない）にコピーします。

SomeDir
  +-AlphaBravo
    +-PingPong.cpp -> AlphaBravo.cpp ※ファイル名を変更
    +-build          : ビルドフォルダ
    +-.vscode        : VSCode 用の設定ファイル

編集の必要があるのは、PingPong.cpp のファイル名です。これをフォルダ名と同じAlphaBravo.cppに変更します。

build\build-BLUE.cmd を実行してBINファイルが生成されれば完了です（Windows10）。

Linux/WSL/macOS ではmake TWELITE=BLUEを実行して、ビルドが成功するか確認します。

ビルド定義の編集

ビルド対象のファイルを追加する場合は build/Makefile を編集します。プロジェクト直下にある .c .cpp ファイルは自動で追加されますが、それ以外のファイルについては編集が必要です。

編集方法は Makefile の解説をご覧ください。

VSCode用の設定

VSCode を利用する場合は、必要に応じて .vscode 以下の定義を編集してください。

TWELITE STAGE SDK に含まれるサンプルの多くは、以下のようになっています。

TWELITE STAGE SDK ライブラリのソースコードは ${env:MWSDK_TWENET_LIBSRC}/include/** ${env:MWSDK_TWENET_LIBSRC}/src/** を引用する。この環境変数 MWSDK_TWENET_LIBSRC は TWELITE STAGE アプリから VSCode でプロジェクトを開いた場合には自動で設定されます。
ビルドタスクについては、デフォルトで -D などの追加的なオプション等は設定されていない。

5 - VSCodeのインストール

Visual Studio Codeのインストール

TWELTIE STAGE SDK では、アクト（ソースコード）記述をより容易に行うため、Visual Studio Code (VSCode) を紹介しています。添付のアクトには、VSCodeで適切にコード解釈が行われるように設定したファイルが含まれます。

VSCodeはソースファイルやヘッダファイルを読み込み、ソースコードを解釈し、これによりソースコードの記述の助けとなる関数定義情報や、関数・メソッド名の補完などを行います。C言語の開発に比べて、MWXライブラリでは読み込まれるヘッダファイルの分量が多くなります。環境によってはエディタの動作が重く感じる場合があります。

ソースコードの解析や VSCode からのビルドを行うために、ライブラリソースコードが格納されるフォルダの情報などの情報が必要になります。これらの情報は TWELITE STAGE アプリから VSCode を呼び出すことによって反映されます。（具体的には適切な環境変数を設定して VSCode を始動します。プロジェクトの設定は環境変数を参照しています）

VSCode のインストール

当社サポートでは VSCode のインストール方法、使用方法のお問い合わせについては対応いたしません。一般で得られる情報を参照ください。

環境によっては、インストールのためにセキュリティ設定などが必要になる場合があります。インストールの可否はシステム管理者にご確認の上、手順は配布元や一般の情報を参考にしてください。

VSCode では、以下のことができます。

ソースコードの編集
ソースコード解釈に基づく intellisense
（＊全ての定義が正確に解釈されることを保証するわけではありません）

VSCode は公式サイトより入手してください。

プラグインの導入

Visual Studio Code が C/C++ 言語の記述を解釈できるようにするために、プラグインをインストールします。

C/C++ for Visual Studio Code

各OSでの特記事項

TWELITE STAGE から VSCode を呼び出すために、code コマンドが有効になっている必要があります。

以下は code.visualstudio.com の情報です。

Running Visual Studio Code on macOS https://code.visualstudio.com/docs/setup/mac
Running Visual Studio Code on Windows https://code.visualstudio.com/docs/setup/windows
Running Visual Studio Code on Linux https://code.visualstudio.com/docs/setup/linux

注記事項

MWXライブラリのサンプルには .vscode の定義を含めています。この定義は MWSDK_ROOT 環境変数を用い、ライブラリのソースコード({MWSDK_ROOT}/TWENET/current以下)を特定しています。

TWELITE STAGEからVSCodeを始動した場合、上記の環境変数などを設定します。既に始動済みであるような場合など、設定が反映されない場合もあります。

VSCode のソースコードの解釈はコンパイラでの解釈とは完全には一致しません（GCCとclangの違い等による）。またソースコードの編集状況によっては解釈がより不完全な状態になる場合もあります。

6 - ビルド定義 Makefile

Makefileによるビルド定義

Makefileはbuild/Makefileに格納されています。makeコマンドを実行することで、アクトをビルドするようにあらかじめ定義されています。

MWSDK 2020-04 では、プロジェクトフォルダ中の .cpp ファイルを自動で検出するため、通常は Makefile の修正は不要です。ソースファイルをサブフォルダに格納するような場合は、編集が必要になります。

MWSDK 2019-12以前では、.cpp ファイルが複数ある場合は、Makefile の編集が必要です。

プロジェクトフォルダを他の環境からコピーしたあとには、必ずbuild/objs_???フォルダを削除してください。他の環境での中間ファイルが残っているとmakeがエラーになります。

(MWSDK 2020-04以降) USE_APPDEPS=0 を付加して clean してから、改めて make コマンドを実行することでエラーを回避できます。


make USE_APPDEPS=0 TWELITE=BLUE clean
...
make TWELITE=BLUE

makeのパラメータ

TWELITE=

ビルド対象をBLUEまたはREDで指定します。TWELITE BLUEならmake TWELITE=BLUEと指定します。

all

ビルドを実行します。通常は省略してmake TWELITE=BLUEのように実行します。

clean

ビルドの中間ファイルを削除します。make TWELITE=BLUE cleanのように実行します。

cleanall

すべての中間ファイルを削除します。make cleanallのように実行します。buildフォルダのobjs_???フォルダをすべて削除するのと同じです。

USE_APPDEPS=0 または 1

1 (デフォルト) を設定すると、ファイルの依存関係をもとに、ビルドファイルを決定します。例えば、ヘッダファイルに変更があった場合に関連するソースファイルが再コンパイル対象となります。

0 では依存関係を評価しません。0 に設定した場合、矛盾ある中間ファイルが残っていても make がエラーになりません。

Makefile 定義

アクトの規模に応じて、また、ビヘイビアの定義をする場合には、通常はソースファイルを分割してビルドします。

ビルドファイルの一つはプロジェクトフォルダ名.cppです。

他にファイルを定義する場合は、プロジェクトフォルダのbuild/Makefileを編集します。

下記はサンプルPAL_AMB-bihaviorでのMakefileの例です。

##############################################################################
# Copyright (C) 2019 Mono Wireless Inc. All Rights Reserved.
# Released under MW-SLA-*J,*E (MONO WIRELESS SOFTWARE LICENSE
# AGREEMENT).
##############################################################################
# USER PROJECT BUILD DEFINITION.
##############################################################################

#####################################################################
## set TWELITE model
TWELITE ?= BLUE
#TWELITE = RED

#####################################################################
## set application version (MUST SET THIS.)
VERSION_MAIN = 0
VERSION_SUB  = 1
VERSION_VAR  = 0

#####################################################################
## set an additional source file
##   the default file name is dirname.

## for C++ files compiled with g++ (must have .cpp suffix)
APPSRC_CXX += myAppBhvParent.cpp
APPSRC_CXX += myAppBhvParent-handlers.cpp
APPSRC_CXX += myAppBhvChild.cpp
APPSRC_CXX += myAppBhvChild-handlers.cpp

## for C files compiled with gcc (must have .c suffix)
#APPSRC += my_c_file.c

## Additional Src/Include Path
# if set, find source files from given dirs.
#
APP_COMMON_SRC_DIR_ADD1 = ../Parent
APP_COMMON_SRC_DIR_ADD2 = ../Child
#APP_COMMON_SRC_DIR_ADD3 =
#APP_COMMON_SRC_DIR_ADD4 =

#####################################################################
## set misc option for compiler

## C++ flags passed to g++
# e.g. CXXFLAGS += -DMY_DEFS
#CXXFLAGS +=

## C++/C flags passed to g++/gcc
# e.g. CFLAGS += -DMY_DEFS
#CFLAGS +=

## include opts
# e.g. INCFLAGS += -I../my_common_src/
#INCFLAGS +=

## optimize flag (default is -Os, normally no need to change)
#OPTFLAG=-O2

#####################################################################
## must include mwx.mk (the makefile body part.)
MWSDK_PATH?=$(realpath $(MWSDK_ROOT))
include $(MWSDK_PATH)/MkFiles/mwx.mk
#####################################################################

VERSION_???

バージョン番号を指定します。ビルド結果ファイル名に反映されます。

## set application version (MUST SET THIS.)
VERSION_MAIN = 0
VERSION_SUB  = 1
VERSION_VAR  = 0

コンパイル中は -DVERSION_MAIN=0 -DVERSION_SUB=1 -DVERSION_VAR=0のように定義として渡されます。

ソースファイルの追加

(MWSDK 2020-04以降) サブフォルダにファイルを配置しない場合は、追加指定は不要になりました。プロジェクトファイルにある .c .cpp ファイルがすべて追加されます。

ソースファイルを追加する際に必要なのはAPPSRC_CXXとAPP_COMMON_SRC_DIR_ADD?です。

サブフォルダにソースファイルを配置する場合は必ずフォルダ APP_COMMON_SRC_DIR_ADD? の指定が必要です。

ソースファイル名をAPPSRC_CXXに追記します。このファイル名にはフォルダ名が含まれてはいけません。サブフォルダにあるものもフォルダなしで指定します（つまり同じファイル名がサブフォルダにある場合は、ビルドが失敗します）

APPSRC_CXX += myAppBhvParent.cpp
APPSRC_CXX += myAppBhvParent-handlers.cpp
APPSRC_CXX += myAppBhvChild.cpp
APPSRC_CXX += myAppBhvChild-handlers.cpp

次にソースファイルがプロジェクトフォルダ以外の場所に格納されている場合の検索パスを指定します。最大４つまで設定できます。

APP_COMMON_SRC_DIR_ADD1 = ../Parent
APP_COMMON_SRC_DIR_ADD2 = ../Child

フォルダの指定はMakefileからの相対パスになります。

コンパイル・リンカオプション

その他にもいくつかのオプションをコンパイラ・リンカに渡すことができます。

指定	内容
`CXXFLAGS`	C++ソースファイルに対してコンパイルオプションを指定します。
`CFLAGS`	C/C++ソースファイルに対してコンパイルオプションを指定します。
`INCFLAGS`	ヘッダファイルのインクルードファイルを指定します。
`OPTFLAGS`	特別な理由があって-Os以外のコンパイルオプションを適用したい場合に定義します。
`LDFLAGS`	リンカオプションを指定します。(上記Makefileのコメントには記述はありませんが指定できます)

7 - 他のプラットフォーム

他のプラットフォームの使用

他のプラットフォームでも一部の機能(serparser, pktparser, コンソール用Serialオブジェクト)をビルドできるように、ビルド定義を用意しています。必要なファイルのみを切り出しています。

ビルド定義は{mwxライブラリ格納}/stdioフォルダに格納しています。ビルド方法はREADME.md(リンクはGitHub上)を参照してください。

C++11でのコンパイルが出来ること。
C++11の標準ライブラリヘッダが利用できること (utility, algorithm, functional, iteratorなど)
new/delete/virtualは使用しません。
newによるメモリ確保は例外的に使用する場合があります。
- serparser/pktparserでnew演算子を利用するalloc_heapではdeleteによる処理を行っています。
- （参考）ただしmwxライブラリとしてはdeleteについては考慮しない前提で設計されている部分もあります。