TechIEEE

UTILIZAÇÃO DA
API REMOTA DO
COPPELIASIM

Leandro Carvalho Santana & Marvim Vinicius Souza de Souza

ThechIEEE
Julho, 2020
INTRODUÇÃO

O CoppeliaSim é um software de simulação de robôs terrestres, aquáticos e aéreos

desenvolvido pela empresa CoppeliaSim Robotics. Ele possui ambiente de
desenvolvimento integrado, baseado em uma arquitetura de controle distribuído: cada
objeto/modelo pode ser controlado individualmente através de um script. Os controladores
podem ser escritos em C/C++, Python, Java, Lua, Matlab ou Octave.
A API remota (em inglês, Remote API) é uma das maneiras de controlar a
simulação e consequentemente os robôs contidos nela.
Com o intuito de orientar acerca da utilização da API remota no CoppeliaSim, este
documento pretende descrever a ferramenta, apresentar suas características e
demonstrar como habilita-la.
API REMOTA DO COPPELIASIM

1. Sobre API Remota

O API Remota faz parte do CoppeliaSim API framework. Ele permite a
comunicação entre o CoppeliaSim e uma aplicação ou hardware externo (por exemplo,
aplicativo em execução em um processo diferente ou em uma máquina diferente), é
multiplataforma e suporta chamadas de serviço (execução de tarefas) e fluxos de dados
bidirecionais.
A API Remota possui duas versões/frameworks distintos (As versões não podem
ser misturadas): API remota baseada em B0 e API remota Legacy.

2. API remota baseada em B0:

Esta é a segunda versão da API remota. Ela é baseada no BlueZero middleware e
é uma interface de plugin para o CoppeliaSim. È mais fácil e mais flexível de usar que o
Legacy, é mais fácil de expandir (criar novas função que não são nativas do remote).
Atualmente suporta C++, Java, Python, Matlab e Lua.
O BØ é um middleware (software que se encontra entre o sistema operacional e os
aplicativos nele executados) multiplataforma que fornece ferramentas para interconectar
partes de software executadas em múltiplos threads, múltiplos processos e até múltiplas
máquinas.

3. Legacy API remota (ou simplesmente API remota):

É a primeira versão da API remota, ele é mais leve e tem menos dependências que
o baseado em B0. Contudo, é menos intuitivo, menos flexível e mais difícil de expandir.
Suporta C/C++, Java, Python, Matlab, Octave e Lua.
É a versão utilizada pelo TechIEEE, no momento, as linguagens de Python e C++,
estão sendo utilizadas.
As funções da API remota interagem com o CoppeliaSim por meio de comunicação
via soquete (ou, opcionalmente, por memória compartilhada). Tudo isso acontece de
forma oculta para o usuário. A API remota pode permitir que uma ou mais aplicações
externas interajam com o CoppeliaSim de maneira sincronizada ou não sincronizada (não
sincronizada por padrão), e ainda possibilita controlar remotamente o simulador (por
exemplo, carregar uma cena, iniciar, pausar ou parar uma simulação).
A funcionalidade da API remota se baseia na comunicação entre duas entidades,
que interagem via soquete:
 O client (aplicação externa): A API remota no lado cliente está disponível para
várias linguagens de programação diferentes.
  O Sever (CoppeliaSim): a API remota no lado do servidor é implementada por meio
de um plug-in carregado pelo CoppeliaSim por padrão: simExtRemoteApi.dll,
libsimExtRemoteApi.dylib ou libsimExtRemoteApi.so.

4. Características das Funções da API remota

Uma função API remota é chamada de maneira similar à uma função da API
regular (dentro do CoppeliaSim), no entanto, com duas grandes diferenças:
 As funções retornam um valor, um “código de retorno”, este serve para informar ao
remote o status do retorno: se a função foi executada ou se houve erro e qual o
tipo de erro, por exemplo.
 As funções da API remota precisam de dois argumentos adicionais: O ClientID e o
modo de Operação.

Figura 1 - Características das funções

As variáveis “err_codel” e “l_motor_handle” foram definidas para mostrar o código

de erro e o identificador do objeto motor, respectivamente. O clientID é identificado na
função “simxStart”, onde se coloca como argumento a identificação do servidor e a porta
de acesso ao CoppeliaSim. Já o modo de operação “simx_opmode_bloking” é explicado
no tópico seguinte.

a. Modo de operação
O modo de operação se refere ao mecanismo para executar as chamadas de
função e como a simulação avançará. Os mecanismos principais são:
 Chamadas de funções de bloqueio (“simx_opmode_bloking”): é a chamada regular,
em que há a devolução de um dado.
 Chamadas de função de não bloqueio (“simx_opmode_oneshot”): Chamada na
qual simplesmente queremos enviar dados ao CoppeliaSim, sem a necessidade de
resposta.
 Fluxo de dados (“simx_opmode_striming”): Quando se quer um fornecimento
constante do valor, sem a necessidade de requisição repetitiva do lado do client.
 Operação síncrona: Nos outros modos a simulação avança independente do
progresso da API remota. Por padrão, as funções remotas são assíncronas. Esta é
a única, das quatro, que é ativada através de função, a “simxSynchronous()”. A
simulação avançará somente se “simxSynchronousTrigger()” for chamada.
Existem outros modos, mas estes são os considerados principais, de acordo com o
manual do CoppeliaSim. É importante salientar que cada função possui um modo de
operação recomendado, e estes são indicados no manual do software.
 b. Código de retorno
