スタートガイド

• 1: TWELITE DIP
• 1.1: まずは使ってみる
• 1.2: インタラクティブモードによるカスタマイズ
• 1.3: UART機能によるPCとの連携
• 1.4: バイナリデータの伝送
• 1.5: リモコンアプリによる高度なデジタル伝送
• 2: TWELITE SPOT
• 2.1: まずは使ってみる
• 2.2: ESP32 を使ったファームウェア開発の基礎
• 2.3: TWELITE 子機からのデータ受信
• 2.4: 関連情報
• 3: TWELITE STAGE SDK / act
• 3.1: 開発環境
• 3.2: SDKのインストール
• 3.3: アクトのビルド
• 3.4: 新しいプロジェクトの作成
• 3.5: actのためのVSCodeのインストール
• 3.6: ビルド定義 Makefile
• 3.7: 他のプラットフォーム

1 - TWELITE DIP

すぐに使用できる無線モジュール

超簡単！標準アプリ

工場出荷時の TWELITE DIP には 超簡単！標準アプリ（App_Twelite）をインストールしています。

超簡単！標準アプリは、デジタル・アナログ信号の伝送を行うファームウェアです。

クイックマニュアル（PDF）

シンプルな無線通信

TWELITE は、起動直後から通信できます。Bluetooth のようなペアリングを行いません。

周波数チャネルを合わせた端末同士で同報通信を行います。したがって、同一の周波数チャネルでは、同時に複数の端末が送信を行うことはできません。自分宛でないパケットは無視します。トランシーバやインカムの動作をイメージすると分かりやすいかもしれません。

TWELITE は受信を伴わずとも送信できるため、省電力性能に優れた端末を実現できます。

データ量の多い通信には適していないものの、単純な信号伝送といった用途には最適です。

ピンの機能

超簡単！標準アプリで使用するピンの機能には、いくつかの種類があります。

• 電源入力（3.3V）
  • VCC/GND 2.3-3.6V
• デジタル・アナログ入出力
  • DIx→DOxへ反映
  • AIx→PWMxへ反映
• シリアル通信
  • TX/RX UART
  • SCL/SDA I2C
• 設定入力
  • Mx 動作モード切り替え
  • BPS 代替ボーレート選択
• RST リセット入力

x: 任意の番号

1.1 - まずは使ってみる

使用する製品

TWELITE DIP
TWELITE 親機／子機／中継機
超簡単！標準アプリ
2個（中継機使用時は3個）

片方向の信号伝送

親機へ入力された信号を、子機から出力できます。

デジタル信号

親機へ接続したスイッチを押すと子機へ接続した LED が点灯し、親機へ接続したスイッチを離すと子機へ接続した LED が消灯します。

上記の例では DI1 と DO1 だけを使っていますが、ポートは合計4つあります。他のポートも同様に使用できます。

アナログ信号

親機へ接続したボリュームを回すと、子機へ接続した LED の明るさが変化します。

上記の例では AI1 と PWM1 だけを使っていますが、ポートは合計4つあります。他のポートも同様に使用できます。

双方向の信号伝送

信号伝送は、親機から子機だけではなく、子機から親機へも同様に行えます。

デジタル信号の伝送例を双方向に拡張してみましょう。なおアナログ信号の伝送例も同様に拡張できます。

親機へ接続したスイッチを押すと子機へ接続した LED が点灯し、親機へ接続したスイッチを離すと子機へ接続した LED が消灯します。 同時に子機へ接続したスイッチを押すと親機へ接続した LED が点灯し、子機へ接続したスイッチを離すと親機へ接続した LED が消灯します。

上記の例では DI1 と DO1 だけを使っていますが、ポートは合計4つあります。他のポートも同様に使用できます。

中継機の設置

中継機として設定したものを親機と子機の間へ設置することで、通信距離を延長できます。最大3段まで中継できます。

M2 を GND へ接続します。

1.2 - インタラクティブモードによるカスタマイズ

インタラクティブモードとは

インタラクティブモードは、TWELITE シリーズを PC へ接続して設定を行う際に利用するモードです。TWELITE シリーズを USBアダプター TWELITE R シリーズを介して PC へ接続することで、UART 通信により各種パラメータの変更を行うことができます。

カスタム例

目的別に TWELITE DIP のカスタム例を示します。

興味のあるものを選んでお試しください。

• ネットワークのグループ分け
  • 親機と子機のペアを2つ用意し、それぞれを独立して動作させます
• 低レイテンシモードの使用
  • 親機と子機のペアを用意し、DIx→DOxの伝送における遅延を短縮します
• ボタン押下時のみ送信させる
  • 親機と子機のペアを用意し、親機のボタンを押したときだけ送信させるようにします

ネットワークのグループ分け

初期状態では、すべての TWELITE DIP が相互に通信できる状態にあります。親機と子機のペアを2つ用意した場合、親機の入力は双方の子機へ反映されるほか、子機の入力も双方の親機へ反映されます。

インタラクティブモードによってアプリケーションIDと周波数チャネルを変更し、2つのペアを同時に独立して使用できるようにしましょう。

使用する製品

TWELITE DIP	TWELITE R2
TWELITE 親機／子機	USB アダプター
超簡単！標準アプリ	-
4個	1個

カスタムの内容

インタラクティブモードの値を次のように設定し、2つのペアをグループAとBに分けます。

• グループA
  • 親機／子機
    • アプリケーションID：0xAAAAAAAA
    • 周波数チャネル：11
• グループB
  • 親機／子機
    • アプリケーションID：0xBBBBBBBB
    • 周波数チャネル：26

カスタム方法

1. TWELITE DIP を TWELITE R2 へ差し込み、USB-C ケーブルを使って PC と接続する
2. TWELITE STAGE アプリを立ち上げ、シリアルポート選択から対象の TWELITE R2 を選択する
3. メインメニューの「3: インタラクティブモード」を選択する
4. 大文字のRを押下して、設定を初期状態へ戻す
5. aを押下したのち、AAAAAAAA/BBBBBBBBを入力してEnterを押下する
6. cを押下したのち、11/26を入力してEnterを押下する
7. 大文字のSを押下して、設定を適用する（TWELITE はリセットされる）
8. ESCを何度か押してメインメニューへ戻り、TWELITE R2 の USB-C ケーブルを抜く
9. TWELITE DIP を取り外し、ブレッドボード等へ差し込み、回路へ接続する

動作確認

グループAとグループBの双方を「まずは使ってみる」の片方向デジタル信号の例のように配線し、親機へスイッチを、子機へ LED を接続します。

• グループAの親機のスイッチを押すと、グループAの子機の LED だけが光ります
• グループBの親機のスイッチを押すと、グループBの子機の LED だけが光ります

グループBの子機のアプリケーションIDを0xAAAAAAAAへ、周波数チャネルを11へ変更します。

• グループAの親機のスイッチを押すと、2台の子機の LED がどちらも光ります

低レイテンシモードの使用

初期状態では、送信元のDIxが送信先のDOxへ反映されるまでに30-70ms程度の遅延が生じます。チャタリングや無線パケットの干渉を避けるための処理が存在するからです。

低レイテンシモードは、これらの処理を簡略化することで遅延を3-10ms程度に短縮します。

インタラクティブモードによって送信側の端末の低レイテンシモードを有効化してみましょう。

使用する製品

TWELITE DIP	TWELITE R2
TWELITE 親機／子機	USB アダプター
超簡単！標準アプリ	-
2個	1個

カスタムの内容

インタラクティブモードの値を次のように設定し、送信側（親機）の低レイテンシモードを有効化します。

• 親機
  • オプションビット：0x00000001
• 子機：変更なし

カスタム方法

