UniversalSerial Blueprint APIリファレンス

このページでは、UniversalSerialがBlueprintに公開するAPIを説明します。C++でも同じAPIを利用できます。各APIの使い分けはユースケースを参照してください。

API全体の関係

UniversalSerialの公開APIは、Serial Port Managerクラス（USerialPortManager）に集約されています。

    flowchart TB
	  BP["Blueprint / C++"] --> M["SerialPortManager"]
	  M -->|"Initialize → Open"| OS["OSのシリアルAPI"]
	  M -->|"Send Data / Send String UTF8 / Send String Hex"| OS
	  OS -->|"受信スレッド"| M
	  M -->|"Connected / Data Received など（ゲームスレッド）"| BP

受信データの読み込みはバックグラウンドスレッドで行われ、受信イベントはゲームスレッドで通知されます。

SerialPortManagerの作成

Serial Port ManagerはBlueprintTypeのクラスです。Construct Object from ClassノードのClassにSerial Port Managerを指定して作成します。

作成したインスタンスはメンバー変数に保存してください。未保存の場合、ガベージコレクションの対象になり、通信が継続できません。

Initialize

ポート名と通信設定を指定します。Initializeは設定を保存するだけです。実際にポートを開くには、続けてOpenを実行します。

設定は対向デバイスまたはソフトウェアの設定と一致している必要があります。

Open

Initializeで保存した設定でポートを開き、受信スレッドを起動します。成功するとConnectedイベントが、失敗するとErrorイベントが発生します。

すでに接続中の場合は何も行わず、ログに警告が出力されます。

Close

ポートを閉じ、受信スレッドを停止します。Disconnectedイベントが発生します。レベルの終了時（EndPlay）に呼び出してください。

IsConnected

ポートが開いているかどうかを返します（true: 接続中、false: 切断）。

送信系ノード

未接続の状態で送信した場合や空のデータを送信した場合は、送信は行われずログに警告が出力されます。

Set DTR / Set RTS

DTR・RTS信号の状態を切り替えます。成功するとtrueが返ります。接続していない状態ではfalseが返ります。

Set Receive Mode / Get Receive Mode

受信スレッドのポーリング方法を指定します。

Highは受信の遅延を最小化しますが、CPUの使用率が上がります。通常は既定値のNormalを使用してください。Get Receive Modeで現在の設定を取得できます。

Set系ノード（オプション設定）

次のノードは戻り値としてマネージャー自身を返すため、Initializeの前などに続けて呼び出せます。

Get Available Serial Ports

現在利用可能なシリアルポート名の一覧を返します（BlueprintPure、static）。取得したポート名はInitializeのPort Nameにそのまま渡せます。

Find First Communicable Serial Port（およびBinary版）

候補ポートを順に開き、最初に通信可能なポート名を返します。通信できない場合は空の文字列を返します。詳細な使い方はユースケースの通信可能なポートを自動で特定するを参照してください。

Find First Communicable Serial Port (Binary)は、プローブと応答確認をバイト列（Probe Data・Expected Response）で行う版です。どちらのノードも、プローブ文字列を両方空にすると「最初に開けたポート」を返します。

イベント

受信イベント（Data Received・Data Received String・Data Received Hex）は、Data Formatで指定した形式に対応する1種類だけが通知されます。ほかの2つはバインドしていても通知されません。

列挙型

C++での実装例

Arduinoと文字列で送受信する例です。Blueprintの構成と同じ要素を使用します。

void UMyActor::BeginPlay()
{
    Super::BeginPlay();

    // SerialPortManagerを作成し、変数に保持する
    SerialPort = NewObject<USerialPortManager>();

    // イベントハンドラーを設定する
    SerialPort->OnConnected.AddDynamic(this, &UMyActor::OnConnected);
    SerialPort->OnDisconnected.AddDynamic(this, &UMyActor::OnDisconnected);
    SerialPort->OnDataReceivedString.AddDynamic(this, &UMyActor::OnDataReceivedString);
    SerialPort->OnError.AddDynamic(this, &UMyActor::OnError);

    // 通信設定を指定する（対向デバイスと一致させる）
    SerialPort->Initialize(
        TEXT("COM3"),
        115200,
        8,
        ESerialPortParity::None,
        ESerialPortStopBits::One,
        ESerialPortFlowControl::None,
        ESerialDataFormat::UTF8String,
        true,
        true);

    // ポートを開く
    SerialPort->Open();
}

void UMyActor::OnConnected(USerialPortManager* SerialPort)
{
    // 文字列を送信する（区切り文字を自動で追加）
    SerialPort->SendStringUTF8(TEXT("Hello"), true);
}

void UMyActor::OnDataReceivedString(USerialPortManager* SerialPort, const FString& Data)
{
    UE_LOG(LogTemp, Log, TEXT("Received: %s"), *Data);
}

void UMyActor::OnError(USerialPortManager* SerialPort, const FString& ErrorMessage)
{
    UE_LOG(LogTemp, Error, TEXT("Serial error: %s"), *ErrorMessage);
}

void UMyActor::EndPlay(const EEndPlayReason::Type EndPlayReason)
{
    if (SerialPort)
    {
        SerialPort->Close();
    }
    Super::EndPlay(EndPlayReason);
}

通信可能なポートを自動で特定する場合は、Openの前にUSerialPortManager::FindFirstCommunicableSerialPortの戻り値をInitializeのポート名に渡します。

const FString PortName = USerialPortManager::FindFirstCommunicableSerialPort(
    115200, 8,
    ESerialPortParity::None, ESerialPortStopBits::One, ESerialPortFlowControl::None,
    50, 500, 4096, true, true,
    TEXT("PING\r\n"), TEXT("PONG"), 2000);

if (!PortName.IsEmpty())
{
    SerialPort->Initialize(PortName, 115200, 8,
        ESerialPortParity::None, ESerialPortStopBits::One, ESerialPortFlowControl::None,
        ESerialDataFormat::UTF8String, true, true);
    SerialPort->Open();
}

非推奨のノード

エディタ上では打ち消し線付きで表示されます。既存のBlueprintに含まれている場合でも動作しますが、新規に使用しないでください。

ライフサイクルと保持のまとめ

1. Construct Object from Classで作成したSerial Port Managerはメンバー変数で保持します。
2. Initializeで設定を保存し、Openでポートを開きます。Openの成功・失敗はConnected・Errorイベントで確認します。
3. 送信は接続中のみ有効です。未接続での送信は警告ログのみで、エラーイベントは発生しません。
4. 受信イベントはData Formatに対応する1種類だけが通知され、ゲームスレッドで実行されます。
5. 不要になったらCloseを呼び出します。呼び出さないままオブジェクトが破棄されると、ポートが開いたままになることがあります。