O código de retorno representa o status de retorno da função, se esta funcionou
corretamente, ou se não, onde está o erro. Pode-se observar todos os tipos de código de
retorno, e sua representação na tabela 1, a seguir:

Tabela 1 - Tipos de Código de Retorno

5. Habilitando a API remota no Lado do Servidor (CoppeliaSim)

Existem duas maneiras de se habilitar a API Remota:
A primeira é na inicialização do CoppeliaSim (serviço de servidor do API remoto
contínuo). O plug-in de API remota tentará ler um arquivo de configuração chamado
remoteApiConnections.txt e, de acordo com seu conteúdo, iniciará os serviços de servidor
apropriados. Com esse método, as funções remotas da API sempre serão executadas no
lado do servidor, mesmo que a simulação não esteja em execução (o que nem sempre é
o caso do próximo método).
 A segunda maneira é habilitar dentro de um script (serviço de servidor API remoto
temporário). Esse é o método preferido na maioria das vezes para iniciar um serviço de
servidor da API remota. O usuário está no controle quando o serviço é iniciado ou parado.
Quando um serviço de servidor de API remota temporário é iniciado a partir de um script
de simulação, no entanto, o serviço será automaticamente parado no final da simulação.
Um serviço de servidor de API remota temporário pode ser iniciado ou interrompido com
as seguintes 2 funções Lua personalizadas: SimRemoteAPI.start e SimRemoteAPI.stop.

Figura 2 - Função em Lua para iniciar a API Remota

Na função em destaque, é definida a porta padrão para a conexão da API Remota

via soquete, a qual o cliente deve acessar para se conectar.
Pode-se ainda coletar informações sobre qualquer serviço de servidor API remoto
com a função “simRemoteApi.status” e redefinir (ou seja, interromper e recriar) através da
função “simRemoteApi.reset”.

6. Habilitando o API remota no Lado do Cliente (Aplicação Externa)

Cada linguagem possui seu método especifico para habilitar a comunicação da
aplicação com o servidor do CoppeliaSim, entretanto, percebe-se um ponto em comum a
todas as linguagens: é necessária a inclusão de arquivos específicos (bibliotecas) no
projeto (ou seja, pasta) onde a aplicação se encontra.
Os arquivos se encontram no diretório de instalação do CoppeliaSim, no caminho
“programming >> remoteApiBidings”, cada linguagem possui sua pasta, que, por sua vez,
contêm os respectivos arquivos necessários e um arquivo “ReadMe.txt” que contém
instruções sobre como proceder para realizar a habilitação no lado do cliente.
De forma mais específica, será tratado, a seguir, sobre a ativação da API remota
do lado do cliente com python, que é a linguagem majoritariamente usada pela equipe do
ThechIEEE, no momento.
a. Ativação da API remota do lado cliente com Python
Para ativar a API remota com python, primeiramente, é importante verificar se a
versão instalada é a de 64 bits, caso contrário, o CoppeliaSim não conectará com a API
remota.
Posteriormente, na pasta projeto, onde o script com os comandos para o robô será
alocado, deve-se incluir os arquivos “sim.py”, “simConst.py” e “remoteApi.dll” (para
sistema operacional Windows), “remoteApi.dylib” (para sistemas Mac) ou “remoteApi.so”
(para sistemas Linux).
Depois disso basta inserir no script a função "sim.simxStart()”, como mostra a
figura:

Figura 3 - Definindo o clientID no lado do cliente

Neste caso a variável ClientID está recebendo o retorno da função simxStart, que
basicamente faz uma conexão via soquete, ou seja, procura pela entidade na qual o
endereço de conexão seja “127.0.0.1” e a porta serial “19999”, o primeiro “True” informa
que se deve aguardar até conectar, o segundo “True” informa para que não haja tentativa
de reconexão uma vez desconectado, os outros 2 números estão relacionados aos
tempos dos frames da simulação.
Com estas etapas anteriores o script já poderá comunicar com o CoppeliaSim e as
funções podem ser chamadas normalmente, entretanto, é interessante manter a conexão,
de modo há executar funções várias vezes, para isso, basta inserir uma condição para
que o programa continue conectado enquanto a variável clientID for igual a “-1”, isso
significa que a conexão está ocorrendo e, enquanto isso for verdade, o programa estará
em execução, caso contrário o loop será interrompido.

Figura 4 - Loop para manter a API Remota conectada

Cumprindo estas etapas, o usuário poderá executar os comandos que achar

interessante para sua aplicação, utilizando-se das bibliotecas disponíveis no Python e na
API remota.
 CONSIDERAÇÕES FINAIS

Este documento apresentou a API remota, descreveu suas características e

demonstrou como esta pode ser habilitada tanto do lado do servidor como do cliente.
Este documento baseou-se no estudo do manual do próprio desenvolvedor do
CoppeliaSim, com intuito de orientar e fornecer uma abordagem geral e resumida. para
esclarecimentos mais específicos, recomenda-se consultar o manual do CoppeliaSim
presente no link: https://www.coppeliarobotics.com/helpFiles/index.html.