Esta página se ha traducido mediante traducción automática. Haga clic aquí para ver la última versión en inglés.

Controle RoadRunner mediante programación usando gRPC API

RoadRunner proporciona una API que le permite controlar la interfaz de usuario de RoadRunner mediante programación. Por ejemplo, utilizando esta API, puedes:

  • Cree, cargue y guarde escenas, escenarios y proyectos de RoadRunner .

  • Importe archivos ASAM OpenDRIVE® a escenas.

  • Exporte escenas y escenarios a uno de los formatos de archivo compatibles con RoadRunner .

RoadRunner le permite compilar versiones de la API en varios lenguajes de programación y llamarlas en el idioma que elija. Alternativamente, puede utilizar una versión precompilada de la API que le permite controlar RoadRunner desde la línea de comandos.

Cómo funciona la API RoadRunner

La API RoadRunner se creó utilizando el marco de código abierto gRPC® . Este marco utiliza una arquitectura cliente-servidor en la que una aplicación cliente controla de forma remota una aplicación de servidor mediante un conjunto de métodos de llamada a procedimiento remoto (RPC). En RoadRunner:

  • Su versión instalada localmente de RoadRunner es la aplicación del servidor.

  • La API de RoadRunner proporciona los métodos RPC utilizados para controlar RoadRunner de forma remota.

  • Los programas que escribe para llamar a los métodos RPC son las aplicaciones cliente. El marco gRPC es neutral en cuanto al idioma y a la plataforma. Puede escribir clientes que llamen a la API de RoadRunner en cualquier plataforma e idioma que admita gRPC . Para obtener detalles sobre qué idiomas y plataformas admite gRPC , consulte gRPC Documentation.

Este diagrama muestra un diseño simplificado de la arquitectura API. En este diagrama, un cliente Python® usa el método LoadScene para cargar una escena en RoadRunner.

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

Cómo envía y recibe datos la API RoadRunner

Los métodos RPC de la API de RoadRunner están definidos en un servicio gRPC . Cada vez que llamas a un método que forma parte de un servicio gRPC , ese método:

  • Envía una solicitud a un servidor.

  • Recibe una respuesta del servidor.

Este diagrama muestra este formato de solicitud-respuesta para una llamada del método LoadScene . En el cliente, la entrada al método, LoadSceneRequest, es una solicitud que el cliente envía al servidor de aplicaciones RoadRunner . RoadRunner procesa esta solicitud, carga una escena y devuelve una respuesta, LoadSceneResponse.

The RoadRunner request-response relationship

Los datos de estas solicitudes y respuestas se estructuran como mensajes que se definen utilizando el esquema de búfer de protocolo (protobuf). El esquema protobuf es un formato de lenguaje neutral desarrollado por Google® y está optimizado para una transferencia de datos rápida y eficiente. El servidor RoadRunner puede enviar y recibir millones de mensajes protobuf desde estas llamadas API simultáneamente mientras mantiene actualizaciones de RoadRunner en tiempo real.

Los mensajes en el esquema protobuf se definen en archivos de texto con una extensión .proto . Estos mensajes contienen campos de nombre-valor que definen:

  • Los nombres de los campos que puede especificar en los mensajes.

  • Los tipos de datos de los campos. Por ejemplo, puede especificar campos como valores booleanos, cadenas u otros mensajes protobuf.

Considere el esquema para el método RPC LoadScene , tal como se define en el archivo roadrunner_service.proto .

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

El esquema para el mensaje de solicitud, LoadSceneRequest, y el mensaje de respuesta, LoadSceneResponse, se definen en el archivo roadrunner_service_messages.proto . LoadSceneRequest toma una entrada requerida, file_path, que es una cadena que especifica la ruta del archivo a cargar. 

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

Después de que RoadRunner procesa la solicitud (intenta cargar la escena), el servidor API de RoadRunner devuelve un mensaje LoadSceneResponse vacío en respuesta.

message LoadSceneResponse
{
}

