Programação do SDK V2X da Aimsun Next¶

Introdução¶

O Kit de Desenvolvimento de Software (SDK) V2X foi projetado para permitir que um modelador acesse a estrutura central V2X no Aimsun Next para implementar VANets de veículos conectados dentro de uma simulação. Um VAnet é uma rede efêmera criada espontaneamente por um grupo de veículos conectados próximos uns dos outros. Os VANets são formados à medida que os veículos detectam transmissões de outros veículos e, enquanto estão dentro do alcance um do outro, eles podem trocar informações sobre sua localização e atividade. Ao agregar essas informações, um veículo é capaz de inferir o padrão do tráfego ao seu redor e, assim, ajustar seu próprio comportamento de acordo.

Um VAnet também pode incluir uma estação sem fio estática em uma Unidade de Rua (RSU), de fato, uma parte da infraestrutura de gestão da rede viária. Incluir uma RSU fixa a localização de um VAnet e lhe dá uma presença permanente; seus membros tornam-se então os veículos conectados na área adjacente. Se essa RSU estiver conectada ao Sistema de Gestão de Tráfego (TMC), 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 é projetada para adicionar simulação de comunicação a um modelo de tráfego dinâmico e simular a passagem de mensagens entre veículos conectados em uma 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 SDK V2X para coletar essas mensagens e usá-las para modificar o comportamento do veículo. Dentro de cada RSU, o modelador igualmente coletará mensagens de veículos dentro do alcance dessa RSU e processará localmente ou as retransmitirá para um TMC central que pode derivar um conjunto coordenado de respostas de gestão a serem retransmitidas aos veículos via a estrutura V2X, ou por mecanismos ITS convencionais.

A estrutura V2X é, portanto, destinada a permitir a simulação de comportamentos colaborativos entre veículos e também comportamentos coordenados por meio de controles de centro de gestão baseados em um rico fluxo de dados de veículos conectados e unidades de infraestrutura ITS em rodovias.

Programação do SDK V2X¶

O SDK V2X difere da programação funcional usada na maioria da API do Aimsun Next. Ele utiliza conceitos de programação orientada a objetos para permitir que o programador desenvolva novas classes para objetos como Mensagens e Motores de Regras baseados em classes de modelo. Um programador utilizando o SDK V2X deve estar familiarizado com esses conceitos em C++.

Herança de Classe Orientada a Objetos¶

Um dos conceitos-chave utilizados no SDK V2X é 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 da classe 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 da V2X::Message e cada uma adiciona a ela os métodos e dados específicos desse tipo de mensagem.

Herança da Classe 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 de configuração chamado quando a classe V2X::MyFramework é carregada no momento da inicialização e registrada com a Estrutura V2X dentro do Aimsun Next.

Quando em uso, mensagens do tipo V2X::MyMessage são passadas entre dispositivos da mesma maneira que outros tipos de mensagens. Isso ocorre porque os algoritmos de passagem de mensagens lidam com objetos da classe V2X::Message e, portanto, lidam automaticamente com todos os tipos de mensagens que herdam essa classe modelo. Assim, não há trabalho extra necessário no núcleo do sistema V2X para permitir que novos tipos de mensagens sejam distribuídos.

Componentes V2X ¶

Os componentes da Estrutura V2X são descritos na Seção da Interface do Usuário V2X onde são criados e editados. Os componentes são:

Tipo de Mensagem: Os tipos de mensagens passadas entre veículos e os RSUs.
Canal: O canal de comunicação é a representação simulada do hardware de rádio e protocolos que fornecem comunicações entre veículos.
Unidade a Bordo: A OBU fornece o receptor e transmissor em um veículo.
Unidade de Rua (RSU): A RSU é o componente "I" da rede de comunicação Veículo para Infraestrutura (V2I). É um dispositivo de rua com uma localização especificada e também pode estar vinculado a um cruzamento ou a vários cruzamentos.
Centro de Gestão de Tráfego: O Centro de Gestão de Tráfego é o integrador dos dados de várias RSUs e o iniciador do controle coordenado de sinais e ações de gestão de tráfego, bem como de desencadear mensagens V2X a serem transmitidas das RSUs.

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

