gRPC API を使用したプログラムによる RoadRunner の制御

RoadRunner には、RoadRunner UI をプログラムにより制御できる API が用意されています。たとえば、この API を使用すると次のことを実行できます。

RoadRunner のシーン、シナリオ、プロジェクトを作成、読み込み、保存する。
ASAM OpenDRIVE^® ファイルをシーンにインポートする。
RoadRunner でサポートされるファイル形式のいずれかに、シーンやシナリオをエクスポートする。

RoadRunner を使用すると、さまざまなプログラミング言語で API のバージョンをコンパイルし、選択した言語でそれらの API を呼び出すことができます。または、API のプリコンパイルされたバージョンを使用することもできます。これにより、コマンドラインから RoadRunner を制御できます。

RoadRunner API の仕組み

RoadRunner API は、オープンソースの gRPC^® フレームワークを使用して構築されています。このフレームワークでは、クライアントアプリケーションが一連のリモートプロシージャコール (RPC) メソッドを使用してサーバーアプリケーションをリモート制御する、クライアント/サーバーアーキテクチャを採用しています。RoadRunner での仕組みは次のとおりです。

ローカルにインストールされた RoadRunner のバージョンがサーバーアプリケーションです。
RoadRunner API は RoadRunner をリモート制御するために使用される RPC メソッドを提供します。
RPC メソッドを呼び出すために作成したプログラムがクライアントアプリケーションです。gRPC フレームワークは言語にもプラットフォームにも依存しません。RoadRunner API を呼び出すクライアントは、gRPC がサポートする任意のプラットフォームおよび言語で作成できます。gRPC がサポートする言語とプラットフォームの詳細については、gRPC のドキュメンテーションを参照してください。

次の図は、この API アーキテクチャの簡略化されたレイアウトを示しています。この図で、Python^® クライアントは、LoadScene メソッドを使用して RoadRunner のシーンを読み込んでいます。

A Python client, myClient.py, calls the LoadScene RPC method to load a scene on the RoadRunner server.

RoadRunner API によるデータの送受信方法

RoadRunner API の RPC メソッドは、gRPC "サービス" で定義されています。gRPC サービスの一部であるメソッドを呼び出すたびに、そのメソッドは次を行います。

リクエストをサーバーに送信する。
サーバーから返されるレスポンスを受信する。

次の図は、LoadScene メソッドの呼び出しにおける、このリクエスト/レスポンスの形式を示しています。クライアントにおいて、メソッドへの入力 LoadSceneRequest は、クライアントが RoadRunner アプリケーションサーバーに送信するリクエストです。RoadRunner はこのリクエストを処理し、シーンを読み込み、レスポンス LoadSceneResponse を送信します。

The RoadRunner request-response relationship

これらのリクエストとレスポンスのデータは、"プロトコルバッファー" (protobuf) スキーマを使用して定義されたメッセージとして構造化されます。protobuf スキーマは、Google^® によって開発された言語に依存しない形式であり、高速かつ効率的なデータ転送のために最適化されています。RoadRunner サーバーは、RoadRunner のリアルタイム更新を維持しながら、これらの API 呼び出しからの数百万もの protobuf メッセージを同時に送受信できます。

protobuf スキーマのメッセージは、.proto 拡張子を持つテキストファイルで定義されます。これらのメッセージには、以下を定義する名前と値のフィールドが含まれています。

メッセージ内で指定できるフィールドの名前。
フィールドのデータ型。たとえば、ブール値、string、またはその他の protobuf メッセージとしてフィールドを指定できます。

roadrunner_service.proto ファイルに定義されている LoadScene RPC メソッドのスキーマについて考えてみましょう。

// Load scene 
rpc LoadScene (LoadSceneRequest) returns (LoadSceneResponse) {}

リクエストメッセージ LoadSceneRequest およびレスポンスメッセージ LoadSceneResponse のスキーマは、roadrunner_service_messages.proto ファイルに定義されています。LoadSceneRequest は 1 つの必須入力 file_path を受け取ります。これは、読み込むファイルのパスを指定する string です。

message LoadSceneRequest
{
  // Scene file to load (required)
  string file_path = 1;
}

RoadRunner がリクエストを処理 (シーンの読み込みを試行) した後に、RoadRunner API サーバーがレスポンスで空の LoadSceneResponse メッセージを送信します。

message LoadSceneResponse
{
}

protobuf スキーマは言語に依存しないため、メソッドの呼び出しやメッセージリクエストの書式設定に使用される構文は、クライアントアプリケーションの作成に使用したプログラミング言語によって異なります。

RoadRunner API サーバーへの接続

RoadRunner API を使用するには、まず RoadRunner API サーバーとのネットワーク接続を確立する必要があります。このサーバーは、ローカルの RoadRunner インストールの一部であり、プロジェクトを開くと起動を開始します。