1. TWELITE DIP を TWELITE R2 へ差し込み、USB-C ケーブルを使って PC と接続する
2. TWELITE STAGE アプリを立ち上げ、シリアルポート選択から対象の TWELITE R2 を選択する
3. メインメニューの「3: インタラクティブモード」を選択する
4. 大文字のRを押下して、設定を初期状態へ戻す
5. oを押下したのち、00000001を入力してEnterを押下する
6. 大文字のSを押下して設定を適用する（TWELITE はリセットされる）
7. ESCを何度か押してメインメニューへ戻り、TWELITE R2 の USB-C ケーブルを抜く
8. TWELITE DIP を取り外し、ブレッドボード等へ差し込み、回路へ接続する

動作確認

親機と子機を「まずは使ってみる」の片方向デジタル信号の例のように配線し、親機へスイッチを、子機へ LED を接続します。

• 親機のスイッチを押すと、子機の LED が光ります
• 動作は初期状態と変わりませんが、少しレスポンスが向上したことを感じ取れるかもしれません
• 親機のDO1と子機のDI1へオシロスコープを接続して比較すると、その効果を確認できます

ボタン押下時のみ送信させる

初期状態では、入力状態が変化したときに送信を行うほか、1秒おきに送信します。

このとき、例えば送信側のボタンを押したまま電源を断つと、受信側の出力は残り続けてしまいます。

ボタン押下時のみ送信 設定では、送信側のDIxがLowのときに繰り返し送信を行い、Highへ遷移しても1秒間は送信を続けます。受信側のDOxをLowとしてから受信が途絶えた場合はHighへ戻します。

インタラクティブモードによってボタン押下時のみ送信するように変更してみましょう。

使用する製品

TWELITE DIP	TWELITE R2
TWELITE 親機／子機	USB アダプター
超簡単！標準アプリ	-
2個	1個

カスタムの内容

インタラクティブモードの値を次のように設定し、送信側（親機）と受信側（子機）のデジタル入出力の振る舞いを変更します。

• 親機／子機
  • オプションビット：0x00000100

カスタム方法

1. TWELITE DIP を TWELITE R2 へ差し込み、USB-C ケーブルを使って PC と接続する
2. TWELITE STAGE アプリを立ち上げ、シリアルポート選択から対象の TWELITE R2 を選択する
3. メインメニューの「3: インタラクティブモード」を選択する
4. 大文字のRを押下して、設定を初期状態へ戻す
5. oを押下したのち、00000100を入力してEnterを押下する
6. 大文字のSを押下して設定を適用する（TWELITE はリセットされる）
7. ESCを何度か押してメインメニューへ戻り、TWELITE R2 の USB-C ケーブルを抜く
8. TWELITE DIP を取り外し、ブレッドボード等へ差し込み、回路へ接続する

動作確認

親機と子機を「まずは使ってみる」の片方向デジタル信号の例のように配線し、親機へスイッチを、子機へ LED を接続します。

• 親機のスイッチを押すと、子機の LED が光ります
• 親機のスイッチを押したまま電源供給を断つと、子機のLEDは消えます（初期状態は消えない）

1.3 - UART機能によるPCとの連携

使用する製品

TWELITE DIP	TWELITE R2
TWELITE 親機／子機	USB アダプター
超簡単！標準アプリ	-
2個	1個

なお、TWELITE DIP と TWELITE R2 のペアは MONOSTICK 単体と同等です。次の組み合わせでも構いません。

TWELITE DIP	MONOSTICK
TWELITE 子機	TWELITE 親機
超簡単！標準アプリ	親機・中継機アプリ
1個	1個

TWELITE STAGE アプリの導入

TWELITE STAGE アプリは、ファームウェアの設定や書き換えに加え、親機との送受信を評価するための機能を備えたツールです。

TWELITE STAGE アプリは、TWELITE STAGE SDK に含まれています。

TWELITE STAGE アプリによる受信

超簡単！標準アプリの子機が送信するデータは、DIx/AIxポートの入力状態や電源電圧、送信元の論理デバイスIDといった情報を含んでいます。

シリアル文字列の表示

親機が子機から受信したデータは、親機がシリアル通信（UART）で出力する文字列を解釈することで取得できます。まずはこの文字列を表示してみましょう。

TWELITE STAGE アプリを立ち上げ、シリアルポート選択で親機を選択します。メインメニューの「1: ビューア」＞「1: ターミナル」を開いてください。

子機のデータを受信すると、次のようなメッセージを表示します。

:78811501C98201015A000391000C2E00810301FFFFFFFFFB

親機が出力するこのような文字列を解釈することで、子機が送信したデータを得ることができます。

なお、TWELITE の親機が出力する文字列は、基本的に次の形式へ従います。

• すべて ASCII 文字※
• 先頭は : (0x3A)
• 末端は CRLF (\r\n/0x0D 0x0A)
• ビッグエンディアン

※ シリアル通信アプリのバイナリ書式を除く

標準アプリ ビューア

上記のような形式はコンピュータにやさしいものですが、人間が確認するにはこれを解釈する必要があります。TWELITE STAGE アプリには、超簡単！標準アプリの子機が送信したデータを表す文字列を解釈して表示する機能があります。後述の Python ライブラリはこの解釈を行います。

メインメニューの「1: ビューア」へ戻り、「2: 標準アプリ ビューア」を開いてください。

タイムスタンプと論理デバイスID、シリアルIDとDIx/AIxの値を確認できます。

TWELITE STAGE アプリによる送信

これまでとは反対に、親機から子機へ無線パケットを送信し、子機の出力状態を変更することもできます。

コマンダー

メインメニューの「1: ビューア」へ戻り、「5: コマンダー」を開いてください。

DIxおよびAIxの入力をシミュレートしたパケットを送信できます。

使い方

• 送信先と入力状態を選択
• 送信をクリック

Python スクリプト

TWELITE STAGE アプリの「標準アプリ ビューア」および「コマンダー」は、どちらもシリアル通信によって文字列をやりとりしているに過ぎません。シリアル通信を利用できる環境であれば、自作のアプリケーションと親機を連携させることができます。

Python スクリプトを応用すれば、受信したデータを加工して保存したり、自作のソフトウェアから出力ポートを操作したりといった仕組みを実現できます。

MWings ライブラリの導入

MWings ライブラリは、TWELITE と Python スクリプトの連携を簡単に実現するためのライブラリです。具体的には、子機から受信したデータを表す文字列の解釈と、子機へ送信するデータの構築を行います。

PyPI からインストールできます。

Python スクリプトによる受信

TWELITE DIP のDI1へ接続したボタンが押された際にメッセージを表示する Python スクリプトを実装してみます。

サンプルスクリプトの実行

下記の内容のスクリプト dip_show_di1.py を作成してください。

# -*- coding:utf-8 -*-
# TWELTIE DIP start guide: receiving in python

import mwings as mw


def main():
    twelite = mw.Twelite(mw.utils.ask_user_for_port())

    @twelite.on(mw.common.PacketType.APP_TWELITE)
    def on_app_twelite(packet):
        if packet.di_state[0]:
            print("DI1 Pressed")

    try:
        twelite.daemon = True
        twelite.start()
        print("Started receiving")
        while True:
            twelite.join(0.5)
    except KeyboardInterrupt:
        print("Flushing...")
        twelite.stop()
        print("Completed")


if __name__ == "__main__":
    main()

スクリプトを実行すると、子機のDI1が Low になったときに DI1 Pressed と出力します。

実行時に複数の TWELITE R シリーズや MONOSTICK シリーズが接続されているときは、親機へ接続されたシリアルポートを選択してください。

poetry run python dip_show_di1.py
Multiple ports detected.
[1] /dev/cu.usbserial-R2xxxxxx TWE-Lite-R (Genuine)
[2] /dev/cu.usbserial-R2xxxxxx TWE-Lite-R (Genuine)
Select [1-2]: 2
Selected: /dev/cu.usbserial-R2xxxxxx
Started receiving
DI1 Pressed
DI1 Pressed
^CFlushing...
Completed

