rossubscriber

トピック上のメッセージをサブスクライブ

R2019b 以降

説明

rossubscriber を使用して、ROS ネットワーク上でメッセージを受信するための ROS サブスクライバーを作成します。メッセージを送信するには、rospublisher を使用します。新しい ROS メッセージを待機するには、関数 receive を、作成したサブスクライバーと共に使用します。

関数 rossubscriber によって作成された Subscriber オブジェクトは、ROS ネットワーク上のサブスクライバーを表します。Subscriber オブジェクトは、使用可能なトピックまたは自ら作成したトピックをサブスクライブします。このトピックにはメッセージ タイプが関連付けられています。パブリッシャーは、Subscriber オブジェクトが受信するメッセージをネットワーク経由で送信できます。

メモ

将来のリリースでは、ROS Toolbox は ROS メッセージ用のオブジェクトではなくメッセージ構造体を使用します。

現時点でメッセージ構造体を使用する場合、名前と値の引数 "DataFormat" を "struct" に設定します。詳細については、ROS メッセージ構造体を参照してください。

Subscriber オブジェクトは、関数 rossubscriber を使用するか、ros.Subscriber を呼び出すことによって作成できます。

• rossubscriber は、rosinit を使用するグローバル ノードでのみ機能します。引数としてノード オブジェクト ハンドルは必要ありません。

• ros.Subscriber は、ros.Node を使用して作成された追加のノードで機能します。最初の引数としてノード オブジェクト ハンドルが必要です。

作成

構文

sub = rossubscriber(topicname)

sub = rossubscriber(topicname,msgtype)

sub = rossubscriber(topicname,callback)

sub = rossubscriber(topicname, msgtype,callback)

sub = rossubscriber(___,Name,Value)

sub = rossubscriber(___,"DataFormat","struct")

sub = ros.Subscriber(node,topicname)

sub = ros.Subscriber(node,topicname,msgtype)

sub = ros.Subscriber(node,topicname,callback)

sub = ros.Subscriber(node,topicname,type,callback)

sub = ros.Subscriber(___,"BufferSize",value)

sub = ros.Subscriber(___,"DataFormat","struct")

説明

sub = rossubscriber(topicname) は、指定された TopicName をもつトピックをサブスクライブします。トピックは、確立されたメッセージ タイプと共に ROS マスターのトピック リスト上に既に存在しなければなりません。ROS ノードがそのトピック上にメッセージをパブリッシュすると、MATLAB^® はこのサブスクライバーを通してそれらのメッセージを受信します。

sub = rossubscriber(topicname,msgtype) は、指定された名前 TopicName とタイプ MessageType をもつトピックをサブスクライブします。ROS マスター上のトピックに、指定された名前とタイプのトピックが含まれていない場合、該当するトピックがトピック リストに追加されます。この構文を使用すると、パブリッシャーが ROS マスター上のトピック リストにトピックを追加する前にそのトピックをサブスクライブしたときのエラーを回避できます。

sub = rossubscriber(topicname,callback) は、サブスクライバー オブジェクト ハンドルがトピック メッセージを受信したときに実行されるコールバック関数 callback を指定します。この構文を使用して、ブロッキング受信関数を回避します。関数 callback は 1 つの関数ハンドルまたは cell 配列にすることができます。cell 配列の最初の要素は、関数ハンドル、または関数の名前を含む string でなければなりません。cell 配列の残りの要素には、コールバック関数に渡される任意のユーザー データを指定できます。

sub = rossubscriber(topicname, msgtype,callback) は、コールバック関数を指定して、指定された名前 TopicName とタイプ MessageType をもつトピックをサブスクライブします。

sub = rossubscriber(___,Name,Value) は、これまでの構文のいずれかの引数を使用して 1 つ以上の Name,Value ペア引数によって指定された追加オプションを提供します。Name はプロパティ名で、Value は対応する値です。

sub = rossubscriber(___,"DataFormat","struct") はオブジェクトではなくメッセージ構造体を使用します。詳細については、ROS メッセージ構造体を参照してください。

sub = ros.Subscriber(node,topicname) は、TopicName という名前のトピックをサブスクライブします。node は、このパブリッシャーの接続先の ros.Node オブジェクト ハンドルです。

sub = ros.Subscriber(node,topicname,msgtype) は、トピックのメッセージ タイプ MessageType を指定します。名前が同じでメッセージ タイプが異なるトピックが存在する場合、MATLAB は、指定されたメッセージ タイプで新しいトピックを作成します。

sub = ros.Subscriber(node,topicname,callback) は、サブスクライバー オブジェクトがトピック メッセージを受信したときに実行するコールバック関数とオプションのデータを指定します。コールバック関数の詳細については、NewMessageFcn を参照してください。

sub = ros.Subscriber(node,topicname,type,callback) は、サブスクライバーのトピック名、メッセージ タイプおよびコールバック関数を指定します。

sub = ros.Subscriber(___,"BufferSize",value) は、受信メッセージのキュー サイズを BufferSize で指定します。この構文では、これまでの入力を任意に組み合わせて使用できます。

