이 페이지는 기계 번역을 사용하여 번역되었습니다. 영어 원문을 보려면 여기를 클릭하십시오.

gRPC API를 사용하여 프로그래밍 방식으로 RoadRunner 제어

RoadRunner는 RoadRunner UI를 프로그래밍 방식으로 제어할 수 있는 API를 제공합니다. 예를 들어 이 API를 사용하면 다음을 수행할 수 있습니다.

  • RoadRunner 장면, 시나리오 및 프로젝트를 생성하고 불러오고 저장하세요.

  • ASAM OpenDRIVE® 파일을 장면으로 가져옵니다.

  • RoadRunner가 지원하는 파일 형식 중 하나로 장면과 시나리오를 내보냅니다.

RoadRunner를 사용하면 다양한 프로그래밍 언어로 API 버전을 컴파일하고 선택한 언어로 호출할 수 있습니다. 또는 명령줄에서 RoadRunner를 제어할 수 있는 미리 컴파일된 API 버전을 사용할 수 있습니다.

RoadRunner API 작동 방식

RoadRunner API는 오픈 소스 gRPC® 프레임워크를 사용하여 구축되었습니다. 이 프레임워크는 클라이언트 애플리케이션이 일련의 RPC(원격 프로시저 호출) 방법을 사용하여 서버 애플리케이션을 원격으로 제어하는 클라이언트-서버 아키텍처를 사용합니다. RoadRunner에서:

  • 로컬에 설치된 RoadRunner 버전은 서버 응용 프로그램입니다.

  • RoadRunner API는 RoadRunner를 원격으로 제어하는 데 사용되는 RPC 방법을 제공합니다.

  • RPC 메소드를 호출하기 위해 작성하는 프로그램은 클라이언트 애플리케이션입니다. gRPC 프레임워크는 언어 중립적이고 플랫폼 중립적입니다. gRPC가 지원하는 모든 플랫폼 및 언어로 RoadRunner API를 호출하는 클라이언트를 작성할 수 있습니다. 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 확장자를 가진 텍스트 파일로 정의됩니다. 이러한 메시지에는 다음을 정의하는 이름-값 필드가 포함되어 있습니다.

  • 메시지에 지정할 수 있는 필드의 이름입니다.

  • 필드의 데이터 유형입니다. 예를 들어 필드를 부울 값, 문자열 또는 기타 protobuf 메시지로 지정할 수 있습니다.

roadrunner_service.proto 파일에 정의된 대로 LoadScene RPC 메서드에 대한 스키마를 고려하세요.

// 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 실행 파일을 호출하세요. 이 실행 파일에는 다음을 지정할 수 있는 명령줄 옵션이 포함되어 있습니다.

  • RoadRunner가 여는 프로젝트

  • RoadRunner API 서버가 실행되는 IP 네트워크 포트

이 명령줄 코드는 Windows®의 기본 설치 위치에서 RoadRunner를 여는 방법을 보여줍니다. RoadRunner는 IP 네트워크 포트 54321의 C:\RR\MyProject에 있는 프로젝트를 엽니다.

cd "C:\Program Files\RoadRunner R2025b\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 실행 파일과 동일한 폴더에 있습니다.

이 코드는 LoadScene 메서드를 호출하여 열려 있는 프로젝트에서 미리 빌드된 FourWaySignal 장면을 불러옵니다.

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

RoadRunner scene containing a four-way intersection with traffic signals

다양한 프로그래밍 언어로 RoadRunner API 사용

RoadRunner API 사용 시 추가적인 유연성을 위해 API를 gRPC에서 지원하는 언어로 컴파일한 다음 해당 언어로 클라이언트 애플리케이션을 작성하여 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 파일 컴파일에 대한 자세한 내용은 RoadRunner gRPC API용 프로토콜 버퍼 컴파일 항목을 참조하세요.

RoadRunner API 클라이언트 생성

RoadRunner를 프로그래밍 방식으로 제어하기 위해 작성하는 클라이언트에는 일반적으로 다음 단계를 수행하는 코드가 포함되어 있습니다.

  1. 컴파일된 바인딩에서 gRPC 코드를 가져옵니다.

  2. RoadRunner API 서버에 대한 로컬 네트워크 연결을 설정합니다.

  3. 가져온 gRPC 코드를 사용하여 RoadRunner API 객체를 생성합니다. 이 객체를 스텁이라고 합니다.

  4. 로컬 네트워크를 통해 RoadRunner를 제어하려면 이 스텁에서 RPC 메서드를 호출하세요.

이 간단한 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는 일반적으로 로컬 컴퓨터에서 실행되고 외부 네트워크에 연결되지 않으므로 보안 위험이 낮습니다. 그런 다음 클라이언트는 현재 열려 있는 프로젝트에서 사전 빌드된 FourWaySignal 장면을 불러오는 API 스텁에서 LoadScene를 호출합니다.

동일한 네트워크 포트의 RoadRunner에 연결되어 있는 한 RPC 메서드를 동시에 호출하는 여러 클라이언트를 가질 수 있습니다. 예를 들어 이 다이어그램에서는 Python 클라이언트와 C++ 클라이언트 모두 네트워크 포트 54321를 통해 LoadScene를 호출하고 있습니다.

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

참고 항목

도움말 항목