使用 gRPC API 以编程方式控制 RoadRunner

RoadRunner API 的工作原理

RoadRunner API 是使用开源 gRPC^® 框架构建的。该框架使用客户端-服务器架构，其中客户端应用程序使用一组远程过程调用(RPC)"）方法远程控制服务器应用程序。在 RoadRunner 中：

该图显示了 API 架构的简化布局。在此图中，Python^® 客户端使用 LoadScene 方法加载 RoadRunner 中的场景。

RoadRunner API 如何发送和接收数据

RoadRunner API 的 RPC 方法在 gRPC 服务中定义。每次调用属于 gRPC 服务一部分的方法时，该方法：

此图显示了调用 LoadScene 方法的请求-响应格式。在客户端中，方法 LoadSceneRequest 的输入是客户端向 RoadRunner 应用服务器发送的请求。RoadRunner 处理该请求，加载场景，并发回响应 LoadSceneResponse。

这些请求和响应中的数据被构造为使用协议缓冲区(protobuf)"）模式定义的消息。Protobuf 模式是由 Google^® 开发的语言中立格式，并针对快速高效的数据传输进行了优化。RoadRunner 服务器可以同时从这些 API 调用发送和接收数百万条 protobuf 消息，同时保持 RoadRunner 的实时更新。

Protobuf 模式中的消息在扩展名为 .proto 的文本文件中定义。这些消息包含定义以下内容的名称-值字段：

考虑 LoadScene RPC 方法的架构，如 roadrunner_service.proto 文件中所定义。

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

请求消息 LoadSceneRequest 和响应消息 LoadSceneResponse 的模式在 roadrunner_service_messages.proto 文件中定义。LoadSceneRequest 接受一个必需输入 file_path，它是一个指定要加载的文件路径的字符串。

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 可执行文件。此可执行文件包含命令行选项，使您能够指定：

此命令行代码显示如何从 Windows^® 上的默认安装位置打开 RoadRunner。RoadRunner 打开到位于 C:\RR\MyProject IP 网络端口 54321 上的工程。

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

RoadRunner 的 Output 窗格显示 RoadRunner API 服务器正在运行的端口。

从命令行使用 RoadRunner API

RoadRunner 提供了一个预编译的辅助命令 CmdRoadRunnerApi，使您能够从命令行调用 RoadRunner RPC 方法。此帮助程序命令与 AppRoadRunner 可执行文件位于同一文件夹中。

此代码调用 LoadScene 方法从打开的工程加载预构建的 FourWaySignal 场景。

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

在各种编程语言中使用 RoadRunner API

为了在使用 RoadRunner API 时获得更多灵活性，您可以将 API 编译为 gRPC 支持的语言，然后用该语言编写客户端应用程序以编程方式控制 RoadRunner。

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)