Visão Geral

O VSS-SDK é um projeto opensource que auxilia na construção de times de futebol de robôs. O SDK possui foco na categoria IEEE Very Small Size Soccer, presente na Competição Brasileira de Robótica (CBR) e na Competição Latino-Americana de Robótica (LARC).

Os projetos estão hospedados no Github, e possuem um Kanban no Trello e um Canal no Slack para que interessados possam trocar ideias sobre a categoria IEEE-VSS e discutir questões sobre o SDK.

• Instalação
• Utilização
• Desenvolvimento
• Arquivos Protos

VSS-Viewer plotando estados do VSS-Simulator e informaçoes de debug de uma estratégia.

O SDK é formado por 4 projetos e alguns exemplos. São esses:

• VSS-Vision - Sistema de visão computacional.
• VSS-Simulator - Simulador de partidas de futebol.
• VSS-Viewer - Visualizador de estados e debug.
• VSS-Joystick - Programa de controle de robôs via joysticks usb/bluetooth.
• VSS-Samples - Exemplos de estratégias.

Atualmente são suportados somente distribuições Linux, como: Ubuntu 14, Ubuntu 16, Ubuntu 18, Linux Mint 18 e Debian 9.

Os projetos do VSS-SDK estão sendo migrados para utilizar Ansible, pois o controle de dependências demonstrou-se complexo para diferentes distros. Por isso é necessário instalar o Ansible-Playbook.

Para instalar siga esse tutorial.

Inicialmente é necessário instalar o biblioteca VSS-Core. Para isso, abra um terminal e execute os comandos:

git clone https://github.com/VSS-SDK/VSS-Core
cd VSS-Core
sudo ./configure.sh

O script irá atualizar os pacotes do Linux e em seguida irá instalar as dependências necessárias para rodar o SDK. Por último, a biblioteca será compilada e instalada na sua distro.

Para instalar os outros projetos não existe ordem. Basta seguir os comandos.

git clone https://github.com/VSS-SDK/VSS-Vision
cd VSS-Vision
sudo ./configure.sh

git clone https://github.com/VSS-SDK/VSS-Simulator
cd VSS-Simulator
sudo ./configure.sh

git clone https://github.com/VSS-SDK/VSS-Viewer
cd VSS-Viewer
sudo ./configure.sh

git clone https://github.com/VSS-SDK/VSS-Joystick
cd VSS-Joystick
sudo ./configure.sh

Após instalar os projetos, para utilizá-los basta executar os comandos no terminal:

Obs: Todos os projetos possuem flags de execução, para listar essas flags basta executar os projetos com a flag -h.

vss-vision

vss-simulator

Flags de Execução

vss-viewer

Flags de Execução

vss-joystick

Flags de Execução

Todos os projetos foram desenvolvidos em C++, utilizando Cmake para compilação, Google Tests como framework de testes unitários, alguns shellscrips de configuração e Docker para realização de integração contínua na plataforma TravisCI.

Obs1: Os projetos não são instalados dessa forma, é necessário executar cada um em sua pasta build.

Obs2: Dentro da pasta build também será gerado um executável tests, com os testes unitários.

Para compilar os projetos em modo de desenvolvimento, com debug e testes unitários basta executar os comandos:

git clone https://github.com/VSS-SDK/VSS-Core
cd VSS-Core
sudo ./configure.sh development

git clone https://github.com/VSS-SDK/VSS-Vision
cd VSS-Vision
sudo ./configure.sh development

git clone https://github.com/VSS-SDK/VSS-Simulator
cd VSS-Simulator
sudo ./configure.sh development

git clone https://github.com/VSS-SDK/VSS-Viewer
cd VSS-Viewer
sudo ./configure.sh development

git clone https://github.com/VSS-SDK/VSS-Joystick
cd VSS-Joystick
sudo ./configure.sh development

Os arquivos protos carregam as definições de contrato entre os projetos. Caso exista necessidade de implementar a integração com o VSS-SDK em uma linguagem que não estenda C, é possível recriar as interfaces utilizando esses protocolos. Existem exemplos de utilização prontos em VSS-Samples.