Dado que el esquema de protobuf es neutral en cuanto al lenguaje, la sintaxis utilizada para llamar a los métodos y formatear sus solicitudes de mensajes depende del lenguaje de programación que utilice para escribir sus aplicaciones cliente.

Conéctese al servidor API de RoadRunner

Para utilizar la API de RoadRunner , primero debe establecer una conexión de red con el servidor de la API de RoadRunner . Este servidor es parte de su instalación local de RoadRunner y comienza a ejecutarse cuando abre un proyecto.

Para abrir RoadRunner mediante programación e iniciar el servidor API, llame al ejecutable AppRoadRunner desde su instalación local de RoadRunner . Este ejecutable contiene opciones de línea de comandos que le permiten especificar:

  • El proyecto al que se abre RoadRunner

  • El puerto de red IP en el que se ejecuta el servidor API de RoadRunner

Este código de línea de comandos muestra cómo abrir RoadRunner desde su ubicación de instalación predeterminada en Windows®. RoadRunner se abre en un proyecto ubicado en C:\RR\MyProject en el puerto de red IP 54321.

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

El panel Output de RoadRunner muestra el puerto en el que se ejecuta el servidor API de RoadRunner .

Output pane with RoadRunner API server message

Utilice la API RoadRunner desde la línea de comandos

RoadRunner proporciona un comando auxiliar precompilado, CmdRoadRunnerApi, que le permite llamar a los métodos RPC de RoadRunner desde la línea de comandos. Este comando auxiliar se encuentra en la misma carpeta que el ejecutable AppRoadRunner .

Este código llama al método LoadScene para cargar la escena FourWaySignal prediseñada desde el proyecto abierto.

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

RoadRunner scene containing a four-way intersection with traffic signals

Utilice la API RoadRunner en varios lenguajes de programación

Para obtener flexibilidad adicional en el uso de la API de RoadRunner , puede compilar la API en un lenguaje compatible con gRPC y luego escribir aplicaciones cliente en ese lenguaje para controlar RoadRunner mediante programación.

Compilar la API de RoadRunner

Para compilar la API de RoadRunner en el lenguaje de programación que desee, primero debe copiar los archivos protobuf que definen la API en una carpeta grabable. Estos archivos se encuentran en su instalación local de RoadRunner . Luego puede usar el compilador protobuf, junto con el complemento gRPC para el lenguaje de programación que desee, para compilar versiones o enlaces específicos del lenguaje de la API RoadRunner . Por ejemplo, este diagrama muestra la generación de enlaces Python y C++.

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

Para obtener detalles sobre cómo compilar los archivos protobuf, consulte Compilar buffers de protocolo para RoadRunner gRPC API.

Crear clientes API RoadRunner

Los clientes que usted escribe para controlar RoadRunner mediante programación generalmente contienen código que realiza estos pasos:

  1. Importe el código gRPC de los enlaces compilados.

  2. Establezca una conexión de red local con el servidor API de RoadRunner .

  3. Utilice el código gRPC importado para crear un objeto API RoadRunner . Este objeto se llama trozo.

  4. Llame a los métodos RPC desde este código auxiliar para controlar RoadRunner a través de la red local.

Este cliente Python simple muestra un ejemplo de cómo llamar al método 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)

Después de importar los enlaces gRPC Python compilados, este cliente establece una conexión a través de un canal gRPC y crea un código auxiliar para la API del servicio RoadRunner . . El canal gRPC para la API utiliza credenciales de canal inseguras y no tiene cifrado ni autenticación. Dado que RoadRunner normalmente se ejecuta en una máquina local y no se conecta a redes externas, el riesgo de seguridad es bajo. Luego, el cliente llama a LoadScene desde el código auxiliar de API, que carga la escena FourWaySignal prediseñada del proyecto actualmente abierto.

Puede tener varios clientes llamando a métodos RPC simultáneamente, siempre que estén conectados a RoadRunner en el mismo puerto de red. Por ejemplo, en este diagrama, tanto un cliente Python como un cliente C++ llaman a LoadScene a través del puerto de red 54321.

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

Consulte también

Temas