上記は macOS における例です。WindowsではCOMポート名を表示します。

サンプルスクリプトの解説

MWings ライブラリのインポート

import mwings as mw

短縮名 mw を使って呼び出せるようにしています。pandas as pd や numpy as np と同様です。

オブジェクトの作成

    twelite = mw.Twelite(mw.utils.ask_user_for_port())

親機をとやりとりするためのインタフェースとなる Twelite オブジェクトを作成しています。

引数にはシリアルポートを指定しますが、ここでは mw.utils.ask_users_for_port() ユーティリティを呼び出し、動的に決定しています。この関数はシリアルポートが存在しないときにエラーメッセージを出力し、1つだけ存在する場合はそのポートを、複数存在する場合はユーザが指定したポートを返します。

受信イベントハンドラの登録

    @twelite.on(mw.common.PacketType.APP_TWELITE)
    def on_app_twelite(packet):
        if packet.di_state[0]:
            print("DI1 Pressed")

超簡単！標準アプリの子機からのパケットを受信したときに呼び出されるイベントハンドラを登録しています。

イベントハンドラの登録は、Python のデコレータ(?)を使って行います。今回は超簡単！標準アプリ（App_Twelite）のデータを対象とするため、@twelite.on(mw.common.PacketType.APP_TWELITE) を記述しています。この記述の直後に定義された関数がハンドラとなります。関数名は問いませんが、Tweliteオブジェクトの初期化後に定義する必要があります。

今回は子機のDI1がLowになったことを検知するため、受信ハンドラが受け取る変数 packet（mwings.parsers.app_twelite.ParsedPacket）のうち、DIxの状態を示す List-like なオブジェクト di_state（デジタルインタフェースの状態）0番目の真偽値を判定しています。di_stateの各値は、Trueのときに Low を示します。

    @twelite.on(mw.common.PacketType.APP_TWELITE)
    def on_app_twelite(packet):
        print(packet.to_json(verbose=True, spread=False))

    @twelite.on(mw.common.PacketType.APP_TWELITE)
    def on_app_twelite(packet):
        print(packet.to_df(verbose=False).to_string())

データの待機

        twelite.daemon = True
        twelite.start()
        print("Started receiving")
        while True:
            twelite.join(0.5)

ここでは、別のスレッドで親機からのデータの待機を行っています。

Tweliteのオブジェクトは threading.Thread のサブクラスであり、ここではその機能によってデーモンスレッドを立ち上げ、スクリプトを終了するまでメインスレッドをブロックしています。

終了処理

        print("Flushing...")
        twelite.stop()
        print("Completed")

Ctrl-C が押された際には、twelite.stop()を呼び出すことでサブスレッドを終了しています。

Python スクリプトによる送信

次は、反対に TWELITE DIP のDO1へ接続された LED をPCから点滅させる Python スクリプトを実装してみます。

サンプルスクリプトの実行

下記の内容のスクリプト dip_blink_led.py を作成してください。

# -*- coding:utf-8 -*-
# TWELITE DIP start guide: blinking from python

from time import sleep

import mwings as mw


def main():
    twelite = mw.Twelite(mw.utils.ask_user_for_port())

    initial = {
        "destination_logical_id": 0x78,
        "di_to_change": [True, False, False, False],
        "di_state": [False, False, False, False],
    }
    command = mw.serializers.app_twelite.Command(**initial)

    while True:
        command.di_state[0] = not command.di_state[0]
        twelite.send(command)
        print(f"Flip DO1: {command.di_state[0]}")
        sleep(1)


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("...Aborting")

スクリプトを実行すると、子機のDO1が一秒おきに点滅します。

実行時に複数の TWELITE R シリーズや MONOSTICK シリーズが接続されているときは、親機へ接続されたシリアルポートを選択してください。

poetry run python dip_blink_led.py
Multiple ports detected.
[1] /dev/cu.usbserial-R2xxxxxx TWE-Lite-R (Genuine)
[2] /dev/cu.usbserial-R2xxxxxx TWE-Lite-R (Genuine)
Select [1-2]: 2
Selected: /dev/cu.usbserial-R2xxxxxx
Flip DO1: True
Flip DO1: False
Flip DO1: True
Flip DO1: False
Flip DO1: True
^C...Aborting

サンプルスクリプトの解説

MWings ライブラリのインポート

import mwings as mw

短縮名 mw を使って呼び出せるようにしています。pandas as pd や numpy as np と同様です。

オブジェクトの作成

    twelite = mw.Twelite(mw.utils.ask_user_for_port())

親機をとやりとりするためのインタフェースとなる Twelite オブジェクトを作成しています。

引数にはシリアルポートを指定しますが、ここでは mw.utils.ask_users_for_port() ユーティリティを呼び出し、動的に決定しています。この関数はシリアルポートが存在しないときにエラーメッセージを出力し、1つだけ存在する場合はそのポートを、複数存在する場合はユーザが指定したポートを返します。

親機へ送信するコマンドの作成

    initial = {
        "destination_logical_id": 0x78,
        "di_to_change": [True, False, False, False],
        "di_state": [False, False, False, False],
    }
    command = mw.serializers.app_twelite.Command(**initial)

超簡単！標準アプリの子機へ送信するパケットを生成するためのコマンドを表すデータ command（mwings.serializers.app_twelite.Command）を初期化しています。

辞書オブジェクト initial は、コマンドの初期状態を表しています。ここでは、送信先の論理デバイスIDを 0x78（全子機）としたうえで、DI1を変更対象、High 状態としています。

データの送信

    while True:
        command.di_state[0] = not command.di_state[0]
        twelite.send(command)
        print(f"Flip DO1: {command.di_state[0]}")
        sleep(1)

ここでは、コマンドデータの文字列への変換および親機への送信を1秒おきに行っています。

コマンドデータのうち、DOxの状態を示す List-like なオブジェクト di_state（デジタルインタフェースの状態）0番目の真偽値を反転させることで、点滅を実現しています。

1.4 - バイナリデータの伝送

使用する製品

TWELITE DIP	TWELITE R2
TWELITE 親機／子機	USB アダプター
シリアル通信アプリ	-
2個	2個

なお、TWELITE DIP と TWELITE R2 のペアは MONOSTICK 単体と同等です。次の組み合わせでも構いません。

MONOSTICK
TWELITE 親機／子機
シリアル通信アプリ
2個

シリアル通信アプリ

TWELITE のファームウェアを、シリアル通信の無線化に特化したシリアル通信アプリ（App_Uart）へ書き換えます。超簡単！標準アプリはシリアル通信によるバイナリデータの伝送機能を備えているものの、その機能は非常に限られているからです。

ファームウェアの書き換え

親機と子機、すべての端末を書き換えます。

1. TWELITE STAGE SDK を導入し、TWELITE STAGE アプリを立ち上げる
2. シリアルポート選択から接続したデバイスを選択する
3. 「メインメニュー」から「2: アプリ書換」を選択する
4. 「1: BINから選択」を選び、App_Uart... を選択する
5. 書き込みが完了するまで、数回Enterを押す

--- CONFIG/TWE UART APP V1-04-5/SID=0x82018ca0/LID=0x78 -- ---
 a: set Application ID (0x67720103)
 i: set Device ID (120=0x78)
 c: set Channels (18)
 x: set RF Conf (3)
 r: set Role (0x0)
 l: set Layer (0x1)
 b: set UART baud (38400)
 B: set UART option (8N1)
 m: set UART mode (E)
 k: set Tx Trigger (sep=0x0d0a, min_bytes=0 dly=0[ms])
 h: set header format [;U;%t;%i;0x%A;%q;%s;<*>;%X;\n]
 C: set crypt mode (0)
 o: set option bits (0x00000100)
---
 S: save Configuration
 R: reset to Defaults