package vss_state;

message Pose{
    required float x = 1;
    required float y = 2;
    optional float yaw = 3;
}

message Ball_State{
    required Pose pose = 1;
    optional Pose v_pose = 2;
}

message Robot_State{
    required Pose pose = 1;
    optional Pose v_pose = 2;
}

message Global_State{
    repeated Ball_State balls = 1;
    repeated Robot_State robots_yellow = 2;
    repeated Robot_State robots_blue = 3;
}

package vss_command;

message Robot_Command{
    required float left_vel = 1;
    required float right_vel = 2;
}

message Global_Commands{
    repeated Robot_Command robot_commands = 1;
}

package vss_debug;

message Pose{
    required float x = 1;
    required float y = 2;
    optional float yaw = 3;
}

message Path{
    repeated Pose poses = 1;
}

message Global_Debug{
    repeated Pose step_poses = 1;
    repeated Pose final_poses = 2;
    repeated Path paths = 3;
}

package vss_control;

message Pose{
    required float x = 1;
    required float y = 2;
    optional float yaw = 3;
}

message User_Control{
    optional bool paused = 1;
    optional Pose new_ball_pose = 2;
    repeated Pose new_robots_blue_pose = 3;
    repeated Pose new_robots_yellow_pose = 4;
}

VSS-Core

O VSS-Core é uma biblioteca com o núcleo compartilhado entre todos projetos do SDK. Ele é responsável por prover estruturas de dados comuns ao problema de futebol de robôs, constantes, enums, métodos úteis e as interfaces de comunicações via rede.

• Comunicação entre projetos
• Arquivos protos

O SDK possui um cuidado especial quanto a tempo de execução, pois, o problema de futebol de robôs é muito dinâmico. Para diminur ao máximo o overhead causado pela comunicação entre os projetos, são utilizados duas bibliotecas: Google Protocol Buffers (Protobuf) e ZeroMQ.

A biblioteca protobuf é responsável pela serialização dos dados que trafegam entre os projetos. Diferente de outros métodos de serialização, como: XML ou JSON. Protobuf gera um código seguro de serialização/deserialização específico para cada linguagem, dessa forma facilitando trabalho. Além disso, a biblioteca é conhecida por possuir menores tempo de serialização e de deserialização, o que corroborou na sua utilização.

A biblioteca ZeroMQ é responsável pela comunicação entre os projetos, sendo essa uma fila de mensagens. Cada pacote que trafega no projeto possui sua própria fila que pode possuir modelos unicast, multicast ou broadcast. Também podem existir comunicações TCP ou UDP.

Um exemplo de comunicação realizada pelo SDK são os pacotes de estados enviados pelo VSS-Vision e VSS-Simulator. Tais pacotes são enviados em broadcast e utilizam o protocolo UDP. O envio desses pacotes em broadcast possibilita que estratégias, o VSS-Viewer e outras eventuais aplicações consigam interpretar as mensages, além de não travar a execução do Sistema de Visão Computacional e do Simulador.

Foram idealizados quatro pacotes de comunicação entre os projetos que possuem responsabilidades diferentes. Suas definições podem ser encontradas nos arquivos protos e exemplos de utilização podem ser encontrados nos VSS-Samples.

O pacote de estado carrega informações das posições e orientações de todos os objetos em campo, ele pode ser enviado pelo VSS-Vision e pelo VSS-Simulator, e o projeto VSS-Viewer está configurado para automáticamente interpretar mensagem de ambos os projetos. O conteúdo do pacote pode ser visto na seção de state nos arquivos protos e o mesmo por padrão trafega na porta 5555.

O pacote de comando carrega informações das velocidades das rodas dos robôs de um time. Cada time envia um pacote desse para o VSS-Simulator, por padrão o time amarelo utiliza a porta 5556 e o time azul utiliza a porta 5557. O projeto VSS-Joystick utiliza o mesmo pacote nas mesmas portas para controlar robôs. O conteúdo do pacote pode ser visto na seção de command.

