このページでは、シリアル通信の設定項目、プラットフォームごとのポート名の違い、トラブル発生時の確認項目を説明します。
シリアル設定の一覧
Initializeで指定する設定項目の一覧です。設定値は対向デバイス（またはソフトウェア）の設定と一致させる必要があります。
| 設定 | 既定値 | 説明 |
|---|---|---|
| Port Name | COM1 | ポート名。OSごとの形式は後述の表を参照 |
| Baud Rate | 9600 | 1秒あたりの通信速度（ボー）。Arduinoのスケッチでは115200がよく使われる |
| Data Bits | 8 | 1文字あたりのデータビット数（5〜8） |
| Parity | None | パリティビット（None/Odd/Even/Mark/Space） |
| Stop Bits | 1 | ストップビット（1/1.5/2） |
| Flow Control | None | フロー制御（None/Hardware (RTS/CTS)/Software (XON/XOFF)） |
| Write Timeout | 1000 | 書き込みのタイムアウト（ミリ秒）。Set Write Timeoutで変更 |
| Receive Buffer Size | 8192 | 受信バッファサイズ（バイト、最小1024）。Set Receive Buffer Sizeで変更 |
| Initial DTR | true | ポートを開いた時点のDTR信号の状態 |
| Initial RTS | true | ポートを開いた時点のRTS信号の状態 |
ボーレートなどの設定が対向デバイスと一致していない場合、通信自体は成立しても受信データが文字化けします。対向デバイスの仕様を確認して設定してください。
受信モード
受信データの読み込みはバックグラウンドスレッドで行われます。Set Receive Modeで、スレッドのポーリング方法を変更できます。
| Receive Mode | 動作 | 用途 |
|---|---|---|
| Low | データがないときに10ミリ秒待機する | 低頻度の通信でCPU負荷を抑えたい場合 |
| Normal | 常に1ミリ秒待機する（既定） | 通常の用途 |
| High | スリープせずにYieldで待機する | 高頻度・大量の受信で遅延を最小化したい場合 |
受信イベント（Data Received系）はゲームスレッドで通知されるため、イベント内でUIの更新なども行えます。
データ形式と区切り文字
受信データの形式はInitializeのData Format（またはSet Data Format）で指定します。詳細はユースケースのデータ形式を切り替えるを参照してください。
| Data Format | 受信するデータ | 通知されるイベント |
|---|---|---|
RawBytes | バイト配列 | Data Received |
UTF8String | UTF-8文字列 | Data Received String |
HexString | 16進数文字列 | Data Received Hex |
UTF8Stringでは区切り文字（初期値\r\n）で文字列を復元します。区切り文字はSet String Delimiterで変更できます。対向デバイスが改行を送ってこないプロトコルの場合は、区切り文字の設定を対向デバイスの仕様に合わせてください。
プラットフォームごとのポート名
ポート名の形式はOSごとに異なります。
| プラットフォーム | ポート名の例 | 列挙の対象 |
|---|---|---|
| Windows | COM3、COM5 | 接続済みのCOMポート（SetupAPI） |
| Mac | cu.usbmodemXXXX、cu.usbserial-XXXX | コールアウトデバイス（cu.で始まる名前） |
| Linux | ttyUSB0、ttyACM0、by-idのパス名 | /dev/ttyUSB*、/dev/ttyACM*などのほか/dev/serial/by-id/も |
MacとLinuxでは、ポート名を/dev/を省略したデバイス名だけで指定できます（自動的に補完されます）。Linuxのby-idのパス名は、USB機器を差すポートが変わっても同じ名前になるため、ポート名が頻繁に変わる環境で便利です。
Get Available Serial Portsは開けないポートを除外して返します。Linuxでは、現在のユーザーにポートを開く権限がない場合、そのポートは一覧に表示されません。必要に応じて、OS側の設定（シリアルポートを使用するグループへのユーザー追加など）を確認してください。
ポートの排他
多くのOSでは、1つのシリアルポートを同時に開けるアプリケーションは1つです。UniversalSerialも例外ではありません。
- Windowsでは、Arduino IDEのシリアルモニターなど、ほかのアプリケーションがポートを開いている間は
Openに失敗し、Errorイベントが発生します。 - 通信の動作確認でArduino IDEのシリアルモニターを使ったあとは、Unreal Engineで
Openする前にモニターを閉じてください。
トラブルシューティング
| 症状 | 確認する項目 | 関連情報 |
|---|---|---|
| ポートが開けない | デバイスが接続されているか。ほかのアプリがポートを占有していないか。ポート名が正しいか | クイックスタートのエラー時の確認 |
Get Available Serial Portsが空になる | デバイスが認識されているか（OSのデバイスマネージャー等で確認）。Linuxではポートを開く権限があるか | このページの「プラットフォームごとのポート名」 |
| 受信データが文字化けする | ボーレート・データビット・パリティ・ストップビットが対向デバイスと一致しているか | このページの「シリアル設定の一覧」 |
| 文字列が受信できない | Data FormatがUTF8Stringか。対向デバイスが区切り文字（既定は\r\n）を送っているか | データ形式を切り替える |
| 受信した文字列が途中で切れる | 区切り文字の設定が対向デバイスと一致しているか。Set String Delimiterで確認 | このページの「データ形式と区切り文字」 |
| 接続直後の送信に応答がない | Arduinoなど、ポートを開いたときにリセットされるデバイスはないか。1〜2秒待ってから再送する | クイックスタート |
| 高頻度の受信で取りこぼしがある | Set Receive ModeをHighにする。Set Receive Buffer Sizeでバッファを大きくする | このページの「受信モード」 |
| 送信したのにデバイスが反応しない | 接続中に送信しているか（未接続の送信は警告ログのみ）。Send String UTF8のAdd Delimiterが対向仕様と合うか | Blueprint APIリファレンス |
| PIE終了後にポートが開いたままになる | EndPlayでCloseを呼んでいるか | クイックスタートの通信を終了する |
原因を切り分けるには、ErrorイベントのError Messageを出力する構成も有効です。プラグイン内部のログは、出力ログでLogUniversalSerialカテゴリを検索すると確認できます。
注意事項
- 対応プラットフォームはWindows、Mac、Linuxです。AndroidとiOSには対応していません。
- プラグインは各OSのAPIを直接使用しています。そのため、古いオペレーティングシステムでは予期しない動作が発生する可能性があります。お使いの環境で動作するかは、Testerアプリで事前に確認してください。
- 受信処理はバックグラウンドスレッドで行われますが、受信イベントはゲームスレッドで通知されます。
- 1つの
Serial Port Managerで扱えるポートは1つです。複数のポートを使用する場合は、ポートごとにマネージャーを作成してください。