BeamNGpy e simulação veicular: roteiro de estudo para percepção antes da rua

O repositório vehicle_simulation_with_BeamNGpy está, neste momento, quase só com README — e este artigo trata isso com honestidade. Não há aqui inventário de experimentos concluídos, métricas de mAP, quilômetros simulados nem demo pronta. O que existe é um marcador de intenção e a necessidade de um roteiro de estudo: por que BeamNG.tech e a API Python BeamNGpy importam para quem trabalha percepção ADAS/AV antes de colocar protótipo na rua, e como isso se amarra à linha de TCC e embarcados com Jetson na Wilson Tecnologia.

O que o repo é (e o que ainda não é)

  • É: ponto de partida nomeado, alinhado a simulação veicular com BeamNGpy.
  • Não é (ainda): dataset versionado, nós ROS, pipelines de treino, nem integração contínua com o carro real.
  • Este texto: roadmap de estudo e justificativa técnica — para preencher o repo com trabalho real, não com narrativa inflada.

Essa franqueza evita o pior antipadrão de portfólio: README ambicioso + pasta vazia + métricas de blog. Prefira um plano executável.

Por que simular soft-body / dinâmica rica antes da rua

Simuladores “de vídeo-game leve” ensinam waypoint; ADAS exige contato com a física do veículo e do mundo:

  • Dinâmica de veículo. Transferência de peso, aderência, suspensão, falha de pneu — percepção sozinha não fecha o loop se o modelo de planta for mentiroso.
  • Cenários perigosos. Pedestre surgindo, perda de aderência, iluminação difícil: no simulador você itera sem risco a terceiros.
  • Repetibilidade. Mesmo seed/cenário para regressão de detector ou de planner — na rua, o mundo não repete o take.
  • Sensor synthetic. Câmera, LiDAR e radar aproximados no loop permitem testar pipeline de software; sempre com a ressalva de reality gap.

BeamNG.tech é conhecido pelo foco em simulação soft-body e danos, com uso consolidado em pesquisa e indústria de direção / ADAS em ambiente soft-real. BeamNGpy é a ponte Python: controle do simulador, telemetria, posicionamento de veículos, captura de sensores e automação de cenários a partir de scripts — o idioma natural de quem já prototipa visão e ML no ecossistema Jupyter/PyTorch e no Jetson.

Reality gap: a regra de ouro do roteiro

Tudo que você mede só no simulador é hipótese. Domínio simulado ≠ domínio da câmera barata no para-choque sob chuva de Sorocaba ou da rodovia. O roteiro de estudo deve prever:

  1. Cenários sintéticos para desenvolver e quebrar o software.
  2. Coleta real limitada e segura (estacionamento fechado, pista controlada) para calibrar expectativas.
  3. Nunca declarar “pronto para via pública” com base só em GIF de sim.

O reality gap não é só “imagem diferente”. Inclui latência de sensor, sync entre câmera e IMU, distorção de lente, compressão, vibração do suporte e o fato de que o detector treinado em textura de jogo falha em asfalto molhado com glare. Tratar o gap como item de risco no README do repo é maturidade; escondê-lo atrás de screenshot é marketing.

Roteiro de estudo em ondas (para popular o repo de verdade)

Onda A — Ambiente e “hello telemetria”

  • Instalar BeamNG.tech na máquina de lab (requisitos de GPU/OS conforme documentação oficial vigente — consulte o site/docs do produto; versões mudam).
  • Criar venv Python e instalar BeamNGpy na versão compatível com o build do jogo/simulador.
  • Script mínimo: lançar cenário, spawn de veículo, ler posição/velocidade, desligar limpo.
  • Commit no repo: examples/01_telemetry_hello.py + notas de versão pinada no README.

Onda B — Controle e laço fechado tosco

  • Enviar comandos de esterçamento/acelerador/freio via API.
  • Controlador PID didático de velocidade ou seguidor de trajetória simples em waypoints.
  • Log CSV de estado (t, x, y, yaw, v) — sem inventar KPI de paper.

Onda C — Sensores e percepção

  • Habilitar câmeras / LiDAR conforme suporte da versão BeamNGpy em uso.
  • Publicar frames para um nó local (pasta de imagens ou stub ROS2).
  • Rodar um detector já conhecido (ex.: modelo leve que você já usa na linha Jetson) só para validar o plumbing — não para reivindicar SOTA.
  • Documentar resolução, taxa alvo e limitações (latência de captura, sync).