sub = ros.Subscriber(___,"DataFormat","struct") はオブジェクトではなくメッセージ構造体を使用します。詳細については、ROS メッセージ構造体を参照してください。

プロパティ

TopicName — サブスクライブされるトピックの名前

string スカラー | 文字ベクトル

この プロパティ は読み取り専用です。

サブスクライブされるトピックの名前。string スカラーまたは文字ベクトルとして指定します。トピックが存在しない場合、オブジェクトは、関連付けられているメッセージ タイプを使用してトピックを作成します。

例: "/chatter"

データ型: char | string

MessageType — サブスクライブされるメッセージのメッセージ タイプ

string スカラー | 文字ベクトル

この プロパティ は読み取り専用です。

サブスクライブされるメッセージのメッセージ タイプ。string スカラーまたは文字ベクトルとして指定します。このメッセージ タイプとトピックとの関連付けは維持されます。

例: "std_msgs/String"

データ型: char | string

LatestMessage — トピックに最後に送信されたメッセージ

Message オブジェクト

トピックに最後に送信されたメッセージ。Message オブジェクトとして指定します。Message オブジェクトは、指定された MessageType に固有です。サブスクライバーがメッセージを受信していない場合、Message オブジェクトは空です。

BufferSize — バッファー サイズ

1 (既定値) | スカラー

受信メッセージ キューのバッファー サイズ。"BufferSize" とスカラーからなるコンマ区切りのペアとして指定します。コールバックの処理を上回る速度でメッセージが到着する場合、受信キューが一杯になるとメッセージが削除されます。

MATLAB では、既定の再帰限界値 500 が設定されています。したがって、500 よりも大きいバッファー サイズ値 N を指定する場合は、次のコードを使用して、MATLAB の再帰限界値を N に変更する必要があります。

set(0,'RecursionLimit',N)

使用可能なスタック領域を超過するような過度に大きい再帰限界値を指定しないようにしてください。

NewMessageFcn — コールバック プロパティ

関数ハンドル | cell 配列

コールバック プロパティ。関数ハンドルまたは cell 配列として指定します。cell 配列の最初の要素では、関数ハンドル、または関数名を表す string を指定します。それ以降の要素では、ユーザー データを指定します。

サブスクライバーのコールバック関数には、少なくとも 2 つの入力引数が必要です。最初の引数 src は、関連付けられているサブスクライバー オブジェクトです。2 番目の引数 msg は、受信したメッセージ オブジェクトです。コールバックの関数ヘッダーは次のとおりです。

function subCallback(src,msg)

NewMessageFcn プロパティを次のように指定します。

sub.NewMessageFcn = @subCallback;

コールバックを設定するときに、コールバック関数とパラメーターを cell 配列の要素として設定することで、追加パラメーターをコールバック関数に渡します。コールバックの関数ヘッダーは次のとおりです。

function subCallback(src,msg,userData)

NewMessageFcn プロパティを次のように指定します。

sub.NewMessageFcn = {@subCallback,userData};

DataFormat — メッセージ形式

"object" (既定値) | "struct"

メッセージ形式。"object" または "struct" として指定します。このプロパティは、作成時に名前と値の入力を使用して設定しなければなりません。詳細については、ROS メッセージ構造体を参照してください。

オブジェクト関数

receive	新しい ROS メッセージを待機
rosmessage	ROS メッセージの作成

例

サブスクライバーを作成して ROS からデータを取得

ROS ネットワークに接続します。サンプルの ROS ネットワークを設定します。'/scan' トピックはネットワーク上でパブリッシュされています。

rosinit

Launching ROS Core...
Done in 0.72523 seconds.
Initializing ROS master on http://172.30.241.81:51573.
Initializing global node /matlab_global_node_35713 with NodeURI http://dcc601040glnxa64:41253/ and MasterURI http://localhost:51573.

exampleHelperROSCreateSampleNetwork

メッセージ構造体を使用して、'/scan' トピックのサブスクライバーを作成します。サブスクライバーがマスターに登録するまで待機します。

sub = rossubscriber('/scan','DataFormat','struct');
pause(1);

サブスクライバーから ROS メッセージ構造体としてデータを受信します。10 秒のタイムアウトを指定します。

[msg2,status,statustext] = receive(sub,10)

msg2 = struct with fields:
       MessageType: 'sensor_msgs/LaserScan'
            Header: [1x1 struct]
          AngleMin: -0.5467
          AngleMax: 0.5467
    AngleIncrement: 0.0017
     TimeIncrement: 0
          ScanTime: 0.0330
          RangeMin: 0.4500
          RangeMax: 10
            Ranges: [640x1 single]
       Intensities: []

status = logical
   1

statustext = 
'success'

サンプル ネットワークで使用されているタイマーをシャットダウンします。

exampleHelperROSShutDownSampleNetwork

ROS ネットワークをシャットダウンします。

rosshutdown