通信モードの一覧

シリアル通信アプリには5つの通信モードがあり、用途に応じて使い分けることができます。

• 書式モード（アスキー）：送受信双方に書式を適用するモード
• 書式モード（バイナリ）：書式モード（アスキー）のバイナリ表記版
• チャットモード：テキストチャットを行うモード
• 透過モード：書式を利用せず純粋にUARTを無線化するモード
• ヘッダ付き透過モード：受信側の出力にのみ書式を適用するモード

初期状態はヘッダ付き透過モードです。

ここでは、次の4つのモードを使った通信テストの手順を紹介します。気になるものを選んでお試しください。

• ヘッダ付き透過モード
  • 送信側の書式はありません。
  • 受信側の書式から、送信元の論理デバイスIDや受信時の電波通信品質といった情報を得ることができます。
  • バランスのよいモードです。
• 透過モード
  • 送受信双方に書式はありません。
  • 送信側の入力と受信側の出力は同等です。
  • 最も簡単ですが、機能は限られています。
• 書式モード（アスキー）
  • 送受信双方へ書式を適用します。
  • 外部デバイスの対応が必要ですが、送信先の指定や送信元の識別ができます。
  • バイナリデータは16進数の文字列で表現します。
• 書式モード（バイナリ）
  • 送受信双方へ書式を適用します。
  • 外部デバイスの対応が必要ですが、送信先の指定や送信元の識別ができます。
  • バイナリデータはそのまま表現します。

今回は同一のPCへ2台の TWELITE を接続し、データをループバックさせてみましょう。通常は外部デバイス同士を無線経由で接続します。

ヘッダ付き透過モード

ヘッダ付き透過モードを使用して、ASCIIデータHelloという文字列を双方から送信してみましょう。

設定方法

シリアル通信アプリの既定のモードはヘッダ付き透過モードです。よって初期設定のまま使用します。

通信テスト

1. TWELITE STAGE アプリを2つ立ち上げる

TWELITE STAGE アプリ（TWELITE_Stage.exe/.command/.run）を2つ立ち上げてください。

2. ターミナルを表示する

双方の TWELITE STAGE アプリにおいてシリアルポートを選択したのち、「1: ビューア」＞「1: ターミナル」を選択します。

3. 片側から送信

片方の画面を選択し、Helloと入力してEnterを押します。もう片方の画面へ反映されます。

4. 反対側から送信

もう片方の画面を選択し、Helloと入力してEnterを押します。元の画面へ反映されます。

;U;00052;120;0x82036841;255;000;Hello;79;

透過モード

透過モードを使用して、ASCIIデータHelloという文字列を双方から送信してみましょう。

設定方法

m：通信モードをDとします。

通信テスト

1. TWELITE STAGE アプリを2つ立ち上げる

TWELITE STAGE アプリ（TWELITE_Stage.exe/.command/.run）を2つ立ち上げてください。

2. ターミナルを表示する

双方の TWELITE STAGE アプリにおいてシリアルポートを選択したのち、「1: ビューア」＞「1: ターミナル」を選択します。

3. 片側から送信

片方の画面を選択し、Helloと入力してEnterを押します。もう片方の画面へ反映されます。

4. 反対側から送信

もう片方の画面を選択し、Helloと入力してEnterを押します。元の画面へ反映されます。

入出力のどちらにも書式がないため、入力したデータをそのまま出力します。

Hello

書式モード（アスキー）

書式モード（アスキー）を使用して、バイナリデータ 0x5A 0xAB 0x90 0x00 を双方から送信してみましょう。

設定方法

m：通信モードをAとします。

片方の端末のi：論理デバイスIDを0（親機）としたうえで、もう片方の端末は1（子機、ID1）とします。

通信テスト（簡易形式）

まずは、簡易形式のシンプルな書式を試してみましょう。

1. TWELITE STAGE アプリを2つ立ち上げる

TWELITE STAGE アプリ（TWELITE_Stage.exe/.command/.run）を2つ立ち上げてください。

2. ターミナルを表示する

双方の TWELITE STAGE アプリにおいてシリアルポートを選択したのち、「1: ビューア」＞「1: ターミナル」を選択します。

3. 親機側から送信

まず、以下の系列をコピーします。

:01235AAB900047

次に、親機側の画面を選択します。

最後に、Alt+V/⌘+Vを押してペーストし、Enterを押します。子機側の画面へ反映されます。

:00235AAB900048

4. 子機側から送信

まず、以下の系列をコピーします。

:00235AAB900048

次に、子機側の画面を選択します。

最後に、Alt+V/⌘+Vを押してペーストし、Enterを押します。親機側の画面へ反映されます。

:01235AAB900047

通信テスト（拡張形式）

次に、拡張形式の高度な書式を試してみましょう。

1. TWELITE STAGE アプリを2つ立ち上げる

TWELITE STAGE アプリ（TWELITE_Stage.exe/.command/.run）を2つ立ち上げてください。

2. ターミナルを表示する

双方の TWELITE STAGE アプリにおいてシリアルポートを選択したのち、「1: ビューア」＞「1: ターミナル」を選択します。

3. 親機側から送信

まず、以下の系列をコピーします。

:01A0CDFF5AAB9000FE

次に、親機側の画面を選択します。

最後に、Alt+V/⌘+Vを押してペーストし、Enterを押します。子機側の画面へ反映されます。

:00A0CD82036841FFFFFFFFFF00045AAB9000D1

4. 子機側から送信

まず、以下の系列をコピーします。

:00A0CDFF5AAB9000FF

次に、子機側の画面を選択します。

最後に、Alt+V/⌘+Vを押してペーストし、Enterを押します。親機側の画面へ反映されます。

:01A0CD820163B2FFFFFFFFFF00045AAB900066

書式モード（バイナリ）

書式モード（バイナリ）を使用して、バイナリデータ 0x5A 0xAB 0x90 0x00 を双方から送信してみましょう。

設定方法

m：通信モードをBとします。

片方の端末のi：論理デバイスIDを0（親機）としたうえで、もう片方の端末は1（子機、ID1）とします。

バイナリへ対応した環境を用意

TWELITE STAGE アプリのターミナル機能や TeraTerm はバイナリデータの扱いに対応していないため、バイナリ形式に対応したターミナルソフトを導入する必要があります。

ここでは、一例としてCoolTermを使用します。

通信テスト（簡易形式）

まずは、簡易形式のシンプルな書式を試してみましょう。

1. CoolTerm の画面を2つ開く

CoolTerm の画面を2つ開き、それぞれのデバイスへ接続します。

受信したデータを16進数で表示するために、View > View Hex を選択しておきます。Connect を押して接続します。

2. 親機側から送信

親機側の画面を選択し、Connection > Send String... を選択して送信画面を開き、ラジオボタンのHex を選んでおきます。

次の内容を入力し、Send を押して親機へ送信します。

A5 5A 80 06 01 23 5A AB 90 00 43 04

A5 5A 80 06 00 23 5A AB 90 00 42 04

3. 子機側から送信

親機と同様に子機側の画面を選択し、Connection > Send String... を選択して送信画面を開き、ラジオボタンのHex を選んでおきます。

次の内容を入力し、Send を押して親機へ送信します。

A5 5A 80 06 00 23 5A AB 90 00 42 04

A5 5A 80 06 01 23 5A AB 90 00 43 04

通信テスト（拡張形式）

次に、拡張形式の高度な書式を試してみましょう。

1. CoolTerm の画面を2つ開く

CoolTerm の画面を2つ開き、それぞれのデバイスへ接続します。

受信したデータを16進数で表示するために、View > View Hex を選択しておきます。Connect を押して接続します。

2. 親機側から送信

親機側の画面を選択し、Connection > Send String... を選択して送信画面を開き、ラジオボタンのHex を選んでおきます。

