UniversalSerial

Unreal Engineでシリアル通信を行うためのマルチプラットフォーム対応プラグイン

Fab

概要

UniversalSerialは、Unreal EngineでArduinoやマイコンとシリアル通信を行うためのプラグインです。難しいプログラミング知識がなくても、ブループリント（ビジュアルスクリプティング）だけで簡単にハードウェアとの通信が可能になります。

IoTプロジェクトやインタラクティブアート、ゲーム内でのリアルワールド連携など、デジタルとフィジカルを繋ぐプロジェクトに最適です。

またAyumaxSoftが公開しているObjectDelivererのプロトコルとして使用するスペシャル機能も搭載しています。

こちらを利用すると、ObjectDelivererが持つパケット分割ルールとDeliveryBoxの仕組みが利用でき用途が広がります。

対応環境

  • Windows : Windows11 24H2で確認
  • Mac : Sequoia 15.5で確認
  • Linux : Ubuntu 24.04 LTSで確認

プラグインの中で各OSのAPIを直接使用して機能を実現しています。そのため古いOSでは予期しない動作をすることがあります。

事前にテスターアプリでご自身の環境で動作するかを確認することをおすすめします。

主な機能

  • 利用可能なポートの自動検出機能
    • 検出したポート名をそのまま初期化に渡せます
  • 対象ポートの設定をカスタマイズして初期化
    • ポート名
    • ボーレート
    • データビット
    • パリティ
    • ストップビット
    • フローコントロール
    • 読み書きタイムアウト
    • 受信バッファサイズ
  • ３種類のデータ送受信方法
    • バイト配列
    • UTF-8エンコードの文字列
    • 16進数表記のUTF-8エンコード文字列をバイト配列として送信
  • 文字列送受信時のデリミタ設定
    • 送信時に自動でデリミタを付加
    • 受信時にはデリミタでデータを区切って文字列を復元する
  • バックグラウンドスレッドでの受信処理
    • ゲームスレッドに重い負荷をかけません

使用例

以下は、UniversalSerialを使用する手順です。

SerialPortManagerの作成

まずはSerialPortManagerを生成します。今後はこの生成したオブジェクトを使って操作をします。

USerialPortManager* SerialPort = NewObject<USerialPortManager>();

SerialPortManagerのイベントを監視する

SerialPortManagerの必要なイベントを監視します。不要なものはスキップして構いません。イベントは以下の種類が用意してあります。

  • 接続、切断
  • データ受信
    • バイト配列
    • UTF-8文字列
    • 16進数表記のUTF-8文字列
  • エラー発生
SerialPort->OnConnected.AddDynamic(TestHelper, &USerialPortTestHelper::OnConnected);
SerialPort->OnDisconnected.AddDynamic(TestHelper, &USerialPortTestHelper::OnDisconnected);
SerialPort->OnDataReceived.AddDynamic(TestHelper, &USerialPortTestHelper::OnDataReceived);
SerialPort->OnDataReceivedString.AddDynamic(TestHelper, &USerialPortTestHelper::OnDataReceivedString);
SerialPort->OnDataReceivedHex.AddDynamic(TestHelper, &USerialPortTestHelper::OnDataReceivedHex);
SerialPort->OnError.AddDynamic(TestHelper, &USerialPortTestHelper::OnError);

シリアル通信の開始

シリアルポートの情報をセットしてからOpenを呼んで通信を開始します。

Initializeに渡す設定は接続する機器やソフトウェアと同じ設定にする必要があります。

また事前にSerialPortManagerのGetAvailableSerialPortsを使って、現在利用可能シリアルポート名の一覧を取得することも可能です。

SerialPort->Initialize("COM1", 9600, 8, ESerialPortParity::None, ESerialPortStopBits::One, ESerialPortFlowControl::None, ESerialDataFormat::RawBytes);

データの送信

データの送信は3通りの方法があります。

バイト配列を送信

指定したバイト配列を送信します。