Shutting down global node /matlab_global_node_35713 with NodeURI http://dcc601040glnxa64:41253/ and MasterURI http://localhost:51573.
Shutting down ROS master on http://172.30.241.81:51573.

コールバック関数を使用するサブスクライバーの作成

サブスクライバーがメッセージを受信したときにコールバック関数をトリガーできます。コールバックは、作成時、または NewMessageFcn プロパティを使用するときに指定します。

ROS ネットワークに接続します。

rosinit

Launching ROS Core...
.Done in 1.2769 seconds.
Initializing ROS master on http://172.30.241.81:50932.
Initializing global node /matlab_global_node_27540 with NodeURI http://dcc601040glnxa64:44877/ and MasterURI http://localhost:50932.

'/chatter' トピックにメッセージをパブリッシュするパブリッシャーを設定します。このトピックは、サブスクライバーのコールバックをトリガーするために使用されます。メッセージの Data プロパティを指定します。パブリッシャーがネットワークに登録できるように、1 秒間待機します。

pub = rospublisher('/chatter','std_msgs/String','DataFormat','struct');
msg = rosmessage(pub);
msg.Data = 'hello world';
pause(1)

指定したコールバック関数をもつサブスクライバーを設定します。関数 exampleHelperROSChatterCallback は、受信メッセージ内に Data を表示します。

sub = rossubscriber('/chatter',@exampleHelperROSChatterCallback,'DataFormat','struct');
pause(1)

パブリッシャー経由でメッセージを送信します。サブスクライバーは、コールバックを実行して新しいメッセージを表示する必要があります。メッセージが受信されるまで待機します。

send(pub,msg);
pause(1)

ans = 
'hello world'

ROS ネットワークをシャットダウンします。

rosshutdown

Shutting down global node /matlab_global_node_27540 with NodeURI http://dcc601040glnxa64:44877/ and MasterURI http://localhost:50932.
Shutting down ROS master on http://172.30.241.81:50932.

ROS Subscriber オブジェクトの使用

ROS Subscriber オブジェクトを使用して、ROS ネットワーク経由でメッセージを受信します。

ROS コアおよびノードを起動します。

master = ros.Core;

Launching ROS Core...
Done in 0.82033 seconds.

node = ros.Node('/test');

ROS ネットワーク経由でメッセージを送受信するパブリッシャーとサブスクライバーを作成します。ROS メッセージを構造体として使用します。

pub = ros.Publisher(node,'/chatter','std_msgs/String','DataFormat','struct');
sub = ros.Subscriber(node,'/chatter','std_msgs/String','DataFormat','struct');

ネットワーク経由でメッセージを送信します。

msg = rosmessage(pub);
msg.Data = 'hello world';
send(pub,msg)

Subscriber オブジェクトの LatestMessage プロパティを使用してメッセージ データを表示します。

pause(1)
sub.LatestMessage

ans = struct with fields:
    MessageType: 'std_msgs/String'
           Data: 'hello world'

パブリッシャー、サブスクライバー、および ROS ノードをクリアします。ROS マスターをシャットダウンします。

clear('pub','sub','node')
clear('master')

拡張機能

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用に関するメモと制限:

• struct メッセージでのみサポートされます。

• MessageType 引数を指定しなければなりません。

• コールバック関数は、Subscriber オブジェクトの作成時に割り当てなければなりません。また、実行時に変更することはできません。

• メッセージを受信しなかった場合、LatestMessage プロパティは、メッセージ タイプに基づいた既定値を含むメッセージを返します。

バージョン履歴

R2019b で導入

R2021a: ROS メッセージ構造体

これで、メッセージ オブジェクトのプロパティと一致するフィールドをもつ構造体としてメッセージを作成できます。通常、構造体を利用すると ROS メッセージの作成、更新、使用のパフォーマンスが向上しますが、設定時にメッセージのフィールドが検証されなくなります。メッセージ タイプと、構造体から取得した対応するフィールド値は、ネットワーク経由で送信されたときに検証されます。

ROS メッセージを構造体として使用するには、パブリッシャー、サブスクライバー、またはその他の ROS オブジェクトの作成時に名前と値の引数 "DataFormat" を使用します。これらのオブジェクトから生成されたすべてのメッセージで構造体が利用されます。

pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")
msg = rosmessage(pub)

また、メッセージを直接構造体として作成することもできますが、パブリッシャー、サブスクライバー、またはその他の ROS オブジェクトについても必ずデータ形式を "struct" として指定してください。現時点では、ROS オブジェクトは既定でメッセージ オブジェクトを使用します。

msg = rosmessage("/scan","sensor_msgs/LaserScan","DataFormat","struct")
...
pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")

将来のリリースでは、ROS メッセージは既定で構造体を使用し、ROS メッセージ オブジェクトは削除されます。

詳細については、Improve Performance of ROS Using Message Structuresを参照してください。

参考

receive | rospublisher | rosmessage

トピック

• ROS のパブリッシャーおよびサブスクライバーとのデータ交換