次の内容を入力し、Send を押して子機へ送信します。

A5 5A 80 08 01 A0 CD FF 5A AB 90 00 F2 04

A5 5A 80 12 00 A0 CD 81 0E 0E 23 FF FF FF FF BA 00 04 5A AB 90 00 10 04

3. 子機側から送信

親機と同様に子機側の画面を選択し、Connection > Send String... を選択して送信画面を開き、ラジオボタンのHex を選んでおきます。

次の内容を入力し、Send を押して親機へ送信します。

A5 5A 80 08 00 A0 CD FF 5A AB 90 00 F3 04

A5 5A 80 12 01 A0 CD 81 0E 00 92 FF FF FF FF BA 00 04 5A AB 90 00 AE 04

1.5 - リモコンアプリによる高度なデジタル伝送

使用する製品

TWELITE DIP	TWELITE R2
TWELITE 親機／子機	USB アダプター
超簡単！標準アプリ	-
2個	1個

リモコンアプリ

TWELITE のファームウェアを、デジタル信号の伝送に特化したリモコンアプリ（App_IO）へ書き換えます。超簡単！標準アプリはデジタル信号の伝送機能を備えているものの、入出力は4本に限られています。リモコンアプリは入出力を増やし、その組み合わせを切り替えることができます。

ファームウェアの書き換え

親機と子機、すべての端末を書き換えます。

1. TWELITE STAGE SDK を導入し、TWELITE STAGE アプリを立ち上げる
2. シリアルポート選択から接続したデバイスを選択する
3. 「メインメニュー」から「2: アプリ書換」を選択する
4. 「1: BINから選択」を選び、App_IO... を選択する
5. 書き込みが完了するまで、数回Enterを押す

--- CONFIG/APP_IO V1-03-2/SID=0x86300001/LID=0x00 ---
 a: set Application ID (0x67720107)
 i: set Device ID (--)
 c: set Channels (16)
 x: set Tx Power (3)
 t: set mode4 sleep dur (1000ms)
 y: set mode7 sleep dur (0s)
 f: set mode3 fps (16)
 d: set hold mask (000000000000)
 D: set hold dur (1000ms)
 o: set Option Bits (0x00000000)
 b: set UART baud (38400)
 p: set UART parity (N)
 C: set crypt mode (0)
 K: set crypt key []
---
 S: save Configuration
 R: reset to Defaults

まずは使ってみる

初期状態のリモコンアプリは、次のように子機が12本のデジタル入力ポートを、親機が12本のデジタル出力ポートを備えた片方向伝送の設定としています。まずは配線してみましょう。

親機の配線

初期状態のとき、親機は最大12本のデジタル信号を受信できます。

上図では DIP 9番 O3 ピンを出力として使用していますが、他のOxピンも同様に使用できます。また、超簡単！標準アプリにはないチャネル上書き機能を検証するため、DIP 23番 C1 ピンへタクトスイッチを接続しています。

子機の配線

初期状態のとき、子機は最大12本のデジタル信号を送信できます。

上図では DIP 17番 I3 ピンを入力として使用していますが、他のIxピンも同様に使用できます。また、こちらも同様にチャネル上書き機能を検証するため、DIP 23番 C1 ピンへタクトスイッチを接続しています。

動作確認

• 子機のI3へ接続したボタンを押したり離したりします
  • 親機のO3へ接続した LED が点灯したり消灯したりします。
• 子機のC1へ接続したボタンを押しながら、I3 のボタンを押したり離したりします
  • 子機の周波数チャネルを一時的に上書きするため、通信できません。
• 親機と子機のC1へ接続したボタンを押しながら、子機のI3へ接続したボタンを押したり離したりします
  • 親機と子機の周波数チャネルを両方とも上書きするため、再び通信できるようになります。

高度な機能を使ってみる

次のようなシチュエーションを想定して、インタラクティブモードによる設定変更を行ってみましょう。

• 子機と親機の入出力の割り当てを変更し、双方とも6入力6出力とする
• 子機の入力を最短で親機へ反映する
• パケットが断絶した際に出力信号を復帰させる
• 子機を省電力リモコンとする
• 子機を長押しによる連続送信へ対応した省電力リモコンとする

子機と親機を6入力6出力とする

インタラクティブモードからオプションビットの値を変更することで、入出力の割り当てを下記のなかから選ぶことができます。

ここでは、双方とも6入力6出力としてみましょう。

1. TWELITE STAGE アプリを立ち上げる
2. シリアルポート選択から接続したデバイスを選択する
3. 「メインメニュー」から「3: インタラクティブモード」を選択する
4. Enterを押し、設定項目が表示されることを確認する
5. o（小文字）を入力し、オプションビットの値 00002000 を入力してEnterを押下する
6. S（大文字）を入力して保存し、ESCを押下して終了

これで次のように、子機と親機がともに6本の入出力をもつ割り当てとなります。

子機の入力を最短で親機へ反映する

子機の連続モードを使用するとき、子機の入力から親機の出力までに通常は 30-70ms 程度の遅延が発生します。すばやい応答が必要とされる場面では、この遅延を小さくするためにインタラクティブモードからオプションビット0x00000001：低レイテンシモードを設定します。

子機の設定

1. TWELITE STAGE アプリを立ち上げる
2. シリアルポート選択から接続したデバイスを選択する
3. 「メインメニュー」から「3: インタラクティブモード」を選択する
4. Enterを押し、設定項目が表示されることを確認する
5. o（小文字）を入力し、オプションビットの値 00000001 を入力してEnterを押下する
6. S（大文字）を入力して保存し、ESCを押下して終了

パケットの断絶時に信号を復帰させる

いずれかの入力がLoの状態のまま電波が途切れた場合には、実際の入力がLoからHiへ戻っても出力はLoを維持します。

パケットが断絶した際に信号を元の状態へ戻すには、リモコン長押しモードを適用します。リモコン長押しモードでは、送信側の入力が変化してからしばらくの間、継続的に信号を送信します。受信側では、Lo 状態を示すパケットが断絶してから一定の時間が経過すると、タイムアウトして出力を Hi へ戻します。

子機の設定

1. M1/M2/M3を開放し、子機：連続モード を設定する
2. TWELITE STAGE アプリを立ち上げる
3. シリアルポート選択から接続したデバイスを選択する
4. 「メインメニュー」から「3: インタラクティブモード」を選択する
5. Enterを押し、設定項目が表示されることを確認する
6. o（小文字）を入力し、オプションビットの値 00000100 を入力してEnterを押下する
7. d（小文字）を入力し、ホールド／長押しモードの対象（000000001010ならI2とI4、長押し時に連続送信するポート）を入力してEnterを押下する
8. D（大文字）を入力し、ホールド／長押しモードの時間（すべての入力がLoからHiへ戻ったあとに送信を続ける時間）を入力してEnterを押下する
9. S（大文字）を入力して保存し、ESCを押下して終了

親機の設定

1. M1/M2/M3を開放し、子機：連続モード を設定する
2. TWELITE STAGE アプリを立ち上げる
3. シリアルポート選択から接続したデバイスを選択する
4. 「メインメニュー」から「3: インタラクティブモード」を選択する
5. Enterを押し、設定項目が表示されることを確認する
6. o（小文字）を入力し、オプションビットの値 00000100 を入力してEnterを押下する
7. d（小文字）を入力し、ホールド／長押しモードの対象（000000001010ならO2とO4、断絶時にタイムアウトするポート）を入力してEnterを押下する
8. D（大文字）を入力し、ホールド／長押しモードの時間（Loの信号が途切れてからHiへ戻すまでの時間）を入力してEnterを押下する
9. S（大文字）を入力して保存し、ESCを押下して終了

子機を省電力リモコンとする

子機を電池で駆動させる場合には、スリープと起床を繰り返す間欠モードが有効です。低レイテンシモードおよびホールドモードを併用することで、子機のボタンを押した際に親機の出力を設定した時間にわたって維持する動作を実現できます。

