Programação do Aimsun Next V2X SDK¶

Introdução¶

O V2X Software Development Kit (SDK) foi projetado para permitir que um modelador acesse o framework V2X central no Aimsun Next para implementar VANets de veículos conectados em uma simulação. Uma VAnet é uma rede efêmera criada espontaneamente por um conjunto de veículos conectados próximos entre si. As VANets são formadas quando os veículos detectam transmissões de outros veículos; então, enquanto estão no alcance uns dos outros, eles conseguem trocar informações sobre sua localização e atividade. Ao agregar essas informações, um veículo consegue inferir o padrão do tráfego ao seu redor e, assim, ajustar seu próprio comportamento de acordo.

Uma VANet também pode incluir uma estação sem fio estática em uma Unidade de Beira de Via (RSU), efetivamente parte da infraestrutura de gestão da rede viária. Incluir uma RSU fixa a localização de uma VANet e lhe dá uma presença permanente; seus membros passam então a ser os veículos conectados na área adjacente. Se essa RSU for então vinculada ao Sistema de Gerenciamento de Tráfego (TMC) da rede, ela se torna tanto uma ferramenta de coleta de dados quanto um dispositivo de disseminação de informações como parte do sistema ITS mais amplo.

A estrutura central V2X implementada no Aimsun Next foi projetada para adicionar simulação de comunicação a um modelo dinâmico de tráfego e simular a troca de mensagens entre veículos conectados em rede ad-hoc e entre veículos conectados e uma RSU. Dentro de cada veículo, um modelador usará as classes e métodos desenvolvidos com o V2X SDK para coletar essas mensagens e usá-las para modificar o comportamento do veículo. Dentro de cada RSU, o modelador coletará, de forma semelhante, mensagens de veículos dentro do alcance dessa RSU e as processará localmente ou as retransmitirá para um TMC central, que pode derivar um conjunto coordenado de respostas de gerenciamento a serem retransmitidas aos veículos por meio da estrutura V2X ou por mecanismos ITS convencionais.

Portanto, o framework V2X tem como objetivo permitir a simulação de comportamento colaborativo entre veículos e também de comportamento coordenado por meio de controles do centro de gerenciamento, baseados em um fluxo rico de dados provenientes de veículos conectados e de unidades de infraestrutura ITS instaladas à margem da via.

Programação do V2X SDK¶

O V2X SDK difere da programação funcional usada na maior parte da API do Aimsun Next. Ele usa conceitos orientados a objetos para permitir que o programador desenvolva novas classes para objetos como Messages e Rules Engines, que são baseados em classes de modelo. Um programador que use o V2X SDK deve estar familiarizado com esses conceitos em C++.

Herança de Classes Orientada a Objetos¶

Um dos conceitos-chave usados no V2X SDK é a herança de classes. Uma classe modelo é usada para fornecer a estrutura de um tipo de objeto, e classes especializadas herdam métodos e dados do modelo. Por exemplo, a classe V2X::Message (abaixo) é o modelo, e as classes V2X::CAMMessage, V2X::SPATEMMessage e V2X::MAPEMMessage são especializações desse modelo. Cada uma das classes para tipos específicos herda os métodos e dados de V2X::Message, e cada uma acrescenta a ela os métodos e dados específicos desse tipo de mensagem.

A classe V2X::MyMessage é um tipo de mensagem fornecido pelo usuário, desenvolvido para uma aplicação específica. A classe é criada pelo método setup chamado quando a classe V2X::MyFramework é carregada no momento de inicialização e registrada com o V2X Framework dentro do Aimsun Next.

Quando em uso, mensagens do tipo V2X::MyMessage são transmitidas entre dispositivos da mesma maneira que outros tipos de mensagem. Isso ocorre porque os algoritmos de transmissão de mensagens manipulam objetos da classe V2X::Message e, portanto, manipulam automaticamente todos os tipos de mensagem que herdam essa classe template. Portanto, não é necessário nenhum trabalho adicional no núcleo do sistema V2X para permitir que novos tipos de mensagem sejam distribuídos.

Componentes V2X ¶

Os componentes do V2X Framework são descritos no Seção de Interface do Usuário V2X onde são criados e editados. Os componentes são:

• Tipo de Mensagem: Os tipos de mensagens trocadas entre veículos e as RSUs.

• Canal: O canal de comunicação é a representação simulada do hardware de rádio e dos protocolos que fornecem comunicações entre veículos.

