Interface de Agente Externo¶

A External Agent Interface (EAI) pode introduzir veículos controlados externamente em uma simulação microscópica do Aimsun Next. Esses veículos externos podem ser guiados pelas ações de, por exemplo, um motorista humano em um simulador, um controlador de veículo autônomo ou um sistema de controle experimental sendo testado em um ambiente de simulação.

Os dados trocados via EAI baseiam-se em localizações geográficas expressas como coordenadas x e y, em vez da representação simulada da rede de tráfego expressa por meio de faixas e movimentos de conversão.

Isso significa que a lógica de controle externa não precisa de conhecimento detalhado de como o Aimsun Next modela a rede de tráfego — ela pode continuar usando seu próprio modelo de rede. A troca de dados depende exclusivamente da existência de um sistema compartilhado de coordenadas comuns.

Veículos externos são posicionados na rede de tráfego dentro da simulação. Os outros veículos na simulação – aqueles controlados e atualizados pelo Aimsun Next – reagirão então à presença dos veículos externos seguindo-os, colaborando com suas manobras de mudança de faixa e incluindo-os em sua avaliação de brechas nas interseções, da mesma forma que reagem a outros veículos 'internos' na simulação.

Observe que, em cada passo de tempo simulado, o Aimsun Next envia uma lista de veículos 'internos' (isto é, veículos na rede do Aimsun) ao redor ou próximos de veículos 'externos' na aplicação externa. A posição desses veículos internos é baseada no centro do para-choque dianteiro.

Os semáforos são controlados exclusivamente pelo Aimsun Next em todos os momentos.

Arquitetura de Sistemas¶

A EAI é baseada em uma arquitetura cliente–servidor na qual o Aimsun Next é o servidor, responsável por gerenciar os semáforos e os demais veículos e pedestres na simulação. O cliente é o controlador externo, ou simulador, que recebe informações sobre os objetos dinâmicos na simulação e responde com as posições e orientações atualizadas dos veículos controlados externamente.

A EAI fornece o arquivo PROTO que deve ser usado para programar a interface usando uma biblioteca de software derivada diretamente desse arquivo no sistema host e usando a linguagem de programação preferida do cliente. Essa linguagem deve ser compatível com Google protocol buffers. Consulte Interface de Protocol Buffer para obter mais informações. Use esta opção ao trabalhar com C++, C#, Java, Python ou várias outras linguagens (verifique a lista completa no Protocol Buffers).

O mecanismo de comunicação subjacente é baseado em TCP/IP, com dados serializados usando Google protocol buffers: uma biblioteca de comunicação altamente eficiente e independente de plataforma. A simulação e o controlador podem estar na mesma plataforma computacional, ou em plataformas diferentes, conectadas por uma rede. Isso permite que a aplicação externa seja desenvolvida em qualquer linguagem de programação, sem a necessidade de conhecimento aprofundado do Aimsun Next.

Os dados serializados devem ser enviados por meio de um socket TCP/IP. Primeiro, o tamanho da mensagem serializada como um inteiro de 32 bits é enviado em ordem de rede. Em segundo lugar, a própria mensagem serializada é enviada. A frequência desta comunicação é a mesma do passo de simulação, que pode ser definido até 10Hz (0.1s).

O /programming/External Agents Interface pasta inclui uma implementação do mecanismo de conexão. Consulte TCPSocket.h e TCPSocket.cpp in Cpp-Sample/AimsunEAConnectorLib para a implementação e Cpp-Sample/AimsunEAConnectorTester para um exemplo de uso em C++.

Como exemplo de como usar a EAI com uma linguagem que não oferece suporte a protobuffers, há um exemplo de integração para MATLAB escrito em C. Você também pode encontrá-lo no /programming/External Agents Interface pasta.

Configuração e Execução do Servidor¶

Configuração da API¶

Abra o editor de Cenário, vá para a aba External Agents Interface e marque Ativar Interface de Agentes Externos. Em seguida, configure suas propriedades conforme descrito na próxima seção (a captura de tela abaixo serve apenas como exemplo).

Opções de Configuração¶

• Initial Communication Timeout (s): Defina um tempo em segundos durante o qual o Aimsun Next aguardará a conexão do controlador externo. Após este tempo limite, a simulação começará sem comunicação.

• Tempo Limite da Mensagem (s): Defina um tempo em segundos durante o qual a Interface de Protocol Buffer aguardará uma resposta. Após esse tempo limite, a comunicação será encerrada.

