Questa pagina è stata tradotta con la traduzione automatica. Fai clic qui per vedere l'ultima versione in inglese.

Controlla RoadRunner a livello di codice utilizzando l'API gRPC

RoadRunner fornisce un'API che consente di controllare l'interfaccia utente RoadRunner in modo programmatico. Ad esempio, utilizzando questa API, puoi:

  • Crea, carica e salva scene, scenari e progetti RoadRunner .

  • Importa file ASAM OpenDRIVE® nelle scene.

  • Esporta scene e scenari in uno dei formati di file supportati RoadRunner .

RoadRunner ti consente di compilare versioni dell'API in vari linguaggi di programmazione e chiamarle nella lingua che scegli. In alternativa, puoi utilizzare una versione precompilata dell'API che ti consente di controllare RoadRunner dalla riga di comando.

Come funziona l'API RoadRunner

L'API RoadRunner è creata utilizzando il framework open source gRPC® . Questo framework utilizza un'architettura client-server in cui un'applicazione client controlla in remoto un'applicazione server utilizzando una serie di metodi RPC (Remote Procedure Call). In RoadRunner:

  • La versione di RoadRunner installata localmente è l'applicazione server.

  • L'API RoadRunner fornisce i metodi RPC utilizzati per controllare in remoto RoadRunner.

  • I programmi scritti per chiamare i metodi RPC sono le applicazioni client. Il framework gRPC è indipendente dal linguaggio e dalla piattaforma. Puoi scrivere client che chiamano l'API RoadRunner in qualsiasi piattaforma e linguaggio supportato gRPC . Per dettagli su quali lingue e piattaforme sono supportate gRPC , vedere gRPC Documentation.

Questo diagramma mostra un layout semplificato dell'architettura API. In questo diagramma, un client Python® utilizza il metodo LoadScene per caricare una scena in RoadRunner.

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

Come l'API RoadRunner invia e riceve i dati

I metodi RPC dell'API RoadRunner sono definiti in un servizio gRPC . Ogni volta che chiami un metodo che fa parte di un servizio gRPC , quel metodo:

  • Invia una richiesta a un server.

  • Riceve una risposta dal server.

Questo diagramma mostra questo formato di richiesta-risposta per una chiamata del metodo LoadScene . Nel client, l'input del metodo, LoadSceneRequest, è una richiesta che il client invia al server delle applicazioni RoadRunner . RoadRunner elabora questa richiesta, carica una scena e invia una risposta, LoadSceneResponse.

The RoadRunner request-response relationship

I dati in queste richieste e risposte sono strutturati come messaggi definiti utilizzando lo schema del buffer del protocollo (protobuf). Lo schema protobuf è un formato indipendente dal linguaggio sviluppato da Google® ed è ottimizzato per un trasferimento dati rapido ed efficiente. Il server RoadRunner può inviare e ricevere milioni di messaggi protobuf da queste chiamate API simultaneamente mantenendo aggiornamenti in tempo reale di RoadRunner.

I messaggi nello schema protobuf sono definiti in file di testo con estensione .proto . Questi messaggi contengono campi nome-valore che definiscono:

  • I nomi dei campi che è possibile specificare nei messaggi.

  • I tipi di dati dei campi. Ad esempio, puoi specificare i campi come valori booleani, stringhe o come altri messaggi protobuf.

Considerare lo schema per il metodo RPC LoadScene , come definito nel file roadrunner_service.proto .

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

Lo schema per il messaggio di richiesta, LoadSceneRequest e il messaggio di risposta, LoadSceneResponse, sono definiti nel file roadrunner_service_messages.proto . LoadSceneRequest accetta un input obbligatorio, file_path, che è una stringa che specifica il percorso del file da caricare. 

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

Dopo che RoadRunner ha elaborato la richiesta (tentativo di caricare la scena), il server API RoadRunner invia in risposta un messaggio LoadSceneResponse vuoto.

message LoadSceneResponse
{
}