• Unidade de Bordo: A OBU fornece o receptor e o transmissor em um veículo.

• RoadSide Unit(RSU): A RSU é o componente "I" da rede de comunicações Vehicle to Infrastructure (V2I). É um dispositivo de beira de via com uma localização especificada e também pode ser vinculado a uma interseção, ou a várias interseções.

• Centro de Gerenciamento de Tráfego: O Traffic Management Center é o integrador dos dados de múltiplas RSUs e o iniciador de ações coordenadas de controle semafórico e gestão de tráfego, além de acionar mensagens V2X a serem transmitidas pelas RSUs.

O componente da API que executa as ações para cada um dos veículos, RSUs e TMCs na simulação é um Mecanismo de Regras. Um Rules Engine é uma especialização de uma classe V2X::RulesEngine e é responsável por processar a lista de mensagens recebidas pela OBU, RSU ou TMC, processar os dados nessas mensagens e, em seguida, executar qualquer ação considerada necessária usando algoritmos projetados e codificados pelo modelador.

Nos casos simples, em que os tipos de mensagem são aqueles já fornecidos no framework V2X e as características do canal representam adequadamente o alcance de transmissão, a latência e as perdas de pacotes, o único código de API a ser escrito é um motor de regras para esses objetos com comportamentos alterados.

Instalação ¶

O instalador do V2X Framework instala tanto o plug-in V2X Framework quanto os arquivos do SDK, que incluem a documentação do usuário, as bibliotecas e arquivos de cabeçalho do V2X SDK e, no /include/aimsun_extensions/v2x/samples diretório, um projeto de exemplo do V2X SDK.

Entre em contato com a Aimsun para solicitar o instalador enviando um e-mail para info@aimsun.com.

Outros requisitos de software antes de iniciar a codificação são:

• Visual Studio 2019 ou mais recente, configurado para uso com Visual C++.
• Qt 5.14 ou mais recente. Você pode baixá-lo em https://www.qt.io/download. Como esclarecimento, o Qt está disponível como uma versão gratuita de código aberto.
• add-in Qt VS Tools para Visual Studio, estes precisam ser instalados a partir do Visual Studio como uma extensão (no Visual Studio, clique em ‘Extensions’ > ‘Online’ > procure por ‘Qt’ > instale ‘Qt Visual Studio Tools’

Configurando¶

• Certifique-se de ter instalado tanto o V2X Framework quanto o V2X SDK, bem como todos os requisitos anteriores.
• Acesse a pasta ‘StopEngine’ localizada dentro da pasta de instalação do V2X SDK da seguinte forma: ‘/include/aimsun_extensions/v2x/samples/StopEngine’
• Inicie o Visual Studio e configure o Qt VS Tools clicando em ‘Extensions’ > ‘Qt VS Tools’ > ‘Qt Options’. Na janela Qt Options, selecione a instalação apropriada do Qt.
• Abra o arquivo de projeto clicando em ‘Extensions’ > ‘Qt VS Tools’ > ‘Open Qt Project File’. Selecione o arquivo StopEngine.pro e compile como faria normalmente.
• Depois que ele terminar, copie a DLL gerada junto com o arquivo StopEngine.xml e coloque-os dentro de ‘/Aimsun Next 26/plugins/dynamicAPIS’. Se a pasta ‘dynamicAPIS’ não existir, crie-a.

O processo de configuração do V2X deve ter sido concluído corretamente. Abra um modelo de exemplo V2X e verifique se tudo está configurado conforme esperado.

Documentação de Classes ¶

A documentação gerada automaticamente para o V2X SDK é fornecida na distribuição. Abra o arquivo Program Files/Aimsun Next 26/docs/html/index.md para acessar a documentação do software

Esta documentação deve ser consultada ao programar com o V2X SDK, pois é gerada a partir do código-fonte e detalha todas as classes, seus inter-relacionamentos e seus métodos.

Classes V2X ¶

As principais classes usadas no desenvolvimento de uma aplicação V2X são a classe V2X::Framework, a classe V2X::Message e a classe V2X::RulesEngine.

V2X::Framework¶

Esta é a classe de modelo para gerenciamento de projetos V2X. O programador deve criar uma especialização desta para formar uma classe V2X:MyFramework baseada nesta classe de modelo.A nova classe deve fornecer a função setup para inicializar o sistema V2X quando a biblioteca programada for carregada e uma função destrutora que é executada ao final da simulação para fechar quaisquer links externos e gerar quaisquer dados de resumo como saída quando o objeto V2X::MyFramework for destruído.

Método de Configuração¶

O método setup para o framework é chamado pelo método construtor. Ele é usado para:

• Criar e registrar novos tipos de mensagem
• Adicione atributos a veículos ou unidades de beira de via para permitir que armazenem informações sobre sua atividade V2X.
• Crie e registre novos tipos de canais de comunicação com mais funcionalidades, ou funcionalidades diferentes, do que o tipo padrão.

Novas mensagens e novos canais serão adicionados à lista apresentada na editor de V2X OBU e editor de RSU após a criação.

Métodos de ação¶

A classe V2X::Framework também contém quatro funções virtuais chamadas durante a simulação:

• arrivalNewVehicle: Chamado quando um veículo entra na simulação.
• removedVehicle: Chamado quando um veículo sai da simulação.
• preUpdate: Chamado no início de cada passo de simulação.
• postUpdate: Chamado ao final de cada passo da simulação.

Estes quatro métodos são chamados em eventos significativos na simulação: quando os veículos entram e saem, e antes e depois de cada timestep. As ações normalmente seriam:

• No evento de novo veículo:
  • Configurar quaisquer dados de inicialização para o mecanismo de regras que controlará o novo veículo.
• No evento de saída do veículo:
  • Registrar quaisquer dados cumulativos sobre atividade relacionada a V2X para esse veículo.
• Em preUpdate, reúna dados que possam ser relevantes para as comunicações V2X:
  • Dados de outros sistemas ITS operando na simulação.
  • Status da rede, fazendo proxy dos dados disponíveis em um centro de controle de tráfego
• Em postUpdate, execute quaisquer ações determinadas usando dados V2X:
  • Fornecer informações a outros sistemas ITS operando na simulação.

Obter método do Rules Engine¶

O Método GetRulesEngine é chamado pelo método init da classe V2X::Framework e é usado para gerar um V2X::RulesEngine para cada tipo de dispositivo.

std::unique_ptr<V2X::RulesEngine> MyFramework::getRulesEngine( V2X::Device::DeviceType dType GKObject *oType ) const
{
    if( dType == V2X::Device::DeviceType::eObu &&
        oType->getTypeName() == "802.11p"){
        // an OBU of a specific type
        MyVehicleRulesEngine* rulesEngine = new MyVehicleRulesEngine();
        std::unique_ptr<V2X::RulesEngine> vres( rulesEngine );
        return vres;
    }
    else if( type == V2X::Device::DeviceType::eRsu ){
        MyRSURulesEngine* rulesEngine = new MyRSURulesEngine();
        std::unique_ptr<V2X::RulesEngine> rres( rulesEngine );
        return rres;
    }
    else
    {
        return nullptr;
    }

Isto cria o vínculo pelo qual a simulação pode chamar os callbacks do Rules Engine para entregar as V2X::Messages.

V2X::RulesEngine ¶

A classe V2X::RulesEngine é a classe modelo para um Rules Engine. O programador deve criar uma classe V2X::MyRulesEngine que herde a classe V2X::RulesEngine e implemente os métodos de ação de acordo com os requisitos do projeto.

Uma classe V2X::MyRulesEngine é necessária para cada um dos tipos de dispositivo usados na simulação e é criada no Método GetRulesEngine chamado pelo método init da classe V2X::Framework quando a simulação é carregada.

O Rules Engine tem dois métodos principais:

• avaliar: Chamado antes da execução do timestep. Este método entrega todas as mensagens recebidas a cada agente de simulação com um V2X::Device. O avaliar método é usado para coletar dados.
• performActions: Chamado após a execução do timestep. Este método é usado para implementar quaisquer ações exigidas pelo agente conectado ao dispositivo.

Esses métodos são chamados a cada passo de tempo para cada dispositivo na simulação. A classe é instanciada para cada dispositivo e, portanto, pode manter informações de estado sobre si mesma ou sobre o agente (isto é, o veículo) ao qual o dispositivo está associado. Por exemplo, isso pode ser o último horário de transmissão ou o último estado transmitido, de modo que a transmissão possa ser feita somente após uma mudança significativa.

Um exemplo de um método Evaluate que recebe mensagens e as adiciona aos dados do agente:

void MyRulesEngine::evaluate( double time )
{
    for( auto message : mMessages )
    {
        if( message->getType() == V2X::Message::eCustom ){
        const auto cMessage = std::dynamic_pointer_cast<MyMessage >(message);
        if(cMessage){
            //Get the data and the device
            const auto & data = cMessage->getData();
            auto agent = mDevice->agent();
            // collate the data
            agent->addToKnowledge(data->mydata);
        }
    }
}

Um exemplo de um método performActions que executa ações relacionadas a V2X a cada passo de tempo e também envia uma mensagem V2X a cada 10 segundos:

void MyRulesEngine::performActions( double time )
{
    auto agent = mDevice->agent();
    if( agent != nullptr)
    {
        auto id = mDevice->getId();
        \\ PerformActions with vehicle id
        agent->instantaction();
    }

    //creation and transmission of custom messages every 10 seconds 
    int trunkTime = static_cast<int>(time);
    if ( trunkTime % 10 == 0 )
    {
        auto message = std::make_shared<MyMessage>();
        auto & data = message->data();
        fillmessage(data); // Find what we want to transmit
        //select channels and set the messages to be send
        auto deviceChannels = mDevice->getChannels();
        for( auto channel : deviceChannels )
        {
             mDevice->addOneTimeMessage( message, channel->getId() );
        }
    }
}

V2X::Device ¶

A classe V2X::Device descreve o objeto V2X anexado a um agente de simulação, ou seja, um veículo. O dispositivo é o objeto usado pelo Rules Engine para transmitir mensagens. Os métodos disponíveis para fazer isso são:

• addOneTimeMessage(message, channel): Adiciona uma Message definida pelo usuário às mensagens que serão enviadas no próximo timestep.
• removeOneTimeMessage( message ): Remove todas as instâncias de uma mensagem definida pelo usuário da lista de mensagens que serão enviadas no próximo timestep.
• removeOneTimeMessage( message, channel ): Remover as instâncias de mensagem definida pelo usuário em um canal especificado.
• clearOneTimeMessages(): Remoção de todas as mensagens definidas pelo usuário do m

Observe que o método generateMessages deve ser chamado antes destes métodos ou a ação falhará.

V2X::Message ¶

Esta é uma classe de modelo para mensagens V2X. Embora vários tipos de mensagens padronizados sejam fornecidos no V2X SDK, muitas aplicações inovadoras exigirão que novos tipos de mensagens sejam criados. Dentro do V2X SDK, isso é feito criando uma nova classe que herda da classe V2X::Message.

A seguir há um exemplo de uma nova classe de mensagem que herda a classe V2X::Message.

class MYV2XFRAMEWORKEXPORT MyMessage : public V2X::Message
{
    public:
    MyMessage();  // Constructor
    ~MyMessage(); // Destructor

    // Message Type
    virtual messType getType() const override { return eCustom; }

    // housekeeping methods
    virtual V2X::Message * copy() const override;
    virtual void print() const override;
    virtual quint32 getSize() const override;

    // Get data as a copy. a constant or a pointer 
    MyData getCopyData() const { return mData;}
    const MyData & getData() const { return mData; }
    MyData & data() {return mData;}
private:
    MyData mData;
};

Na inicialização de V2X::MyFramework, esta mensagem é incluída na lista apresentada na interface do usuário no método de configuração chamando:

V2X::Framework::registerMessage("MyMessageName", "Message Description");

O código então implementado para enviar a mensagem no método performActions do Rules Engine deve:

1. Criar a mensagem.
2. Preencha a estrutura MyData.
3. Adicione a mensagem aos canais nos quais ela deve ser enviada

Isso é mostrado no código de exemplo da classe V2X::MyRulesEngine acima.

Fluxo de trabalho¶

O fluxo de trabalho consolidado é, portanto:

• Na Inicialização, no método de configuração V2X::MyFramework:

  • Crie tipos de mensagem e registre-os com a GUI.
  • Crie mecanismos de regras para dispositivos.

• Em cada passo de tempo para o Framework:

  • Use os métodos de callback preUpdate e postUpdate para gerenciar o V2X Framework.

• Para cada veículo

  • Inicialize seus dados V2X quando ele entra na rede de tráfego ao ser gerado.
  • Encerre sua atividade V2X quando ele sair da rede de tráfego ao final da viagem.

• Em cada timestep para todos os agentes com dispositivos V2X ativos:

  • O callback evaluate é chamado antes da execução do timestep.
  • O callback performActions é chamado após a execução do intervalo de tempo.

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