• Interpolar Trajetória de Mudança de Faixa: Marque esta caixa para aplicar suavização visual à posição dos veículos enquanto eles mudam de faixa na visualização principal da interface do Aimsun Next.

• Server Port: Selecione ou insira o número da porta do servidor.

• Número de Conexões Esperadas: O Aimsun Next pode se conectar a vários clientes. Defina o número de clientes esperados para esta simulação. O servidor deixará de esperar por novas conexões se esse valor for atingido.

• Requires Expected Number of Connections: Marque esta caixa se a simulação deve ser abortada caso o número de conexões estabelecidas seja menor que as conexões esperadas.

• Registrar Mensagens de Entrada: Esta caixa ativa o armazenamento das mensagens que o Aimsun Next recebe de software externo durante a simulação. O arquivo será armazenado como replicationID_connectionID_replay.eai.

• Record Output Messages: Esta caixa ativa o armazenamento das mensagens que o Aimsun Next envia para software externo durante a simulação. O arquivo será armazenado como replicationID_connectionID_replay_out.eai.

• External Agent Type To Vehicle/Pedestrian Type: Adicione a correspondência entre cada Agent Type, por ID, e um Vehicle ou Pedestrian Type.

  Nota: Nenhum dos parâmetros de comportamento ou parâmetros de roteamento dinâmico definidos para a opção selecionada, que normalmente são usados pelo Aimsun Next, é relevante para determinar as ações do veículo controlado externamente.

• Classe de veículo para tipo de agente externo: selecione qual classe de veículo representará cada tipo de agente externo. Se nenhuma classe for selecionada, AGENT_NOT_DEFINED será usado como o tipo de agente externo padrão. Se um veículo simulado pertencer a mais de uma classe de veículo com tradução de tipo de agente externo definida, a menor valor do tipo terá prioridade.

Executando a Simulação¶

1. No Windows, execute o comando:

   Aimsun Next.exe --verbose --EVC-host --wait_to_sync --project evc_model.ang

   Isso iniciará o Aimsun Next como um External Vehicle Host aguardando que um controlador externo se conecte a ele.

2. Separadamente, execute o External Vehicle Controller, que está configurado para se conectar à simulação do Aimsun Next. Quando ambos os elementos – simulação e controlador – estiverem em execução, execute a replicação da simulação normalmente. A cada passo de tempo da simulação, a posição dos veículos controlados externamente será atualizada pelo controlador vinculado. Uma opção interessante seria ter um script que execute essa aplicação/controlador externo e definir esse script como um Script de Pré-Execução.

Programação de Cliente ¶

O controlador cliente é o software que move os veículos controlados externamente. Sua sequência de operações é a seguinte.

• Criação do modelo:

• Configura o controlador para que ele use um mapa que corresponda à mesma área do modelo de simulação. O controlador pode exigir diferentes níveis de conhecimento detalhado da área. Especificamente, ele pode precisar de mais conhecimento sobre mobiliário urbano ou sobre meios-fios e rampas onde possa fazer a transição entre áreas viárias e áreas de pedestres. No entanto, ele deve corresponder à rede de simulação em termos de topologia viária e do sistema de coordenadas. Os IDs de quaisquer semáforos também devem ser compartilhados entre a simulação e o controlador cliente.

• Iniciando o controlador:

• Abre uma conexão com a simulação.

• Cria o(s) veículo(s) controlado(s) externamente.

• Em cada passo de tempo:

• Grava a posição atual do(s) veículo(s) controlado(s) externamente.

• Lê da simulação as novas posições dos agentes simulados (veículos e pedestres) dentro de um raio definido do(s) veículo(s) controlado(s) externamente.

• Lê o novo estado dos semáforos dentro desse raio.

• Lê o novo estado dos painéis de mensagens variáveis (VMS) nesse raio.

• Apresenta essas informações a um controlador de veículo autônomo ou exibe esses veículos e sinais em um simulador de direção.

• Atualiza a posição do(s) veículo(s) externo(s) para o próximo passo de tempo.

• Ao final da simulação:

• Encerra a conexão.

• Desliga o controlador.

A interface pode ser programada no controlador usando:

• protocol buffers em qualquer uma das linguagens suportadas
• para um sistema sem suporte a protocol-buffers, por exemplo, MATLAB, há um exemplo de implementação como biblioteca C.

Diagramas de sequência¶

Caso 1: O Aimsun Next conclui a simulação

Caso 3: Aimsun Next cancela a simulação

Interface Protocol–Buffer ¶