子機の設定

1. M1/M2/M3をGNDへ接続し、子機：間欠10秒モード を設定する
2. TWELITE STAGE アプリを立ち上げる
3. シリアルポート選択から接続したデバイスを選択する
4. 「メインメニュー」から「3: インタラクティブモード」を選択する
5. Enterを押し、設定項目が表示されることを確認する
6. o（小文字）を入力し、オプションビットの値 00000001 を入力してEnterを押下する
7. S（大文字）を入力して保存し、ESCを押下して終了

親機の設定

1. M1/M2/M3を開放し、子機：連続モード を設定する
2. TWELITE STAGE アプリを立ち上げる
3. シリアルポート選択から接続したデバイスを選択する
4. 「メインメニュー」から「3: インタラクティブモード」を選択する
5. Enterを押し、設定項目が表示されることを確認する
6. d（小文字）を入力し、ホールド／長押しモードの対象（000000001010ならO2とO4、ホールドするポート）を入力してEnterを押下する
7. D（大文字）を入力し、ホールド／長押しモードの時間（ホールドする時間）を入力してEnterを押下する
8. S（大文字）を入力して保存し、ESCを押下して終了

子機を長押し省電力リモコンとする

子機を電池で駆動させる場合には、スリープと起床を繰り返す間欠モードが有効です。低レイテンシモードおよびリモコン長押しモードを併用することで、子機のボタンを押している間に親機への送信を連続的に行うことができます。また、子機のボタンを離したあとに一定の時間にわたって送信を続け、親機側では子機のボタンを押した状態の電波が途切れてから一定の時間が経過した場合に出力を元に戻します。このため、省電力性能に優れた子機の入力をより確実に親機へ届けることができます。

子機の設定

1. M1/M2/M3をGNDへ接続し、子機：間欠10秒モード を設定する
2. TWELITE STAGE アプリを立ち上げる
3. シリアルポート選択から接続したデバイスを選択する
4. 「メインメニュー」から「3: インタラクティブモード」を選択する
5. Enterを押し、設定項目が表示されることを確認する
6. o（小文字）を入力し、オプションビットの値 00000103（00000100+00000001+00000002） を入力してEnterを押下する
7. d（小文字）を入力し、ホールド／長押しモードの対象（000000001010ならI2とI4、長押し時に連続送信するポート）を入力してEnterを押下する
8. D（大文字）を入力し、ホールド／長押しモードの時間（すべての入力がLoからHiへ戻ったあとに送信を続ける時間）を入力してEnterを押下する
9. S（大文字）を入力して保存し、ESCを押下して終了

親機の設定

1. M1/M2/M3を開放し、子機：連続モード を設定する
2. TWELITE STAGE アプリを立ち上げる
3. シリアルポート選択から接続したデバイスを選択する
4. 「メインメニュー」から「3: インタラクティブモード」を選択する
5. Enterを押し、設定項目が表示されることを確認する
6. o（小文字）を入力し、オプションビットの値 00000100 を入力してEnterを押下する
7. d（小文字）を入力し、ホールド／長押しモードの対象（000000001010ならO2とO4、断絶時にタイムアウトするポート）を入力してEnterを押下する
8. D（大文字）を入力し、ホールド／長押しモードの時間（Loの信号が途切れてからHiへ戻すまでの時間）を入力してEnterを押下する
9. S（大文字）を入力して保存し、ESCを押下して終了

2 - TWELITE SPOT

TWELITE と ESP32 で広がる世界

TWELITE SPOT は、小型で省電力、さらにペアリングをしないため多くの端末を同時に使用できる TWELITE シリーズと無線 LAN マイコンモジュール ESP32 を組み合わせた製品です。

ESP32 のファームウェアを開発することで、例えば下記のようなシステムを実現できます。

ローカルサーバ	ローカルゲートウェイ	IoT ゲートウェイ
TWELITE 子機のデータを LAN 内で共有	TWELITE 子機のデータを LAN 内で利用	TWELITE 子機のデータをクラウドに利用

ローカルサーバ

ESP32 をサーバとして使用します。例えば、TWELITE CUE が計測した加速度データをスマートフォンに表示したり、TWELITE DIP の出力ポートをスマートフォンで操作したりすることができます。

ローカルゲートウェイ

ESP32 を LAN に接続します。例えば、ビル全体に設置した TWELITE ARIA が送るデータを各フロアの TWELITE SPOT で受信し、LAN 上のサーバに全フロアの温湿度データを集約することができます。

IoT ゲートウェイ

ESP32 をインターネットに接続します。例えば、TWELITE CUE と磁石をドアに取り付け、取得したドアの開閉状態から、ドアが開いたままであることをクラウド上で検知できます。

Arduino IDE と専用ライブラリによる開発

TWELITE SPOT によるシステムを構築するには、ESP32 のファームウェアを開発する必要があります。

このとき、ESP32 のファームウェア開発には Arduino IDE が使用できます。

Arduino ライブラリマネージャで配布中の MWings ライブラリ により、TWELITE 子機からのパケット受信や TWELITE 子機へのコマンド送信を簡単に行うことができます。

スタートガイドの流れ

このスタートガイドでは、TWELITE SPOT の動作確認、ESP32 開発環境の構築、簡単なスケッチの作成および書き込みを行います。

1. TWELITE SPOT の動作を確認する

まずは使ってみる

内容

TWELITE SPOT にプリインストールされているアプリを使って、加速度センサー無線タグ TWELITE CUE のデータをスマートフォンで閲覧してみます。

必要なもの

TWELITE SPOT	TWELITE CUE
TWELITE 親機	TWELITE 子機

2. ESP32 の Hello World を行う

ESP32 を使ったファームウェア開発の基礎

内容

開発環境の構築、Hello World スケッチの作成・書き込み、動作確認を行ってみます。

必要なもの

TWELITE SPOT	TWELITE R3
ファームウェアを書き込むための TWELITE SPOT 本体	PC と TWELITE SPOT を接続するための USB アダプター

3. TWELITE CUE からデータを取得する

TWELITE との通信

内容

TWELITE CUE の加速度データを ESP32 から出力してみます。

必要なもの

TWELITE SPOT	TWELITE CUE	TWELITE R3
ファームウェアを書き込むための TWELITE SPOT 本体	TWELITE SPOT と通信するための TWELITE 子機	PC と TWELITE SPOT を接続するための USB アダプター

2.1 - まずは使ってみる

ここでは、TWELITE SPOT が無線 LAN のアクセスポイントとして機能します。

用意するもの

• 無線LANゲートウェイ TWELITE SPOT
  • 電源用 USB-C ケーブル
  • USB AC アダプタ（1A 以上供給できるもの）
• 加速度センサー無線タグ TWELITE CUE （お持ちでない場合はご購入ください 👉 販売店一覧）
• 📱 スマートフォン

TWELITE SPOT の動作を確認する

1. 本体を起動する ⚡

TWELITE SPOT の側面に USB-C ケーブルを接続し、USB AC アダプタから電源を供給してください。

2. TWELITE CUE を起動する ⚡

TWELITE CUE に CR2032 型コイン電池を挿入してください。ただちに動作を開始します。

3. スマートフォンを接続する 📱

スマートフォンの Wi-Fi 設定からネットワーク TWELITE SPOT (XXXX) に接続してください。

4. Webブラウザを開く 🌐

スマートフォンのWebブラウザを開き、spot.local へアクセスしてください。

以下のような画面が表示されます。

5. CUE ビューアを開く 📈

CUE Viewer をタップして、CUE ビューアの画面を開いてください。

以下のような画面が表示されます。

2.2 - ESP32 を使ったファームウェア開発の基礎

用意するもの