Nos casos simples, onde os tipos de mensagens são aqueles já fornecidos na estrutura V2X e as características do canal representam adequadamente o alcance da transmissão, latência e perdas de pacotes, o único código da API a ser escrito é um mecanismo de regras para aqueles objetos com comportamentos alterados.

Instalação ¶

O SDK V2X é instalado em duas etapas:

A Estrutura V2X, que instala o plug-in no Aimsun Next. Deve ser instalada na pasta onde você instalou o Aimsun Next 24.
O SDK V2X, que instala a documentação do usuário, as bibliotecas e arquivos de cabeçalho do SDK V2X e, no diretório /include/aimsun_extensions/v2x/samples, um exemplo de projeto do SDK V2X. Deve ser instalado em uma pasta com permissões de escrita.

Entre em contato com a Aimsun para solicitar os dois instaladores 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. Para esclarecimento, o Qt está disponível como uma versão open-source gratuita.
Adicionar o complemento Qt VS Tools para o Visual Studio, que precisa ser instalado a partir do Visual Studio como uma extensão (no Visual Studio, clique em ‘Extensões’ > ‘Online’ > Pesquisar por ‘Qt’ > Instalar ‘Qt Visual Studio Tools’)

Configurando ¶

Certifique-se de ter instalado tanto a Estrutura V2X quanto o SDK V2X, bem como todos os requisitos anteriores.
Acesse a pasta ‘StopEngine’ localizada dentro da pasta de instalação do SDK V2X da seguinte forma: ‘/include/aimsun_extensions/v2x/samples/StopEngine’
Inicie o Visual Studio e configure as ferramentas Qt VS clicando em ‘Extensões’ > ‘Qt VS Tools’ > ‘Opções Qt’. Na janela de Opções Qt, selecione a instalação de Qt apropriada.
Abra o arquivo do projeto clicando em ‘Extensões’ > ‘Qt VS Tools’ > ‘Abrir Arquivo de Projeto Qt’. Selecione o arquivo StopEngine.pro e compile como faria normalmente.
Uma vez finalizado, copie o DLL gerado junto com o arquivo StopEngine.xml e coloque-os dentro de ‘/Aimsun Next 24/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 do V2X e verifique se tudo está configurado conforme o esperado.

Documentação da Classe ¶

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

Documentação Gerada pelo Doxygen

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

Classes V2X ¶

As classes principais utilizadas 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 modelo para gerenciamento de projetos V2X. O programador deve criar uma especialização desta para formar uma classe V2X:MyFramework baseada nesta classe modelo. A nova classe deve fornecer a função de configuração para inicializar o sistema V2X quando a biblioteca programada é carregada, e uma função destrutora que é executada no final da simulação para fechar quaisquer links externos e gerar quaisquer dados resumidos quando o objeto V2X::MyFramework é destruído.

Método de Configuração¶

O método de configuração para a estrutura é chamado pelo método construtor. Ele é utilizado para:

Criar e registrar novos tipos de mensagens
Adicionar atributos aos veículos ou unidades de rua para permitir que eles mantenham informações sobre sua atividade V2X.
Criar e registrar novos tipos de canais de comunicação com mais, ou diferente, funcionalidade do que o tipo padrão.

Novas mensagens e novos canais serão adicionados à lista apresentada no 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 etapa da simulação.
postUpdate: Chamado no final de cada etapa da simulação.

Esses quatro métodos são chamados em eventos significativos na simulação: à medida que os veículos entram e saem, e antes e depois de cada passo de tempo. As ações tipicamente seriam:

Em evento de novo veículo:
- Configurar quaisquer dados de inicialização para o mecanismo de regras que controlará o novo veículo.
Em evento de veículo saindo:
- Registrar quaisquer dados cumulativos sobre a atividade relacionada ao V2X para aquele veículo.
No preUpdate, coletar dados que possam ser relevantes para as comunicações V2X:
- Dados de outros sistemas ITS operando na simulação.
- Status da rede, indiferindo os dados disponíveis em um centro de controle de tráfego
No postUpdate, realizar quaisquer ações determinadas utilizando dados V2X:
- Fornecer informações a outros sistemas ITS operando na simulação.

