UniversalSerial ユースケース

このページでは、目的に合わせたデータ形式・ポート選択の方法と、代表的なユースケースを説明します。ノードごとの入出力の詳細はBlueprint APIリファレンスを参照してください。

目的別の選択表

目的	使用する機能
Arduinoやマイコンと文字列でやり取りしたい	`Data Format = UTF8String` ＋ `Send String UTF8`
バイナリデータを扱いたい	`Data Format = RawBytes` ＋ `Send Data`
受信したバイト列を画面やログに表示したい	`Data Format = HexString` ＋ `Data Received Hex`
接続先のポート名が環境ごとに変わる	`Get Available Serial Ports` またはポートの自動特定
どのポートが対象デバイスか不明	`Find First Communicable Serial Port`
複数のデバイスと同時に通信したい	`Serial Port Manager`をポートごとに作成
対向デバイスの起動待ちやリセット制御をしたい	`Set DTR` / `Set RTS`
ObjectDelivererのパケット分割やDeliveryBoxを使いたい	UniversalSerialOD（現在提供停止中）

共通のライフサイクルはすべてのユースケースで同じです。Serial Port Managerを作成して変数に保持し、Initializeで設定を渡し、Openで開始、各イベントで結果を受け取り、不要になったらCloseを呼び出します。

データ形式を切り替える

InitializeのData Format（またはSet Data Format）で、受信データの形式を選択します。受信イベントは、指定した形式に対応する1種類だけが通知されます。

Data Format	受信するデータ	通知されるイベント	用途
`RawBytes`	バイト配列	`Data Received`	対向デバイスがバイナリデータを送信する場合
`UTF8String`	UTF-8文字列	`Data Received String`	対向デバイスが文字列を送信する場合
`HexString`	16進数文字列	`Data Received Hex`	受信データを画面やログファイルに表示したい場合

対向デバイスがバイナリデータ（人間の目には意味のないデータ）を送信する場合は、RawBytesを指定してData Receivedを使用してください。バイト列を文字列形式で取得したい場合は、HexStringを指定してData Received Hexを使用すると、受信データを16進数の文字列で確認できます。

文字列の区切り文字

UTF8Stringでは、区切り文字（初期値は\r\n）でデータを分離して文字列を復元します。1回の受信データに複数の区切り文字が含まれる場合は、区切りごとにData Received Stringが発生します。区切り文字に達しないデータは内部でバッファリングされ、続きの受信時に結合されます。マルチバイト文字が読み込みの境界で分断された場合も、正しく結合されてから通知されます。

区切り文字を変更する場合はSet String Delimiterを使用します。対向デバイスの仕様に合わせて設定してください。

送信方法を使い分ける

送信には3つのノードがあります。

ノード	送信するデータ	説明
`Send Data`	バイト配列	指定されたバイト配列をそのまま送信する
`Send String UTF8`	UTF-8文字列	文字列をUTF-8エンコードで送信する。`Add Delimiter`が`true`なら区切り文字を末尾に追加
`Send String Hex`	16進数文字列	`AA BB CC 01 02 03`のような16進数文字列をバイト配列に変換して送信する。バイト間のスペースは任意

Send String UTF8のAdd Delimiterをtrueにすると、送信する文字列の末尾に区切り文字（初期値は\r\n）が自動的に追加されます。対向デバイスが改行を待つ行指向のプロトコルの場合はtrueのままにします。

通信可能なポートを自動で特定する

PCに複数のシリアルデバイスが接続されていると、目的のデバイスがどのポートか分からないことがあります。v1.3.0以降では、Find First Communicable Serial Portで候補ポートを順に試し、最初に通信可能なポート名を取得できます。

プローブには2つの方法があります。

ノード	プローブ方法
`Find First Communicable Serial Port`	`Probe Command UTF8`で指定した文字列を送り、応答に`Expected Response UTF8`が含まれるか確認
`Find First Communicable Serial Port (Binary)`	`Probe Data`のバイト列を送り、応答に`Expected Response`のバイト列が含まれるか確認

Probe Command UTF8とExpected Response UTF8の両方を空にした場合は、単純に最初に開けたポートを返します。

たとえば対向デバイスがPINGに対してPONGで応答するプロトコルの場合、Probe Command UTF8にPING、Expected Response UTF8にPONGを指定します。応答が確認できたポート名が戻り値として返るため、その値をInitializeのPort Nameに渡します。

Note

候補ポートは、COMやusbmodem、usbserial、ttyACM、ttyUSB、cu.usbのようにUSB接続のシリアルデバイスらしい名前が優先して試行されます。通信に失敗したポートは自動的に閉じられます。

利用可能なポートを一覧する

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

ポート名の形式はOSごとに異なります。

プラットフォーム	ポート名の例
Windows	`COM3`、`COM5`
Mac	`cu.usbmodemXXXX`、`cu.usbserial-XXXX`
Linux	`ttyUSB0`、`ttyACM0`、`by-id`のパス名

MacとLinuxでは、/dev/を省略したデバイス名を指定すると自動的に補完されます。詳細はデータ形式と運用のプラットフォームごとのポート名を参照してください。

複数のポートを同時に使う

Serial Port Managerは1つのインスタンスで1つのポートを扱います。複数のデバイスと同時に通信する場合は、ポートごとにSerial Port Managerを作成し、それぞれ変数に保存してInitializeとOpenを実行してください。

各マネージャーのイベントは独立して通知されます。Connected・Data Received系のイベントの引数Serial Portで、どのマネージャーからの通知かを判別できます。

DTR/RTSを制御する

DTR（Data Terminal Ready）とRTS（Request To Send）は、シリアルポートの制御線です。Arduinoの一部ボードはDTRの切り替えでリセットがかかるため、デバイスの種類によっては制御線の状態が動作に影響します。

InitializeのInitial DTRとInitial RTSでポートを開いた時点の状態を指定します。初期値はどちらもtrueです。通信中の切り替えにはSet DTRとSet RTSを使用します。接続していない状態で実行するとfalseが返ります。

フロー制御にHardware (RTS/CTS)を指定した場合、RTS/CTSはフロー制御に使用されます。

ObjectDelivererと連携する

AyumaxSoftが提供するObjectDelivererのプロトコルとして、UniversalSerialを使用できます。連携には専用プラグインUniversalSerialODを使用し、ObjectDelivererのパケット分割ルールやDeliveryBoxの仕組みをシリアル通信で利用できます。

Warning

UniversalSerialODには現在問題が見つかっており、提供を一時中止しております。修正が完了し次第、提供を再開する予定です。

UniversalSerialODは無料で提供されています。他のプラグインと連携するプラグインはFabの規約に違反するため、当サイトのダウンロードページでのみ配布しています。

連携機能を使用するには、次の3つのプラグインをインストールします。

ObjectDeliverer
UniversalSerial
UniversalSerialOD

この連携により、プロジェクトに次の利点があります。

シリアル通信で、ObjectDelivererのパケット分割ルールやDeliveryBoxの仕組みを使用できる
デバイスとの通信機能を作成する際、デバイスがない場合はTCP/IPや他のプロトコルでモックを作成し、通信方法を切り替えて開発を進められる

使用するには、ObjectDelivererManagerのStartに「Create Protocol Serial Port」を挿入するだけです。その後はObjectDelivererの機能を使用してシリアル通信の送受信を行えます。

実装例はUniversalSerialODプラグインのContentフォルダにあるUniversalODSerialUMGアセットを参照してください。