• 無線LANゲートウェイ TWELITE SPOT
  • 電源用 USB-C ケーブル
  • USB AC アダプタ（1A 以上供給できるもの）
• USBアダプター TWELITE R3 （お持ちでない場合はご購入ください 👉 販売店一覧）
  • 通信用 USB-C ケーブル
• 💻 コンピュータ

環境を構築する

1. IDE を導入する 🚛

コンピュータに Arduino IDE 1.x を導入していない場合は、Arduino 公式ダウンロードページから Legacy IDE (1.8.X) をダウンロードのうえ、これをインストールしてください。

2. ツールチェインを導入する 🚚

Arduino IDE 1.x に Arduino core for the ESP32 を導入していない場合は、ボードマネージャの URL に下記を追加し、esp32 ボード定義をインストールしてください。

https://espressif.github.io/arduino-esp32/package_esp32_index.json

3. ボード設定を行う ⚙️

TWELITE SPOT に合わせて、Arduino core for the ESP32 の設定を行います。

ボード種別を選択する

ツールバーの ツール -> ボード -> ESP32 Arduino -> ESP32 Dev Module を選択してください。

ボード設定を行う

下図と同様に設定してください。

TWELITE SPOT を準備する

1. フタをはずす ⛏️

TWELITE SPOT のケース上面のフタをはずしてください。

スイッチやコネクタ類が露出します。

2. TWELITE R3 / R2 をつなぐ 🔌

ESP32用 7P インターフェイス（ESP32 と記載）に TWELITE R3 / R2 を接続してください。

3. USB-C 電源をつなぐ ⚡

側面の USB-C コネクタ に 5V 電源を供給してください。

スケッチを動かす

Arduino では、プログラムコード／プロジェクトのことをスケッチと呼びます。

1. スケッチを作成する 👨‍💻

ESP32 から文字列をシリアル出力し、Arduino IDE のシリアルモニタに出力する Hello World スケッチを作成します。

Arduino IDE を起動して、下記のコードを入力してください。

void setup() {
  Serial.begin(115200);
  Serial.println("Hello, World!");
}

void loop() {
}

setup() の内容は起動時に一度だけ実行されます。一方、loop() の内容は際限なく繰り返し実行されます。

2行目では、シリアルポートのボーレート（通信速度）を 115200bps に設定しています。

  Serial.begin(115200);

3行目では、"Hello, World!" という文字列をシリアルポートに出力しています。

  Serial.println("Hello, World!");

2. スケッチを書き込む ⚒️

シリアルポートを選択する

ツール -> シリアルポート メニューから、 接続したデバイス（TWELITE R シリーズ）のポートを選択してください。

ESP32 を起動する

ESP32 をプログラムモードで起動します。

ESP32 リセットスイッチ EN(RST) と ESP32 ブートスイッチ BOOT を押し、EN(RST) -> BOOT の順で離してください。

スケッチを書き込む

Arduino IDE 上部の マイコンボードに書き込む ボタンをクリックしてください。

3. シリアルモニタを開く 🖥️

画面を開く

Arduino IDE 右上の シリアルモニタ ボタンをクリックしてください。

設定する

シリアルモニタ画面の右下のボーレートを 115200 に設定してください。

4. スケッチを動かす 🚀

ESP32 を再起動する

書き込みが完了したら、TWELITE SPOT の ESP32 リセットスイッチ EN(RST) を押して離し、ESP32 をリセットしてください。

シリアルモニタを確認する

シリアルモニタに以下の文字列が表示されたら成功です。

Hello, World!

2.3 - TWELITE 子機からのデータ受信

用意するもの

• 無線LANゲートウェイ TWELITE SPOT
  • 電源用 USB-C ケーブル
  • USB AC アダプタ（1A 以上供給できるもの）
• 加速度センサー無線タグ TWELITE CUE （お持ちでない場合はご購入ください 👉 販売店一覧）
  • CR2032 コイン電池
• USBアダプター TWELITE R3 （お持ちでない場合はご購入ください 👉 販売店一覧）
  • 通信用 USB-C ケーブル
• 💻 コンピュータ

環境を構築する

1. 開発環境を導入する 🚛

ESP32 を使ったファームウェア開発の基礎 の環境構築を行っていない場合は、これを実施してください。

2. ボード設定を行う ⚙️

ボード種別を ESP32 Dev Module としたうえで、下記のように設定してください。

3. ライブラリを導入する 🚚

ESP32 から TWELITE を使うために必要となる MWings ライブラリをインストールします。

スケッチ -> ライブラリをインクルード -> ライブラリを管理… を開いてください。

検索ボックスに MWings と入力し、MWings をインストールしてください。

TWELITE SPOT を準備する

1. フタをはずす ⛏️

TWELITE SPOT のケース上面のフタをはずしてください。

2. ケーブルをつなぐ 🔌

ESP32用 7P インターフェイス（ESP32 と記載）に TWELITE R3 / R2 を接続したうえで、側面の USB-C コネクタ に 5V 電源を供給してください。

まずはスケッチを動かしてみる

1. サンプルを開く 📂

Arduino IDE を起動し、ファイル -> スケッチ例 -> MWings -> monitor_spot_app_cue を選択してください。

2. シリアルポートを選ぶ ⚙️

ツール -> シリアルポート メニューから、 接続したデバイス（TWELITE R シリーズ）のポートを選択してください。

3. ESP32 を起動する 👇

ESP32 をプログラムモードで起動します。

リセットスイッチ EN(RST) と ESP32 ブートスイッチ BOOT を押し、EN(RST) -> BOOT の順で離してください。

4. スケッチを書き込む ⚒️

Arduino IDE 上部の マイコンボードに書き込む ボタンをクリックしてください。

5. シリアルモニタを開く 🖥️

画面を開く

Arduino IDE 右上の シリアルモニタ ボタンをクリックしてください。

設定する

シリアルモニタのボーレートを 115200 に設定してください。

6. ESP32 を再起動する 🚀

書き込みが完了したら、TWELITE SPOT の ESP32 リセットスイッチ EN(RST) を押して離し、ESP32 をリセットしてください。

7. 起動を確認する 💬

シリアルモニタに以下の文字列が表示されたら、起動に成功しています。

Monitor example for TWELITE SPOT: App_CUE (CUE Mode)

Monitor example for TWELITE SPOT: App_ARIA (ARIA Mode)

8. TWELITE CUE を起動する ⚡

TWELITE CUE に CR2032 型コイン電池を挿入してください。ただちに動作を開始します。

9. 受信を確認する 💬

シリアルモニタに以下のような文字列が表示されたら、TWELITE CUE からのデータ受信に成功しています。

Packet Number:     #3
Source Logical ID: 0x1
LQI:               147
Supply Voltage:    3310 mV
Accel Event:       Dice (1)
Accel X Axis [0]:  72 mG
Accel Y Axis [0]:  -64 mG
Accel Z Axis [0]:  1000 mG
Magnet State:      Leaving or Not found

スケッチの解説

サンプルスケッチ（monitor_spot_app_cue.ino）の内容を簡単に解説します。

ライブラリのインクルード

4行目では、さきほど導入した MWings ライブラリをインクルードしています。

#include "MWings.h"

ピン番号の定義

6-8行目では、ピン番号を定義しています。

const int RST_PIN = 5;
const int PRG_PIN = 4;
const int LED_PIN = 18;

TWELITE 設定の定義

10-11行目では、TWELITE SPOT に搭載された TWELITE 親機に適用する設定を定義しています。

const uint8_t TWE_CHANNEL = 18;
const uint32_t TWE_APP_ID = 0x67720102;

シリアルポートの設定

19-21行目では、使用するシリアルポートを初期化するとともに、シリアルモニタへ起動メッセージを出力しています。

  Serial.begin(115200);
  Serial.println("Monitor example for TWELITE SPOT: App_CUE (CUE Mode)");
  Serial2.begin(115200);