Onda D — Cenários ADAS

  • Catalogar 5–10 situações: cut-in, pedestre, curva cega, noite, piso de baixa aderência (se o cenário/modelo permitir).
  • Cada cenário = script + README curto do que observa (não “score” inventado).
  • Integrar falhas proposital (sensor drop) e ver se o software degrada com modo seguro.

Onda E — Ponte TCC / Jetson

  • Mesma interface de mensagens (schema de telemetria / tópicos) entre sim e embarcado.
  • No Jetson: câmera real + inferência; no PC: BeamNGpy alimentando o mesmo código de decisão com flag SOURCE=SIM|REAL.
  • TCC ganha capítulo de método: o que foi validado em sim, o que falta em pista, riscos remanescentes.

Armadilhas de toolchain: BeamNG.tech + BeamNGpy + Python de lab

A API parece “só pip install”. O atrito real aparece na integração de versões e no ambiente gráfico.

Pin de versão simulador ↔ biblioteca. BeamNGpy e o build do BeamNG.tech andam de mãos dadas. Atualizar um sem o outro gera erro opaco na conexão ou método ausente. Hábito: no README, BeamNG.tech <build> + beamngpy==x.y.z + python -V. O mesmo rigor do XC8 1.45 no lab Fatec e do gcc-arm-none-eabi no apt.

GPU, driver e headless. Lab com GPU inadequada ou driver antigo falha no launch. “Headless” e captura de sensor dependem do que a versão documenta — não assuma que o que roda num desktop de jogos roda igual num servidor sem display. Anote a placa e o driver no diário; não invente FPS médio para o artigo.

venv versus system Python. Misturar BeamNGpy com pacotes globais do Jetson/notebook vira conflito de NumPy/OpenCV. venv (ou conda) por projeto; requirements pinados; nada de sudo pip.

Caminhos Windows/Linux. Exemplos oficiais e tutoriais misturam barras e paths de instalação. Script que hardcoda C:\... quebra no Linux do lab. Use configuração externa (env var ou YAML pequeno) para o diretório do usuário BeamNG.

Porta e processo zumbi. Simulador não fechou, API não reconecta, porta ocupada. O análogo industrial é o CLP em STOP com online preso. Procedimento: matar processo, relançar limpo, só então debugar o script. Documente o teardown no 01_telemetry_hello.py.

Clock e passo de simulação. Controlar veículo assumindo dt fixo sem ler o tempo de simulação gera PID “nervoso” ou “mole” conforme a carga da GPU. Logar timestamp do simulador no CSV evita achar que o software de controle está errado quando o frame time variou.

Dataset sem .gitignore. Dump de imagens e LiDAR enche o Git. Repo de estudo precisa de .gitignore agressivo e, se houver dataset, link/hash externo — não commit de dezenas de GB “para parecer completo”.

Licença. Uso acadêmico versus comercial do BeamNG.tech muda com os termos vigentes. Antes de qualquer demo pública ou parceria, leia o texto legal atual. Este artigo não interpreta contrato; só lembra que licença é parte da toolchain.

Analogias industriais: simulação como bancada de integração

Quem veio de eletrônica automotiva (Fatec: cluster, ECU monoponto, Task Manager) e de painel (CLP, inversor, IHM) já viu o padrão sob outros nomes:

  • HIL / SIL. Simular planta antes do hardware ↔ testar ladder com força de entrada na IDE ↔ BeamNGpy alimentando o software de percepção/decisão. O nível de fidelidade muda; a pergunta é a mesma: o que estou de fato exercitando?
  • Cenário repetível. Banco de testes de motor com dinamômetro ↔ célula robotizada com ciclo programado ↔ script BeamNGpy com seed e tráfego fixo. Repetibilidade é o que permite regressão.
  • Modo degradado. Falha de sensor no ADAS ↔ fio aberto no 4–20 mA ↔ perda de encoder no eixo. Injetar falha no sim é o primo seguro de puxar o cabo no quadro — desde que o software tenha modo seguro declarado, não só except genérico.
  • Contrato de mensagem. Schema SOURCE=SIM|REAL ↔ tipo de UDT no CLP ↔ struct de telemetria no PIC. Se o campo muda de nome entre sim e embarcado, a integração mente.
  • IHM de confiança. Operador só acredita no processo com feedback ↔ engenheiro só acredita no detector com log e overlay. GIF sem CSV é o LCD que mostra string fixa enquanto o MAP está em curto.

A simulação veicular não substitui o relé de segurança, o STO nem o HARA. Ela barateia o erro de software de percepção e decisão antes da pista controlada.

Ligação com a linha Wilson (TCC, Jetson, sensores)