プログラムにより RoadRunner を開き、API サーバーを起動するには、ローカルの RoadRunner インストールから AppRoadRunner 実行可能ファイルを呼び出します。この実行可能ファイルには、以下を指定できるコマンドラインオプションが含まれています。

RoadRunner で開くプロジェクト
RoadRunner API サーバーが実行される IP ネットワークポート

次のコマンドラインコードは、Windows^® 上の既定のインストール場所から RoadRunner を開く方法を示しています。RoadRunner は、IP ネットワークポート 54321 上で C:\RR\MyProject にあるプロジェクトを表示して開きます。

cd "C:\Program Files\RoadRunner R2026a\bin\win64"
AppRoadRunner --projectPath C:\RR\MyProject --apiPort 54321

RoadRunner の [Output] ペインに、RoadRunner API サーバーが実行されているポートが表示されます。

Output pane with RoadRunner API server message

コマンドラインからの RoadRunner API の使用

RoadRunner には、コマンドラインから RoadRunner RPC メソッドを呼び出すことができる、プリコンパイルされたヘルパーコマンド CmdRoadRunnerApi が用意されています。このヘルパーコマンドは、AppRoadRunner 実行可能ファイルと同じフォルダーにあります。

次のコードは、開いているプロジェクトからプリビルド FourWaySignal シーンを読み込むために LoadScene メソッドを呼び出します。

CmdRoadRunnerApi "LoadScene(file_path='FourWaySignal')" --serverAddress=localhost:54321

RoadRunner scene containing a four-way intersection with traffic signals

さまざまなプログラミング言語での RoadRunner API の使用

RoadRunner API 使用時の柔軟性を高めるために、gRPC によってサポートされる言語に API をコンパイルしてから、その言語でクライアントアプリケーションを作成することで、RoadRunner をプログラムにより制御できます。

RoadRunner API のコンパイル

希望するプログラミング言語に RoadRunner API をコンパイルするには、まず API を定義する protobuf ファイルを書き込み可能なフォルダーにコピーする必要があります。これらのファイルは、ローカルの RoadRunner インストールにあります。次に、希望するプログラミング言語用の gRPC プラグインと共に protobuf コンパイラを使用して、RoadRunner API の言語固有のバージョン、つまり "バインディング" をコンパイルします。たとえば、次の図は Python および C++ のバインディングの生成を示しています。

Protobuf files compiled into Python and C++ bindings using the protobuf compiler and gRPC plugins.

protobuf ファイルのコンパイルの詳細については、Compile Protocol Buffers for RoadRunner gRPC APIを参照してください。

RoadRunner API クライアントの作成

RoadRunner をプログラムにより制御するために作成するクライアントには通常、次の手順を実行するコードが含まれます。

コンパイル済みのバインディングから gRPC コードをインポートする。
RoadRunner API サーバーへのローカルネットワーク接続を確立する。
インポートした gRPC コードを使用して RoadRunner API オブジェクトを作成する。このオブジェクトは、"スタブ" と呼ばれます。
このスタブから RPC メソッドを呼び出し、ローカルネットワーク経由で RoadRunner を制御する。

次の単純な Python クライアントは、LoadScene メソッドを呼び出す例を示します。

import grpc
from mathworks.roadrunner import roadrunner_service_messages_pb2
from mathworks.roadrunner import roadrunner_service_pb2_grpc

with grpc.insecure_channel("localhost:54321") as channel:
    api = roadrunner_service_pb2_grpc.RoadRunnerServiceStub(channel)
    loadSceneRequest = roadrunner_service_messages_pb2.LoadSceneRequest()
    loadSceneRequest.file_path = "FourWaySignal"
    api.LoadScene(loadSceneRequest)

コンパイルした gRPC Python バインディングをインポートした後、クライアントは gRPC チャネルを介して接続を確立し、RoadRunner サービス API のスタブを作成します。API の gRPC チャネルでは、安全でないチャネル資格情報が使用され、暗号化や認証は行われません。RoadRunner は通常、ローカルマシンで実行され、外部ネットワークに接続されないため、セキュリティリスクは低いです。次に、クライアントは API スタブから LoadScene を呼び出し、これにより現在開いているプロジェクトからプリビルド FourWaySignal シーンが読み込まれます。

クライアントが同じネットワークポート上にある RoadRunner に接続されている限り、RPC メソッドを同時に呼び出す複数のクライアントを使用できます。たとえば、次の図では、Python クライアントと C++ クライアントがネットワークポート 54321 を介して LoadScene を呼び出しています。

A Python client, myClient.py, and C++ client, myClient.cc, calling LoadScene over port 54321.

参考

AppRoadRunner