Introdução
Nesta aula prática você irá programar funcionalidades de cinemática de robôs móveis terrestres em ambiente simulado.
Os códigos serão escritos em Python, ilustrando-se assim então como configurar um ambiente pyenv e venv em sua máquina, para executar o python de forma isolada e auto-contida.
Por que pyenv + venv?
Em projetos de robótica é comum que diferentes máquinas (e.g., a sua, a do laboratório, a do robô) tenham diferentes versões do Python instaladas pelo sistema operacional, muitas vezes desatualizadas ou compartilhadas com outros programas.
Neste contexto, instalar bibliotecas diretamente nessa instalação global é arriscado, uma vez que diferentes códigos python que você executa podem depender de versões diferentes e python e/ou módulos (e.g., numpy, matplotlib, etc.).
Neste cenário, o pyenv resolve a primeira parte do problema uma vez que ele instala e gerencia múltiplas versões do Python lado a lado na mesma máquina, sem depender da versão que veio com o sistema operacional.
Assim, o pyenv viabiliza a granularidade de Python, permitindo escolher e executar, de forma simplificada, uma versão específica de Python para cada código.
Já o venv, que é um módulo padrão do próprio Python, resolve a segunda parte do problema ao permitir a criação de um ambiente virtual, chamado venv.
Cada ambiente venv é uma pasta isolada com sua própria cópia do interpretador e suas próprias bibliotecas.
Assim, ao se utilizar o venv, as dependências de um projeto nunca colidem com as de outro.
Juntos, eles garantem que o ambiente de programação em Python que você configurar hoje será reprodutível, ou seja, executável em qualquer outra máquina desde que as mesmas versões de Python e módulos lá também sejam instalados.
Nota
Esta aula assume que você já tem acesso a um terminal (Terminal no Linux/macOS, PowerShell/
cmd no Windows) e permissão para instalar programas na sua máquina.Pyenv - Utilização básica
Esta seção descreve o processo de instalação e usabilidade básica do pyenv.
Instalando o pyenv
O processo de instalação do pyenv muda de acordo com o sistema operacional. Siga apenas a seção correspondente ao seu SO abaixo.
Linux (Debian-based)
No Linux, a forma mais simples é usar o instalador automático do próprio projeto pyenv, que baixa o pyenv e os plugins mais usados (como o pyenv-virtualenv).
Primeiro, instale as dependências de compilação que o pyenv usa para construir cada versão do Python a partir do código-fonte:
bash
sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev curl git libncursesw5-dev xz-utils \
tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
Em seguida, rode o instalador do pyenv:
bash
curl -fsSL https://pyenv.run | bash
Agora, devemos adicionar o pyenv ao seu shell para que ele seja automaticamente carregado toda vez que você abrir um novo terminal. Se você usa Bash, abra o arquivo
~/.bashrc (e.g. nano ~/.bashrc) e adicione ao seu final as seguintes linhas:bash
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
Se você usa Zsh, faça o mesmo no
~/.zshrc, tendo apenas a última linha modificado de acordo para o zsh:bash
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
Atenção
Depois de editar o arquivo de configuração do shell, feche e abra o terminal novamente (ou rode
source ~/.bashrc / source ~/.zshrc) para que as mudanças tenham efeito.macOS
No macOS, a forma recomendada é instalar o pyenv via Homebrew. Se você ainda não tem o Homebrew instalado, instale-o primeiro seguindo as instruções do site oficial.
bash
brew update
brew install pyenv
Adicione o pyenv ao seu shell. A maioria dos Macs recentes usa Zsh por padrão — acrescente ao final do
~/.zshrc:bash
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
Depois, feche e abra o terminal novamente (ou rode
source ~/.zshrc).Windows
O pyenv original não roda nativamente no Windows. Para Windows, usamos o pyenv-win, um projeto irmão com a mesma interface de linha de comando. Os comandos abaixo devem ser executados no PowerShell.
powershell
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
Atenção
Se o PowerShell bloquear a execução do script com um erro sobre "execution policy", abra o PowerShell como administrador e rode
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser antes de tentar novamente.O instalador já configura as variáveis de ambiente necessárias, mas elas só têm efeito em uma nova janela do PowerShell. Feche a janela atual e abra uma nova antes de continuar.
Verificando a instalação do pyenv
Em qualquer sistema operacional, confirme que o pyenv foi reconhecido pelo terminal:
bash
pyenv --version
É esperado que o terminal mostre a versão atual do pyenv, o que confirma sua correta instalação.
Se o comando não for reconhecido, revise o passo de configuração do shell (ou reinicie o terminal) antes de prosseguir.
Instalando uma versão do Python
Com o pyenv funcionando, é possível instalar uma versão específica de python utilizando o comando
install. Por exemplo, para instalar a versão 3.13.4 do Python, rode:bash
pyenv install 3.13.4
Dica
A instalação compila o Python a partir do código-fonte e pode levar alguns minutos — isso é esperado, principalmente na primeira vez.
Uma vez instalada, você pode definí-la como sendo a versão a ser utilizada por um projeto em específico ao navegar para sua pasta e executar o seguinte comando:
bash
cd <pasta-do-projeto>
pyenv local 3.13.4
O comando
pyenv local cria um arquivo .python-version na pasta, de maneira que o pyenv lê este arquivo e automaticamente troca a versão do Python para a que está definida neste arquivo.É possível também definir alguma versão específica de Python thon para ser utilizada como a global do sistema (havendo override somente se alguma pasta tiver sido definida com uma versão em específico):
bash
pyenv global 3.13.4
Criando o ambiente virtual com venv
Com a versão correta do Python ativa na pasta do projeto, o próximo passo é criar o ambiente virtual.
Esta pasta vai armazenar todas as bibliotecas que instalarmos para o código de exemplo desta aula (i.e., utilizando o gerenciador de pacotes
pip), de forma isolada em relação do resto do sistema operacional, .Linux e macOS
bash
# na pasta do projeto
python -m venv .venv
source .venv/bin/activate
Windows (PowerShell)
powershell
# na pasta do projeto
python -m venv .venv
.venv\Scripts\Activate.ps1
Atenção
Se o PowerShell recusar a ativação com um erro de "execution policy" (o mesmo problema da instalação do pyenv-win), rode
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser em um PowerShell aberto como administrador.Em qualquer sistema operacional, o ambiente ativo aparece indicado entre parênteses no início da linha do terminal, por exemplo
(.venv). Esse indicador confirma que os pacotes que você instalar a partir de agora, com pip install, ficarão isolados nesta pasta, não afetando assim o Python do restante da sua máquina.Para sair do ambiente virtual a qualquer momento, digite:
bash
deactivate
O exercício: simulador do robô diferencial
O exercício desta aula parte de um simulador já pronto de um robô móvel diferencial — o mesmo robô modelado em . Ao executá-lo, você verá uma janela com a vista de cima de um robô sobre o plano, com o sistema de coordenadas
O simulador, porém, está incompleto de propósito: as duas funções que fazem a cinemática funcionar estão vazias, e implementá-las é o exercício. Enquanto elas não forem escritas, o programa abre normalmente, mas o robô não sai do lugar.
O que o simulador faz é fechar o ciclo entre o que você calcula e o que "acontece de verdade". Os comandos que você envia pelos sliders passam pela sua função, viram velocidades de roda, e essas velocidades são aplicadas a um robô simulado que é integrado internamente com precisão. O programa então desenha, lado a lado, a trajetória que o robô realmente percorreu e a trajetória que a sua odometria calculou.
O que você vai implementar
Todo o exercício está em um único arquivo,
funcoesAImplementar.py. Ele define duas funções, ambas ainda vazias, e nenhum outro arquivo do projeto precisa ser modificado.python
def calculaVelAngularRodas(velLinearDesejada, velAngularDesejada,
raioRoda, distanciaRodas):
"""Recebe as velocidades linear e angular desejadas para o chassi e
devolve (omegaEsq, omegaDir), as velocidades angulares das rodas."""
...
def integraEstadoRobo(omegaEsq, omegaDir, estadoAtual, deltaT,
raioRoda, distanciaRodas):
"""Recebe as velocidades angulares aplicadas pelas rodas, o estado
(x, y, theta) atual do robô e o intervalo de amostragem, e devolve o
próximo estado (x, y, theta)."""
...
A primeira é a cinemática inversa do robô diferencial: dado o que se quer do chassi, quanto cada roda precisa girar. A segunda é a odometria discreta: dado o que as rodas fizeram durante um intervalo
Nota
As convenções são exatamente as da aula teórica: a origem de
Baixando o código
O código do exercício está publicado em um repositório no GitHub. A forma recomendada de obtê-lo é clonando o repositório com o
git, o que facilita receber correções e atualizações depois.Repositório do exercício no GitHub
Código de apoio da aula: simulador do robô diferencial em Python.
bash
git clone https://github.com/profilgusto/robotica-cinematica-robos-moveis-terrestres.git
cd robotica-cinematica-robos-moveis-terrestres
Dica
Se você ainda não tem o
git instalado, dá para baixar o código pelo próprio site do repositórioao. Para isto, clique no botão verde Code e escolha Download ZIP. Descompacte o arquivo e entre na pasta resultante pelo terminal.Preparando o ambiente do projeto
A pasta do repositório é o projeto desta aula, sendo nela que o
pyenv e o venv devem ser configurados, exatamente como você viu na seção anterior.Linux e macOS
bash
pyenv local 3.13.4
python --version
python -m venv .venv
source .venv/bin/activate
Windows (PowerShell)
powershell
pyenv local 3.13.4
python --version
python -m venv .venv
.venv\Scripts\Activate.ps1
Atenção
Antes de seguir, confirme que o
(.venv) aparece no início da linha do terminal e que python --version responde 3.13.4. Instalar as dependências com o ambiente desativado joga os pacotes no Python do sistema.Instalando as dependências
As bibliotecas de que o projeto precisa estão listadas no arquivo
requirements.txt, na raiz do repositório. Esse arquivo é a forma padrão de declarar dependências em Python: cada linha nomeia um pacote e, opcionalmente, a faixa de versões aceita. Instalá-lo de uma vez é o que garante que todo mundo da turma acabe com o mesmo conjunto de bibliotecas.Neste projeto há uma única dependência, o PyQt6 — o binding Python da biblioteca Qt, usada aqui para desenhar a janela do simulador, os sliders e a vista de cima do robô.
bash
pip install -r requirements.txt
Se preferir instalar o pacote explicitamente, sem passar pelo arquivo, o comando equivalente é:
bash
pip install PyQt6
Dica
Para conferir o que foi instalado no ambiente, rode
pip list. O PyQt6 deve aparecer na lista, junto com as bibliotecas de que ele próprio depende (PyQt6-Qt6 e PyQt6-sip).Executando o simulador
Com o ambiente ativo e as dependências instaladas, execute o programa a partir da raiz do repositório:
bash
python main.py
Uma janela deve abrir com o robô no centro do plano e, na barra inferior, uma mensagem em vermelho avisando que
calculaVelAngularRodas ainda não foi implementada (pois esta é a sua tarefa).
Sempre que você editar o código de
funcoesAImplementar.py e salvar este arquivo, clique na interface no botão Recarregar funcoesAImplementar.py para carregar seu conteúdo na execução da interface a fim de verificar se o código implementado está funcionando como esperado.Atenção
Se o comando falhar com
ModuleNotFoundError: No module named 'PyQt6', o ambiente virtual provavelmente não está ativo. Reative-o (source .venv/bin/activate ou .venv\Scripts\Activate.ps1) e repita a instalação das dependências.Roteiro de implementações
Exercício 2·Implemente e valide a cinemática inversa
Implemente
calculaVelAngularRodas e verifique o seu resultado no painel Leituras do simulador: mova os dois sliders por toda a faixa e compare as colunas desejado e executado das linhas Parta da equação do modelo cinemático do robô diferencial e isole
Se a implementação estiver correta, as duas colunas coincidem em toda a faixa dos sliders: a sua cinemática inversa é exatamente a inversa da cinemática direta que o robô simulado usa. Um teste adicional útil é pedir
Exercício 3·Implemente a odometria e meça o erro de integração
Implemente
integraEstadoRobo e observe as duas trajetórias desenhadas na tela. Depois, com um comando de curva ativo, varie o São dois passos: primeiro o modelo cinemático leva das rodas às velocidades do chassi expressas em
O erro de posição cresce com o