Na prática da casa, percepção não começa no paper: começa em sensor + clock + barramento + software observável. O artigo de stack de sensores (câmera, LiDAR, radar, IMU/GNSS) é o mapa físico; BeamNGpy é o ginásio de integração onde o software de fusão/decisão pode falhar barato. O Jetson entra como alvo de deploy de visão e como lembrete de budget (TOPS, térmicos, latência de CSI/USB). A simulação não substitui o embarcado: alinha contratos.

Quem veio de eletrônica automotiva de curso (cluster/ECU/HMI) reconhece o padrão: primeiro contrato de sinal e estado, depois beleza de UI ou rede neural. O Task Manager da Fatec ensinou a não bloquear o ciclo; o BeamNGpy ensina a não bloquear o laço de decisão com I/O de frame sem fila. O STM32/Blue Pill ensinou probe antes de confiar no silkscreen; aqui o “probe” é telemetria hello antes de treinar rede.

Ponte explícita com o TCC de veículo de teste: capítulos que separam (a) o que o sim validou no plumbing, (b) o que a bancada Jetson validou com câmera real parada, (c) o que só pista controlada pode validar. Sem essa separação, a banca e o mercado leem “demo” como “pronto”.

Riscos e limitações a declarar no README do repo

  • Licenciamento e uso acadêmico/comercial do BeamNG.tech — siga os termos vigentes.
  • Custo de hardware de GPU no lab.
  • Drift de API entre versões BeamNGpy ↔ build do simulador (pine versões).
  • Sensores sintéticos não calibrados como o hardware do protótipo.
  • Tentação de overfit a um mapa único do simulador.
  • Ausência de EMC, load dump, rede veicular real (CAN) neste estudo de percepção visual/lidar sintética.
  • Nenhuma afirmação de conformidade com UNECE, ISO 26262 ou pronta para via pública.

Checklist semanal sugerido (estudo solo)

Uma cadência realista para quem divide tempo com bancada e TCC:

  • Semana 1–2: Onda A estável; documentar drivers GPU e erros de launch.
  • Semana 3: Onda B com log CSV e gráfico simples (matplotlib) da velocidade.
  • Semana 4–5: Onda C com um sensor por vez; não paralelizar tudo no primeiro dia.
  • Semana 6: Dois cenários da Onda D escritos como scripts reproduzíveis.
  • Semana 7+: Alinhar schema de mensagens com o código que já roda (ou rodará) no Jetson.

Se uma semana escorregar, encurte escopo — não invente resultado no README para “compensar”.

Variação honesta: se a GPU do lab falhar duas semanas, o trabalho útil vira schema de mensagens + stubs de sensor em Python puro (replay de CSV). Isso ainda é progresso de contrato — e cabe no Git sem fingir que o simulador rodou.

Critério de “repo não vazio”

O repositório deixa de ser só README quando existir, no mínimo:

  1. README.md com versões testadas e passos de reprodução;
  2. um exemplo de telemetria que rode na máquina de lab;
  3. pasta notes/ com diário de cenário (data, o que quebrou, o que mudou);
  4. .gitignore adequado (binários, caches, dumps grandes).

Sem métricas inventadas. Sem prints de dashboard fictício. Sem fotos geradas por IA.

Critério extra de maturidade (opcional, ainda sem métrica de paper): um cenário de falha de sensor documentado e um parágrafo no README dizendo o que o software faz quando a câmera some — mesmo que a resposta atual seja “para e loga”.

Limites honestos deste artigo

  • O repo, neste momento, é stub; ondas A–E são plano, não commits já feitos.
  • Não afirmo FPS, mAP, km simulados, tempo de integração nem “accuracy” de detector.
  • Não comparo BeamNG.tech com CARLA, LGSVL ou outros além da justificativa qualitativa de dinâmica/soft-body; escolha de ferramenta aqui é de estudo alinhado ao marcador do repo.
  • Não descrevo instalação passo a passo que envelhece com a próxima release — aponto documentação oficial.
  • Não endosso uso em via pública nem chamo o protótipo de veículo autônomo completo.
  • Nada de path /saas, nada de imagem gerada por IA para ilustrar cenário.

Fechamento

vehicle_simulation_with_BeamNGpy hoje é um stub — e está bem em admitir isso. O valor está no roteiro: BeamNG.tech + BeamNGpy como infraestrutura de estudo para ADAS/AV, com reality gap explícito e ponte clara para TCC/Jetson. O próximo commit útil não é prosa: é o 01_telemetry_hello.py rodando, versionado, sem prometer a rua antes da física e do software merecerem.