Serial は、Arduino IDE の シリアルモニタとの通信に使います。シリアルモニタの設定に合わせて、ボーレートを 115200 bps としています。

一方、Serial2 は、TWELITE SPOT に搭載された TWELITE 親機との通信に使います。こちらも TWELITE 親機の初期設定に合わせて、ボーレートを 115200 bps としています。

TWELITE の設定

24-26行目では、Twelite.begin() を呼び出し、TWELITE SPOT に搭載された TWELITE 親機の設定と起動を行っています。

    Twelite.begin(Serial2,
                      LED_PIN, RST_PIN, PRG_PIN,
                      TWE_CHANNEL, TWE_APP_ID);

パケット受信時のイベントの登録

29-49行目では、Twelite.on() を呼び出し、TWELITE CUE から送られたデータに対して行う処理を登録しています。

ここでは、受信したパケットの内容をシリアルモニタに出力しています。

    Twelite.on([](const ParsedAppCuePacket& packet) {
        Serial.println("");
        Serial.print("Packet Number:     #");
        Serial.println(packet.u16SequenceNumber, DEC);
        Serial.print("Source Logical ID: 0x");
        Serial.println(packet.u8SourceLogicalId, HEX);
        Serial.print("LQI:               ");
        Serial.println(packet.u8Lqi, DEC);
        Serial.print("Supply Voltage:    ");
        Serial.print(packet.u16SupplyVoltage, DEC); Serial.println(" mV");
        Serial.print("Accel Event:       ");
        printAccelEvent(packet.u8AccelEvent);
        Serial.print("Accel X Axis [0]:  ");
        Serial.print(packet.i16SamplesX[0], DEC); Serial.println(" mG");
        Serial.print("Accel Y Axis [0]:  ");
        Serial.print(packet.i16SamplesY[0], DEC); Serial.println(" mG");
        Serial.print("Accel Z Axis [0]:  ");
        Serial.print(packet.i16SamplesZ[0], DEC); Serial.println(" mG");
        Serial.print("Magnet State:      ");
        printMagnetState(packet.u8MagnetState, packet.bMagnetStateChanged);
    });

上記のイベントは、TWELITE CUEからのパケットを受信したときにだけ呼び出されます。

受信したパケットの内容は ParsedAppCuePacket 型の引数 packet に格納されます。

packet には、下記のデータが含まれています（太字 のデータを上記のコード中で使用しています）。

Twelite.on([](const ParsedAppAriaPacket& packet) {
    // Handle packet...
});

TWELITE のデータの更新

55行目では、Twelite.update() を呼び出しています。

    Twelite.update();

Twelite.update() は、TWELITE 親機から送信されるパケットデータ（ModBus ASCII 形式）を順次1バイトずつ読み出す関数です。

2.4 - 関連情報

MWings ライブラリ

• GitHub リポジトリ：monowireless/mwings_arduino
• MWings API リファレンス：TWELITE Wings API for 32-bit Arduinos

TWELITE 製品データシート

• TWELITE SPOT
• TWELITE BLUE
• TWELITE R3

TWELITE SPOT マニュアル

スケッチ解説

• 無線 LAN なし
  • 超簡単！標準アプリのデータを取得・操作
  • キューアプリのデータを取得
  • アリアアプリのデータを取得
• 無線 LAN あり
  • プリインストール済みスケッチ
  • WebSocket による中継
  • REST API の使用
  • Google スプレッドシートの利用

その他

• 無線性能に配慮した設置方法
• Arduino IDE 1.x による開発環境の構築方法
• ESP32 へのスケッチの書き込み方法
• ESP32 へのファイルの書き込み方法
• ESP32 のパーティションテーブルを指定した書き込み方法

外部リンク

Arduino

• 公式サイト：Arduino - Home
  • API リファレンス：Arduino Reference - Arduino Reference
  • コーディングスタイルガイド：Arduino Style Guide for Creating Libraries | Arduino Documentation
  • 公式 JSON ライブラリ：arduino-libraries/Arduino_JSON: Official JSON Library for Arduino
  • 公式 NTP ライブラリ：arduino-libraries/NTPClient: Connect to a NTP server

ESP32

• 製品情報：ESP32 Wi-Fi & Bluetooth MCU I Espressif Systems
  • データシート：esp32_datasheet_en.pdf
• Arduino 向けツールチェイン：espressif/arduino-esp32: Arduino core for the ESP32
  • スタートガイド：Getting Started — Arduino-ESP32 documentation
  • 導入方法：Installing — Arduino-ESP32 documentation
  • API リファレンス：Libraries — Arduino-ESP32 documentation
    • Wi-Fi API：Wi-Fi API — Arduino-ESP32 documentation
  • チュートリアル：Tutorials — Arduino-ESP32 documentation
  • トラブルシューティング：Troubleshooting — Arduino-ESP32 documentation
• ESP-IDF：espressif/esp-idf: Espressif IoT Development Framework
  • ドキュメント：ESP-IDF Programming Guide - ESP32
    • マルチタスクやキュー関連：FreeRTOS (ESP-IDF) - ESP32

コミュニティ

ライブラリ

• 非同期 TCP：me-no-dev/AsyncTCP: Async TCP Library for ESP32
• 非同期 Web サーバ：me-no-dev/ESPAsyncWebServer: Async Web Server for ESP8266 and ESP32
• WebSocket：Links2004/arduinoWebSockets: arduinoWebSockets
• Google スプレッドシート：mobizt/ESP-Google-Sheet-Client: Arduino Google Sheet REST client library
• 日付と時刻：PaulStoffregen/Time: Time library for Arduino
• Seeed 96x96 / 128x128 OLED：Seeed-Studio/OLED_Display_96X96: Seeed OLED Display 96*96 library

プラグイン

• ファイル書き込み：me-no-dev/arduino-esp32fs-plugin: Arduino plugin for uploading files to ESP32 file system
• スタックトレース：me-no-dev/EspExceptionDecoder: Exception Stack Trace Decoder for ESP8266 and ESP32

3 - TWELITE STAGE SDK / act

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!
}

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);
		}
	}
}

3.1 - 開発環境

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

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

Windows

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

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

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

Linux

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

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

• Ubuntu 18.04 LTS 64bit
• Ubuntu 20.04 LTS 64bit

macOS

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

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

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

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

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

ビルド環境による差異

3.2 - SDKのインストール

TWELITE STAGE SDK の導入

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

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

環境変数の設定

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\

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の部分はインストールしたフォルダに応じて書き換えてください

3.3 - アクトのビルド

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

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

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

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というチェックサムバイトになります。参考：アスキー形式)

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

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

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

必ずフォルダ直下にフォルダと同名の .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ポートに接続します。

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 アプリマニュアル)

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 にしてください。

VSCode のビルドタスク

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

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

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

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

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

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

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

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

Linux, macOS 環境

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

MWSDK_ROOT=/work/MWSDK
export MWSDK_ROOT

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

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がエラーとなりビルドが失敗します。

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

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

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

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

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

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

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

ビルド定義の編集

ビルド対象のファイルを追加する場合は 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 などの追加的なオプション等は設定されていない。

3.5 - actのためのVSCodeのインストール

act のソースコードの記述を容易に行うために、Visual Studio Code (VSCode) でコード解釈を行うための設定ファイルを同梱しています。

ソースコードの解析や VSCode からのビルドを行うために、ライブラリソースコードが格納されるフォルダの情報などの情報が必要になります。これらの情報は TWELITE STAGE アプリから 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

注記事項

3.6 - ビルド定義 Makefile

Makefileはbuild/Makefileに格納されています。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のように定義として渡されます。

ソースファイルの追加

ソースファイルを追加する際に必要なのはAPPSRC_CXXと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からの相対パスになります。

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

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

3.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については考慮しない前提で設計されている部分もあります。