Poiché lo schema protobuf è indipendente dal linguaggio, la sintassi utilizzata per chiamare i metodi e formattare le richieste di messaggi dipende dal linguaggio di programmazione utilizzato per scrivere le applicazioni client.

Connettiti al server API RoadRunner

Per utilizzare l'API RoadRunner , è necessario innanzitutto stabilire una connessione di rete con il server API RoadRunner . Questo server fa parte dell'installazione locale RoadRunner e inizia a funzionare quando si apre un progetto.

Per aprire RoadRunner a livello di programmazione e avviare il server API, chiamare l'eseguibile AppRoadRunner dall'installazione RoadRunner locale. Questo eseguibile contiene opzioni della riga di comando che consentono di specificare:

  • Il progetto a cui si apre RoadRunner

  • La porta di rete IP su cui viene eseguito il server API RoadRunner

Questo codice della riga di comando mostra come aprire RoadRunner dal percorso di installazione predefinito su Windows®. RoadRunner si apre a un progetto situato in C:\RR\MyProject sulla porta di rete IP 54321.

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

Il riquadro Output di RoadRunner visualizza la porta su cui è in esecuzione il server API RoadRunner .

Output pane with RoadRunner API server message

Utilizza l'API RoadRunner dalla riga di comando

RoadRunner fornisce un comando helper precompilato, CmdRoadRunnerApi, che consente di chiamare i metodi RPC RoadRunner dalla riga di comando. Questo comando di supporto si trova nella stessa cartella dell'eseguibile AppRoadRunner .

Questo codice chiama il metodo LoadScene per caricare la scena FourWaySignal predefinita dal progetto aperto.

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

RoadRunner scene containing a four-way intersection with traffic signals

Utilizza l'API RoadRunner in vari linguaggi di programmazione

Per una maggiore flessibilità nell'utilizzo dell'API RoadRunner , puoi compilare l'API in un linguaggio supportato da gRPC e quindi scrivere applicazioni client in tale linguaggio per controllare RoadRunner a livello di codice.

Compila l'API RoadRunner

Per compilare l'API RoadRunner nel linguaggio di programmazione desiderato, devi prima copiare i file protobuf che definiscono l'API in una cartella scrivibile. Questi file si trovano nell'installazione locale RoadRunner . Puoi quindi utilizzare il compilatore protobuf, insieme al plug-in gRPC per il linguaggio di programmazione desiderato, per compilare versioni o collegamenti specifici del linguaggio dell'API RoadRunner . Ad esempio, questo diagramma mostra la generazione di associazioni Python e C++.

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

Per dettagli sulla compilazione dei file protobuf, vedere Compilare i buffer del protocollo per l'API RoadRunner gRPC.

Crea client API RoadRunner

I client che scrivi per controllare a livello di RoadRunner in genere contengono codice che esegue questi passaggi:

  1. Importa il codice gRPC dalle associazioni compilate.

  2. Stabilire una connessione di rete locale al server API RoadRunner .

  3. Utilizza il codice gRPC importato per creare un oggetto API RoadRunner . Questo oggetto è chiamato stub.

  4. Chiama i metodi RPC da questo stub per controllare RoadRunner sulla rete locale.

Questo semplice client Python mostra un esempio di chiamata al metodo 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)

Dopo aver importato i collegamenti gRPC Python compilati, questo client stabilisce una connessione su un canale gRPC e crea uno stub per l'API del servizio RoadRunner . Il canale gRPC per l'API utilizza credenziali di canale non sicure e non dispone di crittografia o autenticazione. Poiché RoadRunner in genere viene eseguito su un computer locale e non si connette a reti esterne, il rischio per la sicurezza è basso. Quindi, il client chiama LoadScene dallo stub API, che carica la scena FourWaySignal precostruita dal progetto attualmente aperto.

È possibile avere più client che chiamano metodi RPC contemporaneamente, purché siano connessi a RoadRunner sulla stessa porta di rete. Ad esempio, in questo diagramma, sia un client Python che un client C++ chiamano LoadScene sulla porta di rete 54321.

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

Vedi anche

Argomenti