O pacote de depuração carrega informações que podem ser plotadas no VSS-Viewer, como, pose objetivo, vetor de movimento e caminhos. Por padrão é utilizado a porta 5558 para envio de debug pelo time amarelo e a porta 5559 é utilizada pelo time azul. O conteúdo do pacote pode ser visto na seção de debug.

O pacote de controle é exclusivamente enviado pelo VSS-Viewer para o VSS-Simulator e serve para iniciar e pausar a simulação. O conteúdo do pacote pode ser visto na seção de control.

VSS-Simulator

O VSS-Simulator é o simulador de partidas de futebol para a categoria IEEE Very Small Size Soccer. O projeto fornece um mundo 3D feito utilizando a biblioteca Bullet Physics, onde os objetos colidem e possuem restrições cinemáticas e dinâmicas. Há também um árbitro que detecta gols e reposiciona os objetos em campo, fazendo o jogo prosseguir.

O VSS-Simulator e o VSS-Vision possuem o mesmo papel de enviar pacotes de estados em broadcast, que podem ser obtidos pelo VSS-Viewer e por estratégias.

É necessário utilizar o VSS-Viewer para iniciar as simulações no VSS-Simulator, é possível pausar partidas e alterar a posição e orientação dos robôs e da bola em campo.

É possível configurar uma partida para nunca terminar, terminar quando passar 10 minutos de jogo ou terminar quando a diferença de gols entre dois times extrapolar uma certa quantidade. Tudo isso pode ser configurado com as flags de execução.

É possível aumentar a velocidade com que o tempo passa no simulador. Para configurar a aceleração basta utilizar as flags de execução.

Dimensões do campo de futebol da categoria IEEE VSSS

No simulador, o campo possui 1 metro e 70 centímetros de largura (contando a área de dentro do gol) e 1 metro e 30 centímetros de profundidade. A origem é em um canto (no canto superior esquerdo se for comparar com o VSS-Viewer). O ponto (0cm, 0cm) é fora do campo, devido a área do gol ser considerada no plano cartesiano. O centro do campo é no ponto (85cm, 65cm).

Os robôs possuem 8cm x 8cm x 8cm com um shape de um cubo. Atualmente estão sendo reunidos esforços para importar uma malha de triângulos para os robôs.

Todas as flags de execução que podem ser utilizadas no VSS-Simulator.