Se o ponto de partida na codificação da interface do controlador for o arquivo PROTO que define o protocolo de comunicação, então isso permite que a interface seja escrita em uma de várias linguagens, incluindo C++, C# Java e Python – consulte a lista completa no Google's Protocol Buffers.

Ele pode ser compilado em qualquer sistema operacional para atender aos requisitos do software e do firmware do controlador.

Usando o arquivo PROTO, um programador também poderá:

• incluir múltiplos veículos controlados externamente
• definir as bolhas (áreas a partir das quais o Aimsun Next enviará informações sobre veículos e semáforos) e controlar seu tamanho e posição
• enviar uma lista de intenções para controlar o movimento dos pedestres.

Para usar o arquivo PROTO:

1. Obtenha o arquivo ExternalAgentsConnector.proto na subpasta de instalação do Aimsun Next, "/programming/External Agents Interface". Observe que este arquivo usa Protobuf Version 3. -Confira isto. Pode me ajudar.

2. Use as ferramentas fornecidas pelo Google para criar o código-fonte. Isso está documentado em Protocol Buffers página da web.

3. Adicione este código como parte do processo de compilação do projeto, normalmente editando o Makefile.

Então, ao programar a interface:

• Inicialização

• Abra um fluxo de entrada vinculado ao endereço IP e à porta EAI do computador que hospeda a simulação.

• Crie os veículos controlados externamente.

• A cada passo de tempo

• Ler a lista de objetos na(s) bolha(s).

• Avaliar as ações do controlador.

• Atualize as posições no Aimsun Next para os veículos controlados externamente e envie quaisquer informações para controlar pedestres, se necessário.

• Mover para o próximo passo de tempo.

O código gerado pela Google ProtoBuf Interface fornece as estruturas e constantes enumeradas com as quais construir as mensagens e as funções necessárias para enviá-las e recebê-las.

Detalhes do arquivo Proto¶

A partir do Aimsun Next 22, você pode usar três mensagens para controlar o movimento de pedestres se estiver usando a External Agent Interface para conectar sua simulação externa ao microssimulador do Aimsun Next.

Agora você pode sobrescrever a microssimulação do Aimsun Next e controlar se os pedestres esperam nas faixas de pedestres, atravessam ou param onde quer que estejam na simulação.

As mensagens que controlam este comportamento são denominadas WAIT_AT_CROSSWALK, USE_CROSSWALK e STOP_MOVING. Essas mensagens, quando enviadas, substituirão o comportamento esperado ou 'típico' dos pedestres e também substituirão o efeito dos estados dos semáforos.

Os dois primeiros são autoexplicativos, e o terceiro, STOP_MOVING, significa que um pedestre desacelerará e parará, mas, se estiver perto de outros pedestres, ainda poderá se mover se for empurrado e ainda reagirá a obstáculos.

Conector da Interface de Agente Externo para C++¶

Há um exemplo na pasta programming\External Agents Interface\Cpp-Sample para mostrar como usar a interface em C++. Isto deve ser usado como ponto de partida para um projeto que irá se conectar ao Aimsun Next por meio da External Agent Interface.

Use cmake para configurar e compilar o exemplo em C++. O único requisito externo são as bibliotecas protocol buffer e spdlog, idealmente por meio do gerenciador de pacotes vcpkg.