TArray<uint8> Data = { 0x00, 0x00, 0x00 };
SerialPort->SendData(Data);

UTF-8文字列を送信

指定した文字列を送信します。AddDelimiterをtrueにすると文字列の最後にデリミタ文字列(初期値:\r\n)を自動で付加します。

FString Data = TEXT("ABC");
SerialPort->SendStringUTF8(Data, true);

16進数表記のUTF-8エンコード文字列をバイト配列として送信

指定した16進数文字列をバイト配列に変換してからバイト配列として送信します。

// 文字列形式でバイト配列を作成（間のスペースはあってもなくても可）
FString Data = TEXT("AA BB CC 01 02 03");
SerialPort->SendStringHex(Data);

データの受信

以下の3つのイベントの中で受信した値を取得できます。

これらのイベントはInitialize時のData Format、もしくはSetDataFormatで指定したタイプの受信イベントのみが通知されます。

そのため、これらの3つのイベントは常にどれか1つのみが有効になります。残りの2つは設定をしても通知されません。

通信相手の機器がバイナリデータ(人間が目で見ても意味が分からないデータ)を送ってくる場合は、RawBytesを指定してOnDataReceivedを使うのをおすすめします。もしくはHexStringを指定してOnDataReceivedHexを使用すると文字列形式でバイトデータが取得できるので画面やログファイルに受信データを表示したい場合はこれの利用が便利です。

通信相手の機器が文字列を送ってくる場合は、UTF-8Stringを指定して、OnDataReceivedStringイベントを使ってください。

SerialPort->OnDataReceived.AddDynamic(TestHelper, &USerialPortTestHelper::OnDataReceived);
SerialPort->OnDataReceivedString.AddDynamic(TestHelper, &USerialPortTestHelper::OnDataReceivedString);
SerialPort->OnDataReceivedHex.AddDynamic(TestHelper, &USerialPortTestHelper::OnDataReceivedHex);

通信の終了

Closeを呼んで通信を終了します。

SerialPort->Close();

ObjectDelivererとの連携

こちらのページより、UniversalSerialODプラグインをダウンロードしてご利用ください。

こちらは現在は無料で公開中です。Fabでは他のプラグインと連携するプラグインは規約違反で公開できないのでこのサイト限定でダウンロード可能です。

このプラグインを利用するとObjectDelivererのプロトコルとしてUniversalSerialが使用できるようになります。

この連携機能の利用には以下の3つのプラグインがインストールされている必要があります。

  • ObjectDeliverer
  • UniversalSerial
  • UniversalSerialOD

この連携機能はあなたのプロジェクトに以下のメリットを与えます。

  • Serial通信において、ObjectDelivererが持つパケット分割ルールとDeliveryBoxの仕組みが利用できます
  • 機器との通信機能を作成する場合に、機器がないばあいはTCP/IPなどでモックをつくって通信を切り替えて開発を進められます

使用するにはObjectDelivererManagerのStartメソッドに、”Create Protocol Serial Port”を差し込むだけです。

あとはObjectDelivererの機能を使ってシリアル通信の送受信が実行できます。

UniversalSerialODプラグインのContentフォルダの中のUniversalODSerialUMGアセットに、このプラグインの実装例が含まれているので参考にしてください。

プラグイン購入前の事前確認

UniversalSerialはOSのAPIを直接使用しています。そのためお使いの環境によっては正常に動作しない可能性があります。

こちらのページからテスターアプリをダウンロードできますので、こちらを使用して購入前にシリアル通信が可能かどうか確認をすることをお勧めします。

このテスターアプリはUniversalSerialプラグインを使ってシリアル通信をします。そのためこのアプリで通信できた場合はプラグインを使って通信ができる可能性が高いです。

またこのアプリの実装をしているブループリントはプラグインの中に入っていますので購入後にプラグインの使い方をみるのにも役立ちます。

FAQ

こちらでよくある質問を確認することができます