Options:
  -h [ --help ] 
  --ctrl_recv_addr arg (=tcp://localhost)
  --state_port arg (=5555)
  --yellow_cmd_port arg (=5556)
  --blue_cmd_port arg (=5557)
  --ctrl_port arg (=5560)
  --time_execution_type arg (=Normal)
  --match_finish_type arg (=TenGoalsDifference)
  --initial_position_path arg (=file.csv)

VSS-Viewer

O VSS-Viewer é um visualizador de estados de jogo, que também mostra informações de debug. O projeto permite que o usuário inicie e pause uma partida no VSS-Simulator com a possibilidade de mudar a posição dos robôs e da bola.

O VSS-Viewer está fortemente relacionado com o VSS-Simulator. Por padrão, uma partida não começa no VSS-Simulator até que o VSS-Viewer mande um pacote de controle. Para enviar esse pacote, basta teclar espaço no VSS-Viewer. Essa tecla pausa e retoma o jogo, sempre que necessário.

O VSS-Viewer recebe os pacotes de estado de jogo, ouvindo as mensagens do VSS-Simulator e do VSS-Vision.

Para manipular objetos em campo, antes é necessário pausar a partida (apertando a tecla espaço). Após isso, basta clicar com o botão esquerdo e arrastar os objetos. Para alterar a orientação de um robô, clique com o botão esquerdo em um, mantenha pressionado o clique, e utilize as setas (direita e esquerda) do teclado.

Robô (com padrão de cor azul e roxo) sendo manipulado.

Existem dois tipos de câmeras implementadas, uma que mostra o jogo pelo topo do campo e outra que mostra o jogo como se fosse uma transmissão de futebol. Para alterar a câmera basta teclar C, porém, apenas é possível realizar essa operação com o jogo não pausado.

Câmera de TV e câmera do topo.

Todas as flags de execução que podem ser utilizadas no VSS-Viewer.

Options:
  -h [ --help ] 
  --state_recv_addr arg (=tcp://localhost)
  --state_port arg (=5555)
  --yellow_debug_port arg (=5558)
  --blue_debug_port arg (=5559)
  --ctrl_port arg (=5560)

VSS-Joystick

Em construção...

Todas as flags de execução que podem ser utilizadas no VSS-Joystick.

Options:
  -h [ --help ] 
  --yellow_cmd_send_addr arg (=tcp://localhost)
  --blue_cmd_send_addr arg (=tcp://localhost)
  --yellow_cmd_port arg (=5556)
  --blue_cmd_port arg (=5557)
  --team_type arg (=Yellow)
  --environment_type arg (=Simulation)

É o responsável por capturar posições cartesianas dos robôs a partir da imagem da câmera. Utiliza a biblioteca de processamento de imagem opensource OpenCV. O VSS-Vision está dividido em dois módulos, um de calibragem, onde é possível calibrar cores, cortar e rotacionar a imagem. E um módulo de jogo, onde seta-se o padrão de cada robô, assim como a cor do time. A definição das posições dos robôs são realizadas a partir do rastreamento das cores calibradas. Ambos os módulos possuem a opção de trabalhar com imagens ou com uma câmera.

• Para calibrar as cores dos jogadores e da bola utiliza-se os sliders do HSV. Uma dica para facilitar é, deixe todos os máximos no máximo e todos os mínimos no mínimo desta forma estará pegando o range máximo do HSV e a imagem auxiliar ficara branca. Com isso comece mexendo no slider dos minimos na seguinte ordem, V min, S min, H min. Após mexe-se nos máximos para que apenas a cor desejada fique selecionada. Quando a cor estiver selecionada, ela ficará contornada por uma borda branca. Quando a cor já estiver quase calibrada faça pequenos ajustes em todos os sliders.

• Pressionando F1 você navega entre a imagem original e a imagem auxiliar de calibragem. A imagem auxiliar é uma binarização da imagem orinal a partir dos valores dos sliders do HSV. Esta imagem facilita a configuração das cores, pois nela, as cores na faixa desejada ficam completamente brancas, e as fora da faixa pretas.

• Para realizar o corte da imagem deve-se clicar no botão de corte de modo que ele fique pressionado, após clica-se apenas nos cantos do campo na seguinte ordem, canto superior esquerdo, canto superior direito, canto inferior esquerdo e canto inferior direito. Esses cantos estão relacionados com o que você está vendo na tela. Totalizando 4 pontos, que aparecerão vermelhos na tela, esta função ja irá cortar e rotacionar a imagem, através de uma transformação de perspectiva.

• A calibração gera um arquivo .txt, que pode ser acessado de qualquer lugar, ou seja, não necessita ficar armazenado em algum diretório específico (porém recomenda-se utilizar um de fácil acesso). Ele pode ser aberto novamente na calibração para editar o que foi feito, e é necessário para o funcionamento do Vision.

• A maior função do Vision é verificar se a leitura e captura de cores estão sendo feitas de maneira correta, para que as estratégias funcionem com os robôs corretos e suas devidas posições.

• Deve-se carregar a calibragem préviamente feita. Após seleciona-se a cor do time e o padrão dos robôs. Feito isso, as posições dos jogadores, bola e adversários estarâo aparacendo no canto direito da tela. As cores dos times ficam, assim como no Calibration, contornadas de branco, com a adição de um pequeno texto indicando a cor em questão (amarelo ou azul).

São utilizados tecnologias que possibilitam a construção de estratégias em várias linguagens. Atualmente, existem três exemplos de como realizar a comunicação com os projetos do VSS-SDK, um exemplo em C++, outro em Python e outro em Rust. No futuro serão adicionados mais exemplos.

• Ir para a documentação do VSS-SampleCpp
• Ir para o repositório do VSS-SamplePy
• Ir para o repositório do VSS-SampleRust