Método de Obtenção do Mecanismo de Regras¶

O Método GetRulesEngine é chamado pelo método init da classe V2X::Framework e é utilizado 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"){
        // um OBU de um tipo específico
        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;
    }

Isso cria o link pelo qual a simulação pode chamar os callbacks do Mecanismo de Regras para entregar as V2X::Messages.

V2X::RulesEngine ¶

A classe V2X::RulesEngine é a classe modelo para um Mecanismo de Regras. 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 dispositivos 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 Mecanismo de Regras tem dois métodos principais:

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

Esses métodos são chamados em 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 (ou seja, o veículo) que o dispositivo está associado. Por exemplo, isso pode ser o último tempo de transmissão ou o último estado transmitido, de modo que a transmissão só possa ser feita após uma alteração 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){
            //Obter os dados e o dispositivo
            const auto & data = cMessage->getData();
            auto agent = mDevice->agent();
            // compilar os dados
            agent->addToKnowledge(data->mydata);
        }
    }
}

Um exemplo de um método performActions que executa ações relacionadas ao V2X em 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 com o id do veículo
        agent->instantaction();
    }

    //criação e transmissão de mensagens personalizadas a cada 10 segundos 
    int trunkTime = static_cast<int>(time);
    if ( trunkTime % 10 == 0 )
    {
        auto message = std::make_shared<MyMessage>();
        auto & data = message->data();
        fillmessage(data); // Encontrar o que queremos transmitir
        //selecionar canais e definir as mensagens a serem enviadas
        auto deviceChannels = mDevice->getChannels();
        for( auto channel : deviceChannels )
        {
             mDevice->addOneTimeMessage( message, channel->getId() );
        }
    }
}

V2X::Device ¶

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

addOneTimeMessage(message, channel): Adicionar uma Mensagem definida pelo usuário às mensagens que serão enviadas na próxima etapa de tempo.
removeOneTimeMessage( message ): Remover todas as instâncias de uma mensagem definida pelo usuário da lista de mensagens que serão enviadas na próxima etapa de tempo.
removeOneTimeMessage( message, channel ): Remover as instâncias de uma mensagem definida pelo usuário em um canal específico.
clearOneTimeMessages(): Remoção de todas as mensagens definidas pelo usuário de m

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

V2X::Message ¶

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

O seguinte é um exemplo de uma nova classe de mensagem que herda a classe V2X::Message.

class MYV2XFRAMEWORKEXPORT MyMessage : public V2X::Message
{
    public:
    MyMessage();  // Construtor
    ~MyMessage(); // Destrutor

    // Tipo de Mensagem
    virtual messType getType() const override { return eCustom; }

    // métodos de gerenciamento
    virtual V2X::Message * copy() const override;
    virtual void print() const override;
    virtual quint32 getSize() const override;

    // Obter dados como uma cópia, um constante ou um ponteiro 
    MyData getCopyData() const { return mData;}
    const MyData & getData() const { return mData; }
    MyData & data() {return mData;}
private:
    MyData mData;
};

Na inicialização do 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", "Descrição da Mensagem");

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

Criar a mensagem.
Preencher a estrutura MyData.
Adicionar a mensagem aos canais nos quais ela deve ser enviada

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

Fluxo de Trabalho ¶

O fluxo de trabalho consolidado é, portanto:

Na Inicialização, no método de configuração do V2X::MyFramework:
- Criar tipos de mensagem e registrá-los na GUI.
- Criar mecanismos de regras para dispositivos.
Em cada passo de tempo para a Estrutura:
- Usar os métodos de callback preUpdate e postUpdate para gerenciar a Estrutura V2X.
Para cada veículo
- Inicializar seus dados V2X ao entrar na rede de tráfego quando é gerado.
- Fechar sua atividade V2X ao sair da rede de tráfego ao final de sua viagem.
Em cada passo de tempo para todos os agentes com dispositivos V2X ativos:
- O callback evaluate é chamado antes da execução do passo de tempo.
- O callback performActions é chamado após a execução do passo de tempo.