cd "programming\External Agents Interface\Cpp-Sample"
cmake -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=$env:{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake
cmake --build build

Estrutura¶

• AimsunEAConnectorLib é uma biblioteca que controla a conexão, a sincronização e o fluxo de execução.
• AimsunEAConnectorTester é um exemplo de como estender esta biblioteca com seu próprio modelo.

Este exemplo é uma ferramenta que fornece um fluxo de trabalho funcional, mas é uma ferramenta criada para que possa ser integrada em projetos maiores ou usada como base.

Gerar itens externos¶

Executado automaticamente após estabelecer uma conexão bem-sucedida com o Aimsun Next. Destina-se a ser usado para criar o(s) veículo(s) e modelos para a aplicação externa.

void generateExternalItems();

Gerenciar Dados Recebidos¶

Em cada etapa, destina-se a ser usado para tratar os dados recebidos da cossimulação do Aimsun Next e configurar o contexto (talvez preencher estruturas de dados, logs, imprimir informações etc.).

void manageReceivedData( const ExternalAgents::Out * out ) override;

Atualizar Itens Externos¶

Executado imediatamente após gerenciar os dados recebidos, destina-se a ser usado para atualizar o(s) veículo(s) que serão enviados e tomar decisões com o novo contexto.

void updateExternalItems();

Enviar Itens Externos¶

Executado imediatamente após a atualização de itens externos, destina-se a ser usado para enviar o(s) veículo(s), bolhas, intenções de pedestres ou qualquer conteúdo que a mensagem precise conter. Pode ser usado como um hub para iniciar ferramentas de depuração, armazenar logs etc.

void sendExternalItems();

Limpar Itens Externos¶

Executado automaticamente após o encerramento da conexão com o Aimsun Next. Destina-se a ser usado para limpar as estruturas de dados utilizadas na execução, pois esse fluxo de trabalho pode ser um pequeno procedimento dentro de um programa maior que continua em execução após a conclusão da cossimulação.

void cleanExternalItems();

Conector da Interface de Agente Externo para MATLAB¶

Há um exemplo na programming\External Agents Interface\MATLAB pasta para mostrar como usar a interface no MATLAB.

Use cmake para configurar e compilar o exemplo. Os únicos requisitos externos são a biblioteca protocol buffer e a biblioteca spdlog, idealmente usando o gerenciador de pacotes vcpkg.

cd "programming\External Agents Interface\MATLAB"
cmake -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=$env:{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake
cmake --build build

Diagramas de Sequência para MATLAB¶

A biblioteca C que implementa a interface para MATLAB tem uma sequência diferente, baseada em funções em vez de mensagens.

Estruturas¶

Informações do Cenário¶

/*! Scenario information */
struct AimsunEACLoadResult
{
    int timeStep;    // Simulation time step in Aimsun Next (ms)
    int start;       // start time (virtual clock) of the simulation in ms since epoch
    int duration;    // duration of the simulation in ms
};

Semáforo ¶

/*! A traffic signal 
    - name: external name of the signal
    - state:
        NOT_DEFINED = 0
        OFF = 1
        GREEN = 2
        YELLOW = 3
        RED = 4
        FLASHING_YELLOW = 5
        FLASHING_RED = 6
        YELLOW_BEFORE_GREEN = 7
        FLASHING_GREEN_AS_GREEN = 8
        FLASHING_RED_AS_RED = 9
        FLASHING_YELLOW_AS_YELLOW = 10
        YELLOW_AS_GREEN = 11
*/

struct AimsunEACTrafficLightState
{
    char    name[100];   // The external name of the signal
    int     state;   // The state of the signal
}

Estado do VMS ¶

/*! A variable message sign (VMS)
    - external_id: External id of the VMS object.
    - message: The current message shown on the VMS
*/

struct AimsunEACVMSState
{
    char    external_id[64];
    char    message[256];
}

Agente ¶

A estrutura do agente se aplica tanto aos veículos controlados externamente quanto aos veículos da simulação.

/*! An agent
- id: unique identifier of the agent
- x, y, z:  Position of vehicle (for pedestrians, the center)
    - When reading from Aimsun Next, it corresponds to the mid-position of the front bumper
    - When sending to Aimsun Next, send mid-position of the rear axle

- h: heading as radians with the horizontal
- speed: agent speed in m/s
- length: in meters
- width: in meters
- type:
    AGENT_NOT_DEFINED = 0
    CAR = 1
    BIKE = 2
    TRUCK = 3
    BUS = 4
    PEDESTRIAN = 5
    MOTORCYCLE = 6

- brakeLight : Indicates if brake light is activated
- leftTurnSignal: Indicates if left-turn signal is activated
- rightTurnSignal: Indicates if right-turn signal is activated
- minUpstreamTimeGapForLaneChange: Indicates the minimum time needed to change to a different lane in front of an upstream vehicle
*/

struct AimsunEACAgent
{
    int         id;     // The unique identifier of the vehicle
    double      x;      // The x coordinate of a vehicle's rear axle or a pedestrian's center point position
    double      y;      // The y coordinate of a vehicle's rear axle or a pedestrian's center point position
    double      z;      // The z coordinate of a vehicle's rear axle or a pedestrian's center point position
    double      h;      // The heading as radians from the Easting
    double      length; // The agent length in m.
    double      width;  // The agent width in m.
    double      speed;  // The agent speed in m/s
    bool        brakeLight;         // Whether the agent has the brake light on or not
    bool        leftTurnIndicator;  // Whether the agent has the left turn indicator on or not
    bool        rightTurnIndicator; // Whether the agent has the right turn indicator on or not
    int         type;               // The agent type
    double  minUpstreamTimeGapForLaneChange; // Indicates the minimum time needed to change to a different lane in front of an upstream vehicle
};

Funções (Biblioteca C)¶

Observação: Esta biblioteca é uma amostra que usa o código gerado pelos arquivos PROTO para permitir a comunicação com a External Agents Interface. Usando essas funções, seria possível criar um programa que segue a sequência descrita no diagrama MATLAB para executar uma co-simulação.

AimsunEACStart¶

Conecta-se a uma instância do Aimsun Next em execução em um host e com uma porta aberta. Os valores padrão são localhost e 1541. Retorna true se a conexão foi estabelecida e false se não.

bool AimsunEACStart( const char * host, int port );

AimsunEACStop¶

Fecha a conexão com a instância do Aimsun Next.

void AimsunEACStop();

AimsunEACLoad¶

Chama a função load para receber o AimsunEACLoadResult. Retorna true se a conexão ainda estiver aberta, false caso contrário.

bool AimsunEACLoad();

AimsunEACRead¶

Lê os dados do Aimsun Next. Retorna 0 se a conexão foi perdida ou se o tipo de mensagem foi lido. Os tipos de mensagem são:

1. LoadResult. Use AimsunEACGetLoadResult

2. Out. Use AimsunEACAgentsRead, AimsunEACTrafficLightsRead e AimsunEACVMSStatesRead

3. Fechar

4. CloseResult

   int AimsunEACRead();

AimsunEACCloseReceived¶

Verifica se a simulação foi concluída e se a porta foi fechada. Retorna true se o Aimsun Next tiver concluído a simulação.

bool AimsunEACCloseReceived();

AimsunEACGetLoadResult¶

Retorna as informações do cenário. Chame esta função após uma chamada bem-sucedida a AimsunEACRead().

AimsunEACLoadResult * AimsunEACGetLoadResult();

AimsunEACAgentsRead¶

Retorna o número de veículos ao redor do veículo externo. Chame esta função após uma chamada bem-sucedida a AimsunEACRead(). O raio de visibilidade padrão é 100m.

int AimsunEACAgentsRead();

AimsunEACGetAgent¶

Lê as informações de um veículo, indexado de 0 a (AimsunEACAgentsRead() - 1). Chame esta função após uma chamada bem-sucedida a AimsunEACAgentsRead(). O ponteiro para a estrutura AimsunEACAgent não deve ser liberado nem reatribuído.

struct AimsunEACAgent * AimsunEACGetAgent( int i );

AimsunEACTrafficLightsRead¶

Retorna o número de semáforos ao redor do veículo externo. Chame esta função após uma chamada bem-sucedida a AimsunEACRead().

int AimsunEACTrafficLightsRead();

AimsunEACGetTrafficLightState¶

Lê as informações referentes a um semáforo, indexado de 0 a (AimsunEACTrafficLightsRead() - 1). Chame esta função após uma chamada bem-sucedida a AimsunEACTrafficLightsRead(). O ponteiro para a estrutura AimsunEACTrafficLightState não deve ser liberado nem reatribuído.

struct AimsunEACTrafficLightState * AimsunEACGetTrafficLightState( int i );

AimsunEACVMSStatesRead¶

Retorna o número de estados VMS ao redor do veículo externo. Chame esta função após uma chamada bem-sucedida a AimsunEACRead().

int AimsunEACVMSStatesRead();

AimsunEACGetVMSState¶

Lê as informações de um VMS, indexadas de 0 a (AimsunEACVMSStatesRead() - 1). Chame esta função após uma chamada bem-sucedida a AimsunEACVMSStatesRead(). O ponteiro para a estrutura AimsunEACVMSState não deve ser liberado nem reatribuído.

struct AimsunEACVMSState * AimsunEACGetVMSState( int i );

AimsunEACWrite¶

Insere ou atualiza um veículo externo na simulação. A posição e o rumo do veículo devem ser definidos na estrutura AimsunEACAgent. Observe que o comportamento do veículo não é modificado pelo Aimsun Next – apenas a posição é atualizada e, portanto, a velocidade do veículo é ignorada. Retorna false se os dados não puderem ser gravados.

bool AimsunEACWrite( struct AimsunEACAgent *agent );

AimsunEACClose¶

Solicita ao Aimsun Next que encerre a simulação. Retorna true se esta solicitação for executada com sucesso.

bool AimsunEACClose();

Observação sobre licenças: Esta funcionalidade está disponível em assinaturas anuais do Aimsun Next Pro, Advanced ou Expert Edition.